@web-ts-toolkit/utils 0.43.0 → 0.44.0

package/README.md

@@ -8,13 +8,12 @@ Shared collection, object, async, and URL helpers used across the workspace.
 pnpm add @web-ts-toolkit/utils
 ```
 
-## Highlights
+Requires Node `>=22`. Import from the package root with canonical named
+imports; there is no default export and no public subpath:
 
-- object-path helpers such as `get(...)`, `set(...)`, and `hasOwn(...)`
-- collection helpers such as `map(...)`, `filter(...)`, `eachRight(...)`, `join(...)`, `uniq(...)`, `uniqBy(...)`, and `orderBy(...)`
-- small type guards
-- URL helpers such as `normalizeUrlPath(...)`
-- async helpers such as `mapValuesAsync(...)`
+```ts
+import { get, normalizeUrlPath, parseBooleanString } from '@web-ts-toolkit/utils';
+```
 
 ## Quick Start
 
@@ -69,9 +68,141 @@ parseBooleanString('true', false);
 - string helpers: `startCase`, `upperCase`
 - guards: `isArray`, `isPlainObject`, `isString`, `isPromise`
 - URL helpers: `addLeadingSlash`, `removeConsecutiveSlashesFromUrl`, `normalizeUrlPath`
+- async helpers: `mapValuesAsync`, `toAsyncFn`
+- misc: `castArray`, `arrayToRecord`, `mapValues`, `noop`, `padEnd`, `parseBooleanString`
+
+## Path Grammar And Mutation Rules
+
+`get`, `set`, `pick`, and `omit` accept a `PropertyPath`: dot segments
+(`'a.b'`), bare brackets (`'a[0]'`), quoted brackets (`'a["b.c"]'`), or
+segment arrays (`['a', 'b']`).
+
+- Key identity is literal: string segments are never coerced, so `'01'`
+  and `'1'` address different properties, and digit keys beyond
+  `MAX_SAFE_INTEGER` never round. Only canonical indices (`'0'`, `'1'`,
+  … with no leading zeros) address array slots; `'a[01]'` addresses an
+  own `'01'` property. Empty quoted keys, escaped quotes, empty dot
+  segments, and malformed brackets are unspecified (no Lodash parity).
+- Mutation segments `__proto__`, `constructor`, and `prototype` (quoted
+  or not) are rejected before any write: `set` returns its target
+  unchanged and `omit`/`deletePath` are no-ops.
+- In `pick`/`omit`, a flat string array is a **list** of paths
+  (`pick(o, ['a', 'b'])` picks keys `a` and `b`); pass a nested array for
+  a single segmented path (`pick(o, [['a', 'b']])` picks `a.b`).
+- Reads follow the prototype chain; `get` returns `defaultValue` for a
+  `null`/`undefined` intermediate or an `undefined` leaf. Writes never
+  traverse inherited containers: an inherited member is shadowed with a
+  new own container (array for a following canonical index, plain object
+  otherwise) and the final write creates an own data property, bypassing
+  inherited setters. Use `hasOwn` when own-key presence matters.
+- Dictionary builders (`groupBy`, `arrayToRecord`, `mapKeys`,
+  `mapValues`, `pickBy`, `omitBy`, `toStringRecord`) preserve arbitrary
+  string keys — including `__proto__` — as own data properties without
+  replacing the result prototype. Results keep `Object.prototype`
+  (never null-prototype).
+
+## Mutation Versus Copying
+
+- `set` mutates its target in place and returns it. `omit` never mutates
+  its input: it deep-clones first, then deletes from the clone.
+- `assign` is a thin wrapper over native `Object.assign` (source getters
+  and target setters run); it is not a hardened untrusted-input copier.
+- `orderBy`, `uniq`/`uniqBy`, `difference`, the `intersection` family,
+  and `flatten`/`flattenDeep` never mutate their inputs. Sorting and
+  deduplication are stable/first-occurrence: ties keep input order and
+  the first occurrence wins.
+
+## Clone And Comparison Domains
+
+`cloneDeep`, `isEqual`, and `isMatch` share one bounded domain:
+
+- Supported: primitives (`NaN` equals itself), plain objects
+  (`null`/`Object.prototype`, plus `Object.create` graphs over plain
+  ancestors whose prototype is shared by reference), arrays (length,
+  holes, and extra own keys participate), `Date` (by time), and `RegExp`
+  (by source plus flags). Cycles and repeated references terminate and
+  stay shared within the clone.
+- Functions and exotic values (`Map`/`Set`, class instances such as BSON
+  `ObjectId`) are opaque: nested occurrences are shared by reference,
+  never traversed, and distinct references are never equal. A top-level
+  exotic root passed to `cloneDeep` throws `TypeError` instead of
+  returning an alias, so `omit` on an uncloneable root throws before
+  deleting anything rather than deleting from your input.
+- Comparison uses own enumerable string/symbol keys only: inherited
+  state is ignored and prototypes are not compared. `isMatch` requires
+  each own source key (including `undefined`-valued and symbol keys) to
+  exist as an own key on the target, so `isMatch({}, { a: undefined })`
+  is `false`; arrays use prefix semantics.
+
+## Async Contracts
+
+- `toAsyncFn` lifts sync results into a promise, but it is not a full
+  async-function boundary: a synchronous `throw` escapes synchronously
+  instead of becoming a rejection, and thenables (including foreign
+  thenables) are returned unchanged with identity preserved rather than
+  converted to native promises. When `fn` is absent, the wrapper resolves
+  `defaultValue`. `this` is forwarded.
+- `mapValuesAsync` starts every callback eagerly with unbounded
+  parallelism (`Promise.all`): one rejection rejects the whole call, and
+  there is no concurrency limit, cancellation, or scheduler. Chunk the
+  input if downstream throttling is needed.
+
+## Boolean Strings
+
+```ts
+import { parseBooleanString } from '@web-ts-toolkit/utils';
+
+parseBooleanString('true'); // true
+parseBooleanString('false'); // false
+parseBooleanString('TRUE'); // false — exact match only, no case folding
+parseBooleanString(''); // undefined — empty string falls back to the default
+parseBooleanString('', false); // false — via the default
+parseBooleanString(undefined, true); // true — missing input uses the default
+```
+
+`parseBooleanString(str, defaultValue)` returns `true` only for the exact
+string `'true'`, returns `false` for any other non-empty string, and falls
+back to `defaultValue` (which is `undefined` when omitted) when the input
+is `undefined` **or the empty string `''`**. Note that an Express-style
+`?flag=` query value parses to `''` and therefore yields the default, not
+`false`.
+
+## URL Paths Are Pathname-Only
+
+```ts
+import { normalizeUrlPath } from '@web-ts-toolkit/utils';
+
+normalizeUrlPath('api//users'); // '/api/users'
+normalizeUrlPath('api//users/42'); // '/api/users/42'
+```
+
+`normalizeUrlPath` composes route-path fragments: it collapses every run
+of slashes and prepends a leading slash. The input must be a path
+fragment — no scheme/host, query string, or fragment. Full URLs are out
+of domain and are mangled rather than normalized
+(`normalizeUrlPath('https://example.com//a')` yields
+`'/https:/example.com/a'`; slash runs inside query/fragment values are
+collapsed too). These helpers are route-path composition for workspace
+routers, not WHATWG URL normalization and not a security sanitizer.
+
+## Guards And Types
+
+- `isBoolean`/`isNumber`/`isString` accept primitives only: boxed
+  instances such as `new Boolean(false)` return `false` and are never
+  narrowed to primitives.
+- `flattenDeep<T>(input)` takes `unknown` (a non-array yields `[]`) and
+  `T` is an unchecked caller assertion — specify it explicitly
+  (`flattenDeep<number>(input)`) or narrow `unknown[]` yourself. Cyclic
+  arrays throw `TypeError`; shared (non-ancestor) subarrays flatten once
+  per occurrence. Wide and deeply nested inputs flatten iteratively
+  without `RangeError`.
+- `intersectionBy`/`difference` ignore non-array value arguments, while
+  `intersection` treats a non-array secondary as empty (result `[]`).
+  `intersectionBy` evaluates each element's iteratee once per input array;
+  redundant-callback side effects are not preserved.
 
 ## Documentation
 
-Full package documentation lives in `website/docs/packages/utils.md`.
+Full package documentation lives on the published docs site:
 
 - live docs: https://web-ts-toolkit.pages.dev/docs/packages/utils

package/index.d.mts

@@ -1,15 +1,57 @@
+/**
+ * Ensure `value` starts with a `/`. Values that already start with `/` are
+ * returned unchanged; the empty string becomes `'/'`.
+ */
 declare function addLeadingSlash(value: string): string;
 
+/**
+ * Converts an array of strings to a lookup record.
+ *
+ * UTILS-01 contract: every entry becomes an own data property, including
+ * `__proto__` (which plain assignment would drop by attempting a prototype
+ * set). The result keeps the default `Object.prototype` prototype.
+ */
 declare function arrayToRecord(arr: string[]): Record<string, true>;
 
+/**
+ * Thin wrapper over native `Object.assign`: copies own enumerable
+ * string/symbol properties from each source onto `target` and returns
+ * `target`. Source getters and target setters run as normal JavaScript
+ * semantics dictate. This is a plain copy helper, not a hardened
+ * untrusted-input sanitizer.
+ */
 declare function assign<T extends object>(target: T, ...sources: unknown[]): T;
 
 declare function castArray<T>(value: T | T[]): T[];
 
+/**
+ * Deep-clones a value within the UTILS-04 bounded domain.
+ *
+ * Supported: primitives, plain objects (`null`/`Object.prototype`),
+ * `Object.create` graphs over plain-object ancestors (prototype preserved
+ * by reference, own keys deep-cloned), arrays, `Date`, `RegExp`. Functions
+ * and exotic values nested inside a supported container (class instances
+ * such as BSON `ObjectId`, `Map`/`Set`) are preserved by reference as
+ * opaque leaves. A top-level exotic root throws `TypeError` instead of
+ * returning an alias.
+ * Cycles and repeated references are preserved (shared stays shared,
+ * detached from the original). Class instances, `Map`/`Set`, and other
+ * non-plain objects throw `TypeError` instead of returning an alias.
+ */
 declare function cloneDeep<T>(value: T): T;
 
 declare function compact<T>(array: T[] | null | undefined): T[];
 
+/**
+ * Set difference.
+ *
+ * UTILS-08: exclusion membership is precomputed once into a `Set`
+ * (SameValueZero: NaN equals NaN, +0/-0 equal; objects by reference),
+ * matching the previous linear `arrayIncludes` scan. First-occurrence
+ * order, item references, and input non-mutation are preserved. Non-array
+ * `values` entries are ignored (preserved ignore-policy, consistent with
+ * `intersectionBy`; differs from `intersection`'s empty-on-non-array rule).
+ */
 declare function difference<T>(array: T[] | null | undefined, ...values: Array<T[] | null | undefined>): T[];
 
 declare function eachRight<T>(collection: T[] | null | undefined, iteratee: (value: T, key: number, collection: T[]) => unknown): T[] | null | undefined;
@@ -21,47 +63,205 @@ declare function find<T>(collection: T[] | Record<string, T> | null | undefined,
 
 declare function flatten<T>(array: Array<T | T[]> | null | undefined): T[];
 
-declare function flattenDeep<T>(array: unknown[]): T[];
+/**
+ * Recursively flatten nested arrays into a single flat array.
+ *
+ * Iterative implementation: uses an explicit frame stack instead of call-stack
+ * recursion and pushes leaves one at a time instead of spreading whole child
+ * results into `push`, so wide (many-leaf) and deeply nested inputs do not
+ * throw `RangeError`. Left-to-right ordering is preserved.
+ *
+ * Leaf behavior: any non-array value (including `undefined`, holes read as
+ * `undefined`, objects, and functions) is appended as-is. A non-array input
+ * returns `[]`. There are no size limits.
+ *
+ * Cycle policy: an array that contains itself, directly or transitively
+ * through its current ancestor chain, throws a `TypeError`. Legitimate
+ * repeated (shared but non-ancestor) subarrays are flattened once per
+ * occurrence, so `const sub = [1]; flattenDeep([sub, sub])` is `[1, 1]`.
+ *
+ * @param array The value to flatten; non-array inputs yield `[]`.
+ * @returns A new flat array of the leaf values, in left-to-right order.
+ * @throws {TypeError} When a cyclic array reference is detected.
+ *
+ * UTILS-09 typing note: `T` is an unchecked caller assertion, not an
+ * inferred or validated leaf type — the function cannot verify element
+ * types at runtime. Specify it explicitly for typed leaves (e.g.
+ * `flattenDeep<number>(input)`) or narrow the default `unknown[]`
+ * yourself. A fully inferred recursive `FlatArray`-style result type is
+ * deliberately deferred: it would need an arbitrary depth cap and could
+ * not stay sound for non-array inputs (which yield `[]`).
+ */
+declare function flattenDeep<T = unknown>(array: unknown): T[];
 
 declare function forEach<T>(collection: T[] | null | undefined, iteratee: (value: T, key: number, collection: T[]) => unknown): T[] | null | undefined;
 declare function forEach<T extends object>(collection: T | null | undefined, iteratee: (value: T[keyof T], key: string, collection: T) => unknown): T | null | undefined;
 
 type PropertyPath = string | number | Array<string | number>;
 
+/**
+ * Read the value at `path`, returning `defaultValue` when unreachable.
+ *
+ * Supported path grammar (see `toPath` in `_internal.ts`): dot segments
+ * (`'a.b'`), bare brackets (`'a[0]'`), quoted brackets (`'a["b.c"]'`), and
+ * segment arrays (`['a', 'b']`). String segments keep literal identity
+ * (`'01'` ≠ `'1'`); only canonical indices address array slots.
+ *
+ * Reads follow the prototype chain; use `hasOwn` when own-key presence
+ * matters. A `null`/`undefined` intermediate or an `undefined` leaf yields
+ * `defaultValue`, so an explicit `undefined` value is indistinguishable
+ * from a missing path.
+ */
+
 declare function get<T = unknown>(object: unknown, path: PropertyPath, defaultValue?: T): T;
 
+/**
+ * Groups collection values by iteratee result.
+ *
+ * UTILS-01 contract: group names are ordinary string keys preserved as own
+ * data properties, including `__proto__`, `constructor`, `prototype`, and
+ * `toString`. The result keeps the default `Object.prototype` prototype;
+ * inherited members are never read as existing groups.
+ */
 declare function groupBy<T>(collection: T[] | Record<string, T> | null | undefined, iteratee: string | number | ((value: T, key: number | string, collection: T[] | Record<string, T>) => unknown)): Record<string, T[]>;
 
+/**
+ * Own-property check (`Object.hasOwn`): inherited properties do not count,
+ * and `null`/`undefined` values safely return `false`.
+ */
 declare function hasOwn<TKey extends PropertyKey>(value: unknown, key: TKey): value is Record<TKey, unknown>;
 
+/**
+ * Set intersection.
+ *
+ * UTILS-08: each secondary array's membership is precomputed once into a
+ * `Set` (SameValueZero: NaN equals NaN, +0/-0 equal; objects by reference),
+ * matching the previous linear `arrayIncludes` scans. First-occurrence
+ * order (via `baseUniq`), item references, and input non-mutation are
+ * preserved.
+ *
+ * Nullish contract (parity decision, preserved as-is): a non-array first
+ * argument yields `[]`, and any non-array secondary empties the result
+ * (`every` requires `Array.isArray`). This strict rule differs from
+ * `intersectionBy`/`difference`, which ignore non-array values arguments.
+ * The divergence is documented here rather than silently unified;
+ * unification is deferred to UTILS-11.
+ */
 declare function intersection<T>(...arrays: Array<T[] | null | undefined>): T[];
 
-declare function intersectionBy<T>(...args: unknown[]): T[];
+/**
+ * Intersection by iteratee with precomputed secondary membership.
+ *
+ * UTILS-08 performance contract:
+ * - Each element's iteratee is evaluated exactly once per input array
+ *   (work proportional to total input length), not once per candidate per
+ *   secondary. A 100-by-100 workload therefore invokes the callback ~200
+ *   times, not 10,100 times as before. Callback invocation count is
+ *   intentionally changed; side effects from redundant evaluation are not
+ *   preserved.
+ * - Secondary projections are stored in `Set`s, which use SameValueZero
+ *   membership (NaN equals NaN, +0/-0 equal; objects by reference),
+ *   matching the previous `sameValueZero` scans (UTILS-05).
+ * - First-occurrence ordering and original item references are preserved;
+ *   inputs are never mutated.
+ *
+ * Nullish contract (parity decision, preserved as-is): non-array arguments
+ * are dropped via `Array.isArray` filtering (same ignore-policy as
+ * `difference`), so a nullish secondary is ignored rather than emptying
+ * the result. This differs from `intersection`, which treats a non-array
+ * secondary as empty (result `[]`). The divergence is documented here
+ * rather than silently unified; unification is deferred to UTILS-11.
+ */
+type IntersectionByIteratee<T> = ((value: T) => unknown) | string | number;
+/**
+ * Intersection by iteratee with precomputed secondary membership.
+ *
+ * UTILS-09: the result element type is inferred from the first array; the
+ * iteratee parameter is excluded from inference (`NoInfer`) so a callback
+ * never distorts the element type. Non-array secondary arguments are ignored
+ * at runtime (see below) and are accepted in the type for that reason.
+ */
+declare function intersectionBy<T>(array: readonly T[], ...args: Array<readonly unknown[] | IntersectionByIteratee<NoInfer<T>> | null | undefined>): T[];
+declare function intersectionBy<T = unknown>(...args: Array<readonly T[] | IntersectionByIteratee<T> | null | undefined>): T[];
 
 declare function isArray(value: unknown): value is unknown[];
 
+/**
+ * Whether a value is a primitive boolean.
+ *
+ * UTILS-09 contract change: boxed `Boolean` objects are no longer accepted.
+ * A boxed instance (e.g. `new Boolean(false)`) is a truthy object, not the
+ * primitive `false`, so narrowing it to `boolean` was unsound. Use
+ * `value instanceof Boolean` explicitly when boxed instances are intended.
+ */
 declare function isBoolean(value: unknown): value is boolean;
 
 declare function isEmpty(value: unknown): boolean;
 
+/**
+ * Deep equality within the UTILS-05 bounded domain (aligned with UTILS-04).
+ *
+ * Supported: primitives (`NaN` equals itself), plain objects (own
+ * enumerable string/symbol keys only; inherited state ignored, prototypes
+ * not compared), arrays (length + holes + extra own keys), `Date` (by
+ * time), `RegExp` (by source + flags). Functions and exotic objects
+ * (`Map`/`Set`, class instances, etc.) compare by identity only, so
+ * distinct instances are never equal. Cyclic graphs terminate via
+ * pair-aware bookkeeping. See `deepEqual` in `_internal.ts` for the full
+ * contract.
+ */
 declare function isEqual(left: unknown, right: unknown): boolean;
 
 declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
 
+/**
+ * Partial matching within the UTILS-05 bounded domain.
+ *
+ * Every own enumerable string/symbol key of a plain `source` must exist
+ * as an own key on `object` and match recursively; extra keys on
+ * `object` are ignored. Absence is distinguished from `undefined`
+ * (`isMatch({}, { a: undefined })` is false). Arrays use prefix
+ * semantics. `Date`/`RegExp`/primitive/function/exotic sources fall back
+ * to `deepEqual` (identity for opaque types). See `partialMatch` in
+ * `_internal.ts` for the full contract.
+ */
 declare function isMatch(object: unknown, source: unknown): boolean;
 
 declare function isNaNValue(value: unknown): boolean;
 
 declare function isNil(value: unknown): value is null | undefined;
 
+/**
+ * Whether a value is a primitive number.
+ *
+ * UTILS-09 contract change: boxed `Number` objects are no longer accepted.
+ * A boxed instance (e.g. `new Number(0)`) is an object, not the primitive
+ * `0`, so narrowing it to `number` was unsound. Use
+ * `value instanceof Number` explicitly when boxed instances are intended.
+ */
 declare function isNumber(value: unknown): value is number;
 
 declare function isObject(value: unknown): value is object;
 
 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 
+/**
+ * Thenable check: true for any non-null value whose `then` is a function.
+ *
+ * UTILS-07 contract: native promises and foreign/cross-realm thenables
+ * satisfy this; a throwing `then` accessor propagates its throw. It does
+ * not verify genuine promise semantics beyond a callable `then`.
+ */
 declare function isPromise<T = unknown>(value: unknown): value is PromiseLike<T>;
 
+/**
+ * Whether a value is a primitive string.
+ *
+ * UTILS-09 contract change: boxed `String` objects are no longer accepted.
+ * A boxed instance (e.g. `new String('')`) is an object, not the primitive
+ * `''`, so narrowing it to `string` was unsound. Use
+ * `value instanceof String` explicitly when boxed instances are intended.
+ */
 declare function isString(value: unknown): value is string;
 
 declare function isUndefined(value: unknown): value is undefined;
@@ -70,37 +270,180 @@ declare function join(array: unknown[] | null | undefined, separator?: string):
 
 declare function keys(value: unknown): string[];
 
+/**
+ * Map an array by a known element key: the result element type follows the
+ * property type (e.g. `map(users, 'name')` yields `string[]`).
+ *
+ * UTILS-09: deeper property paths (`'a.b'`) are not key types and fall
+ * through to the generic overload below, yielding an honest `unknown[]`
+ * instead of a fabricated inference. No speculative path-type machinery.
+ */
+declare function map<T, K extends keyof T>(collection: readonly T[] | null | undefined, iteratee: K): Array<T[K]>;
 declare function map<T, TResult>(collection: T[] | Record<string, T> | null | undefined, iteratee: string | number | ((value: T, key: number | string, collection: T[] | Record<string, T>) => TResult)): TResult[];
 
+/**
+ * Maps object keys through an iteratee.
+ *
+ * UTILS-01 contract: mapped keys are stored as own data properties, so a
+ * mapped `__proto__` with an object value does not replace the result
+ * prototype. The result keeps the default `Object.prototype` prototype.
+ * Last-write-wins on duplicate mapped keys; callback order follows
+ * `Object.keys` order.
+ */
 declare function mapKeys<TValue>(object: Record<string, TValue> | null | undefined, iteratee: (value: TValue, key: string, object: Record<string, TValue>) => string): Record<string, TValue>;
 
+/**
+ * Maps object values through an iteratee.
+ *
+ * UTILS-01 contract: keys are preserved as own data properties (including
+ * `__proto__` with object values). The result keeps the default
+ * `Object.prototype` prototype; callback order follows `Object.keys` order.
+ */
 declare function mapValues<TValue, TResult>(object: Record<string, TValue> | null | undefined, iteratee: (value: TValue, key: string, object: Record<string, TValue>) => TResult): Record<string, TResult>;
 
+/**
+ * Map an object's values through an async callback.
+ *
+ * UTILS-07 contract (current behavior, locked by tests): all callbacks
+ * start eagerly with unbounded parallelism (`Promise.all`), preserving
+ * key order in the result. There is no concurrency limit, cancellation,
+ * or scheduler; a single rejection (or sync callback throw) rejects the
+ * whole call. An opt-in concurrency option is deferred to a follow-up
+ * (see UTILS-07 decision) pending a concrete caller need.
+ */
 declare function mapValuesAsync<TObject extends Record<string, unknown>, TResult>(object: TObject, asyncFn: (value: TObject[keyof TObject], key: string, object: TObject) => Promise<TResult> | TResult): Promise<Record<string, TResult>>;
 
 declare function noop(): void;
 
+/**
+ * UTILS-03: `paths` is one path or a list of paths. A flat string array is a
+ * LIST of paths (`omit(o, ['a', 'b'])` omits keys `a` and `b`), not one
+ * segmented path. Pass a nested array for a single segmented path:
+ * `omit(o, [['a', 'b']])` omits `a.b`. Key identity follows `toPath`.
+ *
+ * UTILS-04: `omit` never mutates its input. The input is deep-cloned first
+ * within the bounded clone domain (plain objects, `Object.create` graphs
+ * over plain data, arrays, `Date`, `RegExp`; functions and nested exotics
+ * such as `ObjectId`/`Map` preserved by reference as opaque leaves).
+ * A top-level unsupported root (class instance, `Map`/`Set`, etc.) throws
+ * `TypeError` before any deletion instead of returning an aliased clone
+ * that would delete from input-owned state.
+ */
 declare function omit<T extends object>(object: T, paths: PropertyPath | PropertyPath[]): Partial<T>;
 
+/**
+ * Omits entries whose predicate returns true.
+ *
+ * UTILS-01 contract: kept keys are stored as own data properties (including
+ * `__proto__` with object values). The result keeps the default
+ * `Object.prototype` prototype; the input is never mutated.
+ */
 declare function omitBy<TValue>(object: Record<string, TValue> | null | undefined, predicate: (value: TValue, key: string, object: Record<string, TValue>) => boolean): Record<string, TValue>;
 
+/**
+ * Parse a string-encoded boolean with an explicit fallback.
+ *
+ * Returns `true` only for the exact string `'true'`. Any other non-empty
+ * string (`'false'`, `'TRUE'`, `'1'`, …) returns `false` — matching is
+ * case-sensitive and no trimming is applied. The empty string `''` is
+ * treated like missing input and yields `defaultValue` (which is
+ * `undefined` when omitted); it does NOT return `false`.
+ *
+ * Query-string note: an Express-style `?flag=` parses to `''` and therefore
+ * falls back to `defaultValue`, not `false`. Pass an explicit default when
+ * that distinction matters.
+ */
 declare function parseBooleanString(str: string | undefined, defaultValue?: boolean): boolean | undefined;
 
+/**
+ * Sort a collection copy by iteratees with a stable tie-break.
+ *
+ * Ties keep their original relative order, and the input is never mutated
+ * (a copy is sorted). An unrecognized `orders` entry sorts ascending; a
+ * non-array collection yields `[]`.
+ */
 declare function orderBy<T>(collection: T[] | null | undefined, iteratees?: Array<string | number | ((value: T) => unknown)>, orders?: string[]): T[];
 
 declare function padEnd(value: unknown, length?: number, chars?: string): string;
 
+/**
+ * UTILS-03: `paths` is one path or a list of paths. A flat string array is a
+ * LIST of paths (`pick(o, ['a', 'b'])` picks keys `a` and `b`), not one
+ * segmented path. Pass a nested array for a single segmented path:
+ * `pick(o, [['a', 'b']])` picks `a.b`. Key identity follows `toPath`
+ * (literal `'01'`, quoted digit keys, canonical numeric indices).
+ */
 declare function pick<T extends object>(object: T, paths: PropertyPath | PropertyPath[]): Partial<T>;
 
+/**
+ * Picks entries whose predicate returns true.
+ *
+ * UTILS-01 contract: kept keys are stored as own data properties (including
+ * `__proto__`). The result keeps the default `Object.prototype` prototype;
+ * the input is never mutated.
+ */
 declare function pickBy<TValue>(object: Record<string, TValue> | null | undefined, predicate: (value: TValue, key: string, object: Record<string, TValue>) => boolean): Record<string, TValue>;
 
+/**
+ * Normalize a route-path fragment: collapse consecutive slashes and ensure
+ * a leading slash (`'api//users'` → `'/api/users'`).
+ *
+ * Pathname-only contract: the input must be a path fragment without a
+ * scheme/host, query string, or fragment. Full URLs are out of domain —
+ * slash runs are collapsed everywhere, including `https://` (which becomes
+ * `https:/`) and inside query/fragment values, and a leading slash is
+ * always prepended. This composes workspace router paths; it is not WHATWG
+ * URL normalization and not a security sanitizer.
+ */
 declare function normalizeUrlPath(url: string): string;
 
-declare function reduce<T, TResult>(collection: T[] | null | undefined, iteratee: (accumulator: TResult, value: T, key: number, collection: T[]) => TResult, accumulator?: TResult): TResult;
-declare function reduce<T, TResult>(collection: Record<string, T> | null | undefined, iteratee: (accumulator: TResult, value: T, key: string, collection: Record<string, T>) => TResult, accumulator?: TResult): TResult;
-
+/**
+ * Reduce an array to a single value with an explicit initial accumulator.
+ *
+ * UTILS-09: the with-initial and without-initial contracts are separate
+ * overloads (previously one ambiguous optional-accumulator signature). An
+ * empty collection with an initial value returns that value.
+ */
+declare function reduce<T, TResult>(collection: T[] | null | undefined, iteratee: (accumulator: TResult, value: T, key: number, collection: T[]) => TResult, accumulator: TResult): TResult;
+/**
+ * Reduce a record to a single value with an explicit initial accumulator.
+ */
+declare function reduce<T, TResult>(collection: Record<string, T> | null | undefined, iteratee: (accumulator: TResult, value: T, key: string, collection: Record<string, T>) => TResult, accumulator: TResult): TResult;
+/**
+ * Reduce an array without an initial value: the first element seeds the
+ * accumulator, so the accumulator and result share the element type. Throws
+ * `TypeError` on an empty collection (never silently yields `undefined`).
+ */
+declare function reduce<T>(collection: T[] | null | undefined, iteratee: (accumulator: T, value: T, key: number, collection: T[]) => T): T;
+/**
+ * Reduce a record without an initial value: the first value seeds the
+ * accumulator. Throws `TypeError` on an empty collection.
+ */
+declare function reduce<T>(collection: Record<string, T> | null | undefined, iteratee: (accumulator: T, value: T, key: string, collection: Record<string, T>) => T): T;
+
+/**
+ * Collapse every run of two or more `/` characters to a single `/`.
+ *
+ * Pathname-only helper (see `normalizeUrlPath`): runs are collapsed
+ * everywhere in the string, including a URL scheme (`'https://…'` becomes
+ * `'https:/…'`) and query/fragment values. Do not apply to full URLs.
+ */
 declare function removeConsecutiveSlashesFromUrl(url: string): string;
 
+/**
+ * Sets `value` at `path` of `object` and returns `object`.
+ *
+ * UTILS-02 contract: forbidden segments (`__proto__`, `constructor`,
+ * `prototype`) are rejected before any mutation. Intermediate segments reuse
+ * only own object containers; inherited containers are shadowed with a new
+ * own container (array when the next segment is numeric, plain object
+ * otherwise) so ancestors are never mutated. The final write creates an own
+ * data property, bypassing inherited setters when shadowing.
+ *
+ * UTILS-03 key identity: string segments keep their literal identity (`'01'`
+ * stays `'01'`, never index 1; digit keys beyond `MAX_SAFE_INTEGER` never
+ * round). Arrays are created only for canonical indices (see `toPath`).
+ */
 declare function set<T>(object: T, path: PropertyPath, value: unknown): T;
 
 declare function startCase(value: unknown): string;
@@ -109,14 +452,61 @@ declare function sum(values: number[] | null | undefined): number;
 
 declare function sumBy<T>(collection: T[] | null | undefined, iteratee: string | number | ((value: T, key: number, collection: T[]) => number | undefined)): number;
 
-declare function toAsyncFn<TArgs extends unknown[], TResult>(fn?: ((this: unknown, ...args: TArgs) => TResult | PromiseLike<TResult>) | null, defaultValue?: TResult): (this: unknown, ...args: TArgs) => PromiseLike<unknown> | Promise<any>;
-
+/**
+ * Wrap a function so sync results are lifted into a promise.
+ *
+ * UTILS-07 contract (current behavior, locked by tests):
+ * - This is NOT a full async-function boundary. A synchronous `throw`
+ *   from `fn` escapes synchronously instead of becoming a rejection.
+ * - Thenable results (including foreign/cross-realm thenables) are
+ *   returned unchanged with identity preserved; they are not converted
+ *   into native promises. A throwing `then` accessor therefore throws
+ *   synchronously during the `isPromise` check.
+ * - When `fn` is absent/null, the wrapper resolves `defaultValue` in a
+ *   native promise. `this` is forwarded via `fn.apply`.
+ * - UTILS-09 gave this contract an explicit truthful result type (see the
+ *   overloads); do not widen behavior here without maintainer approval.
+ *
+ * UTILS-09 typing note: the overloads below type that contract truthfully.
+ * A present `fn` yields `Promise<Awaited<TResult>> | PromiseLike<TResult>` —
+ * deliberately NOT a bare `Promise`, because thenables pass through with
+ * identity preserved (so `instanceof Promise` may be false). A synchronous
+ * `throw` is not expressible in the return type and stays documented above.
+ * An absent `fn` yields `Promise<TResult | undefined>` since an omitted
+ * `defaultValue` resolves `undefined`.
+ */
+declare function toAsyncFn<TArgs extends unknown[], TResult>(fn: (this: unknown, ...args: TArgs) => TResult | PromiseLike<TResult>, defaultValue?: TResult): (this: unknown, ...args: TArgs) => Promise<Awaited<TResult>> | PromiseLike<TResult>;
+declare function toAsyncFn<TArgs extends unknown[], TResult>(fn: null | undefined, defaultValue?: TResult): (this: unknown, ...args: TArgs) => Promise<TResult | undefined>;
+
+/**
+ * Stringifies own values of a plain object.
+ *
+ * UTILS-01 contract: keys are preserved as own data properties (including
+ * `__proto__`, which plain assignment would drop for string values). The
+ * result keeps the default `Object.prototype` prototype; the input is never
+ * mutated.
+ */
 declare function toStringRecord(value: unknown): Record<string, string> | undefined;
 
+/**
+ * Deduplicate an array keeping the first occurrence of each value.
+ *
+ * Membership is SameValueZero (`NaN` equals `NaN`, `+0`/`-0` equal; objects
+ * by reference). Never mutates the input; a non-array input yields `[]`.
+ */
 declare function uniq<T>(array: T[] | null | undefined): T[];
 
+/**
+ * Dedup by iteratee.
+ *
+ * UTILS-08: `seen` membership uses a `Set` (SameValueZero: NaN equals NaN,
+ * +0/-0 equal; objects by reference), matching the previous linear
+ * `sameValueZero` scan. First-occurrence order, item references, and input
+ * non-mutation are preserved. The iteratee is still invoked exactly once
+ * per element.
+ */
 declare function uniqBy<T>(array: T[] | null | undefined, iteratee?: string | number | ((value: T, key: number, collection: T[]) => unknown)): T[];
 
 declare function upperCase(value: unknown): string;
 
-export { addLeadingSlash, arrayToRecord, assign, castArray, cloneDeep, compact, difference, eachRight, filter, find, flatten, flattenDeep, forEach, get, groupBy, hasOwn, intersection, intersectionBy, isArray, isBoolean, isEmpty, isEqual, isFunction, isMatch, isNaNValue as isNaN, isNil, isNumber, isObject, isPlainObject, isPromise, isString, isUndefined, join, keys, map, mapKeys, mapValues, mapValuesAsync, noop, normalizeUrlPath, omit, omitBy, orderBy, padEnd, parseBooleanString, pick, pickBy, reduce, removeConsecutiveSlashesFromUrl, set, startCase, sum, sumBy, toAsyncFn, toStringRecord, uniq, uniqBy, upperCase };
+export { type PropertyPath, addLeadingSlash, arrayToRecord, assign, castArray, cloneDeep, compact, difference, eachRight, filter, find, flatten, flattenDeep, forEach, get, groupBy, hasOwn, intersection, intersectionBy, isArray, isBoolean, isEmpty, isEqual, isFunction, isMatch, isNaNValue as isNaN, isNil, isNumber, isObject, isPlainObject, isPromise, isString, isUndefined, join, keys, map, mapKeys, mapValues, mapValuesAsync, noop, normalizeUrlPath, omit, omitBy, orderBy, padEnd, parseBooleanString, pick, pickBy, reduce, removeConsecutiveSlashesFromUrl, set, startCase, sum, sumBy, toAsyncFn, toStringRecord, uniq, uniqBy, upperCase };