ts-data-forge 1.0.0 → 1.0.1

package/dist/guard/is-type.mjs

@@ -0,0 +1,432 @@
+/**
+ * Type guard that checks if a value is `undefined`.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows the input type to `undefined` when `true`
+ * - Useful for explicit undefined checks
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is `undefined`, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const value: string | undefined = getValue();
+ *
+ * if (isUndefined(value)) {
+ *   // value is now typed as undefined
+ *   console.log('Value is undefined');
+ * } else {
+ *   // value is now typed as string
+ *   console.log('Value length:', value.length);
+ * }
+ * ```
+ */
+const isUndefined = (u) => u === undefined;
+/**
+ * Type guard that checks if a value is not `undefined`.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `undefined` from the input type when `true`
+ * - Preserves all other types in the union
+ * - Commonly used to filter out undefined values
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not `undefined`, `false` otherwise.
+ *          When `true`, TypeScript excludes `undefined` from the type.
+ *
+ * @example
+ * ```typescript
+ * const items: (string | undefined)[] = ['a', undefined, 'b', undefined, 'c'];
+ *
+ * const definedItems = items.filter(isNotUndefined);
+ * // definedItems is now string[] - undefined values are filtered out
+ *
+ * definedItems.forEach(item => {
+ *   // item is guaranteed to be string, not undefined
+ *   console.log(item.toUpperCase());
+ * });
+ * ```
+ */
+const isNotUndefined = (u) => u !== undefined;
+/**
+ * Type guard that checks if a value is a boolean.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `boolean` when `true`
+ * - Preserves literal boolean types (`true | false`)
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a boolean, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `boolean`.
+ *
+ * @example
+ * ```typescript
+ * const userInput: unknown = parseInput();
+ *
+ * if (isBoolean(userInput)) {
+ *   // userInput is now typed as boolean
+ *   console.log('Boolean value:', userInput ? 'true' : 'false');
+ * }
+ * ```
+ */
+const isBoolean = (u) => typeof u === 'boolean';
+/**
+ * Type guard that checks if a value is not a boolean.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `boolean` from the input type when `true`
+ * - Preserves all other types in the union
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not a boolean, `false` otherwise.
+ *          When `true`, TypeScript excludes `boolean` from the type.
+ *
+ * @example
+ * ```typescript
+ * type MixedValue = string | number | boolean;
+ * const value: MixedValue = getValue();
+ *
+ * if (isNotBoolean(value)) {
+ *   // value is now string | number
+ *   console.log('Non-boolean value:', value);
+ * }
+ * ```
+ */
+const isNotBoolean = (u) => typeof u !== 'boolean';
+/**
+ * Type guard that checks if a value is a number.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `number` when `true`
+ * - Includes `NaN`, `Infinity`, and `-Infinity` as valid numbers
+ * - Preserves literal number types when possible
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a number, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `number`.
+ *
+ * @example
+ * ```typescript
+ * const userInput: unknown = parseInput();
+ *
+ * if (isNumber(userInput)) {
+ *   // userInput is now typed as number
+ *   console.log('Number value:', userInput.toFixed(2));
+ *
+ *   // Note: this includes NaN and Infinity
+ *   if (Number.isFinite(userInput)) {
+ *     console.log('Finite number:', userInput);
+ *   }
+ * }
+ * ```
+ */
+const isNumber = (u) => typeof u === 'number';
+/**
+ * Type guard that checks if a value is not a number.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `number` from the input type when `true`
+ * - Preserves all other types in the union
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not a number, `false` otherwise.
+ *          When `true`, TypeScript excludes `number` from the type.
+ *
+ * @example
+ * ```typescript
+ * type Value = string | number | boolean;
+ * const values: Value[] = ['hello', 42, true, 3.14, false];
+ *
+ * const nonNumbers = values.filter(isNotNumber);
+ * // nonNumbers is now (string | boolean)[] - numbers are filtered out
+ * ```
+ */
+const isNotNumber = (u) => typeof u !== 'number';
+/**
+ * Type guard that checks if a value is a bigint.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `bigint` when `true`
+ * - Identifies values created with `BigInt()` constructor or `n` suffix
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a bigint, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `bigint`.
+ *
+ * @example
+ * ```typescript
+ * const userInput: unknown = parseInput();
+ *
+ * if (isBigint(userInput)) {
+ *   // userInput is now typed as bigint
+ *   console.log('BigInt value:', userInput.toString());
+ *   const doubled = userInput * 2n; // Safe bigint operations
+ * }
+ * ```
+ */
+const isBigint = (u) => typeof u === 'bigint';
+/**
+ * Type guard that checks if a value is not a bigint.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `bigint` from the input type when `true`
+ * - Preserves all other types in the union
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not a bigint, `false` otherwise.
+ *          When `true`, TypeScript excludes `bigint` from the type.
+ *
+ * @example
+ * ```typescript
+ * type NumericValue = number | bigint;
+ * const value: NumericValue = getValue();
+ *
+ * if (isNotBigint(value)) {
+ *   // value is now number
+ *   console.log('Regular number:', value.toFixed(2));
+ * }
+ * ```
+ */
+const isNotBigint = (u) => typeof u !== 'bigint';
+/**
+ * Type guard that checks if a value is a string.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `string` when `true`
+ * - Preserves literal string types when possible
+ * - Includes empty strings
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a string, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `string`.
+ *
+ * @example
+ * ```typescript
+ * const userInput: unknown = parseInput();
+ *
+ * if (isString(userInput)) {
+ *   // userInput is now typed as string
+ *   console.log('String length:', userInput.length);
+ *   console.log('Uppercase:', userInput.toUpperCase());
+ *
+ *   // You can further check for non-empty strings
+ *   if (userInput.length > 0) {
+ *     console.log('Non-empty string:', userInput);
+ *   }
+ * }
+ * ```
+ */
+const isString = (u) => typeof u === 'string';
+/**
+ * Type guard that checks if a value is not a string.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `string` from the input type when `true`
+ * - Preserves all other types in the union
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not a string, `false` otherwise.
+ *          When `true`, TypeScript excludes `string` from the type.
+ *
+ * @example
+ * ```typescript
+ * type Value = string | number | boolean;
+ * const mixedValues: Value[] = ['hello', 42, true, 'world', 3.14];
+ *
+ * const nonStrings = mixedValues.filter(isNotString);
+ * // nonStrings is now (number | boolean)[] - strings are filtered out
+ * ```
+ */
+const isNotString = (u) => typeof u !== 'string';
+/**
+ * Type guard that checks if a value is a symbol.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows `unknown` to `symbol` when `true`
+ * - Identifies values created with `Symbol()` constructor
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a symbol, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `symbol`.
+ *
+ * @example
+ * ```typescript
+ * const userInput: unknown = parseInput();
+ *
+ * if (isSymbol(userInput)) {
+ *   // userInput is now typed as symbol
+ *   console.log('Symbol description:', userInput.description);
+ *   console.log('Symbol string:', userInput.toString());
+ * }
+ * ```
+ */
+const isSymbol = (u) => typeof u === 'symbol';
+/**
+ * Type guard that checks if a value is not a symbol.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `symbol` from the input type when `true`
+ * - Preserves all other types in the union
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not a symbol, `false` otherwise.
+ *          When `true`, TypeScript excludes `symbol` from the type.
+ *
+ * @example
+ * ```typescript
+ * type PropertyKey = string | number | symbol;
+ * const key: PropertyKey = getPropertyKey();
+ *
+ * if (isNotSymbol(key)) {
+ *   // key is now string | number
+ *   console.log('Non-symbol key:', key);
+ * }
+ * ```
+ */
+const isNotSymbol = (u) => typeof u !== 'symbol';
+/**
+ * Type guard that checks if a value is `null`.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows the input type to `null` when `true`
+ * - Useful for explicit null checks
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is `null`, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `null`.
+ *
+ * @example
+ * ```typescript
+ * const value: string | null = getValue();
+ *
+ * if (isNull(value)) {
+ *   // value is now typed as null
+ *   console.log('Value is null');
+ * } else {
+ *   // value is now typed as string
+ *   console.log('Value length:', value.length);
+ * }
+ * ```
+ */
+const isNull = (u) => u === null;
+/**
+ * Type guard that checks if a value is not `null`.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes `null` from the input type when `true`
+ * - Preserves all other types including `undefined`
+ * - Commonly used to filter out null values
+ *
+ * @template T - The type of the input value (which could be `null`)
+ * @param u - The value to check
+ * @returns `true` if `u` is not `null`, `false` otherwise.
+ *          When `true`, TypeScript excludes `null` from the type.
+ *
+ * @example
+ * ```typescript
+ * const items: (string | null)[] = ['a', null, 'b', null, 'c'];
+ *
+ * const nonNullItems = items.filter(isNotNull);
+ * // nonNullItems is now string[] - null values are filtered out
+ *
+ * nonNullItems.forEach(item => {
+ *   // item is guaranteed to be string, not null
+ *   console.log(item.toUpperCase());
+ * });
+ * ```
+ */
+const isNotNull = (u) => u !== null;
+/**
+ * Type guard that checks if a value is `null` or `undefined` (nullish).
+ *
+ * This function uses the loose equality operator (`==`) to check for both `null` and `undefined`
+ * in a single comparison, which is the standard JavaScript idiom for nullish checks.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows the input type to `null | undefined` when `true`
+ * - Useful for checking if a value is "nullish" (either null or undefined)
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is `null` or `undefined`, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `null | undefined`.
+ *
+ * @example
+ * ```typescript
+ * const value: string | null | undefined = getValue();
+ *
+ * if (isNullish(value)) {
+ *   // value is now typed as null | undefined
+ *   console.log('Value is nullish');
+ * } else {
+ *   // value is now typed as string
+ *   console.log('Value length:', value.length);
+ * }
+ * ```
+ */
+const isNullish = (u) => u == null;
+/**
+ * Type guard that checks if a value is not `null` or `undefined` (non-nullish).
+ *
+ * This function uses the loose inequality operator (`!=`) to check that a value is neither
+ * `null` nor `undefined` in a single comparison. This is equivalent to TypeScript's
+ * `NonNullable<T>` utility type.
+ *
+ * **Type Narrowing Behavior:**
+ * - Excludes both `null` and `undefined` from the input type when `true`
+ * - Equivalent to applying TypeScript's `NonNullable<T>` utility type
+ * - Commonly used to filter out nullish values from arrays
+ *
+ * @template T - The type of the input value
+ * @param u - The value to check
+ * @returns `true` if `u` is not `null` and not `undefined`, `false` otherwise.
+ *          When `true`, TypeScript narrows the type to `NonNullable<T>`.
+ *
+ * @example
+ * ```typescript
+ * const items: (string | null | undefined)[] = [
+ *   'hello',
+ *   null,
+ *   'world',
+ *   undefined,
+ *   'test'
+ * ];
+ *
+ * const definedItems = items.filter(isNonNullish);
+ * // definedItems is now string[] - both null and undefined values are filtered out
+ *
+ * definedItems.forEach(item => {
+ *   // item is guaranteed to be string, never null or undefined
+ *   console.log(item.toUpperCase());
+ * });
+ * ```
+ *
+ * @example
+ * Progressive validation with optional chaining alternative:
+ * ```typescript
+ * interface User {
+ *   profile?: {
+ *     name?: string;
+ *     email?: string;
+ *   };
+ * }
+ *
+ * const user: User = getUser();
+ *
+ * // Instead of optional chaining: user.profile?.name
+ * if (isNonNullish(user.profile) && isNonNullish(user.profile.name)) {
+ *   // user.profile.name is now guaranteed to be string
+ *   console.log('User name:', user.profile.name.toUpperCase());
+ * }
+ * ```
+ */
+const isNonNullish = (u) => u != null;
+
+export { isBigint, isBoolean, isNonNullish, isNotBigint, isNotBoolean, isNotNull, isNotNumber, isNotString, isNotSymbol, isNotUndefined, isNull, isNullish, isNumber, isString, isSymbol, isUndefined };
+//# sourceMappingURL=is-type.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"is-type.mjs","sources":["../../src/guard/is-type.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACI,MAAM,WAAW,GAAG,CAAC,CAAU,KAAqB,CAAC,KAAK;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,cAAc,GAAG,CAAK,CAAI,KACrC,CAAC,KAAK;AAER;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,MAAM,SAAS,GAAG,CAAC,CAAU,KAAmB,OAAO,CAAC,KAAK;AAEpE;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,MAAM,YAAY,GAAG,CAAK,CAAI,KACnC,OAAO,CAAC,KAAK;AAEf;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,QAAQ,GAAG,CAAC,CAAU,KAAkB,OAAO,CAAC,KAAK;AAElE;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,MAAM,WAAW,GAAG,CAAK,CAAI,KAClC,OAAO,CAAC,KAAK;AAEf;;;;;;;;;;;;;;;;;;;;;AAqBG;AACI,MAAM,QAAQ,GAAG,CAAC,CAAU,KAAkB,OAAO,CAAC,KAAK;AAElE;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,MAAM,WAAW,GAAG,CAAK,CAAI,KAClC,OAAO,CAAC,KAAK;AAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACI,MAAM,QAAQ,GAAG,CAAC,CAAU,KAAkB,OAAO,CAAC,KAAK;AAElE;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,MAAM,WAAW,GAAG,CAAK,CAAI,KAClC,OAAO,CAAC,KAAK;AAEf;;;;;;;;;;;;;;;;;;;;;AAqBG;AACI,MAAM,QAAQ,GAAG,CAAC,CAAU,KAAkB,OAAO,CAAC,KAAK;AAElE;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,MAAM,WAAW,GAAG,CAAK,CAAI,KAClC,OAAO,CAAC,KAAK;AAEf;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACI,MAAM,MAAM,GAAG,CAAC,CAAU,KAAgB,CAAC,KAAK;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,SAAS,GAAG,CAAK,CAAW,KAAa,CAAC,KAAK;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,SAAS,GAAG,CAAC,CAAU,KAA4B,CAAC,IAAI;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDG;AACI,MAAM,YAAY,GAAG,CAAK,CAAI,KAA0B,CAAC,IAAI;;;;"}

package/dist/guard/key-is-in.d.mts

@@ -0,0 +1,158 @@
+/**
+ * Type guard that checks if a key exists as an own property in an object.
+ *
+ * This function is similar to `hasKey()` but with reversed parameter order and different
+ * type narrowing behavior. While `hasKey()` narrows the object type, `keyIsIn()` narrows
+ * the key type to be a valid key of the given object.
+ *
+ * **Type Narrowing Behavior:**
+ * - Narrows the key type to be a key that exists in the object (`K & keyof R`)
+ * - Useful when you have a dynamic key and want to ensure it's valid for a specific object
+ * - The object type remains unchanged
+ *
+ * **Implementation:** Uses `Object.hasOwn()` to check for own properties (not inherited).
+ *
+ * @template K - The type of the key to check, must extend PropertyKey (string | number | symbol)
+ * @template R - The type of the record (object), must extend UnknownRecord
+ * @param key - The key to check for
+ * @param obj - The object to check within
+ * @returns `true` if `key` is an own property of `obj`, `false` otherwise.
+ *          When `true`, TypeScript narrows the key type to be a valid key of the object.
+ *
+ * @example
+ * Basic usage with known object structure:
+ * ```typescript
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const userInput: string = getUserInput(); // Could be any string
+ *
+ * if (keyIsIn(userInput, obj)) {
+ *   // userInput is now narrowed to 'a' | 'b' | 'c'
+ *   const value = obj[userInput]; // Type-safe access, value is number
+ *   console.log(`Value for ${userInput}:`, value);
+ * } else {
+ *   console.log(`Key '${userInput}' not found in object`);
+ * }
+ * ```
+ *
+ * @example
+ * Dynamic key validation for safe property access:
+ * ```typescript
+ * const config = {
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: 5000,
+ *   retries: 3
+ * } as const;
+ *
+ * function getConfigValue(key: string): unknown {
+ *   if (keyIsIn(key, config)) {
+ *     // key is now narrowed to 'apiUrl' | 'timeout' | 'retries'
+ *     return config[key]; // Safe access with proper typing
+ *   }
+ *
+ *   throw new Error(`Invalid config key: ${key}`);
+ * }
+ *
+ * // Usage
+ * const apiUrl = getConfigValue('apiUrl');    // Returns string
+ * const timeout = getConfigValue('timeout');  // Returns number
+ * // getConfigValue('invalid') would throw an error
+ * ```
+ *
+ * @example
+ * Form field validation:
+ * ```typescript
+ * interface FormData {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const formData: FormData = getFormData();
+ * const requiredFields: readonly string[] = ['name', 'email'] as const;
+ *
+ * function validateRequiredFields(data: FormData): string[] {
+ *   const errors: string[] = [];
+ *
+ *   for (const field of requiredFields) {
+ *     if (keyIsIn(field, data)) {
+ *       // field is now narrowed to keyof FormData
+ *       const value = data[field];
+ *
+ *       if (typeof value === 'string' && value.trim() === '') {
+ *         errors.push(`${field} is required`);
+ *       }
+ *     }
+ *   }
+ *
+ *   return errors;
+ * }
+ * ```
+ *
+ * @example
+ * Safe object property iteration:
+ * ```typescript
+ * const userPreferences = {
+ *   theme: 'dark',
+ *   language: 'en',
+ *   notifications: true
+ * };
+ *
+ * const settingsToUpdate: string[] = getSettingsFromUser();
+ *
+ * function updatePreferences(updates: Record<string, unknown>) {
+ *   const validUpdates: Partial<typeof userPreferences> = {};
+ *
+ *   for (const [key, value] of Object.entries(updates)) {
+ *     if (keyIsIn(key, userPreferences)) {
+ *       // key is now narrowed to valid preference keys
+ *       validUpdates[key] = value as typeof userPreferences[typeof key];
+ *     } else {
+ *       console.warn(`Unknown preference key: ${key}`);
+ *     }
+ *   }
+ *
+ *   return { ...userPreferences, ...validUpdates };
+ * }
+ * ```
+ *
+ * @example
+ * Comparison with hasKey() - different narrowing behavior:
+ * ```typescript
+ * const obj = { x: 10, y: 20 };
+ * const key: string = 'x';
+ *
+ * // Using keyIsIn - narrows the key type
+ * if (keyIsIn(key, obj)) {
+ *   // key is now 'x' | 'y'
+ *   const value = obj[key]; // Safe access
+ * }
+ *
+ * // Using hasKey - narrows the object type
+ * if (hasKey(obj, key)) {
+ *   // obj type is narrowed to guarantee the key exists
+ *   const value = obj.x; // Direct access
+ * }
+ * ```
+ *
+ * @example
+ * Working with union types:
+ * ```typescript
+ * type Config =
+ *   | { type: 'database'; host: string; port: number }
+ *   | { type: 'file'; path: string }
+ *   | { type: 'memory'; maxSize: number };
+ *
+ * function getConfigProperty(config: Config, propName: string): unknown {
+ *   if (keyIsIn(propName, config)) {
+ *     // propName is narrowed to valid keys for the specific config type
+ *     return config[propName];
+ *   }
+ *
+ *   return undefined;
+ * }
+ * ```
+ *
+ * @see {@link hasKey} - Similar function that narrows the object type instead of the key type
+ */
+export declare const keyIsIn: <const K extends PropertyKey, const R extends UnknownRecord>(key: K, obj: R) => key is K & keyof typeof obj;
+//# sourceMappingURL=key-is-in.d.mts.map

package/dist/guard/key-is-in.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-is-in.d.mts","sourceRoot":"","sources":["../../src/guard/key-is-in.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2JG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,CAAC,CAAC,SAAS,WAAW,EAC3B,KAAK,CAAC,CAAC,SAAS,aAAa,EAE7B,KAAK,CAAC,EACN,KAAK,CAAC,KACL,GAAG,IAAI,CAAC,GAAG,MAAM,OAAO,GAA8B,CAAC"}