@saunos/ndjson-index 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saunos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @saunos/ndjson-index
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stream, batch and index huge NDJSON files in the browser without holding them on the JS heap.
+
+Built for files of hundreds of MB, such as a diff of 500k records, that a page must page through and search without a database and without freezing:
+
+- **Backpressure.** The download is read only when you ask for the next batch.
+- **Off-heap storage.** Lines live in `Blob`s; the heap holds three integers per line.
+- **Compact search.** Text is kept as one-byte-per-char "byte strings" and searched with the native `indexOf`.
+- **Never blocks input.** Long work yields to the event loop between ~1 MB slices.
+
+No runtime dependencies. Needs ES2024 (resizable `ArrayBuffer`); uses `scheduler.yield()` where available.
+
+```sh
+npm install @saunos/ndjson-index
+```
+
+## Example
+
+A file whose first line is a header declaring how many bytes of records follow:
+
+```ts
+import {
+  ByteStringSearchIndex,
+  LineStore,
+  boundedBatches,
+  readFirstLine,
+} from '@saunos/ndjson-index';
+
+const reader = (await fetch(url)).body!.getReader();
+const { line, rest } = await readFirstLine(reader, { maxBytes: 1 << 20 });
+const header = JSON.parse(line);
+
+const lines = new LineStore();
+const search = new ByteStringSearchIndex();
+
+for await (const batch of boundedBatches(reader, {
+  byteLength: header.bytes,
+  batchBytes: 8 << 20,
+  leading: rest,
+})) {
+  await lines.append(batch, {
+    line: (text) => search.append(valuesOf(JSON.parse(text))),
+    sliceEnd: () => search.seal(),
+  });
+}
+
+const hits = await search.search('иванов'); // ascending line numbers
+const first = JSON.parse(await lines.read(hits[0]));
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `readFirstLine(reader, { maxBytes })` | Reads and decodes line 1 only; returns it and the bytes read past it. |
+| `boundedBatches(reader, { byteLength, batchBytes, leading })` | Yields the next `byteLength` bytes as newline-aligned batches, then cancels the reader. |
+| `LineBatcher` / `BoundedLineBatcher` | The synchronous chunk-to-batch cutters behind it. |
+| `LineStore` | Blob-backed line storage: `append(batch, visitor)`, `read(n)`, `length`, `dispose()`. |
+| `ByteStringSearchIndex` | Case-insensitive substring index: `append(values)`, `seal()`, `search(needle)`. |
+| `GrowableInt32Array` | Push-only `Int32Array` on a resizable `ArrayBuffer`. |
+| `toByteString(bytes)` | Bytes → one-byte-per-char string. |
+| `yieldToMain()` | Yields to the event loop (`scheduler.yield`, else `MessageChannel`). |
+| `NdjsonError` | Thrown with a `code` when the stream's shape is wrong. |
+
+## Development
+
+```sh
+bun install
+bun run tsc && bun run lint && bun run fmt && bun test && bun run build
+```
+
+## License
+
+MIT

package/dist/BoundedLineBatcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cuts exactly the first `byteLength` bytes of a stream into line-aligned
+ * batches, for a file whose header declares how long its next part is.
+ *
+ * Feeds those bytes into a {@link LineBatcher} and reports when the part is
+ * complete, so the reader can stop downloading instead of fetching what
+ * follows. A chunk that straddles the boundary is cut there, and the batcher
+ * is flushed, so the last batch ends exactly at the part's last newline and
+ * never carries a line of the next part.
+ */
+export declare class BoundedLineBatcher {
+    private readonly byteLength;
+    private readonly batcher;
+    private seen;
+    /**
+     * @param byteLength the part's length; it must end on a newline
+     * @param batchBytes batch size goal, see {@link LineBatcher}
+     */
+    constructor(byteLength: number, batchBytes: number);
+    /** Whether every byte of the part has been consumed and flushed. */
+    get complete(): boolean;
+    /**
+     * Consumes the next chunk.
+     *
+     * @returns the batches it completed, in order: none, one, or two when the
+     *   chunk crosses the part's end (a cut, then the final flush)
+     * @throws {NdjsonError} `not-on-line-boundary` if the byte before the part's
+     *   end is not a newline: then the declared length does not match the
+     *   file, and every line after it would be misattributed
+     */
+    push(chunk: Uint8Array): Uint8Array<ArrayBuffer>[];
+    /**
+     * Called when the stream ends.
+     *
+     * @throws {NdjsonError} `truncated` if it ended inside the part
+     */
+    end(): void;
+}
+//# sourceMappingURL=BoundedLineBatcher.d.ts.map

package/dist/BoundedLineBatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundedLineBatcher.d.ts","sourceRoot":"","sources":["../src/BoundedLineBatcher.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAS3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAR7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,IAAI,CAAK;IAEjB;;;OAGG;gBAEgB,UAAU,EAAE,MAAM,EACnC,UAAU,EAAE,MAAM;IAKpB,oEAAoE;IACpE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,EAAE;IAoBlD;;;;OAIG;IACH,GAAG,IAAI,IAAI;CASZ"}

package/dist/ByteStringSearchIndex.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A case-insensitive substring index over many small documents (such as the
+ * values of each NDJSON line), held compactly on the JS heap.
+ *
+ * Documents are kept as "byte strings": their UTF-8 bytes, one char per byte.
+ * A plain JS string costs two bytes per char as soon as one char is outside
+ * Latin-1 (a name in Cyrillic, a curly quote), and most real text has one; a
+ * byte string stays at one byte per char and can still be searched with the
+ * native `String.indexOf`. A needle's UTF-8 bytes occur exactly where the
+ * needle does, so the answers are the same.
+ *
+ * Documents are grouped into segments, each one flat string. Call
+ * {@link seal} every MB or so of input (for example from
+ * `LineVisitor.sliceEnd`), so no single string gets huge and a search can
+ * yield between segments.
+ */
+export declare class ByteStringSearchIndex {
+    private segments;
+    private docs;
+    /** Id of the first document not yet in a segment. */
+    private pendingFirst;
+    /**
+     * Reused space the pending documents are encoded into before a trimmed copy
+     * becomes their segment, so appending does not allocate per document.
+     */
+    private scratch;
+    private written;
+    /** Where each pending document starts in {@link scratch}. */
+    private pendingStarts;
+    private readonly encoder;
+    private disposed;
+    /** How many documents were appended. */
+    get size(): number;
+    /**
+     * Adds one document; ids count up from zero.
+     *
+     * @param values matched separately: a needle never matches across two of
+     *   them. Lowercased here, as {@link search} lowercases the needle.
+     * @returns the document's id
+     */
+    append(values: readonly string[]): number;
+    /**
+     * Closes the pending documents into a segment. Cheap when nothing is
+     * pending, and called by {@link search} itself, so it only decides where
+     * segments end.
+     */
+    seal(): void;
+    /**
+     * The ids of documents any of whose values contain `needle`, ignoring case,
+     * ascending. An empty needle matches every document.
+     *
+     * Each segment is scanned for the needle's bytes. A hit is mapped to its
+     * document by binary search over the segment's starts, and the scan resumes
+     * at the next document, so a document is reported once however many of its
+     * values match. Yields to the event loop every {@link SCAN_BUDGET_MS}.
+     */
+    search(needle: string): Promise<Int32Array>;
+    /**
+     * Drops every segment, so their text can be collected. Safe to call more
+     * than once; a later {@link append} or {@link search} throws.
+     */
+    dispose(): void;
+    /**
+     * Writes `text` as UTF-8 into {@link scratch}, then a separator byte,
+     * growing the scratch space first if `text` might not fit.
+     */
+    private encode;
+    /** @throws {Error} once disposed */
+    private assertOpen;
+}
+//# sourceMappingURL=ByteStringSearchIndex.d.ts.map

package/dist/ByteStringSearchIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByteStringSearchIndex.d.ts","sourceRoot":"","sources":["../src/ByteStringSearchIndex.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,IAAI,CAAK;IACjB,qDAAqD;IACrD,OAAO,CAAC,YAAY,CAAK;IACzB;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,OAAO,CAAK;IACpB,6DAA6D;IAC7D,OAAO,CAAC,aAAa,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAS;IAEzB,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM;IAazC;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAaZ;;;;;;;;OAQG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuBjD;;;OAGG;IACH,OAAO,IAAI,IAAI;IAUf;;;OAGG;IACH,OAAO,CAAC,MAAM;IAad,oCAAoC;IACpC,OAAO,CAAC,UAAU;CAGnB"}

package/dist/GrowableInt32Array.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An `Int32Array` that grows as values are pushed, doubling its capacity
+ * (amortised O(1) push, like a vector). Per-line indexes over hundreds of
+ * thousands of lines stay a few contiguous typed arrays instead of plain
+ * arrays of boxed numbers, which keeps the JS heap small and reads fast.
+ *
+ * Backed by a resizable `ArrayBuffer` (ES2024), which grows in place: no copy
+ * into a bigger array on each doubling, and the view tracks the buffer's
+ * length.
+ */
+export declare class GrowableInt32Array {
+    private readonly buffer;
+    /** Length-tracking: always spans the whole buffer, spare capacity included. */
+    private readonly values;
+    private size;
+    /** @param maxLength how many values it can ever hold */
+    constructor(maxLength?: number);
+    get length(): number;
+    /** @throws {RangeError} if the array already holds its maximum length */
+    push(value: number): void;
+    /**
+     * The value at `index`.
+     *
+     * @throws {RangeError} if `index` is outside `[0, length)`
+     */
+    at(index: number): number;
+    /**
+     * A view of the pushed values. The buffer only ever grows, so the view
+     * stays valid, but it does not show values pushed after it was taken.
+     */
+    toArray(): Int32Array;
+}
+//# sourceMappingURL=GrowableInt32Array.d.ts.map

package/dist/GrowableInt32Array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrowableInt32Array.d.ts","sourceRoot":"","sources":["../src/GrowableInt32Array.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,IAAI,CAAK;IAEjB,wDAAwD;gBAC5C,SAAS,SAAqB;IAO1C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAUzB;;;;OAIG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOzB;;;OAGG;IACH,OAAO,IAAI,UAAU;CAGtB"}

package/dist/LineBatcher.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Accumulates stream chunks and cuts them into batches that end on a line
+ * boundary.
+ *
+ * NDJSON makes line boundaries trivial: any JSON writer escapes a newline
+ * inside a value as `\n`, so the byte 0x0A only ever ends a line. Cutting a
+ * batch is "find the last newline once enough bytes are pending".
+ *
+ * `target` is a size goal, not a limit: a single line longer than the target
+ * is held until its newline arrives. A batch that ended mid-line would make a
+ * consumer's JSON parse fail on a truncated object, so the boundary is the
+ * one thing that cannot be approximate.
+ *
+ * Every batch is a fresh copy that owns its `ArrayBuffer` (hence the
+ * `Uint8Array<ArrayBuffer>` type, which `Blob` requires), so a consumer can
+ * keep it without also keeping a network chunk alive, and the carried-over
+ * tail never aliases it.
+ */
+export declare class LineBatcher {
+    private readonly target;
+    private chunks;
+    private pending;
+    /** @param target batch size goal in bytes */
+    constructor(target: number);
+    /**
+     * Buffers `chunk` and, once at least `target` bytes are pending, cuts
+     * everything up to the last newline.
+     *
+     * Keeps `chunk` by reference until the next cut, so the caller must not
+     * mutate it afterwards.
+     *
+     * @returns the batch that was cut, or null when fewer than `target` bytes
+     *   are pending or they hold no newline yet
+     */
+    push(chunk: Uint8Array): Uint8Array<ArrayBuffer> | null;
+    /**
+     * Flushes whatever is pending, including a last line without a newline.
+     *
+     * @returns the final batch, or null when nothing is pending
+     */
+    end(): Uint8Array<ArrayBuffer> | null;
+    /** Cuts at the last pending newline and carries the rest over. */
+    private cut;
+    /** Coalesces the pending chunks into one buffer (no copy for one chunk). */
+    private join;
+}
+//# sourceMappingURL=LineBatcher.d.ts.map

package/dist/LineBatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LineBatcher.d.ts","sourceRoot":"","sources":["../src/LineBatcher.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;IAKV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAK;IAEpB,6CAA6C;gBAChB,MAAM,EAAE,MAAM;IAE3C;;;;;;;;;OASG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI;IAMvD;;;;OAIG;IACH,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI;IAQrC,kEAAkE;IAClE,OAAO,CAAC,GAAG;IAcX,4EAA4E;IAC5E,OAAO,CAAC,IAAI;CAKb"}

package/dist/LineStore.d.ts

@@ -0,0 +1,93 @@
+/** What {@link LineStore.append} reports while it indexes a batch. */
+export interface LineVisitor {
+    /**
+     * Called once per non-empty line, in order.
+     *
+     * @param text the line, decoded, without its newline
+     * @param index the line's number in the store, counted from zero
+     * @throws to reject the batch; see {@link LineStore.append}
+     */
+    line(text: string, index: number): void;
+    /**
+     * Called after the lines of each slice (about `sliceBytes` of input), just
+     * before the store yields to the event loop. A natural point to close a
+     * `ByteStringSearchIndex` segment.
+     */
+    sliceEnd?(): void;
+}
+interface LineStoreOptions {
+    /** Bytes decoded between yields; see {@link DEFAULT_SLICE_BYTES}. */
+    sliceBytes?: number;
+}
+/**
+ * Holds many NDJSON lines outside the JS heap and reads any one of them back
+ * by number.
+ *
+ * Each appended batch of lines moves into a `Blob`, which the browser keeps
+ * outside the JS heap (and may page to disk). Per line the store keeps only
+ * three integers in typed arrays: which blob holds it, and where it starts and
+ * ends. So a 500 MB file costs the heap a few MB of indexes, and reading a line
+ * back is one `Blob.slice().text()`.
+ *
+ * Lines are numbered by arrival, counting only non-empty ones.
+ */
+export declare class LineStore {
+    private readonly sliceBytes;
+    /** The batches as appended; a line is read back out of one of them. */
+    private batches;
+    /** Per line, indexed by line number: which of {@link batches} holds it. */
+    private lineBatch;
+    /** Per line: where it starts in its batch. */
+    private lineStart;
+    /** Per line: where it ends in its batch (exclusive, before the newline). */
+    private lineEnd;
+    private disposed;
+    constructor({ sliceBytes }?: LineStoreOptions);
+    /** How many lines the store holds. */
+    get length(): number;
+    /**
+     * Indexes the next batch of lines, about `sliceBytes` at a time, yielding to
+     * the event loop between slices, then moves the batch into a `Blob`.
+     *
+     * Lines are numbered by arrival, so each call must be awaited before the
+     * next.
+     *
+     * @param bytes whole lines (the last may lack its newline); copied into the
+     *   `Blob`, so the caller may reuse them afterwards
+     * @param visitor told about every line, see {@link LineVisitor}
+     * @throws whatever `visitor` throws. The lines indexed before it threw stay
+     *   numbered but can no longer be read, so a store that rejected a batch
+     *   should be disposed.
+     * @throws {Error} once disposed
+     */
+    append(bytes: Uint8Array<ArrayBuffer>, visitor: LineVisitor): Promise<void>;
+    /**
+     * Reads one line back. Reading from a `Blob` is asynchronous, so read the
+     * lines of a page in parallel.
+     *
+     * @throws {RangeError} if no line has that number
+     * @throws {Error} once disposed
+     */
+    read(index: number): Promise<string>;
+    /**
+     * Drops every reference, so the bytes and indexes can be collected. Safe to
+     * call more than once; any later call to the store throws.
+     */
+    dispose(): void;
+    /**
+     * Records each line of `slice`, which starts at byte `offset` of batch
+     * number `batch`, and hands it to `visitor`.
+     *
+     * The slice is decoded to one string and split on newlines; UTF-8 never
+     * uses the newline byte inside a multi-byte character, so the n-th string
+     * piece is the n-th byte range found by scanning for `\n`.
+     */
+    private indexSlice;
+    /**
+     * @throws {Error} once disposed, so a late call fails instead of answering
+     *   from emptied indexes
+     */
+    private assertOpen;
+}
+export {};
+//# sourceMappingURL=LineStore.d.ts.map

package/dist/LineStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LineStore.d.ts","sourceRoot":"","sources":["../src/LineStore.ts"],"names":[],"mappings":"AAYA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,IAAI,CAAC;CACnB;AAED,UAAU,gBAAgB;IACxB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,uEAAuE;IACvE,OAAO,CAAC,OAAO,CAAc;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,SAAS,CAA4B;IAC7C,8CAA8C;IAC9C,OAAO,CAAC,SAAS,CAA4B;IAC7C,4EAA4E;IAC5E,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAS;gBAEb,EAAE,UAAgC,EAAE,GAAE,gBAAqB;IAIvE,sCAAsC;IACtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjF;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAU1C;;;OAGG;IACH,OAAO,IAAI,IAAI;IAQf;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAsBlB;;;OAGG;IACH,OAAO,CAAC,UAAU;CAGnB"}

package/dist/bounded-batches.d.ts

@@ -0,0 +1,29 @@
+interface BoundedBatchesOptions {
+    /** How many bytes the part has; it must end on a newline. */
+    byteLength: number;
+    /** Batch size goal in bytes; see `LineBatcher`. */
+    batchBytes: number;
+    /**
+     * Bytes of the part already read from `reader`, such as the `rest` that
+     * `readFirstLine` returns. They come first.
+     */
+    leading?: Uint8Array | null;
+}
+/**
+ * Reads the next `byteLength` bytes of a stream and yields them as batches of
+ * whole lines, in order; they add up to exactly `byteLength`. Each batch owns
+ * its buffer, so it may be kept or transferred.
+ *
+ * Reading is pull-based: the stream is read only when the caller asks for the
+ * next batch, so a caller that is still processing the last batch holds the
+ * download back. That is the backpressure; nothing else bounds memory.
+ *
+ * However it ends (done, thrown, or the caller stopping early), the reader is
+ * cancelled, so whatever follows the part is never fetched.
+ *
+ * @throws {NdjsonError} `not-on-line-boundary` if the part does not end on a
+ *   newline, or `truncated` if the stream ends inside it
+ */
+export declare function boundedBatches(reader: ReadableStreamDefaultReader<Uint8Array>, { byteLength, batchBytes, leading }: BoundedBatchesOptions): AsyncGenerator<Uint8Array<ArrayBuffer>, void, undefined>;
+export {};
+//# sourceMappingURL=bounded-batches.d.ts.map

package/dist/bounded-batches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-batches.d.ts","sourceRoot":"","sources":["../src/bounded-batches.ts"],"names":[],"mappings":"AAEA,UAAU,qBAAqB;IAC7B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,cAAc,CACnC,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAC/C,EAAE,UAAU,EAAE,UAAU,EAAE,OAAc,EAAE,EAAE,qBAAqB,GAChE,cAAc,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAa1D"}

package/dist/bytes.d.ts

@@ -0,0 +1,23 @@
+/** The byte that ends every NDJSON line. */
+export declare const NEWLINE = 10;
+/**
+ * Copies `chunks` end to end into one new buffer.
+ *
+ * @param byteLength the chunks' total length, which callers already track
+ */
+export declare function concat(chunks: Uint8Array[], byteLength: number): Uint8Array;
+/**
+ * The "byte string" of `bytes`: one char per byte, with the byte's value as
+ * its char code.
+ *
+ * Every char is at most 0xFF, so V8 stores the string at one byte per char,
+ * where a string with any char outside Latin-1 costs two. It can still be
+ * searched with the native `String.indexOf`, which is several times faster
+ * than scanning a `Uint8Array` in JS. Encode a needle the same way and it
+ * occurs exactly where its bytes do.
+ *
+ * Built in chunks because `fromCharCode` takes one argument per char; `join`
+ * then yields one flat string, which `indexOf` scans without first copying it.
+ */
+export declare function toByteString(bytes: Uint8Array): string;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,eAAO,MAAM,OAAO,KAAO,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAQ3E;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAqBtD"}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Why a stream could not be read as NDJSON:
+ *
+ * - `no-newline`: the stream ended before the line being read did
+ * - `line-too-long`: a line grew past the caller's cap
+ * - `not-on-line-boundary`: a declared byte length does not end on a newline
+ * - `truncated`: the stream ended before a declared byte length was reached
+ */
+export type NdjsonErrorCode = 'no-newline' | 'line-too-long' | 'not-on-line-boundary' | 'truncated';
+/** The stream's bytes do not have the shape the reader was told to expect. */
+export declare class NdjsonError extends Error {
+    readonly code: NdjsonErrorCode;
+    /**
+     * For `not-on-line-boundary` and `truncated`: the byte of the part where
+     * the problem shows, so a caller can report it in its own terms. The
+     * declared length for the first, the bytes received for the second.
+     */
+    readonly offset?: number | undefined;
+    constructor(code: NdjsonErrorCode, message: string, 
+    /**
+     * For `not-on-line-boundary` and `truncated`: the byte of the part where
+     * the problem shows, so a caller can report it in its own terms. The
+     * declared length for the first, the bytes received for the second.
+     */
+    offset?: number | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,eAAe,GAAG,sBAAsB,GAAG,WAAW,CAAC;AAEpG,8EAA8E;AAC9E,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAPf,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM;IACf;;;;OAIG;IACM,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stream, batch and index huge NDJSON files in the browser without holding
+ * them on the JS heap.
+ *
+ * @packageDocumentation
+ */
+export { NEWLINE, concat, toByteString } from './bytes';
+export { NdjsonError, type NdjsonErrorCode } from './errors';
+export { GrowableInt32Array } from './GrowableInt32Array';
+export { yieldToMain } from './yield-to-main';
+export { LineBatcher } from './LineBatcher';
+export { BoundedLineBatcher } from './BoundedLineBatcher';
+export { readFirstLine } from './read-first-line';
+export { boundedBatches } from './bounded-batches';
+export { LineStore, type LineVisitor } from './LineStore';
+export { ByteStringSearchIndex } from './ByteStringSearchIndex';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,386 @@
+// src/bytes.ts
+var NEWLINE = 10;
+function concat(chunks, byteLength) {
+  const out = new Uint8Array(byteLength);
+  let at = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, at);
+    at += chunk.byteLength;
+  }
+  return out;
+}
+var CHARS_PER_CALL = 32 * 1024;
+function toByteString(bytes) {
+  const parts = [];
+  for (let at = 0;at < bytes.length; at += CHARS_PER_CALL) {
+    parts.push(String(Reflect.apply(String.fromCharCode, undefined, bytes.subarray(at, at + CHARS_PER_CALL))));
+  }
+  return parts.join("");
+}
+// src/errors.ts
+class NdjsonError extends Error {
+  code;
+  offset;
+  constructor(code, message, offset) {
+    super(message);
+    this.code = code;
+    this.offset = offset;
+    this.name = "NdjsonError";
+  }
+}
+// src/GrowableInt32Array.ts
+var DEFAULT_MAX_LENGTH = 1 << 26;
+
+class GrowableInt32Array {
+  buffer;
+  values;
+  size = 0;
+  constructor(maxLength = DEFAULT_MAX_LENGTH) {
+    this.buffer = new ArrayBuffer(Math.min(1024, maxLength) * 4, {
+      maxByteLength: maxLength * 4
+    });
+    this.values = new Int32Array(this.buffer);
+  }
+  get length() {
+    return this.size;
+  }
+  push(value) {
+    if (this.size === this.values.length) {
+      this.buffer.resize(Math.min(this.buffer.byteLength * 2, this.buffer.maxByteLength));
+    }
+    if (this.size === this.values.length) {
+      throw new RangeError(`More than ${this.size} values`);
+    }
+    this.values[this.size++] = value;
+  }
+  at(index) {
+    if (index < 0 || index >= this.size) {
+      throw new RangeError(`Index ${index} outside [0, ${this.size})`);
+    }
+    return this.values[index];
+  }
+  toArray() {
+    return this.values.subarray(0, this.size);
+  }
+}
+// src/yield-to-main.ts
+function yieldToMain() {
+  const { scheduler } = globalThis;
+  if (typeof scheduler?.yield === "function")
+    return scheduler.yield();
+  if (typeof MessageChannel === "function") {
+    return new Promise((resolve) => {
+      const channel = new MessageChannel;
+      channel.port1.onmessage = () => {
+        channel.port1.close();
+        resolve();
+      };
+      channel.port2.postMessage(null);
+    });
+  }
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+// src/LineBatcher.ts
+class LineBatcher {
+  target;
+  chunks = [];
+  pending = 0;
+  constructor(target) {
+    this.target = target;
+  }
+  push(chunk) {
+    this.chunks.push(chunk);
+    this.pending += chunk.byteLength;
+    return this.pending >= this.target ? this.cut() : null;
+  }
+  end() {
+    if (this.pending === 0)
+      return null;
+    const rest = this.join().slice();
+    this.chunks = [];
+    this.pending = 0;
+    return rest;
+  }
+  cut() {
+    const buf = this.join();
+    const at = buf.lastIndexOf(NEWLINE);
+    if (at === -1) {
+      this.chunks = [buf];
+      return null;
+    }
+    const tail = buf.subarray(at + 1);
+    this.chunks = tail.byteLength > 0 ? [tail.slice()] : [];
+    this.pending = tail.byteLength;
+    return buf.subarray(0, at + 1).slice();
+  }
+  join() {
+    const [only] = this.chunks;
+    if (this.chunks.length === 1 && only != null)
+      return only;
+    return concat(this.chunks, this.pending);
+  }
+}
+// src/BoundedLineBatcher.ts
+class BoundedLineBatcher {
+  byteLength;
+  batcher;
+  seen = 0;
+  constructor(byteLength, batchBytes) {
+    this.byteLength = byteLength;
+    this.batcher = new LineBatcher(batchBytes);
+  }
+  get complete() {
+    return this.seen === this.byteLength;
+  }
+  push(chunk) {
+    if (this.complete)
+      return [];
+    const left = this.byteLength - this.seen;
+    if (chunk.byteLength < left) {
+      this.seen += chunk.byteLength;
+      return present(this.batcher.push(chunk));
+    }
+    const head = chunk.subarray(0, left);
+    this.seen = this.byteLength;
+    if (head[head.byteLength - 1] !== NEWLINE) {
+      throw new NdjsonError("not-on-line-boundary", `byte ${this.byteLength} of the part is not a newline: ` + "the declared length does not fall on a line boundary", this.byteLength);
+    }
+    return [...present(this.batcher.push(head)), ...present(this.batcher.end())];
+  }
+  end() {
+    if (!this.complete) {
+      throw new NdjsonError("truncated", `stream ended after ${this.seen} bytes of the part, ` + `which declares ${this.byteLength}`, this.seen);
+    }
+  }
+}
+function present(batch) {
+  return batch == null ? [] : [batch];
+}
+// src/read-first-line.ts
+async function readFirstLine(reader, { maxBytes }) {
+  const chunks = [];
+  let length = 0;
+  for (;; ) {
+    const { done, value } = await reader.read();
+    if (done) {
+      throw new NdjsonError("no-newline", "stream ended before line 1 did");
+    }
+    const at = value.indexOf(NEWLINE);
+    if (length + (at === -1 ? value.byteLength : at) > maxBytes) {
+      throw new NdjsonError("line-too-long", `line 1 is over ${maxBytes} bytes`);
+    }
+    if (at === -1) {
+      chunks.push(value);
+      length += value.byteLength;
+      continue;
+    }
+    chunks.push(value.subarray(0, at));
+    length += at;
+    const rest = value.subarray(at + 1);
+    return {
+      line: new TextDecoder().decode(concat(chunks, length)),
+      rest: rest.byteLength > 0 ? rest : null
+    };
+  }
+}
+// src/bounded-batches.ts
+async function* boundedBatches(reader, { byteLength, batchBytes, leading = null }) {
+  const part = new BoundedLineBatcher(byteLength, batchBytes);
+  try {
+    if (leading != null)
+      yield* part.push(leading);
+    while (!part.complete) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      yield* part.push(value);
+    }
+    part.end();
+  } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
+  }
+}
+// src/LineStore.ts
+var DEFAULT_SLICE_BYTES = 1 << 20;
+
+class LineStore {
+  sliceBytes;
+  batches = [];
+  lineBatch = new GrowableInt32Array;
+  lineStart = new GrowableInt32Array;
+  lineEnd = new GrowableInt32Array;
+  disposed = false;
+  constructor({ sliceBytes = DEFAULT_SLICE_BYTES } = {}) {
+    this.sliceBytes = sliceBytes;
+  }
+  get length() {
+    return this.lineStart.length;
+  }
+  async append(bytes, visitor) {
+    this.assertOpen();
+    const batch = this.batches.length;
+    const decoder = new TextDecoder;
+    let sliceStart = 0;
+    while (sliceStart < bytes.byteLength) {
+      const newline = bytes.indexOf(NEWLINE, Math.min(sliceStart + this.sliceBytes, bytes.byteLength) - 1);
+      const sliceEnd = newline === -1 ? bytes.byteLength : newline + 1;
+      this.indexSlice(bytes.subarray(sliceStart, sliceEnd), batch, sliceStart, decoder, visitor);
+      visitor.sliceEnd?.();
+      sliceStart = sliceEnd;
+      if (sliceStart < bytes.byteLength)
+        await yieldToMain();
+    }
+    this.batches.push(new Blob([bytes]));
+  }
+  async read(index) {
+    this.assertOpen();
+    const batch = this.batches[this.lineBatch.at(index)];
+    if (batch == null) {
+      throw new RangeError(`Line ${index} belongs to a rejected batch`);
+    }
+    return batch.slice(this.lineStart.at(index), this.lineEnd.at(index)).text();
+  }
+  dispose() {
+    this.disposed = true;
+    this.batches = [];
+    this.lineBatch = new GrowableInt32Array(0);
+    this.lineStart = new GrowableInt32Array(0);
+    this.lineEnd = new GrowableInt32Array(0);
+  }
+  indexSlice(slice, batch, offset, decoder, visitor) {
+    let lineStart = 0;
+    for (const line of decoder.decode(slice).split(`
+`)) {
+      const newline = slice.indexOf(NEWLINE, lineStart);
+      const lineEnd = newline === -1 ? slice.byteLength : newline;
+      if (line.length > 0) {
+        const index = this.lineStart.length;
+        this.lineBatch.push(batch);
+        this.lineStart.push(offset + lineStart);
+        this.lineEnd.push(offset + lineEnd);
+        visitor.line(line, index);
+      }
+      lineStart = lineEnd + 1;
+    }
+  }
+  assertOpen() {
+    if (this.disposed)
+      throw new Error("LineStore disposed");
+  }
+}
+// src/ByteStringSearchIndex.ts
+var SCAN_BUDGET_MS = 30;
+var SEPARATOR = "\x00";
+
+class ByteStringSearchIndex {
+  segments = [];
+  docs = 0;
+  pendingFirst = 0;
+  scratch = new Uint8Array(1 << 21);
+  written = 0;
+  pendingStarts = new Int32Array(1024);
+  encoder = new TextEncoder;
+  disposed = false;
+  get size() {
+    return this.docs;
+  }
+  append(values) {
+    this.assertOpen();
+    const pending = this.docs - this.pendingFirst;
+    if (pending === this.pendingStarts.length) {
+      const grown = new Int32Array(pending * 2);
+      grown.set(this.pendingStarts);
+      this.pendingStarts = grown;
+    }
+    this.pendingStarts[pending] = this.written;
+    this.encode(values.map((value) => value.toLowerCase()).join(SEPARATOR));
+    return this.docs++;
+  }
+  seal() {
+    const pending = this.docs - this.pendingFirst;
+    if (pending === 0)
+      return;
+    this.segments.push({
+      firstDoc: this.pendingFirst,
+      text: toByteString(this.scratch.subarray(0, this.written)),
+      starts: this.pendingStarts.slice(0, pending)
+    });
+    this.pendingFirst = this.docs;
+    this.written = 0;
+  }
+  async search(needle) {
+    this.assertOpen();
+    this.seal();
+    const bytes = toByteString(new TextEncoder().encode(needle.toLowerCase()));
+    const found = new GrowableInt32Array;
+    let sliceStarted = performance.now();
+    for (const { firstDoc, text, starts } of this.segments) {
+      let at = text.indexOf(bytes);
+      while (at !== -1) {
+        const doc = lastAtOrBefore(starts, at);
+        found.push(firstDoc + doc);
+        const next = starts[doc + 1];
+        if (next == null)
+          break;
+        at = text.indexOf(bytes, next);
+      }
+      if (performance.now() - sliceStarted > SCAN_BUDGET_MS) {
+        await yieldToMain();
+        sliceStarted = performance.now();
+      }
+    }
+    return found.toArray();
+  }
+  dispose() {
+    this.disposed = true;
+    this.segments = [];
+    this.scratch = new Uint8Array(0);
+    this.pendingStarts = new Int32Array(0);
+    this.docs = 0;
+    this.pendingFirst = 0;
+    this.written = 0;
+  }
+  encode(text) {
+    const needed = this.written + text.length * 3 + 1;
+    if (needed > this.scratch.length) {
+      const grown = new Uint8Array(Math.max(needed, this.scratch.length * 2));
+      grown.set(this.scratch.subarray(0, this.written));
+      this.scratch = grown;
+    }
+    const { written } = this.encoder.encodeInto(text, this.scratch.subarray(this.written));
+    this.scratch[this.written + written] = 0;
+    this.written += written + 1;
+  }
+  assertOpen() {
+    if (this.disposed)
+      throw new Error("ByteStringSearchIndex disposed");
+  }
+}
+function lastAtOrBefore(sorted, value) {
+  let low = 0;
+  let high = sorted.length - 1;
+  while (low < high) {
+    const mid = low + high + 1 >> 1;
+    if ((sorted[mid] ?? 0) <= value)
+      low = mid;
+    else
+      high = mid - 1;
+  }
+  return low;
+}
+export {
+  BoundedLineBatcher,
+  ByteStringSearchIndex,
+  GrowableInt32Array,
+  LineBatcher,
+  LineStore,
+  NEWLINE,
+  NdjsonError,
+  boundedBatches,
+  concat,
+  readFirstLine,
+  toByteString,
+  yieldToMain
+};

package/dist/read-first-line.d.ts

@@ -0,0 +1,29 @@
+interface ReadFirstLineOptions {
+    /**
+     * The longest line this reader buffers. A header line is usually a few
+     * kilobytes; a stream with no newline in its first `maxBytes` is not what
+     * the caller expects, and buffering it whole would put the entire download
+     * in the JS heap before failing.
+     */
+    maxBytes: number;
+}
+/**
+ * Reads up to the first newline and decodes that line, typically a header
+ * that describes the rest of the stream.
+ *
+ * Chunks are held until the newline arrives, so a line split across network
+ * reads is put back together. Only this line is ever decoded to a JS string;
+ * the rest of the stream stays bytes, and is left unread.
+ *
+ * @returns the line without its newline, and the bytes read past it (a view
+ *   into the last chunk; null when the newline was its last byte)
+ * @throws {NdjsonError} `no-newline` if the stream ends before any newline,
+ *   or `line-too-long` if the line grows past `maxBytes`. The reader is not
+ *   cancelled; that is the caller's call.
+ */
+export declare function readFirstLine(reader: ReadableStreamDefaultReader<Uint8Array>, { maxBytes }: ReadFirstLineOptions): Promise<{
+    line: string;
+    rest: Uint8Array | null;
+}>;
+export {};
+//# sourceMappingURL=read-first-line.d.ts.map

package/dist/read-first-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-first-line.d.ts","sourceRoot":"","sources":["../src/read-first-line.ts"],"names":[],"mappings":"AAGA,UAAU,oBAAoB;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAC/C,EAAE,QAAQ,EAAE,EAAE,oBAAoB,GACjC,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,CAAC,CA2BpD"}

package/dist/yield-to-main.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ends the current task and resumes in a new one, so the browser can paint
+ * and handle input in between: the "yield to the main thread" pattern for
+ * splitting long work.
+ *
+ * Uses `scheduler.yield()` where it exists: it resumes ahead of other queued
+ * tasks, so a long parse that yields hundreds of times is not slowed by
+ * unrelated work queued behind it. Elsewhere it falls back to a
+ * `MessageChannel` message, which starts a new task without the 4 ms clamp
+ * that nested `setTimeout(0)` calls get, and to `setTimeout` where there is
+ * no `MessageChannel` either.
+ */
+export declare function yieldToMain(): Promise<void>;
+//# sourceMappingURL=yield-to-main.d.ts.map

package/dist/yield-to-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yield-to-main.d.ts","sourceRoot":"","sources":["../src/yield-to-main.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAgB3C"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@saunos/ndjson-index",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Stream, batch and index huge NDJSON files in the browser without holding them on the JS heap",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saunos/ndjson-index"
+  },
+  "keywords": [
+    "ndjson",
+    "jsonl",
+    "stream",
+    "search",
+    "blob",
+    "browser"
+  ],
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build:lib": "bun build ./src/index.ts --outdir ./dist --target browser --packages external",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun run build:lib && bun run build:types",
+    "docs": "typedoc",
+    "prepublishOnly": "bun run tsc && bun run lint && bun run fmt && bun run test && bun run build",
+    "tsc": "tsc --noEmit",
+    "test": "bun test --coverage",
+    "lint": "oxlint src",
+    "fmt:write": "oxfmt src",
+    "fmt": "oxfmt --check src"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
+    "typedoc": "^0.28.20",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}