alepha 0.13.0 → 0.13.2

package/dist/thread/index.cjs

@@ -1,350 +0,0 @@
-let alepha = require("alepha");
-let node_os = require("node:os");
-let node_worker_threads = require("node:worker_threads");
-let alepha_logger = require("alepha/logger");
-
-//#region src/thread/descriptors/$thread.ts
-/**
-* Creates a worker thread descriptor for offloading CPU-intensive tasks to separate threads.
-*
-* This descriptor enables you to run JavaScript code in Node.js worker threads, allowing you to
-* leverage multiple CPU cores and avoid blocking the main event loop. It provides a pool-based
-* approach with intelligent thread reuse and automatic lifecycle management.
-*
-* **Key Features**
-*
-* - **Thread Pool Management**: Automatically manages a pool of worker threads with configurable limits
-* - **Thread Reuse**: Reuses existing threads to avoid expensive initialization overhead
-* - **Idle Cleanup**: Automatically terminates unused threads after a configurable timeout
-* - **Type-Safe Communication**: Optional TypeBox schema validation for data passed to threads
-* - **CPU-Aware Defaults**: Pool size defaults to CPU count × 2 for optimal performance
-* - **Error Handling**: Proper error propagation and thread cleanup on failures
-*
-* **Use Cases**
-*
-* Perfect for CPU-intensive tasks that would otherwise block the main thread:
-* - Image/video processing
-* - Data transformation and analysis
-* - Cryptographic operations
-* - Heavy computations and algorithms
-* - Background data processing
-*
-* @example
-* **Basic thread usage:**
-* ```ts
-* import { $thread } from "alepha/thread";
-*
-* class DataProcessor {
-*   heavyComputation = $thread({
-*     name: "compute",
-*     handler: async () => {
-*       // This runs in a separate worker thread
-*       let result = 0;
-*       for (let i = 0; i < 1000000; i++) {
-*         result += Math.sqrt(i);
-*       }
-*       return { result, timestamp: Date.now() };
-*     }
-*   });
-*
-*   async processData() {
-*     // Execute in worker thread without blocking main thread
-*     const result = await this.heavyComputation.execute();
-*     console.log(`Computation result: ${result.result}`);
-*   }
-* }
-* ```
-*
-* @example
-* **Configured thread pool with custom settings:**
-* ```ts
-* class ImageProcessor {
-*   imageProcessor = $thread({
-*     name: "image-processing",
-*     maxPoolSize: 4,        // Limit to 4 concurrent threads
-*     idleTimeout: 30000,    // Clean up idle threads after 30 seconds
-*     handler: async () => {
-*       // CPU-intensive image processing logic
-*       return await processImageData();
-*     }
-*   });
-* }
-* ```
-*
-* @example
-* **Thread with data validation:**
-* ```ts
-* import { t } from "alepha";
-*
-* class CryptoService {
-*   encrypt = $thread({
-*     name: "encryption",
-*     handler: async () => {
-*       // Perform encryption operations
-*       return await encryptData();
-*     }
-*   });
-*
-*   async encryptSensitiveData(data: { text: string; key: string }) {
-*     // Validate input data before sending to thread
-*     const schema = t.object({
-*       text: t.text(),
-*       key: t.text()
-*     });
-*
-*     return await this.encrypt.execute(data, schema);
-*   }
-* }
-* ```
-*
-* @example
-* **Parallel processing with multiple threads:**
-* ```ts
-* class BatchProcessor {
-*   processor = $thread({
-*     name: "batch-worker",
-*     maxPoolSize: 8,  // Allow up to 8 concurrent workers
-*     handler: async () => {
-*       return await processBatchItem();
-*     }
-*   });
-*
-*   async processBatch(items: any[]) {
-*     // Process multiple items in parallel across different threads
-*     const promises = items.map(() => this.processor.execute());
-*     const results = await Promise.all(promises);
-*     return results;
-*   }
-* }
-* ```
-*/
-const $thread = (options) => {
-	return (0, alepha.createDescriptor)(ThreadDescriptor, options);
-};
-var ThreadDescriptor = class ThreadDescriptor extends alepha.Descriptor {
-	script = process.argv[1];
-	static globalPool = /* @__PURE__ */ new Map();
-	get name() {
-		return this.options.name || this.config.propertyKey;
-	}
-	get maxPoolSize() {
-		return this.options.maxPoolSize || (0, node_os.cpus)().length * 2;
-	}
-	get idleTimeout() {
-		return this.options.idleTimeout || 6e4;
-	}
-	getPool() {
-		if (!ThreadDescriptor.globalPool.has(this.name)) ThreadDescriptor.globalPool.set(this.name, new ThreadPool(this.name, this.maxPoolSize, this.idleTimeout, this.script));
-		return ThreadDescriptor.globalPool.get(this.name);
-	}
-	async execute(data, schema) {
-		if (schema && data) try {
-			alepha.TypeBoxValue.Decode(schema, data);
-		} catch (error) {
-			throw new Error(`Invalid data: ${error instanceof Error ? error.message : error}`);
-		}
-		return await this.getPool().execute(data);
-	}
-	async create() {
-		await this.getPool().warmUp();
-	}
-	async terminate() {
-		await this.getPool().terminate();
-		ThreadDescriptor.globalPool.delete(this.name);
-	}
-};
-$thread[alepha.KIND] = ThreadDescriptor;
-var ThreadPool = class {
-	instances = [];
-	queue = [];
-	idleTimer;
-	constructor(name, maxPoolSize, idleTimeout, script) {
-		this.name = name;
-		this.maxPoolSize = maxPoolSize;
-		this.idleTimeout = idleTimeout;
-		this.script = script;
-	}
-	async warmUp() {
-		if (this.instances.length === 0) await this.createInstance();
-	}
-	async createInstance() {
-		const { port1, port2 } = new node_worker_threads.MessageChannel();
-		const worker = new node_worker_threads.Worker(this.script, {
-			env: {
-				...process.env,
-				ALEPHA_WORKER: this.name,
-				APP_NAME: "WORKER"
-			},
-			workerData: { port: port2 },
-			transferList: [port2]
-		});
-		const instance = {
-			worker,
-			port: port1,
-			busy: false,
-			lastUsed: Date.now(),
-			pendingMessages: /* @__PURE__ */ new Map()
-		};
-		instance.port.on("message", (message) => {
-			if (message.type === "response" || message.type === "error") {
-				const pending = instance.pendingMessages.get(message.id);
-				if (pending) {
-					instance.pendingMessages.delete(message.id);
-					instance.busy = false;
-					instance.lastUsed = Date.now();
-					if (message.type === "error") pending.reject(new Error(message.error));
-					else pending.resolve(message.data);
-					this.processQueue();
-				}
-			}
-		});
-		await new Promise((resolve, reject) => {
-			const timeout = setTimeout(() => reject(/* @__PURE__ */ new Error("Thread initialization timeout")), 5e3);
-			worker.once("online", () => {
-				clearTimeout(timeout);
-				resolve();
-			});
-			worker.once("error", (error) => {
-				clearTimeout(timeout);
-				reject(error);
-			});
-		});
-		this.instances.push(instance);
-		this.resetIdleTimer();
-		return instance;
-	}
-	async execute(data) {
-		return new Promise((resolve, reject) => {
-			this.queue.push({
-				data,
-				resolve,
-				reject
-			});
-			this.processQueue();
-		});
-	}
-	async processQueue() {
-		if (this.queue.length === 0) return;
-		let instance = this.instances.find((i) => !i.busy);
-		if (!instance && this.instances.length < this.maxPoolSize) try {
-			instance = await this.createInstance();
-		} catch (error) {
-			const { reject: reject$1 } = this.queue.shift();
-			reject$1(error instanceof Error ? error : /* @__PURE__ */ new Error("Failed to create thread instance"));
-			return;
-		}
-		if (!instance) return;
-		const { data, resolve, reject } = this.queue.shift();
-		const messageId = `${Date.now()}-${Math.random()}`;
-		instance.busy = true;
-		instance.pendingMessages.set(messageId, {
-			resolve,
-			reject
-		});
-		const message = {
-			id: messageId,
-			type: "execute",
-			data
-		};
-		instance.port.postMessage(message);
-	}
-	resetIdleTimer() {
-		if (this.idleTimer) clearTimeout(this.idleTimer);
-		this.idleTimer = setTimeout(() => {
-			this.cleanupIdleInstances();
-		}, this.idleTimeout);
-	}
-	cleanupIdleInstances() {
-		const now = Date.now();
-		const instancesToRemove = this.instances.filter((instance) => !instance.busy && now - instance.lastUsed > this.idleTimeout);
-		for (const instance of instancesToRemove) {
-			const index = this.instances.indexOf(instance);
-			if (index > -1) {
-				this.instances.splice(index, 1);
-				instance.port.close();
-				instance.worker.terminate();
-			}
-		}
-		if (this.instances.length > 0) this.resetIdleTimer();
-	}
-	async terminate() {
-		if (this.idleTimer) clearTimeout(this.idleTimer);
-		await Promise.all(this.instances.map(async (instance) => {
-			instance.port.close();
-			await instance.worker.terminate();
-		}));
-		this.instances = [];
-		this.queue = [];
-	}
-};
-
-//#endregion
-//#region src/thread/providers/ThreadProvider.ts
-var ThreadProvider = class {
-	log = (0, alepha_logger.$logger)();
-	env = (0, alepha.$env)(alepha.t.object({ ALEPHA_WORKER: alepha.t.optional(alepha.t.text()) }));
-	ready = (0, alepha.$hook)({
-		on: "ready",
-		handler: async (alepha$1) => {
-			const worker = this.env.ALEPHA_WORKER;
-			if (!worker) return;
-			const threadDescriptor = alepha$1.descriptors($thread).find((thread) => thread.name === worker);
-			if (!threadDescriptor) {
-				this.log.error(`Thread not found: ${worker}`);
-				return;
-			}
-			this.log.info(`Thread ready: ${threadDescriptor.name}`);
-			const communicationPort = node_worker_threads.workerData?.port || node_worker_threads.parentPort;
-			if (!communicationPort) {
-				this.log.error("No communication port available");
-				return;
-			}
-			communicationPort.on("message", async (message) => {
-				if (message.type === "execute") try {
-					this.log.debug(`Executing thread handler: ${threadDescriptor.name}`);
-					const result = await threadDescriptor.options.handler();
-					communicationPort.postMessage({
-						id: message.id,
-						type: "response",
-						data: result
-					});
-				} catch (error) {
-					this.log.error(`Thread execution error: ${error}`);
-					communicationPort.postMessage({
-						id: message.id,
-						type: "error",
-						error: error instanceof Error ? error.message : String(error)
-					});
-				}
-			});
-			communicationPort.postMessage({ type: "ready" });
-		}
-	});
-	static async cleanup() {
-		if (node_worker_threads.parentPort) node_worker_threads.parentPort.removeAllListeners();
-	}
-};
-
-//#endregion
-//#region src/thread/index.ts
-alepha.Alepha.prototype.isWorkerThread = function() {
-	return !!this.env.ALEPHA_WORKER;
-};
-/**
-* Simple interface for managing worker threads in Alepha.
-*
-* @see {@link $thread}
-* @module alepha.thread
-*/
-const AlephaThread = (0, alepha.$module)({
-	name: "alepha.thread",
-	descriptors: [$thread],
-	services: [ThreadProvider]
-});
-
-//#endregion
-exports.$thread = $thread;
-exports.AlephaThread = AlephaThread;
-exports.ThreadDescriptor = ThreadDescriptor;
-exports.ThreadProvider = ThreadProvider;
-//# sourceMappingURL=index.cjs.map

package/dist/thread/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":["Descriptor","KIND","name: string","maxPoolSize: number","idleTimeout: number","script: string","MessageChannel","Worker","instance: ThreadInstance","message: ThreadMessage","t","alepha","workerData","parentPort"],"sources":["../../src/thread/descriptors/$thread.ts","../../src/thread/providers/ThreadProvider.ts","../../src/thread/index.ts"],"sourcesContent":["import { cpus } from \"node:os\";\nimport { MessageChannel, type MessagePort, Worker } from \"node:worker_threads\";\nimport type { TSchema } from \"alepha\";\nimport { createDescriptor, Descriptor, KIND, TypeBoxValue } from \"alepha\";\n\n/**\n * Creates a worker thread descriptor for offloading CPU-intensive tasks to separate threads.\n *\n * This descriptor enables you to run JavaScript code in Node.js worker threads, allowing you to\n * leverage multiple CPU cores and avoid blocking the main event loop. It provides a pool-based\n * approach with intelligent thread reuse and automatic lifecycle management.\n *\n * **Key Features**\n *\n * - **Thread Pool Management**: Automatically manages a pool of worker threads with configurable limits\n * - **Thread Reuse**: Reuses existing threads to avoid expensive initialization overhead\n * - **Idle Cleanup**: Automatically terminates unused threads after a configurable timeout\n * - **Type-Safe Communication**: Optional TypeBox schema validation for data passed to threads\n * - **CPU-Aware Defaults**: Pool size defaults to CPU count × 2 for optimal performance\n * - **Error Handling**: Proper error propagation and thread cleanup on failures\n *\n * **Use Cases**\n *\n * Perfect for CPU-intensive tasks that would otherwise block the main thread:\n * - Image/video processing\n * - Data transformation and analysis\n * - Cryptographic operations\n * - Heavy computations and algorithms\n * - Background data processing\n *\n * @example\n * **Basic thread usage:**\n * ```ts\n * import { $thread } from \"alepha/thread\";\n *\n * class DataProcessor {\n *   heavyComputation = $thread({\n *     name: \"compute\",\n *     handler: async () => {\n *       // This runs in a separate worker thread\n *       let result = 0;\n *       for (let i = 0; i < 1000000; i++) {\n *         result += Math.sqrt(i);\n *       }\n *       return { result, timestamp: Date.now() };\n *     }\n *   });\n *\n *   async processData() {\n *     // Execute in worker thread without blocking main thread\n *     const result = await this.heavyComputation.execute();\n *     console.log(`Computation result: ${result.result}`);\n *   }\n * }\n * ```\n *\n * @example\n * **Configured thread pool with custom settings:**\n * ```ts\n * class ImageProcessor {\n *   imageProcessor = $thread({\n *     name: \"image-processing\",\n *     maxPoolSize: 4,        // Limit to 4 concurrent threads\n *     idleTimeout: 30000,    // Clean up idle threads after 30 seconds\n *     handler: async () => {\n *       // CPU-intensive image processing logic\n *       return await processImageData();\n *     }\n *   });\n * }\n * ```\n *\n * @example\n * **Thread with data validation:**\n * ```ts\n * import { t } from \"alepha\";\n *\n * class CryptoService {\n *   encrypt = $thread({\n *     name: \"encryption\",\n *     handler: async () => {\n *       // Perform encryption operations\n *       return await encryptData();\n *     }\n *   });\n *\n *   async encryptSensitiveData(data: { text: string; key: string }) {\n *     // Validate input data before sending to thread\n *     const schema = t.object({\n *       text: t.text(),\n *       key: t.text()\n *     });\n *\n *     return await this.encrypt.execute(data, schema);\n *   }\n * }\n * ```\n *\n * @example\n * **Parallel processing with multiple threads:**\n * ```ts\n * class BatchProcessor {\n *   processor = $thread({\n *     name: \"batch-worker\",\n *     maxPoolSize: 8,  // Allow up to 8 concurrent workers\n *     handler: async () => {\n *       return await processBatchItem();\n *     }\n *   });\n *\n *   async processBatch(items: any[]) {\n *     // Process multiple items in parallel across different threads\n *     const promises = items.map(() => this.processor.execute());\n *     const results = await Promise.all(promises);\n *     return results;\n *   }\n * }\n * ```\n */\nexport const $thread = (options: ThreadDescriptorOptions): ThreadDescriptor => {\n  return createDescriptor(ThreadDescriptor, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface ThreadDescriptorOptions {\n  /**\n   * Unique name for this thread worker.\n   *\n   * Used for:\n   * - Thread pool identification (threads with same name share the same pool)\n   * - Logging and debugging\n   * - Error messages and stack traces\n   *\n   * If not provided, defaults to the property key of the descriptor.\n   *\n   * @example \"image-processor\"\n   * @example \"crypto-worker\"\n   * @example \"data-analysis\"\n   */\n  name?: string;\n\n  /**\n   * The function to execute in the worker thread.\n   *\n   * This function:\n   * - Runs in a separate Node.js worker thread\n   * - Should contain the CPU-intensive logic\n   * - Can be async and return any serializable data\n   * - Has access to standard Node.js APIs and modules\n   * - Cannot directly access the main thread's memory or variables\n   *\n   * **Important**: The handler function is serialized and sent to the worker thread,\n   * so it cannot reference variables from the parent scope (closures won't work).\n   * All required data must be passed via the `execute()` method.\n   *\n   * @example\n   * ```ts\n   * handler: async () => {\n   *   // CPU-intensive work here\n   *   const result = performComplexCalculation();\n   *   return { result, completed: Date.now() };\n   * }\n   * ```\n   */\n  handler: () => any | Promise<any>;\n\n  /**\n   * Maximum number of worker threads in the pool.\n   *\n   * Controls how many threads can run concurrently for this named thread worker.\n   * When all threads are busy, additional `execute()` calls will queue until a thread becomes available.\n   *\n   * **Default**: `cpus().length * 2` (number of CPU cores × 2)\n   *\n   * **Guidelines**:\n   * - For CPU-bound tasks: Set to number of CPU cores\n   * - For I/O-bound tasks in workers: Can be higher (2x CPU cores)\n   * - For memory-intensive tasks: Set lower to avoid memory pressure\n   * - For short-lived tasks: Can be higher for better throughput\n   *\n   * @default cpus().length * 2\n   * @example 4    // Limit to 4 concurrent threads\n   * @example 1    // Single worker thread (sequential processing)\n   * @example 16   // High concurrency for lightweight tasks\n   */\n  maxPoolSize?: number;\n\n  /**\n   * Time in milliseconds before idle worker threads are terminated.\n   *\n   * When a worker thread has been idle (not executing any tasks) for this duration,\n   * it will be automatically terminated to free up system resources. New threads\n   * will be created as needed when new tasks are submitted.\n   *\n   * **Default**: 60000 (60 seconds)\n   *\n   * **Considerations**:\n   * - Shorter timeouts: Save memory but increase thread creation overhead\n   * - Longer timeouts: Keep threads ready but consume more memory\n   * - Very short timeouts may cause constant thread creation/destruction\n   *\n   * @default 60000\n   * @example 30000   // 30 seconds\n   * @example 120000  // 2 minutes\n   * @example 5000    // 5 seconds (for very memory-constrained environments)\n   */\n  idleTimeout?: number;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ThreadDescriptor extends Descriptor<ThreadDescriptorOptions> {\n  protected readonly script = process.argv[1];\n  static readonly globalPool = new Map<string, ThreadPool>();\n\n  public get name(): string {\n    return this.options.name || this.config.propertyKey;\n  }\n\n  public get maxPoolSize(): number {\n    return this.options.maxPoolSize || cpus().length * 2;\n  }\n\n  public get idleTimeout(): number {\n    return this.options.idleTimeout || 60000; // 1 minute default\n  }\n\n  private getPool(): ThreadPool {\n    if (!ThreadDescriptor.globalPool.has(this.name)) {\n      ThreadDescriptor.globalPool.set(\n        this.name,\n        new ThreadPool(\n          this.name,\n          this.maxPoolSize,\n          this.idleTimeout,\n          this.script,\n        ),\n      );\n    }\n    return ThreadDescriptor.globalPool.get(this.name)!;\n  }\n\n  public async execute<T = any>(data?: any, schema?: TSchema): Promise<T> {\n    if (schema && data) {\n      try {\n        TypeBoxValue.Decode(schema, data);\n      } catch (error) {\n        throw new Error(\n          `Invalid data: ${error instanceof Error ? error.message : error}`,\n        );\n      }\n    }\n\n    const pool = this.getPool();\n    return await pool.execute<T>(data);\n  }\n\n  public async create(): Promise<void> {\n    const pool = this.getPool();\n    await pool.warmUp();\n  }\n\n  public async terminate(): Promise<void> {\n    const pool = this.getPool();\n    await pool.terminate();\n    ThreadDescriptor.globalPool.delete(this.name);\n  }\n}\n\n$thread[KIND] = ThreadDescriptor;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ninterface ThreadMessage<T = any> {\n  id: string;\n  type: \"execute\" | \"response\" | \"error\";\n  data?: T;\n  error?: string;\n}\n\ninterface ThreadInstance {\n  worker: Worker;\n  port: MessagePort;\n  busy: boolean;\n  lastUsed: number;\n  pendingMessages: Map<\n    string,\n    { resolve: (value: any) => void; reject: (error: Error) => void }\n  >;\n}\n\nclass ThreadPool {\n  private instances: ThreadInstance[] = [];\n  private queue: Array<{\n    data: any;\n    resolve: (value: any) => void;\n    reject: (error: Error) => void;\n  }> = [];\n  private idleTimer?: NodeJS.Timeout;\n\n  constructor(\n    private readonly name: string,\n    private readonly maxPoolSize: number,\n    private readonly idleTimeout: number,\n    private readonly script: string,\n  ) {}\n\n  async warmUp(): Promise<void> {\n    if (this.instances.length === 0) {\n      await this.createInstance();\n    }\n  }\n\n  private async createInstance(): Promise<ThreadInstance> {\n    const { port1, port2 } = new MessageChannel();\n\n    const worker = new Worker(this.script, {\n      env: {\n        ...process.env,\n        ALEPHA_WORKER: this.name,\n        APP_NAME: \"WORKER\",\n      },\n      workerData: { port: port2 },\n      transferList: [port2],\n    });\n\n    const instance: ThreadInstance = {\n      worker,\n      port: port1,\n      busy: false,\n      lastUsed: Date.now(),\n      pendingMessages: new Map(),\n    };\n\n    instance.port.on(\"message\", (message: ThreadMessage) => {\n      if (message.type === \"response\" || message.type === \"error\") {\n        const pending = instance.pendingMessages.get(message.id);\n        if (pending) {\n          instance.pendingMessages.delete(message.id);\n          instance.busy = false;\n          instance.lastUsed = Date.now();\n\n          if (message.type === \"error\") {\n            pending.reject(new Error(message.error));\n          } else {\n            pending.resolve(message.data);\n          }\n\n          this.processQueue();\n        }\n      }\n    });\n\n    await new Promise<void>((resolve, reject) => {\n      const timeout = setTimeout(\n        () => reject(new Error(\"Thread initialization timeout\")),\n        5000,\n      );\n\n      worker.once(\"online\", () => {\n        clearTimeout(timeout);\n        resolve();\n      });\n\n      worker.once(\"error\", (error) => {\n        clearTimeout(timeout);\n        reject(error);\n      });\n    });\n\n    this.instances.push(instance);\n    this.resetIdleTimer();\n\n    return instance;\n  }\n\n  async execute<T = any>(data?: any): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      this.queue.push({ data, resolve, reject });\n      this.processQueue();\n    });\n  }\n\n  private async processQueue(): Promise<void> {\n    if (this.queue.length === 0) {\n      return;\n    }\n\n    let instance = this.instances.find((i) => !i.busy);\n\n    if (!instance && this.instances.length < this.maxPoolSize) {\n      try {\n        instance = await this.createInstance();\n      } catch (error) {\n        const { reject } = this.queue.shift()!;\n        reject(\n          error instanceof Error\n            ? error\n            : new Error(\"Failed to create thread instance\"),\n        );\n        return;\n      }\n    }\n\n    if (!instance) {\n      return; // Wait for an instance to become available\n    }\n\n    const { data, resolve, reject } = this.queue.shift()!;\n    const messageId = `${Date.now()}-${Math.random()}`;\n\n    instance.busy = true;\n    instance.pendingMessages.set(messageId, { resolve, reject });\n\n    const message: ThreadMessage = {\n      id: messageId,\n      type: \"execute\",\n      data,\n    };\n\n    instance.port.postMessage(message);\n  }\n\n  private resetIdleTimer(): void {\n    if (this.idleTimer) {\n      clearTimeout(this.idleTimer);\n    }\n\n    this.idleTimer = setTimeout(() => {\n      this.cleanupIdleInstances();\n    }, this.idleTimeout);\n  }\n\n  private cleanupIdleInstances(): void {\n    const now = Date.now();\n    const instancesToRemove = this.instances.filter(\n      (instance) =>\n        !instance.busy && now - instance.lastUsed > this.idleTimeout,\n    );\n\n    for (const instance of instancesToRemove) {\n      const index = this.instances.indexOf(instance);\n      if (index > -1) {\n        this.instances.splice(index, 1);\n        instance.port.close();\n        void instance.worker.terminate();\n      }\n    }\n\n    if (this.instances.length > 0) {\n      this.resetIdleTimer();\n    }\n  }\n\n  async terminate(): Promise<void> {\n    if (this.idleTimer) {\n      clearTimeout(this.idleTimer);\n    }\n\n    await Promise.all(\n      this.instances.map(async (instance) => {\n        instance.port.close();\n        await instance.worker.terminate();\n      }),\n    );\n\n    this.instances = [];\n    this.queue = [];\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n","import { parentPort, workerData } from \"node:worker_threads\";\nimport { $env, $hook, t } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { $thread } from \"../descriptors/$thread.ts\";\n\ninterface ThreadMessage<T = any> {\n  id: string;\n  type: \"execute\" | \"response\" | \"error\" | \"ready\";\n  data?: T;\n  error?: string;\n}\n\nexport class ThreadProvider {\n  protected readonly log = $logger();\n  protected readonly env = $env(\n    t.object({\n      ALEPHA_WORKER: t.optional(t.text()),\n    }),\n  );\n\n  protected readonly ready = $hook({\n    on: \"ready\",\n    handler: async (alepha) => {\n      const worker = this.env.ALEPHA_WORKER;\n      if (!worker) {\n        return;\n      }\n\n      const threads = alepha.descriptors($thread);\n      const threadDescriptor = threads.find((thread) => thread.name === worker);\n\n      if (!threadDescriptor) {\n        this.log.error(`Thread not found: ${worker}`);\n        return;\n      }\n\n      this.log.info(`Thread ready: ${threadDescriptor.name}`);\n\n      // Use the message channel port from worker data if available, fallback to parentPort\n      const communicationPort = workerData?.port || parentPort;\n\n      if (!communicationPort) {\n        this.log.error(\"No communication port available\");\n        return;\n      }\n\n      // Set up message handling\n      communicationPort.on(\"message\", async (message: ThreadMessage) => {\n        if (message.type === \"execute\") {\n          try {\n            this.log.debug(\n              `Executing thread handler: ${threadDescriptor.name}`,\n            );\n            const result = await threadDescriptor.options.handler();\n\n            communicationPort.postMessage({\n              id: message.id,\n              type: \"response\",\n              data: result,\n            } as ThreadMessage);\n          } catch (error) {\n            this.log.error(`Thread execution error: ${error}`);\n\n            communicationPort.postMessage({\n              id: message.id,\n              type: \"error\",\n              error: error instanceof Error ? error.message : String(error),\n            } as ThreadMessage);\n          }\n        }\n      });\n\n      // Signal that the worker is ready\n      communicationPort.postMessage({ type: \"ready\" } as ThreadMessage);\n    },\n  });\n\n  public static async cleanup(): Promise<void> {\n    if (parentPort) {\n      parentPort.removeAllListeners();\n    }\n  }\n}\n","import { $module, Alepha } from \"alepha\";\nimport { $thread } from \"./descriptors/$thread.ts\";\nimport { ThreadProvider } from \"./providers/ThreadProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$thread.ts\";\nexport * from \"./providers/ThreadProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface Alepha {\n    isWorkerThread(): boolean;\n  }\n}\n\nAlepha.prototype.isWorkerThread = function (this: Alepha): boolean {\n  return !!this.env.ALEPHA_WORKER;\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Simple interface for managing worker threads in Alepha.\n *\n * @see {@link $thread}\n * @module alepha.thread\n */\nexport const AlephaThread = $module({\n  name: \"alepha.thread\",\n  descriptors: [$thread],\n  services: [ThreadProvider],\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuHA,MAAa,WAAW,YAAuD;AAC7E,qCAAwB,kBAAkB,QAAQ;;AA4FpD,IAAa,mBAAb,MAAa,yBAAyBA,kBAAoC;CACxE,AAAmB,SAAS,QAAQ,KAAK;CACzC,OAAgB,6BAAa,IAAI,KAAyB;CAE1D,IAAW,OAAe;AACxB,SAAO,KAAK,QAAQ,QAAQ,KAAK,OAAO;;CAG1C,IAAW,cAAsB;AAC/B,SAAO,KAAK,QAAQ,kCAAqB,CAAC,SAAS;;CAGrD,IAAW,cAAsB;AAC/B,SAAO,KAAK,QAAQ,eAAe;;CAGrC,AAAQ,UAAsB;AAC5B,MAAI,CAAC,iBAAiB,WAAW,IAAI,KAAK,KAAK,CAC7C,kBAAiB,WAAW,IAC1B,KAAK,MACL,IAAI,WACF,KAAK,MACL,KAAK,aACL,KAAK,aACL,KAAK,OACN,CACF;AAEH,SAAO,iBAAiB,WAAW,IAAI,KAAK,KAAK;;CAGnD,MAAa,QAAiB,MAAY,QAA8B;AACtE,MAAI,UAAU,KACZ,KAAI;AACF,uBAAa,OAAO,QAAQ,KAAK;WAC1B,OAAO;AACd,SAAM,IAAI,MACR,iBAAiB,iBAAiB,QAAQ,MAAM,UAAU,QAC3D;;AAKL,SAAO,MADM,KAAK,SAAS,CACT,QAAW,KAAK;;CAGpC,MAAa,SAAwB;AAEnC,QADa,KAAK,SAAS,CAChB,QAAQ;;CAGrB,MAAa,YAA2B;AAEtC,QADa,KAAK,SAAS,CAChB,WAAW;AACtB,mBAAiB,WAAW,OAAO,KAAK,KAAK;;;AAIjD,QAAQC,eAAQ;AAsBhB,IAAM,aAAN,MAAiB;CACf,AAAQ,YAA8B,EAAE;CACxC,AAAQ,QAIH,EAAE;CACP,AAAQ;CAER,YACE,AAAiBC,MACjB,AAAiBC,aACjB,AAAiBC,aACjB,AAAiBC,QACjB;EAJiB;EACA;EACA;EACA;;CAGnB,MAAM,SAAwB;AAC5B,MAAI,KAAK,UAAU,WAAW,EAC5B,OAAM,KAAK,gBAAgB;;CAI/B,MAAc,iBAA0C;EACtD,MAAM,EAAE,OAAO,UAAU,IAAIC,oCAAgB;EAE7C,MAAM,SAAS,IAAIC,2BAAO,KAAK,QAAQ;GACrC,KAAK;IACH,GAAG,QAAQ;IACX,eAAe,KAAK;IACpB,UAAU;IACX;GACD,YAAY,EAAE,MAAM,OAAO;GAC3B,cAAc,CAAC,MAAM;GACtB,CAAC;EAEF,MAAMC,WAA2B;GAC/B;GACA,MAAM;GACN,MAAM;GACN,UAAU,KAAK,KAAK;GACpB,iCAAiB,IAAI,KAAK;GAC3B;AAED,WAAS,KAAK,GAAG,YAAY,YAA2B;AACtD,OAAI,QAAQ,SAAS,cAAc,QAAQ,SAAS,SAAS;IAC3D,MAAM,UAAU,SAAS,gBAAgB,IAAI,QAAQ,GAAG;AACxD,QAAI,SAAS;AACX,cAAS,gBAAgB,OAAO,QAAQ,GAAG;AAC3C,cAAS,OAAO;AAChB,cAAS,WAAW,KAAK,KAAK;AAE9B,SAAI,QAAQ,SAAS,QACnB,SAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,CAAC;SAExC,SAAQ,QAAQ,QAAQ,KAAK;AAG/B,UAAK,cAAc;;;IAGvB;AAEF,QAAM,IAAI,SAAe,SAAS,WAAW;GAC3C,MAAM,UAAU,iBACR,uBAAO,IAAI,MAAM,gCAAgC,CAAC,EACxD,IACD;AAED,UAAO,KAAK,gBAAgB;AAC1B,iBAAa,QAAQ;AACrB,aAAS;KACT;AAEF,UAAO,KAAK,UAAU,UAAU;AAC9B,iBAAa,QAAQ;AACrB,WAAO,MAAM;KACb;IACF;AAEF,OAAK,UAAU,KAAK,SAAS;AAC7B,OAAK,gBAAgB;AAErB,SAAO;;CAGT,MAAM,QAAiB,MAAwB;AAC7C,SAAO,IAAI,SAAY,SAAS,WAAW;AACzC,QAAK,MAAM,KAAK;IAAE;IAAM;IAAS;IAAQ,CAAC;AAC1C,QAAK,cAAc;IACnB;;CAGJ,MAAc,eAA8B;AAC1C,MAAI,KAAK,MAAM,WAAW,EACxB;EAGF,IAAI,WAAW,KAAK,UAAU,MAAM,MAAM,CAAC,EAAE,KAAK;AAElD,MAAI,CAAC,YAAY,KAAK,UAAU,SAAS,KAAK,YAC5C,KAAI;AACF,cAAW,MAAM,KAAK,gBAAgB;WAC/B,OAAO;GACd,MAAM,EAAE,qBAAW,KAAK,MAAM,OAAO;AACrC,YACE,iBAAiB,QACb,wBACA,IAAI,MAAM,mCAAmC,CAClD;AACD;;AAIJ,MAAI,CAAC,SACH;EAGF,MAAM,EAAE,MAAM,SAAS,WAAW,KAAK,MAAM,OAAO;EACpD,MAAM,YAAY,GAAG,KAAK,KAAK,CAAC,GAAG,KAAK,QAAQ;AAEhD,WAAS,OAAO;AAChB,WAAS,gBAAgB,IAAI,WAAW;GAAE;GAAS;GAAQ,CAAC;EAE5D,MAAMC,UAAyB;GAC7B,IAAI;GACJ,MAAM;GACN;GACD;AAED,WAAS,KAAK,YAAY,QAAQ;;CAGpC,AAAQ,iBAAuB;AAC7B,MAAI,KAAK,UACP,cAAa,KAAK,UAAU;AAG9B,OAAK,YAAY,iBAAiB;AAChC,QAAK,sBAAsB;KAC1B,KAAK,YAAY;;CAGtB,AAAQ,uBAA6B;EACnC,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,oBAAoB,KAAK,UAAU,QACtC,aACC,CAAC,SAAS,QAAQ,MAAM,SAAS,WAAW,KAAK,YACpD;AAED,OAAK,MAAM,YAAY,mBAAmB;GACxC,MAAM,QAAQ,KAAK,UAAU,QAAQ,SAAS;AAC9C,OAAI,QAAQ,IAAI;AACd,SAAK,UAAU,OAAO,OAAO,EAAE;AAC/B,aAAS,KAAK,OAAO;AACrB,IAAK,SAAS,OAAO,WAAW;;;AAIpC,MAAI,KAAK,UAAU,SAAS,EAC1B,MAAK,gBAAgB;;CAIzB,MAAM,YAA2B;AAC/B,MAAI,KAAK,UACP,cAAa,KAAK,UAAU;AAG9B,QAAM,QAAQ,IACZ,KAAK,UAAU,IAAI,OAAO,aAAa;AACrC,YAAS,KAAK,OAAO;AACrB,SAAM,SAAS,OAAO,WAAW;IACjC,CACH;AAED,OAAK,YAAY,EAAE;AACnB,OAAK,QAAQ,EAAE;;;;;;ACxcnB,IAAa,iBAAb,MAA4B;CAC1B,AAAmB,kCAAe;CAClC,AAAmB,uBACjBC,SAAE,OAAO,EACP,eAAeA,SAAE,SAASA,SAAE,MAAM,CAAC,EACpC,CAAC,CACH;CAED,AAAmB,0BAAc;EAC/B,IAAI;EACJ,SAAS,OAAO,aAAW;GACzB,MAAM,SAAS,KAAK,IAAI;AACxB,OAAI,CAAC,OACH;GAIF,MAAM,mBADUC,SAAO,YAAY,QAAQ,CACV,MAAM,WAAW,OAAO,SAAS,OAAO;AAEzE,OAAI,CAAC,kBAAkB;AACrB,SAAK,IAAI,MAAM,qBAAqB,SAAS;AAC7C;;AAGF,QAAK,IAAI,KAAK,iBAAiB,iBAAiB,OAAO;GAGvD,MAAM,oBAAoBC,gCAAY,QAAQC;AAE9C,OAAI,CAAC,mBAAmB;AACtB,SAAK,IAAI,MAAM,kCAAkC;AACjD;;AAIF,qBAAkB,GAAG,WAAW,OAAO,YAA2B;AAChE,QAAI,QAAQ,SAAS,UACnB,KAAI;AACF,UAAK,IAAI,MACP,6BAA6B,iBAAiB,OAC/C;KACD,MAAM,SAAS,MAAM,iBAAiB,QAAQ,SAAS;AAEvD,uBAAkB,YAAY;MAC5B,IAAI,QAAQ;MACZ,MAAM;MACN,MAAM;MACP,CAAkB;aACZ,OAAO;AACd,UAAK,IAAI,MAAM,2BAA2B,QAAQ;AAElD,uBAAkB,YAAY;MAC5B,IAAI,QAAQ;MACZ,MAAM;MACN,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;MAC9D,CAAkB;;KAGvB;AAGF,qBAAkB,YAAY,EAAE,MAAM,SAAS,CAAkB;;EAEpE,CAAC;CAEF,aAAoB,UAAyB;AAC3C,MAAIA,+BACF,gCAAW,oBAAoB;;;;;;AC9DrC,cAAO,UAAU,iBAAiB,WAAiC;AACjE,QAAO,CAAC,CAAC,KAAK,IAAI;;;;;;;;AAWpB,MAAa,mCAAuB;CAClC,MAAM;CACN,aAAa,CAAC,QAAQ;CACtB,UAAU,CAAC,eAAe;CAC3B,CAAC"}

package/dist/thread/index.d.cts

@@ -1,260 +0,0 @@
-import * as alepha1 from "alepha";
-import { Descriptor, KIND, TSchema } from "alepha";
-import * as alepha_logger0 from "alepha/logger";
-
-//#region src/thread/descriptors/$thread.d.ts
-
-/**
- * Creates a worker thread descriptor for offloading CPU-intensive tasks to separate threads.
- *
- * This descriptor enables you to run JavaScript code in Node.js worker threads, allowing you to
- * leverage multiple CPU cores and avoid blocking the main event loop. It provides a pool-based
- * approach with intelligent thread reuse and automatic lifecycle management.
- *
- * **Key Features**
- *
- * - **Thread Pool Management**: Automatically manages a pool of worker threads with configurable limits
- * - **Thread Reuse**: Reuses existing threads to avoid expensive initialization overhead
- * - **Idle Cleanup**: Automatically terminates unused threads after a configurable timeout
- * - **Type-Safe Communication**: Optional TypeBox schema validation for data passed to threads
- * - **CPU-Aware Defaults**: Pool size defaults to CPU count × 2 for optimal performance
- * - **Error Handling**: Proper error propagation and thread cleanup on failures
- *
- * **Use Cases**
- *
- * Perfect for CPU-intensive tasks that would otherwise block the main thread:
- * - Image/video processing
- * - Data transformation and analysis
- * - Cryptographic operations
- * - Heavy computations and algorithms
- * - Background data processing
- *
- * @example
- * **Basic thread usage:**
- * ```ts
- * import { $thread } from "alepha/thread";
- *
- * class DataProcessor {
- *   heavyComputation = $thread({
- *     name: "compute",
- *     handler: async () => {
- *       // This runs in a separate worker thread
- *       let result = 0;
- *       for (let i = 0; i < 1000000; i++) {
- *         result += Math.sqrt(i);
- *       }
- *       return { result, timestamp: Date.now() };
- *     }
- *   });
- *
- *   async processData() {
- *     // Execute in worker thread without blocking main thread
- *     const result = await this.heavyComputation.execute();
- *     console.log(`Computation result: ${result.result}`);
- *   }
- * }
- * ```
- *
- * @example
- * **Configured thread pool with custom settings:**
- * ```ts
- * class ImageProcessor {
- *   imageProcessor = $thread({
- *     name: "image-processing",
- *     maxPoolSize: 4,        // Limit to 4 concurrent threads
- *     idleTimeout: 30000,    // Clean up idle threads after 30 seconds
- *     handler: async () => {
- *       // CPU-intensive image processing logic
- *       return await processImageData();
- *     }
- *   });
- * }
- * ```
- *
- * @example
- * **Thread with data validation:**
- * ```ts
- * import { t } from "alepha";
- *
- * class CryptoService {
- *   encrypt = $thread({
- *     name: "encryption",
- *     handler: async () => {
- *       // Perform encryption operations
- *       return await encryptData();
- *     }
- *   });
- *
- *   async encryptSensitiveData(data: { text: string; key: string }) {
- *     // Validate input data before sending to thread
- *     const schema = t.object({
- *       text: t.text(),
- *       key: t.text()
- *     });
- *
- *     return await this.encrypt.execute(data, schema);
- *   }
- * }
- * ```
- *
- * @example
- * **Parallel processing with multiple threads:**
- * ```ts
- * class BatchProcessor {
- *   processor = $thread({
- *     name: "batch-worker",
- *     maxPoolSize: 8,  // Allow up to 8 concurrent workers
- *     handler: async () => {
- *       return await processBatchItem();
- *     }
- *   });
- *
- *   async processBatch(items: any[]) {
- *     // Process multiple items in parallel across different threads
- *     const promises = items.map(() => this.processor.execute());
- *     const results = await Promise.all(promises);
- *     return results;
- *   }
- * }
- * ```
- */
-declare const $thread: {
-  (options: ThreadDescriptorOptions): ThreadDescriptor;
-  [KIND]: typeof ThreadDescriptor;
-};
-interface ThreadDescriptorOptions {
-  /**
-   * Unique name for this thread worker.
-   *
-   * Used for:
-   * - Thread pool identification (threads with same name share the same pool)
-   * - Logging and debugging
-   * - Error messages and stack traces
-   *
-   * If not provided, defaults to the property key of the descriptor.
-   *
-   * @example "image-processor"
-   * @example "crypto-worker"
-   * @example "data-analysis"
-   */
-  name?: string;
-  /**
-   * The function to execute in the worker thread.
-   *
-   * This function:
-   * - Runs in a separate Node.js worker thread
-   * - Should contain the CPU-intensive logic
-   * - Can be async and return any serializable data
-   * - Has access to standard Node.js APIs and modules
-   * - Cannot directly access the main thread's memory or variables
-   *
-   * **Important**: The handler function is serialized and sent to the worker thread,
-   * so it cannot reference variables from the parent scope (closures won't work).
-   * All required data must be passed via the `execute()` method.
-   *
-   * @example
-   * ```ts
-   * handler: async () => {
-   *   // CPU-intensive work here
-   *   const result = performComplexCalculation();
-   *   return { result, completed: Date.now() };
-   * }
-   * ```
-   */
-  handler: () => any | Promise<any>;
-  /**
-   * Maximum number of worker threads in the pool.
-   *
-   * Controls how many threads can run concurrently for this named thread worker.
-   * When all threads are busy, additional `execute()` calls will queue until a thread becomes available.
-   *
-   * **Default**: `cpus().length * 2` (number of CPU cores × 2)
-   *
-   * **Guidelines**:
-   * - For CPU-bound tasks: Set to number of CPU cores
-   * - For I/O-bound tasks in workers: Can be higher (2x CPU cores)
-   * - For memory-intensive tasks: Set lower to avoid memory pressure
-   * - For short-lived tasks: Can be higher for better throughput
-   *
-   * @default cpus().length * 2
-   * @example 4    // Limit to 4 concurrent threads
-   * @example 1    // Single worker thread (sequential processing)
-   * @example 16   // High concurrency for lightweight tasks
-   */
-  maxPoolSize?: number;
-  /**
-   * Time in milliseconds before idle worker threads are terminated.
-   *
-   * When a worker thread has been idle (not executing any tasks) for this duration,
-   * it will be automatically terminated to free up system resources. New threads
-   * will be created as needed when new tasks are submitted.
-   *
-   * **Default**: 60000 (60 seconds)
-   *
-   * **Considerations**:
-   * - Shorter timeouts: Save memory but increase thread creation overhead
-   * - Longer timeouts: Keep threads ready but consume more memory
-   * - Very short timeouts may cause constant thread creation/destruction
-   *
-   * @default 60000
-   * @example 30000   // 30 seconds
-   * @example 120000  // 2 minutes
-   * @example 5000    // 5 seconds (for very memory-constrained environments)
-   */
-  idleTimeout?: number;
-}
-declare class ThreadDescriptor extends Descriptor<ThreadDescriptorOptions> {
-  protected readonly script: string;
-  static readonly globalPool: Map<string, ThreadPool>;
-  get name(): string;
-  get maxPoolSize(): number;
-  get idleTimeout(): number;
-  private getPool;
-  execute<T = any>(data?: any, schema?: TSchema): Promise<T>;
-  create(): Promise<void>;
-  terminate(): Promise<void>;
-}
-declare class ThreadPool {
-  private readonly name;
-  private readonly maxPoolSize;
-  private readonly idleTimeout;
-  private readonly script;
-  private instances;
-  private queue;
-  private idleTimer?;
-  constructor(name: string, maxPoolSize: number, idleTimeout: number, script: string);
-  warmUp(): Promise<void>;
-  private createInstance;
-  execute<T = any>(data?: any): Promise<T>;
-  private processQueue;
-  private resetIdleTimer;
-  private cleanupIdleInstances;
-  terminate(): Promise<void>;
-}
-//#endregion
-//#region src/thread/providers/ThreadProvider.d.ts
-declare class ThreadProvider {
-  protected readonly log: alepha_logger0.Logger;
-  protected readonly env: {
-    ALEPHA_WORKER?: string | undefined;
-  };
-  protected readonly ready: alepha1.HookDescriptor<"ready">;
-  static cleanup(): Promise<void>;
-}
-//#endregion
-//#region src/thread/index.d.ts
-declare module "alepha" {
-  interface Alepha {
-    isWorkerThread(): boolean;
-  }
-}
-/**
- * Simple interface for managing worker threads in Alepha.
- *
- * @see {@link $thread}
- * @module alepha.thread
- */
-declare const AlephaThread: alepha1.Service<alepha1.Module>;
-//#endregion
-export { $thread, AlephaThread, ThreadDescriptor, ThreadDescriptorOptions, ThreadProvider };
-//# sourceMappingURL=index.d.cts.map