ts-data-forge 14.6.2 → 14.6.4

package/dist/object/object.mjs

@@ -1,58 +1,58 @@
 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);
@@ -66,7 +66,7 @@ export var Obj;
                 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: {
@@ -82,15 +82,15 @@ export var Obj;
                 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;
                 };
@@ -98,213 +98,213 @@ export var Obj;
         }
     }
     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);
-    /**
-     * 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 (
-        // `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))));
     }
     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 (
-        // `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: {
@@ -319,7 +319,7 @@ export var Obj;
             case 2: {
                 const [record, path] = args;
                 return (
-                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
                 deepOmitImpl(record, path));
             }
             case 1: {

package/dist/others/cast-mutable.mjs

@@ -1,38 +1,38 @@
-/**
- * Casts a readonly type `T` to its `Mutable<T>` equivalent.
- *
- * **⚠️ Safety Warning**: This is a type assertion that bypasses TypeScript's
- * immutability guarantees. The runtime value remains unchanged - only the type
- * system's view of it changes. Use with caution as it can lead to unexpected
- * mutations of data that was intended to be immutable.
- *
- * @template T - The type of the readonly value
- * @param readonlyValue - The readonly value to cast to mutable
- * @returns The same value with readonly modifiers removed from its type
- * @see castDeepMutable - For deeply nested readonly structures
- * @see castReadonly - For the opposite operation
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const castMutable = (readonlyValue) => 
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+
 readonlyValue;
-/**
- * Casts a readonly type `T` to its `DeepMutable<T>` equivalent, recursively
- * removing all readonly modifiers.
- *
- * **⚠️ Safety Warning**: This recursively bypasses ALL immutability guarantees
- * in nested structures. Extremely dangerous for complex data structures as it
- * allows mutation at any depth. The runtime value is unchanged - only
- * TypeScript's type checking is affected.
- *
- * @template T - The type of the deeply readonly value
- * @param readonlyValue - The deeply readonly value to cast to deeply mutable
- * @returns The same value with all readonly modifiers recursively removed from
- *   its type
- * @see castMutable - For shallow mutability casting
- * @see castDeepReadonly - For the opposite operation
- * @see structuredClone - Recommended for creating safe copies before mutation
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const castDeepMutable = (readonlyValue) => 
-// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
 readonlyValue;
 //# sourceMappingURL=cast-mutable.mjs.map

package/dist/others/cast-readonly.mjs

@@ -1,37 +1,37 @@
-/**
- * Casts a mutable type `T` to its `Readonly<T>` equivalent.
- *
- * This is a safe type assertion that adds immutability constraints at the type
- * level. The runtime value remains unchanged - only TypeScript's view of it
- * becomes readonly. This helps prevent accidental mutations and makes code
- * intentions clearer.
- *
- * @template T - The type of the mutable value
- * @param mutable - The mutable value to cast to readonly
- * @returns The same value with readonly modifiers added to its type
- * @see castDeepReadonly - For deeply nested structures
- * @see castMutable - For the opposite operation (use with caution)
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const castReadonly = (mutable) => 
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+
 mutable;
-/**
- * Casts a mutable type `T` to its `DeepReadonly<T>` equivalent, recursively
- * adding readonly modifiers.
- *
- * This is a safe type assertion that adds immutability constraints at ALL
- * levels of nesting. Provides complete protection against mutations in complex
- * data structures. The runtime value is unchanged - only TypeScript's type
- * checking is enhanced.
- *
- * @template T - The type of the mutable value
- * @param mutable - The mutable value to cast to deeply readonly
- * @returns The same value with readonly modifiers recursively added to all
- *   properties
- * @see castReadonly - For shallow readonly casting
- * @see castDeepMutable - For the opposite operation (use with extreme caution)
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const castDeepReadonly = (mutable) => 
-// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
 mutable;
 //# sourceMappingURL=cast-readonly.mjs.map