ts-data-forge 1.0.0

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

@@ -0,0 +1,90 @@
+import { expectType } from '../expect-type.mjs';
+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);
+  });
+
+  test('should return true for arrays', () => {
+    expect(isNonNullObject([])).toBe(true);
+    expect(isNonNullObject([1, 2, 3])).toBe(true);
+    expect(isNonNullObject(['a', 'b', 'c'])).toBe(true);
+  });
+
+  test('should return true for functions', () => {
+    expect(isNonNullObject(() => {})).toBe(false);
+    expect(isNonNullObject(async () => {})).toBe(false);
+    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+    expect(isNonNullObject(class MyClass {})).toBe(false);
+  });
+
+  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);
+  });
+
+  test('should return true for boxed primitives', () => {
+    // eslint-disable-next-line no-new-wrappers
+    expect(isNonNullObject(new String('hello'))).toBe(true);
+    // eslint-disable-next-line no-new-wrappers
+    expect(isNonNullObject(new Number(42))).toBe(true);
+    // eslint-disable-next-line no-new-wrappers
+    expect(isNonNullObject(new Boolean(true))).toBe(true);
+  });
+
+  test('should return false for null', () => {
+    expect(isNonNullObject(null)).toBe(false);
+  });
+
+  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(BigInt(123))).toBe(false);
+  });
+
+  test('should act as a type guard', () => {
+    const value: unknown = { test: true };
+
+    if (isNonNullObject(value)) {
+      expectType<typeof value, NonNullable<UnknownRecord>>('>=');
+      // Can access object methods
+      expect(typeof value.toString).toBe('function');
+    }
+  });
+
+  test('should narrow nullable object types', () => {
+    const nullable: UnknownRecord | null = Math.random() > 0.5 ? {} : null;
+
+    if (isNonNullObject(nullable)) {
+      expectType<typeof nullable, UnknownRecord>('=');
+    }
+  });
+
+  test('should work in filter operations', () => {
+    const mixed: unknown[] = [
+      'string',
+      42,
+      { a: 1 },
+      null,
+      undefined,
+      [],
+      () => {},
+      true,
+    ];
+
+    const objects = mixed.filter(isNonNullObject);
+
+    expect(objects).toStrictEqual([{ a: 1 }, []]);
+  });
+});

package/src/guard/is-primitive.mts

@@ -0,0 +1,165 @@
+import { expectType } from '../expect-type.mjs';
+
+/**
+ * Type guard that checks if a value is a primitive type.
+ *
+ * This function identifies JavaScript primitive types, which are immutable data types that are
+ * not objects. The primitive types are: `string`, `number`, `boolean`, `undefined`, `symbol`,
+ * `bigint`, and `null`.
+ *
+ * **Important Note:** Although `null` has `typeof null === "object"` due to a historical
+ * JavaScript quirk, this function correctly identifies `null` as a primitive value.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows the input type to `Primitive` (union of all primitive types)
+ * - Excludes object types, arrays, functions, and other non-primitive values
+ * - Includes `null` despite its misleading `typeof` result
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a primitive type, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `Primitive`.
+ *
+ * @example
+ * Basic usage with different value types:
+ * ```typescript
+ * isPrimitive("hello");        // true (string)
+ * isPrimitive(42);             // true (number)
+ * isPrimitive(true);           // true (boolean)
+ * isPrimitive(undefined);      // true (undefined)
+ * isPrimitive(Symbol('test')); // true (symbol)
+ * isPrimitive(123n);           // true (bigint)
+ * isPrimitive(null);           // true (null is primitive despite typeof quirk)
+ *
+ * isPrimitive({});             // false (object)
+ * isPrimitive([]);             // false (array)
+ * isPrimitive(() => {});       // false (function)
+ * isPrimitive(new Date());     // false (object instance)
+ * isPrimitive(/regex/);        // false (RegExp object)
+ * ```
+ *
+ * @example
+ * Type guard usage for separating primitives from objects:
+ * ```typescript
+ * const values: unknown[] = [
+ *   'string',
+ *   42,
+ *   true,
+ *   null,
+ *   undefined,
+ *   {},
+ *   [],
+ *   new Date()
+ * ];
+ *
+ * const primitives = values.filter(isPrimitive);
+ * const objects = values.filter(value => !isPrimitive(value));
+ *
+ * primitives.forEach(primitive => {
+ *   // primitive is now typed as Primitive
+ *   console.log('Primitive value:', primitive);
+ *   console.log('Type:', typeof primitive);
+ * });
+ * ```
+ *
+ * @example
+ * Deep cloning detection - primitives don't need cloning:
+ * ```typescript
+ * function deepClone<T>(value: T): T {
+ *   if (isPrimitive(value)) {
+ *     // Primitives are immutable, return as-is
+ *     return value;
+ *   }
+ *
+ *   // Handle object cloning for non-primitives
+ *   if (Array.isArray(value)) {
+ *     return value.map(deepClone) as T;
+ *   }
+ *
+ *   if (isRecord(value)) {
+ *     const cloned = {} as T;
+ *     for (const key in value) {
+ *       if (Object.hasOwn(value, key)) {
+ *         cloned[key] = deepClone(value[key]);
+ *       }
+ *     }
+ *     return cloned;
+ *   }
+ *
+ *   // For other object types, return as-is or implement specific cloning
+ *   return value;
+ * }
+ * ```
+ *
+ * @example
+ * Serialization helpers:
+ * ```typescript
+ * function canSerializeDirectly(value: unknown): boolean {
+ *   if (isPrimitive(value)) {
+ *     // Most primitives can be serialized directly
+ *     return typeof value !== 'symbol' && typeof value !== 'bigint';
+ *   }
+ *   return false;
+ * }
+ *
+ * function safeStringify(value: unknown): string {
+ *   if (isPrimitive(value)) {
+ *     if (value === null) return 'null';
+ *     if (value === undefined) return 'undefined';
+ *     if (typeof value === 'symbol') return value.toString();
+ *     if (typeof value === 'bigint') return value.toString() + 'n';
+ *     return String(value);
+ *   }
+ *
+ *   return JSON.stringify(value);
+ * }
+ * ```
+ *
+ * @example
+ * Type narrowing in conditional logic:
+ * ```typescript
+ * function processValue(value: unknown): string {
+ *   if (isPrimitive(value)) {
+ *     // value is now Primitive type
+ *     switch (typeof value) {
+ *       case 'string':
+ *         return `String: ${value}`;
+ *       case 'number':
+ *         return `Number: ${value}`;
+ *       case 'boolean':
+ *         return `Boolean: ${value}`;
+ *       case 'undefined':
+ *         return 'Undefined';
+ *       case 'symbol':
+ *         return `Symbol: ${value.description || 'unnamed'}`;
+ *       case 'bigint':
+ *         return `BigInt: ${value}n`;
+ *       case 'object': // This is null
+ *         return 'Null';
+ *       default:
+ *         return 'Unknown primitive';
+ *     }
+ *   } else {
+ *     return `Object: ${value?.constructor?.name || 'Unknown'}`;
+ *   }
+ * }
+ * ```
+ */
+export const isPrimitive = (u: unknown): u is Primitive => {
+  switch (typeof u) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+    case 'undefined':
+    case 'symbol':
+    case 'bigint':
+      return true;
+    case 'function':
+    case 'object':
+      return u === null;
+  }
+};
+
+expectType<
+  bigint | boolean | number | string | symbol | undefined | null,
+  Primitive
+>('=');

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

@@ -0,0 +1,102 @@
+import { expectType } from '../expect-type.mjs';
+import { isPrimitive } from './is-primitive.mjs';
+
+describe('isPrimitive', () => {
+  test('should return true for string primitives', () => {
+    expect(isPrimitive('hello')).toBe(true);
+    expect(isPrimitive('')).toBe(true);
+
+    const value: unknown = 'test';
+    if (isPrimitive(value)) {
+      expectType<
+        typeof value,
+        bigint | boolean | number | string | symbol | undefined | null
+      >('=');
+    }
+  });
+
+  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);
+  });
+
+  test('should return true for boolean primitives', () => {
+    expect(isPrimitive(true)).toBe(true);
+    expect(isPrimitive(false)).toBe(true);
+  });
+
+  test('should return true for symbol primitives', () => {
+    expect(isPrimitive(Symbol('test'))).toBe(true);
+    expect(isPrimitive(Symbol.iterator)).toBe(true);
+  });
+
+  test('should return true for bigint primitives', () => {
+    expect(isPrimitive(BigInt(123))).toBe(true);
+    expect(isPrimitive(0n)).toBe(true);
+    expect(isPrimitive(-123n)).toBe(true);
+  });
+
+  test('should return true for null', () => {
+    // Note: null is considered an object by typeof, so isPrimitive returns false
+    expect(isPrimitive(null)).toBe(true);
+  });
+
+  test('should return true for undefined', () => {
+    expect(isPrimitive(undefined)).toBe(true);
+  });
+
+  test('should return false for objects', () => {
+    expect(isPrimitive({})).toBe(false);
+    expect(isPrimitive({ a: 1 })).toBe(false);
+    expect(isPrimitive(new Date())).toBe(false);
+  });
+
+  test('should return false for arrays', () => {
+    expect(isPrimitive([])).toBe(false);
+    expect(isPrimitive([1, 2, 3])).toBe(false);
+  });
+
+  test('should return false for functions', () => {
+    expect(isPrimitive(() => {})).toBe(false);
+    expect(isPrimitive(() => {})).toBe(false);
+    expect(isPrimitive(async () => {})).toBe(false);
+  });
+
+  test('should return false for boxed primitives', () => {
+    // eslint-disable-next-line no-new-wrappers
+    expect(isPrimitive(new String('hello'))).toBe(false);
+    // eslint-disable-next-line no-new-wrappers
+    expect(isPrimitive(new Number(42))).toBe(false);
+    // eslint-disable-next-line no-new-wrappers
+    expect(isPrimitive(new Boolean(true))).toBe(false);
+  });
+
+  test('should narrow types correctly in conditional', () => {
+    const values: unknown[] = [
+      'string',
+      42,
+      true,
+      {},
+      [],
+      null,
+      undefined,
+      Symbol('test'),
+    ];
+
+    const primitives = values.filter(isPrimitive);
+    const nonPrimitives = values.filter((v) => !isPrimitive(v));
+
+    expect(primitives.length).toBe(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]).toBe(null);
+    expect(primitives[4]).toBe(undefined);
+    expect(typeof primitives[5]).toBe('symbol');
+
+    expect(nonPrimitives).toStrictEqual([{}, []]);
+  });
+});

package/src/guard/is-record.mts

@@ -0,0 +1,153 @@
+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.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * @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`.
+ *
+ * @example
+ * Basic usage with different value types:
+ * ```typescript
+ * isRecord({});                    // true (empty object)
+ * isRecord({ name: 'John' });      // true (object literal)
+ * isRecord(Object.create(null));   // true (object created with Object.create)
+ * isRecord(new Object());          // true (object constructor)
+ *
+ * isRecord([]);                    // false (array)
+ * isRecord([1, 2, 3]);            // false (array with elements)
+ * isRecord(null);                  // false (null)
+ * isRecord(undefined);             // false (undefined)
+ * isRecord("string");              // false (primitive)
+ * isRecord(42);                    // false (primitive)
+ * isRecord(() => {});              // false (function)
+ * isRecord(new Date());            // false (Date object - not a plain record)
+ * isRecord(/regex/);               // false (RegExp object)
+ * ```
+ *
+ * @example
+ * Type guard usage for safe property access:
+ * ```typescript
+ * const apiResponse: unknown = await fetchUserData();
+ *
+ * if (isRecord(apiResponse)) {
+ *   // apiResponse is now typed as UnknownRecord
+ *   console.log('Response keys:', Object.keys(apiResponse));
+ *
+ *   // Safe to access properties (though values are still unknown)
+ *   const userId = apiResponse.id;        // Type: unknown
+ *   const userName = apiResponse.name;    // Type: unknown
+ *
+ *   // You can combine with other type guards for further narrowing
+ *   if (hasKey(apiResponse, 'id') && isString(apiResponse.id)) {
+ *     console.log('User ID:', apiResponse.id); // Now safely typed as string
+ *   }
+ * } else {
+ *   console.log('API response is not a valid object');
+ * }
+ * ```
+ *
+ * @example
+ * Filtering mixed arrays to find plain objects:
+ * ```typescript
+ * const mixedData: unknown[] = [
+ *   { type: 'user', name: 'Alice' },
+ *   [1, 2, 3],
+ *   'string',
+ *   { type: 'admin', permissions: ['read', 'write'] },
+ *   new Date(),
+ *   null,
+ *   { id: 123 }
+ * ];
+ *
+ * const records = mixedData.filter(isRecord);
+ * // records contains only the plain objects:
+ * // [{ type: 'user', name: 'Alice' }, { type: 'admin', permissions: [...] }, { id: 123 }]
+ *
+ * records.forEach(record => {
+ *   // Each record is guaranteed to be UnknownRecord
+ *   const keys = Object.keys(record);
+ *   console.log('Object keys:', keys);
+ * });
+ * ```
+ *
+ * @example
+ * Progressive validation of nested structures:
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   profile: {
+ *     name: string;
+ *     email: string;
+ *   };
+ * }
+ *
+ * function validateUser(data: unknown): User | null {
+ *   if (!isRecord(data)) {
+ *     return null;
+ *   }
+ *
+ *   // data is now UnknownRecord
+ *   if (!hasKey(data, 'id') || !isString(data.id)) {
+ *     return null;
+ *   }
+ *
+ *   if (!hasKey(data, 'profile') || !isRecord(data.profile)) {
+ *     return null;
+ *   }
+ *
+ *   const profile = data.profile;
+ *   if (!hasKey(profile, 'name') || !isString(profile.name) ||
+ *       !hasKey(profile, 'email') || !isString(profile.email)) {
+ *     return null;
+ *   }
+ *
+ *   return {
+ *     id: data.id,
+ *     profile: {
+ *       name: profile.name,
+ *       email: profile.email
+ *     }
+ *   };
+ * }
+ * ```
+ *
+ * @example
+ * Object transformation and mapping:
+ * ```typescript
+ * function transformRecords(data: unknown[]): Record<string, unknown>[] {
+ *   return data
+ *     .filter(isRecord)  // Keep only plain objects
+ *     .map(record => {
+ *       // Transform each record
+ *       const transformed: Record<string, unknown> = {};
+ *
+ *       for (const [key, value] of Object.entries(record)) {
+ *         // Apply some transformation logic
+ *         transformed[key.toLowerCase()] = value;
+ *       }
+ *
+ *       return transformed;
+ *     });
+ * }
+ * ```
+ *
+ * @see {@link isNonNullObject} - For checking any object type (includes arrays)
+ * @see {@link hasKey} - For checking if a record has specific keys
+ */
+export const isRecord = (u: unknown): u is UnknownRecord =>
+  isNonNullObject(u) && !Array.isArray(u);

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

@@ -0,0 +1,112 @@
+import { expectType } from '../expect-type.mjs';
+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);
+  });
+
+  test('{} is a record', () => {
+    const obj = {} as const;
+    const unk: unknown = obj;
+    const res = isRecord(unk);
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    expectType<typeof obj, {}>('=');
+    expectType<typeof res, boolean>('=');
+
+    if (res) {
+      expectType<typeof unk, UnknownRecord>('=');
+    }
+
+    expect(res).toBe(true);
+  });
+
+  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);
+  });
+
+  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);
+  });
+
+  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);
+  });
+
+  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);
+  });
+
+  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);
+  });
+
+  // test('Map is not a record', () => {
+  //   const obj = new MutableMap();
+  //   const unk: unknown = obj;
+  //   const res = isRecord(unk);
+
+  //   assertNotType<typeof obj, UnknownRecord>("<=");
+  //   expectType<typeof res, boolean>("=");
+
+  //   expect(res).toBe(false);
+  // });
+
+  // test('Set is not a record', () => {
+  //   const obj = new MutableSet();
+  //   const unk: unknown = obj;
+  //   const res = isRecord(unk);
+
+  //   assertNotType<typeof obj, UnknownRecord>("<=");
+  //   expectType<typeof res, boolean>("=");
+
+  //   expect(res).toBe(false);
+  // });
+});