utilful 3.0.1 → 3.0.2

package/README.md

@@ -113,12 +113,12 @@ interface CSVParseOptions {
   /** @default ',' */
   delimiter?: string
   /**
-   * Trim whitespace from unquoted headers and values.
+   * Whether to trim whitespace from unquoted headers and values.
    * @default false
    */
   trim?: boolean
   /**
-   * Throw if a row's field count does not match the header row.
+   * Whether to throw if a row's field count does not match the header row.
    * @default true
    */
   strict?: boolean

package/dist/array.d.mts

@@ -1,11 +1,5 @@
 //#region src/array.d.ts
-/**
- * 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[];
 //#endregion
 export { MaybeArray, toArray };

package/dist/array.mjs

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

package/dist/csv.d.mts

@@ -1,11 +1,5 @@
 //#region src/csv.d.ts
-/**
- * Represents a row in a CSV file with column names of type T.
- */
 type CSVRow<T extends string = string> = Record<T, string>;
-/**
- * Options for the CSV creation functions.
- */
 interface CSVCreateOptions {
   /** @default ',' */
   delimiter?: string;
@@ -16,19 +10,16 @@ interface CSVCreateOptions {
   /** @default '\n' */
   lineEnding?: string;
 }
-/**
- * Options for the CSV parsing functions.
- */
 interface CSVParseOptions {
   /** @default ',' */
   delimiter?: string;
   /**
-   * Trim whitespace from unquoted headers and values.
+   * Whether to trim whitespace from unquoted headers and values.
    * @default false
    */
   trim?: boolean;
   /**
-   * Throw if a row's field count does not match the header row.
+   * Whether to throw if a row's field count does not match the header row.
    * @default true
    */
   strict?: boolean;
@@ -132,10 +123,10 @@ declare function escapeCSVValue(value: unknown, options?: {
  * 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
+ * - 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
+ *   unquoted fields are kept as literal characters.
  *
  * @example
  * const csv = `name,age

package/dist/csv.mjs

@@ -211,10 +211,10 @@ var CSVParserCore = class {
 * 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
+* - 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
+*   unquoted fields are kept as literal characters.
 *
 * @example
 * const csv = `name,age

package/dist/defu.d.mts

@@ -1,19 +1,28 @@
 //#region src/defu.d.ts
 type PlainObject = Record<PropertyKey, any>;
 type DefuMerger<T extends PlainObject = PlainObject> = (target: T, key: PropertyKey, value: any, namespace: string) => boolean | void;
+type Nullish = null | undefined | void;
+/**
+ * Values that `isPlainObject` rejects at runtime, so the merged type keeps them
+ * intact rather than recursing into them. `PlainObject` cannot draw this line
+ * itself: its `any` value type makes every object type satisfy it, classes and
+ * built-ins included.
+ */
+type NonPlainObject = ((...args: any[]) => any) | {
+  [Symbol.iterator]: any;
+} | Date | RegExp | Promise<any> | Error | WeakMap<object, any> | WeakSet<object>;
 /**
  * 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;
 /**
- * Defu function type that accepts a source and multiple defaults
+ * Source merged over one defaults object, rebuilding only the shared keys.
+ * Everything else passes through `Omit`, which is what keeps optionality,
+ * `readonly` and the nominal identity of classes intact.
  */
+type MergedObject<Source, Defaults> = Source extends PlainObject ? Defaults extends PlainObject ? Source extends Defaults ? Source : Omit<Source, keyof Source & keyof Defaults> & Omit<Defaults, keyof Source & keyof Defaults> & { -readonly [Key in keyof Source & keyof Defaults]: MergedValue<Source[Key], Defaults[Key]>; } : Source : Source;
+type MergedValue<SourceValue, DefaultValue> = SourceValue extends Nullish ? DefaultValue : DefaultValue extends Nullish ? SourceValue : SourceValue extends readonly any[] ? DefaultValue extends readonly any[] ? Array<SourceValue[number] | DefaultValue[number]> : SourceValue : SourceValue extends NonPlainObject ? SourceValue : DefaultValue extends NonPlainObject ? SourceValue : MergedObject<SourceValue, DefaultValue>;
 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

package/dist/defu.mjs

@@ -1,7 +1,4 @@
 //#region src/defu.ts
-/**
-* Create a defu function with optional custom merger
-*/
 function createDefu(merger) {
 	return ((source, ...defaults) => {
 		return defaults.reduce((mergedResult, currentDefaults) => _defu(mergedResult, currentDefaults ?? {}, "", merger), source ?? {});

package/dist/emitter.d.mts

@@ -15,7 +15,7 @@ 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.
+ * Creates a functional pubsub event emitter.
  *
  * @remarks Ported from `mitt`.
  * @see https://github.com/developit/mitt

package/dist/emitter.mjs

@@ -1,6 +1,6 @@
 //#region src/emitter.ts
 /**
-* Simple functional event emitter / pubsub.
+* Creates a functional pubsub event emitter.
 *
 * @remarks Ported from `mitt`.
 * @see https://github.com/developit/mitt
@@ -13,7 +13,7 @@ function createEmitter(events) {
 		*/
 		events,
 		/**
-		* Register an event handler for the given type.
+		* Registers an event handler for the given type.
 		*
 		* @memberOf createEmitter
 		*/
@@ -23,7 +23,7 @@ function createEmitter(events) {
 			else events.set(type, [handler]);
 		},
 		/**
-		* Remove an event handler for the given type.
+		* Removes an event handler for the given type.
 		*
 		* @remarks
 		* If `handler` is omitted, all handlers of the given type are removed.
@@ -36,11 +36,11 @@ function createEmitter(events) {
 			else events.set(type, []);
 		},
 		/**
-		* Invoke all handlers for the given type.
+		* Invokes all handlers for the given type.
 		*
 		* @remarks
 		* If present, `'*'` handlers are invoked after type-matched handlers.
-		* Manually firing '*' handlers is not supported.
+		* Manually firing `'*'` handlers is not supported.
 		*
 		* @memberOf createEmitter
 		*/

package/dist/json.d.mts

@@ -1,6 +1,6 @@
 //#region src/json.d.ts
 /**
- * Type-safe wrapper around `JSON.parse`.
+ * Wraps `JSON.parse` with a typed return value.
  *
  * @remarks
  * Falls back to the original value if parsing fails or the value is not a string.

package/dist/json.mjs

@@ -1,6 +1,6 @@
 //#region src/json.ts
 /**
-* Type-safe wrapper around `JSON.parse`.
+* Wraps `JSON.parse` with a typed return value.
 *
 * @remarks
 * Falls back to the original value if parsing fails or the value is not a string.

package/dist/module.d.mts

@@ -1,6 +1,6 @@
 //#region src/module.d.ts
 /**
- * Interop helper for default exports.
+ * Unwraps a module's `default` export, or returns the module unchanged if it has none.
  *
  * @example
  * const mod = await interopDefault(import('./module.js'))

package/dist/module.mjs

@@ -1,6 +1,6 @@
 //#region src/module.ts
 /**
-* Interop helper for default exports.
+* Unwraps a module's `default` export, or returns the module unchanged if it has none.
 *
 * @example
 * const mod = await interopDefault(import('./module.js'))

package/dist/object.d.mts

@@ -1,8 +1,6 @@
 //#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
+ * Wraps a getter so its value is computed on first access and cached from then on.
  *
  * @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.
@@ -17,11 +15,11 @@ declare function memoize<T>(getter: () => T): {
   value: T;
 };
 /**
- * Strictly typed `Object.keys`.
+ * Wraps `Object.keys` with a stricter return type.
  */
 declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${Extract<keyof T, string | number>}`>;
 /**
- * Strictly typed `Object.entries`.
+ * Wraps `Object.entries` with a stricter return type.
  */
 declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>;
 /**

package/dist/object.mjs

@@ -1,8 +1,6 @@
 //#region src/object.ts
 /**
-* A simple general purpose memoizer utility.
-* - Lazily computes a value when accessed
-* - Auto-caches the result by overwriting the getter
+* Wraps a getter so its value is computed on first access and cached from then on.
 *
 * @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.
@@ -21,13 +19,13 @@ function memoize(getter) {
 	} };
 }
 /**
-* Strictly typed `Object.keys`.
+* Wraps `Object.keys` with a stricter return type.
 */
 function objectKeys(obj) {
 	return Object.keys(obj);
 }
 /**
-* Strictly typed `Object.entries`.
+* Wraps `Object.entries` with a stricter return type.
 */
 function objectEntries(obj) {
 	return Object.entries(obj);

package/dist/path.d.mts

@@ -40,7 +40,7 @@ declare function withoutBase(input?: string, base?: string): 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;
 //#endregion

package/dist/path.mjs

@@ -101,7 +101,7 @@ function getPathname(path = "/") {
 	return path.slice(0, pathEnd) || "/";
 }
 /**
-* 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.
 */
 function withQuery(input, query) {
 	if (!query || Object.keys(query).length === 0) return input;

package/dist/result.d.mts

@@ -11,8 +11,8 @@ interface ErrData<E> {
 type ResultData<T, E> = OkData<T> | ErrData<E>;
 /**
  * Successful result variant.
- * @template T Success value type.
- * @template E Error type (phantom - for type unification).
+ * @template T Success value type
+ * @template E Error type (phantom – for type unification)
  */
 declare class Ok<T, E = never> {
   readonly value: T;
@@ -20,15 +20,15 @@ declare class Ok<T, E = never> {
   constructor(value: T);
   /** Transforms the success value. */
   map<U>(fn: (value: T) => U): Ok<U, E>;
-  /** No-op on Ok, returns self with new error type. */
+  /** Returns this `Ok` unchanged, with a new error type. */
   mapError<E2>(_fn: (error: E) => E2): Ok<T, E2>;
-  /** Chains a Result-returning function. */
+  /** Chains a `Result`-returning function. */
   andThen<U, E2>(fn: (value: T) => Result<U, E2>): Result<U, E | E2>;
   /** Extracts the value. */
   unwrap(_message?: string): T;
   /** Returns the value, ignoring the fallback. */
   unwrapOr<U>(_fallback: U): T;
-  /** Pattern matches on the Result. */
+  /** Pattern matches on the `Result`. */
   match<R>(handlers: {
     ok: (value: T) => R;
     err: (error: E) => R;
@@ -36,24 +36,24 @@ declare class Ok<T, E = never> {
 }
 /**
  * Error result variant.
- * @template T Success type (phantom - for type unification).
- * @template E Error value type.
+ * @template T Success type (phantom – for type unification)
+ * @template E Error value type
  */
 declare class Err<T, E> {
   readonly error: E;
   readonly ok = false;
   constructor(error: E);
-  /** No-op on Err, returns self with new value type. */
+  /** Returns this `Err` unchanged, with a new value type. */
   map<U>(_fn: (value: T) => U): Err<U, E>;
   /** Transforms the error value. */
   mapError<E2>(fn: (error: E) => E2): Err<T, E2>;
-  /** No-op on Err, returns self with widened error type. */
+  /** Returns this `Err` unchanged, with a widened error type. */
   andThen<U, E2>(_fn: (value: T) => Result<U, E2>): Err<U, E | E2>;
   /** Throws an error with the given message. */
   unwrap(message?: string): never;
   /** Returns the fallback value. */
   unwrapOr<U>(fallback: U): T | U;
-  /** Pattern matches on the Result. */
+  /** Pattern matches on the `Result`. */
   match<R>(handlers: {
     ok: (value: T) => R;
     err: (error: E) => R;

package/dist/result.mjs

@@ -1,8 +1,8 @@
 //#region src/result.ts
 /**
 * Successful result variant.
-* @template T Success value type.
-* @template E Error type (phantom - for type unification).
+* @template T Success value type
+* @template E Error type (phantom – for type unification)
 */
 var Ok = class Ok {
 	constructor(value) {
@@ -13,11 +13,11 @@ var Ok = class Ok {
 	map(fn) {
 		return new Ok(fn(this.value));
 	}
-	/** No-op on Ok, returns self with new error type. */
+	/** Returns this `Ok` unchanged, with a new error type. */
 	mapError(_fn) {
 		return this;
 	}
-	/** Chains a Result-returning function. */
+	/** Chains a `Result`-returning function. */
 	andThen(fn) {
 		return fn(this.value);
 	}
@@ -29,22 +29,22 @@ var Ok = class Ok {
 	unwrapOr(_fallback) {
 		return this.value;
 	}
-	/** Pattern matches on the Result. */
+	/** Pattern matches on the `Result`. */
 	match(handlers) {
 		return handlers.ok(this.value);
 	}
 };
 /**
 * Error result variant.
-* @template T Success type (phantom - for type unification).
-* @template E Error value type.
+* @template T Success type (phantom – for type unification)
+* @template E Error value type
 */
 var Err = class Err {
 	constructor(error) {
 		this.ok = false;
 		this.error = error;
 	}
-	/** No-op on Err, returns self with new value type. */
+	/** Returns this `Err` unchanged, with a new value type. */
 	map(_fn) {
 		return this;
 	}
@@ -52,7 +52,7 @@ var Err = class Err {
 	mapError(fn) {
 		return new Err(fn(this.error));
 	}
-	/** No-op on Err, returns self with widened error type. */
+	/** Returns this `Err` unchanged, with a widened error type. */
 	andThen(_fn) {
 		return this;
 	}
@@ -64,7 +64,7 @@ var Err = class Err {
 	unwrapOr(fallback) {
 		return fallback;
 	}
-	/** Pattern matches on the Result. */
+	/** Pattern matches on the `Result`. */
 	match(handlers) {
 		return handlers.err(this.error);
 	}

package/dist/string.d.mts

@@ -1,7 +1,7 @@
 //#region src/string.d.ts
 declare const TEMPLATE_PLACEHOLDER_RE: RegExp;
 /**
- * Simple template engine to replace variables in a string.
+ * Replaces `{name}` placeholders in a string with the matching variable.
  *
  * @remarks
  * Only own properties of `variables` are substituted, so placeholders like

package/dist/string.mjs

@@ -2,7 +2,7 @@
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 const TEMPLATE_PLACEHOLDER_RE = /\{(\w+)\}/g;
 /**
-* Simple template engine to replace variables in a string.
+* Replaces `{name}` placeholders in a string with the matching variable.
 *
 * @remarks
 * Only own properties of `variables` are substituted, so placeholders like

package/dist/types.d.mts

@@ -1,7 +1,7 @@
 //#region src/types.d.ts
 type AutocompletableString = string & {};
 type LooseAutocomplete<T extends string> = T | AutocompletableString;
-/** Also commonly referred to as `Prettify` */
+/** Also commonly referred to as `Prettify`. */
 type UnifyIntersection<T> = { [K in keyof T]: T[K]; } & {};
 declare const brand: unique symbol;
 type BrandedType<T, B> = T & {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "packageManager": "pnpm@11.15.1",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",