utilful 1.2.1 → 2.1.0

package/README.md

@@ -8,12 +8,13 @@ A collection of TypeScript utilities that I use across my projects.
 - [API](#api)
   - [Array](#array)
   - [CSV](#csv)
+  - [Defu](#defu)
   - [Emitter](#emitter)
   - [JSON](#json)
-  - [Lazy](#lazy)
   - [Module](#module)
   - [Object](#object)
   - [Path](#path)
+  - [Result](#result)
   - [String](#string)
 
 ## Installation
@@ -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).
@@ -168,29 +258,6 @@ Clones the given JSON value.
 declare function cloneJSON<T>(value: T): T
 ```
 
-### Lazy
-
-A simple general purpose memoizer utility.
-
-- Lazily computes a value when accessed
-- Auto-caches the result by overwriting the getter
-- Typesafe
-
-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.
-
-```ts
-declare function lazy<T>(getter: () => T): { value: T }
-```
-
-**Example:**
-
-```ts
-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
-```
-
 ### Module
 
 #### `interopDefault`
@@ -215,6 +282,28 @@ async function loadModule() {
 
 ### Object
 
+#### `memoize`
+
+A simple general purpose memoizer utility.
+
+- Lazily computes a value when accessed
+- Auto-caches the result by overwriting the getter
+
+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.
+
+```ts
+declare function memoize<T>(getter: () => T): { value: T }
+```
+
+**Example:**
+
+```ts
+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
+```
+
 #### `objectKeys`
 
 Strictly typed `Object.keys`.
@@ -327,6 +416,133 @@ const url = withQuery('https://example.com', {
 })
 ```
 
+### Result
+
+The `Result` type that represents either success (`Ok`) or failure (`Err`). It helps to handle errors in a more explicit and type-safe way, without relying on exceptions.
+
+A common use case for `Result` is error handling in functions that might fail. Here's an example of a function that divides two numbers and returns a `Result`:
+
+```ts
+import { err, ok } from 'utilful'
+
+function divide(a: number, b: number) {
+  if (b === 0) {
+    return err('Division by zero')
+  }
+  return ok(a / b)
+}
+
+const result = divide(10, 2)
+if (result.ok)
+  console.log('Result:', result.value)
+else
+  console.error('Error:', result.error)
+```
+
+#### `Result`
+
+The `Result` type represents either success (`Ok`) or failure (`Err`).
+
+**Type Definition:**
+
+```ts
+type Result<T, E> = Ok<T> | Err<E>
+```
+
+#### `Ok`
+
+The `Ok` type wraps a successful value.
+
+**Example:**
+
+```ts
+const result = new Ok(42)
+```
+
+#### `Err`
+
+The `Err` type wraps an error value.
+
+**Example:**
+
+```ts
+const result = new Err('Something went wrong')
+```
+
+#### `ok`
+
+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>
+```
+
+#### `err`
+
+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>
+```
+
+#### `toResult`
+
+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>>
+```
+
+#### `unwrapResult`
+
+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)
+```
+
+**Type Definition:**
+
+```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 }
+```
+
+#### `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.
+
+**Example:**
+
+```ts
+import { tryCatch } from 'utilful'
+
+// Synchronous usage
+const { value, error } = tryCatch(() => JSON.parse('{"foo":"bar"}'))
+
+// Asynchronous usage
+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/array.d.ts

@@ -1,10 +1,12 @@
+//#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,67 @@
+//#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;
-}): CSVRow<Header>[];
-
-export { type CSVRow, createCSV, escapeCSVValue, parseCSV };
+  /** @default ',' */
+  delimiter?: string;
+  /** @default true */
+  trimValues?: boolean;
+}): CSVRow<Header>[]; //#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,16 @@
+//#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 as createDefu$1, defu as defu$1 };

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,30 @@
+//#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 ||= 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 };