ts-data-forge 7.1.0 → 8.0.0

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":"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"}
+{"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.0",
+  "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/array/impl/array-utils-creation.mts

@@ -85,7 +85,7 @@ export const seq = <N extends SizeType.ArgArr>(
  * assert.deepStrictEqual(emptyStrings, []);
  * ```
  */
-export const create = <const V, N extends SizeType.ArgArr>(
+export const create = <N extends SizeType.ArgArr, const V>(
   len: N,
   init: V,
 ): N extends SmallUint

package/src/array/impl/array-utils-transformation.mts

@@ -143,7 +143,7 @@ export function scan<E, S>(
       const [array, reducer, init] = args;
 
       const mut_result: MutableNonEmptyArray<S> = castMutable(
-        newArray<S, PositiveUint32>(asPositiveUint32(array.length + 1), init),
+        newArray<PositiveUint32, S>(asPositiveUint32(array.length + 1), init),
       );
 
       let mut_acc = init;

package/src/functional/optional/impl/optional-expect-to-be.mts

@@ -16,7 +16,7 @@ import { type Unwrap } from './types.mjs';
  *   Optional.expectToBe(optionalValue, 'value expected') === 'data',
  * );
  *
- * const expectValue = Optional.expectToBe<string>('missing optional');
+ * const expectValue = Optional.expectToBe('missing optional');
  *
  * const throwTest = (): void => {
  *   expectValue(Optional.none);
@@ -41,7 +41,7 @@ export function expectToBe<O extends UnknownOptional>(
 ): Unwrap<O>;
 
 // Curried version
-export function expectToBe<S>(message: string): (optional: Optional<S>) => S;
+export function expectToBe(message: string): <O>(optional: Optional<O>) => O;
 
 export function expectToBe<O extends UnknownOptional>(
   ...args: readonly [optional: O, message: string] | readonly [message: string]

package/src/functional/optional/impl/optional-or-else.mts

@@ -47,9 +47,9 @@ export function orElse<
 >(optional: O, alternative: O2): O | O2;
 
 // Curried version
-export function orElse<S, S2>(
-  alternative: Optional<S2>,
-): (optional: Optional<S>) => Optional<S> | Optional<S2>;
+export function orElse<O2>(
+  alternative: Optional<O2>,
+): <O>(optional: Optional<O>) => Optional<O> | Optional<O2>;
 
 export function orElse<
   O extends UnknownOptional,

package/src/functional/optional/impl/optional-unwrap-or.mts

@@ -40,9 +40,9 @@ export function unwrapOr<O extends UnknownOptional, D>(
 ): D | Unwrap<O>;
 
 // Curried version
-export function unwrapOr<S, D>(
+export function unwrapOr<D>(
   defaultValue: D,
-): (optional: Optional<S>) => D | S;
+): <O>(optional: Optional<O>) => D | O;
 
 export function unwrapOr<O extends UnknownOptional, D>(
   ...args: readonly [optional: O, defaultValue: D] | readonly [defaultValue: D]

package/src/functional/optional.test.mts

@@ -295,19 +295,19 @@ describe('Optional test', () => {
 
   describe('expectToBe', () => {
     test('should return the value for Some', () => {
-      const expectNumber = Optional.expectToBe<number>('Expected a number');
+      const expectNumber = Optional.expectToBe('Expected a number');
 
       expect(expectNumber(Optional.some(42))).toBe(42);
     });
 
     test('should throw with custom message for None', () => {
-      const expectNumber = Optional.expectToBe<number>('Expected a number');
+      const expectNumber = Optional.expectToBe('Expected a number');
 
       expect(() => expectNumber(Optional.none)).toThrow('Expected a number');
     });
 
     test('should be curried', () => {
-      const expectValidId = Optional.expectToBe<string>('ID is required');
+      const expectValidId = Optional.expectToBe('ID is required');
 
       const id1 = Optional.some('user-123');
 

package/src/functional/result/impl/result-expect-to-be.mts

@@ -1,4 +1,4 @@
-import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnknownResult } from '../result.mjs';
 import { isOk } from './result-is-ok.mjs';
 import { unwrapOk } from './result-unwrap-ok.mjs';
 import { type UnwrapOk } from './types.mjs';
@@ -14,7 +14,7 @@ import { type UnwrapOk } from './types.mjs';
  *
  * assert.isTrue(Result.expectToBe(okValue, 'should have value') === 'data');
  *
- * const expectResult = Result.expectToBe<string>('missing result');
+ * const expectResult = Result.expectToBe('missing result');
  *
  * const throwTest = (): void => {
  *   expectResult(Result.err('boom'));
@@ -37,7 +37,9 @@ export function expectToBe<R extends UnknownResult>(
 ): UnwrapOk<R>;
 
 // Curried version
-export function expectToBe<S>(message: string): <E>(result: Result<S, E>) => S;
+export function expectToBe(
+  message: string,
+): <R extends UnknownResult>(result: R) => UnwrapOk<R>;
 
 export function expectToBe<R extends UnknownResult>(
   ...args: readonly [result: R, message: string] | readonly [message: string]

package/src/functional/result/impl/result-or-else.mts

@@ -1,4 +1,4 @@
-import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnknownResult } from '../result.mjs';
 import { isOk } from './result-is-ok.mjs';
 import { type NarrowToOk } from './types.mjs';
 
@@ -43,9 +43,9 @@ export function orElse<R extends UnknownResult, R2 extends UnknownResult>(
 ): NarrowToOk<R> | R2;
 
 // Curried version
-export function orElse<S, E, S2, E2>(
-  alternative: Result<S2, E2>,
-): (result: Result<S, E>) => Result<S, E> | Result<S2, E2>;
+export function orElse<R2 extends UnknownResult>(
+  alternative: R2,
+): <R extends UnknownResult>(result: R) => NarrowToOk<R> | R2;
 
 export function orElse<R extends UnknownResult, R2 extends UnknownResult>(
   ...args: readonly [result: R, alternative: R2] | readonly [alternative: R2]

package/src/functional/result/impl/result-unwrap-err-or.mts

@@ -1,4 +1,4 @@
-import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnknownResult } from '../result.mjs';
 import { unwrapErr } from './result-unwrap-err.mjs';
 import { type UnwrapErr } from './types.mjs';
 
@@ -38,7 +38,7 @@ export function unwrapErrOr<R extends UnknownResult, D>(
 // Curried version
 export function unwrapErrOr<D>(
   defaultValue: D,
-): <S, E>(result: Result<S, E>) => D | E;
+): <R extends UnknownResult>(result: R) => D | UnwrapErr<R>;
 
 export function unwrapErrOr<R extends UnknownResult, D>(
   ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]

package/src/functional/result/impl/result-unwrap-ok-or.mts

@@ -1,4 +1,4 @@
-import { type Result, type UnknownResult } from '../result.mjs';
+import { type UnknownResult } from '../result.mjs';
 import { unwrapOk } from './result-unwrap-ok.mjs';
 import { type UnwrapOk } from './types.mjs';
 
@@ -36,9 +36,9 @@ export function unwrapOkOr<R extends UnknownResult, D>(
 ): D | UnwrapOk<R>;
 
 // Curried version
-export function unwrapOkOr<S, D>(
+export function unwrapOkOr<D>(
   defaultValue: D,
-): <E>(result: Result<S, E>) => D | S;
+): <R extends UnknownResult>(result: R) => D | UnwrapOk<R>;
 
 export function unwrapOkOr<R extends UnknownResult, D>(
   ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]

package/src/functional/ternary-result/impl/ternary-result-expect-to-be.mts

@@ -16,7 +16,7 @@ import { type UnwrapOk } from './types.mjs';
  *
  * assert.strictEqual(TernaryResult.expectToBe(okValue, 'missing'), 'ready');
  *
- * const expectResult = TernaryResult.expectToBe<string>('needs value');
+ * const expectResult = TernaryResult.expectToBe('needs value');
  *
  * const throwTest = (): void => {
  *   expectResult(TernaryResult.err('oops'));
@@ -31,9 +31,9 @@ export function expectToBe<R extends UnknownTernaryResult>(
 ): UnwrapOk<R>;
 
 // Curried version
-export function expectToBe<S>(
+export function expectToBe(
   message: string,
-): <W, E>(result: TernaryResult<S, E, W>) => S;
+): <S, W, E>(result: TernaryResult<S, E, W>) => S;
 
 export function expectToBe<R extends UnknownTernaryResult>(
   ...args: readonly [result: R, message: string] | readonly [message: string]

package/src/functional/ternary-result/impl/ternary-result-or-else.mts

@@ -1,7 +1,4 @@
-import {
-  type TernaryResult,
-  type UnknownTernaryResult,
-} from '../ternary-result.mjs';
+import { type UnknownTernaryResult } from '../ternary-result.mjs';
 import { isOk } from './ternary-result-is-ok.mjs';
 import { isWarn } from './ternary-result-is-warn.mjs';
 import { type NarrowToOk, type NarrowToWarn } from './types.mjs';
@@ -36,11 +33,11 @@ export function orElse<
 >(result: R, alternative: R2): NarrowToOk<R> | NarrowToWarn<R> | R2;
 
 // Curried version
-export function orElse<S, W, E, S2, W2, E2>(
-  alternative: TernaryResult<S2, E2, W2>,
-): (
-  result: TernaryResult<S, E, W>,
-) => TernaryResult<S, E, W> | TernaryResult<S2, E2, W2>;
+export function orElse<R2 extends UnknownTernaryResult>(
+  alternative: R2,
+): <R extends UnknownTernaryResult>(
+  result: R,
+) => NarrowToOk<R> | NarrowToWarn<R> | R2;
 
 export function orElse<
   R extends UnknownTernaryResult,

package/src/functional/ternary-result/impl/ternary-result-unwrap-err-or.mts

@@ -1,7 +1,4 @@
-import {
-  type TernaryResult,
-  type UnknownTernaryResult,
-} from '../ternary-result.mjs';
+import { type UnknownTernaryResult } from '../ternary-result.mjs';
 import { unwrapErr } from './ternary-result-unwrap-err.mjs';
 import { type UnwrapErr } from './types.mjs';
 
@@ -34,9 +31,9 @@ export function unwrapErrOr<R extends UnknownTernaryResult, D>(
 ): D | UnwrapErr<R>;
 
 // Curried version
-export function unwrapErrOr<E, D>(
+export function unwrapErrOr<D>(
   defaultValue: D,
-): <S, W>(result: TernaryResult<S, E, W>) => D | E;
+): <R extends UnknownTernaryResult>(result: R) => D | UnwrapErr<R>;
 
 export function unwrapErrOr<R extends UnknownTernaryResult, D>(
   ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]

package/src/functional/ternary-result/impl/ternary-result-unwrap-ok-or.mts

@@ -1,7 +1,4 @@
-import {
-  type TernaryResult,
-  type UnknownTernaryResult,
-} from '../ternary-result.mjs';
+import { type UnknownTernaryResult } from '../ternary-result.mjs';
 import { unwrapOk } from './ternary-result-unwrap-ok.mjs';
 import { type UnwrapOk } from './types.mjs';
 
@@ -31,9 +28,9 @@ export function unwrapOkOr<R extends UnknownTernaryResult, D>(
 ): D | UnwrapOk<R>;
 
 // Curried version
-export function unwrapOkOr<S, D>(
+export function unwrapOkOr<D>(
   defaultValue: D,
-): <W, E>(result: TernaryResult<S, E, W>) => D | S;
+): <R extends UnknownTernaryResult>(result: R) => D | UnwrapOk<R>;
 
 export function unwrapOkOr<R extends UnknownTernaryResult, D>(
   ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]

package/src/functional/ternary-result/impl/ternary-result-unwrap-warn-or.mts

@@ -1,7 +1,4 @@
-import {
-  type TernaryResult,
-  type UnknownTernaryResult,
-} from '../ternary-result.mjs';
+import { type UnknownTernaryResult } from '../ternary-result.mjs';
 import { unwrapWarn } from './ternary-result-unwrap-warn.mjs';
 import { type UnwrapWarn } from './types.mjs';
 
@@ -28,9 +25,9 @@ export function unwrapWarnOr<R extends UnknownTernaryResult, D>(
 ): D | UnwrapWarn<R>;
 
 // Curried version
-export function unwrapWarnOr<W, D>(
+export function unwrapWarnOr<D>(
   defaultValue: D,
-): <S, E>(result: TernaryResult<S, E, W>) => D | W;
+): <R extends UnknownTernaryResult>(result: R) => D | UnwrapWarn<R>;
 
 export function unwrapWarnOr<R extends UnknownTernaryResult, D>(
   ...args: readonly [result: R, defaultValue: D] | readonly [defaultValue: D]

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: (