spliterator 6.2.0 → 6.3.1

package/out/lib/AsyncSpliterator.d.ts

@@ -1,227 +0,0 @@
-/**
- * @copyright Sister Software
- * @license MIT
- * @author Teffen Ellis, et al.
- */
-import { ReadableStream, type ReadableWritablePair, type StreamPipeOptions } from "stream/web";
-import { type CharacterSequenceInput } from "./CharacterSequence.js";
-import { type AsManyWorkersOptions } from "./segment-workers.js";
-import { type SegmentOptions } from "./segments.js";
-import type { AsyncChunkIterator, AsyncDataResource, ByteRange } from "./shared.js";
-/**
- * Initialization options for creating a spliterator.
- */
-export interface SpliteratorInit {
-    /**
-     * The character to delimit by. Typically a newline or comma.
-     *
-     * @default Delimiters.LineFeed
-     */
-    delimiter?: CharacterSequenceInput;
-    /**
-     * The byte offset to start reading from.
-     *
-     * This is an advanced option that is not typically used.
-     *
-     * @default 0
-     */
-    position?: number;
-    /**
-     * Whether to drop empty slices, so a run of repeated delimiters yields nothing between them.
-     *
-     * Setting this to `false` emits those empties and matches the behavior of `String.prototype.split`.
-     *
-     * @default true
-     */
-    skipEmpty?: boolean;
-    /**
-     * Count of skipped matches before emitting a data.
-     *
-     * @default 0
-     */
-    drop?: number;
-    /**
-     * The maximum number of data slices to yield.
-     *
-     * Useful for limiting the number of emitted slices, i.e. lines in a file.
-     *
-     * Note that skipped slices are not counted towards the limit.
-     *
-     * @default Infinity
-     */
-    take?: number;
-    /**
-     * Whether to treat double-quoted regions as opaque: a delimiter inside `"…"` does not split, and the emitted slices
-     * keep their quotes verbatim. Quote _stripping_ and `""` unescaping are the consumer's concern —
-     * {@linkcode CSVSpliterator} does both when this flag is set.
-     *
-     * The asynchronous engine requires a single-byte delimiter for this mode (every {@linkcode Delimiters} entry
-     * qualifies) — a multi-byte delimiter straddling a chunk boundary cannot be rescanned without re-toggling quote
-     * state.
-     *
-     * @default false
-     */
-    enableQuoteHandling?: boolean;
-    /**
-     * Whether to treat a carriage return immediately preceding a delimiter as part of the delimiter — i.e. CRLF
-     * normalization when splitting on `\n`, matching `node:readline`'s `crlfDelay: Infinity`. Only a `\r` directly before
-     * an actual delimiter match is trimmed; a trailing `\r` at end-of-input is preserved.
-     *
-     * {@linkcode CSVSpliterator} defaults this to `true` for row splitting (RFC 4180 mandates CRLF row terminators);
-     * everywhere else the default is `false`.
-     *
-     * @default false
-     */
-    crlf?: boolean;
-    /**
-     * Whether to emit debug information.
-     */
-    debug?: boolean;
-}
-/**
- * Initialization options for creating an asynchronous spliterator.
- */
-export interface AsyncSpliteratorInit extends SpliteratorInit {
-    /**
-     * The buffer chunk size to read from the file, i.e. the high-water mark for the file read operation.
-     *
-     * @default BlockSize * 16
-     * @minimum The delimiter byte length * 4 or block size of the file system. Whichever is greater.
-     * @maximum The byte length of the file.
-     */
-    highWaterMark?: number;
-    /**
-     * Whether to automatically dispose of the source once the iterator is done.
-     *
-     * @default true
-     */
-    autoDispose?: boolean;
-}
-/**
- * An asynchronous spliterator for reading delimited byte streams.
- *
- * ```ts
- * import { AsyncSpliterator } from "spliterator"
- *
- * const file = await AsyncSpliterator.from("data.csv")
- *
- * for await (const line of file) {
- * 	console.log(line)
- * }
- * ```
- *
- * @see {@linkcode Spliterator} for the synchronous version.
- */
-export declare class AsyncSpliterator<R extends Uint8Array | DataView | ArrayBuffer = Uint8Array> implements AsyncIterableIterator<R>, AsyncDisposable {
-    #private;
-    /**
-     * Create a new delimited generator from an asynchronous byte stream.
-     *
-     * @param source - The data resource to read from.
-     * @param init - The initialization options for the generator.
-     *
-     * @returns A new generator instance, yielding byte ranges.
-     */
-    static from(source: AsyncChunkIterator, init?: AsyncSpliteratorInit): AsyncSpliterator;
-    /**
-     * Create a new delimited generator from a resource such as a file handle or URL.
-     *
-     * @param source - The data resource to read from.
-     * @param init - The initialization options for the generator.
-     *
-     * @returns A new generator instance, yielding byte ranges.
-     */
-    static from(source: AsyncDataResource, init?: AsyncSpliteratorInit): Promise<AsyncSpliterator>;
-    /**
-     * Create a new delimited generator from a resource such as a file handle, URL, or byte stream.
-     *
-     * @param source - The data resource to read from.
-     * @param init - The initialization options for the generator.
-     *
-     * @returns A new generator instance, yielding byte ranges.
-     */
-    static from(source: AsyncDataResource | AsyncChunkIterator, init?: AsyncSpliteratorInit): AsyncSpliterator | Promise<AsyncSpliterator>;
-    /**
-     * Dispose of the spliterator, closing the file handle if necessary.
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    /**
-     * Create a new delimited generator from a data resource.
-     */
-    static toTransformStream(init: SpliteratorInit): TransformStream<AsyncChunkIterator, Uint8Array>;
-    /**
-     * Create a new delimited generator from an asynchronous byte stream.
-     *
-     * @param source - The file to read from.
-     * @param init - The initialization options for the generator.
-     * @see {@linkcode AsyncSpliterator.from} to create a new generator from a data resource.
-     */
-    constructor(source: AsyncChunkIterator, init?: AsyncSpliteratorInit);
-    next(): Promise<IteratorResult<R>>;
-    /**
-     * Collect all the byte ranges from the file.
-     *
-     * **This method will read the entire file into memory.**
-     */
-    toArray(): Promise<R[]>;
-    /**
-     * Collect all the byte ranges from the file as a string.
-     *
-     * **This method will read the entire file into memory.**
-     */
-    toDecodedArray(decoder?: import("node:util").TextDecoder): Promise<string[]>;
-    /**
-     * Wraps the spliterator in a readable stream.
-     *
-     * This is useful for piping the spliterator to other streams.
-     *
-     * @returns A readable stream of byte ranges.
-     */
-    toReadableStream(): ReadableStream<R>;
-    /**
-     * Pipes the spliterator to a writable stream.
-     *
-     * ```ts
-     * const spliterator = await AsyncSpliterator.from("data.csv")
-     *
-     * const textStream = spliterator.pipeTo(new TextDecoderStream())
-     * ```
-     *
-     * @see {@linkcode toReadableStream} to first convert the spliterator to a readable stream.
-     */
-    pipeThrough<T>(transform: ReadableWritablePair<T, R>, options?: StreamPipeOptions): ReadableStream<T>;
-    /**
-     * Iterate over the byte ranges in the file, yielding each range. between delimiters.
-     */
-    [Symbol.asyncIterator](): this;
-    return(): Promise<IteratorReturnResult<undefined>>;
-    /**
-     * Compute delimiter-aligned `[start, end)` byte ranges dividing `source` into up to `concurrency` segments. The
-     * boundary primitive for parallel parsing — hand each range to a worker (with its own handle). See
-     * {@linkcode asManyWorkers} for the turnkey worker version.
-     */
-    static segments(source: AsyncDataResource, options: SegmentOptions): Promise<ByteRange[]>;
-    /**
-     * Split `source` into delimiter-aligned segments and return one {@linkcode AsyncSpliterator} per segment. All share
-     * the event loop (no worker threads) — for moderate jobs or to overlap I/O. Returns at most `concurrency` instances.
-     *
-     * @param source - The data resource to read from.
-     * @param options - Delimiter, desired concurrency, and optional probe size.
-     *
-     * @returns One `AsyncSpliterator` per non-empty segment, possibly fewer than `concurrency`.
-     */
-    static asMany(source: AsyncDataResource, options: SegmentOptions): Promise<AsyncSpliterator[]>;
-    /**
-     * Parse `source` across worker threads. Each worker owns a handle to a delimiter-aligned segment, runs the `worker`
-     * handler module per record, and streams results back to the main thread as one merged async iterator — for a
-     * single-thread writer. Results interleave across segments.
-     *
-     * The handler returns a value (structured-cloned back), a `Uint8Array` (transferred zero-copy), or `undefined` (the
-     * record is skipped). The handler module's top-level code runs once per worker — load models/handles there.
-     *
-     * @param source A file path or URL (file handles cannot cross threads → `TypeError` otherwise).
-     * @param options Handler module, delimiter, concurrency, and batching/backpressure tuning.
-     */
-    static asManyWorkers<R = unknown>(source: AsyncDataResource, options: AsManyWorkersOptions): AsyncIterableIterator<R>;
-}
-//# sourceMappingURL=AsyncSpliterator.d.ts.map

package/out/lib/AsyncSpliterator.d.ts.map

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