utilful 2.2.4 → 2.4.0

package/README.md

@@ -50,26 +50,24 @@ declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[]
 
 #### `createCSV`
 
-Converts an array of objects to a comma-separated values (CSV) string that contains only the `columns` specified.
+Converts an array of objects to a comma-separated values (CSV) string. You can either specify which columns to include explicitly, or let the function automatically infer all columns from your data.
 
 ```ts
+// With explicit columns
 declare function createCSV<T extends Record<string, unknown>>(
-  data: T[],
+  data: readonly T[],
   columns: readonly (keyof T)[],
-  options?: {
-    /** @default ',' */
-    delimiter?: string
-    /** @default true */
-    addHeader?: boolean
-    /** @default false */
-    quoteAll?: boolean
-    /** @default '\n' */
-    lineEnding?: string
-  }
+  options?: CSVCreateOptions
+): string
+
+// With automatic column inference
+declare function createCSV<T extends Record<string, unknown>>(
+  data: readonly T[],
+  options?: CSVCreateOptions
 ): string
 ```
 
-**Example:**
+**Example with explicit columns:**
 
 ```ts
 const data = [
@@ -77,12 +75,32 @@ const data = [
   { name: 'Jane', age: '25', city: 'Boston' }
 ]
 
+// Only include 'name' and 'age' columns
 const csv = createCSV(data, ['name', 'age'])
 // name,age
 // John,30
 // Jane,25
 ```
 
+**Example with automatic column inference:**
+
+When you omit the `columns` parameter, `createCSV` automatically collects all unique keys from your data in first-seen order. This is particularly useful when working with data that has varying structures:
+
+```ts
+const rows = [
+  { name: 'John', age: '30' },
+  { name: 'Jane', city: 'Boston' },
+  { name: 'Bob', age: '40', city: 'Chicago' }
+]
+
+// All columns are automatically detected: name, age, city
+const csv = createCSV(rows)
+// name,age,city
+// John,30,
+// Jane,,Boston
+// Bob,40,Chicago
+```
+
 #### `parseCSV`
 
 Parses a comma-separated values (CSV) string into an array of objects.
@@ -119,7 +137,7 @@ const csv = `
 name,age
 John,30
 Jane,25
-`
+`.trim()
 
 const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
 ```
@@ -134,7 +152,7 @@ Recursively assigns missing properties from defaults to the source object. The s
 
 **Key Features:**
 
-- **Null/undefined handling**: `null` and `undefined` values in source are replaced with defaults
+- **Nullish handling**: `null` and `undefined` values in source are replaced with defaults
 - **Array concatenation**: Arrays are concatenated (source + defaults)
 - **Deep merging**: Nested objects are recursively merged
 - **Type safety**: Preserves TypeScript types
@@ -171,7 +189,7 @@ const result = defu(
 // Result: { items: ['a', 'b', 'c', 'd'] }
 ```
 
-**Null/undefined handling:**
+**Handling null/undefined:**
 
 ```ts
 const result = defu(
@@ -455,8 +473,6 @@ else
 
 The `Result` type represents either success (`Ok`) or failure (`Err`).
 
-**Type Definition:**
-
 ```ts
 type Result<T, E> = Ok<T> | Err<E>
 ```
@@ -485,8 +501,6 @@ const result = new Err('Something went wrong')
 
 Shorthand function to create an `Ok` result. Use it to wrap a successful value.
 
-**Type Definition:**
-
 ```ts
 declare function ok<T>(value: T): Ok<T>
 ```
@@ -495,8 +509,6 @@ declare function ok<T>(value: T): Ok<T>
 
 Shorthand function to create an `Err` result. Use it to wrap an error value.
 
-**Type Definition:**
-
 ```ts
 declare function err<E extends string = string>(err: E): Err<E>
 declare function err<E = unknown>(err: E): Err<E>
@@ -506,8 +518,6 @@ declare function err<E = unknown>(err: E): Err<E>
 
 Wraps a function that might throw an error and returns a `Result` with the result of the function.
 
-**Type Definition:**
-
 ```ts
 declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>
 declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
@@ -517,25 +527,28 @@ declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T
 
 Unwraps a `Result`, `Ok`, or `Err` value and returns the value or error in an object. If the result is an `Ok`, the object contains the value and an `undefined` error. If the result is an `Err`, the object contains an `undefined` value and the error.
 
-**Example:**
-
 ```ts
-const result = toResult(() => JSON.parse('{"foo":"bar"}'))
-const { value, error } = unwrapResult(result)
+declare function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
+declare function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
+declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
 ```
 
-**Type Definition:**
+**Example:**
 
 ```ts
-declare function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
-declare function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
-declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
+const result = toResult(() => JSON.parse('{"foo":"bar"}'))
+const { value, error } = unwrapResult(result)
 ```
 
 #### `tryCatch`
 
 A simpler alternative to `toResult` + `unwrapResult`. It executes a function that might throw an error and directly returns the result in a `ResultData` format. Works with both synchronous functions and promises.
 
+```ts
+declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
+declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
+```
+
 **Example:**
 
 ```ts
@@ -548,13 +561,6 @@ const { value, error } = tryCatch(() => JSON.parse('{"foo":"bar"}'))
 const { value, error } = await tryCatch(fetch('https://api.example.com/data').then(r => r.json()))
 ```
 
-**Type Definition:**
-
-```ts
-declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
-declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
-```
-
 ### String
 
 #### `template`

package/dist/csv.d.mts

@@ -4,10 +4,32 @@
 */
 type CSVRow<T extends string = string> = Record<T, string>;
 /**
-* Converts an array of objects to a comma-separated values (CSV) string
-* that contains only the `columns` specified.
+* Options for the `createCSV` function.
+*/
+interface CSVCreateOptions {
+  /** @default ',' */
+  delimiter?: string;
+  /** @default true */
+  addHeader?: boolean;
+  /** @default false */
+  quoteAll?: boolean;
+  /** @default '\n' */
+  lineEnding?: string;
+}
+/**
+* Converts an array of objects to a comma-separated values (CSV) string.
+*
+* @remarks
+* When `columns` is omitted, the function automatically infers columns by collecting
+* the union of all keys across all objects in first-seen order. This means if different
+* objects have different keys, all keys will be included in the CSV. Objects missing
+* certain keys will have empty values for those columns.
+*
+* When `columns` is provided explicitly, only those columns are included in the output,
+* allowing you to control column order and filter out unwanted properties.
 *
 * @example
+* // With explicit columns
 * const data = [
 *   { name: 'John', age: '30', city: 'New York' },
 *   { name: 'Jane', age: '25', city: 'Boston' }
@@ -17,17 +39,56 @@ type CSVRow<T extends string = string> = Record<T, string>;
 * // name,age
 * // John,30
 * // Jane,25
+*
+* @example
+* // With inferred columns (union of all keys in first-seen order)
+* const rows = [
+*   { name: 'John', age: '30' },
+*   { name: 'Jane', city: 'Boston' },
+* ]
+*
+* const csv = createCSV(rows)
+* // name,age,city
+* // John,30,
+* // Jane,,Boston
 */
-declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: readonly (keyof T)[], options?: {
-  /** @default ',' */
-  delimiter?: string;
-  /** @default true */
-  addHeader?: boolean;
-  /** @default false */
-  quoteAll?: boolean;
-  /** @default '\n' */
-  lineEnding?: string;
-}): string;
+declare function createCSV<T extends Record<string, unknown>>(data: readonly T[], columns: readonly (keyof T)[], options?: CSVCreateOptions): string;
+declare function createCSV<T extends Record<string, unknown>>(data: readonly T[], options?: CSVCreateOptions): string;
+/**
+* Creates a CSV stream from an iterable or async iterable of objects.
+*
+* @remarks
+* This function yields CSV content as strings, including line endings.
+* Each yielded chunk contains complete lines (header and/or data rows).
+*
+* @example
+* const data = [
+*   { name: 'John', age: '30' },
+*   { name: 'Jane', age: '25' }
+* ]
+*
+* for await (const chunk of createCSVStream(data, ['name', 'age'])) {
+*   console.log(chunk)
+* }
+*/
+declare function createCSVStream<T extends Record<string, unknown>>(data: AsyncIterable<T> | Iterable<T>, columns: readonly (keyof T)[], options?: CSVCreateOptions): AsyncIterable<string>;
+/**
+* Creates a CSV string from an async iterable or iterable of objects.
+*
+* @remarks
+* This is a convenience wrapper around `createCSVStream` that collects
+* all chunks into a single string. Note that the result will have a
+* trailing line ending, unlike the synchronous `createCSV`.
+*
+* @example
+* const data = [
+*   { name: 'John', age: '30' },
+*   { name: 'Jane', age: '25' }
+* ]
+*
+* const csv = await createCSVAsync(data, ['name', 'age'])
+*/
+declare function createCSVAsync<T extends Record<string, unknown>>(data: AsyncIterable<T> | Iterable<T>, columns: readonly (keyof T)[], options?: CSVCreateOptions): Promise<string>;
 /**
 * Escapes a value for a CSV string.
 *
@@ -74,5 +135,45 @@ declare function parseCSV<Header extends string>(csv?: string | null | undefined
   */
   strict?: boolean;
 }): CSVRow<Header>[];
+/**
+* Parses CSV data from an async iterable or iterable of string chunks.
+*
+* @remarks
+* This function yields CSV rows as they are parsed. Chunks do not need to
+* align with row boundaries; the parser handles quotes and newlines correctly
+* across chunk boundaries.
+*
+* @example
+* const chunks = ['name,age\nJo', 'hn,30\nJane,25']
+*
+* for await (const row of parseCSVStream<'name' | 'age'>(chunks)) {
+*   console.log(row)
+* }
+*/
+declare function parseCSVStream<Header extends string>(chunks: AsyncIterable<string> | Iterable<string>, options?: {
+  delimiter?: string;
+  trim?: boolean;
+  strict?: boolean;
+}): AsyncIterable<CSVRow<Header>>;
+/**
+* Parses CSV data from an async iterable or iterable of lines.
+*
+* @remarks
+* This is a convenience wrapper around `parseCSVStream` that treats each line
+* as a chunk. Note that lines do not necessarily correspond to CSV rows due to
+* quoted fields containing newlines. The parser handles this correctly.
+*
+* @example
+* const lines = ['name,age', 'John,30', 'Jane,25']
+*
+* for await (const row of parseCSVFromLines<'name' | 'age'>(lines)) {
+*   console.log(row)
+* }
+*/
+declare function parseCSVFromLines<Header extends string>(lines: AsyncIterable<string> | Iterable<string>, options?: {
+  delimiter?: string;
+  trim?: boolean;
+  strict?: boolean;
+}): AsyncIterable<CSVRow<Header>>;
 //#endregion
-export { CSVRow, createCSV, escapeCSVValue, parseCSV };
+export { CSVCreateOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream };

package/dist/csv.mjs

@@ -1,29 +1,87 @@
 //#region src/csv.ts
+const COMMA = ",";
+const DOUBLE_QUOTE = "\"";
+const NEWLINE = "\n";
+const CARRIAGE_RETURN = "\r";
+const ESCAPED_QUOTE = "\"\"";
+const SPACE = " ";
+const TAB = "	";
+function createCSV(data, columnsOrOptions, maybeOptions = {}) {
+	let columns;
+	let options;
+	if (Array.isArray(columnsOrOptions)) {
+		columns = columnsOrOptions;
+		options = maybeOptions;
+	} else {
+		columns = inferColumns(data);
+		options = columnsOrOptions ?? {};
+	}
+	if (columns.length === 0 && data.length === 0) return "";
+	const { delimiter = COMMA, addHeader = true, quoteAll = false, lineEnding = NEWLINE } = options;
+	if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
+	if (addHeader) {
+		const header = encodeCSVHeader(columns.map(String), delimiter, quoteAll);
+		if (data.length === 0) return header;
+		const bodyLines = data.map((row) => encodeCSVRow(row, columns, delimiter, quoteAll));
+		return header + lineEnding + bodyLines.join(lineEnding);
+	}
+	return data.map((row) => encodeCSVRow(row, columns, delimiter, quoteAll)).join(lineEnding);
+}
 /**
-* Converts an array of objects to a comma-separated values (CSV) string
-* that contains only the `columns` specified.
+* Creates a CSV stream from an iterable or async iterable of objects.
+*
+* @remarks
+* This function yields CSV content as strings, including line endings.
+* Each yielded chunk contains complete lines (header and/or data rows).
 *
 * @example
 * const data = [
-*   { name: 'John', age: '30', city: 'New York' },
-*   { name: 'Jane', age: '25', city: 'Boston' }
+*   { name: 'John', age: '30' },
+*   { name: 'Jane', age: '25' }
 * ]
 *
-* const csv = createCSV(data, ['name', 'age'])
-* // name,age
-* // John,30
-* // Jane,25
+* for await (const chunk of createCSVStream(data, ['name', 'age'])) {
+*   console.log(chunk)
+* }
 */
-function createCSV(data, columns, options = {}) {
-	const { delimiter = ",", addHeader = true, quoteAll = false, lineEnding = "\n" } = options;
+async function* createCSVStream(data, columns, options = {}) {
+	const { delimiter = COMMA, addHeader = true, quoteAll = false, lineEnding = NEWLINE } = options;
 	if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
-	const formatCell = (value) => escapeCSVValue(value, {
+	if (addHeader) yield encodeCSVHeader(columns.map(String), delimiter, quoteAll) + lineEnding;
+	for await (const row of data) yield encodeCSVRow(row, columns, delimiter, quoteAll) + lineEnding;
+}
+/**
+* Creates a CSV string from an async iterable or iterable of objects.
+*
+* @remarks
+* This is a convenience wrapper around `createCSVStream` that collects
+* all chunks into a single string. Note that the result will have a
+* trailing line ending, unlike the synchronous `createCSV`.
+*
+* @example
+* const data = [
+*   { name: 'John', age: '30' },
+*   { name: 'Jane', age: '25' }
+* ]
+*
+* const csv = await createCSVAsync(data, ['name', 'age'])
+*/
+async function createCSVAsync(data, columns, options = {}) {
+	const chunks = [];
+	for await (const chunk of createCSVStream(data, columns, options)) chunks.push(chunk);
+	return chunks.join("");
+}
+function encodeCSVHeader(columns, delimiter, quoteAll) {
+	return columns.map((col) => escapeCSVValue(col, {
 		delimiter,
 		quoteAll
-	});
-	const rows = data.map((obj) => columns.map((key) => formatCell(obj[key])).join(delimiter));
-	if (addHeader) return columns.map(formatCell).join(delimiter) + lineEnding + rows.join(lineEnding);
-	return rows.join(lineEnding);
+	})).join(delimiter);
+}
+function encodeCSVRow(row, columns, delimiter, quoteAll) {
+	return columns.map((key) => escapeCSVValue(row[key], {
+		delimiter,
+		quoteAll
+	})).join(delimiter);
 }
 /**
 * Escapes a value for a CSV string.
@@ -38,12 +96,118 @@ function createCSV(data, columns, options = {}) {
 * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
 */
 function escapeCSVValue(value, options = {}) {
-	const { delimiter = ",", quoteAll = false } = options;
+	const { delimiter = COMMA, quoteAll = false } = options;
 	if (value == null) return "";
 	const coercedValue = String(value);
-	if (quoteAll || coercedValue.includes(delimiter) || coercedValue.includes("\"") || coercedValue.includes("\n") || coercedValue.includes("\r")) return `"${coercedValue.replaceAll("\"", "\"\"")}"`;
+	const hasQuote = coercedValue.includes(DOUBLE_QUOTE);
+	if (quoteAll || coercedValue.includes(delimiter) || hasQuote || coercedValue.includes(NEWLINE) || coercedValue.includes(CARRIAGE_RETURN)) return `${DOUBLE_QUOTE}${hasQuote ? coercedValue.replaceAll(DOUBLE_QUOTE, ESCAPED_QUOTE) : coercedValue}${DOUBLE_QUOTE}`;
 	return coercedValue;
 }
+var CSVParserCore = class {
+	delimiter;
+	trim;
+	strict;
+	onRow;
+	currentRow = [];
+	currentRowQuotedFlags = [];
+	currentField = "";
+	inQuotes = false;
+	isFieldQuoted = false;
+	currentRowNumber = 1;
+	headerRaw;
+	headerQuotedFlags;
+	headers;
+	constructor(options, onRow) {
+		const { delimiter = COMMA, trim = true, strict = true } = options;
+		if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
+		this.delimiter = delimiter;
+		this.trim = trim;
+		this.strict = strict;
+		this.onRow = onRow;
+	}
+	push(chunk) {
+		for (let i = 0; i < chunk.length; i++) {
+			const character = chunk[i];
+			const nextCharacter = i + 1 < chunk.length ? chunk[i + 1] : "";
+			if (this.isFieldQuoted && !this.inQuotes && character !== this.delimiter && (character === SPACE || character === TAB)) continue;
+			if (character === DOUBLE_QUOTE) if (this.currentField.length === 0 && !this.inQuotes) {
+				this.inQuotes = true;
+				this.isFieldQuoted = true;
+			} else if (this.inQuotes && nextCharacter === DOUBLE_QUOTE) {
+				this.currentField += DOUBLE_QUOTE;
+				i++;
+			} else if (this.inQuotes) this.inQuotes = false;
+			else this.currentField += character;
+			else if (character === this.delimiter && !this.inQuotes) this.appendField();
+			else if ((character === NEWLINE || character === CARRIAGE_RETURN) && !this.inQuotes) {
+				if (character === CARRIAGE_RETURN && nextCharacter === NEWLINE) i++;
+				this.appendRow();
+			} else this.currentField += character;
+		}
+	}
+	finish() {
+		if (this.inQuotes) throw new SyntaxError(`CSV contains unterminated quoted field at row ${this.currentRowNumber}`);
+		if (this.currentField !== "" || this.currentRow.length > 0) this.appendRow();
+	}
+	appendField() {
+		this.currentRow.push(this.currentField);
+		this.currentRowQuotedFlags.push(this.isFieldQuoted);
+		this.currentField = "";
+		this.isFieldQuoted = false;
+	}
+	appendRow() {
+		this.appendField();
+		if (!this.headerRaw) {
+			this.headerRaw = this.currentRow;
+			this.headerQuotedFlags = this.currentRowQuotedFlags;
+			this.processHeaderRow();
+		} else this.processDataRow(this.currentRow, this.currentRowQuotedFlags);
+		this.currentRow = [];
+		this.currentRowQuotedFlags = [];
+		this.currentRowNumber++;
+	}
+	processHeaderRow() {
+		const headerRow = this.headerRaw;
+		const headerQuotedFlags = this.headerQuotedFlags ?? [];
+		const headers = this.trim ? headerRow.map((h, i) => headerQuotedFlags[i] ? h : h.trim()) : headerRow;
+		if (headers.filter((h) => h.length === 0).length > 0) {
+			const positions = headers.map((h, i) => h.length === 0 ? i + 1 : -1).filter((i) => i > 0).join(", ");
+			throw new SyntaxError(`CSV header row contains empty column name(s) at position(s): ${positions}`);
+		}
+		const headerSet = /* @__PURE__ */ new Set();
+		const duplicateHeaderNames = /* @__PURE__ */ new Set();
+		for (const header of headers) if (headerSet.has(header)) duplicateHeaderNames.add(header);
+		else headerSet.add(header);
+		if (duplicateHeaderNames.size > 0) throw new SyntaxError(`CSV header row contains duplicate column name(s): ${[...duplicateHeaderNames].join(", ")}`);
+		this.headers = headers;
+	}
+	processDataRow(fieldValues, quotedFlags) {
+		if (!this.headers) throw new Error("CSVParserCore: headers not initialized");
+		const headers = this.headers;
+		const isFieldPopulated = this.trim ? (field, wasQuoted) => wasQuoted ? field.length > 0 : field.trim().length > 0 : (field) => field.length > 0;
+		const hasMultipleFields = fieldValues.length > 1;
+		const hasAnyPopulatedField = fieldValues.some((field, idx) => isFieldPopulated(field, quotedFlags[idx] ?? false));
+		if (!hasMultipleFields && !hasAnyPopulatedField) return;
+		if (fieldValues.length > headers.length) {
+			const fieldsExceedingHeaders = fieldValues.slice(headers.length);
+			const excessQuotedFlags = quotedFlags.slice(headers.length);
+			const containsNonEmptyOverflow = fieldsExceedingHeaders.some((field, idx) => isFieldPopulated(field, excessQuotedFlags[idx] ?? false));
+			if (this.strict && containsNonEmptyOverflow) {
+				const expectedCount = headers.length;
+				const actualCount = fieldValues.length;
+				const excessCount = actualCount - expectedCount;
+				throw new SyntaxError(`CSV row ${this.currentRowNumber} has ${excessCount} extra field(s): expected ${expectedCount} column(s), found ${actualCount}`);
+			}
+		}
+		const rowEntries = headers.map((header, columnIndex) => {
+			const untrimmedValue = columnIndex < fieldValues.length ? fieldValues[columnIndex] ?? "" : "";
+			const wasQuoted = quotedFlags[columnIndex] ?? false;
+			return [header, this.trim && !wasQuoted ? untrimmedValue.trim() : untrimmedValue];
+		});
+		const rowObject = Object.fromEntries(rowEntries);
+		this.onRow(rowObject);
+	}
+};
 /**
 * Parses a comma-separated values (CSV) string into an array of objects.
 *
@@ -61,67 +225,72 @@ function escapeCSVValue(value, options = {}) {
 function parseCSV(csv, options = {}) {
 	if (!csv?.trim()) return [];
 	const rows = [];
-	let currentRow = [];
-	let currentField = "";
-	let inQuotes = false;
-	let currentRowNumber = 1;
-	const { delimiter = ",", trim = true, strict = true } = options;
-	if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
-	const appendField = () => {
-		currentRow.push(currentField);
-		currentField = "";
-	};
-	const appendRow = () => {
-		appendField();
-		rows.push(currentRow);
-		currentRow = [];
-	};
-	for (let i = 0; i < csv.length; i++) {
-		const character = csv[i];
-		const nextCharacter = i + 1 < csv.length ? csv[i + 1] : "";
-		if (character === "\"") if (inQuotes && nextCharacter === "\"") {
-			currentField += "\"";
-			i++;
-		} else inQuotes = !inQuotes;
-		else if (character === delimiter && !inQuotes) appendField();
-		else if ((character === "\n" || character === "\r" && nextCharacter === "\n") && !inQuotes) {
-			if (character === "\r") i++;
-			appendRow();
-			currentRowNumber++;
-		} else currentField += character;
+	const parser = new CSVParserCore(options, (row) => {
+		rows.push(row);
+	});
+	parser.push(csv);
+	parser.finish();
+	return rows;
+}
+/**
+* Parses CSV data from an async iterable or iterable of string chunks.
+*
+* @remarks
+* This function yields CSV rows as they are parsed. Chunks do not need to
+* align with row boundaries; the parser handles quotes and newlines correctly
+* across chunk boundaries.
+*
+* @example
+* const chunks = ['name,age\nJo', 'hn,30\nJane,25']
+*
+* for await (const row of parseCSVStream<'name' | 'age'>(chunks)) {
+*   console.log(row)
+* }
+*/
+async function* parseCSVStream(chunks, options = {}) {
+	const queue = [];
+	const parser = new CSVParserCore(options, (row) => {
+		queue.push(row);
+	});
+	for await (const chunk of chunks) {
+		parser.push(chunk);
+		while (queue.length > 0) yield queue.shift();
 	}
-	if (currentField || currentRow.length > 0) appendRow();
-	if (inQuotes) throw new SyntaxError(`CSV contains unterminated quoted field at row ${currentRowNumber}`);
-	if (rows.length <= 1) return [];
-	const [headerRow] = rows;
-	if (!headerRow) return [];
-	const headers = trim ? headerRow.map((h) => h.trim()) : headerRow;
-	if (headers.filter((h) => h.length === 0).length > 0) {
-		const positions = headers.map((h, i) => h.length === 0 ? i + 1 : -1).filter((i) => i > 0).join(", ");
-		throw new SyntaxError(`CSV header row contains empty column name(s) at position(s): ${positions}`);
+	parser.finish();
+	while (queue.length > 0) yield queue.shift();
+}
+/**
+* Parses CSV data from an async iterable or iterable of lines.
+*
+* @remarks
+* This is a convenience wrapper around `parseCSVStream` that treats each line
+* as a chunk. Note that lines do not necessarily correspond to CSV rows due to
+* quoted fields containing newlines. The parser handles this correctly.
+*
+* @example
+* const lines = ['name,age', 'John,30', 'Jane,25']
+*
+* for await (const row of parseCSVFromLines<'name' | 'age'>(lines)) {
+*   console.log(row)
+* }
+*/
+async function* parseCSVFromLines(lines, options) {
+	yield* parseCSVStream(lines, options);
+}
+/**
+* Infers column names from data by collecting the union of keys
+* across all rows in first-seen order.
+*/
+function inferColumns(rows) {
+	const seenColumns = /* @__PURE__ */ new Set();
+	const columns = [];
+	for (const row of rows) if (row && typeof row === "object") for (const columnName of Object.keys(row)) {
+		if (seenColumns.has(columnName)) continue;
+		seenColumns.add(columnName);
+		columns.push(columnName);
 	}
-	const headerSet = /* @__PURE__ */ new Set();
-	const duplicateHeaderNames = /* @__PURE__ */ new Set();
-	for (const header of headers) if (headerSet.has(header)) duplicateHeaderNames.add(header);
-	else headerSet.add(header);
-	if (duplicateHeaderNames.size > 0) throw new SyntaxError(`CSV header row contains duplicate column name(s): ${[...duplicateHeaderNames].join(", ")}`);
-	const isFieldPopulated = trim ? (field) => field.trim().length > 0 : (field) => field.length > 0;
-	return rows.slice(1).filter((row) => row.length > 1 || row.some(isFieldPopulated)).map((fieldValues, rowIndex) => {
-		if (fieldValues.length > headers.length) {
-			const containsNonEmptyOverflow = fieldValues.slice(headers.length).some(isFieldPopulated);
-			if (strict && containsNonEmptyOverflow) {
-				const expectedCount = headers.length;
-				const actualCount = fieldValues.length;
-				const excessCount = actualCount - expectedCount;
-				throw new SyntaxError(`CSV row ${rowIndex + 2} has ${excessCount} extra field(s): expected ${expectedCount} column(s), found ${actualCount}`);
-			}
-		}
-		return Object.fromEntries(headers.map((header, columnIndex) => {
-			const untrimmedValue = columnIndex < fieldValues.length ? fieldValues[columnIndex] ?? "" : "";
-			return [header, trim ? untrimmedValue.trim() : untrimmedValue];
-		}));
-	});
+	return columns;
 }
 
 //#endregion
-export { createCSV, escapeCSVValue, parseCSV };
+export { createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { MaybeArray, toArray } from "./array.mjs";
-import { CSVRow, createCSV, escapeCSVValue, parseCSV } from "./csv.mjs";
+import { CSVCreateOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream } from "./csv.mjs";
 import { DefuFn, DefuMerger, createDefu, defu } from "./defu.mjs";
 import { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from "./emitter.mjs";
 import { cloneJSON, tryParseJSON } from "./json.mjs";
@@ -9,4 +9,4 @@ import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSla
 import { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { generateRandomId, template } from "./string.mjs";
 import { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection } from "./types.mjs";
-export { AutocompletableString, BrandedType, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { AutocompletableString, BrandedType, CSVCreateOptions, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { toArray } from "./array.mjs";
-import { createCSV, escapeCSVValue, parseCSV } from "./csv.mjs";
+import { createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream } from "./csv.mjs";
 import { createDefu, defu } from "./defu.mjs";
 import { createEmitter } from "./emitter.mjs";
 import { cloneJSON, tryParseJSON } from "./json.mjs";
@@ -9,4 +9,4 @@ import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTraili
 import { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { generateRandomId, template } from "./string.mjs";
 
-export { Err, Ok, cloneJSON, createCSV, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { Err, Ok, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/json.mjs

@@ -21,11 +21,11 @@ function tryParseJSON(value) {
 */
 function cloneJSON(value) {
 	if (typeof value !== "object" || value === null) return value;
-	if (Array.isArray(value)) return value.map((e) => typeof e !== "object" || e === null ? e : cloneJSON(e));
+	if (Array.isArray(value)) return value.map((element) => typeof element !== "object" || element === null ? element : cloneJSON(element));
 	const result = {};
-	for (const k in value) {
-		const v = value[k];
-		result[k] = typeof v !== "object" || v === null ? v : cloneJSON(v);
+	for (const key in value) {
+		const propertyValue = value[key];
+		result[key] = typeof propertyValue !== "object" || propertyValue === null ? propertyValue : cloneJSON(propertyValue);
 	}
 	return result;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.2.4",
+  "version": "2.4.0",
   "packageManager": "pnpm@10.21.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",