ts-data-forge 14.6.0 → 14.6.2

package/dist/object/object.mjs

@@ -1,214 +1,367 @@
-import '../number/branded-types/finite-number.mjs';
-import '../number/branded-types/int.mjs';
-import '../number/branded-types/int16.mjs';
-import '../number/branded-types/int32.mjs';
-import '../number/branded-types/negative-finite-number.mjs';
-import '../number/branded-types/negative-int.mjs';
-import '../number/branded-types/negative-safe-int.mjs';
-import '../number/branded-types/non-negative-finite-number.mjs';
-import '../number/branded-types/non-negative-int16.mjs';
-import '../number/branded-types/non-negative-int32.mjs';
-import '../number/branded-types/non-positive-finite-number.mjs';
-import '../number/branded-types/non-positive-int.mjs';
-import '../number/branded-types/non-positive-safe-int.mjs';
-import '../number/branded-types/non-zero-finite-number.mjs';
-import '../number/branded-types/non-zero-int.mjs';
-import '../number/branded-types/non-zero-int16.mjs';
-import '../number/branded-types/non-zero-int32.mjs';
-import '../number/branded-types/non-zero-safe-int.mjs';
-import '../number/branded-types/non-zero-uint16.mjs';
-import '../number/branded-types/non-zero-uint32.mjs';
-import '../number/branded-types/positive-finite-number.mjs';
-import '../number/branded-types/positive-int.mjs';
-import '../number/branded-types/positive-int16.mjs';
-import '../number/branded-types/positive-int32.mjs';
-import '../number/branded-types/positive-safe-int.mjs';
-import '../number/branded-types/positive-uint16.mjs';
-import '../number/branded-types/positive-uint32.mjs';
-import '../number/branded-types/safe-int.mjs';
-import '../number/branded-types/safe-uint.mjs';
-import '../number/branded-types/uint.mjs';
-import '../number/branded-types/uint16.mjs';
-import '../number/branded-types/uint32.mjs';
-import '../number/enum/int8.mjs';
-import '../number/enum/uint8.mjs';
-import '../number/num.mjs';
-import '../number/refined-number-utils.mjs';
-import { isSome } from '../functional/optional/impl/optional-is-some.mjs';
-import { hasKey } from '../guard/has-key.mjs';
-import { isRecord } from '../guard/is-record.mjs';
-import '@sindresorhus/is';
-import { isNonEmpty } from '../array/impl/array-utils-length-bounded-array-guard.mjs';
-import '../collections/imap-mapped.mjs';
-import '../collections/imap.mjs';
-import '../collections/iset-mapped.mjs';
-import '../collections/iset.mjs';
-
-var Obj;
-((Obj2) => {
-  Obj2.shallowEq = (a, b, eq = Object.is) => {
-    const aEntries = Object.entries(a);
-    const bEntries = Object.entries(b);
-    if (aEntries.length !== bEntries.length) return false;
-    return aEntries.every(([k, v]) => eq(b[k], v));
-  };
-  function pick(...args) {
-    switch (args.length) {
-      case 2: {
-        const [record, keys] = args;
-        const keysSet = new Set(keys);
-        return (
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-          Object.fromEntries(
-            Object.entries(record).filter(([k, _v]) => keysSet.has(k))
-          )
-        );
-      }
-      case 1: {
-        const [keys] = args;
-        return (record) => pick(record, keys);
-      }
+import { Arr } from '../array/index.mjs';
+import { Optional } from '../functional/index.mjs';
+import { hasKey, isRecord } from '../guard/index.mjs';
+/**
+ * A collection of type-safe object utility functions providing functional
+ * programming patterns for object manipulation, including pick, omit, shallow
+ * equality checks, and more.
+ *
+ * All functions maintain TypeScript type safety and support both direct and
+ * curried usage patterns for better composition with pipe operations.
+ */
+export var Obj;
+(function (Obj) {
+    /**
+     * Performs a shallow equality check on two records using a configurable
+     * equality function. Verifies that both records have the same number of
+     * entries and that for every key in the first record, the corresponding value
+     * passes the equality test with the value in the second record.
+     *
+     * @example
+     *
+     * ```ts
+     * const obj1 = { name: 'Alice', age: 30 } as const;
+     *
+     * const obj2 = { name: 'Alice', age: 30 } as const;
+     *
+     * const obj3 = { name: 'Alice', age: 31 } as const;
+     *
+     * assert.isTrue(Obj.shallowEq(obj1, obj2));
+     *
+     * assert.isFalse(Obj.shallowEq(obj1, obj3));
+     *
+     * // Custom equality function
+     * const obj4 = { value: 1 } as const;
+     *
+     * const obj5 = { value: 1.00001 } as const;
+     *
+     * const closeEnough = (a: unknown, b: unknown): boolean => {
+     *   if (typeof a === 'number' && typeof b === 'number') {
+     *     return Math.abs(a - b) < 0.001;
+     *   }
+     *
+     *   return Object.is(a, b);
+     * };
+     *
+     * assert.isTrue(Obj.shallowEq(obj4, obj5, closeEnough));
+     * ```
+     *
+     * @param a - The first record to compare
+     * @param b - The second record to compare
+     * @param eq - Optional equality function (defaults to Object.is for strict
+     *   equality)
+     * @returns `true` if the records are shallowly equal according to the
+     *   equality function, `false` otherwise
+     */
+    Obj.shallowEq = (a, b, eq = Object.is) => {
+        const aEntries = Object.entries(a);
+        const bEntries = Object.entries(b);
+        if (aEntries.length !== bEntries.length)
+            return false;
+        return aEntries.every(([k, v]) => eq(b[k], v));
+    };
+    function pick(...args) {
+        switch (args.length) {
+            case 2: {
+                const [record, keys] = args;
+                const keysSet = new Set(keys);
+                return (
+                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                Object.fromEntries(Object.entries(record).filter(([k, _v]) => keysSet.has(k))));
+            }
+            case 1: {
+                const [keys] = args;
+                return (record) => pick(record, keys);
+            }
+        }
     }
-  }
-  Obj2.pick = pick;
-  function omit(...args) {
-    switch (args.length) {
-      case 2: {
-        const [record, keys] = args;
-        const keysSet = new Set(keys);
-        return (
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-          Object.fromEntries(
-            Object.entries(record).filter(([k, _v]) => !keysSet.has(k))
-          )
-        );
-      }
-      case 1: {
-        const [keys] = args;
-        return (record) => {
-          const result = omit(
-            record,
-            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-            keys
-          );
-          return result;
-        };
-      }
+    Obj.pick = pick;
+    function omit(...args) {
+        switch (args.length) {
+            case 2: {
+                const [record, keys] = args;
+                const keysSet = new Set(keys);
+                return (
+                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                Object.fromEntries(Object.entries(record).filter(([k, _v]) => !keysSet.has(k))));
+            }
+            case 1: {
+                const [keys] = args;
+                return (record) => {
+                    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                    const result = omit(record, 
+                    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                    keys);
+                    return result;
+                };
+            }
+        }
     }
-  }
-  Obj2.omit = omit;
-  Obj2.fromEntries = (entries) => (
+    Obj.omit = omit;
+    /**
+     * Creates an object from an array of key-value pairs with precise TypeScript
+     * typing. This is a type-safe wrapper around `Object.fromEntries` that
+     * provides better type inference and compile-time guarantees about the
+     * resulting object structure.
+     *
+     * **Type Behavior**:
+     *
+     * - When entries is a fixed-length tuple, the exact object type is inferred
+     * - When entries has dynamic length with union key types, `Partial` is applied
+     *   to prevent incorrect assumptions about which keys will be present
+     *
+     * @example
+     *
+     * ```ts
+     * // Fixed-length tuple - exact type inferred
+     * const entries1 = [
+     *   ['name', 'David'],
+     *   ['age', 25],
+     *   ['active', true],
+     * ] as const;
+     *
+     * const obj1 = Obj.fromEntries(entries1);
+     *
+     * assert.deepStrictEqual(obj1, {
+     *   name: 'David',
+     *   age: 25,
+     *   active: true,
+     * });
+     *
+     * // Dynamic length array - Partial type applied
+     * const dynamicEntries: readonly (readonly ['x' | 'y', number])[] = [
+     *   ['x', 10],
+     *   ['y', 20],
+     * ] as const;
+     *
+     * const obj2 = Obj.fromEntries(dynamicEntries);
+     *
+     * assert.deepStrictEqual(obj2, { x: 10, y: 20 });
+     * ```
+     *
+     * @template Entries - The readonly array type of key-value entry tuples
+     * @param entries - An array of readonly key-value entry tuples `[key, value]`
+     * @returns An object created from the entries with precise typing
+     */
+    Obj.fromEntries = (entries) => 
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    Object.fromEntries(entries)
-  );
-  Obj2.map = (record, mapFn) => {
-    const mapFnWidened = mapFn;
-    return (
-      // `Object.entries` enumerates exactly the own enumerable string keys of
-      // `record`, and nothing here adds or removes an entry, so the result has
-      // the key set `MappedRecord` claims.
-      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      Object.fromEntries(
-        Object.entries(record).map(
-          ([k, v]) => [k, mapFnWidened(v, k)]
-        )
-      )
-    );
-  };
-  function filter(record, predicate) {
-    const predicateWidened = predicate;
-    return (
-      // `Object.entries` enumerates exactly the own enumerable string keys of
-      // `record`, and filtering only ever removes entries, so the result has a
-      // subset of those keys — which is what `FilteredRecord` claims.
-      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      Object.fromEntries(
-        Object.entries(record).filter(([k, v]) => predicateWidened(v, k))
-      )
-    );
-  }
-  Obj2.filter = filter;
-  Obj2.filterMap = (record, mapFn) => {
-    const mapFnWidened = mapFn;
-    return (
-      // `Object.entries` enumerates exactly the own enumerable string keys of
-      // `record`, and this only ever drops entries or replaces their values, so
-      // the result has a subset of those keys with `V2` values.
-      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      Object.fromEntries(
-        Object.entries(record).flatMap(([k, v]) => {
-          const mapped = mapFnWidened(v, k);
-          return isSome(mapped) ? [[k, mapped.value]] : [];
-        })
-      )
-    );
-  };
-  Obj2.merge = (...records) => (
-    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    Object.fromEntries(records.flatMap((r) => Object.entries(r)))
-  );
-  function deepPick(...args) {
-    switch (args.length) {
-      case 2: {
-        const [record, path] = args;
+    Object.fromEntries(entries);
+    /**
+     * Transforms every value of a record, leaving the key set untouched.
+     *
+     * **Type Behavior**: the result is a mapped type over `keyof R`, so the keys
+     * — and their optional modifiers — survive verbatim:
+     * `{ a: number; b?: number }` maps to `{ a: V2; b?: V2 }`, and a record with
+     * an index signature stays total rather than becoming `Partial`.
+     *
+     * This is what `Object.fromEntries(Object.entries(record).map(...))` cannot
+     * express: an entries array carries no evidence that it still covers every
+     * key of the record it came from, so its element type is all the return type
+     * can be built from. Going through a mapped type instead states the
+     * invariant that a value-only transform preserves the key set.
+     *
+     * **Key handling**: keys reach the callback the way `Object.entries` yields
+     * them, so a numeric key `1` arrives as `'1'`. Symbol-keyed properties are
+     * not enumerated by `Object.entries`; they are dropped from both the result
+     * and its type.
+     *
+     * @example
+     *
+     * <!-- doc:embed:jsdoc:example:./samples/src/object/map-example.mts -->
+     *
+     * ```ts
+     * const scores = { alice: 1, bob: 2 } as const;
+     *
+     * const doubled = Obj.map(scores, (value) => value * 2);
+     *
+     * assert.deepStrictEqual(doubled, { alice: 2, bob: 4 });
+     *
+     * // The key is available as the second argument.
+     * const labelled = Obj.map(scores, (value, key) => `${key}=${value}`);
+     *
+     * assert.deepStrictEqual(labelled, { alice: 'alice=1', bob: 'bob=2' });
+     * ```
+     *
+     * <!-- /doc:embed:jsdoc:example:./samples/src/object/map-example.mts -->
+     *
+     * @template R - The type of the source record
+     * @template V2 - The type the callback returns for every key
+     * @param record - The record whose values are transformed
+     * @param mapFn - Called once per own enumerable string key, with the value
+     *   and the key
+     * @returns A new record with the same keys as `record` and the mapped values
+     */
+    Obj.map = (record, mapFn) => {
+        // `Object.entries` erases both the key and the value type of `R`, so the
+        // callback is widened once here instead of asserting on every entry.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        const mapFnWidened = mapFn;
+        return (
+        // `Object.entries` enumerates exactly the own enumerable string keys of
+        // `record`, and nothing here adds or removes an entry, so the result has
+        // the key set `MappedRecord` claims.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        Object.fromEntries(Object.entries(record).map(([k, v]) => [k, mapFnWidened(v, k)])));
+    };
+    function filter(record, predicate) {
+        // `Object.entries` erases both the key and the value type of `R`, so the
+        // callback is widened once here instead of asserting on every entry.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        const predicateWidened = predicate;
         return (
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-          deepPickImpl(record, path)
-        );
-      }
-      case 1: {
-        const [path] = args;
-        return (record) => deepPick(record, path);
-      }
+        // `Object.entries` enumerates exactly the own enumerable string keys of
+        // `record`, and filtering only ever removes entries, so the result has a
+        // subset of those keys — which is what `FilteredRecord` claims.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        Object.fromEntries(Object.entries(record).filter(([k, v]) => predicateWidened(v, k))));
     }
-  }
-  Obj2.deepPick = deepPick;
-  function deepOmit(...args) {
-    switch (args.length) {
-      case 2: {
-        const [record, path] = args;
+    Obj.filter = filter;
+    /**
+     * Transforms and drops entries in one pass: the callback returns
+     * `Optional.some(value)` to keep an entry with a new value, or
+     * `Optional.none` to drop it.
+     *
+     * **Type Behavior**: as with {@link filter}, the surviving keys are the keys
+     * of the source record made optional, and a record keyed by an index
+     * signature stays total. Unlike {@link filter}, every kept value takes the
+     * type the callback returns.
+     *
+     * `Optional` rather than `undefined` marks the dropped entries, so a record
+     * whose values are legitimately `undefined` stays expressible.
+     *
+     * **Key handling**: keys reach the callback the way `Object.entries` yields
+     * them, so a numeric key `1` arrives as `'1'`. Symbol-keyed properties are
+     * not enumerated by `Object.entries`; they are dropped from both the result
+     * and its type.
+     *
+     * @example
+     *
+     * <!-- doc:embed:jsdoc:example:./samples/src/object/filter-map-example.mts -->
+     *
+     * ```ts
+     * const scores = { alice: 1, bob: 2 } as const;
+     *
+     * // `Optional.some` keeps an entry with a new value, `Optional.none` drops it.
+     * const labelled = Obj.filterMap(scores, (value, key) =>
+     *   value > 1 ? Optional.some(`${key}=${value}`) : Optional.none,
+     * );
+     *
+     * assert.deepStrictEqual(labelled, { bob: 'bob=2' });
+     * ```
+     *
+     * <!-- /doc:embed:jsdoc:example:./samples/src/object/filter-map-example.mts -->
+     *
+     * @template R - The type of the source record
+     * @template V2 - The type the callback returns for the entries it keeps
+     * @param record - The record whose entries are transformed and filtered
+     * @param mapFn - Called once per own enumerable string key, with the value
+     *   and the key
+     * @returns A new record holding only the kept entries, with mapped values
+     */
+    Obj.filterMap = (record, mapFn) => {
+        // `Object.entries` erases both the key and the value type of `R`, so the
+        // callback is widened once here instead of asserting on every entry.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        const mapFnWidened = mapFn;
         return (
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-          deepOmitImpl(record, path)
-        );
-      }
-      case 1: {
-        const [path] = args;
-        return (record) => deepOmit(record, path);
-      }
+        // `Object.entries` enumerates exactly the own enumerable string keys of
+        // `record`, and this only ever drops entries or replaces their values, so
+        // the result has a subset of those keys with `V2` values.
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        Object.fromEntries(Object.entries(record).flatMap(([k, v]) => {
+            const mapped = mapFnWidened(v, k);
+            return Optional.isSome(mapped) ? [[k, mapped.value]] : [];
+        })));
+    };
+    /**
+     * Merges multiple records into a single record using `Object.assign`.
+     * Later records override properties from earlier records with the same key.
+     *
+     * @example
+     *
+     * <!-- doc:embed:jsdoc:example:./samples/src/object/merge-example.mts -->
+     *
+     * ```ts
+     * const a = { a: 0, b: 0 } as const;
+     *
+     * const b = { b: 1, c: 0 } as const;
+     *
+     * const result = Obj.merge(a, b);
+     *
+     * assert.deepStrictEqual(result, { a: 0, b: 1, c: 0 });
+     * ```
+     *
+     * <!-- /doc:embed:jsdoc:example:./samples/src/object/merge-example.mts -->
+     *
+     * @param records - The records to merge
+     * @returns A new record with all properties merged
+     */
+    Obj.merge = (...records) => 
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    Object.fromEntries(records.flatMap((r) => Object.entries(r)));
+    function deepPick(...args) {
+        switch (args.length) {
+            case 2: {
+                const [record, path] = args;
+                return (
+                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                deepPickImpl(record, path));
+            }
+            case 1: {
+                const [path] = args;
+                return (record) => deepPick(record, path);
+            }
+        }
+    }
+    Obj.deepPick = deepPick;
+    function deepOmit(...args) {
+        switch (args.length) {
+            case 2: {
+                const [record, path] = args;
+                return (
+                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                deepOmitImpl(record, path));
+            }
+            case 1: {
+                const [path] = args;
+                return (record) => deepOmit(record, path);
+            }
+        }
     }
-  }
-  Obj2.deepOmit = deepOmit;
+    Obj.deepOmit = deepOmit;
 })(Obj || (Obj = {}));
 const deepPickImpl = (record, path) => {
-  if (!isNonEmpty(path)) return record;
-  const head = path[0];
-  if (!hasKey(record, head)) return {};
-  const value = record[head];
-  const tail = path.slice(1);
-  if (!isNonEmpty(tail)) return { [head]: value };
-  if (!isRecord(value)) return { [head]: {} };
-  return {
-    [head]: deepPickImpl(value, tail)
-  };
+    if (!Arr.isNonEmpty(path))
+        return record;
+    const head = path[0];
+    if (!hasKey(record, head))
+        return {};
+    const value = record[head];
+    const tail = path.slice(1);
+    if (!Arr.isNonEmpty(tail))
+        return { [head]: value };
+    if (!isRecord(value))
+        return { [head]: {} };
+    return {
+        [head]: deepPickImpl(value, tail),
+    };
 };
 const deepOmitImpl = (record, path) => {
-  if (!isNonEmpty(path)) return record;
-  const head = path[0];
-  if (!hasKey(record, head)) return record;
-  const tail = path.slice(1);
-  if (!isNonEmpty(tail)) {
-    return Object.fromEntries(
-      Object.entries(record).filter(([k]) => k !== head)
-    );
-  }
-  const value = record[head];
-  if (!isRecord(value)) return record;
-  return {
-    ...record,
-    [head]: deepOmitImpl(value, tail)
-  };
+    if (!Arr.isNonEmpty(path))
+        return record;
+    const head = path[0];
+    if (!hasKey(record, head))
+        return record;
+    const tail = path.slice(1);
+    if (!Arr.isNonEmpty(tail)) {
+        return Object.fromEntries(Object.entries(record).filter(([k]) => k !== head));
+    }
+    const value = record[head];
+    if (!isRecord(value))
+        return record;
+    return {
+        ...record,
+        [head]: deepOmitImpl(value, tail),
+    };
 };
-
-export { Obj };
-//# sourceMappingURL=object.mjs.map
+//# sourceMappingURL=object.mjs.map