HN 日本語サマリー

← 一覧へ戻る
プログラミング

Nozzle: 可能であればストリームし、必要に応じてバッファリングするストリーミングライブラリ

Nozzle: A streaming library that emits when possible and buffers where necessary (github.com)

8 pointsby robertvc1 コメント

要約

Nozzleは、LLMからのテキストストリームを効率的に処理するためのTypeScriptライブラリです。このライブラリは、必要最低限のバッファリングで、可能な限り早くデータチャンクをストリームとして放出します。正規表現マッチングなどの特定の処理ではバッファリングを行いますが、それ以外では即座にデータを送信します。ストリーム処理のための多様なユーティリティを提供し、リアルタイムなテキスト処理を容易にします。

全文翻訳

フォルダとファイル

[画像: Nozzle]

可能であればストリームし、必要に応じてバッファリングするテキストストリーミングライブラリ。

[画像] [画像] [画像] [画像]

クイックスタート  •  レシピ  •  API  •  保証  •  リファレンス


Nozzleは、LLMからストリームされるテキストを処理するための小さなTypeScriptライブラリです。その関数は、必要な場合にのみバッファリングし、それ以外の場合は可能な限り早くチャンクを放出します。例えば、正規表現は、一致が確認または拒否されるまで、潜在的な一致をバッファリングするだけで、それ以外のすべてを即座に放出します。

クイックスタート

npm i nozzle-js # または 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)

/*
 * 入力:   "Here is im"  "g-abc"  "123 and im"                "g-xyz"  "789."
 * 出力:  "Here is "             { src: "abc123" }  " and "           { src: "xyz789" }  "."
 */

nz()は、同期または非同期のイテラブルを受け入れます。

プロバイダーからテキストストリームを取得する

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

レシピ

生成されたセクションを抽出する

モデルがまだ書き込んでいる間にコードブロックだけをプレビューにストリームし、その後保存します。

const code = await nz(stream)
  .after("```ts\n")
  .before("```")
  .tap(sendToPreview)
  .consume()

await saveSnippet(code.string())

/*
 * 入力:   "Sure!\n``"  "`ts\nconst x = "  "await f()\n"  "return x\n``"  "`\nDone!"
 * 出力:               "const x = "       "await f()\n"  "return x\n"
 */
プロバイダーの出力のチャンクをスムーズにする

プロバイダーはしばしばテキストをバーストで配信します。単語ごとに再チャンク化し、一定のペースでリリースします。

const smooth = nz(stream)
  .splitAfter(" ")
  .compact()
  .minInterval(40)

/*
 * 入力:   The quick ...... brown fox jumps over ................ the lazy dog.
 * 出力:  The .. quick .. brown .. fox .. jumps .. over .. the .. lazy .. dog.
 */

保証

  • パイプラインは遅延実行されます:for await または .consume() を実行するまで何も実行されません。ジェネレーターソースは一度だけ使用できます。
  • ループから早期に抜けると、アップストリームのイテレーターは閉じられます。インフライトI/Oのキャンセルはソース/プロバイダーに依存します。
  • ソースからのエラー(タイマーで発生したエラーを含む)は、await した場所で表面化するため、try/catch が機能します。
  • ジェネレーターの戻り値は、変換を通過します(mapReturn、consume().return() を参照)。

API概要

グループ関数
正規表現parse · scan · match · replace
分割split · splitAfter · splitBefore · after · before · chunk
タイミングminInterval · throttle
要素map · asyncMap · filter · find
変換flatMap · flatten
フィルタリングcompact · takeWhile · takeUntil
インデックスfirst · last · at · head · tail · initial · slice
蓄積accumulate · diff · reduce
バッファリングbatch · buffer · withContext · aperture
副作用tap · tee
エラーrecover · wrap · unwrap
変換consume · toReadableStream · fromList · mapReturn

リファレンス

正規表現

これらの関数は、ストリーミングテキストの検索、マッチング、変換にJavaScriptの正規表現を使用します。

Nozzleは、チャンク境界をまたぐマッチングを処理するために、内部でテキストをバッファリングします。一致しないテキストは、一致しないことが確実になり次第すぐに発行され、潜在的な一致は確認されるまで保留されます。

サポートされていない機能

ストリーミングでは信頼性が低いため、エラーが発生する機能:

機能例理由
先読み(?=...), (?!...)先読みするコンテンツがまだ到着していない可能性がある
後読み(?<=...), (?<!...)後読みするコンテンツが既に発行されている可能性がある
後方参照\1, \k<name>参照されるグループがチャンクをまたぐか、部分的にバッファリングされている可能性がある
マルチラインモード/pattern/m^/$ は、任意のチャンク境界で一貫性のない動作をする
アンカー^, $ストリームの開始と終了は、ストリームの途中で不明です。before/after を使用してください
単語境界\b, \B隣接する文字がまだ到着していないチャンクにある可能性がある
Unicodeエスケープ\uXXXX, \u{...}部分的な一致のために解析されません。リテラル文字を使用してください
StickyおよびUnicodeセットフラグ/pattern/y, /pattern/v部分マッチングエンジンでサポートされていません
空のマッチ/x?/, /a{0,}/何もマッチしないパターンは、各文字の間でマッチする
出力を遅延させるパターン

一部のパターンは、Nozzleに予期したよりも長くテキストをバッファリングさせる原因となります:

  • パターンの末尾にあるオープンエンドな量指定子: /hello.+/g は、ストリームが終了するまで「hello」以降のすべてをバッファリングします。.+ は常にさらにマッチできます。代わりに区切り文字を使用してください:/hello[^!]+/g は ! までマッチし、早期の出力を可能にします。

  • 共通のプレフィックスを持つ代替: /cat|caterpillar/g は、「caterpillar」を除外するのに十分なテキストが到着するまで「cat」をバッファリングします。より長い代替を先に配置してください:/caterpillar|cat/g。

  • オプションの接尾辞: /items?/g は、末尾の「s」を確認するために「item」をバッファリングします。これは通常問題ありませんが、/data.*?end/g は「end」が表示されるまで「data」からバッファリングします。

グローバル vs 非グローバル
  • グローバル (/pattern/g): ストリーム全体で全てのマッチを検索します。
  • 非グローバル (/pattern/): 最初の一致のみを検索し、残りのテキストは変更せずに通過させます。
match
nz(["a", "b", "b", "a"]).match(/a([ab]*)a/g) // => ["abba", "bb"] (キャプチャグループを持つマッチ配列)

入力ストリームから正規表現パターンのマッチを抽出します。

earliestPossibleMatchIndex を使用して、正規表現にマッチしないトークンを可能な限り早くスキップし、マッチするかどうかを判断できるまで潜在的なマッチを保留します。

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

詳細

function match<R = any>(input: AsyncIterable<string, R>, regex: RegExp): AsyncGenerator<RegExpExecArray, R, undefined>;
パラメータ
パラメータタイプ説明
inputAsyncIterable<string, R>文字列の非同期イテラブル。
regexRegExpマッチする正規表現パターン。

parse
// テキストからUUIDを抽出する
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" }, "."

// テキストから数値を解析する
nz(["The answer is 42 and also 123"])
  .parse(/\d+/g, m => parseInt(m[0], 10))
// yields: "The answer is ", 42, " and also ", 123

正規表現マッチングのために入力を解析し、テキストをそのまま、マッチを変換して発行します。

この変換は、テキストストリームから構造化データを抽出するのに役立ちます。一致しないテキストは文字列として渡され、マッチは提供された関数を使用して変換されます。

詳細

function parse<T, R = any>(input: AsyncIterable<string, R>, regex: RegExp, transform: (match: RegExpExecArray) => T): AsyncGenerator<string | T, R, undefined>;
パラメータ
パラメータタイプ説明
inputAsyncIterable<string, R>文字列の非同期イテラブル。
regexRegExpマッチする正規表現パターン。
transform(match: RegExpExecArray) => T各マッチを指定されたタイプに変換する関数。

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

入力ストリーム内の正規表現パターンのマッチを指定された置換文字列に置き換えます。

earliestPossibleMatchIndex を使用して、正規表現にマッチしないトークンを可能な限り早く発行し、置換されるかどうかを判断できるまで潜在的なマッチを保留します。

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

詳細

function replace<R = any>(input: AsyncIterable<string, R>, regex: RegExp, replacement: string): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
inputAsyncIterable<string, R>文字列の非同期イテラブル。
regexRegExpマッチする正規表現パターン。
replacementstringマッチを置き換える文字列。

scan
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: "..." }

正規表現マッチングのためにスキャン入力を行い、インターリーブされたテキストとマッチ結果を発行します。

これは、他の変換が構築される基盤となる正規表現変換です。一致しないテキストを、マッチしないことが確実になり次第効率的に発行し、境界を判断できるまで潜在的なマッチを保留します。

注:空のテキスト文字列は発行されません。

詳細

function scan<R = any>(input: AsyncIterable<string, R>, regex: RegExp): AsyncGenerator<ScanResult, R, undefined>;
パラメータ
パラメータタイプ説明
inputAsyncIterable<string, R>文字列の非同期イテラブル。
regexRegExpマッチする正規表現パターン。

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

累積されたプレフィックスが pattern にマッチした後、それ以降のすべてを発行します。

基盤: scan(source, regex) で最初の一致までスキップし、その後すべてを発行します。

詳細

function after<R = any>(source: StringIterable<R>, pattern: string | RegExp): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
sourceStringIterable<R>スキャンするストリームまたはイテラブル
patternstring | RegExpカットオフをマークする最初の RegExp

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

累積されたプレフィックスが separator を含む前に、それ以前のすべてを発行します。

基盤: scan(source, regex) で最初の一致までテキストを蓄積します。

早期終了は、ソースの最終値の代わりに undefined を返す場合があります。

詳細

function before<R = any>(source: StringIterable<R>, separator: string | RegExp): AsyncGenerator<string, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
sourceStringIterable<R>スキャンするストリームまたはイテラブル
separatorstring | RegExpカットオフをマークする文字列

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

入力トークンを指定されたサイズのチャンクにグループ化し、結合された結果を発行します。N個の入力項目を取り、N/size個の出力項目を発行します。各出力はsize個の入力項目の連結です。

詳細

function chunk<R = any>(source: AsyncIterable<string, R>, size: number): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<string, R>文字列(トークン)の非同期イテラブルソース。
sizenumber各出力チャンクにグループ化する入力トークンの数。

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

受信したチャンクを取り込み、それらをマージしてから、文字列区切り文字で分割します。

基盤: scan(source, regex) でマッチ間のテキストを蓄積します。

詳細

function split<R = any>(source: AsyncIterable<string, R>, separator: string | RegExp): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<string, R>文字列の非同期イテラブルソース。
separatorstring | RegExp分割する文字列区切り文字。

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

受信したチャンクを取り込み、それらをマージしてから、文字列区切り文字で分割します。区切り文字は最後の部分を除き、各部分の末尾に保持されます。

基盤: scan(source, regex) で区切り文字を各セグメントの末尾に追加します。

詳細

function splitAfter<R = any>(source: AsyncIterable<string, R>, separator: string | RegExp): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<string, R>文字列の非同期イテラブルソース。
separatorstring | RegExp分割する文字列区切り文字。

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

受信したチャンクを取り込み、それらをマージしてから、文字列区切り文字で分割します。区切り文字は最初の部分を除き、各部分の先頭に保持されます。

基盤: scan(source, regex) で最初の部分以降の各セグメントの先頭に区切り文字を追加します。

詳細

function splitBefore<R = any>(source: AsyncIterable<string, R>, separator: string | RegExp): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<string, R>文字列の非同期イテラブルソース。
separatorstring | RegExp分割する文字列区切り文字。

タイミング
minInterval
nz(["a", "b", "c"]).minInterval(100) // => "a" (0ms), "b" (100ms), "c" (200ms)

ストリーム内の隣接するトークン間の最小遅延を強制します。最初のトークンは即座に発行され、それ以降のトークンは、各発行間に少なくとも delayMs ミリ秒が経過するように遅延されます。

詳細

function minInterval<T, R = any>(source: AsyncIterable<T, R>, delayMs: number): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>トークンの非同期イテラブルソース。
delayMsnumber隣接するトークン間の最小遅延(ミリ秒)。

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

時間ウィンドウに値をバッチ処理し、マージされたバッチを発行します。最初の値は intervalMs のウィンドウを開きます。このウィンドウは即座には発行されません。そのウィンドウ内に到着した値はマージされ、タイマーが期限切れになったときに発行されます。アイドル期間の後、次の値が新しいウィンドウを開きます。最後の部分的なバッチは、既存のタイマーを待ちます。ゼロの間隔は値をそのまま通過させます。ソースのエラーは、既に発行されたバッチの直後に表面化します。未完了のバッチは破棄されます。ソースは積極的に消費されるため、遅いコンシューマーは無制限のバッチキューを構築する可能性があります。

詳細

function throttle<T, R = any>(source: AsyncIterable<T, R>, intervalMs: number, merge: (values: T[]) => T): AsyncGenerator<T, R>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブルソース。
intervalMsnumberスロットリング間隔(ミリ秒)。
merge(values: T[]) => T-

要素
asyncMap
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 })

提供された非同期関数を使用して、入力ストリームの各値を変換します。設定された同時実行制限まで、ソースイテレーターからアイテムが取得され次第、各アイテムの非同期関数を開始します。結果は完了順ではなくソース順で発行されるため、後続のアイテムが先に完了しても、前のすべてのアイテムが処理されるまで発行またはスローされません。同時実行はキューに入れられた結果ではなく、アクティブな呼び出しを制限します。遅いコンシューマーは無制限のバッファリングを引き起こす可能性があります。キャンセルは、既に開始されたマッパー呼び出しを中止しません。

詳細

function asyncMap<T, U, R = any>(iterator: AsyncIterable<T, R>, fn: (value: T) => Promise<U>, options?: AsyncMapOptions): AsyncGenerator<U, R>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>文字列の非同期イテラブル。
fn(value: T) => Promise<U>各文字列値を変換する非同期関数。
optionsAsyncMapOptionsオプション設定。

filter
nz(["Hello", "Hi", "World"]).filter(chunk => chunk.length > 4) // => "Hello", "World"

述語関数に基づいて入力ストリームをフィルタリングします。

詳細

function filter<T, R = any>(iterator: AsyncIterable<T, R>, predicate: (chunk: T) => boolean): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>文字列の非同期イテラブル。
predicate(chunk: T) => booleanアイテムを保持するためにtrueを返す関数。

find
await nz(["apple", "banana", "cherry"]).find(chunk => chunk.startsWith("b")) // => "banana"

述語に一致する入力ストリームの最初の値を見つけます。

詳細

function find<T>(iterator: AsyncIterable<T>, predicate: (chunk: T) => boolean): Promise<T | undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T>値の非同期イテラブル。
predicate(chunk: T) => boolean見つけるアイテムに対してtrueを返す関数。

map
nz(["hello", "world"]).map(x => x.toUpperCase()) // => "HELLO", "WORLD"

提供された関数を使用して、入力ストリームの各値を変換します。

詳細

function map<T, U, R = any>(iterator: AsyncIterable<T, R>, fn: (value: T) => U): AsyncGenerator<U, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>文字列の非同期イテラブル。
fn(value: T) => U各文字列値を変換する関数。

変換
flatMap
nz(["hi", "ok"]).flatMap(word => word.split("")) // => "h", "i", "o", "k"
nz([1, 2, 3]).flatMap(n => Array(n).fill(n)) // => 1, 2, 2, 3, 3, 3

入力ストリームの各値をゼロ個以上の出力値に変換します。

詳細

function flatMap<T, U, R = any>(source: AsyncIterable<T, R>, fn: (value: T) => Iterable<U, any, any> | AsyncIterable<U, any, any>): AsyncGenerator<U, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブル。
fn(value: T) => Iterable<U, any, any> | AsyncIterable<U, any, any>各入力に対して同期または非同期イテラブル値を返す関数。

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

ネストされた配列またはイテラブルを単一のストリームにフラット化します。

詳細

function flatten<T, R = any>(src: Iterable<Iterable<T> | T[], R>): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
srcIterable<Iterable<T> | T[], R>ネストされた配列またはイテラブルを含むソースイテラブル。

フィルタリング
compact
nz(["Hello", "", "World", ""]).compact() // => "Hello", "World"

入力ストリームから空の文字列をフィルタリングします。

詳細

function compact<R = any>(iterator: AsyncIterable<string, R>): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<string, R>文字列の非同期イテラブル。

takeUntil
nz([1, 2, 3, 4]).takeUntil(n => n === 3) // => 1, 2

述語が一致するまで値を発行します。一致する値は除外されます。

早期終了は、ソースの最終値の代わりに undefined を返す場合があります。

詳細

function takeUntil<T, R = any>(source: AsyncIterable<T, R>, predicate: (value: T) => boolean): AsyncGenerator<T, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブル。
predicate(value: T) => booleanストリームを停止すべき値に対してtrueを返す関数。

takeWhile
nz([1, 2, 3, 1]).takeWhile(n => n < 3) // => 1, 2

述語が一致する間、値を発行します。最初の一致しない値は除外されます。

早期終了は、ソースの最終値の代わりに undefined を返す場合があります。

詳細

function takeWhile<T, R = any>(source: AsyncIterable<T, R>, predicate: (value: T) => boolean): AsyncGenerator<T, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブル。
predicate(value: T) => boolean保持する値に対してtrueを返す関数。

インデックス
at
await nz(["a", "b", "c", "d", "e"]).at(2) // => "c"
await nz(["a", "b", "c", "d", "e"]).at(-1) // => "e"

入力ストリームの指定されたインデックスの要素を返します。末尾からのカウントをサポートする負のインデックスもサポートします。

詳細

function at<T>(iterator: AsyncIterable<T>, index: number): Promise<T | undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T>値の非同期イテラブル。
indexnumberアクセスするインデックス。負の値は末尾からカウントします。

first
await nz(["Hello", "World", "!"]).first() // => "Hello"

入力ストリームの最初の値を返します。

詳細

function first<T>(iterator: AsyncIterable<T>): Promise<T | undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T>値の非同期イテラブル。

head
nz(["Hello", "World", "!"]).head() // => "Hello"

入力ストリームの最初の値のみを発行します。

早期終了は、ソースの最終値の代わりに undefined を返す場合があります。

詳細

function head<T, R = any>(iterator: AsyncIterable<T, R>): AsyncGenerator<T, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>値の非同期イテラブル。

参照: at, tail, initial, last


initial
nz(["Hello", "World", "!"]).initial() // => "Hello", "World"

入力ストリームの最後の値を除くすべての値を発行します。

詳細

function initial<T, R = any>(iterator: AsyncIterable<T, R>): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>値の非同期イテラブル。

last
await nz(["Hello", "World", "!"]).last() // => "!"

入力ストリームの最後の値を返します。

詳細

function last<T>(iterator: AsyncIterable<T>): Promise<T | undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T>値の非同期イテラブル。

slice
nz(["a", "b", "c", "d", "e"]).slice(1, 3) // => "b", "c"
nz(["a", "b", "c", "d", "e"]).slice(-2) // => "d", "e"

開始および終了インデックス間の入力ストリームのスライスを発行します。内部バッファを維持することで負のインデックスをサポートします。制限付きスライスは早期に停止し、undefined を返す場合があります。終了がない場合、完了時にソースの戻り値を保持します。

詳細

function slice<T, R = any>(iterator: AsyncIterable<T, R>, start: number, end?: undefined): AsyncGenerator<T, R, undefined>;
function slice<T, R = any>(iterator: AsyncIterable<T, R>, start: number, end: number | undefined): AsyncGenerator<T, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>スライスする非同期イテラブル
startnumber開始インデックス(含む)。負の値は末尾からカウントします。
endnumber | undefined終了インデックス(含まない)。負の値は末尾からカウントします。undefined の場合、最後までスライスします。

tail
nz(["Hello", "World", "!"]).tail() // => "World", "!"

入力ストリームの最初の値を除くすべての値を発行します。

詳細

function tail<T, R = any>(iterator: AsyncIterable<T, R>): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>値の非同期イテラブル。

蓄積
accumulate
nz(["This ", "is ", "a ", "test!"]).accumulate() // => "This ", "This is ", "This is a ", "This is a test!"

入力ストリームの累積的なプレフィックスを発行します。

詳細

function accumulate<R = any>(iterator: AsyncIterable<string, R>): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<string, R>文字列の非同期イテラブル。

diff
nz(["This ", "This is ", "This is a ", "This is a test!"]).diff().value() // => "This ", "is ", "a ", "test!"

入力ストリームの現在の文字列と前の文字列との差分を発行します。

詳細

function diff<R = any>(iterator: AsyncIterable<string, R>): AsyncGenerator<string, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<string, R>文字列の非同期イテラブル。

reduce
nz([1, 2, 3, 4]).reduce((acc, n) => acc + n, 0) // => 1, 3, 6, 10

リデューサー関数を使用して、段階的な累積値を生成します。

詳細

function reduce<T, A, R = any>(source: AsyncIterable<T, R>, reducer: (accumulator: A, current: T, index: number) => A, initial: A): AsyncGenerator<A, R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブル。
reducer(accumulator: A, current: T, index: number) => Aアキュムレーターと各値を組み合わせる関数。
initialA初期アキュムレーター値。

バッファリング
aperture
nz([1, 2, 3, 4, 5]).aperture(3) // => [1, 2, 3], [2, 3, 4], [3, 4, 5]

入力ストリーム上にサイズnのスライディングウィンドウを作成し、連続する要素の配列を発行します。

詳細

function aperture<T, R = any>(source: Iterable<T, R>, n: number): AsyncGenerator<T[], R | undefined>;
パラメータ
パラメータタイプ説明
sourceIterable<T, R>ウィンドウを作成するイテラブル。
nnumber各ウィンドウのサイズ。

batch
nz([1, 2, 3, 4, 5]).batch(2) // => [1, 2], [3, 4], [5]
nz(["a", "b", "c"]).batch(2).map(xs => xs.join("")) // => "ab", "c"

入力値を指定されたサイズの配列にグループ化します。

詳細

function batch<T, R = any>(source: AsyncIterable<T, R>, size: number): AsyncGenerator<T[], R, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブルソース。
sizenumber各バッチに含まれる入力値の数。

buffer
nz(["a", "b", "c"]).buffer(2) // => "a", "b", "c"
// 遅いコンシューマーが "a" を処理している間、ソースは先読みされます:
// 消費済み: a, 発行済み: a, 消費済み: b, 消費済み: c, 発行済み: b, 発行済み: c

ソースイテレーターから最大N個のアイテムをバッファリングし、それらを積極的に消費して要求に応じて発行します。nが未定義の場合、無制限のアイテムをバッファリングします。

buffer()関数は、入力イテレーターを可能な限り速く、可能な限り多く「吸い上げ」、アイテムを内部バッファに格納します。バッファからアイテムが要求されると、それらは事前に満たされたバッファから発行されます。これにより、消費レートと生産レートが分離されます。

詳細

function buffer<T, R = any>(source: AsyncIterable<T, R>, n?: number): AsyncGenerator<T, R>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブルソース。
nnumberバッファリングする最大アイテム数。undefined の場合、無制限にバッファリングします。

withContext
nz([1, 2, 3]).withContext({ before: 1, after: 1 })
// { past: [], current: 1, upcoming: [2], index: 0 }
// { past: [1], current: 2, upcoming: [3], index: 1 }
// { past: [2], current: 3, upcoming: [], index: 2 }

ソース順で、境界付きの隣接コンテキストを持つ各アイテムを発行します。before と after はデフォルトでゼロであり、非負の安全な整数である必要があります。ルックアヘッドは、after アイテムが到着するかソースが終了するまで発行を遅延させます。コンテキストはストリーム境界で短くなります。各出力は独立した配列を持ちます。アイテム自体は共有されます。ソースの戻り値は保持されます。

詳細

function withContext<T, R = any>(source: Iterable<T, R>, options: WithContextOptions): AsyncGenerator<ItemContext<T>, R>;
パラメータ
パラメータタイプ説明
sourceIterable<T, R>-
optionsWithContextOptions-

副作用
tap
nz(["Hello", "World", "!"]).tap(x => console.log(`yielded: ${x}`)) // => "Hello", "World", "!" (ログ: yielded: Hello, yielded: World, yielded: !)

ストリームを変更せずに、各値に対して副作用を実行します。

詳細

function tap<T, R = any>(iterator: AsyncIterable<T, R>, fn: (value: T) => void): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>文字列の非同期イテラブル。
fn(value: T) => void各値に対して実行する関数。

tee
const [stream1, stream2] = nz(["a", "b", "c"]).tee(2) // => "a", "b", "c" の2つの独立したストリーム

単一のイテレーターをN個の独立したイテラブルに分割します。最初のブランチが読み取られると、積極的に読み取りを開始します。ブランチキューは無制限です。すべてのブランチを消費するか、iterator.return() で未使用のブランチを閉じます。

詳細

function tee<T, R = any>(iterator: AsyncIterator<T, R>, n: number): AsyncGenerator<T, R, any>[];
パラメータ
パラメータタイプ説明
iteratorAsyncIterator<T, R>分割するソース非同期イテレーター。
nnumber作成する独立したイテラブルの数。

エラー処理
recover
nz(stream).recover(() => ["[stream failed]"])
nz(stream).recover(() => []) // エラーを飲み込み、ストリームを終了する

アップストリームのエラーをキャッチし、オプションで置換値を生成します。

詳細

function recover<T, R = any>(source: AsyncIterable<T, R>, handler: (error: unknown) => RecoverResult<T>): AsyncGenerator<T, R | undefined, undefined>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T, R>値の非同期イテラブル。
handler(error: unknown) => RecoverResult<T>置換値を返す関数、またはストリームを終了するために何も返さない関数。

unwrap
nz(["hello", "world"]).wrap().unwrap() // => "hello", "world"

wrap() からの結果を通常のイテレーターに戻します。エラーをスローする代わりに、結果オブジェクト形式でエラーを生成します。エラーは {type: "error", error} として、成功した値は {type: "value", value} として発行されます。wrap() の反対です。

詳細

function unwrap<T, R = any>(iterator: AsyncIterable<WrappedResult<T, R>>): AsyncGenerator<T, R, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<WrappedResult<T, R>>ラップされた結果オブジェクトの非同期イテラブル。

wrap
nz(["hello", "world"]).wrap()
// => {type: "value", value: "hello"}, {type: "value", value: "world"}, {type: "return", value: undefined}

イテレーターをラップして、任意のエラーをキャッチし、結果オブジェクト形式で返します。エラーをスローする代わりに、エラーは {type: "error", error} として、成功した値は {type: "value", value} として発行されます。

詳細

function wrap<T, R = any>(iterator: AsyncIterable<T, R>): AsyncGenerator<WrappedResult<T, R>>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>非同期イテラブル。

変換
consume
const consumed = await nz(["a", "b"]).consume()
consumed.list()   // => ["a", "b"]
consumed.return() // => undefined (またはイテレーターの戻り値)

非同期イテレーターを完全に消費し、生成された値と戻り値の両方を収集します。

生成された値と戻り値の両方にアクセスできる ConsumedPipeline を返します:

  • .list() - 生成されたすべての値を配列 (T[]) として返します。
  • .return() - イテレーターの戻り値 (R | undefined) を返します。
  • .string() - 文字列値を連結します。

詳細

function consume<T, R>(iterator: AsyncIterable<T, R>): Promise<ConsumedPipeline<T, R>>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>消費する非同期イテラブル

fromList
nz(["Hello", "World", "!"]) // => "Hello", "World", "!"

配列を非同期イテレーターに変換します。

詳細

function fromList<T>(list: T[]): AsyncGenerator<T>;
パラメータ
パラメータタイプ説明
listT[]値の配列。

toReadableStream
return new Response(nz(llmTextStream).minInterval(40).toReadableStream().pipeThrough(new TextEncoderStream()))

非同期イテラブルをWebの ReadableStream に変換します。

ストリームは、リーダーが値の要求をしたときにのみソースからプルするため、先読みは行われず、タイミング変換はそのペースを維持します。ストリームをキャンセルするとソースイテレーターが閉じられます。Webストリームには戻り値がないため、ソースの戻り値は破棄されます。

0.12.0 で追加され、nz() の ReadableStream ソースと共に追加されました。

詳細

function toReadableStream<T>(source: AsyncIterable<T>): ReadableStream<T>;
パラメータ
パラメータタイプ説明
sourceAsyncIterable<T>読み取る非同期イテラブル。

戻り値
mapReturn
nz(["a", "b"]).mapReturn(returnValue => returnValue?.toString() ?? "default") // => "a", "b" (マッピングされた戻り値付き)

生成されたすべての値を変更せずに保持しながら、イテレーターの戻り値のタイプをマッピングします。

詳細

function mapReturn<T, R, U>(iterator: AsyncIterable<T, R>, fn: (value: R) => U): AsyncGenerator<T, U, undefined>;
パラメータ
パラメータタイプ説明
iteratorAsyncIterable<T, R>非同期イテラブル。
fn(value: R) => U戻り値を変換する関数。

開発

pnpm install --frozen-lockfile
pnpm run check

APIコメントまたはREADMEテンプレートを編集した後は pnpm run docs を実行してください。公開せずにパッケージの内容を検証するには pnpm run release:dry を実行してください。

ライセンス

MIT