spliterator 1.5.0

package/out/lib/Spliterator.js

@@ -0,0 +1,238 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { AsyncSpliterator } from "./AsyncSpliterator.js";
+import { CharacterSequence, normalizeCharacterInput } from "./CharacterSequence.js";
+import { IndexQueue } from "./IndexQueue.js";
+export { AsyncSpliterator };
+/**
+ * A byte stream delimiting iterator.
+ */
+export class Spliterator {
+    //#region Lifecycle
+    /**
+     * Create a spliterator from an asynchronous resource such as a file.
+     *
+     * This is an alias for `AsyncSpliterator.from`.
+     *
+     * @param source - The data resource to read from.
+     * @param init - The initialization options for the generator.
+     * @see {@linkcode AsyncSpliterator} for usage.
+     */
+    static fromAsync = AsyncSpliterator.from;
+    /**
+     * Create a spliterator from an iterable resource such as a buffer, array, or string.
+     *
+     * @param source - The data resource to read from.
+     * @param init - The initialization options for the generator.
+     */
+    static from(source, init = {}) {
+        return new Spliterator(normalizeCharacterInput(source), init);
+    }
+    /**
+     * Dispose of the spliterator, closing the file handle if necessary.
+     */
+    [Symbol.dispose]() {
+        this.#indices.clear();
+    }
+    constructor(source, init = {}) {
+        this.#source = source;
+        this.#needle = new CharacterSequence(init.delimiter);
+        this.#readPosition = init.position ?? 0;
+        this.#highWaterMark = Math.max(this.#needle.length * 4, 4096);
+        this.#yieldDropCount = Math.max(0, init.drop ?? 0);
+        this.#yieldStopCount = Math.max(init.take ?? Infinity, 0) + this.#yieldDropCount;
+        this.#yieldByteEstimate = this.#source.byteLength - this.#readPosition;
+        this.#skipEmpty = init.skipEmpty ?? true;
+        this.#debug = init.debug ?? false;
+        this.#log = this.#debug ? console.debug.bind(console) : () => void 0;
+    }
+    //#endregion
+    //#region Private Properties
+    /**
+     * The byte source to read from.
+     */
+    #source;
+    /**
+     * 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;
+    /**
+     * How many yields to skip.
+     */
+    #yieldDropCount;
+    /**
+     * How many yields to allow before stopping.
+     */
+    #yieldStopCount;
+    /**
+     * The total number of bytes we expect to yield.
+     *
+     * We use this to ensure that we don't miss any data as we read through the buffer.
+     */
+    #yieldByteEstimate;
+    /**
+     * Whether to skip empty yields.
+     */
+    #skipEmpty;
+    /**
+     * The high water mark for the buffer.
+     *
+     * This defines 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;
+    #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.#source.byteLength,
+                readPosition: this.#readPosition,
+                yieldByteEstimate: this.#yieldByteEstimate,
+                yieldedByteLength: this.#yieldedByteLength,
+                yieldCount: this.#yieldCount,
+                expectedYieldedDelimitedBytes,
+                omittedBytes,
+            });
+        }
+        return {
+            done: true,
+            value: undefined,
+        };
+    }
+    /**
+     * Fill the buffer with data and search for delimiters.
+     */
+    #fill() {
+        const sourceByteLength = this.#source.byteLength;
+        if (this.#readPosition === sourceByteLength) {
+            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 < sourceByteLength) {
+                    // We need to determine if we're at the end of the *file* and there's no delimiter.
+                    const possibleDelimiterIndex = this.#needle.search(this.#source, sourceByteLength - this.#needle.length);
+                    if (possibleDelimiterIndex !== -1) {
+                        this.#log("Inserted byte range at the last delimiter", [possibleDelimiterIndex, sourceByteLength]);
+                        // We found a delimiter at the end of the file, so we enqueue the byte range.
+                        this.#indices.enqueue([possibleDelimiterIndex + this.#needle.length, sourceByteLength]);
+                    }
+                    else {
+                        this.#log("Inserted byte range at the last byte", [lastByteIndex, sourceByteLength]);
+                        // The file didn't end with a delimiter, so we just enqueue the last byte range.
+                        this.#indices.enqueue([lastByteIndex + this.#needle.length, sourceByteLength]);
+                    }
+                }
+                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 ${sourceByteLength}.`);
+                }
+            }
+            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, sourceByteLength]);
+            }
+            this.#done = true;
+            return;
+        }
+        while (this.#readPosition < sourceByteLength && this.#indices.byteLength < this.#highWaterMark) {
+            // Unlike the async version, we can keep reading until our indices match the high water mark.
+            const delimiterIndex = this.#needle.search(this.#source, this.#readPosition);
+            if (delimiterIndex === -1) {
+                this.#log(`No viable byte range found in buffer. Breaking.`);
+                break;
+            }
+            this.#log("Found byte range", [this.#readPosition, delimiterIndex]);
+            this.#indices.enqueue([this.#readPosition, delimiterIndex]);
+            this.#readPosition = delimiterIndex + this.#needle.length;
+        }
+    }
+    //#endregion
+    //#region Iterator Methods
+    /**
+     * Read the next byte range from the source.
+     */
+    next() {
+        if (this.#done || this.#yieldCount >= this.#yieldStopCount)
+            return this.#finalize();
+        if (this.#indices.size === 0) {
+            this.#fill();
+        }
+        const currentByteRange = this.#indices.dequeue();
+        this.#lastByteRangeSeen = currentByteRange;
+        const [start, end] = currentByteRange;
+        const slice = this.#source.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.
+     */
+    toArray() {
+        return Array.from(this);
+    }
+    /**
+     * Collect all the byte ranges from the file as a string.
+     */
+    toDecodedArray(decoder = new TextDecoder()) {
+        return Array.from(this, (bytes) => decoder.decode(bytes));
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+//# sourceMappingURL=Spliterator.js.map

package/out/lib/Spliterator.js.map

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

package/out/lib/TextSpliterator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { CharacterSequenceInput } from "./CharacterSequence.js";
+import { AsyncDataResource } from "./shared.js";
+import { AsyncSpliteratorInit, SpliteratorInit } from "./Spliterator.js";
+export interface TextSpliteratorInit {
+    /**
+     * The encoding to use when decoding the data.
+     *
+     * @default "utf-8"
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder/TextDecoder
+     */
+    encoding?: string;
+    /**
+     * Whether to throw an error when encountering invalid data, or to swap it with a replacement
+     * character.
+     */
+    fatal?: boolean;
+    /**
+     * Whether to ignore BOM characters.
+     */
+    ignoreBOM?: boolean;
+}
+export declare abstract class TextSpliterator {
+    constructor();
+    /**
+     * @yields Each row as a string.
+     */
+    static from(source: CharacterSequenceInput, { encoding, fatal, ignoreBOM, ...options }?: TextSpliteratorInit & SpliteratorInit): Generator<string>;
+    /**
+     * Given a byte array or string, yield each row as an array of columns.
+     *
+     * @yields Each row as an array of columns.
+     */
+    static fromAsync(source: AsyncDataResource, { encoding, fatal, ignoreBOM, ...options }?: TextSpliteratorInit & AsyncSpliteratorInit): AsyncGenerator<string>;
+}
+//# sourceMappingURL=TextSpliterator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TextSpliterator.d.ts","sourceRoot":"","sources":["../../lib/TextSpliterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAe,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAErF,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,8BAAsB,eAAe;;IAKpC;;OAEG;IACH,MAAM,CAAE,IAAI,CACX,MAAM,EAAE,sBAAsB,EAC9B,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,GAAE,mBAAmB,GAAG,eAAoB,GACpF,SAAS,CAAC,MAAM,CAAC;IAwBpB;;;;OAIG;WACW,SAAS,CACtB,MAAM,EAAE,iBAAiB,EACzB,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,GAAE,mBAAmB,GAAG,oBAAyB,GACzF,cAAc,CAAC,MAAM,CAAC;CAsBzB"}

package/out/lib/TextSpliterator.js

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { Spliterator } from "./Spliterator.js";
+export class TextSpliterator {
+    constructor() {
+        throw new TypeError("Static class cannot be instantiated. Did you mean `TextSpliterator.from`?");
+    }
+    /**
+     * @yields Each row as a string.
+     */
+    static *from(source, { encoding, fatal, ignoreBOM, ...options } = {}) {
+        const decoder = new TextDecoder(encoding, { fatal, ignoreBOM });
+        let rowCursor = 0;
+        const spliterator = Spliterator.from(source, options);
+        for (const row of spliterator) {
+            let decoded;
+            try {
+                decoded = decoder.decode(row);
+            }
+            catch (parsedError) {
+                const error = SyntaxError(`Failed to decode data at row ${rowCursor}`);
+                error.cause = parsedError;
+                throw error;
+            }
+            yield decoded;
+            rowCursor++;
+        }
+    }
+    /**
+     * Given a byte array or string, yield each row as an array of columns.
+     *
+     * @yields Each row as an array of columns.
+     */
+    static async *fromAsync(source, { encoding, fatal, ignoreBOM, ...options } = {}) {
+        const decoder = new TextDecoder(encoding, { fatal, ignoreBOM });
+        let rowCursor = 0;
+        const spliterator = await Spliterator.fromAsync(source, options);
+        for await (const row of spliterator) {
+            let decoded;
+            try {
+                decoded = decoder.decode(row);
+            }
+            catch (parsedError) {
+                const error = SyntaxError(`Failed to decode data at row ${rowCursor}`);
+                error.cause = parsedError;
+                throw error;
+            }
+            yield decoded;
+            rowCursor++;
+        }
+    }
+}
+//# sourceMappingURL=TextSpliterator.js.map

package/out/lib/TextSpliterator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextSpliterator.js","sourceRoot":"","sources":["../../lib/TextSpliterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAwB,WAAW,EAAmB,MAAM,kBAAkB,CAAA;AAuBrF,MAAM,OAAgB,eAAe;IACpC;QACC,MAAM,IAAI,SAAS,CAAC,2EAA2E,CAAC,CAAA;IACjG,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,CAAC,IAAI,CACX,MAA8B,EAC9B,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,KAA4C,EAAE;QAEtF,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;QAC/D,IAAI,SAAS,GAAG,CAAC,CAAA;QAEjB,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAErD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,OAAe,CAAA;YAEnB,IAAI,CAAC;gBACJ,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC9B,CAAC;YAAC,OAAO,WAAW,EAAE,CAAC;gBACtB,MAAM,KAAK,GAAG,WAAW,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAA;gBACtE,KAAK,CAAC,KAAK,GAAG,WAAW,CAAA;gBAEzB,MAAM,KAAK,CAAA;YACZ,CAAC;YAED,MAAM,OAAO,CAAA;YAEb,SAAS,EAAE,CAAA;QACZ,CAAC;IACF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CACtB,MAAyB,EACzB,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,KAAiD,EAAE;QAE3F,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;QAC/D,IAAI,SAAS,GAAG,CAAC,CAAA;QACjB,MAAM,WAAW,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAEhE,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YACrC,IAAI,OAAe,CAAA;YAEnB,IAAI,CAAC;gBACJ,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC9B,CAAC;YAAC,OAAO,WAAW,EAAE,CAAC;gBACtB,MAAM,KAAK,GAAG,WAAW,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAA;gBACtE,KAAK,CAAC,KAAK,GAAG,WAAW,CAAA;gBAEzB,MAAM,KAAK,CAAA;YACZ,CAAC;YAED,MAAM,OAAO,CAAA;YAEb,SAAS,EAAE,CAAA;QACZ,CAAC;IACF,CAAC;CACD"}

package/out/lib/casing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { CamelCase, SnakeCase } from "type-fest";
+/**
+ * Converts a name to snake_case, unless the name is already in all caps.
+ */
+export declare function smartSnakeCase<T extends string>(name: T): T extends Uppercase<T> ? T : SnakeCase<T>;
+/**
+ * Converts a name to camelCase, unless the name is already in all caps.
+ */
+export declare function smartCamelCase<T extends string>(name: T): T extends Uppercase<T> ? T : CamelCase<T>;
+/**
+ * Predicate to determine if a given string is uniformly cased, i.e. all uppercase or all lowercase.
+ */
+export declare function isUniformlyCased(input: string | null): boolean;
+/**
+ * Capitalizes a string, unless the string is uniformly cased, or an email address.
+ */
+export declare function smartCapitalCase(input: string): string;
+/**
+ * Given an array of column names, normalize them to ensure they are unique and usable as object
+ * keys.
+ */
+export declare function normalizeColumnNames(columnHeaders: Iterable<string>): string[];
+//# sourceMappingURL=casing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"casing.d.ts","sourceRoot":"","sources":["../../lib/casing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErD;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAiBnG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAInG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAkB9E"}

package/out/lib/casing.js

@@ -0,0 +1,69 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { camelCase, capitalCase, snakeCase } from "change-case";
+/**
+ * Converts a name to snake_case, unless the name is already in all caps.
+ */
+export function smartSnakeCase(name) {
+    const normalizedName = name
+        // Remove periods after capital letters, e.g. "U.S.A." -> "USA"
+        .replace(/([A-Z])(\.+)/g, "$1")
+        .trim();
+    if (normalizedName.toUpperCase() === normalizedName) {
+        return name
+            // Replace all non-word characters with underscores...
+            .replace(/\W{1,}/g, "_")
+            // ...and then replace all sequences of underscores with a single underscore.
+            .replace(/_{2,}/g, "_");
+    }
+    return snakeCase(normalizedName);
+}
+/**
+ * Converts a name to camelCase, unless the name is already in all caps.
+ */
+export function smartCamelCase(name) {
+    if (name.toUpperCase() === name)
+        return name;
+    return camelCase(name);
+}
+/**
+ * Predicate to determine if a given string is uniformly cased, i.e. all uppercase or all lowercase.
+ */
+export function isUniformlyCased(input) {
+    return Boolean(input && (input === input.toUpperCase() || input === input.toLowerCase()));
+}
+/**
+ * Capitalizes a string, unless the string is uniformly cased, or an email address.
+ */
+export function smartCapitalCase(input) {
+    if (input.includes("@"))
+        return input;
+    if (isUniformlyCased(input))
+        return input;
+    return capitalCase(input);
+}
+/**
+ * Given an array of column names, normalize them to ensure they are unique and usable as object
+ * keys.
+ */
+export function normalizeColumnNames(columnHeaders) {
+    const columnInputCountMap = new Map();
+    const distinctColumns = new Set();
+    const keyableColumnNames = Iterator.from(columnHeaders).map(smartSnakeCase);
+    for (const columnHeader of keyableColumnNames) {
+        if (distinctColumns.has(columnHeader)) {
+            const headerCount = (columnInputCountMap.get(columnHeader) ?? 1) + 1;
+            columnInputCountMap.set(columnHeader, headerCount);
+            const uniqueColumnName = `${columnHeader}_${headerCount}`;
+            distinctColumns.add(uniqueColumnName);
+        }
+        else {
+            distinctColumns.add(columnHeader);
+        }
+    }
+    return Array.from(distinctColumns);
+}
+//# sourceMappingURL=casing.js.map

package/out/lib/casing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"casing.js","sourceRoot":"","sources":["../../lib/casing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAG/D;;GAEG;AACH,MAAM,UAAU,cAAc,CAAmB,IAAO;IACvD,MAAM,cAAc,GAAG,IAAI;QAC1B,+DAA+D;SAC9D,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC;SAC9B,IAAI,EAAE,CAAA;IAER,IAAI,cAAc,CAAC,WAAW,EAAE,KAAK,cAAc,EAAE,CAAC;QACrD,OACC,IAAI;YACH,sDAAsD;aACrD,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;YACxB,6EAA6E;aAC5E,OAAO,CAAC,QAAQ,EAAE,GAAG,CACvB,CAAA;IACF,CAAC;IAED,OAAO,SAAS,CAAC,cAAc,CAAQ,CAAA;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAmB,IAAO;IACvD,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI;QAAE,OAAO,IAAW,CAAA;IAEnD,OAAO,SAAS,CAAC,IAAI,CAAQ,CAAA;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAoB;IACpD,OAAO,OAAO,CAAC,KAAK,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;AAC1F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC7C,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACrC,IAAI,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEzC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAA+B;IACnE,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrD,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAA;IACzC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAE3E,KAAK,MAAM,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC/C,IAAI,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACvC,MAAM,WAAW,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;YACpE,mBAAmB,CAAC,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;YAElD,MAAM,gBAAgB,GAAG,GAAG,YAAY,IAAI,WAAW,EAAE,CAAA;YACzD,eAAe,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAA;QACtC,CAAC;aAAM,CAAC;YACP,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QAClC,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;AACnC,CAAC"}

package/out/lib/node/fs.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { type PathLike } from "node:fs";
+import { TypedArray } from "type-fest";
+import { ByteRangeReader, ReadBytesOptions, StatsLike, TypedArrayFallback, type FileHandleLike, type FileResourceLike } from "../shared.js";
+export interface NodeFileResourceInit {
+    name?: string;
+    type?: string;
+    position?: number;
+    byteLength?: number;
+    lastModified?: number;
+    blockSize?: number;
+}
+/**
+ * An isomorphic file resource which can be read from and disposed.
+ */
+export declare class NodeFileResource implements FileResourceLike, ByteRangeReader, AsyncDisposable {
+    #private;
+    /**
+     * The last modified timestamp of the file.
+     */
+    readonly lastModified: number;
+    /**
+     * The name of the file.
+     */
+    readonly name: string;
+    /**
+     * @deprecated This property is not supported in Node.js.
+     */
+    readonly webkitRelativePath = "";
+    readonly blockSize?: number;
+    /**
+     * The byte length of the file.
+     */
+    readonly size: number;
+    /**
+     * The byte length of the file.
+     *
+     * Alias for {@linkcode #byteLength}.
+     */
+    get byteLength(): number;
+    readonly type: string;
+    constructor(handle: FileHandleLike, init: NodeFileResourceInit);
+    /**
+     * Read a range of bytes from the file.
+     *
+     * @param options - The options for reading the byte range.
+     */
+    read<B extends TypedArray>(options?: ReadBytesOptions & {
+        buffer?: B;
+    }): Promise<TypedArrayFallback<B>>;
+    /**
+     * Read the entire file as a byte array.
+     *
+     * @see {@linkcode slice} to create a sliced view of the file.
+     * @see {@linkcode arrayBuffer} to read the file as an array buffer.
+     */
+    bytes(): Promise<Uint8Array>;
+    /**
+     * Read the entire file as an array buffer.
+     *
+     * @see {@linkcode slice} to create a sliced view of the file.
+     * @see {@linkcode bytes} to read the file as a byte array.
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Slice the file into a new file resource.
+     *
+     * Note that the slice is a view of the original file, thus we're really just creating a new file
+     * resource with a different byte range.
+     *
+     * @param start - The starting byte offset.
+     * @param end - The ending byte offset.
+     * @param contentType - The content type of the slice.
+     *
+     * @returns A new file resource representing the sliced view of the file.
+     */
+    slice(start?: number, end?: number, contentType?: string): NodeFileResource;
+    /**
+     * Read the entire file as a string.
+     */
+    text(): Promise<string>;
+    /**
+     * Create a readable stream of the file.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    [Symbol.asyncDispose](): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Create a new file resource from a file handle or path.
+     */
+    static open(input: FileHandleLike | PathLike, stats?: StatsLike, init?: NodeFileResourceInit): Promise<NodeFileResource>;
+}
+export default NodeFileResource;
+//# sourceMappingURL=fs.d.ts.map

package/out/lib/node/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../lib/node/fs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAA;AAG/D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EACN,eAAe,EAEf,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,MAAM,cAAc,CAAA;AAErB,MAAM,WAAW,oBAAoB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB,EAAE,eAAe,EAAE,eAAe;;IAG1F;;OAEG;IACH,SAAgB,YAAY,EAAE,MAAM,CAAA;IACpC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B;;OAEG;IACH,SAAgB,kBAAkB,MAAK;IAEvC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAMD,SAAgB,IAAI,EAAE,MAAM,CAAA;gBAEhB,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,oBAAoB;IAW9D;;;;OAIG;IACG,IAAI,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,GAAE,gBAAgB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAwBjH;;;;;OAKG;IACU,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIzC;;;;;OAKG;IACI,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAI1C;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAelF;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAOpC;;OAEG;IACI,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAI9B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;OAEG;WACU,IAAI,CAChB,KAAK,EAAE,cAAc,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE,SAAS,EACjB,IAAI,GAAE,oBAAyB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;CAqB5B;AAED,eAAe,gBAAgB,CAAA"}