@helpers4/object 3.0.0-alpha.2 → 3.0.0

package/README.md

@@ -12,11 +12,13 @@ A set of helpers for working with URLs.
 [https://helpers4.dev/typescript/categories/object/](https://helpers4.dev/typescript/categories/object/)
 
 <!-- AUTOMATIC-METHODS -->
+- clone
 - cloneDeep
 - compact
 - diff
 - equalsDeep
 - equalsShallow
+- flatten
 - get
 - groupBy
 - invert
@@ -25,10 +27,16 @@ A set of helpers for working with URLs.
 - map
 - mergeDeep
 - omit
+- omitBy
+- parsePropertyPath
 - pick
+- pickBy
 - removeUndefinedNull
 - safeJsonParse
 - set
+- unflatten
+- unset
+- update
 <!-- /AUTOMATIC-METHODS -->
 
 ## See

package/lib/index.d.ts

@@ -1,3 +1,31 @@
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a shallow copy of a value — one level deep, unlike {@link cloneDeep}.
+ *
+ * Unlike a plain `{ ...value }` spread, this correctly reconstructs `Date`,
+ * `Map`, `Set`, and arrays instead of producing an empty (or wrong-shaped)
+ * plain object for them. Primitives are returned as-is. Any other object
+ * (including class instances not listed above) has its own enumerable string
+ * keys shallow-copied into a plain object — the same fallback `cloneDeep`
+ * uses, so the two stay consistent for types neither one special-cases.
+ *
+ * @param value - The value to shallow-clone
+ * @returns A shallow copy of `value`
+ * @example
+ * clone({ a: { b: 1 } })
+ * // => { a: { b: 1 } } — new object, but `a` is the *same* nested reference
+ * @example
+ * clone(new Date('2024-01-01')) // => new Date with the same timestamp
+ * clone(new Map([['a', 1]]))    // => new Map with the same entries
+ * clone([1, 2, 3])              // => new array, same elements
+ * @since 3.0.0
+ */
+declare function clone<T>(value: T): T;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -162,6 +190,37 @@ declare function equalsDeep(objA: object | undefined | null, objB: object | unde
  */
 declare function equalsShallow(objA: unknown, objB: unknown): boolean;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Flattens a nested object into a single-level object whose keys are the
+ * dot-notation path to each leaf value. The inverse of {@link unflatten}.
+ *
+ * Only **plain objects** are recursed into — arrays, `Date`, `Map`, `RegExp`,
+ * class instances, and empty plain objects `{}` are kept as opaque leaf
+ * values. This keeps `flatten`/`unflatten` a clean, invertible pair: arrays
+ * can't be losslessly told apart from plain objects once reduced to dotted
+ * keys, so this implementation doesn't attempt it.
+ *
+ * Caveat shared by every dotted-path flattening scheme: a key that itself
+ * contains a literal `.` is indistinguishable from real nesting once
+ * flattened (`{ 'a.b': 1 }` and `{ a: { b: 1 } }` both produce `{ 'a.b': 1 }`).
+ *
+ * @param obj - The object to flatten
+ * @returns A single-level object with dot-notation keys
+ * @example
+ * flatten({ a: { b: { c: 1 }, d: 2 } })
+ * // => { 'a.b.c': 1, 'a.d': 2 }
+ * @example
+ * flatten({ a: [1, 2], b: new Date(0) })
+ * // => { a: [1, 2], b: Date }  (arrays and special objects stay as leaves)
+ * @since 3.0.0
+ */
+declare function flatten(obj: Record<string, unknown>): Record<string, unknown>;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -175,6 +234,101 @@ declare const UNSAFE_KEY_LIST: readonly ["__proto__", "constructor", "prototype"
 /** @ignore */
 type UnsafeKey = (typeof UNSAFE_KEY_LIST)[number];
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Converts a union type to an intersection type: `A | B | C` → `A & B & C`.
+ *
+ * Uses conditional-type distribution and the contravariant position of a
+ * function parameter to collapse the union into an intersection.
+ *
+ * @example
+ * type Union = { a: number } | { b: string } | { c: boolean };
+ * type Intersection = UnionToIntersection<Union>;
+ * // { a: number } & { b: string } & { c: boolean }
+ *
+ * type Keys = UnionToIntersection<'a' | 'b'>;
+ * // 'a' & 'b'  (resolves to never for disjoint literals)
+ * @since 3.0.0
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Returns `never` for `null`/`undefined`, otherwise `keyof T`.
+ *
+ * Used instead of inlining `keyof NonNullable<T>` at each `DeepGet` recursion
+ * step — TypeScript doesn't evaluate that expression eagerly inside a
+ * recursive generic, so `keyof` ends up applied to an unresolved conditional
+ * type instead of a concrete one. That collapses the whole recursive chain to
+ * `never` (rather than `unknown`) the moment a path travels through a
+ * property whose value is `null`, even though `null` itself is never in
+ * `Path`. Checking the null-ness first, in its own conditional, forces eager
+ * resolution and keeps that case at `unknown` as intended.
+ * @ignore
+ */
+type KeysOf<T> = T extends null | undefined ? never : keyof T;
+/**
+ * Resolves the value type at a given `Path` within `T`.
+ *
+ * Returns `unknown` when any key in `Path` is not present in the corresponding
+ * level of `T`. An empty path resolves to `T` itself. A path segment that goes
+ * through an optional property keeps the result nullable (`V | undefined`)
+ * instead of degrading to `unknown`.
+ *
+ * @example
+ * type Obj = { a: { b: { c: number } } };
+ *
+ * DeepGet<Obj, ['a', 'b', 'c']> // => number
+ * DeepGet<Obj, ['a', 'b']>      // => { c: number }
+ * DeepGet<Obj, ['a', 'x']>      // => unknown
+ * DeepGet<Obj, []>              // => Obj
+ *
+ * type WithOptional = { a?: { b: number } };
+ * DeepGet<WithOptional, ['a', 'b']> // => number | undefined
+ * @since 3.0.0
+ */
+type DeepGet<T, Path extends readonly PropertyKey[]> = Path extends readonly [] ? T : Path extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends KeysOf<T> ? DeepGet<NonNullable<T>[K & keyof NonNullable<T>], Rest> | (undefined extends T ? undefined : never) : unknown : unknown;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Builds a brand-new nested object type from the remaining path segments and a leaf value type.
+ * Used by `DeepSet` once a path segment no longer matches an existing key on T.
+ * @ignore
+ */
+type BuildPath<Path extends readonly PropertyKey[], V> = Path extends readonly [infer K extends PropertyKey, ...infer Rest extends readonly PropertyKey[]] ? Record<K, BuildPath<Rest, V>> : V;
+/**
+ * Produces the type of `T` after replacing the value at `Path` with `V`.
+ *
+ * When a key in `Path` is absent from the corresponding level of `T`, that level
+ * (and everything below it) is added as a new field instead of resolving to
+ * `never` — mirroring how `set()` creates intermediate objects at runtime.
+ *
+ * @example
+ * type Obj = { a: { b: number; c: string } };
+ *
+ * DeepSet<Obj, ['a', 'b'], string>
+ * // => { a: { b: string; c: string } }
+ *
+ * DeepSet<Obj, ['a', 'x'], boolean>
+ * // => { a: { b: number; c: string } & { x: boolean } }
+ * @since 3.0.0
+ */
+type DeepSet<T, Path extends readonly PropertyKey[], V> = Path extends readonly [] ? V : Path extends readonly [infer K extends PropertyKey, ...infer Rest extends readonly PropertyKey[]] ? T extends object ? K extends keyof T ? {
+    [P in keyof T]: P extends K ? DeepSet<T[K], Rest, V> : T[P];
+} : T & Record<K, BuildPath<Rest, V>> : BuildPath<Path, V> : never;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -222,12 +376,6 @@ type ParsePath<P extends string | readonly PropertyKey[]> = P extends string ? P
  * @ignore
  */
 type ContainsUnsafeStringKey<Keys extends readonly PropertyKey[]> = Keys extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends UnsafeKey ? true : ContainsUnsafeStringKey<Rest> : false;
-/**
- * Converts a union to an intersection: `A | B | C` → `A & B & C`.
- * Used to derive the return type of `mergeDeep` from a tuple of source types.
- * @ignore
- */
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 /**
  * Return type of `mergeDeep`: intersection of all source types.
  *
@@ -237,57 +385,6 @@ type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) exten
  * MergeResult<[{ a: { b: number } }, { a: { c: string } }]>  // { a: { b: number } & { c: string } }
  */
 type MergeResult<T extends object[]> = UnionToIntersection<T[number]>;
-/**
- * Returns `never` for `null`/`undefined`, otherwise `keyof T`.
- *
- * Used instead of inlining `keyof NonNullable<T>` at each `DeepGet` recursion
- * step — TypeScript doesn't evaluate that expression eagerly inside a
- * recursive generic, so `keyof` ends up applied to an unresolved conditional
- * type instead of a concrete one. That collapses the whole recursive chain to
- * `never` (rather than `unknown`) the moment a path travels through a
- * property whose value is `null`, even though `null` itself is never in
- * `Path`. Checking the null-ness first, in its own conditional, forces eager
- * resolution and keeps that case at `unknown` as intended.
- * @ignore
- */
-type KeysOf<T> = T extends null | undefined ? never : keyof T;
-/**
- * Resolves the value type at a given path within T.
- * Returns `unknown` when the path doesn't match the shape of T. A path segment
- * that goes through an optional property keeps the result nullable
- * (`V | undefined`) instead of degrading to `unknown`.
- *
- * @ignore
- * @example
- * DeepGet<{ a: { b: number } }, ['a', 'b']>  // => number
- * DeepGet<{ a: { b: number } }, ['a', 'x']>  // => unknown
- * DeepGet<{ a: number }, []>                  // => { a: number }
- * DeepGet<{ a?: { b: number } }, ['a', 'b']>  // => number | undefined
- * DeepGet<{ a: { b: null } }, ['a', 'b', 'c']> // => unknown (not never)
- */
-type DeepGet<T, Path extends readonly PropertyKey[]> = Path extends readonly [] ? T : Path extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends KeysOf<T> ? DeepGet<NonNullable<T>[K & keyof NonNullable<T>], Rest> | (undefined extends T ? undefined : never) : unknown : unknown;
-/**
- * Builds a brand-new nested object type from the remaining path segments and a leaf value type.
- * Used by `DeepSet` once a path segment no longer matches an existing key on T.
- * @ignore
- */
-type BuildPath<Path extends readonly PropertyKey[], V> = Path extends readonly [infer K extends PropertyKey, ...infer Rest extends readonly PropertyKey[]] ? Record<K, BuildPath<Rest, V>> : V;
-/**
- * Produces the type of T after setting the value at Path to V.
- * When a key in Path is not present at the corresponding level of T, that level (and
- * everything below it) is added as a new field instead of resolving to `never` — matching
- * the runtime behavior of `set`, which creates intermediate objects as needed.
- *
- * @ignore
- * @example
- * DeepSet<{ a: { b: number } }, ['a', 'b'], string>
- * // => { a: { b: string } }
- * DeepSet<{ a: { b: number } }, ['a', 'c'], string>
- * // => { a: { b: number } & { c: string } }
- */
-type DeepSet<T, Path extends readonly PropertyKey[], V> = Path extends readonly [] ? V : Path extends readonly [infer K extends PropertyKey, ...infer Rest extends readonly PropertyKey[]] ? K extends keyof T ? {
-    [P in keyof T]: P extends K ? DeepSet<T[K], Rest, V> : T[P];
-} : T & Record<K, BuildPath<Rest, V>> : never;
 
 /**
  * This file is part of helpers4.
@@ -549,6 +646,60 @@ declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj:
 declare function omit(obj: undefined, keys: readonly string[]): undefined;
 declare function omit(obj: null, keys: readonly string[]): null;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a new object without the own enumerable entries for which
+ * `predicate` returns `true`.
+ *
+ * Complements {@link omit} for when the keys to remove aren't known ahead of
+ * time — `omit` takes an explicit key list, `omitBy` takes a predicate.
+ *
+ * @param obj - The source object. `null`/`undefined` pass through unchanged.
+ * @param predicate - Called with `(value, key)` for each own enumerable entry
+ * @returns A new object without the matching entries
+ * @example
+ * omitBy({ a: 1, b: undefined, c: 2 }, (value) => value === undefined)
+ * // => { a: 1, c: 2 }
+ * @since 3.0.0
+ */
+declare function omitBy<T extends Record<string, unknown>>(obj: T | undefined | null, predicate: (value: T[keyof T], key: keyof T) => boolean): Partial<T> | undefined | null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Parses a dot/bracket-notation property path into an array of string/number
+ * key segments — the same notation accepted by {@link get} and {@link set}.
+ *
+ * - Dot separators (`.`) split segments; each segment becomes a string key.
+ * - Bracket indices (`[n]`) become number keys.
+ * - A leading `.` is treated as "current level" and stripped before parsing,
+ *   so `.[0]` ≡ `[0]` and `.a.b` ≡ `a.b`.
+ * - Empty string (or a bare `.`) returns `['']` (addresses the `''` key on the root object).
+ * - Consecutive dots (`a..b`) produce an empty-string segment: `['a', '', 'b']`.
+ *
+ * Results are cached (up to 500 distinct path strings, oldest evicted first)
+ * since real-world callers tend to reuse a small, fixed set of literal paths.
+ *
+ * @param path - The dot/bracket-notation path string to parse
+ * @returns The parsed key segments
+ * @throws {RangeError} When non-bracket text trails the last `]` within a
+ *   dot-segment (e.g. `'a[0]b'` is ambiguous — use `'a[0].b'` instead)
+ * @example
+ * parsePropertyPath('a.b.c')       // => ['a', 'b', 'c']
+ * parsePropertyPath('layers[1].x') // => ['layers', 1, 'x']
+ * parsePropertyPath('.[0]')        // => [0]              (leading dot stripped)
+ * parsePropertyPath('a..b')        // => ['a', '', 'b']   (empty segment preserved)
+ * @since 3.0.0
+ */
+declare function parsePropertyPath(path: string): readonly (string | number)[];
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -570,6 +721,28 @@ declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj:
 declare function pick(obj: undefined, keys: readonly string[]): undefined;
 declare function pick(obj: null, keys: readonly string[]): null;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a new object with only the own enumerable entries for which
+ * `predicate` returns `true`.
+ *
+ * Complements {@link pick} for when the keys to keep aren't known ahead of
+ * time — `pick` takes an explicit key list, `pickBy` takes a predicate.
+ *
+ * @param obj - The source object. `null`/`undefined` pass through unchanged.
+ * @param predicate - Called with `(value, key)` for each own enumerable entry
+ * @returns A new object with only the matching entries
+ * @example
+ * pickBy({ a: 1, b: 0, c: 2 }, (value) => value > 0)
+ * // => { a: 1, c: 2 }
+ * @since 3.0.0
+ */
+declare function pickBy<T extends Record<string, unknown>>(obj: T | undefined | null, predicate: (value: T[keyof T], key: keyof T) => boolean): Partial<T> | undefined | null;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -671,5 +844,88 @@ declare function safeJsonParse<T>(input: string, fallback: T): T;
  */
 declare function set<T extends object, const P extends string | readonly PropertyKey[], V extends DeepGet<T, ParsePath<P>>>(obj: T, path: P, value: V): string extends P ? T : readonly PropertyKey[] extends P ? T : ContainsUnsafeStringKey<ParsePath<P>> extends true ? T : DeepSet<T, ParsePath<P>, V>;
 
-export { cloneDeep, compact, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, pick, removeUndefinedNull, safeJsonParse, set };
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Rebuilds a nested object from a single-level object whose keys are
+ * dot-notation paths. The inverse of {@link flatten}.
+ *
+ * Uses {@link set} internally, so intermediate nodes are always created as
+ * plain objects (never arrays — see {@link flatten}'s doc for why), and any
+ * key segment equal to `__proto__`, `constructor`, or `prototype` is silently
+ * rejected (same prototype-pollution guard as `set`).
+ *
+ * @param obj - A single-level object with dot-notation keys
+ * @returns The rebuilt nested object
+ * @example
+ * unflatten({ 'a.b.c': 1, 'a.d': 2 })
+ * // => { a: { b: { c: 1 }, d: 2 } }
+ * @since 3.0.0
+ */
+declare function unflatten(obj: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Removes the value at a dot/bracket-notation path or explicit key array,
+ * mutating the object in place. Uses the same path syntax as {@link get}/{@link set}.
+ *
+ * A missing intermediate segment is a no-op (nothing to remove), not an error.
+ * As with `set`, any path containing a string segment equal to `__proto__`,
+ * `constructor`, or `prototype` is rejected and the object is returned unchanged.
+ *
+ * The removed key stops appearing in `Object.keys`/`for...in` — unlike setting
+ * it to `undefined`, which would keep the key present.
+ *
+ * @param obj - The object to mutate
+ * @param path - Dot/bracket-notation string, or explicit `PropertyKey[]`
+ * @returns The same object reference, with the key removed if it existed
+ * @example
+ * unset({ a: { b: 1, c: 2 } }, 'a.b')
+ * // => { a: { c: 2 } }
+ * @example
+ * unset({ a: 1 }, 'x.y') // path doesn't exist — no-op
+ * // => { a: 1 }
+ * @since 3.0.0
+ */
+declare function unset<T extends object>(obj: T, path: string | readonly PropertyKey[]): T;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+/**
+ * Updates the value at a path by applying a function to its current value,
+ * creating intermediate objects as needed. Equivalent to
+ * `set(obj, path, updater(get(obj, path)))` in a single call.
+ *
+ * Uses the same path syntax and type-inference rules as {@link get} and
+ * {@link set} — see those for the full behavior (string vs. `PropertyKey[]`
+ * paths, prototype-pollution guarding, etc.).
+ *
+ * @param obj - The object to mutate
+ * @param path - Dot/bracket-notation string literal or explicit `PropertyKey[]`
+ * @param updater - Called with the current value (`undefined` if the path is
+ *   absent); its return value is written back at the path
+ * @returns The mutated object (same reference, narrowed type)
+ * @example
+ * update({ count: 1 }, 'count', (n) => (n ?? 0) + 1)
+ * // => { count: 2 }
+ * @example
+ * // Missing intermediate objects are created, just like set()
+ * update({}, 'stats.hits', (n: number | undefined) => (n ?? 0) + 1)
+ * // => { stats: { hits: 1 } }
+ * @since 3.0.0
+ */
+declare function update<T extends object, const P extends string | readonly PropertyKey[], V extends DeepGet<T, ParsePath<P>>>(obj: T, path: P, updater: (current: DeepGet<T, ParsePath<P>> | undefined) => V): string extends P ? T : readonly PropertyKey[] extends P ? T : ContainsUnsafeStringKey<ParsePath<P>> extends true ? T : DeepSet<T, ParsePath<P>, V>;
+
+export { clone, cloneDeep, compact, diff, equalsDeep, equalsShallow, flatten, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, omitBy, parsePropertyPath, pick, pickBy, removeUndefinedNull, safeJsonParse, set, unflatten, unset, update };
 export type { DiffOptions, DiffResult };