utilful 2.5.3 → 3.0.0

package/dist/csv.mjs

@@ -6,6 +6,7 @@ const CARRIAGE_RETURN = "\r";
 const ESCAPED_QUOTE = "\"\"";
 const SPACE = " ";
 const TAB = "	";
+const BYTE_ORDER_MARK = "";
 function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 	let columns;
 	let options;
@@ -18,7 +19,7 @@ function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 	}
 	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}"`);
+	assertValidCSVDelimiter(delimiter);
 	if (addHeader) {
 		const header = encodeCSVHeader(columns.map(String), delimiter, quoteAll);
 		if (data.length === 0) return header;
@@ -46,7 +47,7 @@ function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 */
 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}"`);
+	assertValidCSVDelimiter(delimiter);
 	if (addHeader) yield encodeCSVHeader(columns.map(String), delimiter, quoteAll) + lineEnding;
 	for await (const row of data) yield encodeCSVRow(row, columns, delimiter, quoteAll) + lineEnding;
 }
@@ -71,6 +72,10 @@ async function createCSVAsync(data, columns, options = {}) {
 	for await (const chunk of createCSVStream(data, columns, options)) chunks.push(chunk);
 	return chunks.join("");
 }
+function assertValidCSVDelimiter(delimiter) {
+	if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
+	if (delimiter === DOUBLE_QUOTE || delimiter === NEWLINE || delimiter === CARRIAGE_RETURN) throw new RangeError(`CSV delimiter must not be a quote or line break character, got ${JSON.stringify(delimiter)}`);
+}
 function encodeCSVHeader(columns, delimiter, quoteAll) {
 	return columns.map((col) => escapeCSVValue(col, {
 		delimiter,
@@ -100,35 +105,54 @@ function escapeCSVValue(value, options = {}) {
 	if (value == null) return "";
 	const coercedValue = String(value);
 	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}`;
+	if (quoteAll || coercedValue.includes(delimiter) || hasQuote || coercedValue.includes(NEWLINE) || coercedValue.includes(CARRIAGE_RETURN)) {
+		const escaped = hasQuote ? coercedValue.replaceAll(DOUBLE_QUOTE, ESCAPED_QUOTE) : coercedValue;
+		return `${DOUBLE_QUOTE}${escaped}${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.currentRow = [];
+		this.currentField = "";
+		this.inQuotes = false;
+		this.isFieldQuoted = false;
+		this.currentRowNumber = 1;
+		this.isAtInputStart = true;
+		this.pendingChunkTail = "";
+		const { delimiter = COMMA, trim = false, strict = true } = options;
+		assertValidCSVDelimiter(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] : "";
+		let pendingText = this.pendingChunkTail + chunk;
+		this.pendingChunkTail = "";
+		if (this.isAtInputStart && pendingText.length > 0) {
+			if (pendingText[0] === BYTE_ORDER_MARK) pendingText = pendingText.slice(1);
+			this.isAtInputStart = false;
+		}
+		let holdbackIndex = pendingText.length;
+		while (holdbackIndex > 0 && pendingText[holdbackIndex - 1] === DOUBLE_QUOTE) holdbackIndex--;
+		if (holdbackIndex === pendingText.length && holdbackIndex > 0 && pendingText[holdbackIndex - 1] === CARRIAGE_RETURN) holdbackIndex--;
+		this.pendingChunkTail = pendingText.slice(holdbackIndex);
+		this.consume(pendingText.slice(0, holdbackIndex));
+	}
+	finish() {
+		if (this.pendingChunkTail.length > 0) {
+			const chunkTail = this.pendingChunkTail;
+			this.pendingChunkTail = "";
+			this.consume(chunkTail);
+		}
+		if (this.inQuotes) throw new SyntaxError(`CSV contains unterminated quoted field at row ${this.currentRowNumber}`);
+		if (this.currentField !== "" || this.currentRow.length > 0) this.appendRow();
+	}
+	consume(text) {
+		for (let i = 0; i < text.length; i++) {
+			const character = text[i];
+			const nextCharacter = i + 1 < text.length ? text[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;
@@ -145,74 +169,52 @@ var CSVParserCore = class {
 			} 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);
+		const fieldValue = this.trim && !this.isFieldQuoted ? this.currentField.trim() : this.currentField;
+		this.currentRow.push(fieldValue);
 		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);
+		if (this.headers) this.processDataRow(this.currentRow, this.headers);
+		else this.processHeaderRow(this.currentRow);
 		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();
+	processHeaderRow(headers) {
+		const emptyHeaderPositions = headers.map((header, index) => header.length === 0 ? index + 1 : -1).filter((position) => position > 0);
+		if (emptyHeaderPositions.length > 0) throw new SyntaxError(`CSV header row contains empty column name(s) at position(s): ${emptyHeaderPositions.join(", ")}`);
+		const seenHeaderNames = /* @__PURE__ */ new Set();
 		const duplicateHeaderNames = /* @__PURE__ */ new Set();
-		for (const header of headers) if (headerSet.has(header)) duplicateHeaderNames.add(header);
-		else headerSet.add(header);
+		for (const header of headers) if (seenHeaderNames.has(header)) duplicateHeaderNames.add(header);
+		else seenHeaderNames.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}`);
-			}
+	processDataRow(fieldValues, headers) {
+		if (fieldValues.length === 1 && fieldValues[0].length === 0) return;
+		if (this.strict) {
+			if (fieldValues.length > headers.length) {
+				if (fieldValues.slice(headers.length).some((fieldValue) => fieldValue.length > 0)) throw new SyntaxError(`CSV row ${this.currentRowNumber} has ${fieldValues.length - headers.length} extra field(s): expected ${headers.length} column(s), found ${fieldValues.length}`);
+			} else if (fieldValues.length < headers.length) throw new SyntaxError(`CSV row ${this.currentRowNumber} has ${headers.length - fieldValues.length} missing field(s): expected ${headers.length} column(s), found ${fieldValues.length}`);
 		}
-		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);
+		const rowEntries = headers.map((header, columnIndex) => [header, fieldValues[columnIndex] ?? ""]);
+		this.onRow(Object.fromEntries(rowEntries));
 	}
 };
 /**
 * Parses a comma-separated values (CSV) string into an array of objects.
 *
 * @remarks
-* The first row of the CSV string is used as the header row.
+* The first row of the CSV string is used as the header row. A leading
+* UTF-8 byte order mark is stripped.
+*
+* Parsing tolerances (lenient deviations from RFC 4180):
+* - LF, CR, and CRLF line endings are all accepted
+* - Whitespace between a closing quote and the next delimiter or line break is ignored
+* - A field is only treated as quoted if it starts with a quote; quotes inside
+*   unquoted fields are kept as literal characters
 *
 * @example
 * const csv = `name,age
@@ -260,24 +262,6 @@ async function* parseCSVStream(chunks, options = {}) {
 	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.
 */
@@ -292,4 +276,4 @@ function inferColumns(rows) {
 	return columns;
 }
 //#endregion
-export { createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream };
+export { createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVStream };

package/dist/defu.d.mts

@@ -2,13 +2,19 @@
 type PlainObject = Record<PropertyKey, any>;
 type DefuMerger<T extends PlainObject = PlainObject> = (target: T, key: PropertyKey, value: any, namespace: string) => boolean | void;
 /**
-* Defu function type that accepts a source and multiple defaults
-*/
-type DefuFn = <T extends PlainObject>(source: T, ...defaults: PlainObject[]) => T;
+ * Deeply merged result type of a source object over a list of defaults.
+ */
+type Defu<Source, Defaults extends any[]> = Defaults extends [infer First, ...infer Rest] ? Defu<MergedObject<Source, First>, Rest> : Source;
+type MergedObject<Source, Defaults> = Source extends PlainObject ? Defaults extends PlainObject ? { [Key in keyof Source | keyof Defaults]: MergedValue<Key extends keyof Source ? Source[Key] : undefined, Key extends keyof Defaults ? Defaults[Key] : undefined>; } : Source : Source;
+type MergedValue<SourceValue, DefaultValue> = SourceValue extends null | undefined ? DefaultValue : SourceValue extends any[] ? DefaultValue extends any[] ? Array<SourceValue[number] | DefaultValue[number]> : SourceValue : SourceValue extends ((...args: any[]) => any) ? SourceValue : SourceValue extends PlainObject ? MergedObject<SourceValue, DefaultValue> : SourceValue;
 /**
-* Create a defu function with optional custom merger
-*/
+ * Defu function type that accepts a source and multiple defaults
+ */
+type DefuFn = <Source extends PlainObject, Defaults extends PlainObject[]>(source: Source, ...defaults: Defaults) => Defu<Source, Defaults>;
+/**
+ * Create a defu function with optional custom merger
+ */
 declare function createDefu(merger?: DefuMerger): DefuFn;
 declare const defu: DefuFn;
 //#endregion
-export { DefuFn, DefuMerger, createDefu, defu };
+export { Defu, DefuFn, DefuMerger, createDefu, defu };

package/dist/defu.mjs

@@ -3,9 +3,9 @@
 * Create a defu function with optional custom merger
 */
 function createDefu(merger) {
-	return (source, ...defaults) => {
-		return defaults.reduce((acc, current) => _defu(acc, current ?? {}, "", merger), source ?? {});
-	};
+	return ((source, ...defaults) => {
+		return defaults.reduce((mergedResult, currentDefaults) => _defu(mergedResult, currentDefaults ?? {}, "", merger), source ?? {});
+	});
 }
 const defu = createDefu();
 function _defu(source, defaults, namespace = "", merger) {

package/dist/emitter.d.mts

@@ -15,11 +15,11 @@ interface Emitter<Events extends Record<EventType, unknown>> {
   emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
 }
 /**
-* Simple functional event emitter / pubsub.
-*
-* @remarks Ported from `mitt`.
-* @see https://github.com/developit/mitt
-*/
+ * Simple functional event emitter / pubsub.
+ *
+ * @remarks Ported from `mitt`.
+ * @see https://github.com/developit/mitt
+ */
 declare function createEmitter<Events extends Record<EventType, unknown>>(events?: EventHandlerMap<Events>): Emitter<Events>;
 //#endregion
 export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter };

package/dist/emitter.mjs

@@ -8,17 +8,42 @@
 function createEmitter(events) {
 	events ||= /* @__PURE__ */ new Map();
 	return {
+		/**
+		* A Map of event names to registered handler functions.
+		*/
 		events,
+		/**
+		* Register an event handler for the given type.
+		*
+		* @memberOf createEmitter
+		*/
 		on(type, handler) {
 			const handlers = events.get(type);
 			if (handlers) handlers.push(handler);
 			else events.set(type, [handler]);
 		},
+		/**
+		* Remove an event handler for the given type.
+		*
+		* @remarks
+		* If `handler` is omitted, all handlers of the given type are removed.
+		*
+		* @memberOf createEmitter
+		*/
 		off(type, handler) {
 			const handlers = events.get(type);
 			if (handlers) if (handler) handlers.splice(handlers.indexOf(handler) >>> 0, 1);
 			else events.set(type, []);
 		},
+		/**
+		* Invoke all handlers for the given type.
+		*
+		* @remarks
+		* If present, `'*'` handlers are invoked after type-matched handlers.
+		* Manually firing '*' handlers is not supported.
+		*
+		* @memberOf createEmitter
+		*/
 		emit(type, evt) {
 			let handlers = events.get(type);
 			if (handlers) for (const handler of [...handlers]) handler(evt);

package/dist/index.d.mts

@@ -1,12 +1,12 @@
 import { MaybeArray, toArray } from "./array.mjs";
-import { CSVCreateOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream } from "./csv.mjs";
-import { DefuFn, DefuMerger, createDefu, defu } from "./defu.mjs";
+import { CSVCreateOptions, CSVParseOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVStream } from "./csv.mjs";
+import { Defu, 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";
+import { tryParseJSON } from "./json.mjs";
 import { interopDefault } from "./module.mjs";
 import { deepApply, isObject, memoize, objectEntries, objectKeys } from "./object.mjs";
 import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
 import { Err, ErrData, Ok, OkData, Result, ResultData, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
-import { TEMPLATE_PLACEHOLDER_RE, generateRandomId, template } from "./string.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, TEMPLATE_PLACEHOLDER_RE, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { AutocompletableString, BrandedType, CSVCreateOptions, CSVParseOptions, CSVRow, Defu, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/index.mjs

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

package/dist/json.d.mts

@@ -1,17 +1,10 @@
 //#region src/json.d.ts
 /**
-* Type-safe wrapper around `JSON.stringify`.
-*
-* @remarks
-* Falls back to the original value if the JSON serialization fails or the value is not a string.
-*/
+ * Type-safe wrapper around `JSON.parse`.
+ *
+ * @remarks
+ * Falls back to the original value if parsing fails or the value is not a string.
+ */
 declare function tryParseJSON<T = unknown>(value: unknown): T;
-/**
-* Clones the given JSON value.
-*
-* @remarks
-* The value must not contain circular references as JSON does not support them. It also must contain JSON serializable values.
-*/
-declare function cloneJSON<T>(value: T): T;
 //#endregion
-export { cloneJSON, tryParseJSON };
+export { tryParseJSON };

package/dist/json.mjs

@@ -1,9 +1,9 @@
 //#region src/json.ts
 /**
-* Type-safe wrapper around `JSON.stringify`.
+* Type-safe wrapper around `JSON.parse`.
 *
 * @remarks
-* Falls back to the original value if the JSON serialization fails or the value is not a string.
+* Falls back to the original value if parsing fails or the value is not a string.
 */
 function tryParseJSON(value) {
 	if (typeof value !== "string") return value;
@@ -13,21 +13,5 @@ function tryParseJSON(value) {
 		return value;
 	}
 }
-/**
-* Clones the given JSON value.
-*
-* @remarks
-* The value must not contain circular references as JSON does not support them. It also must contain JSON serializable values.
-*/
-function cloneJSON(value) {
-	if (typeof value !== "object" || value === null) return value;
-	if (Array.isArray(value)) return value.map((element) => typeof element !== "object" || element === null ? element : cloneJSON(element));
-	const result = {};
-	for (const key in value) {
-		const propertyValue = value[key];
-		result[key] = typeof propertyValue !== "object" || propertyValue === null ? propertyValue : cloneJSON(propertyValue);
-	}
-	return result;
-}
 //#endregion
-export { cloneJSON, tryParseJSON };
+export { tryParseJSON };

package/dist/module.d.mts

@@ -1,10 +1,10 @@
 //#region src/module.d.ts
 /**
-* Interop helper for default exports.
-*
-* @example
-* const mod = await interopDefault(import('./module.js'))
-*/
+ * Interop helper for default exports.
+ *
+ * @example
+ * const mod = await interopDefault(import('./module.js'))
+ */
 declare function interopDefault<T>(m: T | Promise<T>): Promise<T extends {
   default: infer U;
 } ? U : T>;

package/dist/module.mjs

@@ -7,7 +7,8 @@
 */
 async function interopDefault(m) {
 	const resolved = await m;
-	return resolved.default || resolved;
+	if (resolved != null && (typeof resolved === "object" || typeof resolved === "function") && "default" in resolved) return resolved.default;
+	return resolved;
 }
 //#endregion
 export { interopDefault };

package/dist/object.d.mts

@@ -1,36 +1,40 @@
 //#region src/object.d.ts
 /**
-* A simple general purpose memoizer utility.
-* - Lazily computes a value when accessed
-* - Auto-caches the result by overwriting the getter
-*
-* @remarks
-* Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
-*
-* @example
-* const myValue = lazy(() => 'Hello, World!')
-* console.log(myValue.value) // Computes value, overwrites getter
-* console.log(myValue.value) // Returns cached value
-* console.log(myValue.value) // Returns cached value
-*/
+ * A simple general purpose memoizer utility.
+ * - Lazily computes a value when accessed
+ * - Auto-caches the result by overwriting the getter
+ *
+ * @remarks
+ * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invocation, since the getter itself is overwritten with the memoized value.
+ *
+ * @example
+ * const myValue = memoize(() => 'Hello, World!')
+ * console.log(myValue.value) // Computes value, overwrites getter
+ * console.log(myValue.value) // Returns cached value
+ * console.log(myValue.value) // Returns cached value
+ */
 declare function memoize<T>(getter: () => T): {
   value: T;
 };
 /**
-* Strictly typed `Object.keys`.
-*/
-declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>;
+ * Strictly typed `Object.keys`.
+ */
+declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${Extract<keyof T, string | number>}`>;
 /**
-* Strictly typed `Object.entries`.
-*/
+ * Strictly typed `Object.entries`.
+ */
 declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>;
 /**
-* Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays.
-*/
+ * Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays (including arrays nested inside arrays).
+ */
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
 /**
-* Checks if a value is a plain object.
-*/
+ * Checks if a value is an object with the plain `[object Object]` tag.
+ *
+ * @remarks
+ * Returns `true` for object literals, class instances, and `null`-prototype
+ * objects – unlike stricter plain-object checks that reject class instances.
+ */
 declare function isObject(value: unknown): value is Record<any, any>;
 //#endregion
 export { deepApply, isObject, memoize, objectEntries, objectKeys };

package/dist/object.mjs

@@ -5,10 +5,10 @@
 * - Auto-caches the result by overwriting the getter
 *
 * @remarks
-* Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+* Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invocation, since the getter itself is overwritten with the memoized value.
 *
 * @example
-* const myValue = lazy(() => 'Hello, World!')
+* const myValue = memoize(() => 'Hello, World!')
 * console.log(myValue.value) // Computes value, overwrites getter
 * console.log(myValue.value) // Returns cached value
 * console.log(myValue.value) // Returns cached value
@@ -33,18 +33,24 @@ function objectEntries(obj) {
 	return Object.entries(obj);
 }
 /**
-* Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays.
+* Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays (including arrays nested inside arrays).
 */
 function deepApply(data, callback) {
 	for (const [key, value] of Object.entries(data)) {
 		callback(data, key, value);
-		if (Array.isArray(value)) {
-			for (const element of value) if (isObject(element)) deepApply(element, callback);
-		} else if (isObject(value)) deepApply(value, callback);
+		applyToNestedValue(value, callback);
 	}
 }
+function applyToNestedValue(value, callback) {
+	if (Array.isArray(value)) for (const element of value) applyToNestedValue(element, callback);
+	else if (isObject(value)) deepApply(value, callback);
+}
 /**
-* Checks if a value is a plain object.
+* Checks if a value is an object with the plain `[object Object]` tag.
+*
+* @remarks
+* Returns `true` for object literals, class instances, and `null`-prototype
+* objects – unlike stricter plain-object checks that reject class instances.
 */
 function isObject(value) {
 	return Object.prototype.toString.call(value) === "[object Object]";

package/dist/path.d.mts

@@ -2,42 +2,46 @@
 type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined;
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
 /**
-* Removes the leading slash from the given path if it has one.
-*/
+ * Removes the leading slash from the given path if it has one.
+ */
 declare function withoutLeadingSlash(path?: string): string;
 /**
-* Adds a leading slash to the given path if it does not already have one.
-*/
+ * Adds a leading slash to the given path if it does not already have one.
+ */
 declare function withLeadingSlash(path?: string): string;
 /**
-* Removes the trailing slash from the given path if it has one,
-* preserving query strings and hash fragments.
-*/
+ * Removes the trailing slash from the given path if it has one,
+ * preserving query strings and hash fragments.
+ */
 declare function withoutTrailingSlash(path?: string): string;
 /**
-* Adds a trailing slash to the given path if it does not already have one,
-* preserving query strings and hash fragments.
-*/
+ * Adds a trailing slash to the given path if it does not already have one,
+ * preserving query strings and hash fragments.
+ */
 declare function withTrailingSlash(path?: string): string;
 /**
-* Joins the given URL path segments, ensuring that there is only one slash between them.
-*/
+ * Joins the given URL path segments, ensuring that there is only one slash between them.
+ */
 declare function joinURL(...paths: (string | undefined)[]): string;
 /**
-* Adds the base path to the input path, if it is not already present.
-*/
+ * Adds the base path to the input path, if it is not already present.
+ */
 declare function withBase(input?: string, base?: string): string;
 /**
-* Removes the base path from the input path, if it is present.
-*/
+ * Removes the base path from the input path, if it is present.
+ */
 declare function withoutBase(input?: string, base?: string): string;
 /**
-* Returns the pathname of the given path, which is the path without the query string or hash.
-*/
+ * Returns the pathname of the given path, which is the path without the query string or hash.
+ *
+ * @remarks
+ * Absolute URLs (with a scheme, e.g. `https://example.com/foo`) return the URL's pathname.
+ * All other inputs are returned unchanged with the query string and hash removed.
+ */
 declare function getPathname(path?: string): string;
 /**
-* Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
-*/
+ * Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+ */
 declare function withQuery(input: string, query?: QueryObject): string;
 //#endregion
 export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };