Nozzle: A streaming library that emits when possible and buffers where necessary
Hacker News

Nozzle: A streaming library that emits when possible and buffers where necessary

Quickstart

A text streaming library that emits when possible and buffers where necessary.

nz() accepts any sync or async iterable.

npm i nozzle-js # or pnpm / bun / yarn
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" } "."
 */

Getting a text stream from your provider

// 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

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"
 */

Providers often deliver text in bursts. Re-chunk into words and release them at a steady pace.

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()).
Group Functions
Regex parse · scan · match · replace
Splitting split · splitAfter · splitBefore · after · before · chunk
Timing minInterval · throttle
Elements map · asyncMap · filter · find
Transformation flatMap · flatten
Filtering compact · takeWhile · takeUntil
Indexing first · last · at · head · tail · initial · slice
Accumulation accumulate · diff · reduce
Buffering batch · buffer · withContext · aperture
Side effects tap · tee
Errors recover · wrap · unwrap
Conversion consume · toReadableStream · fromList · mapReturn

Regex Streaming

These functions use JavaScript regular expressions to search, match, and transform streaming text. Nozzle handles matching patterns across chunk boundaries by buffering text internally.

Non-matching text is yielded as soon as it's certain not to be part of a match, while potential matches are held back until confirmed.

These features throw an error because they cannot work reliably with streaming:

Feature Example Why
Lookaheads (?=...) , (?!...) Content to look ahead may not have arrived yet
Lookbehinds (?<=...) , (?<!...) Referenced group may span chunks or be partially buffered
Multiline mode /pattern/m ^ / $ would behave inconsistently at arbitrary chunk boundaries
Anchors ^ , $ The start and end of the stream are not known mid-stream; use before / after
Word boundaries \b , \B The neighboring character may be in a chunk that has not arrived
Unicode escapes \uXXXX , \u{...} Not analyzed for partial matches; use literal characters
Sticky and Unicode-sets flags /pattern/y , /pattern/v Not supported by the partial matcher
Empty matches /x?/ , /a{0,}/ A pattern that can match nothing would match between every character

Some patterns force nozzle to buffer text longer than you might expect:

  • Open-ended quantifiers at pattern end: /hello.+/g buffers everything after "hello" until the stream ends - .+ can always match more. Use a delimiter instead: /hello[^!]+/g matches until !, allowing earlier output.
  • Alternations with shared prefixes: /cat|caterpillar/g buffers "cat" until enough text arrives to rule out "caterpillar". Put longer alternatives first: /caterpillar|cat/g.
  • Optional suffixes: /items?/g buffers "item" to check for a trailing "s". This is usually fine, but /data.*?end/g buffers from "data" until "end" appears.
  • Global (/pattern/g): Finds all matches throughout the stream
  • Non-global (/pattern/): Finds only the first match, then passes remaining text through unchanged

Reference

nz(["a", "b", "b", "a"]).match(/a([ab]*)a/g) // => ["abba", "bb"] (match arrays with capture groups)

Extracts matches of a regex pattern from the input stream. Uses earliestPossibleMatchIndex to efficiently skip tokens as soon as we know they don't match the regex, while holding back potential matches until we can determine if they match.

Built on: scan(input, regex).filter(x => 'match' in x).map(x => x.match)

Details function match(input: AsyncIterable<string>, regex: RegExp): AsyncGenerator<RegExpExecArray>;

Parameter Type Description
input AsyncIterable<string> An asynchronous iterable of strings.
regex RegExp The regular expression pattern to match.
// Extract UUIDs from text
nz(["Now I'm taking uuid-asdf-flkj and adding it to uuid-fslkj-alkjlsf."])
  .parse(/uuid-(?<id>\w+)-\w+/g, m => ({ id: m.groups!.id }))
// yields: "Now I'm taking ", { id: "asdf" }, " and adding it to ", { id: "fslkj" }, "."

// Parse numbers from text
nz(["The answer is 42 and also 123"])
  .parse(/\d+/g, m => parseInt(m[0], 10))
// yields: "The answer is ", 42, " and also ", 123

Parses input for regex matches, yielding text as-is and transforming matches. This transform is useful for extracting structured data from text streams. Non-matching text is passed through as strings, while matches are transformed using the provided function.

Details function parse(input: AsyncIterable<string>, regex: RegExp, transform: (match: RegExpExecArray) => T): AsyncGenerator<string | T>;

Parameter Type Description
input AsyncIterable<string> An asynchronous iterable of strings.
regex RegExp The regular expression pattern to match.
transform (match: RegExpExecArray) => T A function that transforms each match into a desired type.

nz(["a", "b", "b", "a"]).replace(/a[ab]*a/g, "X") // => "X"

Replaces matches of a regex pattern with a replacement string in the input stream. Uses earliestPossibleMatchIndex to efficiently yield tokens as soon as we know they don't match the regex, while holding back potential matches until we can determine if they should be replaced.

Built on: scan(input, regex).map(x => 'text' in x ? x.text : x.match[0].replace(regex, replacement))

Details function replace(input: AsyncIterable<string>, regex: RegExp, replacement: string): AsyncGenerator<string>;

Parameter Type Description
input AsyncIterable<string> An asynchronous iterable of strings.
regex RegExp The regular expression pattern to match.
replacement string The string to replace matches with.
nz(["hello world"]).scan(/\w+/g)
// yields: { match: [...] }, { text: " " }, { match: [...] }

nz(["Now I'm taking uuid-asdf-flkj..."]).scan(/uuid-(\w+)-\w+/g)
// yields: { text: "Now I'm taking " }, { match: [...] }, { text: "..." }

Scans input for regex matches, yielding interleaved text and match results. This is the foundational regex transform that other transforms build on. It efficiently yields non-matching text as soon as we're certain it can't match, while holding back potential matches until we can determine their boundaries.

Note: Empty text strings are never yielded.

Details function scan(input: AsyncIterable<string>, regex: RegExp): AsyncGenerator<{ text: string } | { match: RegExpExecArray }>;

Parameter Type Description
input AsyncIterable<string> An asynchronous iterable of strings.
regex RegExp The regular expression pattern to match.

nz(["a", "b", "c", "d", "e"]).after(/bc/) // => "d", "e"

Emit everything after the accumulated prefix that matches pattern. Built on: scan(source, regex) skipping until first match, then yielding everything after

Details function after(source: StringIterable, pattern: string | RegExp): AsyncGenerator<string>;

| Parameter | Type | Description |
|---|---|---|
| source | StringIterable | stream or iterable to scan |
| pattern | string | RegExp | first RegExp that marks the cut-off |

nz(["a", "b", "c", "d", "e"]).before("cd") // => "a", "b"

Emit everything before the accumulated prefix that contains separator. Built on: scan(source, regex) taking text until first match Early termination may return undefined instead of the source's final value.

Details function before(source: StringIterable, separator: string | RegExp): AsyncGenerator<string>;

| Parameter | Type | Description |
|---|---|---|
| source | StringIterable | stream or iterable to scan |
| separator | string | RegExp | string that marks the cut-off |

nz(["a", "b", "c", "d", "e", "f"]).chunk(3) // => "abc", "def"

Groups input tokens into chunks of the specified size and yields the joined result. Takes N input items and yields N/size output items, where each output is the concatenation of size input items.

Details function chunk(source: AsyncIterable<string>, size: number): AsyncGenerator<string>;

Parameter Type Description
source AsyncIterable<string> The async iterable source of strings (tokens).
size number The number of input tokens to group together in each output chunk.

nz(["hello,world,test"]).split(",") // => "hello", "world", "test"

Takes incoming chunks, merges them, and then splits them by a string separator. Built on: scan(source, regex) accumulating text between matches

Details function split(source: AsyncIterable<string>, separator: string | RegExp): AsyncGenerator<string>;

| Parameter | Type | Description |
|---|---|---|
| source | AsyncIterable<string> | The async iterable source of strings. |
| separator | string | RegExp | The string separator to split by. |

nz(["hello,world,test"]).splitAfter(",") // => "hello,", "world,", "test"

Takes incoming chunks, merges them, and then splits them by a string separator, keeping the separator at the end of each part (except the last). Built on: scan(source, regex) with separator appended to each segment

Details function splitAfter(source: AsyncIterable<string>, separator: string | RegExp): AsyncGenerator<string>;

| Parameter | Type | Description |
|---|---|---|
| source | AsyncIterable<string> | The async iterable source of strings. |
| separator | string | RegExp | The string separator to split by. |

nz(["hello,world,test"]).splitBefore(",") // => "hello", ",world", ",test"

Takes incoming chunks, merges them, and then splits them by a string separator, keeping the separator at the beginning of each part (except the first). Built on: scan(source, regex) with separator prepended to each segment after first

Details function splitBefore(source: AsyncIterable<string>, separator: string | RegExp): AsyncGenerator<string>;

| Parameter | Type | Description |
|---|---|---|
| source | AsyncIterable<string> | The async iterable source of strings. |
| separator | string | RegExp | The string separator to split by. |

nz(["a", "b", "c"]).minInterval(100) // => "a" (0ms), "b" (100ms), "c" (200ms)

Enforces a minimum delay between adjacent tokens in a stream. The first token is yielded immediately, then subsequent tokens are delayed to ensure at least delayMs milliseconds pass between each yield.

Details function minInterval(source: AsyncIterable<T>, delayMs: number): AsyncGenerator<T>;

Parameter Type Description
source AsyncIterable<T> The async iterable source of tokens.
delayMs number The minimum delay in milliseconds between adjacent tokens.

nz(["a", "b", "c", "d"]).throttle(100, chunks => chunks.join("")) // => "abcd" (100ms)

Batches values into time windows, then yields the merged batch. The first value opens a window lasting intervalMs; it is not emitted immediately. Values arriving within that window are merged and emitted when its timer expires. After an idle period, the next value opens a new window. A final partial batch waits for its existing timer. An interval of zero passes values through unchanged. Source errors are surfaced immediately after already-emitted batches; an unfinished batch is discarded. The source is consumed eagerly, so slow consumers can build up an unbounded queue of merged batches.

Details function throttle(source: AsyncIterable<T>, intervalMs: number, merge: (values: T[]) => T): AsyncGenerator<T>;

Parameter Type Description
source AsyncIterable<T> The async iterable source of values.
intervalMs number The throttling interval in milliseconds.
merge (values: T[]) => T -
nz(["hello", "world"]).asyncMap(async x => x.toUpperCase())
// => "HELLO", "WORLD"

nz(["api/users", "api/posts"]).asyncMap(async url => fetch(url).then(r => r.json()))
// => [userData], [postsData]

nz(urls).asyncMap(fetchJson, { concurrency: 4 })

Transforms each value from the input stream using the provided async function. Starts the async function for each item as soon as it comes off the source iterator, up to the configured concurrency limit. Results are yielded in source order, not completion order, so a later item can finish first but will not be yielded or thrown until all earlier items have settled. Concurrency limits active calls, not queued results. Slow consumers can cause unbounded buffering. Cancellation does not abort already-started mapper calls.

Details function asyncMap(iterator: AsyncIterable<T>, fn: (value: T) => Promise<U>, options?: AsyncMapO

Read on Hacker News ↗ ← Back to News

Comments

No comments yet. Start the discussion.