ts-data-forge 1.0.0 → 1.0.1

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

@@ -0,0 +1,108 @@
+/**
+ * Type guard that checks if a value is a non-null object.
+ *
+ * This function checks if a value has type `"object"` according to the `typeof` operator
+ * and is not `null`. This includes all object types such as plain objects, arrays, dates,
+ * regular expressions, and other object instances, but excludes functions.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `object`
+ * - Excludes `null`, `undefined`, and all primitive types
+ * - 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.
+ *
+ * @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`.
+ *
+ * @example
+ * Basic usage with different value types:
+ * ```typescript
+ * isNonNullObject({});           // true (plain object)
+ * isNonNullObject([]);           // true (arrays are objects)
+ * isNonNullObject(new Date());   // true (Date instance)
+ * isNonNullObject(/regex/);      // true (RegExp instance)
+ * isNonNullObject(new Map());    // true (Map instance)
+ * isNonNullObject(null);         // false (null is not considered object here)
+ * isNonNullObject(undefined);    // false (primitive)
+ * isNonNullObject("string");     // false (primitive)
+ * isNonNullObject(42);           // false (primitive)
+ * isNonNullObject(true);         // false (primitive)
+ * isNonNullObject(() => {});     // false (functions are not objects in this context)
+ * ```
+ *
+ * @example
+ * Type guard usage with unknown values:
+ * ```typescript
+ * const value: unknown = parseJsonData();
+ *
+ * if (isNonNullObject(value)) {
+ *   // value is now typed as object
+ *   console.log('Value is an object');
+ *
+ *   // You can now safely use object-specific operations
+ *   console.log(Object.keys(value));      // Safe to call Object.keys
+ *   console.log(value.toString());        // Safe to call methods
+ *
+ *   // But you may need additional checks for specific object types
+ *   if (Array.isArray(value)) {
+ *     console.log('It\'s an array with length:', value.length);
+ *   }
+ * } else {
+ *   console.log('Value is not an object');
+ * }
+ * ```
+ *
+ * @example
+ * Filtering arrays to find objects:
+ * ```typescript
+ * const mixedArray: unknown[] = [
+ *   { name: 'John' },
+ *   'string',
+ *   [1, 2, 3],
+ *   42,
+ *   null,
+ *   new Date(),
+ *   () => 'function'
+ * ];
+ *
+ * const objects = mixedArray.filter(isNonNullObject);
+ * // objects contains: [{ name: 'John' }, [1, 2, 3], Date instance]
+ * // Note: includes both plain objects and arrays
+ *
+ * objects.forEach(obj => {
+ *   // Each obj is guaranteed to be an object
+ *   console.log('Object type:', obj.constructor.name);
+ * });
+ * ```
+ *
+ * @example
+ * Progressive type narrowing with other guards:
+ * ```typescript
+ * const apiResponse: unknown = await fetchData();
+ *
+ * if (isNonNullObject(apiResponse)) {
+ *   // apiResponse is now object
+ *
+ *   if (isRecord(apiResponse)) {
+ *     // Further narrowed to UnknownRecord (plain object, not array)
+ *
+ *     if (hasKey(apiResponse, 'status')) {
+ *       console.log('API status:', apiResponse.status);
+ *     }
+ *   } else if (Array.isArray(apiResponse)) {
+ *     console.log('Response is an array with length:', apiResponse.length);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
+ */
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
+const isNonNullObject = (u) => typeof u === 'object' && u !== null;
+
+export { isNonNullObject };
+//# sourceMappingURL=is-non-null-object.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"is-non-null-object.mjs","sources":["../../src/guard/is-non-null-object.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGG;AACH;AACO,MAAM,eAAe,GAAG,CAAC,CAAU,KACxC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK;;;;"}

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

@@ -0,0 +1,146 @@
+/**
+ * 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 declare const isPrimitive: (u: unknown) => u is Primitive;
+//# sourceMappingURL=is-primitive.d.mts.map

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

@@ -0,0 +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"}

package/dist/guard/is-primitive.mjs

@@ -0,0 +1,161 @@
+/**
+ * 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'}`;
+ *   }
+ * }
+ * ```
+ */
+const isPrimitive = (u) => {
+    switch (typeof u) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'undefined':
+        case 'symbol':
+        case 'bigint':
+            return true;
+        case 'function':
+        case 'object':
+            return u === null;
+    }
+};
+
+export { isPrimitive };
+//# sourceMappingURL=is-primitive.mjs.map

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

@@ -0,0 +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;;;;"}

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

@@ -0,0 +1,151 @@
+/**
+ * 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 declare const isRecord: (u: unknown) => u is UnknownRecord;
+//# sourceMappingURL=is-record.d.mts.map

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

@@ -0,0 +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"}