Nozzle 发布零依赖流式文本处理库
Nozzle 是一个面向 LLM 流式输出的轻量 TypeScript 库,核心思路是仅在必要时缓冲、其余内容立即发射,例如正则匹配只缓冲潜在命中片段,周边文本即时输出。它零依赖、体积小,提供 consume、toReadableStream 等流式转换 API,适合构建低延迟的流式 UI 与解析管线。
报道正文
本文目录3 个章节
A text streaming library that emits when possible and buffers where necessary.
<img src="https://badgen.net/npm/v/nozzle-js" /> <img src="https://img.shields.io/bundlejs/size/nozzle-js?label=minzip" /> <img src="https://badgen.net/badge/dependencies/0/green" /> <img src="https://img.shields.io/badge/license-MIT-blue" /> <br /> <br /> Quickstart <span> • </span> Recipes <span> • </span> API <span> • </span> Guarantees <span> • </span> Reference
</div>Nozzle is a small TypeScript library for handling text streamed from LLMs. Its functions buffer only where necessary and otherwise emit chunks as soon as possible. For example, regexes buffer a potential match only until it's confirmed or rejected, and emit everything around it immediately.
Quickstart
npm i nozzle-js # or pnpm / bun / yarnimport { nz } from "nozzle-js"
const parts = nz(textStream).parse(/img-(\w+)/g, (m) => ({ src: m[1] }))
for await (const part of parts) console.log(part)
/*
* in: "Here is im" "g-abc" "123 and im" "g-xyz" "789."
* out: "Here is " { src: "abc123" } " and " { src: "xyz789" } "."
*/nz() accepts any sync or async iterable.
// Vercel AI SDK
const { textStream } = streamText({ model, prompt })
nz(textStream)
// OpenAI
const stream = await openai.chat.completions.create({ ...args, stream: true })
nz(stream).map((chunk) => chunk.choices[0]?.delta?.content ?? "")
// Anthropic
const stream = anthropic.messages.stream({ ...args })
nz(stream).map((e) => (e.type === "content_block_delta" && e.delta.type === "text_delta" ? e.delta.text : ""))
// fetch
const res = await fetch(url)
nz(res.body!.pipeThrough(new TextDecoderStream()))Recipes
Extract a generated section
Stream just the code block to a preview while the model is still writing, then save it.
const code = await nz(stream)
.after("```ts\n")
.before("```")
.tap(sendToPreview)
.consume()
await saveSnippet(code.string())
/*
* in: "Sure!\n``" "`ts\nconst x = " "await f()\n" "return x\n``" "`\nDone!"
* out: "const x = " "await f()\n" "return x\n"
*/
```
### Smooth chunky provider output
Providers often deliver text in bursts. Re-chunk into words and release them at a steady pace.
```typescript
const smooth = nz(stream)
.splitAfter(" ")
.compact()
.minInterval(40)
/*
* in: The quick ...... brown fox jumps over ................ the lazy dog.
* out: The .. quick .. brown .. fox .. jumps .. over .. the .. lazy .. dog.
*/
```
## Guarantees
- Pipelines are lazy: nothing runs until you `for await` or `.consume()`. Generator sources are single-use.
- Breaking out of a loop early closes upstream iterators. Cancelling in-flight I/O is up to the source/provider.
- Errors from the source, including errors raised in timers, surface where you `await`, so `try/catch` works.
- Generator return values pass through transforms (see `mapReturn`, `consume().return()`).
## API at a glance
| Group | Functions |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Regex** | [`parse`](#parse) · [`scan`](#scan) · [`match`](#match) · [`replace`](#replace) |
| **Splitting** | [`split`](#split) · [`splitAfter`](#splitafter) · [`splitBefore`](#splitbefore) · [`after`](#after) · [`before`](#before) · [`chunk`](#chunk) |
| **Timing** | [`minInterval`](#mininterval) · [`throttle`](#throttle) |
| **Elements** | [`map`](#map) · [`asyncMap`](#asyncmap) · [`filter`](#filter) · [`find`](#find) |
| **Transformation** | [`flatMap`](#flatmap) · [`flatten`](#flatten) |
| **Filtering** | [`compact`](#compact) · [`takeWhile`](#takewhile) · [`takeUntil`](#takeuntil) |
| **Indexing** | [`first`](#first) · [`last`](#last) · [`at`](#at) · [`head`](#head) · [`tail`](#tail) · [`initial`](#initial) · [`slice`](#slice) |
| **Accumulation** | [`accumulate`](#accumulate) · [`diff`](#diff) · [`reduce`](#reduce) |
| **Buffering** | [`batch`](#batch) · [`buffer`](#buffer) · [`withContext`](#withcontext) · [`aperture`](#aperture) |
| **Side effects** | [`tap`](#tap) · [`tee`](#tee) |
| **Errors** | [`recover`](#recover) · [`wrap`](#wrap) · [`unwrap`](#unwrap) |
| **Conversion** | [`consume`](#consume) · [`toReadableStream`](#toreadablestream) · [`fromList`](#fromlist) · [`mapReturn`](#mapreturn) |
> (注:更多技术实现细节与完整 API 文档请查阅原项目 README)