tjs-lang 0.6.19 → 0.6.26

package/dist/src/lang/parser-types.d.ts

@@ -1,175 +0,0 @@
-/**
- * Parser types and interfaces
- *
- * Shared type definitions used across parser modules.
- */
-/** Parser options */
-export interface ParseOptions {
-    /** Filename for error messages */
-    filename?: string;
-    /** Enable colon shorthand syntax preprocessing */
-    colonShorthand?: boolean;
-    /**
-     * Target is the VM (AJS code).
-     * When true, skips == to Is() transformation since the VM handles == correctly.
-     */
-    vmTarget?: boolean;
-}
-/**
- * A WASM block extracted from source
- *
- * Simple form (body is both WASM source and JS fallback):
- *   wasm {
- *     for (let i = 0; i < arr.length; i++) { arr[i] *= 2 }
- *   }
- *
- * With explicit fallback (when WASM and JS need different code):
- *   wasm {
- *     // WASM-optimized path
- *   } fallback {
- *     // JS fallback using different approach
- *   }
- *
- * Variables are captured from scope automatically.
- */
-export interface WasmBlock {
-    /** Unique ID for this block */
-    id: string;
-    /** The body (JS subset that compiles to WASM, also used as fallback) */
-    body: string;
-    /** Explicit fallback body (only if different from body) */
-    fallback?: string;
-    /** Variables captured from enclosing scope (auto-detected) */
-    captures: string[];
-    /** Start position in original source */
-    start: number;
-    /** End position in original source */
-    end: number;
-}
-/**
- * A test block extracted from source
- *
- * Syntax:
- *   test { body }
- *   test 'description' { body }
- *
- * Tests run at transpile time and are stripped from output.
- */
-export interface TestBlock {
-    /** Optional description */
-    description?: string;
-    /** The test body code */
-    body: string;
-    /** Start position in original source */
-    start: number;
-    /** End position in original source */
-    end: number;
-    /** Source line number (1-indexed) */
-    line?: number;
-}
-/**
- * Preprocess options
- */
-export interface PreprocessOptions {
-    /** Skip test execution (tests still stripped from output) */
-    dangerouslySkipTests?: boolean;
-    /**
-     * Skip == to Is() transformation.
-     * Set to true for AJS code that runs in the VM, which already handles == correctly.
-     * Default: false (transform == to Is() for TJS code running in regular JS)
-     */
-    vmTarget?: boolean;
-}
-/**
- * Tokenizer state for tracking context during source transformation
- */
-export type TokenizerState = 'normal' | 'single-string' | 'double-string' | 'template-string' | 'line-comment' | 'block-comment' | 'regex';
-/**
- * Structural context for tracking where we are in the code
- * This enables proper handling of class methods vs function calls
- */
-export type StructuralContext = 'top-level' | 'class-body' | 'function-body' | 'block';
-export interface ContextFrame {
-    type: StructuralContext;
-    braceDepth: number;
-}
-/**
- * Unified paren expression transformer using state machine tokenizer
- *
- * Model: opening paren can be ( or (? or (!, closing can be ) or )->type or )-?type or )-!type
- *
- * This unifies handling of:
- * - Function declaration params: function foo(x: type) -> returnType { }
- * - Arrow function params: (x: type) => expr
- * - Safe/unsafe markers: function foo(?) or function foo(!)
- * - Return type annotations: ) -> type or ) -? type or ) -! type
- *
- * @param source The source code to transform
- * @param ctx Context for tracking required params, safe/unsafe functions, etc.
- * @returns Transformed source and extracted metadata
- */
-/** TJS mode flags for opt-in language improvements */
-export interface TjsModes {
-    /** TjsEquals: == and != use structural equality */
-    tjsEquals: boolean;
-    /** TjsClass: classes callable without new, explicit new is banned */
-    tjsClass: boolean;
-    /** TjsDate: Date is banned, use Timestamp/LegalDate */
-    tjsDate: boolean;
-    /** TjsNoeval: eval() and new Function() are banned */
-    tjsNoeval: boolean;
-    /** TjsStandard: newlines as statement terminators (prevents ASI footguns) */
-    tjsStandard: boolean;
-    /** TjsSafeEval: include Eval/SafeFunction in runtime for dynamic code execution */
-    tjsSafeEval: boolean;
-}
-/**
- * Extension info for a single extend block
- */
-export interface ExtensionInfo {
-    /** The type name being extended (e.g., 'String', 'Array', 'MyClass') */
-    typeName: string;
-    /** Method names defined in this extend block */
-    methods: string[];
-}
-/**
- * Transform `extend TypeName { ... }` blocks into `const __ext_TypeName = { ... }` objects
- * and runtime registration calls.
- *
- * extend String {
- *   capitalize() { return this[0].toUpperCase() + this.slice(1) }
- * }
- *
- * becomes:
- *
- * const __ext_String = {
- *   capitalize: function() { return this[0].toUpperCase() + this.slice(1) }
- * }
- * if (__tjs?.registerExtension) {
- *   __tjs.registerExtension('String', 'capitalize', __ext_String.capitalize)
- * }
- */
-export interface PolyVariant {
-    /** Index (1-based) for renaming */
-    index: number;
-    /** Start position in source */
-    start: number;
-    /** End position in source (after closing brace) */
-    end: number;
-    /** The full function source text */
-    text: string;
-    /** Whether it was exported */
-    exported: boolean;
-    /** Whether it was async */
-    isAsync: boolean;
-    /** Parsed parameter info: [name, defaultValue][] */
-    params: {
-        name: string;
-        defaultValue: string;
-        required: boolean;
-    }[];
-}
-/**
- * Infer a type-check expression from a parameter's default value string.
- * Returns a condition that checks if an argument matches this param's type.
- */

package/dist/src/lang/parser.d.ts

@@ -1,56 +0,0 @@
-/**
- * TJS Parser — Orchestration Layer
- *
- * This module contains the main entry points: preprocess() and parse().
- * Transform functions are in parser-transforms.ts, param processing in parser-params.ts.
- */
-import type { Program, FunctionDeclaration } from 'acorn';
-export type { ParseOptions, WasmBlock, TestBlock, PreprocessOptions, TjsModes, } from './parser-types';
-import type { ParseOptions, WasmBlock, TestBlock, PreprocessOptions, TjsModes } from './parser-types';
-export { transformExtensionCalls } from './parser-transforms';
-export declare function preprocess(source: string, options?: PreprocessOptions): {
-    source: string;
-    returnType?: string;
-    returnSafety?: 'safe' | 'unsafe';
-    moduleSafety?: 'none' | 'inputs' | 'all';
-    tjsModes: TjsModes;
-    originalSource: string;
-    requiredParams: Set<string>;
-    unsafeFunctions: Set<string>;
-    safeFunctions: Set<string>;
-    wasmBlocks: WasmBlock[];
-    tests: TestBlock[];
-    testErrors: string[];
-    polymorphicNames: Set<string>;
-    extensions: Map<string, Set<string>>;
-};
-/**
- * Parse source code into an Acorn AST
- */
-export declare function parse(source: string, options?: ParseOptions): {
-    ast: Program;
-    returnType?: string;
-    returnSafety?: 'safe' | 'unsafe';
-    moduleSafety?: 'none' | 'inputs' | 'all';
-    originalSource: string;
-    requiredParams: Set<string>;
-    unsafeFunctions: Set<string>;
-    safeFunctions: Set<string>;
-    wasmBlocks: WasmBlock[];
-    tests: TestBlock[];
-    testErrors: string[];
-};
-/**
- * Validate that the source contains exactly one function declaration
- */
-export declare function validateSingleFunction(ast: Program, filename?: string): FunctionDeclaration;
-/**
- * Extract TDoc comment from before a function
- *
- * TJS doc comments use /\*# ... \*\/ syntax and preserve full markdown content.
- * Legacy JSDoc (/\*\* ... \*\/) is supported as a fallback.
- */
-export declare function extractTDoc(source: string, func: FunctionDeclaration): {
-    description?: string;
-    params: Record<string, string>;
-};

package/dist/src/lang/runtime.d.ts

@@ -1,454 +0,0 @@
-/**
- * TJS Runtime
- *
- * Monadic type checking at runtime:
- * - Functions validate inputs against __tjs metadata
- * - If any input is an error, pass it through (no work)
- * - Type mismatches return error objects
- * - Errors propagate through call chains
- *
- * This runtime is attached to globalThis.__tjs and shared across modules.
- */
-import { validate } from 'tosijs-schema';
-import { Type, isRuntimeType, Union, Generic, Enum, FunctionPredicate, Nullable, Optional, TArray, TString, TNumber, TBoolean, TInteger, TPositiveInt, TNonEmptyString, TEmail, TUrl, TUuid, Timestamp, LegalDate, TPair, TRecord, isValidUrl, isValidTimestamp, isValidLegalDate } from '../types/Type';
-export { Type, isRuntimeType, Union, Generic, Enum, FunctionPredicate, Nullable, Optional, TArray, TString, TNumber, TBoolean, TInteger, TPositiveInt, TNonEmptyString, TEmail, TUrl, TUuid, Timestamp, LegalDate, TPair, TRecord, isValidUrl, isValidTimestamp, isValidLegalDate, };
-export declare const TJS_VERSION: string;
-/**
- * Well-known symbol for custom equality.
- *
- * Any object can implement `[tjsEquals](other)` to control how `==` / `Is()`
- * compares it. Useful for Proxies that should delegate equality to their target.
- *
- * Priority: tjsEquals symbol → .Equals method → structural comparison
- */
-export declare const tjsEquals: unique symbol;
-/**
- * Compare two version strings
- * Returns: -1 if a < b, 0 if equal, 1 if a > b
- */
-export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
-/**
- * Check if two versions are compatible (same major version)
- */
-export declare function versionsCompatible(a: string, b: string): boolean;
-/**
- * MonadicError - Internal error type for monadic error propagation
- *
- * This extends Error so:
- * 1. It's a real Error with proper stack traces
- * 2. User code can't accidentally process it as data (unlike { $error: true })
- * 3. It flows through function calls via instanceof checks
- *
- * NOT exported to user code - they just see Error instances.
- */
-export declare class MonadicError extends Error {
-    /** Path where the error occurred, e.g., "src/file.ts:42:greet.name" */
-    readonly path: string;
-    /** Expected type */
-    readonly expected?: string;
-    /** Actual type received */
-    readonly actual?: string;
-    /** TJS call stack (only in debug mode) - shows source locations */
-    readonly callStack?: string[];
-    constructor(message: string, path: string, expected?: string, actual?: string, callStack?: string[]);
-}
-/**
- * Create a type error for inline validation
- *
- * Called ONLY when a type check fails - no overhead on happy path.
- * Returns a MonadicError that propagates through the call chain.
- * In debug mode, captures the TJS call stack with source locations.
- *
- * @param path - Location of the error, e.g., "src/file.ts:42:greet.name"
- * @param expected - Expected type, e.g., "string"
- * @param value - The actual value that failed the check
- */
-export declare function typeError(path: string, expected: string, value: unknown): MonadicError;
-/**
- * Check if a value is a MonadicError (for internal use)
- */
-export declare function isMonadicError(value: unknown): value is MonadicError;
-/**
- * Error marker - identifies TJS error objects
- * @deprecated Use MonadicError instead. This interface is kept for backward compatibility.
- */
-export interface TJSError {
-    $error: true;
-    message: string;
-    /** Failure location - e.g., "greet.name" */
-    path?: string;
-    /** Call stack in debug mode - e.g., ["main", "processUser", "greet.name"] */
-    stack?: string[];
-    expected?: string;
-    actual?: string;
-    cause?: Error | TJSError;
-    /** Source location for error reporting */
-    loc?: {
-        start: number;
-        end: number;
-    };
-    /** Multiple errors (when composing parameter errors) */
-    errors?: TJSError[];
-}
-/**
- * Safety levels for runtime validation
- * - 'none': No validation unless explicitly forced with (?) or -?
- * - 'inputs': Validate inputs only (default) - outputs only with explicit -> or -?
- * - 'all': Validate both inputs and outputs unless explicitly skipped with (!) or -!
- */
-export type SafetyLevel = 'none' | 'inputs' | 'all';
-/**
- * Runtime configuration
- */
-export interface TJSConfig {
-    /** Enable debug mode - captures call stacks in errors */
-    debug?: boolean;
-    /** Safety level for validation (default: 'inputs') */
-    safety?: SafetyLevel;
-    /** Require explicit return types (error if -> not specified) */
-    requireReturnTypes?: boolean;
-    /** Maximum call stack size to prevent memory issues (default: 100) */
-    maxStackSize?: number;
-}
-/**
- * Enter unsafe mode - disables validation for all wrapped function calls
- * Can be nested (uses depth counter)
- */
-export declare function enterUnsafe(): void;
-/**
- * Exit unsafe mode - re-enables validation when depth returns to 0
- */
-export declare function exitUnsafe(): void;
-/**
- * Check if currently in unsafe mode
- */
-export declare function isUnsafeMode(): boolean;
-/**
- * Configure TJS runtime
- */
-export declare function configure(options: TJSConfig): void;
-/**
- * Get current configuration
- */
-export declare function getConfig(): TJSConfig;
-/**
- * Push a function onto the call stack (debug mode only)
- * Respects maxStackSize to prevent unbounded memory growth
- */
-export declare function pushStack(name: string): void;
-/**
- * Pop a function from the call stack (debug mode only)
- */
-export declare function popStack(): void;
-/**
- * Get current call stack snapshot
- */
-export declare function getStack(): string[];
-/**
- * Reset runtime state to defaults
- *
- * Resets: config, callStack, unsafeDepth
- * Use this in test teardown to prevent state leaking between tests.
- */
-export declare function resetRuntime(): void;
-/**
- * Structural equality - the == that works
- *
- * Rules:
- * 1. If left has [tjsEquals], call left[tjsEquals](right)
- * 2. If right has [tjsEquals], call right[tjsEquals](left)
- * 3. If left has .Equals, call left.Equals(right)
- * 4. If right has .Equals, call right.Equals(left)
- * 5. Arrays/objects: recursive structural comparison
- * 6. Primitives: strict equality (no coercion)
- *
- * Usage: `a Is b` transforms to `Is(a, b)`
- */
-export declare function Is(a: unknown, b: unknown): boolean;
-/**
- * Structural inequality - the != that works
- *
- * Usage: `a IsNot b` transforms to `IsNot(a, b)`
- */
-export declare function IsNot(a: unknown, b: unknown): boolean;
-/**
- * Check if a value is a TJS error
- */
-export declare function isError(value: unknown): value is TJSError;
-/**
- * Create a TJS error
- * In debug mode, captures the current call stack
- */
-export declare function error(message: string, details?: Partial<Omit<TJSError, '$error' | 'message'>>): TJSError;
-/**
- * Compose multiple errors into a single error
- * Used when multiple parameters have errors
- */
-export declare function composeErrors(errors: TJSError[], funcName?: string): TJSError;
-/**
- * Get the type of a value
- *
- * Enhanced typeof that handles:
- * - null (returns 'null' not 'object')
- * - undefined (returns 'undefined')
- * - arrays (returns 'array' not 'object')
- * - native/platform types (returns constructor name for objects)
- *
- * For objects, returns the constructor name which enables pragmatic
- * native type checking (e.g., 'HTMLElement', 'Buffer', 'Event')
- */
-export declare function typeOf(value: unknown): string;
-/**
- * Check if a value is an instance of a native/platform type by constructor name
- *
- * This enables pragmatic native type checking without shipping type definitions:
- * - isNativeType(el, 'HTMLElement') - DOM element check
- * - isNativeType(buf, 'Buffer') - Node.js Buffer check
- * - isNativeType(evt, 'Event') - DOM Event check
- * - isNativeType(map, 'Map') - Map instance check
- *
- * @param value - The value to check
- * @param typeName - The constructor name to match (e.g., 'HTMLElement', 'Buffer')
- * @returns true if value's constructor.name matches or is in prototype chain
- */
-export declare function isNativeType(value: unknown, typeName: string): boolean;
-/**
- * Check if a value matches an expected type
- *
- * @param value - The value to check
- * @param expected - Either a string type name ('string', 'number', etc.)
- *                   or a RuntimeType instance with .check() method
- * @param path - Optional path for error messages
- */
-export declare function checkType(value: unknown, expected: string | {
-    check: (v: unknown) => boolean;
-    description: string;
-}, path?: string): TJSError | null;
-/** Type specifier - either a string name or a RuntimeType */
-type TypeSpec = string | {
-    check: (v: unknown) => boolean;
-    description: string;
-};
-/** Parameter metadata with optional location */
-interface ParamMeta {
-    type: TypeSpec;
-    required: boolean;
-    default?: unknown;
-    loc?: {
-        start: number;
-        end: number;
-    };
-}
-/**
- * Validate function arguments against __tjs metadata
- * Returns first error found, or null if all valid
- */
-export declare function validateArgs(args: Record<string, unknown>, meta: {
-    params: Record<string, ParamMeta>;
-}, funcName?: string): TJSError | null;
-/**
- * Function metadata with safety flags
- */
-export interface FunctionMeta {
-    params: Record<string, any>;
-    returns?: {
-        type: any;
-        safe?: boolean;
-        defaults?: Record<string, unknown>;
-    };
-    /** Function marked with (!) - never validate inputs */
-    unsafe?: boolean;
-    /** Function marked with (?) - always validate inputs */
-    safe?: boolean;
-    /** Return type marked with -! - never validate output */
-    unsafeReturn?: boolean;
-    /** Return type marked with -? - always validate output */
-    safeReturn?: boolean;
-    /** Explicit function name for stack tracking (used when fn.name is empty) */
-    name?: string;
-    /** Polymorphic dispatcher — skip wrapping, dispatch handles validation */
-    polymorphic?: boolean;
-}
-/**
- * Wrap a function with monadic type checking
- *
- * @param fn - The original function
- * @param meta - The __tjs metadata
- * @returns Wrapped function that validates inputs and propagates errors
- */
-export declare function wrap<T extends (...args: any[]) => any>(fn: T, meta: FunctionMeta): T;
-/**
- * Wrap a class to make it callable without `new`
- *
- * In TJS, classes can be instantiated without the `new` keyword:
- *   const obj = MyClass(args)  // equivalent to new MyClass(args)
- *
- * This eliminates a common source of errors where developers forget `new`.
- * Using explicit `new` still works but should be flagged by the linter.
- */
-export declare function wrapClass<T extends new (...args: any[]) => any>(cls: T): T & ((...args: ConstructorParameters<T>) => InstanceType<T>);
-/**
- * Create an isolated TJS runtime instance
- *
- * Each call returns a fresh runtime with its own:
- * - config (debug, safety, etc.)
- * - callStack
- * - unsafeDepth
- *
- * The new instance inherits the current global config at creation time,
- * but subsequent changes are isolated.
- *
- * Use this to prevent state leaking between transpiled modules.
- */
-export declare function createRuntime(): {
-    version: string;
-    MonadicError: typeof MonadicError;
-    typeError: (path: string, expected: string, value: unknown) => MonadicError;
-    isMonadicError: typeof isMonadicError;
-    isError: typeof isError;
-    error: (message: string, details?: Partial<Omit<TJSError, "$error" | "message">>) => TJSError;
-    composeErrors: typeof composeErrors;
-    typeOf: typeof typeOf;
-    isNativeType: typeof isNativeType;
-    checkType: typeof checkType;
-    validateArgs: typeof validateArgs;
-    wrap: typeof wrap;
-    wrapClass: typeof wrapClass;
-    compareVersions: typeof compareVersions;
-    versionsCompatible: typeof versionsCompatible;
-    configure: (options: TJSConfig) => void;
-    getConfig: () => TJSConfig;
-    pushStack: (name: string) => void;
-    popStack: () => void;
-    getStack: () => string[];
-    resetRuntime: () => void;
-    enterUnsafe: () => void;
-    exitUnsafe: () => void;
-    isUnsafeMode: () => boolean;
-    validate: typeof validate;
-    infer: (value: any) => import("tosijs-schema").Base<any>;
-    Type: typeof Type;
-    isRuntimeType: typeof isRuntimeType;
-    Union: typeof Union;
-    Generic: typeof Generic;
-    Enum: typeof Enum;
-    FunctionPredicate: typeof FunctionPredicate;
-    Nullable: typeof Nullable;
-    Optional: typeof Optional;
-    TArray: typeof TArray;
-    TString: import("..").RuntimeType<string>;
-    TNumber: import("..").RuntimeType<number>;
-    TBoolean: import("..").RuntimeType<boolean>;
-    TInteger: import("..").RuntimeType<number>;
-    TPositiveInt: import("..").RuntimeType<number>;
-    TNonEmptyString: import("..").RuntimeType<string>;
-    TEmail: import("..").RuntimeType<string>;
-    TUrl: import("..").RuntimeType<string>;
-    TUuid: import("..").RuntimeType<string>;
-    TPair: import("..").GenericType<string[]>;
-    TRecord: import("..").GenericType<string[]>;
-    Is: typeof Is;
-    IsNot: typeof IsNot;
-    tjsEquals: symbol;
-    registerExtension: (typeName: string, methodName: string, fn: (...args: any[]) => any) => void;
-    resolveExtension: (value: unknown, methodName: string) => ((...args: any[]) => any) | undefined;
-};
-/** Type for runtime instances */
-export type TJSRuntime = ReturnType<typeof createRuntime>;
-/**
- * TJS Runtime object - attached to globalThis.__tjs
- *
- * NOTE: This is a shared global instance. For isolated execution,
- * use createRuntime() instead.
- */
-export declare const runtime: {
-    version: string;
-    MonadicError: typeof MonadicError;
-    typeError: typeof typeError;
-    isMonadicError: typeof isMonadicError;
-    isError: typeof isError;
-    error: typeof error;
-    composeErrors: typeof composeErrors;
-    typeOf: typeof typeOf;
-    isNativeType: typeof isNativeType;
-    checkType: typeof checkType;
-    validateArgs: typeof validateArgs;
-    wrap: typeof wrap;
-    wrapClass: typeof wrapClass;
-    compareVersions: typeof compareVersions;
-    versionsCompatible: typeof versionsCompatible;
-    configure: typeof configure;
-    getConfig: typeof getConfig;
-    pushStack: typeof pushStack;
-    popStack: typeof popStack;
-    getStack: typeof getStack;
-    resetRuntime: typeof resetRuntime;
-    enterUnsafe: typeof enterUnsafe;
-    exitUnsafe: typeof exitUnsafe;
-    isUnsafeMode: typeof isUnsafeMode;
-    createRuntime: typeof createRuntime;
-    validate: typeof validate;
-    infer: (value: any) => import("tosijs-schema").Base<any>;
-    Type: typeof Type;
-    isRuntimeType: typeof isRuntimeType;
-    Union: typeof Union;
-    Generic: typeof Generic;
-    Enum: typeof Enum;
-    FunctionPredicate: typeof FunctionPredicate;
-    Nullable: typeof Nullable;
-    Optional: typeof Optional;
-    TArray: typeof TArray;
-    TString: import("..").RuntimeType<string>;
-    TNumber: import("..").RuntimeType<number>;
-    TBoolean: import("..").RuntimeType<boolean>;
-    TInteger: import("..").RuntimeType<number>;
-    TPositiveInt: import("..").RuntimeType<number>;
-    TNonEmptyString: import("..").RuntimeType<string>;
-    TEmail: import("..").RuntimeType<string>;
-    TUrl: import("..").RuntimeType<string>;
-    TUuid: import("..").RuntimeType<string>;
-    Timestamp: import("..").RuntimeType<string>;
-    LegalDate: import("..").RuntimeType<string>;
-    TPair: import("..").GenericType<string[]>;
-    TRecord: import("..").GenericType<string[]>;
-    Is: typeof Is;
-    IsNot: typeof IsNot;
-};
-/**
- * Install runtime globally (idempotent, version-checked)
- *
- * Version handling:
- * - Same version: reuse existing (no warning)
- * - Compatible (same major): reuse existing, log info
- * - Incompatible (different major): warn, use newer version
- */
-export declare function installRuntime(): typeof runtime;
-/**
- * Generate runtime wrapper code for emitted JS
- * Skips wrapping for unsafe functions (marked with !)
- */
-export declare function emitRuntimeWrapper(funcName: string): string;
-/**
- * Generate class wrapper code for emitted JS
- * Makes classes callable without `new` keyword
- * Emits standalone JS - no runtime dependency
- */
-export declare function emitClassWrapper(className: string): string;
-/**
- * Questions/Notes:
- *
- * Q1: Should wrap() be automatic or opt-in?
- *     Current: Must be explicitly wrapped
- *     Could: Auto-wrap all functions with __tjs metadata
- *
- * Q2: Performance overhead of validation?
- *     Need benchmarks comparing wrapped vs unwrapped
- *     Could have 'production' mode that skips validation
- *
- * Q3: Async function handling?
- *     wrap() should detect async and handle Promise returns
- *
- * Q4: Deep object validation?
- *     Currently only checks top-level type
- *     Could recursively validate object shapes
- */