spliterator 1.5.0

package/README.md

@@ -0,0 +1,119 @@
+# Ribbon 🎀
+
+Ribbon makes newline-delimited files easy to work with.
+
+Let's say you have a huge newline-delimited JSON file that can't fit into memory.
+
+```js
+{"name": "Jessie", "age": 30}
+{"name": "Kelly", "age": 40}
+{"name": "Loren", "age": 50}
+// Several hundred thousand more lines...
+```
+
+Ribbon can help you read it line-by-line:
+
+```ts
+import { JSONSpliterator } from "spliterator"
+
+interface Person {
+	name: string
+	age: number
+}
+
+const reader = JSONSpliterator.fromAsync("example.jsonl")
+
+for await (const line of reader) {
+	console.log(line) // {"name": "Alice", "age": 30}, etc.
+}
+```
+
+[![NPM Version](https://img.shields.io/npm/v/%40sister.software%2Fribbon)](https://www.npmjs.com/package/spliterator)
+
+# Installation
+
+```bash
+yarn add spliterator
+# or
+npm install spliterator
+```
+
+# Usage
+
+## Character-delimited files
+
+While Ribbon supports any delimited byte stream, it's particularly useful for character-delimited content such as comma-separated values (CSV), tab-separated values (TSV) – or any other delimiter you can think of.
+
+```csv
+Full Name, Occupation, Age
+Morgan, Developer, 30
+Nataly, Designer, 40
+Orlando, Manager, 50
+```
+
+```ts
+import { CSVSpliterator } from "spliterator"
+
+const reader = CSVSpliterator.fromAsync("people.csv")
+
+for await (const columns of reader) {
+	console.log(columns) // ["Full Name", "Occupation", "Age"], ["Morgan", "Developer", 30], etc.
+}
+```
+
+CSV files can also be emitted as objects with headers as keys, with some quality-of-life features, such as normalizing property keys:
+
+```ts
+import { CSVSpliterator } from "spliterator"
+
+interface Person {
+	full_name: string
+	occupation: string
+	age: number
+}
+
+const reader = CSVSpliterator.fromAsync<Person>("people.csv", { mode: "object" })
+
+for await (const columns of reader) {
+	console.log(columns) // { full_name: "Morgan", occupation: "Developer", age: 30 }, etc.
+}
+```
+
+## Advanced usage
+
+Ribbon is designed to be simple to use, but also flexible and powerful.
+For more advanced use cases, check out our tests in the `test` directory, or our fully-annotated source code.
+
+### Reading from a stream
+
+All Ribbon generators implement the `Generator` and `AsyncGenerator` interfaces, so you can use them in `for...of` and `for await...of` loops, as well the web-native [ReadableStreams](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream), so you can use them in `for await...of` loops, as well as piping them through transformations to avoid nested and partially materialized streams.
+
+```ts
+import { JSONSpliterator } from "spliterator"
+
+const people = [
+	{ name: "Alice", age: 30 },
+	{ name: "Bob", age: 40 },
+	{ name: "Charlie", age: 50 },
+]
+
+const generator = JSONSpliterator.from(people.map(JSON.stringify).join("\n"))
+const stream = ReadableStream.from(generator)
+
+for await (const line of stream) {
+	console.log(line) // {"name": "Alice", "age": 30}, etc.
+}
+```
+
+### Custom generators
+
+While Ribbon includes premade exports for most use-cases, custom generators can be created via `DelimitedGenerator`. This class is a low-level interface that allows you to create your own generators for any kind of delimited content.
+
+# License
+
+Ribbon is licensed under the AGPL-3.0 license. Generally,
+this means that you can use the software for free, but you must share
+any modifications you make to the software.
+
+For more information on commercial usage licensing, please contact us at
+`hello@sister.software`

package/out/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "./lib/BufferController.js";
+export * from "./lib/casing.js";
+export * from "./lib/CharacterSequence.js";
+export * from "./lib/CompositeDataView.js";
+export * from "./lib/CSVSpliterator.js";
+export * from "./lib/DelimitedChunkReader.js";
+export * from "./lib/DelimiterTransformer.js";
+export * from "./lib/IndexQueue.js";
+export * from "./lib/JSONSpliterator.js";
+export * from "./lib/shared.js";
+export * from "./lib/SlidingWindow.js";
+export * from "./lib/Spliterator.js";
+export * from "./lib/take.js";
+export * from "./lib/TextSpliterator.js";
+export * from "./lib/writer.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,qBAAqB,CAAA;AACnC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA"}

package/out/index.js

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "./lib/BufferController.js";
+export * from "./lib/casing.js";
+export * from "./lib/CharacterSequence.js";
+export * from "./lib/CompositeDataView.js";
+export * from "./lib/CSVSpliterator.js";
+export * from "./lib/DelimitedChunkReader.js";
+export * from "./lib/DelimiterTransformer.js";
+export * from "./lib/IndexQueue.js";
+export * from "./lib/JSONSpliterator.js";
+export * from "./lib/shared.js";
+export * from "./lib/SlidingWindow.js";
+export * from "./lib/Spliterator.js";
+export * from "./lib/take.js";
+export * from "./lib/TextSpliterator.js";
+export * from "./lib/writer.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,qBAAqB,CAAA;AACnC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA"}

package/out/lib/AsyncSpliterator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { CharacterSequenceInput } from "./CharacterSequence.js";
+import { AsyncDataResource, type FileResourceLike } from "./shared.js";
+/**
+ * Initialization options for creating a spliterator.
+ */
+export interface SpliteratorInit {
+    /**
+     * The character to delimit by. Typically a newline or comma.
+     */
+    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 emit repeated delimiters as empty buffers.
+     *
+     * Setting this to `false` 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 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 close the file handle after completion.
+     *
+     * @default true
+     */
+    autoClose?: 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 implements AsyncIterableIterator<Uint8Array>, AsyncDisposable {
+    #private;
+    /**
+     * Create a new delimited generator from a data resource.
+     *
+     * Unlike the constructor, this method can be used to create a generator from a file path or URL.
+     *
+     * @param source - The data resource to read from.
+     * @param init - The initialization options for the generator.
+     */
+    static from(source: AsyncDataResource, init?: AsyncSpliteratorInit): Promise<AsyncSpliterator>;
+    /**
+     * Dispose of the spliterator, closing the file handle if necessary.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Create a new delimited generator from a file handle.
+     *
+     * @param file - 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(file: FileResourceLike, init?: AsyncSpliteratorInit);
+    next(): Promise<IteratorResult<Uint8Array>>;
+    /**
+     * Collect all the byte ranges from the file.
+     *
+     * **This method will read the entire file into memory.**
+     */
+    toArray(): Promise<Uint8Array[]>;
+    /**
+     * Collect all the byte ranges from the file as a string.
+     *
+     * **This method will read the entire file into memory.**
+     */
+    toDecodedArray(decoder?: import("util").TextDecoder): Promise<string[]>;
+    [Symbol.asyncIterator](): this;
+    return(): Promise<IteratorReturnResult<undefined>>;
+}
+//# sourceMappingURL=AsyncSpliterator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncSpliterator.d.ts","sourceRoot":"","sources":["../../lib/AsyncSpliterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAqB,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAElF,OAAO,EAEN,iBAAiB,EAGjB,KAAK,gBAAgB,EAErB,MAAM,aAAa,CAAA;AAEpB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAA;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC5D;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,qBAAqB,CAAC,UAAU,CAAC,EAAE,eAAe;;IAG1F;;;;;;;OAOG;WACU,IAAI,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,GAAE,oBAAyB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAaxG;;OAEG;IACU,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IASnD;;;;;;OAMG;gBAES,IAAI,EAAE,gBAAgB,EAAE,IAAI,GAAE,oBAAyB;IA+RtD,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAgCxD;;;;OAIG;IACI,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIvC;;;;OAIG;IACI,cAAc,CAAC,OAAO,6BAAoB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI9D,CAAC,MAAM,CAAC,aAAa,CAAC;IAItB,MAAM,IAAI,OAAO,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;CAGzD"}

package/out/lib/AsyncSpliterator.js

@@ -0,0 +1,332 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { BufferController } from "./BufferController.js";
+import { CharacterSequence } from "./CharacterSequence.js";
+import { IndexQueue } from "./IndexQueue.js";
+import { applyReaderPolyfill, isFileResourceLike, } from "./shared.js";
+/**
+ * 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 class AsyncSpliterator {
+    //#region Lifecycle
+    /**
+     * Create a new delimited generator from a data resource.
+     *
+     * Unlike the constructor, this method can be used to create a generator from a file path or URL.
+     *
+     * @param source - The data resource to read from.
+     * @param init - The initialization options for the generator.
+     */
+    static async from(source, init = {}) {
+        let file;
+        if (isFileResourceLike(source)) {
+            file = source;
+        }
+        else {
+            const { NodeFileResource } = await import("spliterator/node/fs");
+            file = await NodeFileResource.open(source);
+        }
+        return new AsyncSpliterator(file, init);
+    }
+    /**
+     * Dispose of the spliterator, closing the file handle if necessary.
+     */
+    async [Symbol.asyncDispose]() {
+        this.#indices.clear();
+        this.#controller.clear();
+        if (this.#autoClose) {
+            await this.#file[Symbol.asyncDispose]?.();
+        }
+    }
+    /**
+     * Create a new delimited generator from a file handle.
+     *
+     * @param file - 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(file, init = {}) {
+        applyReaderPolyfill(file);
+        this.#file = file;
+        this.#autoClose = init.autoClose ?? false;
+        this.#needle = new CharacterSequence(init.delimiter);
+        this.#readPosition = init.position ?? 0;
+        this.#totalByteSize = file.size;
+        this.#yieldByteEstimate = this.#totalByteSize - this.#readPosition;
+        this.#highWaterMark = Math.max(this.#needle.length * 4, init.highWaterMark ?? 4096);
+        this.#yieldDropCount = Math.max(0, init.drop ?? 0);
+        this.#yieldStopCount = Math.max(init.take ?? Infinity, 0) + this.#yieldDropCount;
+        this.#skipEmpty = init.skipEmpty ?? true;
+        this.#controller = new BufferController({
+            initialBufferSize: Math.max(this.#needle.length * 4, this.#highWaterMark),
+        });
+        this.#debug = init.debug ?? false;
+        this.#log = this.#debug ? console.debug.bind(console) : () => void 0;
+    }
+    //#endregion
+    //#region Private Properties
+    /**
+     * The file to read from.
+     */
+    #file;
+    /**
+     * Whether to close the file handle when the iterator is completed or disposed.
+     */
+    #autoClose;
+    /**
+     * A queue of index tuples marking the start and end of delimiter positions.
+     *
+     * Note that indices are relative to the buffer, not the file.
+     *
+     * This means that the start index is always 0, and the end index is the byte length of the
+     * buffer.
+     */
+    #indices = new IndexQueue();
+    /**
+     * The byte sequence to search for, i.e. an encoded delimiter.
+     */
+    #needle;
+    /**
+     * The buffer containing the current chunks of data. This will be resized as needed to accommodate
+     * the file read operation.
+     */
+    #controller;
+    /**
+     * The total byte size of the file.
+     */
+    #totalByteSize;
+    /**
+     * The total number of bytes we expect to yield.
+     *
+     * We use this to ensure that we don't miss any data when the file is read in chunks.
+     */
+    #yieldByteEstimate;
+    /**
+     * How many yields to skip.
+     */
+    #yieldDropCount;
+    /**
+     * How many yields to allow before stopping.
+     */
+    #yieldStopCount;
+    /**
+     * Whether to skip empty yields.
+     */
+    #skipEmpty;
+    /**
+     * The high water mark for the buffer.
+     *
+     * This defines the size of each read operation, as well as the total size of indices to keep in
+     * memory.
+     */
+    #highWaterMark;
+    /**
+     * The total number of bytes we've yielded.
+     */
+    #yieldedByteLength = 0;
+    /**
+     * The total number of yields.
+     */
+    #yieldCount = 0;
+    /**
+     * The current byte index to perform read operations from.
+     */
+    #readPosition;
+    /**
+     * The last byte range seen while draining the buffer.
+     */
+    #lastByteRangeSeen;
+    /**
+     * Whether to output debug information.
+     */
+    #debug;
+    /**
+     * Whether the iterator is done.
+     */
+    #done = false;
+    //#endregion
+    //#region Private Methods
+    #log;
+    /**
+     * Find and enqueue delimiter positions.
+     */
+    #search() {
+        const lastByteRange = this.#indices.peekLast();
+        let searchCursor = lastByteRange ? lastByteRange[1] + this.#needle.length : 0;
+        while (searchCursor <= this.#controller.bytesWritten) {
+            const delimiterIndex = this.#needle.search(this.#controller.bytes, searchCursor);
+            if (delimiterIndex === -1) {
+                this.#log(`No viable byte range found in buffer. Breaking.`);
+                break;
+            }
+            this.#log("Found byte range", [searchCursor, delimiterIndex]);
+            this.#indices.enqueue([searchCursor, delimiterIndex]);
+            searchCursor = delimiterIndex + this.#needle.length;
+        }
+    }
+    /**
+     * Read a chunk of data from the file.
+     */
+    async #read() {
+        // We're extra careful here to ensure that we don't read past the end of the file.
+        // And because `file.read` doesn't expose the number of bytes read,
+        // we keep track of this ourselves.
+        const nextReadLength = Math.min(this.#highWaterMark, this.#totalByteSize - this.#readPosition);
+        // Offset in this context means the byte offset to begin writing to the buffer.
+        const offset = this.#controller.bytesWritten;
+        // Before reading we grow the buffer to ensure that we have enough space.
+        const nextBufferSize = Math.max(this.#controller.byteLengthMinimum, offset + nextReadLength);
+        this.#controller.grow(nextBufferSize);
+        this.#log("Before read", { cursor: this.#readPosition, nextReadLength, nextBufferSize, offset });
+        await this.#file.read({
+            buffer: this.#controller.bytes,
+            offset,
+            position: this.#readPosition,
+            length: nextReadLength,
+        });
+        this.#controller.bytesWritten += nextReadLength;
+        // this.#log(
+        // 	"Inspecting buffer",
+        // 	debugAsVisibleCharacters(this.#controller.bytes.subarray(0, this.#controller.bytesWritten))
+        // )
+        this.#readPosition += nextReadLength;
+    }
+    /**
+     * Fill the buffer with data and search for delimiters.
+     */
+    async #fill() {
+        if (this.#readPosition === this.#totalByteSize) {
+            this.#log("Reached end of file. Preparing to finalize.");
+            // There's a few special cases we could get this far and not have drained the buffer.
+            const lastByteRange = this.#lastByteRangeSeen;
+            if (lastByteRange) {
+                const lastByteIndex = lastByteRange[1];
+                // There's a special case where the last delimiter is at the end of the *file*.
+                if (lastByteIndex < this.#controller.bytesWritten) {
+                    // We need to determine if we're at the end of the *file* and there's no delimiter.
+                    const possibleDelimiterIndex = this.#needle.search(this.#controller.bytes, this.#controller.bytesWritten - this.#needle.length);
+                    if (possibleDelimiterIndex !== -1) {
+                        this.#log("Inserted byte range at the last delimiter", [
+                            possibleDelimiterIndex,
+                            this.#controller.bytesWritten,
+                        ]);
+                        // We found a delimiter at the end of the file, so we enqueue the byte range.
+                        this.#indices.enqueue([possibleDelimiterIndex + this.#needle.length, this.#controller.bytesWritten]);
+                    }
+                    else {
+                        this.#log("Inserted byte range at the last byte", [lastByteIndex, this.#controller.bytesWritten]);
+                        // The file didn't end with a delimiter, so we just enqueue the last byte range.
+                        this.#indices.enqueue([lastByteIndex + this.#needle.length, this.#controller.bytesWritten]);
+                    }
+                }
+                else {
+                    this.#log(`Weird situation. We're at the end of the file, but the last byte range ${lastByteIndex} is greater than the buffer length ${this.#controller.bytesWritten}.`);
+                }
+            }
+            else if (this.#yieldCount === 0) {
+                // We didn't find any delimiters in the file, so we just enqueue the whole buffer.
+                this.#indices.enqueue([0, this.#controller.bytesWritten]);
+            }
+            this.#done = true;
+            return;
+        }
+        // We're effectively done with that window of the buffer.
+        // So we can compress it to save memory.
+        const nextBufferStart = this.#lastByteRangeSeen ? this.#lastByteRangeSeen[1] + this.#needle.length : 0;
+        this.#log("Compressing buffer", { nextBufferStart });
+        this.#controller.compress(nextBufferStart);
+        while (this.#readPosition < this.#totalByteSize && this.#indices.byteLength < this.#highWaterMark) {
+            await this.#read();
+            this.#search();
+        }
+    }
+    async #finalize() {
+        if (this.#debug) {
+            /**
+             * The total number of bytes we expect to be omitted from the buffer. This is derived from the
+             * number of of yields and the length of the delimiter.
+             */
+            const expectedYieldedDelimitedBytes = (this.#yieldCount - 1) * this.#needle.length;
+            const omittedBytes = this.#yieldByteEstimate - (this.#yieldedByteLength + expectedYieldedDelimitedBytes);
+            this.#log({
+                totalByteSize: this.#totalByteSize,
+                readPosition: this.#readPosition,
+                yieldByteEstimate: this.#yieldByteEstimate,
+                yieldedByteLength: this.#yieldedByteLength,
+                yieldCount: this.#yieldCount,
+                expectedYieldedDelimitedBytes,
+                omittedBytes,
+            });
+        }
+        if (this.#autoClose) {
+            await this.#file[Symbol.asyncDispose]?.();
+        }
+        return {
+            done: true,
+            value: undefined,
+        };
+    }
+    //#endregion
+    //#region Iterator Methods
+    async next() {
+        if (this.#done || this.#yieldCount >= this.#yieldStopCount)
+            return this.#finalize();
+        if (this.#indices.size === 0) {
+            await this.#fill();
+        }
+        const currentByteRange = this.#indices.dequeue();
+        this.#lastByteRangeSeen = currentByteRange;
+        const [start, end] = currentByteRange;
+        const slice = this.#controller.subarray(start, end);
+        if (slice.length === 0 && this.#skipEmpty) {
+            return this.next();
+        }
+        this.#yieldCount++;
+        if (this.#yieldCount <= this.#yieldDropCount) {
+            return this.next();
+        }
+        this.#yieldedByteLength += end - start;
+        return {
+            value: slice,
+            done: false,
+        };
+    }
+    /**
+     * Collect all the byte ranges from the file.
+     *
+     * **This method will read the entire file into memory.**
+     */
+    toArray() {
+        return Array.fromAsync(this);
+    }
+    /**
+     * Collect all the byte ranges from the file as a string.
+     *
+     * **This method will read the entire file into memory.**
+     */
+    toDecodedArray(decoder = new TextDecoder()) {
+        return Array.fromAsync(this, (bytes) => decoder.decode(bytes));
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    return() {
+        return this.#finalize();
+    }
+}
+//# sourceMappingURL=AsyncSpliterator.js.map

package/out/lib/AsyncSpliterator.js.map

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