ts-data-forge 3.3.0 → 4.0.0

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

@@ -1,146 +1,33 @@
 /**
  * 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`.
+ * 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.
+ * **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()
- * ];
+ * ```ts
+ * const values: readonly unknown[] = [42, 'Ada', null, { id: 1 }] as const;
  *
  * 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);
- * }
+ * assert.deepStrictEqual(primitives, [42, 'Ada', null]);
  * ```
  *
- * @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'}`;
- *   }
- * }
- * ```
+ * @param u - The value to check
+ * @returns `true` if `u` is a primitive type, `false` otherwise. When `true`,
+ *   TypeScript narrows the type to `Primitive`.
  */
 export declare const isPrimitive: (u: unknown) => u is Primitive;
 //# sourceMappingURL=is-primitive.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"is-primitive.d.mts","sourceRoot":"","sources":["../../src/guard/is-primitive.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+IG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SAa7C,CAAC"}
+{"version":3,"file":"is-primitive.d.mts","sourceRoot":"","sources":["../../src/guard/is-primitive.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SAa7C,CAAC"}

package/dist/guard/is-primitive.mjs

@@ -1,146 +1,33 @@
 /**
  * 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`.
+ * 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.
+ * **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()
- * ];
+ * ```ts
+ * const values: readonly unknown[] = [42, 'Ada', null, { id: 1 }] as const;
  *
  * 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);
- * }
+ * assert.deepStrictEqual(primitives, [42, 'Ada', null]);
  * ```
  *
- * @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'}`;
- *   }
- * }
- * ```
+ * @param u - The value to check
+ * @returns `true` if `u` is a primitive type, `false` otherwise. When `true`,
+ *   TypeScript narrows the type to `Primitive`.
  */
 const isPrimitive = (u) => {
     switch (typeof u) {

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

@@ -1 +1 @@
-{"version":3,"file":"is-primitive.mjs","sources":["../../src/guard/is-primitive.mts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+IG;AACI,MAAM,WAAW,GAAG,CAAC,CAAU,KAAoB;IACxD,QAAQ,OAAO,CAAC;AACd,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,SAAS;AACd,QAAA,KAAK,WAAW;AAChB,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,IAAI;AACb,QAAA,KAAK,UAAU;AACf,QAAA,KAAK,QAAQ;YACX,OAAO,CAAC,KAAK,IAAI;;AAEvB;;;;"}
+{"version":3,"file":"is-primitive.mjs","sources":["../../src/guard/is-primitive.mts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;AACI,MAAM,WAAW,GAAG,CAAC,CAAU,KAAoB;IACxD,QAAQ,OAAO,CAAC;AACd,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,SAAS;AACd,QAAA,KAAK,WAAW;AAChB,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,IAAI;AACb,QAAA,KAAK,UAAU;AACf,QAAA,KAAK,QAAQ;YACX,OAAO,CAAC,KAAK,IAAI;;AAEvB;;;;"}

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

@@ -1,149 +1,38 @@
 /**
- * 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 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.
+ * 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>`)
+ *
+ * - 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 `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);
- * });
- * ```
+ * **Implementation:** Uses `isNonNullObject()` to check for objects, then
+ * `Array.isArray()` to exclude arrays.
  *
  * @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;
- *   }
+ * ```ts
+ * const entries: unknown[] = [{ id: 1 }, ['tuple']];
  *
- *   const profile = data.profile;
- *   if (!hasKey(profile, 'name') || !isString(profile.name) ||
- *       !hasKey(profile, 'email') || !isString(profile.email)) {
- *     return null;
- *   }
+ * const records = entries.filter(isRecord);
  *
- *   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;
- *     });
- * }
+ * assert.deepStrictEqual(records, [{ id: 1 }]);
  * ```
  *
+ * @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)
  * @see {@link hasKey} - For checking if a record has specific keys
  */

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":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aACF,CAAC"}
+{"version":3,"file":"is-record.d.mts","sourceRoot":"","sources":["../../src/guard/is-record.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,aACF,CAAC"}

package/dist/guard/is-record.mjs

@@ -1,151 +1,40 @@
 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 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.
+ * 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>`)
+ *
+ * - 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 `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);
- * });
- * ```
+ * **Implementation:** Uses `isNonNullObject()` to check for objects, then
+ * `Array.isArray()` to exclude arrays.
  *
  * @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;
- *   }
+ * ```ts
+ * const entries: unknown[] = [{ id: 1 }, ['tuple']];
  *
- *   const profile = data.profile;
- *   if (!hasKey(profile, 'name') || !isString(profile.name) ||
- *       !hasKey(profile, 'email') || !isString(profile.email)) {
- *     return null;
- *   }
+ * const records = entries.filter(isRecord);
  *
- *   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;
- *     });
- * }
+ * assert.deepStrictEqual(records, [{ id: 1 }]);
  * ```
  *
+ * @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)
  * @see {@link hasKey} - For checking if a record has specific keys
  */

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":";;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoJG;MACU,QAAQ,GAAG,CAAC,CAAU,KACjC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;;;"}
+{"version":3,"file":"is-record.mjs","sources":["../../src/guard/is-record.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;MACU,QAAQ,GAAG,CAAC,CAAU,KACjC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;;;"}