@elysiumjs/heracles 0.4.3 → 0.5.0

package/dist/workers/base.worker.d.ts

@@ -0,0 +1,216 @@
+import type { Job } from '../job';
+import type { JobDispatchOptions } from '../queue';
+import type { Transport } from '../transport';
+import type { QueueState, Worker, WorkerInfo, WorkerQueueOptions } from '../worker';
+import { InteractsWithConsole } from '@elysiumjs/core';
+import { JobStatus } from '../job';
+import { WorkerStatus } from '../worker';
+/**
+ * Base class for workers that manages multiple job queues and processes them in parallel.
+ * Each queue processes its jobs sequentially by default, but can be configured for concurrency.
+ * @author Axel Nana <axel.nana@workbud.com>
+ *
+ * @template TTransport The type of transport used by the worker.
+ */
+export declare abstract class BaseWorker<TTransport extends Transport> extends InteractsWithConsole implements Worker {
+    #private;
+    /**
+     * Transport instance used for Redis communication
+     */
+    protected transport: TTransport;
+    /**
+     * The queues managed by this worker.
+     */
+    protected queues: Map<string, QueueState>;
+    /**
+     * The default queue name.
+     */
+    protected defaultQueueName: string;
+    /**
+     * The default transport used by this worker.
+     */
+    protected defaultTransport?: Transport;
+    /**
+     * The current status of this worker.
+     */
+    protected workerStatus: WorkerStatus;
+    /**
+     * When this worker was started.
+     */
+    protected startedAt: Date;
+    /**
+     * Interval in milliseconds to check for scheduled jobs.
+     */
+    protected scheduledJobInterval: number;
+    /**
+     * Timer for checking scheduled jobs.
+     */
+    private scheduledJobTimer?;
+    constructor(id?: string);
+    /**
+     * Gets the worker ID.
+     * @returns The worker ID.
+     */
+    get id(): string;
+    /**
+     * Gets the worker status.
+     */
+    get status(): WorkerStatus;
+    /**
+     * Creates a new queue with the specified options.
+     *
+     * @param options The queue configuration options.
+     * @returns The Worker instance for method chaining.
+     */
+    createQueue(options: WorkerQueueOptions): Promise<Worker>;
+    /**
+     * Adds a job to the specified queue or the default queue if not specified.
+     *
+     * @param job The job to add to the queue.
+     * @param queueName Optional name of the queue to add the job to. Defaults to the default queue.
+     * @param options Additional options for job scheduling
+     * @returns The Worker instance for method chaining.
+     * @throws Error if the specified queue does not exist.
+     */
+    addJob(job: Job, queueName?: string, options?: JobDispatchOptions): Promise<Worker>;
+    /**
+     * Pauses a queue, preventing it from processing new jobs.
+     *
+     * @param queueName The name of the queue to pause. If not specified, pauses all queues.
+     * @returns The Worker instance for method chaining.
+     */
+    pause(queueName?: string): Promise<Worker>;
+    /**
+     * Resumes a paused queue.
+     *
+     * @param queueName The name of the queue to resume. If not specified, resumes all queues.
+     * @returns The Worker instance for method chaining.
+     */
+    resume(queueName?: string): Promise<Worker>;
+    /**
+     * Drains a queue, completing all current jobs but not accepting new ones.
+     *
+     * @param queueName The name of the queue to drain. If not specified, drains all queues.
+     * @returns The Worker instance for method chaining.
+     */
+    drain(queueName?: string): Promise<Worker>;
+    /**
+     * Clears all jobs from a queue.
+     *
+     * @param queueName The name of the queue to clear. If not specified, clears all queues.
+     * @returns The Worker instance for method chaining.
+     */
+    clear(queueName?: string): Promise<Worker>;
+    /**
+     * Gets the number of jobs in a queue.
+     *
+     * @param queueName The name of the queue to get the size of.
+     * @returns The number of jobs in the queue.
+     * @throws Error if the specified queue does not exist.
+     */
+    size(queueName?: string): Promise<number>;
+    /**
+     * Gets the total number of jobs across all queues.
+     *
+     * @returns The total number of jobs.
+     */
+    totalSize(): Promise<number>;
+    /**
+     * Gets statistics about all queues.
+     *
+     * @returns An object containing statistics about each queue.
+     */
+    getStats(): Promise<Record<string, {
+        waiting: number;
+        processing: number;
+        paused: boolean;
+        draining: boolean;
+    }>>;
+    /**
+     * Gets information about this worker for the worker pool.
+     *
+     * @returns Worker information object
+     */
+    getInfo(): WorkerInfo;
+    /**
+     * Cancels a job by its ID.
+     *
+     * @param jobId The ID of the job to cancel.
+     * @param queueName Optional queue name to search in. If not provided, searches all queues.
+     * @returns `true` if the job was found and canceled, false otherwise.
+     */
+    cancelJob(jobId: string, queueName?: string): Promise<boolean>;
+    /**
+     * Cancels all jobs in a queue.
+     *
+     * @param queueName The name of the queue to cancel jobs from. If not provided, cancels jobs in all queues.
+     * @returns The number of jobs canceled.
+     */
+    cancelAllJobs(queueName?: string): Promise<number>;
+    /**
+     * Get a job by its ID.
+     *
+     * @param jobId The ID of the job to get.
+     * @param queueName Optional queue name to search in. If not provided, searches all queues.
+     * @returns The job if found, null otherwise.
+     */
+    getJob(jobId: string, queueName?: string): Promise<Job | null>;
+    /**
+     * Start the worker.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker.
+     *
+     * @param force If true, cancel all running jobs. If false, allow them to complete.
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Set the concurrency for a queue.
+     *
+     * @param queueName The name of the queue.
+     * @param concurrency The new concurrency value.
+     */
+    setConcurrency(queueName: string, concurrency: number): Promise<void>;
+    /**
+     * Start the timer for checking scheduled jobs.
+     */
+    private startScheduledJobTimer;
+    /**
+     * Stop the timer for checking scheduled jobs.
+     */
+    private stopScheduledJobTimer;
+    /**
+     * Check for jobs that are scheduled to run now.
+     */
+    private checkScheduledJobs;
+    /**
+     * Processes the next job in the specified queue.
+     *
+     * @param queueName The name of the queue to process.
+     */
+    protected abstract processNextJob(queueName: string): Promise<void>;
+    /**
+     * Processes jobs in a queue up to the concurrency limit.
+     *
+     * @param queueName The name of the queue to process.
+     * @returns A promise that resolves when job processing has been initiated.
+     */
+    protected processQueueJobs(queueName: string): Promise<void>;
+    /**
+     * Send job status update
+     * @param jobId Job ID
+     * @param queue Queue name
+     * @param status Job status
+     * @param error Optional error message
+     */
+    protected sendJobStatusUpdate(jobId: string, dispatchId: string, queue: string, status: JobStatus, error?: string): Promise<void>;
+    /**
+     * Cancels a job in a specific queue.
+     *
+     * @param jobId The ID of the job to cancel.
+     * @param queueName The name of the queue to search in.
+     * @returns `true` if the job was found and canceled, false otherwise.
+     */
+    private cancelJobInQueue;
+}

package/dist/workers/redis.worker.d.ts

@@ -0,0 +1,57 @@
+import type { QueueOptions } from '../queue';
+import type { Worker } from '../worker';
+import { RedisTransport } from '../transports/redis.transport';
+import { BaseWorker } from './base.worker';
+/**
+ * Worker implementation that uses Redis for communication.
+ * This worker can run in a separate process from the dispatcher.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class RedisWorker extends BaseWorker<RedisTransport> {
+    /**
+     * Whether the worker is currently running
+     */
+    private isRunning;
+    /**
+     * Queues registered with this worker
+     */
+    private registeredQueues;
+    /**
+     * Creates a new RedisWorker instance
+     * @param connectionName Name of the Redis connection to use
+     * @param options Additional options for the Redis transport
+     */
+    constructor(connectionName?: string, options?: Record<string, any>);
+    /**
+     * Start the worker and begin processing jobs
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker
+     * @param force If true, cancel all jobs in progress
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Process the next job in a queue, respecting overlap settings
+     * @param queueName Name of the queue
+     */
+    protected processNextJob(queueName: string): Promise<void>;
+    /**
+     * Create a new queue with the specified options
+     * @param options Queue options
+     */
+    createQueue(options: QueueOptions): Promise<Worker>;
+    /**
+     * Handle a message from the transport
+     * @param message The message to handle
+     */
+    private handleTransportMessage;
+    /**
+     * Handle a job:process message
+     * @param jobName Job class name
+     * @param args Job constructor arguments
+     * @param queueName Queue name
+     * @param options Job options
+     */
+    private handleProcessJob;
+}

package/package.json

@@ -1,24 +1,26 @@
 {
 	"name": "@elysiumjs/heracles",
-	"version": "0.4.3",
-	"description": "Background job processing system for Elysium.js",
-	"main": "index.ts",
-	"bin": {
-		"heracles": "./dist/bin/cli.js"
-	},
+	"version": "0.5.0",
+	"description": "Background job processing system for Elysium.js apps.",
+	"module": "dist/index.js",
+	"type": "module",
+	"types": "dist/index.d.ts",
 	"scripts": {
-		"build:cli": "bun build ./bin/cli.ts --outdir ./dist/bin --target bun -e @elysiumjs/heracles -e @elysiumjs/core",
 		"test": "bun test",
 		"dev": "bun --watch src/index.ts",
-		"clean": "rimraf dist",
 		"format": "prettier --write 'src/**/*.{ts,tsx}'",
-		"prepublishOnly": "bun run clean && bun run build:cli"
+		"clean": "rimraf dist",
+		"build:js": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --root ./src --minify",
+		"build:ts": "tsc",
+		"build": "bun run clean && bun run build:js && bun run build:ts",
+		"prepublishOnly": "bun run build"
 	},
 	"keywords": [
 		"elysium",
 		"job",
 		"queue",
 		"worker",
+		"scheduler",
 		"background",
 		"processing",
 		"heracles"
@@ -26,18 +28,18 @@
 	"author": "Workbud Technologies Inc.",
 	"license": "Apache-2.0",
 	"dependencies": {
-		"@elysiumjs/core": "latest",
 		"commander": "^13.1.0",
 		"radash": "^12.1.0",
 		"reflect-metadata": "^0.2.2"
 	},
 	"devDependencies": {
-		"bun-types": "^1.2.13",
+		"bun-types": "^1.2.15",
 		"prettier": "^3.5.3",
 		"rimraf": "^6.0.1",
 		"type-fest": "^4.41.0"
 	},
 	"peerDependencies": {
+		"@elysiumjs/core": "latest",
 		"typescript": "^5.8.3"
 	}
 }

package/tsconfig.json

@@ -12,36 +12,37 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 {
-  "compilerOptions": {
-    // Environment setup & latest features
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleDetection": "force",
-    "allowJs": true,
-    "types": [
-      "bun-types",
-      "type-fest"
-    ],
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": false,
-    "forceConsistentCasingInFileNames": true,
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noPropertyAccessFromIndexSignature": false,
-  },
-  "exclude": [
-    "node_modules",
-    "dist",
-  ],
-}
+	"compilerOptions": {
+		// Environment setup & latest features
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"allowJs": true,
+		"types": ["bun-types", "type-fest"],
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": true,
+		// Compiler setup
+		"outDir": "dist",
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"declarationMap": false,
+		"declarationDir": "dist",
+		"rootDir": "src",
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": false,
+		"forceConsistentCasingInFileNames": true,
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noPropertyAccessFromIndexSignature": false
+	},
+	"exclude": ["node_modules", "dist"],
+	"include": ["src"]
+}