@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Obj.d.ts

@@ -1,189 +1,538 @@
+declare namespace _exports {
+    export { PathLeaf, Paths, NullishToUndefined, PathValue, PathStep, PathInput, DeepReadonly, Change, MergeOptions, SortKeysOptions, CompactOptions };
+}
+declare namespace _exports {
+    export { clone };
+    export { merge };
+    export { mergeWith };
+    export { defaults };
+    export { equal };
+    export { diff };
+    export { get };
+    export { set };
+    export { update };
+    export { unset };
+    export { has };
+    export { pick };
+    export { omit };
+    export { filter };
+    export { mapValues };
+    export { mapKeys };
+    export { renameKeys };
+    export { invert };
+    export { compact };
+    export { flatten };
+    export { unflatten };
+    export { paths };
+    export { sortKeys };
+    export { keys };
+    export { entries };
+    export { fromEntries };
+    export { size };
+    export { isEmpty };
+    export { deepFreeze };
+}
+export = _exports;
 /**
- * Deeply clones a value.
+ * Values that end a path: dates, regexes, maps, sets, functions and arrays.
+ */
+type PathLeaf = Date | RegExp | Map<any, any> | Set<any> | ((...args: any[]) => any) | readonly any[];
+/**
+ * Every dotted path of an object type, up to 6 levels. This is what powers
+ * path completion in `obj.get()` and friends.
+ */
+type Paths<T, Depth extends unknown[] = []> = Depth["length"] extends 6 ? never : T extends PathLeaf ? never : T extends object ? { [K in keyof T & (string | number)]: NonNullable<T[K]> extends PathLeaf ? `${K}` : NonNullable<T[K]> extends object ? `${K}` | `${K}.${Paths<NonNullable<T[K]>, [...Depth, 0]>}` : `${K}`; }[keyof T & (string | number)] : never;
+type NullishToUndefined<T> = [Extract<T, null | undefined>] extends [never] ? never : undefined;
+/**
+ * The type found at a dotted path of `T`, or `any` for an unknown path.
+ */
+type PathValue<T, P extends string> = P extends `${infer Head}.${infer Rest}` ? PathStep<T, Head> extends infer Next ? ([Next] extends [typeof _NOT_FOUND] ? any : PathValue<Next, Rest> | NullishToUndefined<T>) : any : PathStep<T, P> extends infer Next ? ([Next] extends [typeof _NOT_FOUND] ? any : Next | NullishToUndefined<T>) : any;
+type PathStep<T, K extends string> = K extends keyof NonNullable<T> ? NonNullable<T>[K] : NonNullable<T> extends readonly (infer E)[] ? (K extends `${number}` ? E | undefined : typeof _NOT_FOUND) : typeof _NOT_FOUND;
+/**
+ * A path: a known dotted path (completed by your editor), any other string
+ * like `"items[0].name"`, or an array of keys.
+ */
+type PathInput<T> = Paths<T> | (string & {}) | ReadonlyArray<string | number>;
+/**
+ * `T`, read-only all the way down.
+ */
+type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
+/**
+ * One difference reported by `diff()`.
+ */
+type Change = {
+    /**
+     * Where it changed, like `["address", "city"]`.
+     */
+    path: Array<string | number>;
+    type: "added" | "removed" | "changed";
+    /**
+     * The old value.
+     */
+    from?: unknown;
+    /**
+     * The new value.
+     */
+    to?: unknown;
+};
+/**
+ * Options for `mergeWith()`.
+ */
+type MergeOptions = {
+    /**
+     * When both sides have an array: keep the last, join them, or join without duplicates. Defaults to `"replace"`.
+     */
+    arrays?: "concat" | "replace" | "unique" | undefined;
+    /**
+     * Don't let `undefined` overwrite an existing value.
+     */
+    skipUndefined?: boolean | undefined;
+};
+/**
+ * Options for `sortKeys()`.
+ */
+type SortKeysOptions = {
+    /**
+     * Sort nested objects too, arrays included. Defaults to `true`. With `false`, only the first level is copied and sorted: what it holds is shared with the original.
+     */
+    deep?: boolean | undefined;
+    /**
+     * How to order two keys. Defaults to code-unit order, which is stable across machines.
+     */
+    compare?: ((a: string, b: string) => number) | undefined;
+};
+/**
+ * Options for `compact()`.
+ */
+type CompactOptions = {
+    /**
+     * Clean nested objects and arrays too.
+     */
+    deep?: boolean | undefined;
+    /**
+     * Also remove `""`, `[]` and `{}`.
+     */
+    removeEmpty?: boolean | undefined;
+};
+/**
+ * Deep copy. Unlike `structuredClone`, it keeps functions and class
+ * instances (with their prototype), and it's faster on plain data. Shared
+ * references and cycles are preserved.
  *
- * Uses the native `structuredClone` when the value supports it (plain data,
- * Dates, Maps, Sets, typed arrays, ...), and falls back to a manual deep copy
- * otherwise. Functions are copied by reference.
+ * @example
+ * const copy = obj.clone({ a: { b: [1, 2] }, when: new Date() });
+ * copy.a.b.push(3); // the original is untouched
+ *
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+declare function clone<T>(value: T): T;
+/**
+ * Deep-merges objects into a new one. Later objects win, nested objects are
+ * merged, arrays are replaced. See `mergeWith()` to join arrays instead.
  *
  * @example
- * const copy = nodeComfort.obj.clone({ a: { b: 1 } });
+ * obj.merge({ db: { host: "localhost", port: 5432 } }, { db: { port: 6543 } });
+ * // { db: { host: "localhost", port: 6543 } }
+ *
+ * @template {object} A
+ * @overload
+ * @param {A} a
+ * @returns {A}
+ */
+declare function merge<A extends object>(a: A): A;
+/**
+ * Deep-merges `b` into a copy of `a`.
+ *
+ * @template {object} A
+ * @template {object} B
+ * @overload
+ * @param {A} a
+ * @param {B} b
+ * @returns {A & B}
+ */
+declare function merge<A extends object, B extends object>(a: A, b: B): A & B;
+/**
+ * Deep-merges three objects; the last one wins.
+ *
+ * @template {object} A
+ * @template {object} B
+ * @template {object} C
+ * @overload
+ * @param {A} a
+ * @param {B} b
+ * @param {C} c
+ * @returns {A & B & C}
+ */
+declare function merge<A extends object, B extends object, C extends object>(a: A, b: B, c: C): A & B & C;
+/**
+ * Deep-merges any number of objects; the last one wins.
+ *
+ * @overload
+ * @param {...object} sources
+ * @returns {Record<string, any>}
+ */
+declare function merge(...sources: object[]): Record<string, any>;
+/**
+ * Like `merge()`, with a choice of what happens to arrays and `undefined`.
+ *
+ * @example
+ * obj.mergeWith({ arrays: "unique" }, { tags: ["a", "b"] }, { tags: ["b", "c"] });
+ * // { tags: ["a", "b", "c"] }
+ * obj.mergeWith({ skipUndefined: true }, { port: 80 }, { port: undefined });
+ * // { port: 80 }
+ *
+ * @param {MergeOptions} options
+ * @param {...object} sources
+ * @returns {Record<string, any>}
+ */
+declare function mergeWith(options: MergeOptions, ...sources: object[]): Record<string, any>;
+/**
+ * Fills in missing properties from defaults, deeply. Values that are set,
+ * even `null` or `0`, are kept.
+ *
+ * @example
+ * obj.defaults({ port: 8080, db: { user: "me" } }, { port: 80, db: { user: "root", pass: "" } });
+ * // { port: 8080, db: { user: "me", pass: "" } }
+ *
+ * @template {object} T
+ * @template {object} D
+ * @param {T} target
+ * @param {...D} sources The first one has the highest priority.
+ * @returns {T & D}
+ */
+declare function defaults<T extends object, D extends object>(target: T, ...sources: D[]): T & D;
+/**
+ * Deep equality. Knows about arrays, dates, regexes, maps, sets, typed
+ * arrays, `NaN` and circular references.
+ *
+ * @example
+ * obj.equal({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }); // true
+ * obj.equal(new Set([1, 2]), new Set([2, 1]));          // true
+ * obj.equal({ a: 1 }, { a: 1, b: undefined });          // false
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+declare function equal(a: unknown, b: unknown): boolean;
+/**
+ * Lists what changed between two values, deeply. Handy for audit logs and
+ * partial updates.
+ *
+ * @example
+ * obj.diff({ name: "Ada", tags: ["a"] }, { name: "Ada L.", tags: ["a", "b"] });
+ * // [
+ * //   { path: ["name"], type: "changed", from: "Ada", to: "Ada L." },
+ * //   { path: ["tags", 1], type: "added", to: "b" },
+ * // ]
+ *
+ * @param {unknown} before
+ * @param {unknown} after
+ * @returns {Change[]} Empty when nothing changed.
+ */
+declare function diff(before: unknown, after: unknown): Change[];
+/**
+ * Reads a nested value from a dotted path. Your editor completes the paths
+ * and knows the type of the result.
+ *
+ * @example
+ * obj.get(config, "db.pool.max");      // number | undefined
+ * obj.get(config, "db.pool.max", 10);  // number
+ * obj.get(data, "users[0].name");
+ * obj.get(data, ["users", 0, "name"]);
+ *
+ * @template T
+ * @template {string} P
+ * @overload
+ * @param {T} object
+ * @param {P | Paths<T> | ReadonlyArray<string | number>} path Like `"a.b.c"`, `"a[0].b"` or `["a", 0, "b"]`.
+ * @returns {PathValue<T, P>}
+ */
+declare function get<T, P extends string>(object: T, path: P | Paths<T> | ReadonlyArray<string | number>): PathValue<T, P>;
+/**
+ * Reads a nested value from a dotted path, or returns `fallback` if there's
+ * nothing there.
  *
  * @template T
- * @param {T} value - Value to clone.
- * @returns {T} A deep copy.
+ * @template {string} P
+ * @template F
+ * @overload
+ * @param {T} object
+ * @param {P | Paths<T> | ReadonlyArray<string | number>} path Like `"a.b.c"`, `"a[0].b"` or `["a", 0, "b"]`.
+ * @param {F} fallback
+ * @returns {Exclude<PathValue<T, P>, undefined> | F}
  */
-export function clone<T>(value: T): T;
+declare function get<T, P extends string, F>(object: T, path: P | Paths<T> | ReadonlyArray<string | number>, fallback: F): Exclude<PathValue<T, P>, undefined> | F;
 /**
- * Deeply merges two or more plain objects into a new object.
+ * Returns a copy with a nested value set. Missing levels are created
+ * (arrays when the next key is a number).
+ *
+ * @example
+ * obj.set({}, "a.b.c", 1);            // { a: { b: { c: 1 } } }
+ * obj.set(state, "user.name", "Ada"); // state is untouched
+ *
+ * @template T
+ * @param {T} object
+ * @param {PathInput<T>} path
+ * @param {unknown} value
+ * @returns {T}
+ */
+declare function set<T>(object: T, path: PathInput<T>, value: unknown): T;
+/**
+ * Returns a copy where the value at `path` is replaced by what `updater`
+ * returns for it. Handy for counters and lists.
+ *
+ * @example
+ * obj.update(state, "stats.visits", (n = 0) => n + 1);
+ * obj.update(cart, "items", (items = []) => [...items, product]);
+ *
+ * @template T
+ * @param {T} object
+ * @param {PathInput<T>} path
+ * @param {(value: any) => unknown} updater Gets the current value, `undefined` if there's none.
+ * @returns {T}
+ */
+declare function update<T>(object: T, path: PathInput<T>, updater: (value: any) => unknown): T;
+/**
+ * Returns a copy without the property at `path`.
+ *
+ * @example
+ * obj.unset({ a: { b: 1, c: 2 } }, "a.b"); // { a: { c: 2 } }
  *
- * Later sources win. Plain-object values are merged recursively; arrays and
- * other values are replaced (not concatenated). Inputs are never mutated.
+ * @template T
+ * @param {T} object
+ * @param {PathInput<T>} path
+ * @returns {T}
+ */
+declare function unset<T>(object: T, path: PathInput<T>): T;
+/**
+ * Does the path exist? A property set to `undefined` still counts.
  *
  * @example
- * nodeComfort.obj.merge({ a: { x: 1 } }, { a: { y: 2 } });
- * // { a: { x: 1, y: 2 } }
+ * obj.has({ a: { b: undefined } }, "a.b"); // true
+ * obj.has({ a: {} }, "a.b");               // false
  *
- * @param {...Record<string, any>} sources - Objects to merge.
- * @returns {Record<string, any>} The merged object.
+ * @template T
+ * @param {T} object
+ * @param {PathInput<T>} path
+ * @returns {boolean}
  */
-export function merge(...sources: Record<string, any>[]): Record<string, any>;
+declare function has<T>(object: T, path: PathInput<T>): boolean;
 /**
- * Deeply compares two values for structural equality.
+ * A copy with only the listed keys.
+ *
+ * @example
+ * obj.pick(user, ["id", "email"]);
  *
- * Handles plain objects, arrays, Dates, RegExps, Maps and Sets.
+ * @template {object} T
+ * @template {keyof T} K
+ * @param {T} object
+ * @param {readonly K[]} keys
+ * @returns {Pick<T, K>}
+ */
+declare function pick<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * A copy without the listed keys.
  *
  * @example
- * nodeComfort.obj.equal({ a: [1, 2] }, { a: [1, 2] }); // true
+ * obj.omit(user, ["password", "token"]);
  *
- * @param {*} a - First value.
- * @param {*} b - Second value.
- * @returns {boolean} True if the values are deeply equal.
+ * @template {object} T
+ * @template {keyof T} K
+ * @param {T} object
+ * @param {readonly K[]} keys
+ * @returns {Omit<T, K>}
  */
-export function equal(a: any, b: any): boolean;
+declare function omit<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Omit<T, K>;
 /**
- * Gets a nested value from an object using a dot/bracket path.
+ * Keeps the entries that pass a test.
  *
  * @example
- * nodeComfort.obj.get({ a: { b: [{ c: 42 }] } }, "a.b[0].c");    // 42
- * nodeComfort.obj.get({}, "a.b.c", "default");                   // "default"
+ * obj.filter({ a: 1, b: 2, c: 3 }, (value) => value > 1); // { b: 2, c: 3 }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string|Array<string|number>} path - Dot path or key array.
- * @param {*} [fallback] - Returned when the path does not resolve.
- * @returns {*} The value at the path, or the fallback.
+ * @template {object} T
+ * @param {T} object
+ * @param {(value: T[keyof T], key: keyof T & string) => unknown} predicate
+ * @returns {Partial<T>}
  */
-export function get(object: Record<string, any>, path: string | Array<string | number>, fallback?: any): any;
+declare function filter<T extends object>(object: T, predicate: (value: T[keyof T], key: keyof T & string) => unknown): Partial<T>;
 /**
- * Sets a nested value in an object using a dot/bracket path (returns a clone).
+ * Transforms every value, keeping the keys.
+ *
+ * @example
+ * obj.mapValues({ a: 1, b: 2 }, (v) => v * 10); // { a: 10, b: 20 }
  *
- * Intermediate objects/arrays are created as needed. The original object is
- * not mutated.
+ * @template {object} T
+ * @template R
+ * @param {T} object
+ * @param {(value: T[keyof T], key: keyof T & string) => R} fn
+ * @returns {{ [K in keyof T]: R }}
+ */
+declare function mapValues<T extends object, R>(object: T, fn: (value: T[keyof T], key: keyof T & string) => R): { [K in keyof T]: R; };
+/**
+ * Transforms every key, keeping the values.
  *
  * @example
- * nodeComfort.obj.set({}, "a.b.c", 1); // { a: { b: { c: 1 } } }
+ * obj.mapKeys({ first_name: "Ada" }, (key) => nc.str.camelCase(key)); // { firstName: "Ada" }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string|Array<string|number>} path - Dot path or key array.
- * @param {*} value - Value to set.
- * @returns {Record<string, any>} A new object with the value set.
+ * @template {object} T
+ * @param {T} object
+ * @param {(key: keyof T & string, value: T[keyof T]) => PropertyKey} fn Returns the new key.
+ * @returns {Record<string, T[keyof T]>}
  */
-export function set(object: Record<string, any>, path: string | Array<string | number>, value: any): Record<string, any>;
+declare function mapKeys<T extends object>(object: T, fn: (key: keyof T & string, value: T[keyof T]) => PropertyKey): Record<string, T[keyof T]>;
 /**
- * Checks whether a nested path exists in an object.
+ * Renames some keys and leaves the others alone.
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string|Array<string|number>} path - Dot path or key array.
- * @returns {boolean} True if the path resolves.
+ * @example
+ * obj.renameKeys({ _id: 1, name: "Ada" }, { _id: "id" }); // { id: 1, name: "Ada" }
+ *
+ * @template {object} T
+ * @param {T} object
+ * @param {Partial<Record<keyof T, string>>} mapping Old name to new name.
+ * @returns {Record<string, T[keyof T]>}
  */
-export function has(object: Record<string, any>, path: string | Array<string | number>): boolean;
+declare function renameKeys<T extends object>(object: T, mapping: Partial<Record<keyof T, string>>): Record<string, T[keyof T]>;
 /**
- * Returns a new object containing only the given keys.
+ * Swaps keys and values.
  *
  * @example
- * nodeComfort.obj.pick({ a: 1, b: 2, c: 3 }, ["a", "c"]); // { a: 1, c: 3 }
+ * obj.invert({ a: "x", b: "y" }); // { x: "a", y: "b" }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string[]} keys - Keys to keep.
- * @returns {Record<string, any>} The picked object.
+ * @param {Record<string, PropertyKey>} object
+ * @returns {Record<string, string>}
  */
-export function pick(object: Record<string, any>, keys: string[]): Record<string, any>;
+declare function invert(object: Record<string, PropertyKey>): Record<string, string>;
 /**
- * Returns a new object without the given keys.
+ * Removes `null` and `undefined` values, and optionally empty ones.
  *
  * @example
- * nodeComfort.obj.omit({ a: 1, b: 2, c: 3 }, ["b"]); // { a: 1, c: 3 }
+ * obj.compact({ a: 1, b: null, c: undefined });                          // { a: 1 }
+ * obj.compact({ a: { b: null, c: "" } }, { deep: true, removeEmpty: true }); // {}
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string[]} keys - Keys to remove.
- * @returns {Record<string, any>} The remaining object.
+ * @template {object} T
+ * @param {T} object
+ * @param {CompactOptions} [options]
+ * @returns {Partial<T>}
  */
-export function omit(object: Record<string, any>, keys: string[]): Record<string, any>;
+declare function compact<T extends object>(object: T, options?: CompactOptions): Partial<T>;
 /**
- * Returns a new object keeping only the entries that pass a predicate.
+ * Flattens nested objects into dotted keys. Arrays stay as values.
  *
  * @example
- * nodeComfort.obj.filter({ a: 1, b: 2, c: 3 }, (v) => v > 1); // { b: 2, c: 3 }
+ * obj.flatten({ db: { host: "x", port: 5432 } }); // { "db.host": "x", "db.port": 5432 }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {(value: any, key: string) => boolean} predicate - Test function.
- * @returns {Record<string, any>} The filtered object.
+ * @param {object} object
+ * @param {string} [prefix=""] Added in front of every key.
+ * @returns {Record<string, unknown>}
  */
-export function filter(object: Record<string, any>, predicate: (value: any, key: string) => boolean): Record<string, any>;
+declare function flatten(object: object, prefix?: string): Record<string, unknown>;
 /**
- * Maps over an object's values, returning a new object with the same keys.
+ * Rebuilds nested objects from dotted keys. The opposite of `flatten()`.
  *
  * @example
- * nodeComfort.obj.mapValues({ a: 1, b: 2 }, (v) => v * 10); // { a: 10, b: 20 }
+ * obj.unflatten({ "db.host": "x", "db.port": 5432 }); // { db: { host: "x", port: 5432 } }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {(value: any, key: string) => any} fn - Mapping function.
- * @returns {Record<string, any>} The mapped object.
+ * @param {Record<string, unknown>} object
+ * @returns {Record<string, any>}
  */
-export function mapValues(object: Record<string, any>, fn: (value: any, key: string) => any): Record<string, any>;
+declare function unflatten(object: Record<string, unknown>): Record<string, any>;
 /**
- * Maps over an object's keys, returning a new object with remapped keys.
+ * Every leaf path of an object, in dotted form. Arrays count as leaves.
  *
  * @example
- * nodeComfort.obj.mapKeys({ a: 1 }, (k) => k.toUpperCase()); // { A: 1 }
+ * obj.paths({ db: { host: "x", port: 5432 }, tags: ["a"] }); // ["db.host", "db.port", "tags"]
  *
- * @param {Record<string, any>} object - Source object.
- * @param {(key: string, value: any) => string} fn - Key-mapping function.
- * @returns {Record<string, any>} The remapped object.
+ * @param {object} object
+ * @returns {string[]}
  */
-export function mapKeys(object: Record<string, any>, fn: (key: string, value: any) => string): Record<string, any>;
+declare function paths(object: object): string[];
 /**
- * Swaps keys and values of an object.
+ * A copy with its keys in order, nested objects included. Two objects with
+ * the same content then give the same JSON, which makes stable hashes,
+ * cache keys and readable diffs.
  *
  * @example
- * nodeComfort.obj.invert({ a: "x", b: "y" }); // { x: "a", y: "b" }
+ * obj.sortKeys({ b: 1, a: { d: 1, c: 2 } }); // { a: { c: 2, d: 1 }, b: 1 }
+ * nc.crypto.hash(JSON.stringify(obj.sortKeys(payload)));
  *
- * @param {Record<string, any>} object - Source object.
- * @returns {Record<string, string>} The inverted object.
+ * @template T
+ * @param {T} object
+ * @param {SortKeysOptions} [options]
+ * @returns {T}
  */
-export function invert(object: Record<string, any>): Record<string, string>;
+declare function sortKeys<T>(object: T, options?: SortKeysOptions): T;
 /**
- * Removes entries whose value is `null` or `undefined` (shallow).
+ * `Object.keys`, but typed with the object's actual keys.
  *
  * @example
- * nodeComfort.obj.compact({ a: 1, b: null, c: undefined }); // { a: 1 }
+ * for (const key of obj.keys(config)) config[key]; // no type error
+ *
+ * @template {object} T
+ * @param {T} object
+ * @returns {Array<keyof T & string>}
+ */
+declare function keys<T extends object>(object: T): Array<keyof T & string>;
+/**
+ * `Object.entries`, with typed keys and values.
  *
- * @param {Record<string, any>} object - Source object.
- * @returns {Record<string, any>} The compacted object.
+ * @template {object} T
+ * @param {T} object
+ * @returns {Array<[keyof T & string, T[keyof T]]>}
  */
-export function compact(object: Record<string, any>): Record<string, any>;
+declare function entries<T extends object>(object: T): Array<[keyof T & string, T[keyof T]]>;
 /**
- * Flattens a nested object into a single-level object with dot-path keys.
+ * `Object.fromEntries` that accepts any iterable (a `Map` too) and skips
+ * unsafe keys.
  *
  * @example
- * nodeComfort.obj.flatten({ a: { b: { c: 1 } } }); // { "a.b.c": 1 }
+ * obj.fromEntries(new Map([["x", true]])); // { x: true }
  *
- * @param {Record<string, any>} object - Source object.
- * @param {string} [prefix=""] - Prefix for keys (used internally).
- * @returns {Record<string, any>} The flattened object.
+ * @template {PropertyKey} K
+ * @template V
+ * @param {Iterable<readonly [K, V]>} pairs
+ * @returns {Record<K, V>}
  */
-export function flatten(object: Record<string, any>, prefix?: string): Record<string, any>;
+declare function fromEntries<K extends PropertyKey, V>(pairs: Iterable<readonly [K, V]>): Record<K, V>;
 /**
- * Rebuilds a nested object from a flat, dot-path keyed object.
+ * How many entries: own keys of an object, size of a map or set, length of
+ * an array or string.
  *
  * @example
- * nodeComfort.obj.unflatten({ "a.b.c": 1 }); // { a: { b: { c: 1 } } }
+ * obj.size({ a: 1, b: 2 }); // 2
  *
- * @param {Record<string, any>} object - Flat object.
- * @returns {Record<string, any>} The nested object.
+ * @param {unknown} value
+ * @returns {number}
  */
-export function unflatten(object: Record<string, any>): Record<string, any>;
+declare function size(value: unknown): number;
 /**
- * Checks whether an object has no own enumerable keys.
+ * Is there nothing in it? No own keys for an object, no entries for a Map
+ * or a Set. `null` and `undefined` count as empty; a date, a regular
+ * expression and an error never do.
  *
- * @param {Record<string, any>} object - Source object.
- * @returns {boolean} True if the object is empty.
+ * @example
+ * obj.isEmpty({});                  // true
+ * obj.isEmpty(new Map([["a", 1]])); // false
+ *
+ * @param {unknown} object
+ * @returns {boolean}
  */
-export function isEmpty(object: Record<string, any>): boolean;
+declare function isEmpty(object: unknown): boolean;
 /**
- * Freezes an object deeply, making it (and all nested objects) immutable.
+ * Freezes an object and everything inside it. Good for configuration and
+ * constants.
  *
- * @param {Record<string, any>} object - Object to freeze.
- * @returns {Record<string, any>} The same, now deeply-frozen, object.
+ * @example
+ * const CONFIG = obj.deepFreeze({ db: { host: "localhost" } });
+ * CONFIG.db.host = "x"; // TypeScript error, and ignored at runtime
+ *
+ * @template T
+ * @param {T} object
+ * @returns {DeepReadonly<T>} The same object.
  */
-export function deepFreeze(object: Record<string, any>): Record<string, any>;
+declare function deepFreeze<T>(object: T): DeepReadonly<T>;
+/** Marks an unknown path segment in `PathStep`. */
+declare const _NOT_FOUND: unique symbol;
 //# sourceMappingURL=Obj.d.ts.map