Nozzle 发布零依赖流式文本处理库

原标题:Nozzle: A streaming library that emits when possible and buffers where necessary
58AI 研判分

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

BASH
npm i nozzle-js # or pnpm / bun / yarn
TYPESCRIPT
import { 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.

<details><summary>Getting a text stream from your provider</summary>
TYPESCRIPT
// 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()))
</details>

Recipes

Extract a generated section

Stream just the code block to a preview while the model is still writing, then save it.

TS
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)