tywrap 0.2.0 → 0.3.0

package/src/utils/cache.ts

@@ -147,18 +147,72 @@ export class IntelligentCache {
 
     // Add prefix
     hash.update(prefix);
+    hash.update('\0');
 
     // Add inputs
     for (const input of inputs) {
+      // Why: disambiguate types so "1" and 1 don't collide, and keep input boundaries so
+      // ["a", "bc"] doesn't collide with ["ab", "c"].
+      if (input === undefined) {
+        hash.update('undef:');
+        hash.update('\0');
+        continue;
+      }
+      if (input === null) {
+        hash.update('null:');
+        hash.update('\0');
+        continue;
+      }
       if (typeof input === 'string') {
+        hash.update('str:');
         hash.update(input);
-      } else if (Buffer.isBuffer(input)) {
+        hash.update('\0');
+        continue;
+      }
+      if (typeof input === 'number') {
+        hash.update('num:');
+        hash.update(String(input));
+        hash.update('\0');
+        continue;
+      }
+      if (typeof input === 'boolean') {
+        hash.update('bool:');
+        hash.update(input ? '1' : '0');
+        hash.update('\0');
+        continue;
+      }
+      if (typeof input === 'bigint') {
+        hash.update('bigint:');
+        hash.update(input.toString());
+        hash.update('\0');
+        continue;
+      }
+      if (Buffer.isBuffer(input)) {
+        hash.update('buf:');
         hash.update(input);
-      } else if (input !== undefined && input !== null) {
-        hash.update(JSON.stringify(input));
-      } else {
-        hash.update('null');
+        hash.update('\0');
+        continue;
+      }
+
+      if (typeof input === 'symbol') {
+        hash.update('sym:');
+        hash.update(input.toString());
+        hash.update('\0');
+        continue;
+      }
+
+      hash.update('json:');
+      let json: string;
+      try {
+        json =
+          JSON.stringify(input, (_key, value) =>
+            typeof value === 'symbol' ? value.toString() : value
+          ) ?? 'undefined';
+      } catch {
+        json = String(input);
       }
+      hash.update(json);
+      hash.update('\0');
     }
 
     return hash.digest('hex').substring(0, 16); // Use first 16 chars for readability

package/src/utils/codec.ts

@@ -243,6 +243,97 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   );
 }
 
+/**
+ * Convert a typed array (Int32Array, Float64Array, BigInt64Array, etc.) to a plain JS array.
+ *
+ * Why: Arrow's column.toArray() returns typed arrays, but we need plain arrays for
+ * JSON-compatible output and proper nested array reshaping.
+ *
+ * @param arr - Typed array or plain array
+ * @returns Plain JavaScript array with values converted (BigInt → Number where safe)
+ */
+function typedArrayToPlain(arr: unknown): unknown[] {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  // Handle typed arrays (Int32Array, Float64Array, BigInt64Array, etc.)
+  if (ArrayBuffer.isView(arr) && 'length' in arr) {
+    const values = Array.from(arr as unknown as ArrayLike<unknown>);
+    return values.map(value => {
+      // Convert BigInt to Number if within safe integer range
+      if (typeof value === 'bigint') {
+        if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+          return Number(value);
+        }
+      }
+      return value; // Keep BigInt when too large (or preserve non-BigInt values)
+    });
+  }
+  // Fallback: check if iterable before converting
+  if (arr !== null && arr !== undefined && typeof arr === 'object' && Symbol.iterator in arr) {
+    return Array.from(arr as Iterable<unknown>);
+  }
+  // Non-iterable: return empty array (shouldn't happen with valid Arrow data)
+  return [];
+}
+
+/**
+ * Extract values from an Arrow table as a plain JavaScript array.
+ *
+ * Why: Arrow decoding returns Table objects, not raw arrays. We need to extract
+ * the column values and convert any typed arrays to plain arrays.
+ */
+function extractArrowValues(data: unknown): unknown[] | null {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  // Arrow table - extract values from first column
+  const table = data as ArrowTable & { getChildAt?: (i: number) => { toArray?: () => unknown } };
+  if (typeof table.getChildAt === 'function') {
+    const column = table.getChildAt(0);
+    if (column && typeof column.toArray === 'function') {
+      return typedArrayToPlain(column.toArray());
+    }
+  }
+  return null;
+}
+
+/**
+ * Reshape a flat array into a multi-dimensional nested array.
+ *
+ * Why: PyArrow's pa.array() only handles 1D arrays, so we flatten multi-dimensional
+ * arrays before Arrow encoding and reshape after decoding. This maintains Arrow's
+ * binary efficiency while working with current arrow-js (which doesn't yet support
+ * FixedShapeTensorArray). See: https://github.com/apache/arrow-js/issues/115
+ *
+ * @param flat - Flat array of values (must be a plain array, not typed array)
+ * @param shape - Target shape, e.g., [2, 3] for a 2x3 matrix
+ * @returns Nested array with the specified shape
+ */
+function reshapeArray(flat: unknown[], shape: readonly number[]): unknown {
+  if (shape.length === 0) {
+    return flat[0];
+  }
+  if (shape.length === 1) {
+    return flat;
+  }
+
+  const first = shape[0];
+  if (first === undefined) {
+    return [];
+  }
+  const rest = shape.slice(1);
+  const chunkSize = rest.reduce((a, b) => a * b, 1);
+  const result: unknown[] = [];
+
+  for (let i = 0; i < first; i++) {
+    const chunk = flat.slice(i * chunkSize, (i + 1) * chunkSize);
+    result.push(reshapeArray(chunk, rest));
+  }
+
+  return result;
+}
+
 // Why: decoding needs to reject incompatible envelopes before we attempt to interpret payloads.
 const CODEC_VERSION = 1;
 
@@ -326,13 +417,43 @@ function decodeEnvelopeCore<T>(
 
   if (marker === 'ndarray') {
     const encoding = (value as { encoding?: unknown }).encoding;
+    const shapeValue = (value as { shape?: unknown }).shape;
+    const shape = isNumberArray(shapeValue) ? shapeValue : undefined;
+
     if (encoding === 'arrow') {
       const b64 = (value as { b64?: unknown }).b64;
       if (typeof b64 !== 'string') {
         throw new Error('Invalid ndarray envelope: missing b64');
       }
       const bytes = fromBase64(b64);
-      return decodeArrow(bytes);
+      const decoded = decodeArrow(bytes);
+
+      // Extract values from Arrow table and reshape if needed
+      // Arrow only handles 1D arrays, so we flatten on encode and reshape here
+      // Reshape for: scalars (shape.length === 0) and multi-dim (shape.length > 1)
+      // Skip reshape for: 1D arrays (shape.length === 1) - return as-is
+      if (isPromiseLike(decoded)) {
+        return decoded.then(data => {
+          const values = extractArrowValues(data);
+          if (!values) {
+            return data; // Fallback: return raw data if extraction fails
+          }
+          // Reshape scalars and multi-dimensional arrays, but not 1D
+          if (shape && shape.length !== 1) {
+            return reshapeArray(values, shape);
+          }
+          return values;
+        });
+      }
+      const values = extractArrowValues(decoded);
+      if (!values) {
+        return decoded; // Fallback: return raw data if extraction fails
+      }
+      // Reshape scalars and multi-dimensional arrays, but not 1D
+      if (shape && shape.length !== 1) {
+        return reshapeArray(values, shape);
+      }
+      return values;
     }
     if (encoding === 'json') {
       if (!('data' in (value as object))) {

package/src/utils/ir-cache.ts

@@ -0,0 +1,51 @@
+import { hashUtils } from './runtime.js';
+
+export interface IrCacheKeyObject {
+  module: string;
+  moduleVersion: string | null;
+  irVersion: string;
+  pythonImportPath?: readonly string[];
+  runtime: {
+    pythonPath: string;
+    virtualEnv: string | null;
+  };
+  output: {
+    format: 'esm' | 'cjs' | 'both';
+    declaration: boolean;
+    sourceMap: boolean;
+  };
+  performance: {
+    caching: boolean;
+    compression: 'auto' | 'gzip' | 'brotli' | 'none';
+  };
+  typeHints: 'strict' | 'loose' | 'ignore';
+}
+
+function stableSortForJson(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(v => stableSortForJson(v));
+  }
+  if (value && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      out[key] = stableSortForJson(obj[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Compute a stable, safe filename for on-disk IR caching.
+ *
+ * Why: cache filenames must not include user-controlled module names to avoid
+ * path traversal or invalid filename characters (especially on Windows).
+ */
+export async function computeIrCacheFilename(keyObject: IrCacheKeyObject): Promise<string> {
+  // Canonicalize to avoid cache misses when key object property insertion order differs.
+  const normalized = JSON.stringify(stableSortForJson(keyObject));
+  const digest = await hashUtils.sha256Hex(normalized);
+  // Hash-only filename: safe ASCII, no separators, stable length.
+  return `ir_${digest.slice(0, 32)}.json`;
+}

package/src/utils/parallel-processor.ts

@@ -127,10 +127,12 @@ export class ParallelProcessor extends EventEmitter {
   private workers = new Map<string, Worker>();
   private workerStats = new Map<string, WorkerStats>();
   private taskQueue: ParallelTask[] = [];
+  private queueInterval?: NodeJS.Timeout;
   private activeTasks = new Map<string, ParallelTask>();
   private pendingResults = new Map<
     string,
     {
+      workerId: string;
       resolve: (result: ParallelResult<unknown>) => void;
       reject: (error: Error) => void;
       timeout?: NodeJS.Timeout;
@@ -329,12 +331,16 @@ export class ParallelProcessor extends EventEmitter {
       attempts++;
 
       try {
-        const worker = this.selectOptimalWorker();
-        if (!worker) {
+        const selected = this.selectOptimalWorker();
+        if (!selected) {
           throw new Error('No available workers');
         }
 
-        const result = await this.sendTaskToWorker<Data, Result>(worker, task);
+        const result = await this.sendTaskToWorker<Data, Result>(
+          selected.workerId,
+          selected.worker,
+          task
+        );
 
         // Cache successful results
         if (this.options.enableCaching && result.success) {
@@ -366,10 +372,16 @@ export class ParallelProcessor extends EventEmitter {
   /**
    * Select optimal worker using load balancing strategy
    */
-  private selectOptimalWorker(): Worker | null {
-    const availableWorkers = Array.from(this.workers.values()).filter(
-      worker => worker.threadId > 0
-    );
+  private selectOptimalWorker(): { workerId: string; worker: Worker } | null {
+    const availableWorkers = Array.from(this.workers.entries())
+      .map(([workerId, worker]) => ({ workerId, worker }))
+      .filter(({ workerId, worker }) => {
+        if (worker.threadId <= 0) {
+          return false;
+        }
+        const stats = this.workerStats.get(workerId);
+        return stats?.isActive !== false;
+      });
 
     if (availableWorkers.length === 0) {
       return null;
@@ -384,37 +396,37 @@ export class ParallelProcessor extends EventEmitter {
 
       case 'least-loaded': {
         // Find worker with least active tasks
-        const workerLoads = availableWorkers.map(w => {
-          const workerId = this.getWorkerId(w);
+        const workerLoads = availableWorkers.map(({ workerId, worker }) => {
           const stats = this.workerStats.get(workerId);
-          return { worker: w, load: stats?.tasksCompleted ?? 0 };
+          return { workerId, worker, load: stats?.tasksCompleted ?? 0 };
         });
 
         workerLoads.sort((a, b) => a.load - b.load);
-        return workerLoads[0]?.worker ?? null;
+        const first = workerLoads[0];
+        return first ? { workerId: first.workerId, worker: first.worker } : null;
       }
 
       case 'weighted': {
         // Weight by average task completion time
-        const workerWeights = availableWorkers.map(w => {
-          const workerId = this.getWorkerId(w);
+        const workerWeights = availableWorkers.map(({ workerId, worker }) => {
           const stats = this.workerStats.get(workerId);
           const avgTime = stats?.averageTime ?? 1000;
-          return { worker: w, weight: 1 / avgTime };
+          return { workerId, worker, weight: 1 / avgTime };
         });
 
         // Weighted random selection
         const totalWeight = workerWeights.reduce((sum, w) => sum + w.weight, 0);
         let random = Math.random() * totalWeight;
 
-        for (const { worker: candidate, weight } of workerWeights) {
+        for (const { workerId, worker: candidate, weight } of workerWeights) {
           random -= weight;
           if (random <= 0) {
-            return candidate;
+            return { workerId, worker: candidate };
           }
         }
 
-        return workerWeights[0]?.worker ?? null;
+        const fallback = workerWeights[0];
+        return fallback ? { workerId: fallback.workerId, worker: fallback.worker } : null;
       }
 
       default:
@@ -426,17 +438,29 @@ export class ParallelProcessor extends EventEmitter {
    * Send task to specific worker
    */
   private async sendTaskToWorker<Data, Result>(
+    workerId: string,
     worker: Worker,
     task: ParallelTask<Data>
   ): Promise<ParallelResult<Result>> {
     return new Promise((resolve, reject) => {
+      if (this.disposed) {
+        reject(new Error('Processor has been disposed'));
+        return;
+      }
+
       const timeoutMs = task.timeout ?? this.options.taskTimeout;
       const timeout = setTimeout(() => {
+        const pending = this.pendingResults.get(task.id);
+        if (!pending) {
+          return;
+        }
         this.pendingResults.delete(task.id);
-        reject(new Error(`Task ${task.id} timed out after ${timeoutMs}ms`));
+        this.activeTasks.delete(task.id);
+        pending.reject(new Error(`Task ${task.id} timed out after ${timeoutMs}ms`));
       }, timeoutMs);
 
       this.pendingResults.set(task.id, {
+        workerId,
         resolve: resolve as unknown as (result: ParallelResult<unknown>) => void,
         reject,
         timeout,
@@ -444,10 +468,17 @@ export class ParallelProcessor extends EventEmitter {
 
       this.activeTasks.set(task.id, task);
 
-      worker.postMessage({
-        type: 'task',
-        task,
-      });
+      try {
+        worker.postMessage({
+          type: 'task',
+          task,
+        });
+      } catch (error: unknown) {
+        this.pendingResults.delete(task.id);
+        this.activeTasks.delete(task.id);
+        clearTimeout(timeout);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
     });
   }
 
@@ -472,8 +503,9 @@ export class ParallelProcessor extends EventEmitter {
 
     // Setup worker error handling
     worker.on('error', error => {
-      log.error('Worker error', { workerId, error: String(error) });
-      this.handleWorkerError(workerId, error);
+      const workerError = error instanceof Error ? error : new Error(String(error));
+      log.error('Worker error', { workerId, error: String(workerError) });
+      this.handleWorkerError(workerId, workerError);
     });
 
     // Setup worker exit handling
@@ -554,15 +586,25 @@ export class ParallelProcessor extends EventEmitter {
       stats.isActive = false;
     }
 
-    // Reject pending tasks for this worker
+    // Reject only tasks owned by this worker.
+    const ownedTasks: string[] = [];
     for (const [taskId, pending] of this.pendingResults) {
-      const task = this.activeTasks.get(taskId);
-      if (task) {
-        pending.reject(new Error(`Worker ${workerId} error: ${error.message}`));
-        this.pendingResults.delete(taskId);
-        this.activeTasks.delete(taskId);
+      if (pending.workerId === workerId) {
+        ownedTasks.push(taskId);
       }
     }
+    for (const taskId of ownedTasks) {
+      const pending = this.pendingResults.get(taskId);
+      if (!pending) {
+        continue;
+      }
+      if (pending.timeout) {
+        clearTimeout(pending.timeout);
+      }
+      pending.reject(new Error(`Worker ${workerId} error: ${error.message}`));
+      this.pendingResults.delete(taskId);
+      this.activeTasks.delete(taskId);
+    }
 
     this.emit('worker_error', workerId, error);
   }
@@ -578,6 +620,26 @@ export class ParallelProcessor extends EventEmitter {
       stats.isActive = false;
     }
 
+    // Reject any tasks that were in-flight on this worker.
+    const ownedTasks: string[] = [];
+    for (const [taskId, pending] of this.pendingResults) {
+      if (pending.workerId === workerId) {
+        ownedTasks.push(taskId);
+      }
+    }
+    for (const taskId of ownedTasks) {
+      const pending = this.pendingResults.get(taskId);
+      if (!pending) {
+        continue;
+      }
+      if (pending.timeout) {
+        clearTimeout(pending.timeout);
+      }
+      pending.reject(new Error(`Worker ${workerId} exited with code ${code}`));
+      this.pendingResults.delete(taskId);
+      this.activeTasks.delete(taskId);
+    }
+
     // Respawn worker if not disposing
     if (!this.disposed && this.workers.size < this.options.maxWorkers) {
       this.spawnWorker(`${workerId}_respawn_${Date.now()}`).catch(error => {
@@ -593,7 +655,10 @@ export class ParallelProcessor extends EventEmitter {
    */
   private processQueue(): void {
     // Simple queue processing - could be enhanced with priority scheduling
-    setInterval(() => {
+    if (this.queueInterval) {
+      return;
+    }
+    this.queueInterval = setInterval(() => {
       if (this.taskQueue.length > 0 && this.workers.size > 0) {
         const task = this.taskQueue.shift();
         if (task) {
@@ -603,6 +668,8 @@ export class ParallelProcessor extends EventEmitter {
         }
       }
     }, 100);
+    // Don't keep the event loop alive just for an idle queue pump.
+    this.queueInterval.unref?.();
   }
 
   /**
@@ -645,15 +712,6 @@ export class ParallelProcessor extends EventEmitter {
     return chunks;
   }
 
-  private getWorkerId(worker: Worker): string {
-    for (const [id, w] of this.workers) {
-      if (w === worker) {
-        return id;
-      }
-    }
-    return 'unknown';
-  }
-
   private sleep(ms: number): Promise<void> {
     return new Promise(resolve => setTimeout(resolve, ms));
   }
@@ -670,6 +728,22 @@ export class ParallelProcessor extends EventEmitter {
 
     this.debugLog('🛑 Disposing parallel processor...');
 
+    if (this.queueInterval) {
+      clearInterval(this.queueInterval);
+      this.queueInterval = undefined;
+    }
+
+    // Reject any pending results immediately so callers don't hang.
+    const disposedError = new Error('Processor has been disposed');
+    for (const pending of this.pendingResults.values()) {
+      if (pending.timeout) {
+        clearTimeout(pending.timeout);
+      }
+      pending.reject(disposedError);
+    }
+    this.pendingResults.clear();
+    this.activeTasks.clear();
+
     // Terminate all workers
     const terminationPromises = Array.from(this.workers.values()).map(worker => {
       return new Promise<void>(resolve => {
@@ -683,7 +757,11 @@ export class ParallelProcessor extends EventEmitter {
           resolve();
         });
 
-        worker.postMessage({ type: 'shutdown' });
+        try {
+          worker.postMessage({ type: 'shutdown' });
+        } catch {
+          // Ignore: worker may already be dead.
+        }
       });
     });
 
@@ -693,8 +771,6 @@ export class ParallelProcessor extends EventEmitter {
     this.workers.clear();
     this.workerStats.clear();
     this.taskQueue.length = 0;
-    this.activeTasks.clear();
-    this.pendingResults.clear();
 
     this.removeAllListeners();