utilful 2.0.0 → 2.1.1

package/README.md

@@ -8,6 +8,7 @@ A collection of TypeScript utilities that I use across my projects.
 - [API](#api)
   - [Array](#array)
   - [CSV](#csv)
+  - [Defu](#defu)
   - [Emitter](#emitter)
   - [JSON](#json)
   - [Module](#module)
@@ -111,6 +112,95 @@ Jane,25`
 const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
 ```
 
+### Defu
+
+Recursively assign default properties. Simplified version based on [unjs/defu](https://github.com/unjs/defu).
+
+#### `defu`
+
+Recursively assigns missing properties from defaults to the source object. The source object takes precedence over defaults.
+
+**Key Features:**
+
+- **Null/undefined 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
+- **Prototype pollution protection**: Ignores `__proto__` and `constructor` keys
+
+```ts
+type PlainObject = Record<PropertyKey, any>
+
+declare function defu<T extends PlainObject>(
+  source: T,
+  ...defaults: PlainObject[]
+): T
+```
+
+**Example:**
+
+```ts
+import { defu } from 'utilful'
+
+const result = defu(
+  { a: 1, b: { x: 1 } },
+  { a: 2, b: { y: 2 }, c: 3 }
+)
+// Result: { a: 1, b: { x: 1, y: 2 }, c: 3 }
+```
+
+**Array concatenation example:**
+
+```ts
+const result = defu(
+  { items: ['a', 'b'] },
+  { items: ['c', 'd'] }
+)
+// Result: { items: ['a', 'b', 'c', 'd'] }
+```
+
+**Null/undefined handling:**
+
+```ts
+const result = defu(
+  { name: null, age: undefined },
+  { name: 'John', age: 30, city: 'NYC' }
+)
+// Result: { name: 'John', age: 30, city: 'NYC' }
+```
+
+#### `createDefu`
+
+Creates a custom defu function with a custom merger.
+
+```ts
+type DefuMerger<T extends PlainObject = PlainObject> = (
+  target: T,
+  key: PropertyKey,
+  value: any,
+  namespace: string,
+) => boolean | void
+
+declare function createDefu(merger?: DefuMerger): DefuFn
+```
+
+**Example:**
+
+```ts
+import { createDefu } from 'utilful'
+
+// Custom merger that adds numbers instead of replacing them
+const addNumbers = createDefu((obj, key, val) => {
+  if (typeof val === 'number' && typeof obj[key] === 'number') {
+    obj[key] += val
+    return true // Indicates the merger handled this property
+  }
+})
+
+const result = addNumbers({ cost: 15 }, { cost: 10 })
+// Result: { cost: 25 }
+```
+
 ### Emitter
 
 Tiny functional event emitter / pubsub, based on [mitt](https://github.com/developit/mitt).
@@ -386,7 +476,7 @@ Shorthand function to create an `Ok` result. Use it to wrap a successful value.
 **Type Definition:**
 
 ```ts
-function ok<T>(value: T): Ok<T>
+declare function ok<T>(value: T): Ok<T>
 ```
 
 #### `err`
@@ -396,8 +486,8 @@ Shorthand function to create an `Err` result. Use it to wrap an error value.
 **Type Definition:**
 
 ```ts
-function err<E extends string = string>(err: E): Err<E>
-function err<E = unknown>(err: E): Err<E>
+declare function err<E extends string = string>(err: E): Err<E>
+declare function err<E = unknown>(err: E): Err<E>
 ```
 
 #### `toResult`
@@ -407,8 +497,8 @@ Wraps a function that might throw an error and returns a `Result` with the resul
 **Type Definition:**
 
 ```ts
-function toResult<T, E = unknown>(fn: () => T): Result<T, E>
-function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
+declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>
+declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
 ```
 
 #### `unwrapResult`
@@ -425,9 +515,9 @@ const { value, error } = unwrapResult(result)
 **Type Definition:**
 
 ```ts
-function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
-function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
-function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
+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 }
 ```
 
 #### `tryCatch`
@@ -449,8 +539,8 @@ const { value, error } = await tryCatch(fetch('https://api.example.com/data').th
 **Type Definition:**
 
 ```ts
-function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
-function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
+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

package/dist/array.d.ts

@@ -1,10 +1,11 @@
+//#region src/array.d.ts
 /**
- * Represents a value that can be either a single value or an array of values.
- */
+* Represents a value that can be either a single value or an array of values.
+*/
 type MaybeArray<T> = T | T[];
 /**
- * Converts `MaybeArray<T>` to `Array<T>`.
- */
+* Converts `MaybeArray<T>` to `Array<T>`.
+*/
 declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[];
-
-export { type MaybeArray, toArray };
+//#endregion
+export { MaybeArray, toArray };

package/dist/array.js

@@ -0,0 +1,11 @@
+//#region src/array.ts
+/**
+* Converts `MaybeArray<T>` to `Array<T>`.
+*/
+function toArray(array) {
+	array ??= [];
+	return Array.isArray(array) ? array : [array];
+}
+
+//#endregion
+export { toArray };

package/dist/csv.d.ts

@@ -1,67 +1,68 @@
+//#region src/csv.d.ts
 /**
- * Represents a row in a CSV file with column names of type T.
- */
+* Represents a row in a CSV file with column names of type T.
+*/
 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.
- *
- * @example
- * const data = [
- *   { name: 'John', age: '30', city: 'New York' },
- *   { name: 'Jane', age: '25', city: 'Boston' }
- * ]
- *
- * const csv = createCSV(data, ['name', 'age'])
- * // name,age
- * // John,30
- * // Jane,25
- */
+* Converts an array of objects to a comma-separated values (CSV) string
+* that contains only the `columns` specified.
+*
+* @example
+* const data = [
+*   { name: 'John', age: '30', city: 'New York' },
+*   { name: 'Jane', age: '25', city: 'Boston' }
+* ]
+*
+* const csv = createCSV(data, ['name', 'age'])
+* // name,age
+* // John,30
+* // Jane,25
+*/
 declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: (keyof T)[], options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default true */
-    addHeader?: boolean;
-    /** @default false */
-    quoteAll?: boolean;
+  /** @default ',' */
+  delimiter?: string;
+  /** @default true */
+  addHeader?: boolean;
+  /** @default false */
+  quoteAll?: boolean;
 }): string;
 /**
- * Escapes a value for a CSV string.
- *
- * @remarks
- * Returns an empty string if the value is `null` or `undefined`.
- * Values containing delimiters, quotes, or line breaks are quoted.
- * Within quoted values, double quotes are escaped by doubling them.
- *
- * @example
- * escapeCSVValue('hello, world') // "hello, world"
- * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
- */
+* Escapes a value for a CSV string.
+*
+* @remarks
+* Returns an empty string if the value is `null` or `undefined`.
+* Values containing delimiters, quotes, or line breaks are quoted.
+* Within quoted values, double quotes are escaped by doubling them.
+*
+* @example
+* escapeCSVValue('hello, world') // "hello, world"
+* escapeCSVValue('contains "quotes"') // "contains ""quotes"""
+*/
 declare function escapeCSVValue(value: unknown, options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default false */
-    quoteAll?: boolean;
+  /** @default ',' */
+  delimiter?: string;
+  /** @default false */
+  quoteAll?: boolean;
 }): string;
 /**
- * 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.
- *
- * @example
- * const csv = `name,age
- * John,30
- * Jane,25`
- *
- * const data = parseCSV<'name' | 'age'>(csv)
- * // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
- */
+* 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.
+*
+* @example
+* const csv = `name,age
+* John,30
+* Jane,25`
+*
+* const data = parseCSV<'name' | 'age'>(csv)
+* // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
+*/
 declare function parseCSV<Header extends string>(csv?: string | null | undefined, options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default true */
-    trimValues?: boolean;
+  /** @default ',' */
+  delimiter?: string;
+  /** @default true */
+  trimValues?: boolean;
 }): CSVRow<Header>[];
-
-export { type CSVRow, createCSV, escapeCSVValue, parseCSV };
+//#endregion
+export { CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.js

@@ -0,0 +1,98 @@
+//#region src/csv.ts
+/**
+* Converts an array of objects to a comma-separated values (CSV) string
+* that contains only the `columns` specified.
+*
+* @example
+* const data = [
+*   { name: 'John', age: '30', city: 'New York' },
+*   { name: 'Jane', age: '25', city: 'Boston' }
+* ]
+*
+* const csv = createCSV(data, ['name', 'age'])
+* // name,age
+* // John,30
+* // Jane,25
+*/
+function createCSV(data, columns, options = {}) {
+	const { delimiter = ",", addHeader = true, quoteAll = false } = options;
+	const escapeAndQuote = (value) => escapeCSVValue(value, {
+		delimiter,
+		quoteAll
+	});
+	const rows = data.map((obj) => columns.map((key) => escapeAndQuote(obj[key])).join(delimiter));
+	if (addHeader) rows.unshift(columns.map(escapeAndQuote).join(delimiter));
+	return rows.join("\n");
+}
+/**
+* Escapes a value for a CSV string.
+*
+* @remarks
+* Returns an empty string if the value is `null` or `undefined`.
+* Values containing delimiters, quotes, or line breaks are quoted.
+* Within quoted values, double quotes are escaped by doubling them.
+*
+* @example
+* escapeCSVValue('hello, world') // "hello, world"
+* escapeCSVValue('contains "quotes"') // "contains ""quotes"""
+*/
+function escapeCSVValue(value, options = {}) {
+	const { delimiter = ",", quoteAll = false } = options;
+	if (value == null) return "";
+	const stringValue = String(value);
+	const needsQuoting = quoteAll || stringValue.includes(delimiter) || stringValue.includes("\"") || stringValue.includes("\n") || stringValue.includes("\r");
+	if (needsQuoting) return `"${stringValue.replaceAll("\"", "\"\"")}"`;
+	return stringValue;
+}
+/**
+* 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.
+*
+* @example
+* const csv = `name,age
+* John,30
+* Jane,25`
+*
+* const data = parseCSV<'name' | 'age'>(csv)
+* // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
+*/
+function parseCSV(csv, options = {}) {
+	if (!csv?.trim()) return [];
+	const rows = [];
+	let currentRow = [];
+	let currentField = "";
+	let inQuotes = false;
+	const { delimiter = ",", trimValues = true } = options;
+	for (let i = 0; i < csv.length; i++) {
+		const char = csv[i];
+		const nextChar = i + 1 < csv.length ? csv[i + 1] : "";
+		if (char === "\"") if (inQuotes && nextChar === "\"") {
+			currentField += "\"";
+			i++;
+		} else inQuotes = !inQuotes;
+		else if (char === delimiter && !inQuotes) {
+			currentRow.push(trimValues ? currentField.trim() : currentField);
+			currentField = "";
+		} else if ((char === "\n" || char === "\r" && nextChar === "\n") && !inQuotes) {
+			if (char === "\r") i++;
+			currentRow.push(trimValues ? currentField.trim() : currentField);
+			rows.push(currentRow);
+			currentRow = [];
+			currentField = "";
+		} else currentField += char;
+	}
+	if (currentField || currentRow.length > 0) {
+		currentRow.push(trimValues ? currentField.trim() : currentField);
+		rows.push(currentRow);
+	}
+	if (rows.length <= 1) return [];
+	const headers = rows[0];
+	return rows.slice(1).filter((row) => row.some((field) => field.trim().length > 0)).map((values) => {
+		return Object.fromEntries(headers.map((header, index) => [header, index < values.length ? values[index] : ""]));
+	});
+}
+
+//#endregion
+export { createCSV, escapeCSVValue, parseCSV };

package/dist/defu.d.ts

@@ -0,0 +1,15 @@
+//#region src/defu.d.ts
+// Forked from unjs/defu (MIT)
+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;
+/**
+* Create a defu function with optional custom merger
+*/
+declare function createDefu(merger?: DefuMerger): DefuFn;
+declare const defu: DefuFn;
+//#endregion
+export { DefuFn, DefuMerger, createDefu, defu };

package/dist/defu.js

@@ -0,0 +1,34 @@
+//#region src/defu.ts
+/**
+* Create a defu function with optional custom merger
+*/
+function createDefu(merger) {
+	return (source, ...defaults) => {
+		return defaults.reduce((acc, current) => _defu(acc, current ?? {}, "", merger), source ?? {});
+	};
+}
+const defu = createDefu();
+function _defu(source, defaults, namespace = "", merger) {
+	if (!isPlainObject(defaults)) return source;
+	const result = { ...defaults };
+	for (const [key, value] of Object.entries(source)) {
+		if (key === "__proto__" || key === "constructor") continue;
+		if (value == null) continue;
+		if (merger?.(result, key, value, namespace)) continue;
+		const currentNamespace = namespace ? `${namespace}.${key}` : key;
+		if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [...value, ...result[key]];
+		else if (isPlainObject(value) && isPlainObject(result[key])) result[key] = _defu(value, result[key], currentNamespace, merger);
+		else result[key] = value;
+	}
+	return result;
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== null && prototype !== Object.prototype && Object.getPrototypeOf(prototype) !== null) return false;
+	if (Symbol.iterator in value) return false;
+	return true;
+}
+
+//#endregion
+export { createDefu, defu };

package/dist/emitter.d.ts

@@ -1,24 +1,29 @@
+//#region src/emitter.d.ts
+/* eslint-disable ts/method-signature-style */
 type EventType = string | symbol;
+// An event handler can take an optional event argument
+// and should not return a value
 type Handler<T = unknown> = (event: T) => void;
 type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
 type EventHandlerList<T = unknown> = Handler<T>[];
 type WildCardEventHandlerList<T = Record<string, unknown>> = WildcardHandler<T>[];
-type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | '*', EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
+// A map of event types and their corresponding event handlers.
+type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | "*", EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
 interface Emitter<Events extends Record<EventType, unknown>> {
-    events: EventHandlerMap<Events>;
-    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
-    on(type: '*', handler: WildcardHandler<Events>): void;
-    off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
-    off(type: '*', handler: WildcardHandler<Events>): void;
-    emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
-    emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
+  events: EventHandlerMap<Events>;
+  on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
+  on(type: "*", handler: WildcardHandler<Events>): void;
+  off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
+  off(type: "*", handler: WildcardHandler<Events>): void;
+  emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
+  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>;
-
-export { type Emitter, type EventHandlerList, type EventHandlerMap, type EventType, type Handler, type WildCardEventHandlerList, type WildcardHandler, createEmitter };
+//#endregion
+export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter };

package/dist/emitter.js

@@ -0,0 +1,32 @@
+//#region src/emitter.ts
+/**
+* Simple functional event emitter / pubsub.
+*
+* @remarks Ported from `mitt`.
+* @see https://github.com/developit/mitt
+*/
+function createEmitter(events) {
+	events ||= /* @__PURE__ */ new Map();
+	return {
+		events,
+		on(type, handler) {
+			const handlers = events.get(type);
+			if (handlers) handlers.push(handler);
+			else events.set(type, [handler]);
+		},
+		off(type, handler) {
+			const handlers = events.get(type);
+			if (handlers) if (handler) handlers.splice(handlers.indexOf(handler) >>> 0, 1);
+			else events.set(type, []);
+		},
+		emit(type, evt) {
+			let handlers = events.get(type);
+			if (handlers) for (const handler of [...handlers]) handler(evt);
+			handlers = events.get("*");
+			if (handlers) for (const handler of [...handlers]) handler(type, evt);
+		}
+	};
+}
+
+//#endregion
+export { createEmitter };

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,12 @@
+import { toArray } from "./array.js";
+import { createCSV, escapeCSVValue, parseCSV } from "./csv.js";
+import { createDefu, defu } from "./defu.js";
+import { createEmitter } from "./emitter.js";
+import { cloneJSON, tryParseJSON } from "./json.js";
+import { interopDefault } from "./module.js";
+import { deepApply, memoize, objectEntries, objectKeys } from "./object.js";
+import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.js";
+import { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from "./result.js";
+import { generateRandomId, template } from "./string.js";
+
+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 };

package/dist/json.d.ts

@@ -1,16 +1,17 @@
+//#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.stringify`.
+*
+* @remarks
+* Falls back to the original value if the JSON serialization 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.
- */
+* 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;
-
-export { cloneJSON, tryParseJSON };
+//#endregion
+export { cloneJSON, tryParseJSON };

package/dist/json.js

@@ -0,0 +1,34 @@
+//#region src/json.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.
+*/
+function tryParseJSON(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		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((e) => typeof e !== "object" || e === null ? e : cloneJSON(e));
+	const result = {};
+	for (const k in value) {
+		const v = value[k];
+		result[k] = typeof v !== "object" || v === null ? v : cloneJSON(v);
+	}
+	return result;
+}
+
+//#endregion
+export { cloneJSON, tryParseJSON };