spliterator 6.0.1 → 6.2.0

package/out/lib/formats/TextSpliterator.js

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { Spliterator } from "../core/Spliterator.js";
+import { openDelimitedRows } from "../io/adaptive-source.js";
+import { AsyncSequence } from "../iterators/AsyncSequence.js";
+export class TextSpliterator {
+    constructor() {
+        throw new TypeError("Static class cannot be instantiated. Did you mean `TextSpliterator.from`?");
+    }
+    /**
+     * Synchronously yield delimited text from a byte array or string.
+     *
+     * @param source The source content to split.
+     * @param options The options to use when splitting the content.
+     *
+     * @yields Each slice of the source content.
+     * @see {@linkcode TextSpliterator.fromAsync} for asynchronous iteration with decoding.
+     * @see {@linkcode Spliterator.fromSync} for synchronous iteration without decoding.
+     */
+    static *from(source, { encoding, fatal, ignoreBOM, ...options } = {}) {
+        const decoder = new TextDecoder(encoding, { fatal, ignoreBOM });
+        let rowCursor = 0;
+        const spliterator = Spliterator.fromSync(source, options);
+        for (const row of spliterator) {
+            let decoded;
+            try {
+                decoded = decoder.decode(row);
+            }
+            catch (parsedError) {
+                const error = new SyntaxError(`Failed to decode data at row ${rowCursor}`);
+                error.cause = parsedError;
+                throw error;
+            }
+            yield decoded;
+            rowCursor++;
+        }
+    }
+    /**
+     * Asynchronously yield delimited text from a byte array or string.
+     *
+     * @param source The async data resource to split.
+     * @param options The options to use when splitting the content.
+     *
+     * @yields Each slice of the source content.
+     * @see {@linkcode TextSpliterator.from} for synchronous iteration with decoding.
+     * @see {@linkcode Spliterator.fromAsync} for asynchronous iteration without decoding.
+     */
+    static fromAsync(source, { encoding, fatal, ignoreBOM, ...options } = {}) {
+        const decoder = new TextDecoder(encoding, { fatal, ignoreBOM });
+        // Decoding is an op on the sequence, not a generator wrapped inside one. A wrapping generator adds an async frame
+        // per row on top of the sequence's own, which measured 297ms against 279ms over 500k rows.
+        return AsyncSequence.from(() => openDelimitedRows(source, options)).map((row, rowCursor) => {
+            try {
+                return decoder.decode(row);
+            }
+            catch (parsedError) {
+                const error = new SyntaxError(`Failed to decode data at row ${rowCursor}`);
+                error.cause = parsedError;
+                throw error;
+            }
+        });
+    }
+}
+//# sourceMappingURL=TextSpliterator.js.map

package/out/lib/formats/TextSpliterator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextSpliterator.js","sourceRoot":"","sources":["../../../lib/formats/TextSpliterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAA6B,WAAW,EAAwB,MAAM,wBAAwB,CAAA;AAErG,OAAO,EAA2B,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAsB7D,MAAM,OAAgB,eAAe;IACpC;QACC,MAAM,IAAI,SAAS,CAAC,2EAA2E,CAAC,CAAA;IACjG,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,IAAI,CACX,MAA8B,EAC9B,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,GAA0C,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,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAEzD,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,IAAI,WAAW,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAA;gBAC1E,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;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAS,CACf,MAAyB,EACzB,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,GAA6C,EAAE;QAEzF,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;QAE/D,kHAAkH;QAClH,2FAA2F;QAC3F,OAAO,aAAa,CAAC,IAAI,CAAa,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE;YACtG,IAAI,CAAC;gBACJ,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC3B,CAAC;YAAC,OAAO,WAAW,EAAE,CAAC;gBACtB,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAA;gBAC1E,KAAK,CAAC,KAAK,GAAG,WAAW,CAAA;gBAEzB,MAAM,KAAK,CAAA;YACZ,CAAC;QACF,CAAC,CAAC,CAAA;IACH,CAAC;CACD"}

package/out/lib/formats/XLSXSpliterator.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import type { AsyncChunkIterator } from "../internal/shared.js";
+import { AsyncSequence } from "../iterators/AsyncSequence.js";
+import { type RowEmitter, type RowOutputMode, type RowTransformer, type RowTransformerEntry, type RowTransformerRecord, type RowTuple } from "./row-emitters.js";
+/**
+ * A cell value as parsed from an XLSX sheet. Unlike CSV columns, XLSX cells arrive typed — numbers, booleans, and dates
+ * are real values, not strings — and an empty cell is `null`.
+ */
+export type XLSXCellValue = string | number | boolean | Date | null;
+export type XLSXTransformer<T = unknown> = RowTransformer<XLSXCellValue, T>;
+export type XLSXTransformerEntry<T = unknown> = RowTransformerEntry<XLSXCellValue, T>;
+export type XLSXTransformerRecord = RowTransformerRecord<XLSXCellValue>;
+export type XLSXSpliteratorEmittedRecord<V = XLSXCellValue> = Record<string, V>;
+/**
+ * A readable XLSX source: a file path, a whole workbook in memory, or an asynchronous byte stream.
+ */
+export type XLSXSource = string | URL | Uint8Array | AsyncChunkIterator;
+/**
+ * A row accepted by {@linkcode XLSXSpliterator.write}: either an array of cells, or a record whose keys become the
+ * header row. `undefined` cells are written as empty (`null`) cells, so records read under `noUncheckedIndexedAccess`
+ * pass through without ceremony.
+ */
+export type XLSXWritableRow = readonly (XLSXCellValue | undefined)[] | Readonly<Record<string, XLSXCellValue | undefined>>;
+export declare const XLSXSpliteratorEmitters: Record<RowOutputMode, RowEmitter<XLSXCellValue> | null>;
+export interface XLSXSpliteratorInit {
+    /**
+     * The sheet to read, as a 1-based sheet number or a sheet name.
+     *
+     * @default 1
+     */
+    sheet?: number | string;
+    /**
+     * The mode determines the shape of the data emitted by the generator.
+     *
+     * - `object` will emit each row as an object with the header names as keys.
+     * - `array` will emit each row as an array.
+     * - `entries` will emit each row as an array of key-value pairs.
+     *
+     * @default "array"
+     */
+    mode?: RowOutputMode;
+    /**
+     * Whether to treat the first row as a header.
+     *
+     * @default true
+     */
+    header?: boolean;
+    /**
+     * Whether to normalize the keys of the header row into `snake_case`, matching {@linkcode CSVSpliterator}.
+     *
+     * @default `mode !== "array"`
+     */
+    normalizeKeys?: boolean;
+    /**
+     * Per-column transformers. Unlike CSV transformers, these receive typed cell values ({@linkcode XLSXCellValue}), not
+     * strings.
+     */
+    transformers?: Iterable<XLSXTransformerEntry> | XLSXTransformerRecord;
+    /**
+     * The number of data rows to skip before yielding.
+     */
+    drop?: number;
+    /**
+     * The maximum number of rows to yield.
+     */
+    take?: number;
+}
+export interface XLSXWriteInit {
+    /**
+     * The name of the written sheet.
+     */
+    sheet?: string;
+    /**
+     * Whether to emit a header row.
+     *
+     * @default true for record rows — the header is derived from the first record's keys. Array rows have no keys, so
+     *   this defaults to false and enabling it is a `TypeError`.
+     */
+    header?: boolean;
+}
+/**
+ * A handle over a pending XLSX serialization. The source rows are materialized on the first invocation of any method —
+ * XLSX is a ZIP archive, so the workbook must be complete before any bytes can be produced.
+ */
+export interface XLSXWriteHandle {
+    toFile(path: string): Promise<void>;
+    toBuffer(): Promise<Buffer>;
+    toStream(writable?: NodeJS.WritableStream): Promise<unknown>;
+}
+/**
+ * A static class spliterator for XLSX workbooks, reading through the optional peer dependency `read-excel-file` and
+ * writing through `write-excel-file`.
+ *
+ * **Memory:** XLSX is a ZIP archive of XML documents — shared strings live in a separate archive entry, and the central
+ * directory sits at the end of the file. Both reading and writing therefore materialize the whole workbook, unlike the
+ * byte-level spliterators. Prefer CSV for sources large enough that bounded memory matters.
+ *
+ * @see {@linkcode XLSXSpliterator.fromAsync} for reading.
+ * @see {@linkcode XLSXSpliterator.write} for writing.
+ */
+export declare abstract class XLSXSpliterator {
+    constructor();
+    /**
+     * XLSX cannot be parsed synchronously — decompression and XML parsing are asynchronous in the underlying reader.
+     *
+     * @throws {TypeError} Always. Use {@linkcode XLSXSpliterator.fromAsync}.
+     */
+    static from(_source?: unknown, _init?: unknown): never;
+    /**
+     * @yields Each row as an object with the header names as keys.
+     */
+    static fromAsync<T extends XLSXSpliteratorEmittedRecord = XLSXSpliteratorEmittedRecord>(source: XLSXSource, options?: XLSXSpliteratorInit & {
+        mode: "object";
+    }): AsyncSequence<T>;
+    /**
+     * @yields Each row as a 3-tuple [key, value, idx].
+     */
+    static fromAsync<T extends RowTuple<unknown>[] = RowTuple<XLSXCellValue>[]>(source: XLSXSource, options?: XLSXSpliteratorInit & {
+        mode: "entries";
+    }): AsyncSequence<T>;
+    /**
+     * @yields Each row as an array of typed cells.
+     */
+    static fromAsync<T extends XLSXCellValue[] = XLSXCellValue[]>(source: XLSXSource, options?: XLSXSpliteratorInit & {
+        mode?: "array";
+    }): AsyncSequence<T>;
+    /**
+     * Serialize rows into an XLSX workbook through the optional peer dependency `write-excel-file`.
+     *
+     * Rows may be arrays of cells, or records — record keys become the header row, read in the first record's key order.
+     * The source is materialized on the first invocation of a handle method: the workbook must be complete before any
+     * bytes can be produced.
+     *
+     * @param source The rows to write, as any iterable or async iterable.
+     * @param init Options for the writer.
+     */
+    static write(source: Iterable<XLSXWritableRow> | AsyncIterable<XLSXWritableRow>, init?: XLSXWriteInit): XLSXWriteHandle;
+}
+//# sourceMappingURL=XLSXSpliterator.d.ts.map

package/out/lib/formats/XLSXSpliterator.d.ts.map

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

package/out/lib/formats/XLSXSpliterator.js

@@ -0,0 +1,161 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { AsyncSequence } from "../iterators/AsyncSequence.js";
+import { normalizeColumnNames } from "./casing.js";
+import { bindTransformers, createRowEmitters, } from "./row-emitters.js";
+export const XLSXSpliteratorEmitters = createRowEmitters(null);
+/**
+ * Wrap the optional peer dependency import so a missing module names the package to install.
+ */
+async function importVendor(packageName, importer) {
+    try {
+        return await importer();
+    }
+    catch (error) {
+        throw new Error(`XLSXSpliterator requires the optional peer dependency "${packageName}". Install it to use this API.`, { cause: error });
+    }
+}
+/**
+ * Adapt a {@linkcode XLSXSource} to what `read-excel-file/node` accepts: a path, a `Buffer`, or a Node stream.
+ */
+async function resolveVendorInput(source) {
+    if (typeof source === "string")
+        return source;
+    if (source instanceof URL) {
+        const { fileURLToPath } = await import("node:url");
+        return fileURLToPath(source);
+    }
+    if (source instanceof Uint8Array) {
+        // Respect the byte offset: small `Buffer`s share a pool, so offset 0 of the
+        // underlying `ArrayBuffer` may be another allocation's data.
+        return Buffer.from(source.buffer, source.byteOffset, source.byteLength);
+    }
+    const { Readable } = await import("node:stream");
+    return Readable.from(source);
+}
+/**
+ * A static class spliterator for XLSX workbooks, reading through the optional peer dependency `read-excel-file` and
+ * writing through `write-excel-file`.
+ *
+ * **Memory:** XLSX is a ZIP archive of XML documents — shared strings live in a separate archive entry, and the central
+ * directory sits at the end of the file. Both reading and writing therefore materialize the whole workbook, unlike the
+ * byte-level spliterators. Prefer CSV for sources large enough that bounded memory matters.
+ *
+ * @see {@linkcode XLSXSpliterator.fromAsync} for reading.
+ * @see {@linkcode XLSXSpliterator.write} for writing.
+ */
+export class XLSXSpliterator {
+    constructor() {
+        throw new TypeError("Static class cannot be instantiated. Did you mean `XLSXSpliterator.fromAsync`?");
+    }
+    /**
+     * XLSX cannot be parsed synchronously — decompression and XML parsing are asynchronous in the underlying reader.
+     *
+     * @throws {TypeError} Always. Use {@linkcode XLSXSpliterator.fromAsync}.
+     */
+    static from(_source, _init) {
+        throw new TypeError("XLSX cannot be parsed synchronously. Did you mean `XLSXSpliterator.fromAsync`?");
+    }
+    /**
+     * Given an XLSX workbook, yield each row of a sheet, shaped according to the `mode` option.
+     *
+     * Note that unlike the byte-level spliterators, the whole sheet is materialized before the first row is yielded.
+     *
+     * @param source The workbook to read.
+     * @param init Options for the spliterator.
+     *
+     * @yields Each row, shaped according to the `mode` option.
+     */
+    static fromAsync(source, init = {}) {
+        const { 
+        // ---
+        sheet = 1, header = true, mode = "array", transformers: transformersInput = [], normalizeKeys = mode !== "array", take = Infinity, drop = 0, } = init;
+        const emitter = XLSXSpliteratorEmitters[mode];
+        // Populated by the header pass below before the first row op runs, matching `CSVSpliterator.fromAsync`.
+        let transformers = [];
+        const openRows = async () => {
+            const { readSheet } = await importVendor("read-excel-file", () => import("read-excel-file/node"));
+            const input = await resolveVendorInput(source);
+            const rows = (await readSheet(input, sheet));
+            if (!header)
+                return rows;
+            const headerRow = rows[0];
+            if (!headerRow)
+                return [];
+            // A header row may legally contain non-string cells — stringify before normalization.
+            const columns = headerRow.map((cell) => String(cell ?? ""));
+            const headers = normalizeKeys ? normalizeColumnNames(columns) : columns;
+            transformers = bindTransformers(headers, transformersInput);
+            return rows.slice(1);
+        };
+        let sequence = AsyncSequence.from(openRows).map((row) => {
+            return emitter ? emitter(row, transformers) : row;
+        });
+        if (drop > 0) {
+            sequence = sequence.drop(drop);
+        }
+        if (Number.isFinite(take)) {
+            sequence = sequence.take(take);
+        }
+        return sequence;
+    }
+    /**
+     * Serialize rows into an XLSX workbook through the optional peer dependency `write-excel-file`.
+     *
+     * Rows may be arrays of cells, or records — record keys become the header row, read in the first record's key order.
+     * The source is materialized on the first invocation of a handle method: the workbook must be complete before any
+     * bytes can be produced.
+     *
+     * @param source The rows to write, as any iterable or async iterable.
+     * @param init Options for the writer.
+     */
+    static write(source, init = {}) {
+        const open = async () => {
+            const { default: writeXlsxFile } = await importVendor("write-excel-file", () => import("write-excel-file/node"));
+            const data = await materializeSheetData(source, init);
+            return writeXlsxFile(data, init.sheet === undefined ? undefined : { sheet: init.sheet });
+        };
+        return {
+            async toFile(path) {
+                await (await open()).toFile(path);
+            },
+            async toBuffer() {
+                return (await open()).toBuffer();
+            },
+            async toStream(writable) {
+                return (await open()).toStream(writable);
+            },
+        };
+    }
+}
+/**
+ * Materialize writable rows into `write-excel-file`'s sheet data: bare cell values, with a header row derived from
+ * record keys when the rows are records.
+ */
+async function materializeSheetData(source, init) {
+    const data = [];
+    let keys;
+    for await (const row of source) {
+        if (Array.isArray(row)) {
+            if (init.header) {
+                throw new TypeError("`header` requires record rows — array rows have no keys to derive a header from.");
+            }
+            data.push(row);
+            continue;
+        }
+        const record = row;
+        if (!keys) {
+            // The header is derived from the first record's keys; later records are read in that order.
+            keys = Object.keys(record);
+            if (init.header !== false) {
+                data.push(keys);
+            }
+        }
+        data.push(keys.map((key) => record[key] ?? null));
+    }
+    return data;
+}
+//# sourceMappingURL=XLSXSpliterator.js.map

package/out/lib/formats/XLSXSpliterator.js.map

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

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

@@ -0,0 +1,27 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @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/formats/casing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"casing.d.ts","sourceRoot":"","sources":["../../../lib/formats/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,CAMtD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAkB9E"}

package/out/lib/formats/casing.js

@@ -0,0 +1,68 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @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"
+        .replaceAll(/([A-Z])(\.+)/g, "$1")
+        .trim();
+    if (normalizedName.toUpperCase() === normalizedName) {
+        return name
+            // Replace all non-word characters with underscores...
+            .replaceAll(/\W{1,}/g, "_")
+            // ...and then replace all sequences of underscores with a single underscore.
+            .replaceAll(/_{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/formats/casing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"casing.js","sourceRoot":"","sources":["../../../lib/formats/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,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC;SACjC,IAAI,EAAE,CAAA;IAER,IAAI,cAAc,CAAC,WAAW,EAAE,KAAK,cAAc,EAAE,CAAC;QACrD,OACC,IAAI;YACH,sDAAsD;aACrD,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC;YAC3B,6EAA6E;aAC5E,UAAU,CAAC,QAAQ,EAAE,GAAG,CAC1B,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;IAErC,IAAI,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEzC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC;AAED;;GAEG;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/formats/row-emitters.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+/**
+ * An output mode for row-emitting spliterators.
+ */
+export type RowOutputMode = "array" | "object" | "entries";
+export type RowTransformer<V, T = unknown> = (value: V) => T;
+export type RowTransformerEntry<V, T = unknown> = [columnName: string, transformer: RowTransformer<V, T>];
+export type RowTransformerRecord<V> = Record<string, RowTransformer<V> | undefined>;
+export type RowEmitter<V, T = unknown> = (columns: Iterable<V>, headerColumns?: Iterable<RowTransformerEntry<V>>) => T;
+export type EmittedRecord<V = unknown> = Record<string, V>;
+/**
+ * A row emitted in `entries` mode, as a 3-tuple:
+ *
+ * - The key of the column.
+ * - The value of the column.
+ * - The index of the row.
+ */
+export type RowTuple<V = string | number> = [key: string, value: V, idx: number];
+export declare const identity: <V>(value: V) => V;
+/**
+ * Create the `mode`-keyed emitter table for a cell type.
+ *
+ * `missingValue` fills columns absent from a short row (CSV binds `""`, XLSX binds `null`).
+ */
+export declare function createRowEmitters<V>(missingValue: V): Record<RowOutputMode, RowEmitter<V> | null>;
+/**
+ * Bind a header row to the caller's transformers, producing the `headerColumns` entries the emitters consume. Columns
+ * without a transformer pass through {@linkcode identity}.
+ */
+export declare function bindTransformers<V>(headers: string[], transformersInput: Iterable<RowTransformerEntry<V>> | RowTransformerRecord<V>): RowTransformerEntry<V>[];
+//# sourceMappingURL=row-emitters.d.ts.map

package/out/lib/formats/row-emitters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-emitters.d.ts","sourceRoot":"","sources":["../../../lib/formats/row-emitters.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE1D,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;AAE5D,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAEzG,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;AAEnF,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;AAEtH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;AAEhF,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,KAAG,CAAU,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAyBjG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EACjC,OAAO,EAAE,MAAM,EAAE,EACjB,iBAAiB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC3E,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAa1B"}

package/out/lib/formats/row-emitters.js

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license MIT
+ * @author Teffen Ellis, et al.
+ */
+import { zipSync } from "../iterators/zip.js";
+export const identity = (value) => value;
+/**
+ * Create the `mode`-keyed emitter table for a cell type.
+ *
+ * `missingValue` fills columns absent from a short row (CSV binds `""`, XLSX binds `null`).
+ */
+export function createRowEmitters(missingValue) {
+    return {
+        array: null,
+        entries(columns, headerColumns = []) {
+            return Array.from(zipSync(headerColumns, columns), ([transformer, value], idx) => {
+                const key = transformer?.[0];
+                const transform = transformer?.[1] ?? identity;
+                return [key ?? `column_${idx}`, transform(value ?? missingValue), idx];
+            });
+        },
+        object(columns, headerColumns = []) {
+            const record = {};
+            for (const [transformer, value, idx] of zipSync(headerColumns, columns)) {
+                const key = transformer?.[0] ?? `column_${idx}`;
+                const transform = transformer?.[1] ?? identity;
+                record[key] = transform(value ?? missingValue);
+            }
+            return record;
+        },
+    };
+}
+/**
+ * Bind a header row to the caller's transformers, producing the `headerColumns` entries the emitters consume. Columns
+ * without a transformer pass through {@linkcode identity}.
+ */
+export function bindTransformers(headers, transformersInput) {
+    if (Array.isArray(transformersInput)) {
+        return Array.from(zipSync(headers, transformersInput), ([columnName, transformer]) => [
+            columnName,
+            transformer ?? identity,
+        ]);
+    }
+    return headers.map((columnName) => {
+        const transform = transformersInput[columnName] || identity;
+        return [columnName, transform];
+    });
+}
+//# sourceMappingURL=row-emitters.js.map

package/out/lib/formats/row-emitters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-emitters.js","sourceRoot":"","sources":["../../../lib/formats/row-emitters.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AA0B7C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAI,KAAQ,EAAK,EAAE,CAAC,KAAK,CAAA;AAEjD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAI,YAAe;IACnD,OAAO;QACN,KAAK,EAAE,IAAI;QAEX,OAAO,CAAC,OAAoB,EAAE,aAAa,GAAqC,EAAE;YACjF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE;gBAChF,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,CAAA;gBAC5B,MAAM,SAAS,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAA;gBAE9C,OAAO,CAAC,GAAG,IAAI,UAAU,GAAG,EAAE,EAAE,SAAS,CAAC,KAAK,IAAI,YAAY,CAAC,EAAE,GAAG,CAAC,CAAA;YACvE,CAAC,CAAC,CAAA;QACH,CAAC;QACD,MAAM,CAAC,OAAoB,EAAE,aAAa,GAAqC,EAAE;YAChF,MAAM,MAAM,GAA2B,EAAE,CAAA;YAEzC,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC;gBACzE,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,GAAG,EAAE,CAAA;gBAC/C,MAAM,SAAS,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAA;gBAE9C,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,YAAY,CAAC,CAAA;YAC/C,CAAC;YAED,OAAO,MAAM,CAAA;QACd,CAAC;KACD,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAiB,EACjB,iBAA6E;IAE7E,IAAI,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC;YACrF,UAAW;YACV,WAA6C,IAAI,QAAQ;SAC1D,CAAC,CAAA;IACH,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QACjC,MAAM,SAAS,GAAI,iBAA6C,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAA;QAExF,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;AACH,CAAC"}