tywrap 0.2.0 → 0.2.1

package/dist/runtime/validators.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure validation functions for runtime value checking.
+ *
+ * These functions are used by BoundedContext and can also be used
+ * independently for validation in CLI tools, config loading, etc.
+ */
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Check if a value is a finite number (not NaN, not Infinity).
+ */
+export declare function isFiniteNumber(value: unknown): value is number;
+/**
+ * Check if a value is a positive finite number.
+ */
+export declare function isPositiveNumber(value: unknown): value is number;
+/**
+ * Check if a value is a non-negative finite number.
+ */
+export declare function isNonNegativeNumber(value: unknown): value is number;
+/**
+ * Check if a value is a non-empty string.
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Assert that a value is a finite number.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a finite number
+ */
+export declare function assertFiniteNumber(value: unknown, name: string): number;
+/**
+ * Assert that a value is a positive number (> 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a positive number
+ */
+export declare function assertPositive(value: unknown, name: string): number;
+/**
+ * Assert that a value is a non-negative number (>= 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a non-negative number
+ */
+export declare function assertNonNegative(value: unknown, name: string): number;
+/**
+ * Assert that a value is a string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a string
+ */
+export declare function assertString(value: unknown, name: string): string;
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a non-empty string
+ */
+export declare function assertNonEmptyString(value: unknown, name: string): string;
+/**
+ * Assert that a value is an array.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as an array
+ * @throws ValidationError if the value is not an array
+ */
+export declare function assertArray<T = unknown>(value: unknown, name: string): T[];
+/**
+ * Assert that a value is a plain object (not null, not array).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a Record
+ * @throws ValidationError if the value is not a plain object
+ */
+export declare function assertObject(value: unknown, name: string): Record<string, unknown>;
+/**
+ * Check if a value contains non-finite numbers (NaN, Infinity, -Infinity).
+ * Recursively checks arrays and objects.
+ *
+ * This is used to detect values that cannot be safely serialized to JSON,
+ * as JSON.stringify converts NaN/Infinity to null, which can cause
+ * silent data corruption.
+ *
+ * @param value - The value to check
+ * @returns True if the value contains NaN or Infinity anywhere
+ */
+export declare function containsSpecialFloat(value: unknown): boolean;
+/**
+ * Assert that a value does not contain non-finite numbers.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @throws ValidationError if the value contains NaN or Infinity
+ */
+export declare function assertNoSpecialFloats(value: unknown, name: string): void;
+/**
+ * Sanitize a string for use in a cache key filename.
+ * Removes or replaces characters that could cause path traversal or invalid filenames.
+ *
+ * @param value - The string to sanitize
+ * @returns A safe string for use in filenames
+ */
+export declare function sanitizeForFilename(value: string): string;
+/**
+ * Check if a string looks like a path traversal attempt.
+ *
+ * @param value - The string to check
+ * @returns True if the string contains path traversal patterns
+ */
+export declare function containsPathTraversal(value: string): boolean;
+//# sourceMappingURL=validators.d.ts.map

package/dist/runtime/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/runtime/validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CAK1E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW5D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAMxE;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/runtime/validators.js

@@ -0,0 +1,219 @@
+/**
+ * Pure validation functions for runtime value checking.
+ *
+ * These functions are used by BoundedContext and can also be used
+ * independently for validation in CLI tools, config loading, etc.
+ */
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a value is a finite number (not NaN, not Infinity).
+ */
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * Check if a value is a positive finite number.
+ */
+export function isPositiveNumber(value) {
+    return isFiniteNumber(value) && value > 0;
+}
+/**
+ * Check if a value is a non-negative finite number.
+ */
+export function isNonNegativeNumber(value) {
+    return isFiniteNumber(value) && value >= 0;
+}
+/**
+ * Check if a value is a non-empty string.
+ */
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ASSERTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Assert that a value is a finite number.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a finite number
+ */
+export function assertFiniteNumber(value, name) {
+    if (!isFiniteNumber(value)) {
+        const actual = typeof value === 'number' ? String(value) : typeof value;
+        throw new ValidationError(`${name} must be a finite number, got: ${actual}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a positive number (> 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a positive number
+ */
+export function assertPositive(value, name) {
+    const num = assertFiniteNumber(value, name);
+    if (num <= 0) {
+        throw new ValidationError(`${name} must be positive, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Assert that a value is a non-negative number (>= 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a non-negative number
+ */
+export function assertNonNegative(value, name) {
+    const num = assertFiniteNumber(value, name);
+    if (num < 0) {
+        throw new ValidationError(`${name} must be non-negative, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Assert that a value is a string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a string
+ */
+export function assertString(value, name) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(`${name} must be a string, got: ${typeof value}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a non-empty string
+ */
+export function assertNonEmptyString(value, name) {
+    const str = assertString(value, name);
+    if (str.length === 0) {
+        throw new ValidationError(`${name} must not be empty`);
+    }
+    return str;
+}
+/**
+ * Assert that a value is an array.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as an array
+ * @throws ValidationError if the value is not an array
+ */
+export function assertArray(value, name) {
+    if (!Array.isArray(value)) {
+        throw new ValidationError(`${name} must be an array, got: ${typeof value}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a plain object (not null, not array).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a Record
+ * @throws ValidationError if the value is not a plain object
+ */
+export function assertObject(value, name) {
+    if (!isPlainObject(value)) {
+        const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+        throw new ValidationError(`${name} must be an object, got: ${actual}`);
+    }
+    return value;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SPECIAL FLOAT DETECTION (for codec validation)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a value contains non-finite numbers (NaN, Infinity, -Infinity).
+ * Recursively checks arrays and objects.
+ *
+ * This is used to detect values that cannot be safely serialized to JSON,
+ * as JSON.stringify converts NaN/Infinity to null, which can cause
+ * silent data corruption.
+ *
+ * @param value - The value to check
+ * @returns True if the value contains NaN or Infinity anywhere
+ */
+export function containsSpecialFloat(value) {
+    if (typeof value === 'number') {
+        return !Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some(containsSpecialFloat);
+    }
+    if (isPlainObject(value)) {
+        return Object.values(value).some(containsSpecialFloat);
+    }
+    return false;
+}
+/**
+ * Assert that a value does not contain non-finite numbers.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @throws ValidationError if the value contains NaN or Infinity
+ */
+export function assertNoSpecialFloats(value, name) {
+    if (containsSpecialFloat(value)) {
+        throw new ValidationError(`${name} contains non-finite numbers (NaN or Infinity) which cannot be serialized to JSON`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// PATH VALIDATION (for CLI security)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Sanitize a string for use in a cache key filename.
+ * Removes or replaces characters that could cause path traversal or invalid filenames.
+ *
+ * @param value - The string to sanitize
+ * @returns A safe string for use in filenames
+ */
+export function sanitizeForFilename(value) {
+    // Replace path separators and traversal patterns
+    return value
+        .replace(/\.\./g, '__')
+        .replace(/[/\\:*?"<>|]/g, '_')
+        .replace(/\s+/g, '_');
+}
+/**
+ * Check if a string looks like a path traversal attempt.
+ *
+ * @param value - The string to check
+ * @returns True if the string contains path traversal patterns
+ */
+export function containsPathTraversal(value) {
+    return value.includes('..') || value.includes('/') || value.includes('\\');
+}
+//# sourceMappingURL=validators.js.map

package/dist/runtime/validators.js.map

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

package/dist/runtime/worker-pool.d.ts

@@ -0,0 +1,196 @@
+/**
+ * WorkerPool - Manages multiple Transport instances for concurrent request handling.
+ *
+ * Provides semaphore-based concurrency control with configurable limits per worker
+ * and a wait queue for callers when all workers are at capacity.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import { BoundedContext } from './bounded-context.js';
+import type { Transport } from './transport.js';
+/**
+ * Configuration options for the WorkerPool.
+ */
+export interface WorkerPoolOptions {
+    /** Factory function to create transports */
+    createTransport: () => Transport;
+    /** Maximum number of workers in the pool */
+    maxWorkers: number;
+    /** Minimum number of workers to pre-spawn during init. Default: 0 (lazy) */
+    minWorkers?: number;
+    /** Timeout for waiting in queue (ms). Default: 30000 */
+    queueTimeoutMs?: number;
+    /** Maximum concurrent requests per worker. Default: 1 */
+    maxConcurrentPerWorker?: number;
+    /**
+     * Callback invoked after each worker is created and initialized.
+     * Use this for per-worker warmup (e.g., importing modules, running setup).
+     */
+    onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+}
+/**
+ * A pooled worker with its transport and current in-flight request count.
+ */
+export interface PooledWorker {
+    /** The underlying transport instance */
+    transport: Transport;
+    /** Number of requests currently being processed by this worker */
+    inFlightCount: number;
+}
+/**
+ * Pool of Transport workers with semaphore-based concurrency control.
+ *
+ * Features:
+ * - Lazy worker creation (workers created on demand)
+ * - Configurable concurrency per worker
+ * - Wait queue with timeout for callers when pool is at capacity
+ * - Automatic cleanup of timers and workers on disposal
+ *
+ * @example
+ * ```typescript
+ * const pool = new WorkerPool({
+ *   createTransport: () => new ProcessIO({ pythonPath: 'python3' }),
+ *   maxWorkers: 4,
+ *   maxConcurrentPerWorker: 2,
+ *   queueTimeoutMs: 5000,
+ * });
+ *
+ * await pool.init();
+ *
+ * // Use withWorker for automatic acquire/release
+ * const result = await pool.withWorker(async (worker) => {
+ *   return worker.transport.send(message, timeout);
+ * });
+ *
+ * await pool.dispose();
+ * ```
+ */
+export declare class WorkerPool extends BoundedContext {
+    private readonly options;
+    private readonly workers;
+    private readonly waitQueue;
+    /** Tracks workers being created to prevent race condition in acquire() */
+    private pendingCreations;
+    /**
+     * Create a new WorkerPool.
+     *
+     * @param options - Pool configuration options
+     */
+    constructor(options: WorkerPoolOptions);
+    /**
+     * Initialize the pool.
+     *
+     * If minWorkers > 0, pre-spawns workers during initialization.
+     * Otherwise, workers are created lazily on demand.
+     */
+    protected doInit(): Promise<void>;
+    /**
+     * Dispose the pool and all workers.
+     *
+     * - Rejects all waiters in the queue
+     * - Disposes all transport instances
+     * - Clears internal state
+     */
+    protected doDispose(): Promise<void>;
+    /**
+     * Acquire a worker from the pool.
+     *
+     * This method:
+     * - Returns an available worker if one exists (inFlightCount < maxConcurrentPerWorker)
+     * - Creates a new worker if under the maxWorkers limit
+     * - Waits in queue if all workers are at capacity
+     *
+     * @returns Promise resolving to a pooled worker
+     * @throws BridgeTimeoutError if queue timeout expires
+     * @throws BridgeExecutionError if pool is disposed while waiting
+     */
+    acquire(): Promise<PooledWorker>;
+    /**
+     * Release a worker back to the pool.
+     *
+     * Decrements the worker's in-flight count and notifies any waiters
+     * that a worker may be available.
+     *
+     * @param worker - The worker to release
+     */
+    release(worker: PooledWorker): void;
+    /**
+     * Execute a function with an acquired worker, automatically releasing afterward.
+     *
+     * This is the recommended way to use the pool, as it ensures proper cleanup
+     * even if the function throws an error.
+     *
+     * @param fn - Async function to execute with the worker
+     * @returns Promise resolving to the function's return value
+     *
+     * @example
+     * ```typescript
+     * const result = await pool.withWorker(async (worker) => {
+     *   return worker.transport.send(message, timeout);
+     * });
+     * ```
+     */
+    withWorker<T>(fn: (worker: PooledWorker) => Promise<T>): Promise<T>;
+    /**
+     * Check if an error indicates the worker is dead and should be removed.
+     *
+     * Fatal errors include:
+     * - Process not running
+     * - Process exited unexpectedly
+     * - Pipe errors (EPIPE)
+     * - Connection reset errors (ECONNRESET)
+     */
+    private isFatalWorkerError;
+    /**
+     * Remove a worker from the pool.
+     *
+     * This is called when a worker is detected as dead (crashed, pipe error, etc.).
+     * The worker's transport is disposed in the background.
+     */
+    private removeWorker;
+    /**
+     * Current number of workers in the pool.
+     */
+    get workerCount(): number;
+    /**
+     * Number of callers waiting in the queue.
+     */
+    get queueLength(): number;
+    /**
+     * Total number of in-flight requests across all workers.
+     */
+    get totalInFlight(): number;
+    /**
+     * Find an available worker with capacity for another request.
+     */
+    private findAvailableWorker;
+    /**
+     * Create a new worker and add it to the pool.
+     *
+     * If onWorkerReady is configured, calls it after the transport is initialized.
+     * This is useful for per-worker warmup (importing modules, running setup).
+     */
+    private createWorker;
+    /**
+     * Wait in queue for a worker to become available.
+     */
+    private waitForWorker;
+    /**
+     * Not implemented - WorkerPool does not execute Python calls directly.
+     * Use the BridgeProtocol layer with a pooled worker's transport.
+     */
+    call<T = unknown>(_module: string, _functionName: string, _args: unknown[], _kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Not implemented - WorkerPool does not execute Python calls directly.
+     */
+    instantiate<T = unknown>(_module: string, _className: string, _args: unknown[], _kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Not implemented - WorkerPool does not execute Python calls directly.
+     */
+    callMethod<T = unknown>(_handle: string, _methodName: string, _args: unknown[], _kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Not implemented - WorkerPool does not execute Python calls directly.
+     */
+    disposeInstance(_handle: string): Promise<void>;
+}
+//# sourceMappingURL=worker-pool.d.ts.map

package/dist/runtime/worker-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.d.ts","sourceRoot":"","sources":["../../src/runtime/worker-pool.ts"],"names":[],"mappings":"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"}