ts-data-forge 7.1.1 → 8.0.0

package/dist/guard/is-non-null-object.d.mts

@@ -13,8 +13,8 @@
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for
- * plain objects specifically (excluding arrays), use `isRecord()` instead.
+ * **Note:** This function returns `true` for arrays. If you need
+ * record-oriented narrowing that excludes arrays, use `isRecord()` instead.
  *
  * @example
  *
@@ -29,7 +29,7 @@
  * @param u - The value to check
  * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
  *   `true`, TypeScript narrows the type to `object`.
- * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
+ * @see {@link isRecord} - For record-oriented type narrowing (excludes arrays)
  */
 export declare const isNonNullObject: (u: unknown) => u is object;
 //# sourceMappingURL=is-non-null-object.d.mts.map

package/dist/guard/is-non-null-object.mjs

@@ -13,8 +13,8 @@
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for
- * plain objects specifically (excluding arrays), use `isRecord()` instead.
+ * **Note:** This function returns `true` for arrays. If you need
+ * record-oriented narrowing that excludes arrays, use `isRecord()` instead.
  *
  * @example
  *
@@ -29,7 +29,7 @@
  * @param u - The value to check
  * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
  *   `true`, TypeScript narrows the type to `object`.
- * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
+ * @see {@link isRecord} - For record-oriented type narrowing (excludes arrays)
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types
 const isNonNullObject = (u) => typeof u === 'object' && u !== null;

package/dist/guard/is-record.d.mts

@@ -1,30 +1,45 @@
 import { type MutableRecord, type UnknownRecord } from 'ts-type-forge';
 /**
- * Type guard that checks if a value is a plain object (record) - a non-null
- * object that is not an array.
+ * Type guard that checks if a value is a record — a non-null, non-array
+ * object — and narrows it to `UnknownRecord` (= `ReadonlyRecord<string,
+ * unknown>`).
  *
- * This function is useful for identifying "plain" JavaScript objects (also
- * called records or dictionaries) - objects that are typically used as
- * key-value collections. It excludes arrays, functions, and special object
- * types like Date, RegExp, etc., focusing on objects that can be safely treated
- * as property collections.
+ * This function is designed to be combined with {@link hasKey} to probe
+ * values of type `unknown` (e.g. parsed JSON, caught errors, external data)
+ * in a type-safe way: `if (isRecord(u) && hasKey(u, 'some-key')) { ... }`.
  *
  * **Type Narrowing Behavior:**
  *
- * - Narrows `unknown` to `UnknownRecord` (equivalent to `Record<PropertyKey,
- *   unknown>`)
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects `{}`, object literals, and objects created
- *   with `Object.create()`
- * - Returns `false` for arrays, even though they are technically objects
- *
- * **Implementation:** Uses `isNonNullObject()` to check for objects, then
- * `Array.isArray()` to exclude arrays.
+ * - Narrows `unknown` to `UnknownRecord` (= `ReadonlyRecord<string, unknown>`)
+ * - Excludes `null`, `undefined`, primitives, and functions
+ * - Excludes arrays: arrays have no string index signature, so they are not
+ *   assignable to `UnknownRecord`; admitting them at runtime would be
+ *   inconsistent with the narrowed type
+ * - Returns `true` for every other non-null object, including dictionary
+ *   objects created with `Object.create(null)` and instances such as `Date`,
+ *   `RegExp`, `Map`, `Set`, `Error`, and user-defined classes
+ *
+ * **Why non-plain objects are included:** since every property of
+ * `UnknownRecord` is typed `unknown`, reading properties from any object
+ * through this narrowing is type-safe, and `hasKey` (backed by
+ * `Object.hasOwn`) answers own-property questions correctly on any object
+ * (e.g. `Map` entries are not own properties, so `hasKey` correctly returns
+ * `false` for them). Restricting the guard to plain objects would require
+ * prototype checks that misjudge cross-realm objects and would prevent
+ * probing useful instances such as `Error` subclasses.
+ *
+ * **Implementation:** `isNonNullObject(u) && !Array.isArray(u)`.
  *
  * @example
  *
  * ```ts
- * const entries: readonly unknown[] = [{ id: 1 }, 'str', 0, null] as const;
+ * const entries: readonly unknown[] = [
+ *   { id: 1 },
+ *   [1, 2],
+ *   'str',
+ *   0,
+ *   null,
+ * ] as const;
  *
  * const records = entries.filter(isRecord);
  *
@@ -32,29 +47,31 @@ import { type MutableRecord, type UnknownRecord } from 'ts-type-forge';
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a non-null object and not an array, `false`
- *   otherwise. When `true`, TypeScript narrows the type to `UnknownRecord`.
- * @see {@link isNonNullObject} - For checking any object type (includes arrays)
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `UnknownRecord`.
+ * @see {@link isNonNullObject} - For checking any non-null object (includes arrays)
  * @see {@link hasKey} - For checking if a record has specific keys
  */
 export declare const isRecord: (u: unknown) => u is UnknownRecord;
 /**
- * Type guard that checks if a value is a mutable record (an object with mutable string keys).
+ * Type guard that checks if a value is a mutable record.
  *
- * This function is an alias for {@link isRecord}, but narrows the type to
- * `MutableRecord<string, unknown>`, which is useful when you need to ensure
- * that the object can be safely mutated (i.e., its properties can be added or changed).
+ * This function has the same runtime behavior as {@link isRecord} (non-null,
+ * non-array object check), but narrows the type to `MutableRecord<string,
+ * unknown>`, which is useful when you need to add or overwrite properties on
+ * the narrowed object.
  *
  * **Type Narrowing Behavior:**
  *
  * - Narrows `unknown` to `MutableRecord<string, unknown>`
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects with mutable string keys
- * - Returns `false` for arrays and other non-record types
+ * - Excludes `null`, `undefined`, primitives, functions, and arrays
+ * - Returns `true` for every other non-null object (see {@link isRecord} for
+ *   details on non-plain objects such as `Date`, `Map`, and `Set`)
  *
  * **Implementation:** This is a type alias for {@link isRecord}.
  *
  * @example
+ *
  * ```ts
  * const obj: unknown = { foo: 1 } as const;
  *
@@ -64,8 +81,9 @@ export declare const isRecord: (u: unknown) => u is UnknownRecord;
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a mutable record (plain object with string keys), `false` otherwise.
- *   When `true`, TypeScript narrows the type to `MutableRecord<string, unknown>`.
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `MutableRecord<string,
+ *   unknown>`.
  * @see {@link isRecord} - For the underlying implementation and more details
  */
 export declare const isMutableRecord: (u: unknown) => u is MutableRecord<string, unknown>;

package/dist/guard/is-record.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"is-record.d.mts","sourceRoot":"","sources":["../../src/guard/is-record.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aAAmC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,EAAE,CAC5B,CAAC,EAAE,OAAO,KACP,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,OAAO,CAAY,CAAC"}
+{"version":3,"file":"is-record.d.mts","sourceRoot":"","sources":["../../src/guard/is-record.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aACF,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,CAC5B,CAAC,EAAE,OAAO,KACP,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,OAAO,CAAY,CAAC"}

package/dist/guard/is-record.mjs

@@ -1,31 +1,46 @@
 import { isNonNullObject } from './is-non-null-object.mjs';
 
 /**
- * Type guard that checks if a value is a plain object (record) - a non-null
- * object that is not an array.
+ * Type guard that checks if a value is a record — a non-null, non-array
+ * object — and narrows it to `UnknownRecord` (= `ReadonlyRecord<string,
+ * unknown>`).
  *
- * This function is useful for identifying "plain" JavaScript objects (also
- * called records or dictionaries) - objects that are typically used as
- * key-value collections. It excludes arrays, functions, and special object
- * types like Date, RegExp, etc., focusing on objects that can be safely treated
- * as property collections.
+ * This function is designed to be combined with {@link hasKey} to probe
+ * values of type `unknown` (e.g. parsed JSON, caught errors, external data)
+ * in a type-safe way: `if (isRecord(u) && hasKey(u, 'some-key')) { ... }`.
  *
  * **Type Narrowing Behavior:**
  *
- * - Narrows `unknown` to `UnknownRecord` (equivalent to `Record<PropertyKey,
- *   unknown>`)
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects `{}`, object literals, and objects created
- *   with `Object.create()`
- * - Returns `false` for arrays, even though they are technically objects
- *
- * **Implementation:** Uses `isNonNullObject()` to check for objects, then
- * `Array.isArray()` to exclude arrays.
+ * - Narrows `unknown` to `UnknownRecord` (= `ReadonlyRecord<string, unknown>`)
+ * - Excludes `null`, `undefined`, primitives, and functions
+ * - Excludes arrays: arrays have no string index signature, so they are not
+ *   assignable to `UnknownRecord`; admitting them at runtime would be
+ *   inconsistent with the narrowed type
+ * - Returns `true` for every other non-null object, including dictionary
+ *   objects created with `Object.create(null)` and instances such as `Date`,
+ *   `RegExp`, `Map`, `Set`, `Error`, and user-defined classes
+ *
+ * **Why non-plain objects are included:** since every property of
+ * `UnknownRecord` is typed `unknown`, reading properties from any object
+ * through this narrowing is type-safe, and `hasKey` (backed by
+ * `Object.hasOwn`) answers own-property questions correctly on any object
+ * (e.g. `Map` entries are not own properties, so `hasKey` correctly returns
+ * `false` for them). Restricting the guard to plain objects would require
+ * prototype checks that misjudge cross-realm objects and would prevent
+ * probing useful instances such as `Error` subclasses.
+ *
+ * **Implementation:** `isNonNullObject(u) && !Array.isArray(u)`.
  *
  * @example
  *
  * ```ts
- * const entries: readonly unknown[] = [{ id: 1 }, 'str', 0, null] as const;
+ * const entries: readonly unknown[] = [
+ *   { id: 1 },
+ *   [1, 2],
+ *   'str',
+ *   0,
+ *   null,
+ * ] as const;
  *
  * const records = entries.filter(isRecord);
  *
@@ -33,29 +48,31 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a non-null object and not an array, `false`
- *   otherwise. When `true`, TypeScript narrows the type to `UnknownRecord`.
- * @see {@link isNonNullObject} - For checking any object type (includes arrays)
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `UnknownRecord`.
+ * @see {@link isNonNullObject} - For checking any non-null object (includes arrays)
  * @see {@link hasKey} - For checking if a record has specific keys
  */
-const isRecord = (u) => isNonNullObject(u);
+const isRecord = (u) => isNonNullObject(u) && !Array.isArray(u);
 /**
- * Type guard that checks if a value is a mutable record (an object with mutable string keys).
+ * Type guard that checks if a value is a mutable record.
  *
- * This function is an alias for {@link isRecord}, but narrows the type to
- * `MutableRecord<string, unknown>`, which is useful when you need to ensure
- * that the object can be safely mutated (i.e., its properties can be added or changed).
+ * This function has the same runtime behavior as {@link isRecord} (non-null,
+ * non-array object check), but narrows the type to `MutableRecord<string,
+ * unknown>`, which is useful when you need to add or overwrite properties on
+ * the narrowed object.
  *
  * **Type Narrowing Behavior:**
  *
  * - Narrows `unknown` to `MutableRecord<string, unknown>`
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects with mutable string keys
- * - Returns `false` for arrays and other non-record types
+ * - Excludes `null`, `undefined`, primitives, functions, and arrays
+ * - Returns `true` for every other non-null object (see {@link isRecord} for
+ *   details on non-plain objects such as `Date`, `Map`, and `Set`)
  *
  * **Implementation:** This is a type alias for {@link isRecord}.
  *
  * @example
+ *
  * ```ts
  * const obj: unknown = { foo: 1 } as const;
  *
@@ -65,8 +82,9 @@ const isRecord = (u) => isNonNullObject(u);
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a mutable record (plain object with string keys), `false` otherwise.
- *   When `true`, TypeScript narrows the type to `MutableRecord<string, unknown>`.
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `MutableRecord<string,
+ *   unknown>`.
  * @see {@link isRecord} - For the underlying implementation and more details
  */
 const isMutableRecord = isRecord;

package/dist/guard/is-record.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"is-record.mjs","sources":["../../src/guard/is-record.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;AACI,MAAM,QAAQ,GAAG,CAAC,CAAU,KAAyB,eAAe,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACI,MAAM,eAAe,GAEe;;;;"}
+{"version":3,"file":"is-record.mjs","sources":["../../src/guard/is-record.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDG;MACU,QAAQ,GAAG,CAAC,CAAU,KACjC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACI,MAAM,eAAe,GAEe;;;;"}

package/dist/others/fast-deep-equal.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fast-deep-equal.d.mts","sourceRoot":"","sources":["../../src/others/fast-deep-equal.mts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,GAAG,CAAC,EAAE,GAAG,CAAC,KAAG,OAqF9C,CAAC"}
+{"version":3,"file":"fast-deep-equal.d.mts","sourceRoot":"","sources":["../../src/others/fast-deep-equal.mts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,GAAG,CAAC,EAAE,GAAG,CAAC,KAAG,OAuF9C,CAAC"}

package/dist/others/fast-deep-equal.mjs

@@ -15,6 +15,13 @@ const fastDeepEqual = (a, b) => {
     if (typeof a !== typeof b) {
         return false;
     }
+    // Arrays are handled before `isRecord`, which excludes them.
+    if (Array.isArray(a)) {
+        return (Array.isArray(b) &&
+            a.constructor === b.constructor &&
+            a.length === b.length &&
+            a.every((ai, index) => fastDeepEqual(ai, b[index])));
+    }
     if (isRecord(a)) {
         if (!isRecord(b)) {
             return false;
@@ -22,11 +29,6 @@ const fastDeepEqual = (a, b) => {
         if (a.constructor !== b.constructor) {
             return false;
         }
-        if (Array.isArray(a)) {
-            return (Array.isArray(b) &&
-                a.length === b.length &&
-                a.every((ai, index) => fastDeepEqual(ai, b[index])));
-        }
         if (isMap(a)) {
             return (isMap(b) &&
                 a.size === b.size &&

package/dist/others/fast-deep-equal.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fast-deep-equal.mjs","sources":["../../src/others/fast-deep-equal.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAGA;;;;;AAKG;MACU,aAAa,GAAG,CAAK,CAAI,EAAE,CAAI,KAAa;AACvD,IAAA,IAAI,CAAC,KAAK,CAAC,EAAE;AACX,QAAA,OAAO,IAAI;IACb;AAEA,IAAA,IAAI,OAAO,CAAC,KAAK,OAAO,CAAC,EAAE;AACzB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE;AACf,QAAA,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;AAChB,YAAA,OAAO,KAAK;QACd;QAEA,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE;AACnC,YAAA,OAAO,KAAK;QACd;AAEA,QAAA,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;AACpB,YAAA,QACE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAChB,gBAAA,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;gBACrB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,KAAK,KAAK,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAEvD;AAEA,QAAA,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE;AACZ,YAAA,QACE,KAAK,CAAC,CAAC,CAAC;AACR,gBAAA,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;AACjB,gBAAA,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAC3B,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CACjE;QAEL;AAEA,QAAA,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE;AACZ,YAAA,QACE,KAAK,CAAC,CAAC,CAAC;AACR,gBAAA,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;gBACjB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAE5D;AAEA,QAAA,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE;AACnB,YAAA,QACE,YAAY,CAAC,CAAC,CAAC;AACf,gBAAA,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;AACrB,gBAAA,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;QAEjD;AAEA,QAAA,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE;YACf,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QACpE;QAEA,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE;YAC1C,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE;QACpC;QAEA,IAAI,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE;YAC5C,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE;QACtC;QAEA,MAAM,KAAK,GAAsB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAE/C,MAAM,KAAK,GAAsB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAE/C,QAAA,QACE,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;AAC7B,YAAA,KAAK,CAAC,KAAK,CACT,CAAC,GAAG,KACF,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC;;;;;gBAKd,EAAE,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC;AACpC,gBAAA,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAChC;IAEL;;AAGA,IAAA,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3C;;;;"}
+{"version":3,"file":"fast-deep-equal.mjs","sources":["../../src/others/fast-deep-equal.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "7.1.1",
+  "version": "8.0.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -91,7 +91,7 @@
   "devDependencies": {
     "@emotion/react": "11.14.0",
     "@emotion/styled": "11.14.1",
-    "@mui/material": "9.1.1",
+    "@mui/material": "9.1.2",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-strip": "3.0.4",
     "@rollup/plugin-typescript": "12.3.0",
@@ -107,7 +107,7 @@
     "@vitest/browser-playwright": "4.1.9",
     "@vitest/coverage-v8": "4.1.9",
     "@vitest/ui": "4.1.9",
-    "conventional-changelog-conventionalcommits": "9.3.1",
+    "conventional-changelog-conventionalcommits": "10.2.0",
     "cspell": "10.0.1",
     "dedent": "1.7.2",
     "eslint": "9.39.4",
@@ -132,7 +132,7 @@
     "typedoc": "0.28.19",
     "typedoc-github-theme": "0.4.0",
     "typescript": "5.9.3",
-    "vite": "8.0.16",
+    "vite": "8.1.0",
     "vitest": "4.1.9"
   },
   "peerDependencies": {

package/src/guard/is-non-null-object.mts

@@ -13,8 +13,8 @@
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for
- * plain objects specifically (excluding arrays), use `isRecord()` instead.
+ * **Note:** This function returns `true` for arrays. If you need
+ * record-oriented narrowing that excludes arrays, use `isRecord()` instead.
  *
  * @example
  *
@@ -29,7 +29,7 @@
  * @param u - The value to check
  * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
  *   `true`, TypeScript narrows the type to `object`.
- * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
+ * @see {@link isRecord} - For record-oriented type narrowing (excludes arrays)
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types
 export const isNonNullObject = (u: unknown): u is object =>

package/src/guard/is-record.mts

@@ -2,31 +2,46 @@ import { type MutableRecord, type UnknownRecord } from 'ts-type-forge';
 import { isNonNullObject } from './is-non-null-object.mjs';
 
 /**
- * Type guard that checks if a value is a plain object (record) - a non-null
- * object that is not an array.
+ * Type guard that checks if a value is a record — a non-null, non-array
+ * object — and narrows it to `UnknownRecord` (= `ReadonlyRecord<string,
+ * unknown>`).
  *
- * This function is useful for identifying "plain" JavaScript objects (also
- * called records or dictionaries) - objects that are typically used as
- * key-value collections. It excludes arrays, functions, and special object
- * types like Date, RegExp, etc., focusing on objects that can be safely treated
- * as property collections.
+ * This function is designed to be combined with {@link hasKey} to probe
+ * values of type `unknown` (e.g. parsed JSON, caught errors, external data)
+ * in a type-safe way: `if (isRecord(u) && hasKey(u, 'some-key')) { ... }`.
  *
  * **Type Narrowing Behavior:**
  *
- * - Narrows `unknown` to `UnknownRecord` (equivalent to `Record<PropertyKey,
- *   unknown>`)
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects `{}`, object literals, and objects created
- *   with `Object.create()`
- * - Returns `false` for arrays, even though they are technically objects
- *
- * **Implementation:** Uses `isNonNullObject()` to check for objects, then
- * `Array.isArray()` to exclude arrays.
+ * - Narrows `unknown` to `UnknownRecord` (= `ReadonlyRecord<string, unknown>`)
+ * - Excludes `null`, `undefined`, primitives, and functions
+ * - Excludes arrays: arrays have no string index signature, so they are not
+ *   assignable to `UnknownRecord`; admitting them at runtime would be
+ *   inconsistent with the narrowed type
+ * - Returns `true` for every other non-null object, including dictionary
+ *   objects created with `Object.create(null)` and instances such as `Date`,
+ *   `RegExp`, `Map`, `Set`, `Error`, and user-defined classes
+ *
+ * **Why non-plain objects are included:** since every property of
+ * `UnknownRecord` is typed `unknown`, reading properties from any object
+ * through this narrowing is type-safe, and `hasKey` (backed by
+ * `Object.hasOwn`) answers own-property questions correctly on any object
+ * (e.g. `Map` entries are not own properties, so `hasKey` correctly returns
+ * `false` for them). Restricting the guard to plain objects would require
+ * prototype checks that misjudge cross-realm objects and would prevent
+ * probing useful instances such as `Error` subclasses.
+ *
+ * **Implementation:** `isNonNullObject(u) && !Array.isArray(u)`.
  *
  * @example
  *
  * ```ts
- * const entries: readonly unknown[] = [{ id: 1 }, 'str', 0, null] as const;
+ * const entries: readonly unknown[] = [
+ *   { id: 1 },
+ *   [1, 2],
+ *   'str',
+ *   0,
+ *   null,
+ * ] as const;
  *
  * const records = entries.filter(isRecord);
  *
@@ -34,30 +49,33 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a non-null object and not an array, `false`
- *   otherwise. When `true`, TypeScript narrows the type to `UnknownRecord`.
- * @see {@link isNonNullObject} - For checking any object type (includes arrays)
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `UnknownRecord`.
+ * @see {@link isNonNullObject} - For checking any non-null object (includes arrays)
  * @see {@link hasKey} - For checking if a record has specific keys
  */
-export const isRecord = (u: unknown): u is UnknownRecord => isNonNullObject(u);
+export const isRecord = (u: unknown): u is UnknownRecord =>
+  isNonNullObject(u) && !Array.isArray(u);
 
 /**
- * Type guard that checks if a value is a mutable record (an object with mutable string keys).
+ * Type guard that checks if a value is a mutable record.
  *
- * This function is an alias for {@link isRecord}, but narrows the type to
- * `MutableRecord<string, unknown>`, which is useful when you need to ensure
- * that the object can be safely mutated (i.e., its properties can be added or changed).
+ * This function has the same runtime behavior as {@link isRecord} (non-null,
+ * non-array object check), but narrows the type to `MutableRecord<string,
+ * unknown>`, which is useful when you need to add or overwrite properties on
+ * the narrowed object.
  *
  * **Type Narrowing Behavior:**
  *
  * - Narrows `unknown` to `MutableRecord<string, unknown>`
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects with mutable string keys
- * - Returns `false` for arrays and other non-record types
+ * - Excludes `null`, `undefined`, primitives, functions, and arrays
+ * - Returns `true` for every other non-null object (see {@link isRecord} for
+ *   details on non-plain objects such as `Date`, `Map`, and `Set`)
  *
  * **Implementation:** This is a type alias for {@link isRecord}.
  *
  * @example
+ *
  * ```ts
  * const obj: unknown = { foo: 1 } as const;
  *
@@ -67,8 +85,9 @@ export const isRecord = (u: unknown): u is UnknownRecord => isNonNullObject(u);
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a mutable record (plain object with string keys), `false` otherwise.
- *   When `true`, TypeScript narrows the type to `MutableRecord<string, unknown>`.
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `MutableRecord<string,
+ *   unknown>`.
  * @see {@link isRecord} - For the underlying implementation and more details
  */
 export const isMutableRecord: (

package/src/guard/is-record.test.mts

@@ -1,123 +1,195 @@
 import { type UnknownRecord } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
+import { hasKey } from './has-key.mjs';
 import { isRecord } from './is-record.mjs';
 
 describe(isRecord, () => {
-  describe('arrays are Records', () => {
-    test('number[] is assignable to Record<number, unknown>', () => {
-      const arr: Record<number, unknown> = [1, 2, 3] as const;
+  describe('plain objects are records', () => {
+    test('{ x: 1 } is a record', () => {
+      const unk: unknown = { x: 1 } as const;
+
+      if (isRecord(unk)) {
+        expectType<typeof unk, UnknownRecord>('=');
+      } else {
+        assert.fail();
+      }
+    });
 
-      const unk: unknown = arr;
+    test('{} is a record', () => {
+      const unk: unknown = {} as const;
 
       assert.isTrue(isRecord(unk));
+    });
+
+    test('Object.create(null) is a record', () => {
+      const unk: unknown = Object.create(null);
 
-      expectType<typeof unk, UnknownRecord>('<=');
+      assert.isTrue(isRecord(unk));
     });
+  });
 
-    test('string[] is assignable to Record<number, unknown>', () => {
-      const arr: Record<number, unknown> = ['1', '2', '3'] as const;
+  describe('arrays are not records', () => {
+    test('type-level: arrays are not assignable to UnknownRecord', () => {
+      // Arrays have a number index signature but no string index signature,
+      // so they are assignable to `Record<number, unknown>` but not to
+      // `UnknownRecord` (= `ReadonlyRecord<string, unknown>`).
+      expectType<readonly number[], Record<number, unknown>>('<=');
 
-      const unk: unknown = arr;
+      expectType<readonly number[], UnknownRecord>('!<=');
 
-      assert.isTrue(isRecord(unk));
+      expectType<readonly string[], Record<number, unknown>>('<=');
+
+      expectType<readonly string[], UnknownRecord>('!<=');
 
-      expectType<typeof unk, UnknownRecord>('<=');
+      expectType<readonly [], UnknownRecord>('!<=');
     });
 
-    test('[] is a record', () => {
-      const arr: unknown = [] as const;
+    test('[1, 2, 3] is not a record', () => {
+      const unk: unknown = [1, 2, 3] as const;
 
-      const unk: unknown = arr;
+      assert.isFalse(isRecord(unk));
+    });
 
-      assert.isTrue(isRecord(unk));
+    test('["1", "2", "3"] is not a record', () => {
+      const unk: unknown = ['1', '2', '3'] as const;
 
-      expectType<typeof unk, UnknownRecord>('<=');
+      assert.isFalse(isRecord(unk));
+    });
+
+    test('[] is not a record', () => {
+      const unk: unknown = [] as const;
+
+      assert.isFalse(isRecord(unk));
     });
   });
 
-  describe('non-null objects are Records', () => {
-    test('{ x: 1 } is a record', () => {
-      const obj = { x: 1 } as const;
+  describe('other non-null objects are records', () => {
+    // These are not statically assignable to `UnknownRecord` either, but the
+    // guard intentionally admits them: every property read through
+    // `UnknownRecord` is typed `unknown`, so the narrowing is type-safe, and
+    // it keeps `isRecord(u) && hasKey(u, k)` usable for probing instances
+    // such as caught `Error` objects.
+    test('Date is a record', () => {
+      expectType<Date, UnknownRecord>('!<=');
+
+      const unk: unknown = new Date('2020-01-01');
+
+      assert.isTrue(isRecord(unk));
+    });
 
-      const unk: unknown = obj;
+    test('RegExp is a record', () => {
+      const unk: unknown = /test/u;
 
       assert.isTrue(isRecord(unk));
+    });
+
+    test('Map is a record (but its entries are not own properties)', () => {
+      expectType<ReadonlyMap<string, number>, UnknownRecord>('!<=');
+
+      const unk: unknown = new Map([['a', 1]]);
 
-      expectType<typeof unk, UnknownRecord>('<=');
+      if (isRecord(unk)) {
+        // Map entries are not own properties, so hasKey correctly rejects them.
+        assert.isFalse(hasKey(unk, 'a'));
+      } else {
+        assert.fail();
+      }
     });
 
-    test('{} is a record', () => {
-      const obj = {} as const;
+    test('Set is a record', () => {
+      expectType<ReadonlySet<number>, UnknownRecord>('!<=');
+
+      const unk: unknown = new Set([1, 2, 3]);
+
+      assert.isTrue(isRecord(unk));
+    });
+
+    test('Error is a record and its own properties can be probed', () => {
+      const unk: unknown = Object.assign(new Error('failure'), {
+        code: 'ENOENT',
+      });
+
+      if (isRecord(unk) && hasKey(unk, 'code')) {
+        expectType<(typeof unk)['code'], unknown>('=');
 
-      const unk: unknown = obj;
+        assert.strictEqual(unk.code, 'ENOENT');
+      } else {
+        assert.fail();
+      }
+    });
+
+    test('class instance is a record', () => {
+      class Foo {
+        readonly x = 1;
+      }
+
+      const unk: unknown = new Foo();
 
       assert.isTrue(isRecord(unk));
+    });
+  });
+
+  describe('functions are not records', () => {
+    test('arrow function is not a record', () => {
+      const unk: unknown = () => 0;
 
-      expectType<typeof unk, UnknownRecord>('<=');
+      assert.isFalse(isRecord(unk));
     });
   });
 
-  describe('primitives are not Records', () => {
+  describe('primitives are not records', () => {
     test('null is not a record', () => {
-      const obj = null;
-
-      const unk: unknown = obj;
+      const unk: unknown = null;
 
       assert.isFalse(isRecord(unk));
-
-      expectType<typeof unk, UnknownRecord>('!<=');
     });
 
     test('undefined is not a record', () => {
-      const prm = undefined;
-
-      const unk: unknown = prm;
+      const unk: unknown = undefined;
 
       assert.isFalse(isRecord(unk));
-
-      expectType<typeof unk, UnknownRecord>('!<=');
     });
 
     test('3 is not a record', () => {
-      const prm = 3;
-
-      const unk: unknown = prm;
+      const unk: unknown = 3;
 
       assert.isFalse(isRecord(unk));
-
-      expectType<typeof unk, UnknownRecord>('!<=');
     });
 
     test('"str" is not a record', () => {
-      const prm = 'str';
-
-      const unk: unknown = prm;
+      const unk: unknown = 'str';
 
       assert.isFalse(isRecord(unk));
+    });
 
-      expectType<typeof unk, UnknownRecord>('!<=');
+    test('true is not a record', () => {
+      const unk: unknown = true;
+
+      assert.isFalse(isRecord(unk));
     });
-  });
 
-  // test('Map is not a record', () => {
-  //   const obj = new MutableMap();
-  //   const unk: unknown = obj;
-  //   const res = isRecord(unk);
+    test('symbol is not a record', () => {
+      const unk: unknown = Symbol('sym');
 
-  //   assertNotType<typeof obj, UnknownRecord>("<=");
-  //   expectType<typeof res, boolean>("=");
+      assert.isFalse(isRecord(unk));
+    });
 
-  //   expect(res).toBe(false);
-  // });
+    test('bigint is not a record', () => {
+      const unk: unknown = 1n;
 
-  // test('Set is not a record', () => {
-  //   const obj = new MutableSet();
-  //   const unk: unknown = obj;
-  //   const res = isRecord(unk);
+      assert.isFalse(isRecord(unk));
+    });
+  });
+
+  test('combined with hasKey', () => {
+    const unk: unknown = { 'some-key': 42 } as const;
 
-  //   assertNotType<typeof obj, UnknownRecord>("<=");
-  //   expectType<typeof res, boolean>("=");
+    if (isRecord(unk) && hasKey(unk, 'some-key')) {
+      expectType<(typeof unk)['some-key'], unknown>('=');
 
-  //   expect(res).toBe(false);
-  // });
+      assert.strictEqual(unk['some-key'], 42);
+    } else {
+      assert.fail();
+    }
+  });
 });

package/src/others/fast-deep-equal.mts

@@ -16,6 +16,16 @@ export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
     return false;
   }
 
+  // Arrays are handled before `isRecord`, which excludes them.
+  if (Array.isArray(a)) {
+    return (
+      Array.isArray(b) &&
+      a.constructor === b.constructor &&
+      a.length === b.length &&
+      a.every((ai, index) => fastDeepEqual(ai, b[index]))
+    );
+  }
+
   if (isRecord(a)) {
     if (!isRecord(b)) {
       return false;
@@ -25,14 +35,6 @@ export const fastDeepEqual = <T,>(a: T, b: T): boolean => {
       return false;
     }
 
-    if (Array.isArray(a)) {
-      return (
-        Array.isArray(b) &&
-        a.length === b.length &&
-        a.every((ai, index) => fastDeepEqual(ai, b[index]))
-      );
-    }
-
     if (isMap(a)) {
       return (
         isMap(b) &&