spliterator 6.0.1 → 6.2.0

package/out/lib/internal/shared.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { PathBuilderLike } from "path-ts";
+/**
+ * A trimmed-down version of the Node.js `Stats` interface.
+ */
+export type StatsLike = Pick<Stats, "size" | "blksize" | "mtimeMs">;
+/**
+ * A trimmed-down version of the Node.js `FileHandle` interface.
+ */
+export type FileHandleLike = Pick<FileHandle, "fd" | "stat" | "close" | "read" | "readableWebStream" | "createReadStream">;
+/**
+ * A tuple representing a window of bytes in a buffer.
+ */
+export type ByteRange = [
+    /**
+     * The starting byte index of the window.
+     */
+    start: number,
+    /**
+     * The ending byte index of the window.
+     */
+    end: number
+];
+/**
+ * Typed arrays that may be used as sources for byte streams.
+ */
+export type TypedArray = Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | BigUint64Array | BigInt64Array | Float32Array | Float64Array;
+/**
+ * A source of bytes that can be read from.
+ */
+export type ReadableSource = FileHandleLike | TypedArray;
+/**
+ * Type-predicate to determine if a value is a file handle.
+ */
+export declare function isFileHandleLike(input: unknown): input is FileHandleLike;
+/**
+ * Type-helper to determine the destination type for a typed array.
+ *
+ * This is useful to infer the ultimate return type of a function which optionally accepts a typed array destination.
+ */
+export type TypedArrayFallback<T> = T extends TypedArray ? T : Uint8Array;
+/**
+ * Options for reading a range of bytes from a source.
+ */
+export interface ReadBytesOptions {
+    /**
+     * The offset from where to begin writing to the buffer.
+     *
+     * This is useful when reading multiple buffers into a single buffer.
+     *
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * How many bytes to read.
+     *
+     * @default `length of buffer`
+     */
+    length?: number;
+    /**
+     * From where to start reading.
+     */
+    position?: number;
+}
+/**
+ * A trait for reading a range of bytes from a source.
+ *
+ * While possible with a variety of platform-specific APIs, this trait provides a common interface for reading byte
+ * ranges.
+ */
+export interface ByteRangeReader extends AsyncIterator<Uint8Array> {
+    /**
+     * Reads a range of bytes from a source.
+     */
+    read(options?: ReadBytesOptions): Promise<Uint8Array>;
+    read<B extends TypedArray>(options: ReadBytesOptions & {
+        buffer: B;
+    }): Promise<B>;
+}
+/**
+ * An isomorphic file resource which can be read from and disposed.
+ *
+ * Generally, this interface aligns with the `File` interface in the browser.
+ */
+export interface FileResourceLike extends File {
+    /**
+     * Slice the file into a new file resource.
+     *
+     * @param start - The byte offset to start the slice.
+     * @param end - The byte offset to end the slice.
+     */
+    slice(start: number, end: number): FileResourceLike;
+    /**
+     * The block size of the file, if known.
+     */
+    blockSize?: number;
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
+}
+/**
+ * Type-predicate to determine if a value is a file resource.
+ */
+export declare function isFileResourceLike(input: unknown): input is FileResourceLike;
+/**
+ * Given a file resource, adds a `read` method to read a range of bytes.
+ *
+ * This allows the web `File` interface to be used as a byte range reader.
+ */
+export declare function applyReaderPolyfill<T extends FileResourceLike>(file: T): asserts file is T & ByteRangeReader;
+/**
+ * An asynchronous iterable byte stream.
+ *
+ * String chunks are tolerated and UTF-8 encoded on arrival — a `fs.createReadStream(path, "utf8")` or Node `Readable`
+ * in string mode would otherwise coerce to garbage bytes via `TypedArray.set`.
+ *
+ * Note that as an iterable this will drained of all bytes when iterated over.
+ */
+export interface AsyncChunkIterator extends AsyncIterable<Uint8Array | string> {
+    /**
+     * Disposes of the byte stream, releasing any resources.
+     *
+     * This method is optional and may not be implemented by all byte streams.
+     */
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
+}
+/**
+ * An asynchronous resource to a delimited byte stream, which can be a...
+ *
+ * - `string` representing a file path.
+ * - {@linkcode URL} object representing a file path.
+ * - {@linkcode FileHandleLike} object representing an open file handle.
+ * - {@linkcode AsyncChunkIterator} object representing an asynchronous byte stream — anything async-iterable over bytes
+ *   qualifies: a Node `Readable` (child-process stdout, a gunzip pipe), a web `ReadableStream` wrapped via
+ *   `Symbol.asyncIterator`, or a hand-rolled generator.
+ */
+export type AsyncDataResource = string | URL | FileHandleLike | AsyncChunkIterator | PathBuilderLike;
+/**
+ * A resource to a delimited byte stream, i.e., a file buffer, handle, or path.
+ *
+ * @see {@link AsyncDataResource} : File paths, URLs, and handles.
+ * @see {@link TypedArray} : Buffers and typed arrays.
+ */
+export type DataResource = AsyncDataResource | TypedArray;
+/**
+ * A trimmed-down version of the text decoder interface.
+ */
+export interface TextDecoderLike {
+    decode(input: Uint8Array): string;
+}
+//# sourceMappingURL=shared.d.ts.map

package/out/lib/internal/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../lib/internal/shared.ts"],"names":[],"mappings":"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"}

package/out/lib/internal/shared.js

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+/**
+ * Type-predicate to determine if a value is a file handle.
+ */
+export function isFileHandleLike(input) {
+    return Boolean(input && typeof input === "object" && "fd" in input);
+}
+/**
+ * Type-predicate to determine if a value is a file resource.
+ */
+export function isFileResourceLike(input) {
+    return Boolean(input && typeof input === "object" && "slice" in input);
+}
+/**
+ * Given a file resource, adds a `read` method to read a range of bytes.
+ *
+ * This allows the web `File` interface to be used as a byte range reader.
+ */
+export function applyReaderPolyfill(file) {
+    if ("read" in file && typeof file.read === "function") {
+        return;
+    }
+    Object.assign(file, {
+        async read(options = {}) {
+            const { position: start = 0, length = file.size, offset = 0 } = options;
+            const windowed = file.slice(start, start + length);
+            const bytes = (await windowed.bytes());
+            if (options.buffer) {
+                const destination = options.buffer;
+                destination.set(bytes, offset);
+                return destination;
+            }
+            return bytes;
+        },
+    });
+}
+//# sourceMappingURL=shared.js.map

package/out/lib/internal/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../lib/internal/shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyDH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC9C,OAAO,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,IAAI,KAAK,CAAC,CAAA;AACpE,CAAC;AAuED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAChD,OAAO,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,CAAC,CAAA;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAA6B,IAAO;IACtE,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACvD,OAAM;IACP,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;QACnB,KAAK,CAAC,IAAI,CAAuB,OAAO,GAAsC,EAAE;YAC/E,MAAM,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,GAAG,OAAO,CAAA;YACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,CAAA;YAElD,MAAM,KAAK,GAAG,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,CAA0B,CAAA;YAE/D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACpB,MAAM,WAAW,GAAG,OAAO,CAAC,MAA+B,CAAA;gBAC3D,WAAW,CAAC,GAAG,CAAC,KAAY,EAAE,MAAM,CAAC,CAAA;gBAErC,OAAO,WAAW,CAAA;YACnB,CAAC;YAED,OAAO,KAAK,CAAA;QACb,CAAC;KACD,CAAC,CAAA;AACH,CAAC"}

package/out/lib/internal/utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+/**
+ * Convenience function to await an async iterable.
+ */
+export declare function iterateInParallel<T>(asyncIterable: AsyncIterable<T>): Promise<void>;
+/**
+ * Type-predicate for checking if a value is iterable.
+ *
+ * @category Type Guard
+ * @category Object
+ */
+export declare function isIterable<T>(input: unknown): input is Iterable<T>;
+/**
+ * Iterable that can be checked for the existence of a member.
+ */
+export interface IndexedIterable<T = unknown> extends Iterable<T> {
+    has(value: T): boolean;
+}
+/**
+ * Type-predicate for checking if an member within an iterable can be checked for existence.
+ */
+export declare function isIndexedIterable<T>(value: Iterable<T>): value is IndexedIterable<T>;
+/**
+ * Extracts the property keys of an object that are of type `number`.
+ */
+export type NumericProperties<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+/**
+ * Given an iterable of objects, returns the sum of the specified property.
+ */
+export declare function sumOf<T extends object>(iterable: Iterable<T>, prop: NumericProperties<T>): number;
+//# sourceMappingURL=utils.d.ts.map

package/out/lib/internal/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../lib/internal/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,CAElE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAChE,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,CAEpF;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;KACjC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK;CAC/C,CAAC,MAAM,CAAC,CAAC,CAAA;AAEV;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,CAQjG"}

package/out/lib/internal/utils.js

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+/**
+ * Convenience function to await an async iterable.
+ */
+export async function iterateInParallel(asyncIterable) {
+    for await (const _ of asyncIterable) {
+        /* empty */
+    }
+}
+/**
+ * Type-predicate for checking if a value is iterable.
+ *
+ * @category Type Guard
+ * @category Object
+ */
+export function isIterable(input) {
+    return Symbol.iterator in new Object(input);
+}
+/**
+ * Type-predicate for checking if an member within an iterable can be checked for existence.
+ */
+export function isIndexedIterable(value) {
+    return value && typeof value.has === "function";
+}
+/**
+ * Given an iterable of objects, returns the sum of the specified property.
+ */
+export function sumOf(iterable, prop) {
+    let total = 0;
+    for (const item of iterable) {
+        total += item[prop];
+    }
+    return total;
+}
+//# sourceMappingURL=utils.js.map

package/out/lib/internal/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../lib/internal/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAI,aAA+B;IACzE,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QACrC,WAAW;IACZ,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAI,KAAc;IAC3C,OAAO,MAAM,CAAC,QAAQ,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAA;AAC5C,CAAC;AASD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAI,KAAkB;IACtD,OAAO,KAAK,IAAI,OAAQ,KAAyB,CAAC,GAAG,KAAK,UAAU,CAAA;AACrE,CAAC;AASD;;GAEG;AACH,MAAM,UAAU,KAAK,CAAmB,QAAqB,EAAE,IAA0B;IACxF,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC7B,KAAK,IAAI,IAAI,CAAC,IAAI,CAAW,CAAA;IAC9B,CAAC;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}

package/out/lib/io/adaptive-source.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { type AsyncSpliteratorInit } from "../core/Spliterator.js";
+import type { AsyncChunkIterator, AsyncDataResource } from "../internal/shared.js";
+/**
+ * Byte length at or below which a source is read whole and parsed synchronously.
+ *
+ * What this buys is **fixed setup cost** — opening a handle and standing up a read stream, ~100µs — not throughput, so
+ * the win decays as the source grows and the threshold marks where it stops being measurable. End-to-end against the
+ * streaming path (Node 26, min of 200 runs, two independent sweeps): ~1.85× at 635B, ~1.45× at 6.5KB, ~1.4× at 125KiB.
+ * At 253KiB and above the two runs disagreed on which was faster, so there is nothing reliable left to win.
+ *
+ * Raising this does not recover the much larger gap a raw synchronous parse shows (~1.6× even at 1GiB); that gap is
+ * eaten by the per-row cost of the sequence itself, which both paths pay. It only trades resident memory — a 1GiB
+ * source costs ~105MB streamed against ~1121MB read whole — for a difference that no longer measures.
+ */
+export declare const DEFAULT_BULK_THRESHOLD: number;
+export interface AdaptiveSourceInit extends AsyncSpliteratorInit {
+    /**
+     * Byte length at or below which the whole source is read into memory and parsed synchronously, trading resident
+     * memory for speed.
+     *
+     * Raising it buys nothing measurable and costs memory linearly — the advantage is gone by ~256KiB. Set `0` to always
+     * stream, which is what you want when a bounded footprint is the reason you reached for this library.
+     *
+     * @default 128 KiB ({@linkcode DEFAULT_BULK_THRESHOLD})
+     */
+    bulkThreshold?: number;
+}
+/**
+ * Take the delimited rows of `source`, reading it whole when it is small enough to be worth the memory and streaming it
+ * otherwise. Returns a sync iterable in the first case and an async one in the second; both satisfy
+ * {@linkcode AsyncSequence}.
+ */
+export declare function openDelimitedRows(source: AsyncDataResource | AsyncChunkIterator, init?: AdaptiveSourceInit): Promise<AsyncIterable<Uint8Array> | Iterable<Uint8Array>>;
+//# sourceMappingURL=adaptive-source.d.ts.map

package/out/lib/io/adaptive-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-source.d.ts","sourceRoot":"","sources":["../../../lib/io/adaptive-source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,oBAAoB,EAAe,MAAM,wBAAwB,CAAA;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAElF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,QAAa,CAAA;AAEhD,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC/D;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAuBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,iBAAiB,GAAG,kBAAkB,EAC9C,IAAI,GAAE,kBAAuB,GAC3B,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAuB3D"}

package/out/lib/io/adaptive-source.js

@@ -0,0 +1,95 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { CharacterSequence } from "../core/CharacterSequence.js";
+import { Spliterator } from "../core/Spliterator.js";
+/**
+ * Byte length at or below which a source is read whole and parsed synchronously.
+ *
+ * What this buys is **fixed setup cost** — opening a handle and standing up a read stream, ~100µs — not throughput, so
+ * the win decays as the source grows and the threshold marks where it stops being measurable. End-to-end against the
+ * streaming path (Node 26, min of 200 runs, two independent sweeps): ~1.85× at 635B, ~1.45× at 6.5KB, ~1.4× at 125KiB.
+ * At 253KiB and above the two runs disagreed on which was faster, so there is nothing reliable left to win.
+ *
+ * Raising this does not recover the much larger gap a raw synchronous parse shows (~1.6× even at 1GiB); that gap is
+ * eaten by the per-row cost of the sequence itself, which both paths pay. It only trades resident memory — a 1GiB
+ * source costs ~105MB streamed against ~1121MB read whole — for a difference that no longer measures.
+ */
+export const DEFAULT_BULK_THRESHOLD = 128 * 1024;
+function isChunkIterator(source) {
+    return typeof source === "object" && source !== null && Symbol.asyncIterator in source;
+}
+function toBytes(chunk) {
+    return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+}
+/**
+ * Parse in-memory bytes with the synchronous engine.
+ *
+ * Awaiting {@linkcode CharacterSequence.whenReady} first is the point: the WASM scanner loads asynchronously, so a
+ * synchronous caller normally completes before it is available and silently uses the JS scanner. Reaching the sync
+ * engine through an async path is the one place that can be avoided — worth ~26% on a large source.
+ */
+async function bulk(bytes, init) {
+    await CharacterSequence.whenReady();
+    return Spliterator.fromSync(bytes, init);
+}
+/**
+ * Take the delimited rows of `source`, reading it whole when it is small enough to be worth the memory and streaming it
+ * otherwise. Returns a sync iterable in the first case and an async one in the second; both satisfy
+ * {@linkcode AsyncSequence}.
+ */
+export async function openDelimitedRows(source, init = {}) {
+    const threshold = init.bulkThreshold ?? DEFAULT_BULK_THRESHOLD;
+    if (threshold <= 0)
+        return Spliterator.fromAsync(source, init);
+    if (isChunkIterator(source))
+        return openChunkIterator(source, threshold, init);
+    let size;
+    try {
+        const { readFileSize } = await import("spliterator/node/fs");
+        size = await readFileSize(source);
+    }
+    catch {
+        // Unsized or unreachable by the Node adapter — the streaming path owns reporting why.
+        return Spliterator.fromAsync(source, init);
+    }
+    if (size > threshold)
+        return Spliterator.fromAsync(source, init);
+    const { readBytes } = await import("spliterator/node/fs");
+    return bulk(await readBytes(source, 0, size), init);
+}
+/**
+ * A stream cannot be measured before it is read, so the size test becomes an end-of-input test: pull one chunk, and if
+ * the stream is already exhausted the whole input is in hand and no threshold policy is needed.
+ *
+ * When it is not exhausted the pulled chunks cannot be discarded, so the stream is re-headed with them in front.
+ */
+async function openChunkIterator(source, threshold, init) {
+    const iterator = source[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    if (first.done)
+        return bulk(new Uint8Array(0), init);
+    const second = await iterator.next();
+    const head = toBytes(first.value);
+    if (second.done && head.byteLength <= threshold)
+        return bulk(head, init);
+    const pulled = second.done ? [first.value] : [first.value, second.value];
+    const reheaded = {
+        async *[Symbol.asyncIterator]() {
+            yield* pulled;
+            for (;;) {
+                const next = await iterator.next();
+                if (next.done)
+                    return;
+                yield next.value;
+            }
+        },
+    };
+    if (Symbol.asyncDispose in source) {
+        reheaded[Symbol.asyncDispose] = () => source[Symbol.asyncDispose]();
+    }
+    return Spliterator.fromAsync(reheaded, init);
+}
+//# sourceMappingURL=adaptive-source.js.map

package/out/lib/io/adaptive-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-source.js","sourceRoot":"","sources":["../../../lib/io/adaptive-source.ts"],"names":[],"mappings":"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"}

package/out/lib/io/writer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { type WriteStream, type PathLike } from "node:fs";
+/**
+ * Callback for writing a line to a newline-delimited file.
+ *
+ * The trailing newline is appended for you — pass the content alone.
+ */
+export interface WriteLineCallback {
+    /**
+     * Write a line to the file, terminated with a newline. The content should not contain one itself.
+     */
+    (content: string): Promise<void>;
+    /**
+     * Write a chunk to the file, terminated with a newline. The chunk should not contain one itself.
+     */
+    (chunk: any, encoding: BufferEncoding): Promise<void>;
+}
+export interface NewlineWriter extends AsyncDisposable {
+    /**
+     * Write a line to the file, terminated with a newline.
+     *
+     * The content should not contain a newline character — the writer supplies the delimiter.
+     */
+    write: WriteLineCallback;
+    dispose: () => Promise<void>;
+    writer: WriteStream;
+}
+/**
+ * Creates a writer for newline-delimited files.
+ *
+ * Every {@linkcode NewlineWriter.write} terminates its content with `\n`, so the file is delimited (and round-trips
+ * through {@linkcode TextSpliterator}) without the caller appending anything:
+ *
+ * ```ts
+ * await using out = createNewlineWriter("rows.jsonl")
+ *
+ * for (const row of rows) await out.write(JSON.stringify(row))
+ * ```
+ */
+export declare function createNewlineWriter(filePath: PathLike): NewlineWriter;
+//# sourceMappingURL=writer.d.ts.map

package/out/lib/io/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../lib/io/writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAqB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChC;;OAEG;IACH,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,aAAc,SAAQ,eAAe;IACrD;;;;OAIG;IACH,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,EAAE,WAAW,CAAA;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CA6CrE"}

package/out/lib/io/writer.js

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { createWriteStream } from "node:fs";
+/**
+ * Creates a writer for newline-delimited files.
+ *
+ * Every {@linkcode NewlineWriter.write} terminates its content with `\n`, so the file is delimited (and round-trips
+ * through {@linkcode TextSpliterator}) without the caller appending anything:
+ *
+ * ```ts
+ * await using out = createNewlineWriter("rows.jsonl")
+ *
+ * for (const row of rows) await out.write(JSON.stringify(row))
+ * ```
+ */
+export function createNewlineWriter(filePath) {
+    const writer = createWriteStream(filePath);
+    const write = (content, encoding) => {
+        return new Promise((resolve, reject) => {
+            const settle = (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            };
+            // The delimiter goes out as its own chunk rather than concatenated onto `content`: the
+            // two-argument overload accepts a Buffer, and `buffer + "\n"` would stringify it via
+            // `toString()` and corrupt the bytes. Stream writes are ordered, so the newline always
+            // follows its content, and settling on the delimiter's callback resolves once the whole
+            // line has flushed.
+            writer.write(content, encoding ?? "utf8");
+            writer.write("\n", "utf8", settle);
+        });
+    };
+    const dispose = () => {
+        return new Promise((resolve, reject) => {
+            writer.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    };
+    return {
+        write,
+        writer,
+        dispose,
+        [Symbol.asyncDispose]: dispose,
+    };
+}
+//# sourceMappingURL=writer.js.map

package/out/lib/io/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../lib/io/writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAoB,iBAAiB,EAAiB,MAAM,SAAS,CAAA;AA6B5E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAkB;IACrD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAA;IAE1C,MAAM,KAAK,GAAsB,CAAC,OAAY,EAAE,QAAyB,EAAE,EAAE;QAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtC,MAAM,MAAM,GAAG,CAAC,KAA+B,EAAQ,EAAE;gBACxD,IAAI,KAAK,EAAE,CAAC;oBACX,MAAM,CAAC,KAAK,CAAC,CAAA;oBAEb,OAAM;gBACP,CAAC;gBAED,OAAO,EAAE,CAAA;YACV,CAAC,CAAA;YAED,uFAAuF;YACvF,qFAAqF;YACrF,uFAAuF;YACvF,wFAAwF;YACxF,oBAAoB;YACpB,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,CAAA;YACzC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QACnC,CAAC,CAAC,CAAA;IACH,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,GAAG,EAAE;QACpB,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC5C,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACtB,IAAI,KAAK,EAAE,CAAC;oBACX,MAAM,CAAC,KAAK,CAAC,CAAA;oBAEb,OAAM;gBACP,CAAC;gBAED,OAAO,EAAE,CAAA;YACV,CAAC,CAAC,CAAA;QACH,CAAC,CAAC,CAAA;IACH,CAAC,CAAA;IAED,OAAO;QACN,KAAK;QACL,MAAM;QACN,OAAO;QACP,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO;KAC9B,CAAA;AACF,CAAC"}