indusagi-coding-agent 0.1.59 → 0.1.61

package/dist/helpers/type-guards.js

@@ -1,671 +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 function isPrimitive(value) {
-    const type = typeof value;
-    if (type === 'number') {
-        // Exclude Infinity and NaN - they represent error states
-        return isFinite(value);
-    }
-    return type === 'string' || type === 'boolean' ||
-        type === 'symbol' || type === 'bigint' || value === null || value === undefined;
-}
-/**
- * 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 function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value) &&
-        !(value instanceof Date) && !(value instanceof Map) &&
-        !(value instanceof Set) && !(value instanceof RegExp) &&
-        !(value instanceof Error);
-}
-/**
- * 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 function isArray(value) {
-    return Array.isArray(value);
-}
-/**
- * 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 function isString(value) {
-    return typeof value === '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 function isNumber(value) {
-    return typeof value === 'number' && isFinite(value);
-}
-/**
- * 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 function isBoolean(value) {
-    return typeof value === '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 function isFunction(value) {
-    return typeof value === 'function';
-}
-/**
- * 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 function isError(value) {
-    return value instanceof 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 function isDate(value) {
-    return value instanceof 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 function isRegExp(value) {
-    return value instanceof 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 function isNullOrUndefined(value) {
-    return value === null || value === 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 function isDefined(value) {
-    return value !== null && value !== undefined;
-}
-/**
- * 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 function hasProperty(obj, prop) {
-    return prop in obj;
-}
-/**
- * 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 function isArrayOf(arr, guard) {
-    return Array.isArray(arr) && arr.every(guard);
-}
-//# sourceMappingURL=type-guards.js.map

package/dist/helpers/type-guards.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../../app/helpers/type-guards.ts"],"names":[],"mappings":"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"}