ts-data-forge 6.5.0 → 6.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -88,7 +88,7 @@
   "devDependencies": {
     "@emotion/react": "11.14.0",
     "@emotion/styled": "11.14.1",
-    "@mui/material": "7.3.7",
+    "@mui/material": "7.3.9",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-strip": "3.0.4",
     "@rollup/plugin-typescript": "12.3.0",
@@ -96,38 +96,38 @@
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/exec": "7.1.0",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "12.0.3",
-    "@semantic-release/npm": "13.1.3",
+    "@semantic-release/github": "12.0.6",
+    "@semantic-release/npm": "13.1.5",
     "@semantic-release/release-notes-generator": "14.1.0",
-    "@types/node": "25.2.0",
-    "@types/react": "19.2.13",
+    "@types/node": "25.4.0",
+    "@types/react": "19.2.14",
     "@vitest/browser-playwright": "4.0.18",
     "@vitest/coverage-v8": "4.0.18",
     "@vitest/ui": "4.0.18",
-    "conventional-changelog-conventionalcommits": "9.1.0",
-    "cspell": "9.6.4",
-    "dedent": "^1.7.1",
-    "eslint": "9.39.2",
-    "eslint-config-typed": "4.6.2",
-    "github-settings-as-code": "1.1.2",
-    "immer": "11.1.3",
+    "conventional-changelog-conventionalcommits": "9.3.0",
+    "cspell": "9.7.0",
+    "dedent": "^1.7.2",
+    "eslint": "9.39.3",
+    "eslint-config-typed": "4.7.4",
+    "github-settings-as-code": "1.2.0",
+    "immer": "11.1.4",
     "jiti": "2.6.1",
     "markdownlint": "0.40.0",
-    "markdownlint-cli2": "0.20.0",
+    "markdownlint-cli2": "0.21.0",
     "npm-run-all2": "8.0.4",
-    "playwright": "1.58.1",
+    "playwright": "1.58.2",
     "prettier": "3.8.1",
     "prettier-plugin-organize-imports": "4.3.0",
-    "prettier-plugin-packagejson": "3.0.0",
+    "prettier-plugin-packagejson": "3.0.2",
     "react": "^19.2.4",
-    "rollup": "4.57.1",
+    "rollup": "4.59.0",
     "semantic-release": "25.0.3",
-    "ts-codemod-lib": "^2.0.3",
-    "ts-repo-utils": "8.1.0",
+    "ts-codemod-lib": "^2.1.1",
+    "ts-repo-utils": "9.0.0",
     "tslib": "2.8.1",
     "tsx": "4.21.0",
-    "typedoc": "0.28.16",
-    "typedoc-github-theme": "0.3.1",
+    "typedoc": "0.28.17",
+    "typedoc-github-theme": "0.4.0",
     "typescript": "5.9.3",
     "vite": "7.3.1",
     "vitest": "4.0.18"
@@ -135,7 +135,7 @@
   "peerDependencies": {
     "typescript": ">=4.8"
   },
-  "packageManager": "pnpm@10.28.2",
+  "packageManager": "pnpm@10.32.1",
   "engines": {
     "node": ">=20.11.0",
     "pnpm": ">=8.0.0"

package/src/collections/imap-mapped.mts

@@ -56,21 +56,15 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the map satisfy a predicate.
+   * Checks if all elements in the map satisfy a predicate. Also supports a
+   * type predicate overload that narrows the type of values in the map if the
+   * predicate returns true for all elements.
    *
+   * @template W The narrowed type of the values.
    * @param predicate A function to test each key-value pair.
    * @returns `true` if all elements satisfy the predicate, `false` otherwise.
    */
   every: ((predicate: (value: V, key: K) => boolean) => boolean) &
-    /**
-     * Checks if all elements in the map satisfy a type predicate. Narrows the
-     * type of values in the map if the predicate returns true for all
-     * elements.
-     *
-     * @template W The narrowed type of the values.
-     * @param predicate A type predicate function.
-     * @returns `true` if all elements satisfy the predicate, `false` otherwise.
-     */
     (<W extends V>(
       predicate: (value: V, key: K) => value is W,
     ) => this is IMapMapped<K, W, KM>);

package/src/collections/imap.mts

@@ -93,7 +93,9 @@ type IMapInterface<K extends MapSetKeyType, V> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the map satisfy a predicate.
+   * Checks if all elements in the map satisfy a predicate. Also supports a
+   * type predicate overload that narrows the type of values in the map if the
+   * predicate returns true for all elements.
    *
    * @example
    *
@@ -112,19 +114,11 @@ type IMapInterface<K extends MapSetKeyType, V> = Readonly<{
    * assert.isTrue(isNarrowed);
    * ```
    *
+   * @template W The narrowed type of the values.
    * @param predicate A function to test each key-value pair.
    * @returns `true` if all elements satisfy the predicate, `false` otherwise.
    */
   every: ((predicate: (value: V, key: K) => boolean) => boolean) &
-    /**
-     * Checks if all elements in the map satisfy a type predicate. Narrows the
-     * type of values in the map if the predicate returns true for all
-     * elements.
-     *
-     * @template W The narrowed type of the values.
-     * @param predicate A type predicate function.
-     * @returns `true` if all elements satisfy the predicate, `false` otherwise.
-     */
     (<W extends V>(
       predicate: (value: V, key: K) => value is W,
     ) => this is IMap<K, W>);

package/src/collections/iset-mapped.mts

@@ -129,7 +129,10 @@ type ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the set satisfy a predicate.
+   * Checks if all elements in the set satisfy a type predicate. Narrows the
+   * type of elements in the set if the predicate returns true for all
+   * elements.
+   *
    *
    * @example
    *
@@ -162,19 +165,11 @@ type ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{
    * assert.isTrue(narrowed);
    * ```
    *
+   * @template L The narrowed type of the elements.
    * @param predicate A function to test each element.
    * @returns `true` if all elements satisfy the predicate, `false` otherwise.
    */
   every: ((predicate: (key: K) => boolean) => boolean) &
-    /**
-     * Checks if all elements in the set satisfy a type predicate. Narrows the
-     * type of elements in the set if the predicate returns true for all
-     * elements.
-     *
-     * @template L The narrowed type of the elements.
-     * @param predicate A type predicate function.
-     * @returns `true` if all elements satisfy the predicate, `false` otherwise.
-     */
     (<L extends K>(
       predicate: (key: K) => key is L,
     ) => this is ISetMapped<L, KM>);

package/src/collections/iset.mts

@@ -83,7 +83,9 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
   // Reducing a value
 
   /**
-   * Checks if all elements in the set satisfy a predicate.
+   * Checks if all elements in the set satisfy a predicate. Also supports a
+   * type predicate overload that narrows the type of elements in the set if
+   * the predicate returns true for all elements.
    *
    * @example
    *
@@ -101,19 +103,11 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
    * assert.isTrue(narrowed);
    * ```
    *
+   * @template L The narrowed type of the elements.
    * @param predicate A function to test each element.
    * @returns `true` if all elements satisfy the predicate, `false` otherwise.
    */
   every: ((predicate: (key: K) => boolean) => boolean) &
-    /**
-     * Checks if all elements in the set satisfy a type predicate. Narrows the
-     * type of elements in the set if the predicate returns true for all
-     * elements.
-     *
-     * @template L The narrowed type of the elements.
-     * @param predicate A type predicate function.
-     * @returns `true` if all elements satisfy the predicate, `false` otherwise.
-     */
     (<L extends K>(predicate: (key: K) => key is L) => this is ISet<L>);
 
   /**
@@ -234,8 +228,8 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
   map: <K2 extends MapSetKeyType>(mapFn: (key: K) => K2) => ISet<K2>;
 
   /**
-   * Filters the elements of the set based on a type predicate. Narrows the type
-   * of elements in the resulting set.
+   * Filters the elements of the set based on a predicate. Also supports a type
+   * predicate overload that narrows the type of elements in the resulting set.
    *
    * @example
    *
@@ -254,16 +248,10 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
    * ```
    *
    * @template K2 The narrowed type of the elements.
-   * @param predicate A type predicate function.
-   * @returns A new ISet instance with elements that satisfy the type predicate.
+   * @param predicate A function to test each element.
+   * @returns A new ISet instance with elements that satisfy the predicate.
    */
   filter: (<K2 extends K>(predicate: (key: K) => key is K2) => ISet<K2>) &
-    /**
-     * Filters the elements of the set based on a predicate.
-     *
-     * @param predicate A function to test each element.
-     * @returns A new ISet instance with elements that satisfy the predicate.
-     */
     ((predicate: (key: K) => boolean) => ISet<K>);
 
   /**

package/src/object/object.mts

@@ -306,77 +306,197 @@ export namespace Obj {
     Object.fromEntries(entries) as never;
 
   /**
-   * @internal
-   * Internal type utilities for the Obj module.
+   * Merges multiple records into a single record using `Object.assign`.
+   * Later records override properties from earlier records with the same key.
+   *
+   * @example
+   *
+   * ```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 });
+   * ```
+   *
+   * @param records - The records to merge
+   * @returns A new record with all properties merged
    */
-  declare namespace TsDataForgeInternals {
-    type RecursionLimit = 20;
+  export const merge = <const Records extends readonly UnknownRecord[]>(
+    ...records: Records
+  ): TsDataForgeInternals.MergeAll<Records> =>
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    Object.fromEntries(records.flatMap((r) => Object.entries(r))) as never;
+}
+
+/**
+ * @internal
+ * Internal type utilities for the Obj module.
+ */
+declare namespace TsDataForgeInternals {
+  type RecursionLimit = 20;
+
+  /** - `[['x', 1], ['y', 3]]` -> `{ x: 1, y: 3 }` */
+  export type EntriesToObject<
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  > = Readonly<EntriesToObjectImpl<{}, Entries>>;
 
-    /** - `[['x', 1], ['y', 3]]` -> `{ x: 1, y: 3 }` */
-    export type EntriesToObject<
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-      // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-    > = Readonly<EntriesToObjectImpl<{}, Entries>>;
+  /** @internal */
+  type EntriesToObjectImpl<
+    R,
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+  > =
+    TypeEq<Entries['length'], 0> extends true
+      ? R
+      : EntriesToObjectImpl<
+          R & Readonly<Record<Entries[0][0], Entries[0][1]>>,
+          List.Tail<Entries>
+        >;
+
+  /**
+   * - `['x' | 'y' | 'z', number][]]` -> `'x' | 'y' | 'z'`
+   * - `[['a' | 'b' | 'c', number], ...['x' | 'y' | 'z', number][]]` -> `'a' |
+   *   'b' | 'c' | 'x' | 'y' | 'z'`
+   *
+   * @note To handle the second example above, recursion needs to be performed on infinite-length Entries,
+   * but since the timing to stop cannot be determined, a recursion limit is set.
+   */
+  export type KeysOfEntries<
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+  > = KeysOfEntriesImpl<never, Entries, RecursionLimit>;
 
-    /** @internal */
-    type EntriesToObjectImpl<
-      R,
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-    > =
-      TypeEq<Entries['length'], 0> extends true
-        ? R
-        : EntriesToObjectImpl<
-            R & Readonly<Record<Entries[0][0], Entries[0][1]>>,
-            List.Tail<Entries>
+  type KeysOfEntriesImpl<
+    K,
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+    RemainingNumRecursions extends number,
+  > =
+    TypeEq<RemainingNumRecursions, 0> extends true
+      ? K
+      : TypeEq<Entries['length'], 0> extends true
+        ? K
+        : KeysOfEntriesImpl<
+            K | Entries[0][0],
+            List.Tail<Entries>,
+            Decrement<RemainingNumRecursions>
           >;
 
-    /**
-     * - `['x' | 'y' | 'z', number][]]` -> `'x' | 'y' | 'z'`
-     * - `[['a' | 'b' | 'c', number], ...['x' | 'y' | 'z', number][]]` -> `'a' |
-     *   'b' | 'c' | 'x' | 'y' | 'z'`
-     *
-     * @note To handle the second example above, recursion needs to be performed on infinite-length Entries,
-     * but since the timing to stop cannot be determined, a recursion limit is set.
-     */
-    export type KeysOfEntries<
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-    > = KeysOfEntriesImpl<never, Entries, RecursionLimit>;
+  export type ValuesOfEntries<
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+  > = ValuesOfEntriesImpl<never, Entries, RecursionLimit>;
 
-    type KeysOfEntriesImpl<
-      K,
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-      RemainingNumRecursions extends number,
-    > =
-      TypeEq<RemainingNumRecursions, 0> extends true
+  type ValuesOfEntriesImpl<
+    K,
+    Entries extends readonly (readonly [PropertyKey, unknown])[],
+    RemainingNumRecursions extends number,
+  > =
+    TypeEq<RemainingNumRecursions, 0> extends true
+      ? K
+      : TypeEq<Entries['length'], 0> extends true
         ? K
-        : TypeEq<Entries['length'], 0> extends true
-          ? K
-          : KeysOfEntriesImpl<
-              K | Entries[0][0],
-              List.Tail<Entries>,
-              Decrement<RemainingNumRecursions>
-            >;
+        : ValuesOfEntriesImpl<
+            K | Entries[0][1],
+            List.Tail<Entries>,
+            Decrement<RemainingNumRecursions>
+          >;
 
-    export type ValuesOfEntries<
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-    > = ValuesOfEntriesImpl<never, Entries, RecursionLimit>;
+  export type PartialIfKeyIsUnion<K, T> =
+    IsUnion<K> extends true ? Partial<T> : T;
 
-    type ValuesOfEntriesImpl<
-      K,
-      Entries extends readonly (readonly [PropertyKey, unknown])[],
-      RemainingNumRecursions extends number,
-    > =
-      TypeEq<RemainingNumRecursions, 0> extends true
+  /**
+   * Merges two object types where keys in B override keys in A, preserving optional modifiers.
+   *
+   * This implementation uses a sophisticated technique to preserve optional property modifiers (`?`)
+   * during the merge operation, which would otherwise be lost in a naive mapped type implementation.
+   *
+   * ## Core Technique: Optional Property Detection
+   *
+   * Uses `{} extends Pick<T, K>` to determine if a property is optional:
+   * - **Required property**: `Pick<T, 'x'>` = `{ x: number }` → `{}` does NOT extend it (false)
+   * - **Optional property**: `Pick<T, 'y'>` = `{ y?: string }` → `{}` DOES extend it (true)
+   *
+   * This works because `{}` (empty object) is assignable to objects with only optional properties
+   * but not to objects with required properties.
+   *
+   * ## Implementation Strategy
+   *
+   * The type is constructed as an intersection of five mapped types:
+   *
+   * 1. **Required properties from B** - Properties in B that are required (override A completely)
+   * 2. **Optional properties from B (not in A)** - New optional properties from B
+   * 3. **Optional properties from B (in A)** - Union of A[K] | B[K] to preserve both possibilities
+   * 4. **Required properties only in A** - Properties in A but not in B that are required
+   * 5. **Optional properties only in A** - Properties in A but not in B that are optional (with `?` modifier)
+   *
+   * Finally, the intersection is flattened using an optional-preserving identity mapping that
+   * re-applies the optional detection logic to maintain the `?` modifiers in the final type.
+   *
+   * @example
+   * ```ts
+   * type A = { x: number; y?: string };
+   * type B = { y?: number; z?: boolean };
+   * type Result = MergeTwo<A, B>;
+   * // Result: { x: number; y?: string | number; z?: boolean }
+   * ```
+   */
+  // transformer-ignore-next-line
+  type MergeTwo<A extends UnknownRecord, B extends UnknownRecord> = {
+    // 1. Required properties from B (override A completely)
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    readonly [K in keyof B as {} extends Pick<B, K> ? never : K]: B[K];
+  } & {
+    // 2. Optional properties from B that are NOT in A
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    readonly [K in keyof B as {} extends Pick<B, K>
+      ? K extends keyof A
+        ? never
+        : K
+      : never]?: B[K];
+  } & {
+    // 3. Optional properties from B that ARE in A (create union)
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    readonly [K in keyof B as {} extends Pick<B, K>
+      ? K extends keyof A
         ? K
-        : TypeEq<Entries['length'], 0> extends true
-          ? K
-          : ValuesOfEntriesImpl<
-              K | Entries[0][1],
-              List.Tail<Entries>,
-              Decrement<RemainingNumRecursions>
-            >;
+        : never
+      : never]?: K extends keyof A ? A[K] | B[K] : never;
+  } & {
+    // 4. Required properties only in A (not overridden by B)
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    readonly [K in Exclude<keyof A, keyof B> as {} extends Pick<A, K>
+      ? never
+      : K]: A[K];
+  } & {
+    // 5. Optional properties only in A (not overridden by B)
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    readonly [K in Exclude<keyof A, keyof B> as {} extends Pick<A, K>
+      ? K
+      : never]?: A[K];
+  } extends infer O
+    ? Readonly<
+        {
+          // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+          [K in keyof O as {} extends Pick<O, K> ? never : K]: O[K];
+        } & {
+          // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+          [K in keyof O as {} extends Pick<O, K> ? K : never]?: O[K];
+        }
+      >
+    : never;
 
-    export type PartialIfKeyIsUnion<K, T> =
-      IsUnion<K> extends true ? Partial<T> : T;
-  }
+  /** Sequentially merges a tuple of object types from left to right. */
+  export type MergeAll<
+    Records extends readonly UnknownRecord[],
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    Acc extends UnknownRecord = {},
+  > =
+    IsFixedLengthList<Records> extends false
+      ? ArrayElement<Records>
+      : Records extends readonly [
+            infer First extends UnknownRecord,
+            ...infer Rest extends readonly UnknownRecord[],
+          ]
+        ? MergeAll<Rest, MergeTwo<Acc, First>>
+        : Acc;
 }