ts-data-forge 5.0.1 → 5.1.1

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

@@ -3,54 +3,73 @@ import { isNonNullObject } from './is-non-null-object.mjs';
 
 describe(isNonNullObject, () => {
   test('should return true for plain objects', () => {
-    expect(isNonNullObject({})).toBe(true);
-    expect(isNonNullObject({ a: 1, b: 'test' })).toBe(true);
-    expect(isNonNullObject({ nested: { value: true } })).toBe(true);
+    assert.isTrue(isNonNullObject({}));
+
+    assert.isTrue(isNonNullObject({ a: 1, b: 'test' }));
+
+    assert.isTrue(isNonNullObject({ nested: { value: true } }));
   });
 
   test('should return true for arrays', () => {
-    expect(isNonNullObject([])).toBe(true);
-    expect(isNonNullObject([1, 2, 3])).toBe(true);
-    expect(isNonNullObject(['a', 'b', 'c'])).toBe(true);
+    assert.isTrue(isNonNullObject([]));
+
+    assert.isTrue(isNonNullObject([1, 2, 3]));
+
+    assert.isTrue(isNonNullObject(['a', 'b', 'c']));
   });
 
   test('should return true for functions', () => {
-    expect(isNonNullObject(() => {})).toBe(false);
-    expect(isNonNullObject(async () => {})).toBe(false);
+    assert.isFalse(isNonNullObject(() => {}));
+
+    assert.isFalse(isNonNullObject(async () => {}));
+
     // eslint-disable-next-line @typescript-eslint/no-extraneous-class
-    expect(isNonNullObject(class MyClass {})).toBe(false);
+    assert.isFalse(isNonNullObject(class MyClass {}));
   });
 
   test('should return true for built-in objects', () => {
-    expect(isNonNullObject(new Date())).toBe(true);
-    expect(isNonNullObject(/test/u)).toBe(true);
-    expect(isNonNullObject(/regex/u)).toBe(true);
-    expect(isNonNullObject(new Map())).toBe(true);
-    expect(isNonNullObject(new Set())).toBe(true);
-    expect(isNonNullObject(new Error('test'))).toBe(true);
+    assert.isTrue(isNonNullObject(new Date()));
+
+    assert.isTrue(isNonNullObject(/test/u));
+
+    assert.isTrue(isNonNullObject(/regex/u));
+
+    assert.isTrue(isNonNullObject(new Map()));
+
+    assert.isTrue(isNonNullObject(new Set()));
+
+    assert.isTrue(isNonNullObject(new Error('test')));
   });
 
   test('should return true for boxed primitives', () => {
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isNonNullObject(new String('hello'))).toBe(true);
+    assert.isTrue(isNonNullObject(new String('hello')));
+
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isNonNullObject(new Number(42))).toBe(true);
+    assert.isTrue(isNonNullObject(new Number(42)));
+
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isNonNullObject(new Boolean(true))).toBe(true);
+    assert.isTrue(isNonNullObject(new Boolean(true)));
   });
 
   test('should return false for null', () => {
-    expect(isNonNullObject(null)).toBe(false);
+    assert.isFalse(isNonNullObject(null));
   });
 
   test('should return false for primitive values', () => {
-    expect(isNonNullObject(undefined)).toBe(false);
-    expect(isNonNullObject('string')).toBe(false);
-    expect(isNonNullObject(42)).toBe(false);
-    expect(isNonNullObject(true)).toBe(false);
-    expect(isNonNullObject(false)).toBe(false);
-    expect(isNonNullObject(Symbol('test'))).toBe(false);
-    expect(isNonNullObject(123n)).toBe(false);
+    assert.isFalse(isNonNullObject(undefined));
+
+    assert.isFalse(isNonNullObject('string'));
+
+    assert.isFalse(isNonNullObject(42));
+
+    assert.isFalse(isNonNullObject(true));
+
+    assert.isFalse(isNonNullObject(false));
+
+    assert.isFalse(isNonNullObject(Symbol('test')));
+
+    assert.isFalse(isNonNullObject(123n));
   });
 
   test('should act as a type guard', () => {

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

@@ -4,10 +4,12 @@ import { isSymbol } from './is-type.mjs';
 
 describe(isPrimitive, () => {
   test('should return true for string primitives', () => {
-    expect(isPrimitive('hello')).toBe(true);
-    expect(isPrimitive('')).toBe(true);
+    assert.isTrue(isPrimitive('hello'));
+
+    assert.isTrue(isPrimitive(''));
 
     const value: unknown = 'test';
+
     if (isPrimitive(value)) {
       expectType<
         typeof value,
@@ -17,62 +19,77 @@ describe(isPrimitive, () => {
   });
 
   test('should return true for number primitives', () => {
-    expect(isPrimitive(42)).toBe(true);
-    expect(isPrimitive(0)).toBe(true);
-    expect(isPrimitive(-3.14)).toBe(true);
-    expect(isPrimitive(Number.NaN)).toBe(true);
-    expect(isPrimitive(Number.POSITIVE_INFINITY)).toBe(true);
+    assert.isTrue(isPrimitive(42));
+
+    assert.isTrue(isPrimitive(0));
+
+    assert.isTrue(isPrimitive(-3.14));
+
+    assert.isTrue(isPrimitive(Number.NaN));
+
+    assert.isTrue(isPrimitive(Number.POSITIVE_INFINITY));
   });
 
   test('should return true for boolean primitives', () => {
-    expect(isPrimitive(true)).toBe(true);
-    expect(isPrimitive(false)).toBe(true);
+    assert.isTrue(isPrimitive(true));
+
+    assert.isTrue(isPrimitive(false));
   });
 
   test('should return true for symbol primitives', () => {
-    expect(isPrimitive(Symbol('test'))).toBe(true);
-    expect(isPrimitive(Symbol.iterator)).toBe(true);
+    assert.isTrue(isPrimitive(Symbol('test')));
+
+    assert.isTrue(isPrimitive(Symbol.iterator));
   });
 
   test('should return true for bigint primitives', () => {
-    expect(isPrimitive(123n)).toBe(true);
-    expect(isPrimitive(0n)).toBe(true);
-    expect(isPrimitive(-123n)).toBe(true);
+    assert.isTrue(isPrimitive(123n));
+
+    assert.isTrue(isPrimitive(0n));
+
+    assert.isTrue(isPrimitive(-123n));
   });
 
   test('should return true for null', () => {
     // Note: null is considered an object by typeof, so isPrimitive returns false
-    expect(isPrimitive(null)).toBe(true);
+    assert.isTrue(isPrimitive(null));
   });
 
   test('should return true for undefined', () => {
-    expect(isPrimitive(undefined)).toBe(true);
+    assert.isTrue(isPrimitive(undefined));
   });
 
   test('should return false for objects', () => {
-    expect(isPrimitive({})).toBe(false);
-    expect(isPrimitive({ a: 1 })).toBe(false);
-    expect(isPrimitive(new Date())).toBe(false);
+    assert.isFalse(isPrimitive({}));
+
+    assert.isFalse(isPrimitive({ a: 1 }));
+
+    assert.isFalse(isPrimitive(new Date()));
   });
 
   test('should return false for arrays', () => {
-    expect(isPrimitive([])).toBe(false);
-    expect(isPrimitive([1, 2, 3])).toBe(false);
+    assert.isFalse(isPrimitive([]));
+
+    assert.isFalse(isPrimitive([1, 2, 3]));
   });
 
   test('should return false for functions', () => {
-    expect(isPrimitive(() => {})).toBe(false);
-    expect(isPrimitive(() => {})).toBe(false);
-    expect(isPrimitive(async () => {})).toBe(false);
+    assert.isFalse(isPrimitive(() => {}));
+
+    assert.isFalse(isPrimitive(() => {}));
+
+    assert.isFalse(isPrimitive(async () => {}));
   });
 
   test('should return false for boxed primitives', () => {
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isPrimitive(new String('hello'))).toBe(false);
+    assert.isFalse(isPrimitive(new String('hello')));
+
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isPrimitive(new Number(42))).toBe(false);
+    assert.isFalse(isPrimitive(new Number(42)));
+
     // eslint-disable-next-line unicorn/new-for-builtins
-    expect(isPrimitive(new Boolean(true))).toBe(false);
+    assert.isFalse(isPrimitive(new Boolean(true)));
   });
 
   test('should narrow types correctly in conditional', () => {
@@ -88,16 +105,22 @@ describe(isPrimitive, () => {
     ];
 
     const primitives = values.filter(isPrimitive);
+
     const nonPrimitives = values.filter((v) => !isPrimitive(v));
 
     expect(primitives).toHaveLength(6); // string, 42, true, null, undefined, symbol
+
     expect(primitives[0]).toBe('string');
+
     expect(primitives[1]).toBe(42);
+
     expect(primitives[2]).toBe(true);
+
     expect(primitives[3]).toBeNull();
+
     expect(primitives[4]).toBeUndefined();
 
-    expect(isSymbol(primitives[5])).toBe(true);
+    assert.isTrue(isSymbol(primitives[5]));
 
     assert.deepStrictEqual(nonPrimitives, [{}, []]);
   });

package/src/guard/is-record.mts

@@ -40,3 +40,37 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  */
 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).
+ *
+ * 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).
+ *
+ * **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
+ *
+ * **Implementation:** This is a type alias for {@link isRecord}.
+ *
+ * @example
+ * ```ts
+ * const obj: unknown = { foo: 1 };
+ *
+ * if (isMutableRecord(obj)) {
+ *   obj['bar'] = 2; // Safe: obj is now known to be a mutable record
+ * }
+ * ```
+ *
+ * @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>`.
+ * @see {@link isRecord} - For the underlying implementation and more details
+ */
+export const isMutableRecord: (
+  u: unknown,
+) => u is MutableRecord<string, unknown> = isRecord;

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

@@ -4,87 +4,108 @@ import { isRecord } from './is-record.mjs';
 describe(isRecord, () => {
   test('{ x: 1 } is a record', () => {
     const obj = { x: 1 } as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, UnknownRecord>('<=');
+
     expectType<typeof res, boolean>('=');
 
     if (res) {
       expectType<typeof unk, UnknownRecord>('=');
     }
 
-    expect(res).toBe(true);
+    assert.isTrue(res);
   });
 
   test('{} is a record', () => {
     const obj = {} as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, {}>('=');
+
     expectType<typeof res, boolean>('=');
 
     if (res) {
       expectType<typeof unk, UnknownRecord>('=');
     }
 
-    expect(res).toBe(true);
+    assert.isTrue(res);
   });
 
   test('[] is not a record', () => {
     const obj: DeepReadonly<never[]> = [] as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, readonly never[]>('=');
+
     expectType<typeof res, boolean>('=');
 
-    expect(res).toBe(false);
+    assert.isFalse(res);
   });
 
   test('null is not a record', () => {
     const obj = null;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, null>('=');
+
     expectType<typeof res, boolean>('=');
 
-    expect(res).toBe(false);
+    assert.isFalse(res);
   });
 
   test('undefined is not a record', () => {
     const obj = undefined;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, undefined>('=');
+
     expectType<typeof res, boolean>('=');
 
-    expect(res).toBe(false);
+    assert.isFalse(res);
   });
 
   test('3 is not a record', () => {
     const obj = 3;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, 3>('=');
+
     expectType<typeof res, boolean>('=');
 
-    expect(res).toBe(false);
+    assert.isFalse(res);
   });
 
   test('"str" is not a record', () => {
     const obj = 'str';
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, 'str'>('=');
+
     expectType<typeof res, boolean>('=');
 
-    expect(res).toBe(false);
+    assert.isFalse(res);
   });
 
   // test('Map is not a record', () => {

package/src/guard/is-type.mts

@@ -263,7 +263,9 @@ export const isNotString = <T,>(u: T): u is RelaxedExclude<T, string> =>
  *
  * ```ts
  * const id = Symbol('id');
+ *
  * const shared = Symbol.for('shared');
+ *
  * const tokens: unknown[] = [id, 'shared', shared];
  *
  * const symbols = tokens.filter(isSymbol);
@@ -289,6 +291,7 @@ export const isSymbol = (u: unknown): u is symbol => typeof u === 'symbol';
  *
  * ```ts
  * const id = Symbol('id');
+ *
  * const tokens: unknown[] = [id, 'shared'];
  *
  * const nonSymbols = tokens.filter(isNotSymbol);