utilful 2.0.0 → 2.1.0

package/dist/module.d.ts

@@ -1,11 +1,13 @@
+//#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;
+  default: infer U;
 } ? U : T>;
 
-export { interopDefault };
+//#endregion
+export { interopDefault };

package/dist/module.js

@@ -0,0 +1,14 @@
+//#region src/module.ts
+/**
+* Interop helper for default exports.
+*
+* @example
+* const mod = await interopDefault(import('./module.js'))
+*/
+async function interopDefault(m) {
+	const resolved = await m;
+	return resolved.default || resolved;
+}
+
+//#endregion
+export { interopDefault };

package/dist/object.d.ts

@@ -1,31 +1,33 @@
+//#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 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
+*/
 declare function memoize<T>(getter: () => T): {
-    value: T;
+  value: T;
 };
 /**
- * Strictly typed `Object.keys`.
- */
+* 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.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.
+*/
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
 
-export { deepApply, memoize, objectEntries, objectKeys };
+//#endregion
+export { deepApply, memoize, objectEntries, objectKeys };

package/dist/object.js

@@ -0,0 +1,51 @@
+//#region src/object.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
+*/
+function memoize(getter) {
+	return { get value() {
+		const value = getter();
+		Object.defineProperty(this, "value", { value });
+		return value;
+	} };
+}
+/**
+* Strictly typed `Object.keys`.
+*/
+function objectKeys(obj) {
+	return Object.keys(obj);
+}
+/**
+* Strictly typed `Object.entries`.
+*/
+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.
+*/
+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);
+	}
+}
+function isObject(value) {
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+//#endregion
+export { deepApply, memoize, objectEntries, objectKeys };

package/dist/path.d.ts

@@ -1,40 +1,42 @@
+//#region src/path.d.ts
 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.
- */
+* Removes the trailing slash from the given path if it has one.
+*/
 declare function withoutTrailingSlash(path?: string): string;
 /**
- * Adds a trailing slash to the given path if it does not already have one
- */
+* Adds a trailing slash to the given path if it does not already have one
+*/
 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.
- */
+* Returns the pathname of the given path, which is the path without the query string.
+*/
 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;
 
-export { type QueryObject, type QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+//#endregion
+export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/path.js

@@ -0,0 +1,105 @@
+//#region src/path.ts
+/**
+* Removes the leading slash from the given path if it has one.
+*/
+function withoutLeadingSlash(path) {
+	if (!path || path === "/") return "/";
+	return path[0] === "/" ? path.slice(1) : path;
+}
+/**
+* Adds a leading slash to the given path if it does not already have one.
+*/
+function withLeadingSlash(path) {
+	if (!path || path === "/") return "/";
+	return path[0] === "/" ? path : `/${path}`;
+}
+/**
+* Removes the trailing slash from the given path if it has one.
+*/
+function withoutTrailingSlash(path) {
+	if (!path || path === "/") return "/";
+	return path[path.length - 1] === "/" ? path.slice(0, -1) : path;
+}
+/**
+* Adds a trailing slash to the given path if it does not already have one
+*/
+function withTrailingSlash(path) {
+	if (!path || path === "/") return "/";
+	return path[path.length - 1] === "/" ? path : `${path}/`;
+}
+/**
+* Joins the given URL path segments, ensuring that there is only one slash between them.
+*/
+function joinURL(...paths) {
+	let result = "";
+	for (let i = 0; i < paths.length; i++) {
+		const path = paths[i];
+		if (!result || result === "/") {
+			result = path || "/";
+			continue;
+		}
+		if (!path || path === "/") continue;
+		const resultHasTrailing = result[result.length - 1] === "/";
+		const pathHasLeading = path[0] === "/";
+		if (resultHasTrailing && pathHasLeading) result += path.slice(1);
+		else if (!resultHasTrailing && !pathHasLeading) result += `/${path}`;
+		else result += path;
+	}
+	return result;
+}
+/**
+* Adds the base path to the input path, if it is not already present.
+*/
+function withBase(input = "", base = "") {
+	if (!base || base === "/") return input;
+	const _base = withoutTrailingSlash(base);
+	if (input.startsWith(_base)) return input;
+	return joinURL(_base, input);
+}
+/**
+* Removes the base path from the input path, if it is present.
+*/
+function withoutBase(input = "", base = "") {
+	if (!base || base === "/") return input;
+	const _base = withoutTrailingSlash(base);
+	if (!input.startsWith(_base)) return input;
+	const trimmed = input.slice(_base.length);
+	return trimmed[0] === "/" ? trimmed : `/${trimmed}`;
+}
+/**
+* Returns the pathname of the given path, which is the path without the query string.
+*/
+function getPathname(path = "/") {
+	return path.startsWith("/") ? path.split("?")[0] : new URL(path, "http://localhost").pathname;
+}
+/**
+* Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+*/
+function withQuery(input, query) {
+	if (!query || Object.keys(query).length === 0) return input;
+	const searchIndex = input.indexOf("?");
+	const hasExistingParams = searchIndex !== -1;
+	const base = hasExistingParams ? input.slice(0, searchIndex) : input;
+	const searchParams = hasExistingParams ? new URLSearchParams(input.slice(searchIndex + 1)) : new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0) {
+			searchParams.delete(key);
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length === 0) continue;
+			for (const item of value) if (item !== void 0) searchParams.append(key, normalizeQueryValue(item));
+		} else searchParams.set(key, normalizeQueryValue(value));
+	}
+	const queryString = searchParams.toString();
+	return queryString ? `${base}?${queryString}` : base;
+}
+function normalizeQueryValue(value) {
+	if (value === null) return "";
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+
+//#endregion
+export { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/result.d.ts

@@ -1,22 +1,23 @@
+//#region src/result.d.ts
 type Result<T, E> = Ok<T> | Err<E>;
 interface OkData<T> {
-    value: T;
-    error: undefined;
+  value: T;
+  error: undefined;
 }
 interface ErrData<E> {
-    value: undefined;
-    error: E;
+  value: undefined;
+  error: E;
 }
 type ResultData<T, E> = OkData<T> | ErrData<E>;
 declare class Ok<T> {
-    readonly value: T;
-    readonly ok = true;
-    constructor(value: T);
+  readonly value: T;
+  readonly ok: true;
+  constructor(value: T);
 }
 declare class Err<E> {
-    readonly error: E;
-    readonly ok = false;
-    constructor(error: E);
+  readonly error: E;
+  readonly ok: false;
+  constructor(error: E);
 }
 declare function ok<T>(value: T): Ok<T>;
 declare function err<E extends string = string>(error: E): Err<E>;
@@ -29,4 +30,5 @@ declare function unwrapResult<T, E>(result: Result<T, E>): ResultData<T, E>;
 declare function tryCatch<T, E = unknown>(fn: () => T): ResultData<T, E>;
 declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<ResultData<T, E>>;
 
-export { Err, type ErrData, Ok, type OkData, type Result, type ResultData, err, ok, toResult, tryCatch, unwrapResult };
+//#endregion
+export { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult };

package/dist/result.js

@@ -0,0 +1,45 @@
+//#region src/result.ts
+var Ok = class {
+	value;
+	ok = true;
+	constructor(value) {
+		this.value = value;
+	}
+};
+var Err = class {
+	error;
+	ok = false;
+	constructor(error) {
+		this.error = error;
+	}
+};
+function ok(value) {
+	return new Ok(value);
+}
+function err(error) {
+	return new Err(error);
+}
+function toResult(fnOrPromise) {
+	if (fnOrPromise instanceof Promise) return fnOrPromise.then(ok).catch(err);
+	try {
+		return ok(fnOrPromise());
+	} catch (error) {
+		return err(error);
+	}
+}
+function unwrapResult(result) {
+	return result.ok ? {
+		value: result.value,
+		error: void 0
+	} : {
+		value: void 0,
+		error: result.error
+	};
+}
+function tryCatch(fnOrPromise) {
+	if (fnOrPromise instanceof Promise) return toResult(fnOrPromise).then((result) => unwrapResult(result));
+	return unwrapResult(toResult(fnOrPromise));
+}
+
+//#endregion
+export { Err, Ok, err, ok, toResult, tryCatch, unwrapResult };

package/dist/string.d.ts

@@ -1,19 +1,21 @@
+//#region src/string.d.ts
 /**
- * Simple template engine to replace variables in a string.
- *
- * @example
- * const str = 'Hello, {name}!'
- * const variables = { name: 'world' }
- *
- * console.log(template(str, variables)) // Hello, world!
- */
+* Simple template engine to replace variables in a string.
+*
+* @example
+* const str = 'Hello, {name}!'
+* const variables = { name: 'world' }
+*
+* console.log(template(str, variables)) // Hello, world!
+*/
 declare function template(str: string, variables: Record<string | number, any>, fallback?: string | ((key: string) => string)): string;
 /**
- * Generates a random string.
- *
- * @remarks Ported from `nanoid`.
- * @see https://github.com/ai/nanoid
- */
+* Generates a random string.
+*
+* @remarks Ported from `nanoid`.
+* @see https://github.com/ai/nanoid
+*/
 declare function generateRandomId(size?: number, dict?: string): string;
 
-export { generateRandomId, template };
+//#endregion
+export { generateRandomId, template };

package/dist/string.js

@@ -0,0 +1,32 @@
+//#region src/string.ts
+const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+/**
+* Simple template engine to replace variables in a string.
+*
+* @example
+* const str = 'Hello, {name}!'
+* const variables = { name: 'world' }
+*
+* console.log(template(str, variables)) // Hello, world!
+*/
+function template(str, variables, fallback) {
+	return str.replace(/\{(\w+)\}/g, (_, key) => {
+		return variables[key] || ((typeof fallback === "function" ? fallback(key) : fallback) ?? key);
+	});
+}
+/**
+* Generates a random string.
+*
+* @remarks Ported from `nanoid`.
+* @see https://github.com/ai/nanoid
+*/
+function generateRandomId(size = 16, dict = URL_ALPHABET) {
+	let id = "";
+	let i = size;
+	const len = dict.length;
+	while (i--) id += dict[Math.random() * len | 0];
+	return id;
+}
+
+//#endregion
+export { generateRandomId, template };

package/dist/types.d.ts

@@ -1,8 +1,8 @@
+//#region src/types.d.ts
 type AutocompletableString = string & {};
 type LooseAutocomplete<T extends string> = T | AutocompletableString;
 /** Also commonly referred to as `Prettify` */
-type UnifyIntersection<T> = {
-    [K in keyof T]: T[K];
-} & {};
+type UnifyIntersection<T> = { [K in keyof T]: T[K] } & {};
 
-export type { AutocompletableString, LooseAutocomplete, UnifyIntersection };
+//#endregion
+export { AutocompletableString, LooseAutocomplete, UnifyIntersection };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.0.0",
-  "packageManager": "pnpm@10.5.2",
+  "version": "2.1.0",
+  "packageManager": "pnpm@10.11.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -28,9 +28,13 @@
       "types": "./dist/csv.d.mts",
       "default": "./dist/csv.mjs"
     },
+    "./defu": {
+      "types": "./dist/defu.d.mts",
+      "default": "./dist/defu.mjs"
+    },
     "./emitter": {
-      "types": "./dist/csv.d.mts",
-      "default": "./dist/csv.mjs"
+      "types": "./dist/emitter.d.mts",
+      "default": "./dist/emitter.mjs"
     },
     "./json": {
       "types": "./dist/json.d.mts",
@@ -66,7 +70,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "unbuild",
+    "build": "tsdown",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest",
@@ -74,17 +78,18 @@
     "release": "bumpp"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^4.3.0",
-    "@types/node": "^22.13.5",
-    "bumpp": "^10.0.3",
-    "eslint": "^9.21.0",
-    "typescript": "^5.7.3",
-    "unbuild": "^3.5.0",
-    "vitest": "^3.0.7"
+    "@antfu/eslint-config": "^4.13.2",
+    "@types/node": "^22.15.21",
+    "bumpp": "^10.1.1",
+    "eslint": "^9.27.0",
+    "tsdown": "^0.12.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
-      "esbuild"
+      "esbuild",
+      "unrs-resolver"
     ]
   }
 }

package/dist/array.d.mts

@@ -1,10 +0,0 @@
-/**
- * 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>`.
- */
-declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[];
-
-export { type MaybeArray, toArray };

package/dist/array.mjs

@@ -1,6 +0,0 @@
-function toArray(array) {
-  array ??= [];
-  return Array.isArray(array) ? array : [array];
-}
-
-export { toArray };

package/dist/csv.d.mts

@@ -1,67 +0,0 @@
-/**
- * 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
- */
-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;
-}): 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"""
- */
-declare function escapeCSVValue(value: unknown, options?: {
-    /** @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' }]
- */
-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 };