utilful 2.3.0 → 2.4.0

package/dist/csv.d.mts

@@ -55,6 +55,41 @@ interface CSVCreateOptions {
 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.
 *
 * @remarks
@@ -100,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 { CSVCreateOptions, CSVRow, createCSV, escapeCSVValue, parseCSV };
+export { CSVCreateOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream };

package/dist/csv.mjs

@@ -1,4 +1,11 @@
 //#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;
@@ -10,19 +17,71 @@ function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 		options = columnsOrOptions ?? {};
 	}
 	if (columns.length === 0 && data.length === 0) return "";
-	const { delimiter = ",", addHeader = true, quoteAll = false, lineEnding = "\n" } = 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, {
-		delimiter,
-		quoteAll
-	});
-	const rows = data.map((obj) => columns.map((key) => formatCell(obj[key])).join(delimiter));
 	if (addHeader) {
-		const header = columns.map(formatCell).join(delimiter);
-		if (rows.length === 0) return header;
-		return header + lineEnding + rows.join(lineEnding);
+		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 rows.join(lineEnding);
+	return data.map((row) => encodeCSVRow(row, columns, delimiter, quoteAll)).join(lineEnding);
+}
+/**
+* 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)
+* }
+*/
+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}"`);
+	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
+	})).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.
@@ -37,12 +96,118 @@ function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 * 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.
 *
@@ -60,66 +225,57 @@ 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;
-	}
-	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}`);
-	}
-	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];
-		}));
+	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();
+	}
+	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
@@ -137,4 +293,4 @@ function inferColumns(rows) {
 }
 
 //#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 { CSVCreateOptions, 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, CSVCreateOptions, 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.3.0",
+  "version": "2.4.0",
   "packageManager": "pnpm@10.21.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",