indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/helpers/type-guards.d.ts

@@ -1,634 +0,0 @@
-/**
- * @fileoverview Type Guards and Type Narrowing Utilities
- *
- * This module provides comprehensive runtime type checking functions that serve as
- * TypeScript type predicates. Type guards enable type narrowing in TypeScript, allowing
- * the compiler to automatically refine types based on runtime checks. This is essential
- * for:
- *
- * 1. **Runtime Type Safety**: Validate data at runtime before it's processed
- * 2. **Type Narrowing**: Automatically narrow union types based on guard results
- * 3. **Discriminated Unions**: Pattern match on type characteristics
- * 4. **API Response Validation**: Verify external data conforms to expected types
- * 5. **Error Handling**: Safely handle different error types
- *
- * ## Type Narrowing in TypeScript
- *
- * Type guards allow TypeScript to narrow types within conditional blocks:
- *
- * ```typescript
- * const value: string | number = getValue();
- *
- * if (isString(value)) {
- *   // TypeScript now knows value is string
- *   value.toUpperCase(); // ✓ Allowed
- * } else if (isNumber(value)) {
- *   // TypeScript now knows value is number
- *   value.toFixed(2); // ✓ Allowed
- * }
- * ```
- *
- * ## When to Use Type Guards
- *
- * - Validating external data (API responses, user input, config files)
- * - Handling union types safely
- * - Implementing discriminated unions
- * - Working with `any` or `unknown` types
- * - Defensive programming at module boundaries
- *
- * @author Coding Agent
- * @version 1.0.0
- */
-/**
- * Checks if a value is a primitive type (string, number, boolean, null, undefined, symbol, bigint).
- *
- * Primitive types in JavaScript are immutable and passed by value. This is useful for
- * quick type categorization and distinguishing primitives from objects.
- *
- * Note: Infinity and NaN are not considered primitive by this guard because they
- * represent special numeric states that are often error conditions.
- *
- * @param value - The value to check
- * @returns true if value is a primitive type (excludes Infinity and NaN)
- *
- * @example
- * ```typescript
- * isPrimitive(42)           // true
- * isPrimitive("hello")      // true
- * isPrimitive(true)         // true
- * isPrimitive(null)         // true
- * isPrimitive(undefined)    // true
- * isPrimitive(Infinity)     // false (not finite)
- * isPrimitive(NaN)          // false (not finite)
- * isPrimitive({})           // false
- * isPrimitive([])           // false
- * isPrimitive(() => {})     // false
- * ```
- *
- * @usage
- * ```typescript
- * function processValue(value: unknown) {
- *   if (isPrimitive(value)) {
- *     // Safely stringify or log primitive
- *     console.log(String(value));
- *   } else {
- *     // Handle complex object
- *     processObject(value as object);
- *   }
- * }
- * ```
- */
-export declare function isPrimitive(value: unknown): value is string | number | boolean | null | undefined | symbol | bigint;
-/**
- * Checks if a value is a plain JavaScript object (not null, array, function, or built-in object).
- *
- * This guard specifically identifies plain objects created with `{}` or `Object.create(null)`,
- * excluding arrays, dates, regex, errors, and other special object types. Useful for
- * differentiating data objects from other object types.
- *
- * @param value - The value to check
- * @returns true if value is a plain object
- *
- * @example
- * ```typescript
- * isObject({})                    // true
- * isObject({ name: 'John' })     // true
- * isObject(Object.create(null))  // true
- * isObject([])                    // false (array)
- * isObject(new Date())            // false (built-in object)
- * isObject(new Map())             // false (built-in object)
- * isObject(null)                  // false
- * isObject("string")              // false
- * ```
- *
- * @usage
- * ```typescript
- * // Merge configuration objects safely
- * function mergeConfig(target: Record<string, any>, source: unknown) {
- *   if (isObject(source)) {
- *     Object.assign(target, source);
- *   } else {
- *     throw new Error('Configuration must be a plain object');
- *   }
- * }
- * ```
- */
-export declare function isObject(value: unknown): value is Record<string, unknown>;
-/**
- * Checks if a value is an array.
- *
- * Type narrows to Array<unknown>. Use type parameters for more specific array types
- * in combination with element validation.
- *
- * @param value - The value to check
- * @returns true if value is an array
- *
- * @example
- * ```typescript
- * isArray([])                           // true
- * isArray([1, 2, 3])                   // true
- * isArray(['a', 'b'])                  // true
- * isArray(new Array())                 // true
- * isArray({})                          // false
- * isArray("string")                    // false
- * isArray(null)                        // false
- * ```
- *
- * @usage
- * ```typescript
- * // Type-safe array processing
- * function processItems(items: unknown): number {
- *   if (isArray(items)) {
- *     return items.reduce((sum, item) => {
- *       return sum + (isNumber(item) ? item : 0);
- *     }, 0);
- *   }
- *   return 0;
- * }
- *
- * // Iterate safely with type narrowing
- * if (isArray(data)) {
- *   data.forEach(item => {
- *     console.log(item);
- *   });
- * }
- * ```
- */
-export declare function isArray(value: unknown): value is unknown[];
-/**
- * Checks if a value is a string.
- *
- * Useful for string validation, form input verification, and discriminating
- * between string and number types.
- *
- * @param value - The value to check
- * @returns true if value is a string
- *
- * @example
- * ```typescript
- * isString("hello")                   // true
- * isString("")                        // true
- * isString(new String("text"))        // false (object wrapper)
- * isString(123)                       // false
- * isString(null)                      // false
- * ```
- *
- * @usage
- * ```typescript
- * // Validate user input
- * function processUserInput(input: unknown): void {
- *   if (!isString(input)) {
- *     throw new TypeError('Input must be a string');
- *   }
- *
- *   const trimmed = input.trim();
- *   if (trimmed.length === 0) {
- *     throw new Error('Input cannot be empty');
- *   }
- * }
- *
- * // Parse environment variables safely
- * function getEnvString(key: string, defaultValue: string = ''): string {
- *   const value = process.env[key];
- *   return isString(value) ? value : defaultValue;
- * }
- * ```
- */
-export declare function isString(value: unknown): value is string;
-/**
- * Checks if a value is a number (excluding NaN and Infinity).
- *
- * This strict guard rejects NaN and Infinity, which are valid JavaScript numbers
- * but often represent error states. Use with caution when you specifically need
- * to accept these special values.
- *
- * @param value - The value to check
- * @returns true if value is a valid finite number
- *
- * @example
- * ```typescript
- * isNumber(42)                    // true
- * isNumber(3.14)                  // true
- * isNumber(-5)                    // true
- * isNumber(0)                     // true
- * isNumber(Infinity)              // false (rejected for safety)
- * isNumber(-Infinity)             // false
- * isNumber(NaN)                   // false
- * isNumber("123")                 // false
- * isNumber(new Number(42))        // false (wrapper object)
- * ```
- *
- * @usage
- * ```typescript
- * // Calculate average safely
- * function calculateAverage(values: unknown[]): number | null {
- *   const numbers = values.filter(isNumber);
- *   if (numbers.length === 0) return null;
- *   return numbers.reduce((a, b) => a + b, 0) / numbers.length;
- * }
- *
- * // Validate port numbers
- * function isValidPort(port: unknown): boolean {
- *   return isNumber(port) && port >= 0 && port <= 65535;
- * }
- * ```
- */
-export declare function isNumber(value: unknown): value is number;
-/**
- * Checks if a value is a boolean (true or false).
- *
- * @param value - The value to check
- * @returns true if value is a boolean
- *
- * @example
- * ```typescript
- * isBoolean(true)                 // true
- * isBoolean(false)                // true
- * isBoolean(1)                    // false
- * isBoolean("true")               // false
- * isBoolean(new Boolean(true))    // false (wrapper object)
- * ```
- *
- * @usage
- * ```typescript
- * // Type-safe configuration
- * interface Config {
- *   debug?: boolean;
- * }
- *
- * function parseConfig(input: unknown): Config {
- *   if (!isObject(input)) throw new Error('Config must be an object');
- *
- *   const debug = (input as any).debug;
- *   return {
- *     debug: isBoolean(debug) ? debug : false
- *   };
- * }
- * ```
- */
-export declare function isBoolean(value: unknown): value is boolean;
-/**
- * Checks if a value is a function.
- *
- * Distinguishes callable functions from other object types. Useful for
- * callback validation and dynamic function calling.
- *
- * @param value - The value to check
- * @returns true if value is a function
- *
- * @example
- * ```typescript
- * isFunction(() => {})                    // true
- * isFunction(function() {})               // true
- * isFunction(async () => {})              // true
- * isFunction(class MyClass {})            // true
- * isFunction(Promise.resolve)             // true
- * isFunction(Math.max)                    // true
- * isFunction({})                          // false
- * isFunction("function")                  // false
- * ```
- *
- * @usage
- * ```typescript
- * // Callback validation and execution
- * function processWithCallback(
- *   data: unknown,
- *   callback: unknown
- * ): unknown {
- *   if (!isFunction(callback)) {
- *     throw new TypeError('Callback must be a function');
- *   }
- *   return callback(data);
- * }
- *
- * // Build event emitter safely
- * const listeners: Map<string, Function[]> = new Map();
- *
- * function on(event: string, listener: unknown) {
- *   if (!isFunction(listener)) {
- *     throw new TypeError('Listener must be a function');
- *   }
- *   if (!listeners.has(event)) {
- *     listeners.set(event, []);
- *   }
- *   listeners.get(event)!.push(listener);
- * }
- * ```
- */
-export declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
-/**
- * Checks if a value is an Error instance.
- *
- * Identifies instances of Error and its subclasses (TypeError, ReferenceError, etc.).
- * Essential for error handling and recovery strategies.
- *
- * @param value - The value to check
- * @returns true if value is an Error instance
- *
- * @example
- * ```typescript
- * isError(new Error("message"))           // true
- * isError(new TypeError("message"))       // true
- * isError(new ReferenceError("message"))  // true
- * isError(new Error())                    // true
- * isError(new CustomError())              // true (if extends Error)
- * isError({ message: "error" })           // false
- * isError("error string")                 // false
- * isError(null)                           // false
- * ```
- *
- * @usage
- * ```typescript
- * // Safe error handling
- * async function executeWithFallback(fn: () => Promise<void>) {
- *   try {
- *     await fn();
- *   } catch (error) {
- *     if (isError(error)) {
- *       console.error('Caught error:', error.message);
- *       console.error('Stack:', error.stack);
- *     } else {
- *       console.error('Unknown error type:', error);
- *     }
- *   }
- * }
- *
- * // Error type discrimination
- * function handleError(error: unknown): string {
- *   if (!isError(error)) {
- *     return 'Unknown error';
- *   }
- *
- *   if (error instanceof TypeError) {
- *     return 'Type error: ' + error.message;
- *   } else if (error instanceof RangeError) {
- *     return 'Range error: ' + error.message;
- *   } else {
- *     return 'Error: ' + error.message;
- *   }
- * }
- * ```
- */
-export declare function isError(value: unknown): value is Error;
-/**
- * Checks if a value is a Date instance.
- *
- * Useful for temporal data validation and date handling workflows.
- *
- * @param value - The value to check
- * @returns true if value is a Date instance
- *
- * @example
- * ```typescript
- * isDate(new Date())                      // true
- * isDate(new Date('2024-01-01'))         // true
- * isDate(Date.now())                      // false (returns number)
- * isDate("2024-01-01")                    // false
- * isDate({ toISOString: () => {} })      // false (duck typing doesn't work)
- * isDate(null)                            // false
- * ```
- *
- * @usage
- * ```typescript
- * // Validate API response dates
- * function parseResponse(data: unknown): { timestamp: Date } | null {
- *   if (!isObject(data)) return null;
- *
- *   const timestamp = (data as any).timestamp;
- *   if (isDate(timestamp)) {
- *     return { timestamp };
- *   }
- *
- *   // Try parsing string dates
- *   if (isString(timestamp)) {
- *     const parsed = new Date(timestamp);
- *     return isValidDate(parsed) ? { timestamp: parsed } : null;
- *   }
- *
- *   return null;
- * }
- *
- * // Helper to validate Date is not invalid (NaN)
- * function isValidDate(date: Date): boolean {
- *   return isDate(date) && !isNaN(date.getTime());
- * }
- * ```
- */
-export declare function isDate(value: unknown): value is Date;
-/**
- * Checks if a value is a RegExp instance.
- *
- * Useful for pattern validation, regex-based routing, and configuration parsing.
- *
- * @param value - The value to check
- * @returns true if value is a RegExp instance
- *
- * @example
- * ```typescript
- * isRegExp(/test/)                        // true
- * isRegExp(new RegExp('test'))            // true
- * isRegExp(/test/gi)                      // true
- * isRegExp("/test/")                      // false (string)
- * isRegExp({ test: () => {} })            // false
- * isRegExp(null)                          // false
- * ```
- *
- * @usage
- * ```typescript
- * // Validate pattern matchers
- * function buildMatcher(pattern: unknown): (str: string) => boolean {
- *   if (isRegExp(pattern)) {
- *     return (str: string) => pattern.test(str);
- *   } else if (isString(pattern)) {
- *     const regex = new RegExp(pattern);
- *     return (str: string) => regex.test(str);
- *   } else {
- *     throw new TypeError('Pattern must be RegExp or string');
- *   }
- * }
- *
- * // Route matching with regex validation
- * interface Route {
- *   pattern: unknown;
- *   handler: (match: string) => void;
- * }
- *
- * function createRouter(routes: Route[]) {
- *   return {
- *     match(path: string) {
- *       for (const route of routes) {
- *         if (isRegExp(route.pattern)) {
- *           const matches = path.match(route.pattern);
- *           if (matches) {
- *             route.handler(path);
- *             return true;
- *           }
- *         }
- *       }
- *       return false;
- *     }
- *   };
- * }
- * ```
- */
-export declare function isRegExp(value: unknown): value is RegExp;
-/**
- * Checks if a value is null or undefined.
- *
- * Handy shortcut for checking nullish values. Use together with other guards
- * for optional property validation.
- *
- * @param value - The value to check
- * @returns true if value is null or undefined
- *
- * @example
- * ```typescript
- * isNullOrUndefined(null)                 // true
- * isNullOrUndefined(undefined)            // true
- * isNullOrUndefined(0)                    // false
- * isNullOrUndefined("")                   // false
- * isNullOrUndefined(false)                // false
- * ```
- *
- * @usage
- * ```typescript
- * // Optional property validation
- * interface User {
- *   id: number;
- *   email?: string;
- * }
- *
- * function validateUser(data: unknown): User | null {
- *   if (!isObject(data)) return null;
- *
- *   const { id, email } = data as any;
- *
- *   if (!isNumber(id)) return null;
- *   if (!isNullOrUndefined(email) && !isString(email)) {
- *     return null;
- *   }
- *
- *   return { id, email };
- * }
- *
- * // Provide defaults for undefined
- * function getWithDefault<T>(value: T | null | undefined, defaultValue: T): T {
- *   return isNullOrUndefined(value) ? defaultValue : value;
- * }
- * ```
- */
-export declare function isNullOrUndefined(value: unknown): value is null | undefined;
-/**
- * Checks if a value is not null or undefined (type guard for non-nullish).
- *
- * Useful in filter operations and optional chaining scenarios.
- *
- * @param value - The value to check
- * @returns true if value is not null or undefined
- *
- * @example
- * ```typescript
- * isDefined("text")                       // true
- * isDefined(0)                            // true
- * isDefined(false)                        // true
- * isDefined([])                           // true
- * isDefined(null)                         // false
- * isDefined(undefined)                    // false
- * ```
- *
- * @usage
- * ```typescript
- * // Filter nullish values from arrays
- * const values = [1, null, 2, undefined, 3];
- * const filtered = values.filter(isDefined);
- * // Result: [1, 2, 3]
- *
- * // Type narrowing in conditional
- * function process(value: string | null) {
- *   if (isDefined(value)) {
- *     // TypeScript knows value is string (never null)
- *     console.log(value.toUpperCase());
- *   }
- * }
- * ```
- */
-export declare function isDefined<T>(value: T | null | undefined): value is T;
-/**
- * Checks if an object has a specific property (type guard for discriminated unions).
- *
- * Enables property-based type narrowing for discriminated unions and polymorphic types.
- *
- * @param obj - The object to check
- * @param prop - The property name to look for
- * @returns true if object has the property
- *
- * @example
- * ```typescript
- * interface Success { success: true; data: string }
- * interface Error { error: true; message: string }
- * type Result = Success | Error;
- *
- * const result: Result = { success: true, data: "ok" };
- *
- * if (hasProperty(result, 'success')) {
- *   // TypeScript narrows to Success
- *   console.log(result.data);
- * }
- * ```
- *
- * @usage
- * ```typescript
- * // Discriminate union types
- * function handleResult(result: unknown) {
- *   if (isObject(result)) {
- *     if (hasProperty(result, 'error')) {
- *       console.error(result.error);
- *     } else if (hasProperty(result, 'data')) {
- *       console.log(result.data);
- *     }
- *   }
- * }
- * ```
- */
-export declare function hasProperty<T extends object, K extends PropertyKey>(obj: T, prop: K): obj is T & Record<K, unknown>;
-/**
- * Type guard for array elements of a specific type.
- *
- * Validates all array elements match a predicate function.
- *
- * @param arr - The array to check
- * @param guard - The type guard function for elements
- * @returns true if all elements pass the guard
- *
- * @example
- * ```typescript
- * const data = [1, 2, 3];
- * if (isArrayOf(data, isNumber)) {
- *   // TypeScript knows data is number[]
- *   const sum = data.reduce((a, b) => a + b, 0);
- * }
- * ```
- *
- * @usage
- * ```typescript
- * // Validate API response array
- * interface User { id: number; name: string }
- *
- * function isUser(obj: unknown): obj is User {
- *   return isObject(obj) &&
- *     isNumber((obj as any).id) &&
- *     isString((obj as any).name);
- * }
- *
- * function processUsers(data: unknown) {
- *   if (isArray(data) && isArrayOf(data, isUser)) {
- *     // TypeScript knows data is User[]
- *     data.forEach(user => {
- *       console.log(user.name);
- *     });
- *   }
- * }
- * ```
- */
-export declare function isArrayOf<T>(arr: unknown, guard: (value: unknown) => value is T): arr is T[];
-//# sourceMappingURL=type-guards.d.ts.map

package/dist/helpers/type-guards.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../app/helpers/type-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAQnH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EACjE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,GACN,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACpC,GAAG,IAAI,CAAC,EAAE,CAEZ"}