@nanocollective/nanocoder/dist/utils/type-helpers.d.ts

A local-first CLI coding agent that brings the power of agentic coding tools like Claude Code and Gemini CLI to local models or controlled APIs like OpenRouter

/**
 * Type-safe helper utilities for handling non-string content
 *
 * This module provides type guards and conversion functions that:
 * 1. Accept unknown types (string, object, array, null, undefined)
 * 2. Convert to appropriate types for processing
 * 3. Preserve types in memory (critical for ToolCall.arguments)
 * 4. Provide safe fallbacks for edge cases
 *
 * TYPE PRESERVATION STRATEGY
 * ===========================
 *
 * "Preserving types" means:
 * 1. When receiving LLM responses (which can be ANY type):
 *    - We accept unknown types (string, object, array, null, undefined)
 *    - We convert to string ONLY for PARSING OPERATIONS
 *    - We preserve the original type in the tool call structure
 *
 * 2. When storing ToolCall.arguments:
 *    - MUST preserve as Record<string, unknown> (object type)
 *    - NOT convert to string
 *    - Enables direct property access without JSON.parse
 *
 * 3. When displaying/writing to disk:
 *    - Convert to string for display/storage operations
 *    - Use JSON.stringify for objects/arrays
 *    - Use String() for primitives
 *
 * The confusion comes from mixing up:
 * - "Preserve types in memory" (CRITICAL: ToolCall.arguments stays as object)
 * - "Convert to string for processing" (NECESSARY: Parser expects strings)
 */
/**
 * Type guard to check if value is a string
 *
 * @param value - Value to check
 * @returns True if value is a string, false otherwise
 */
export declare function isString(value: unknown): value is string;
/**
 * Type guard to check if value is a non-null object
 *
 * @param value - Value to check
 * @returns True if value is a non-null object, false otherwise
 */
export declare function isObject(value: unknown): value is Record<string, unknown>;
/**
 * Type guard to check if value is an array
 *
 * @param value - Value to check
 * @returns True if value is an array, false otherwise
 */
export declare function isArray(value: unknown): value is unknown[];
/**
 * Type guard to check if value is a plain object (not null, not array, not instance)
 *
 * @param value - Value to check
 * @returns True if value is a plain object, false otherwise
 */
export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
/**
 * Type guard to check if value is a valid function
 *
 * @param value - Value to check
 * @returns True if value is a function, false otherwise
 */
export declare function isFunction(value: unknown): value is Function;
/**
 * Type guard to check if value is a valid number
 *
 * @param value - Value to check
 * @returns True if value is a number, false otherwise
 */
export declare function isNumber(value: unknown): value is number;
/**
 * Type guard to check if value is a valid boolean
 *
 * @param value - Value to check
 * @returns True if value is a boolean, false otherwise
 */
export declare function isBoolean(value: unknown): value is boolean;
/**
 * Type guard to check if value is a valid null value
 *
 * @param value - Value to check
 * @returns True if value is null, false otherwise
 */
export declare function isNull(value: unknown): value is null;
/**
 * Type guard to check if value is undefined
 *
 * @param value - Value to check
 * @returns True if value is undefined, false otherwise
 */
export declare function isUndefined(value: unknown): value is undefined;
/**
 * Ensures value is a string for display/storage operations
 *
 * This function is used for:
 * 1. DISPLAY OPERATIONS - where we need to display content
 * 2. STORAGE OPERATIONS - where we write to disk
 *
 * For display/storage, we convert to string.
 *
 * @param value - Value to convert (unknown type)
 * @returns String representation of the value
 *
 * @example
 * ```typescript
 * // ToolCall.arguments is an object in memory
 * const toolCall = {
 *   function: {
 *     name: 'write_file',
 *     arguments: {path: "/tmp/test.txt", content: "hello"}
 *   }
 * };
 *
 * // For storage, convert to string
 * const contentStr = ensureString(toolCall.function.arguments);
 * // contentStr = '{"path": "/tmp/test.txt", "content": "hello"}'
 *
 * await writeFile(path, contentStr, 'utf-8');
 * ```
 */
export declare function ensureString(value: unknown): string;
/**
 * Checks if value is empty
 *
 * @param value - Value to check
 * @returns True if value is empty, false otherwise
 */
export declare function isEmpty(value: unknown): boolean;
/**
 * Checks if value is non-empty (opposite of isEmpty)
 *
 * @param value - Value to check
 * @returns True if value is non-empty, false otherwise
 */
export declare function isNotEmpty(value: unknown): boolean;
//# sourceMappingURL=type-helpers.d.ts.map