@elysiumjs/heracles 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elysiumjs/heracles",
-	"version": "0.4.2",
+	"version": "0.4.3",
 	"description": "Background job processing system for Elysium.js",
 	"main": "index.ts",
 	"bin": {

package/src/transports/thread.transport.ts

@@ -0,0 +1,289 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { JobStatusInfo, Transport, TransportEvent } from '../transport';
+
+import { InteractsWithConsole } from '@elysiumjs/core';
+
+import { JobStatus } from '../job';
+import { TransportMode } from '../transport';
+
+/**
+ * Manages a Bun Worker as a "thread" channel (producer driven).
+ */
+export class ThreadTransport extends InteractsWithConsole implements Transport {
+	private worker: Worker | null = null;
+	private workerReady = false;
+	private messageHandlers: Array<(message: TransportEvent) => void> = [];
+	private workerScript = './src/workers/thread.worker.ts'; // Path to ThreadWorker
+	// No local cache needed since Queue already manages job statuses
+	private registeredWorkers: Map<string, Set<string>> = new Map(); // workerId -> Set of queues
+	private options: Record<string, any>;
+
+	constructor(
+		private readonly mode: TransportMode,
+		options: Record<string, any> = {}
+	) {
+		super();
+
+		this.options = options;
+		this.workerScript = ELYSIUM_BUILD
+			? './thread.worker.js'
+			: this.options.workerScript || __dirname + '/../workers/thread.worker.ts';
+	}
+
+	async start(): Promise<void> {
+		if (this.worker) return; // Already started
+
+		this.debug(`Starting ThreadTransport with worker script: ${this.workerScript}`);
+		this.worker = new Worker(this.workerScript);
+
+		// Thread ready flag
+		this.worker.addEventListener('open', () => {
+			this.workerReady = true;
+			this.debug('ThreadTransport worker ready');
+		});
+
+		// Message event listener for handling responses
+		this.worker.addEventListener('message', (event: MessageEvent) => {
+			const message = event.data as TransportEvent;
+
+			// Handle specific message types
+			if (message.type === 'job:status' || message.type === 'job:result') {
+				this.handleStatusMessage(message);
+			} else if (message.type === 'worker:register' || message.type === 'worker:unregister') {
+				this.updateWorkerRegistration(message);
+			}
+
+			// Forward message to all handlers
+			for (const handler of this.messageHandlers) {
+				try {
+					handler(message);
+				} catch (error) {
+					this.error(`Error in message handler: ${error}`);
+				}
+			}
+		});
+
+		// Handle worker errors
+		this.worker.addEventListener('error', (event) => {
+			this.error(`Worker error: ${event}`);
+		});
+	}
+
+	/**
+	 * Process job status messages
+	 * This method is called when a job status message is received from a worker thread
+	 * The message is then forwarded to the Queue via the message handlers
+	 */
+	private handleStatusMessage(message: TransportEvent): void {
+		// Simply forward the message to handlers (Queue will store the status)
+		this.debug(
+			`Received status update for job ${(message as any).jobId}: ${(message as any).status}`
+		);
+	}
+
+	/**
+	 * Update worker registration information
+	 */
+	private updateWorkerRegistration(message: TransportEvent): void {
+		if (message.type === 'worker:register' && message.queues) {
+			const queues = new Set(message.queues);
+			this.registeredWorkers.set(message.workerId, queues);
+			this.debug(`Worker ${message.workerId} registered for queues: ${message.queues.join(', ')}`);
+		} else if (message.type === 'worker:unregister') {
+			this.registeredWorkers.delete(message.workerId);
+			this.debug(`Worker ${message.workerId} unregistered`);
+		}
+	}
+
+	async stop(): Promise<void> {
+		if (this.worker) {
+			this.debug('Stopping ThreadTransport worker');
+
+			try {
+				// Send terminate message to gracefully shut down
+				await this.send({
+					type: 'worker:unregister',
+					workerId: 'main'
+				});
+
+				// Wait a moment to allow graceful shutdown
+				await new Promise((resolve) => setTimeout(resolve, 100));
+
+				// Force terminate if still running
+				this.worker.terminate();
+			} catch (error) {
+				this.error(`Error stopping ThreadTransport: ${error}`);
+			} finally {
+				this.worker = null;
+				this.workerReady = false;
+				this.messageHandlers = [];
+				this.debug('ThreadTransport stopped');
+			}
+		}
+	}
+
+	async send(message: TransportEvent): Promise<void> {
+		if (!this.worker) {
+			this.debug('Starting worker before sending message');
+			await this.start();
+		}
+
+		// Ensure worker is ready
+		if (!this.workerReady) {
+			this.debug('Waiting for worker to be ready');
+			await new Promise((resolve) =>
+				this.worker!.addEventListener('open', () => resolve(undefined), { once: true })
+			);
+		}
+
+		try {
+			this.debug(`Sending ${message.type} message to worker`);
+			this.worker!.postMessage(message);
+		} catch (error) {
+			this.error(`Error sending message to worker: ${error}`);
+			throw new Error(`Failed to send message: ${error}`);
+		}
+	}
+
+	/**
+	 * Register a callback to handle messages from the transport
+	 */
+	onMessage(handler: (message: TransportEvent) => void): void {
+		this.messageHandlers.push(handler);
+	}
+
+	/**
+	 * Updates the status of a job directly
+	 * @param jobId The ID of the job to update
+	 * @param queueName The name of the queue the job is in
+	 * @param updates The updates to apply to the job status
+	 */
+	async updateJobStatus(
+		jobId: string,
+		dispatchId: string,
+		queueName: string,
+		updates: Partial<JobStatusInfo>
+	): Promise<void> {
+		// Get the current timestamp for all updates
+		const now = Date.now().toString();
+		const statusValue = updates.status || 'unknown';
+
+		// Determine if this is a terminal status that should use job:result type
+		const isTerminalStatus =
+			statusValue === JobStatus.COMPLETED ||
+			statusValue === JobStatus.FAILED ||
+			statusValue === JobStatus.CANCELLED;
+
+		// Create the message with the appropriate type
+		const messageType = isTerminalStatus ? 'job:result' : 'job:status';
+		const message = {
+			type: messageType,
+			jobId,
+			queue: queueName,
+			status: statusValue,
+			error: updates.error,
+			retries: updates.retries || 0,
+			startedAt: updates.startedAt,
+			completedAt: updates.completedAt || (isTerminalStatus ? now : undefined),
+			updatedAt: updates.updatedAt || now
+		};
+
+		if (this.mode === TransportMode.PRODUCER) {
+			// In producer mode, forward the status update to the worker thread
+			await this.send(message as TransportEvent);
+			this.debug(
+				`[Producer] Sent ${messageType} for job ${jobId} to worker thread: ${statusValue}`
+			);
+		} else {
+			// In consumer mode, we're in the worker thread, so send message to main thread
+			if (typeof self !== 'undefined') {
+				// @ts-ignore - self is available in worker threads
+				self.postMessage(message);
+				this.debug(
+					`[Consumer] Sent ${messageType} for job ${jobId} to main thread: ${statusValue}`
+				);
+			} else {
+				this.warning(`Unable to send job status update: not in a worker context`);
+			}
+		}
+	}
+
+	/**
+	 * Get the current status of a job
+	 */
+	async getJobStatus(jobId: string, dispatchId: string, queueName: string): Promise<JobStatusInfo> {
+		try {
+			// Request status from worker
+			await this.send({
+				type: 'job:status',
+				jobId,
+				dispatchId,
+				queue: queueName,
+				status: 'unknown'
+			});
+
+			// Since we don't maintain a local cache, we'll return a pending status
+			// The Queue will receive the actual status via the message handler when the worker responds
+			return {
+				jobId,
+				dispatchId,
+				queue: queueName,
+				status: 'unknown',
+				retries: 0,
+				createdAt: new Date().toISOString()
+			};
+		} catch (error) {
+			this.error(`Error getting job status for ${jobId}: ${error}`);
+			// Return a basic status object on error
+			return {
+				jobId,
+				dispatchId,
+				queue: queueName,
+				status: 'unknown',
+				retries: 0,
+				createdAt: new Date().toISOString(),
+				error: `Failed to get status: ${error}`
+			};
+		}
+	}
+
+	/**
+	 * Register a worker with the transport
+	 */
+	async registerWorker(workerId: string, queues: string[]): Promise<void> {
+		await this.send({
+			type: 'worker:register',
+			workerId,
+			queues
+		});
+
+		// Store locally too
+		this.registeredWorkers.set(workerId, new Set(queues));
+	}
+
+	/**
+	 * Unregister a worker from the transport
+	 */
+	async unregisterWorker(workerId: string): Promise<void> {
+		await this.send({
+			type: 'worker:unregister',
+			workerId
+		});
+
+		// Remove from local storage
+		this.registeredWorkers.delete(workerId);
+	}
+}

package/src/worker_pool.ts

@@ -0,0 +1,393 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Job, JobDispatchOptions } from './job';
+import type { WorkerInfo } from './worker';
+
+import { InteractsWithConsole } from '@elysiumjs/core';
+
+/**
+ * Interface for tracking worker selection state per queue.
+ */
+interface QueueWorkerState {
+	/**
+	 * All workers assigned to this queue
+	 */
+	workers: WorkerInfo[];
+
+	/**
+	 * Index of the last selected worker for round-robin
+	 */
+	lastWorkerIndex: number;
+}
+
+/**
+ * WorkerPool manages a pool of workers and distributes jobs among them
+ * using a round-robin algorithm.
+ */
+export class WorkerPool extends InteractsWithConsole {
+	/**
+	 * Singleton instance of the worker pool
+	 */
+	private static _instance: WorkerPool;
+
+	/**
+	 * All workers in the pool, indexed by worker ID
+	 */
+	private workers: Map<string, WorkerInfo> = new Map();
+
+	/**
+	 * Queue-to-workers mapping for tracking which workers handle each queue
+	 */
+	private queueWorkers: Map<string, QueueWorkerState> = new Map();
+
+	/**
+	 * Last used worker per queue for true round-robin
+	 */
+	private lastUsedWorker: Map<string, string> = new Map();
+
+	/**
+	 * Get the singleton instance of the worker pool
+	 */
+	public static get instance(): WorkerPool {
+		if (!WorkerPool._instance) {
+			WorkerPool._instance = new WorkerPool();
+		}
+		return WorkerPool._instance;
+	}
+
+	/**
+	 * Private constructor to enforce singleton pattern
+	 */
+	private constructor() {
+		super();
+	}
+
+	/**
+	 * Initialize the worker pool
+	 */
+	public async init(): Promise<void> {
+		this.info('WorkerPool initialized');
+	}
+
+	/**
+	 * Add a worker to the pool and associate it with queues
+	 *
+	 * @param worker The worker information to add
+	 * @param queues The queues this worker will handle
+	 */
+	public async addWorker(worker: WorkerInfo, queues: string[] = []): Promise<void> {
+		if (this.workers.has(worker.id)) {
+			this.warning(`Worker ${worker.id} is already registered in the pool`);
+			return;
+		}
+
+		// Store the worker
+		this.workers.set(worker.id, worker);
+
+		// Associate worker with each queue
+		for (const queueName of queues) {
+			// Get or create queue state
+			const queueState = this.getOrCreateQueueState(queueName);
+
+			// Add worker to queue if not already present
+			if (!queueState.workers.some((w) => w.id === worker.id)) {
+				queueState.workers.push(worker);
+				this.debug(`Worker ${worker.id} assigned to queue '${queueName}'`);
+			}
+		}
+
+		this.info(`Worker ${worker.id} added to pool with ${queues.length} queues`);
+	}
+
+	/**
+	 * Remove a worker from the pool
+	 *
+	 * @param workerId The ID of the worker to remove
+	 */
+	public async removeWorker(workerId: string): Promise<void> {
+		const worker = this.workers.get(workerId);
+		if (!worker) {
+			this.warning(`Attempted to remove non-existent worker ${workerId}`);
+			return;
+		}
+
+		// Remove worker from all queues
+		for (const [queueName, queueState] of this.queueWorkers.entries()) {
+			const workerIndex = queueState.workers.findIndex((w) => w.id === workerId);
+			if (workerIndex >= 0) {
+				queueState.workers.splice(workerIndex, 1);
+
+				// Adjust lastWorkerIndex if needed
+				if (queueState.lastWorkerIndex >= queueState.workers.length) {
+					queueState.lastWorkerIndex = queueState.workers.length > 0 ? 0 : -1;
+				}
+
+				// Also adjust lastUsedWorker if it was this worker
+				if (this.lastUsedWorker.get(queueName) === workerId) {
+					this.lastUsedWorker.delete(queueName);
+				}
+
+				this.debug(`Worker ${workerId} removed from queue '${queueName}'`);
+			}
+		}
+
+		// Remove worker from the pool
+		this.workers.delete(workerId);
+		this.info(`Worker ${workerId} removed from pool`);
+	}
+
+	/**
+	 * Terminate all workers in the pool
+	 */
+	public async terminate(): Promise<void> {
+		for (const workerId of this.workers.keys()) {
+			await this.removeWorker(workerId);
+		}
+
+		this.info('WorkerPool terminated');
+	}
+
+	/**
+	 * Get the next available worker for a queue using round-robin
+	 *
+	 * @param queueName The name of the queue to get a worker for
+	 * @returns The selected worker info or null if none available
+	 */
+	public getNextWorker(queueName: string): WorkerInfo | null {
+		const queueState = this.queueWorkers.get(queueName);
+		if (!queueState || queueState.workers.length === 0) {
+			this.warning(`No workers available for queue '${queueName}'`);
+			return null;
+		}
+
+		// True round-robin selection that considers worker load
+		// First, sort workers by number of active jobs (lightest load first)
+		const sortedWorkers = [...queueState.workers].sort((a, b) => a.activeJobs - b.activeJobs);
+
+		// If there's a big difference in load (e.g., more than 5 jobs), prefer the least loaded worker
+		const leastLoaded = sortedWorkers[0];
+		const mostLoaded = sortedWorkers[sortedWorkers.length - 1];
+
+		if (mostLoaded.activeJobs - leastLoaded.activeJobs > 5) {
+			this.debug(
+				`Selected least loaded worker ${leastLoaded.id} for queue '${queueName}' (load: ${leastLoaded.activeJobs}/${mostLoaded.activeJobs})`
+			);
+			return leastLoaded;
+		}
+
+		// Otherwise, use round-robin to ensure fair distribution
+		// Find the index of the last used worker, or -1 if none was used yet
+		const lastUsedWorkerId = this.lastUsedWorker.get(queueName);
+		let lastIndex = -1;
+
+		if (lastUsedWorkerId) {
+			lastIndex = queueState.workers.findIndex((w) => w.id === lastUsedWorkerId);
+		}
+
+		// Move to the next worker
+		const nextIndex = (lastIndex + 1) % queueState.workers.length;
+		const selectedWorker = queueState.workers[nextIndex];
+
+		// Update the last used worker
+		this.lastUsedWorker.set(queueName, selectedWorker.id);
+		queueState.lastWorkerIndex = nextIndex;
+
+		this.debug(
+			`Selected worker ${selectedWorker.id} for queue '${queueName}' (worker ${nextIndex + 1}/${queueState.workers.length}, active jobs: ${selectedWorker.activeJobs})`
+		);
+		return selectedWorker;
+	}
+
+	/**
+	 * Execute a job using a worker from the pool
+	 *
+	 * @param job The job to execute
+	 * @param queueName The queue the job belongs to
+	 * @param options Optional job dispatch options
+	 * @returns A promise that resolves when the job is dispatched to a worker
+	 */
+	public async runJob(
+		job: Job,
+		queueName: string,
+		options: JobDispatchOptions = {}
+	): Promise<void> {
+		const worker = this.getNextWorker(queueName);
+		if (!worker) {
+			throw new Error(`No workers available for queue '${queueName}'`);
+		}
+
+		// Assign queue name to job
+		job.queueName = queueName;
+
+		// Apply job options
+		const jobOptions = {
+			scheduledFor: options.scheduledFor,
+			priority: options.priority || 10,
+			maxRetries: options.maxRetries,
+			retryDelay: options.retryDelay
+		};
+
+		// Dispatch job to worker
+		try {
+			this.debug(`Dispatching job ${job.id} to worker ${worker.id} in queue '${queueName}'`);
+			// Pass job options to worker
+			if (typeof worker.addJob === 'function') {
+				const result = await worker.addJob(job, queueName);
+				if (!result) {
+					throw new Error(`Worker ${worker.id} failed to accept job ${job.id}`);
+				}
+			} else {
+				throw new Error(`Worker ${worker.id} does not implement addJob method`);
+			}
+		} catch (error) {
+			// If this worker fails, remove it and try another worker
+			this.error(`Failed to dispatch job ${job.id} to worker ${worker.id}: ${error}`);
+			await this.removeWorker(worker.id);
+
+			// Retry with another worker
+			await this.runJob(job, queueName, options);
+		}
+	}
+
+	/**
+	 * Cancel a job across all workers
+	 *
+	 * @param jobId The ID of the job to cancel
+	 * @param queueName Optional queue name to limit search
+	 * @returns True if the job was canceled, false otherwise
+	 */
+	public async cancelJob(jobId: string, queueName?: string): Promise<boolean> {
+		let canceled = false;
+
+		if (queueName) {
+			// Try to cancel in specific queue
+			const queueState = this.queueWorkers.get(queueName);
+			if (queueState) {
+				// Try each worker in the queue
+				for (const worker of queueState.workers) {
+					try {
+						if (await worker.cancelJob(jobId, queueName)) {
+							canceled = true;
+							this.debug(`Job ${jobId} cancelled on worker ${worker.id}`);
+							break;
+						}
+					} catch (error) {
+						this.warning(`Error cancelling job ${jobId} on worker ${worker.id}: ${error}`);
+					}
+				}
+			}
+		} else {
+			// Try all workers
+			for (const worker of this.workers.values()) {
+				try {
+					if (await worker.cancelJob(jobId)) {
+						canceled = true;
+						this.debug(`Job ${jobId} cancelled on worker ${worker.id}`);
+						break;
+					}
+				} catch (error) {
+					this.warning(`Error cancelling job ${jobId} on worker ${worker.id}: ${error}`);
+				}
+			}
+		}
+
+		return canceled;
+	}
+
+	/**
+	 * Cancel all jobs across all workers
+	 *
+	 * @param queueName Optional queue name to limit cancellation
+	 * @returns The number of jobs canceled
+	 */
+	public async cancelAllJobs(queueName?: string): Promise<number> {
+		let total = 0;
+
+		if (queueName) {
+			// Cancel in specific queue
+			const queueState = this.queueWorkers.get(queueName);
+			if (queueState) {
+				for (const worker of queueState.workers) {
+					try {
+						const count = await worker.cancelAllJobs(queueName);
+						total += count;
+						this.debug(`Cancelled ${count} jobs on worker ${worker.id} in queue ${queueName}`);
+					} catch (error) {
+						this.warning(`Error cancelling jobs on worker ${worker.id}: ${error}`);
+					}
+				}
+			}
+		} else {
+			// Cancel in all workers
+			for (const worker of this.workers.values()) {
+				try {
+					const count = await worker.cancelAllJobs();
+					total += count;
+					this.debug(`Cancelled ${count} jobs on worker ${worker.id}`);
+				} catch (error) {
+					this.warning(`Error cancelling jobs on worker ${worker.id}: ${error}`);
+				}
+			}
+		}
+
+		return total;
+	}
+
+	/**
+	 * Get all queues being handled by this pool
+	 *
+	 * @returns An array of queue names
+	 */
+	public getQueues(): string[] {
+		return Array.from(this.queueWorkers.keys());
+	}
+
+	/**
+	 * Get all workers in the pool
+	 *
+	 * @returns An array of worker infos
+	 */
+	public getWorkers(): WorkerInfo[] {
+		return Array.from(this.workers.values());
+	}
+
+	/**
+	 * Get workers for a specific queue
+	 *
+	 * @param queueName The name of the queue
+	 * @returns An array of worker infos for the queue
+	 */
+	public getWorkersForQueue(queueName: string): WorkerInfo[] {
+		const queueState = this.queueWorkers.get(queueName);
+		return queueState ? [...queueState.workers] : [];
+	}
+
+	/**
+	 * Get or create queue state for tracking workers
+	 *
+	 * @param queueName The name of the queue
+	 * @returns The queue worker state
+	 */
+	private getOrCreateQueueState(queueName: string): QueueWorkerState {
+		if (!this.queueWorkers.has(queueName)) {
+			this.queueWorkers.set(queueName, {
+				workers: [],
+				lastWorkerIndex: -1
+			});
+		}
+
+		return this.queueWorkers.get(queueName)!;
+	}
+}

package/src/workers/thread.worker.entry.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'reflect-metadata';
+
+import type { Class } from 'type-fest';
+import type { Job } from '../job';
+import type { TransportEvent } from '../transport';
+
+import { Service } from '@elysiumjs/core';
+
+import { WorkerStatus } from '../worker';
+import { ThreadWorker } from './thread.worker';
+
+// Define self for TypeScript
+declare const self: Worker;
+
+// Ensure we're in a worker context
+if (typeof self === 'undefined') {
+	throw new Error('This script must be run in a worker context');
+}
+
+// Log worker startup
+console.log(`Heracles thread worker starting...`);
+
+// Set a global worker reference
+let worker: ThreadWorker | null = null;
+
+// For storing pre-imported job classes
+const jobClasses = new Map<string, Class<Job>>();
+
+// Handle all messages from the main thread
+self.addEventListener('message', async (event) => {
+	try {
+		// Process the message based on its type
+		if (event.data && typeof event.data === 'object') {
+			const message = event.data as TransportEvent;
+
+			switch (message.type) {
+				case 'worker:init': {
+					// Initialize worker if not already initialized
+					if (!worker) {
+						const { queues = ['default'], options = {} } = message as any;
+
+						console.log(`Initializing worker with queues: ${queues.join(', ')}`);
+
+						// Initialize worker with provided queues
+						worker = new ThreadWorker(queues);
+
+						// Configure worker with options
+						if (options.concurrency) {
+							for (const queue of queues) {
+								await worker.setConcurrency(queue, options.concurrency);
+							}
+						}
+
+						// Store worker in global scope for debug purposes
+						(self as any).__worker = worker;
+
+						// Start the worker
+						await worker.start();
+
+						// Send ready message back to main thread
+						self.postMessage({
+							type: 'worker:ready',
+							id: worker.id,
+							queues: Array.from(worker.getInfo().queues),
+							status: worker.status,
+							timestamp: Date.now()
+						});
+					}
+					break;
+				}
+
+				case 'job:process': {
+					// Process a job
+					if (!worker) {
+						throw new Error('Worker not initialized');
+					}
+
+					// Handle the job processing
+					const { job: jobName, args = [], queue = 'default', options } = message;
+					await handleMessage(message);
+					break;
+				}
+
+				default:
+					// Other messages will be handled by the ThreadWorker itself
+					if (worker) {
+						await handleMessage(message);
+					} else {
+						console.warn(`Received message before worker initialization: ${message.type}`);
+
+						// Try to handle initialization on the fly
+						worker = new ThreadWorker(['default']);
+						await worker.start();
+						await handleMessage(message);
+					}
+					break;
+			}
+		}
+	} catch (error) {
+		console.error('Error handling message in worker thread:', error);
+
+		// Report error to main thread
+		self.postMessage({
+			type: 'worker:error',
+			error: error instanceof Error ? error.message : String(error),
+			timestamp: Date.now()
+		});
+	}
+});
+
+/**
+ * Handle a transport message
+ */
+async function handleMessage(message: TransportEvent): Promise<void> {
+	if (!worker) {
+		throw new Error('Worker not initialized');
+	}
+
+	// Forward the message to the worker instance for processing
+	await worker.handleMessage(message);
+}
+
+// Send open message to main thread to indicate worker is ready for initialization
+self.postMessage({ type: 'worker:open' });
+
+// Handle uncaught errors
+self.addEventListener('error', (event) => {
+	console.error('Uncaught error in worker thread:', event.error || event.message);
+
+	// Report error to main thread
+	self.postMessage({
+		type: 'worker:error',
+		error: event.error?.message || event.message || 'Unknown error',
+		timestamp: Date.now()
+	});
+});
+
+// Handle unhandled promise rejections
+self.addEventListener('unhandledrejection', (event) => {
+	console.error('Unhandled rejection in worker thread:', event.reason);
+
+	// Report error to main thread
+	self.postMessage({
+		type: 'worker:error',
+		error: event.reason?.message || String(event.reason) || 'Unhandled promise rejection',
+		timestamp: Date.now()
+	});
+});
+
+// Initialize custom module loading if needed
+if (typeof Bun !== 'undefined') {
+	// Bun-specific initialization
+	console.log('Running in Bun environment');
+}
+
+// Export ThreadWorker and other components for testing/debugging
+export { ThreadWorker, WorkerStatus };

package/src/workers/thread.worker.ts

@@ -0,0 +1,525 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Class } from 'type-fest';
+import type { Job } from '../job';
+import type { JobDispatchOptions } from '../queue';
+import type { TransportEvent } from '../transport';
+
+import { Service } from '@elysiumjs/core';
+
+import { JobStatus } from '../job';
+import { TransportMode } from '../transport';
+import { ThreadTransport } from '../transports/thread.transport';
+import { BaseWorker } from './base.worker';
+
+declare const self: Worker;
+
+/**
+ * Worker class that receives jobs from parent thread.
+ */
+export class ThreadWorker extends BaseWorker {
+	/**
+	 * Transport instance used for communication with main thread
+	 */
+	private readonly transport: ThreadTransport;
+
+	constructor(queues: string[] = ['default'], id?: string) {
+		super(id);
+
+		this.info(`ThreadWorker ${this.id} started with queues: ${queues.join(', ')}`);
+
+		// Create transport in consumer mode if in worker thread
+		this.transport = new ThreadTransport(TransportMode.CONSUMER);
+		this.debug('Created transport in consumer mode');
+
+		// Only set up message listeners if running in a worker thread
+		this.setupMessageListeners();
+
+		// Initialize the specified queues
+		for (const queueName of queues) {
+			if (!this.queues.has(queueName)) {
+				this.createQueue({ name: queueName });
+			}
+		}
+
+		// Report that the worker is ready if in worker thread
+		self.postMessage({
+			type: 'worker:ready',
+			id: this.id,
+			queues: Array.from(this.queues.keys()),
+			status: this.status
+		});
+	}
+
+	/**
+	 * Set up message listeners for worker thread
+	 */
+	private setupMessageListeners(): void {
+		self.addEventListener('message', async (event: MessageEvent) => {
+			const message = event.data as TransportEvent;
+
+			try {
+				await this.handleMessage(message);
+			} catch (error: any) {
+				this.error(`Error handling message: ${error}`);
+				self.postMessage({
+					type: 'worker:error',
+					error: error.message || String(error),
+					workerId: this.id
+				});
+			}
+		});
+
+		// Handle errors
+		self.addEventListener('error', (e) => {
+			this.trace({ ...e.error, filename: e.filename }, `ThreadWorker ${this.id} error:`);
+			self.postMessage({
+				type: 'worker:error',
+				error: e.error?.message || e.message || 'Unknown error',
+				workerId: this.id
+			});
+		});
+
+		// Handle unhandled promise rejections
+		self.addEventListener('unhandledrejection', (e: any) => {
+			const error = e.reason || e;
+			this.trace(error, `ThreadWorker ${this.id} unhandled rejection:`);
+			self.postMessage({
+				type: 'worker:error',
+				error: error.message || String(error),
+				workerId: this.id
+			});
+		});
+	}
+
+	/**
+	 * Handle a message from the main thread
+	 * @public This method is exposed to be called from thread.worker.entry.ts
+	 */
+	public async handleMessage(message: TransportEvent): Promise<void> {
+		switch (message.type) {
+			case 'job:process': {
+				// Process a new job
+				const { job: jobName, args = [], queue = 'default', options } = message;
+				this.debug(`ThreadWorker ${this.id} received job ${jobName} for queue ${queue}`);
+				await this.handleProcessJob(jobName, args, queue, {
+					...options,
+					scheduledFor: new Date(options?.scheduledFor ?? Date.now())
+				});
+				break;
+			}
+
+			case 'job:cancel': {
+				// Cancel a job
+				const { jobId, queue = 'default' } = message;
+				const canceled = await this.cancelJob(jobId, queue);
+				this.sendStatusUpdate({
+					type: 'job:canceled',
+					jobId,
+					queue,
+					success: canceled,
+					count: canceled ? 1 : 0
+				});
+				break;
+			}
+
+			case 'job:cancelAll': {
+				// Cancel all jobs in a queue
+				const { queue = 'default' } = message;
+				const canceledCount = await this.cancelAllJobs(queue);
+				this.sendStatusUpdate({
+					type: 'job:canceled',
+					queue,
+					count: canceledCount
+				});
+				break;
+			}
+
+			case 'job:status': {
+				// Get job status
+				const { jobId, queue = 'default' } = message;
+				const job = await this.getJob(jobId, queue);
+
+				if (job) {
+					this.sendStatusUpdate({
+						type: 'job:status',
+						jobId,
+						queue,
+						status: job.status,
+						error: job.lastError?.message,
+						retries: job.retries,
+						startedAt: job.startedAt?.toISOString(),
+						completedAt: job.completedAt?.toISOString()
+					});
+				} else {
+					this.sendStatusUpdate({
+						type: 'job:status',
+						jobId,
+						queue,
+						status: 'unknown'
+					});
+				}
+				break;
+			}
+
+			case 'worker:register': {
+				// Add new queues to this worker
+				if (message.queues?.length) {
+					for (const queueName of message.queues) {
+						if (!this.queues.has(queueName)) {
+							await this.createQueue({ name: queueName });
+						}
+					}
+
+					// Send updated worker info
+					this.sendWorkerStatusUpdate();
+				}
+				break;
+			}
+
+			case 'worker:unregister': {
+				// Stop the worker
+				await this.stop();
+
+				// Notify main thread that worker is stopping
+				this.sendStatusUpdate({
+					type: 'worker:status',
+					workerId: this.id,
+					status: 'stopped',
+					queues: Array.from(this.queues.keys()),
+					processing: 0,
+					waiting: 0
+				});
+
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Process the next job in a queue
+	 */
+	public async processNextJob(queueName: string): Promise<void> {
+		const queue = this.queues.get(queueName);
+		if (!queue || queue.paused || queue.processing >= queue.options.concurrency!) {
+			return;
+		}
+
+		const queuedJob = queue.jobs.shift();
+		if (!queuedJob) {
+			return;
+		}
+
+		if (queuedJob.job.status === JobStatus.CANCELLED) {
+			this.info(`Skipping cancelled job ${queuedJob.job.id}`);
+			this.sendStatusUpdate({
+				type: 'job:status',
+				jobId: queuedJob.job.id,
+				queue: queueName,
+				status: JobStatus.CANCELLED
+			});
+
+			this.processQueueJobs(queueName);
+			return;
+		}
+
+		// Add to active jobs
+		queue.activeJobs.set(queuedJob.job.id, queuedJob);
+		queue.processing++;
+
+		// Send job started status update
+		try {
+			await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.dispatchId, queueName, {
+				status: JobStatus.RUNNING,
+				startedAt: new Date().toISOString()
+			});
+		} catch (error) {
+			this.error(`Error updating job status to RUNNING: ${error}`);
+		}
+
+		try {
+			this.debug(`Processing job ${queuedJob.job.id} from queue '${queueName}'`);
+			await queuedJob.job.run();
+
+			// Handle job completion based on status
+			if (queuedJob.job.status === JobStatus.FAILED) {
+				// Determine max retries - use job-specific setting if available, otherwise queue setting
+				const maxRetries =
+					queuedJob.maxRetries !== undefined ? queuedJob.maxRetries : queue.options.maxRetries!;
+
+				if (queuedJob.retries < maxRetries) {
+					// Schedule for retry
+					queuedJob.retries++;
+					queuedJob.job.incrementRetries();
+					this.warning(
+						`Job ${queuedJob.job.id} failed, retrying (${queuedJob.retries}/${maxRetries})`
+					);
+
+					// Determine retry delay - use job-specific setting if available, otherwise queue setting
+					const retryDelay =
+						queuedJob.retryDelay !== undefined ? queuedJob.retryDelay : queue.options.retryDelay!;
+
+					// Set scheduled time for retry
+					const retryTime = new Date();
+					retryTime.setMilliseconds(retryTime.getMilliseconds() + retryDelay);
+					queuedJob.scheduledFor = retryTime;
+
+					// Send status update for scheduled retry
+					try {
+						await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.id, queueName, {
+							status: JobStatus.SCHEDULED_FOR_RETRY,
+							error: queuedJob.job.lastError?.message,
+							retries: queuedJob.retries
+						});
+					} catch (error) {
+						this.error(`Error updating job status to SCHEDULED_FOR_RETRY: ${error}`);
+					}
+
+					// Schedule the retry
+					setTimeout(async () => {
+						if (queuedJob.job.status !== JobStatus.CANCELLED) {
+							queue.jobs.push(queuedJob);
+							this.processQueueJobs(queueName);
+						} else {
+							this.info(`Skipping cancelled job ${queuedJob.job.id} during retry delay`);
+							try {
+								await this.transport.updateJobStatus(
+									queuedJob.job.id,
+									queuedJob.job.id,
+									queueName,
+									{
+										status: JobStatus.CANCELLED
+									}
+								);
+							} catch (error) {
+								this.error(`Error updating job status to CANCELLED: ${error}`);
+							}
+						}
+					}, retryDelay);
+				} else {
+					// Job failed permanently after all retries
+					const maxRetries =
+						queuedJob.maxRetries !== undefined ? queuedJob.maxRetries : queue.options.maxRetries!;
+					this.error(
+						`Job ${queuedJob.job.id} failed after ${queuedJob.retries} retries (max: ${maxRetries})`
+					);
+
+					// Send final failure status
+					const completedAt = queuedJob.job.completedAt?.toISOString() || new Date().toISOString();
+					try {
+						await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.id, queueName, {
+							status: JobStatus.FAILED,
+							error: queuedJob.job.lastError?.message,
+							completedAt
+						});
+					} catch (error) {
+						this.error(`Error updating job status to FAILED: ${error}`);
+					}
+
+					if (queue.options.pauseOnError) {
+						this.pause(queueName);
+						this.warning(`Queue '${queueName}' paused due to job failure`);
+					}
+				}
+			} else if (queuedJob.job.status === JobStatus.COMPLETED) {
+				// Job completed successfully
+				this.success(`Job ${queuedJob.job.id} completed successfully`);
+
+				// Send completion status
+				const completedAt = queuedJob.job.completedAt?.toISOString() || new Date().toISOString();
+				try {
+					await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.id, queueName, {
+						status: JobStatus.COMPLETED,
+						completedAt
+					});
+				} catch (error) {
+					this.error(`Error updating job status to COMPLETED: ${error}`);
+				}
+			} else if (queuedJob.job.status === JobStatus.CANCELLED) {
+				// Job was cancelled while running
+				this.info(`Job ${queuedJob.job.id} cancelled while running`);
+
+				// Send cancellation status
+				const completedAt = queuedJob.job.completedAt?.toISOString() || new Date().toISOString();
+				try {
+					await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.id, queueName, {
+						status: JobStatus.CANCELLED,
+						completedAt
+					});
+				} catch (error) {
+					this.error(`Error updating job status to CANCELLED: ${error}`);
+				}
+			}
+		} catch (error: any) {
+			// Handle unexpected errors during job execution
+			this.error(`Unexpected error processing job ${queuedJob.job.id}: ${error}`);
+
+			// Send error status using transport if available
+			const completedAt = new Date().toISOString();
+			const errorMsg = error.message || String(error);
+			if (this.transport && typeof this.transport.updateJobStatus === 'function') {
+				await this.transport.updateJobStatus(queuedJob.job.id, queuedJob.job.id, queueName, {
+					status: JobStatus.FAILED,
+					error: errorMsg,
+					completedAt
+				});
+			} else {
+				this.sendStatusUpdate({
+					type: 'job:result',
+					jobId: queuedJob.job.id,
+					queue: queueName,
+					status: JobStatus.FAILED,
+					error: errorMsg,
+					completedAt
+				});
+			}
+
+			if (queue.options.pauseOnError) {
+				this.pause(queueName);
+				this.warning(`Queue '${queueName}' paused due to unexpected error`);
+			}
+		} finally {
+			// Remove job from active jobs and decrement processing count
+			queue.activeJobs.delete(queuedJob.job.id);
+			queue.processing--;
+
+			// Send worker status update
+			this.sendWorkerStatusUpdate();
+
+			// Process next job if available
+			this.processQueueJobs(queueName);
+		}
+	}
+
+	/**
+	 * Create a job from a job class name and add it to a queue
+	 */
+	private async handleProcessJob(
+		jobName: string,
+		args: any[],
+		queue: string = 'default',
+		options?: Partial<JobDispatchOptions>
+	): Promise<void> {
+		this.debug(`Processing job ${jobName} in ThreadWorker for queue ${queue}`);
+		try {
+			// Get job class from service container
+			const JobClass = Service.get(jobName) as Class<Job>;
+			if (!JobClass) {
+				this.error(`Job class ${jobName} not found`);
+				throw new Error(`Job class ${jobName} not found`);
+			}
+
+			// Create job instance
+			const job = new JobClass(...(args || []));
+			job.queueName = queue;
+
+			// Prepare job options
+			const jobOptions: JobDispatchOptions = options || {};
+
+			// Convert ISO string date to Date object if needed
+			if (jobOptions.scheduledFor && typeof jobOptions.scheduledFor === 'string') {
+				jobOptions.scheduledFor = new Date(jobOptions.scheduledFor);
+			}
+
+			// Set initial job status
+			const initialStatus =
+				jobOptions.scheduledFor && jobOptions.scheduledFor > new Date()
+					? JobStatus.SCHEDULED_FOR_RETRY
+					: JobStatus.PENDING;
+
+			try {
+				await this.transport.updateJobStatus(job.id, job.dispatchId, queue, {
+					status: initialStatus,
+					createdAt: new Date().toISOString()
+				});
+			} catch (error) {
+				this.error(`Error setting initial job status: ${error}`);
+			}
+
+			// Add job to queue with options
+			await this.addJob(job, queue, jobOptions);
+
+			// Send job received confirmation
+			this.sendStatusUpdate({
+				type: 'job:received',
+				jobId: job.id,
+				queue
+			});
+		} catch (error: any) {
+			// Log and report error
+			this.trace(
+				error,
+				`Error while adding job '${jobName}' to queue '${queue}' with worker ${this.id}`
+			);
+
+			this.sendStatusUpdate({
+				type: 'job:error',
+				jobId: `error_${Date.now()}`,
+				jobName,
+				queue,
+				error: error.message || String(error)
+			});
+		}
+	}
+
+	/**
+	 * Send a status update to the main thread (legacy method)
+	 * @deprecated Use transport.updateJobStatus instead
+	 */
+	private sendStatusUpdate(message: any): void {
+		this.warning(`Using deprecated sendStatusUpdate. Use transport.updateJobStatus instead`);
+		self.postMessage(message);
+	}
+
+	/**
+	 * Send worker status update to main thread
+	 */
+	private sendWorkerStatusUpdate(): void {
+		// Calculate waiting and processing counts
+		let waiting = 0;
+		let processing = 0;
+
+		for (const queue of this.queues.values()) {
+			waiting += queue.jobs.length;
+			processing += queue.processing;
+		}
+
+		// Send status update
+		self.postMessage({
+			type: 'worker:status',
+			workerId: this.id,
+			queues: Array.from(this.queues.keys()),
+			status: this.status as string,
+			processing,
+			waiting
+		});
+	}
+
+	/**
+	 * Override start method to send status update
+	 */
+	public async start(): Promise<void> {
+		await super.start();
+		this.sendWorkerStatusUpdate();
+	}
+
+	/**
+	 * Override stop method to send status update
+	 */
+	public async stop(force: boolean = false): Promise<void> {
+		await super.stop(force);
+		this.sendWorkerStatusUpdate();
+	}
+}