@boringnode/queue 0.0.1-alpha.3 → 0.0.1-alpha.4

package/build/index.d.ts

@@ -1,27 +1,375 @@
-import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig } from './job-Bd_c2lFK.js';
-export { J as Job, c as customBackoff, e as exponentialBackoff, f as fixedBackoff, l as linearBackoff } from './job-Bd_c2lFK.js';
+import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, b as JobFactory, c as Job, d as JobClass } from './index-C3_tlebh.js';
+export { e as customBackoff, f as exponentialBackoff, g as fixedBackoff, l as linearBackoff } from './index-C3_tlebh.js';
+import * as _poppinss_utils from '@poppinss/utils';
 
+/**
+ * Job processing worker.
+ *
+ * The Worker continuously polls queues for jobs and executes them
+ * with configurable concurrency. It handles:
+ * - Concurrent job execution via JobPool
+ * - Automatic retries with backoff strategies
+ * - Stalled job detection and recovery
+ * - Graceful shutdown on SIGINT/SIGTERM
+ *
+ * @example
+ * ```typescript
+ * import { Worker, redis } from '@boringnode/queue'
+ *
+ * const worker = new Worker({
+ *   default: 'redis',
+ *   adapters: { redis: redis() },
+ *   locations: ['./jobs/**\/*.js'],
+ *   worker: {
+ *     concurrency: 5,
+ *     idleDelay: '1s',
+ *   },
+ * })
+ *
+ * // Start processing jobs
+ * await worker.start(['default', 'emails'])
+ *
+ * // Or for testing, process one cycle at a time
+ * const cycle = await worker.processCycle(['default'])
+ * ```
+ */
 declare class Worker {
     #private;
+    /** Unique identifier for this worker instance */
     get id(): string;
+    /**
+     * Create a new worker instance.
+     *
+     * @param config - Queue configuration including adapter and worker settings
+     */
     constructor(config: QueueManagerConfig);
+    /**
+     * Initialize the worker (called automatically by `start()`).
+     *
+     * Sets up the QueueManager and adapter connection.
+     */
     init(): Promise<void>;
+    /**
+     * Start processing jobs from the specified queues.
+     *
+     * This method blocks until the worker is stopped (via `stop()` or signal).
+     * Jobs are processed concurrently up to the configured concurrency limit.
+     *
+     * @param queues - Queue names to process (default: ['default'])
+     *
+     * @example
+     * ```typescript
+     * // Process single queue
+     * await worker.start()
+     *
+     * // Process multiple queues (priority order)
+     * await worker.start(['high-priority', 'default', 'low-priority'])
+     * ```
+     */
     start(queues?: string[]): Promise<void>;
+    /**
+     * Stop the worker gracefully.
+     *
+     * Waits for all running jobs to complete before shutting down.
+     * Called automatically on SIGINT/SIGTERM if gracefulShutdown is enabled.
+     */
     stop(): Promise<void>;
+    /**
+     * Process a single cycle and return the result.
+     *
+     * Useful for testing or when you need fine-grained control.
+     * Each cycle may start new jobs, complete a job, or return idle.
+     *
+     * @param queues - Queue names to process
+     * @returns The cycle result, or null if the worker was stopped
+     *
+     * @example
+     * ```typescript
+     * const worker = new Worker(config)
+     *
+     * // Process cycles manually
+     * let cycle = await worker.processCycle(['default'])
+     * while (cycle) {
+     *   console.log('Cycle:', cycle.type)
+     *   cycle = await worker.processCycle(['default'])
+     * }
+     * ```
+     */
     processCycle(queues: string[]): Promise<WorkerCycle | null>;
+    /**
+     * Generator that yields worker cycle events.
+     *
+     * Low-level API for processing jobs. Yields events for:
+     * - `started`: A new job began execution
+     * - `completed`: A job finished (success or failure)
+     * - `idle`: No jobs available, suggest waiting
+     * - `error`: An error occurred during processing
+     *
+     * @param queues - Queue names to process
+     * @yields WorkerCycle events
+     *
+     * @example
+     * ```typescript
+     * for await (const cycle of worker.process(['default'])) {
+     *   switch (cycle.type) {
+     *     case 'started':
+     *       console.log(`Started job ${cycle.job.id}`)
+     *       break
+     *     case 'completed':
+     *       console.log(`Completed job ${cycle.job.id}`)
+     *       break
+     *     case 'idle':
+     *       await sleep(cycle.suggestedDelay)
+     *       break
+     *   }
+     * }
+     * ```
+     */
     process(queues: string[]): AsyncGenerator<WorkerCycle, void, unknown>;
 }
 
+/**
+ * Central configuration and adapter management for the queue system.
+ *
+ * The QueueManager is responsible for:
+ * - Initializing adapters and job registration
+ * - Providing adapter instances to workers and dispatchers
+ * - Managing retry configuration across global, queue, and job levels
+ *
+ * @example
+ * ```typescript
+ * import { QueueManager, redis } from '@boringnode/queue'
+ *
+ * await QueueManager.init({
+ *   default: 'redis',
+ *   adapters: {
+ *     redis: redis({ host: 'localhost' }),
+ *   },
+ *   locations: ['./jobs/**\/*.js'],
+ *   retry: {
+ *     maxRetries: 3,
+ *     backoff: exponentialBackoff(),
+ *   },
+ * })
+ *
+ * // Get the default adapter
+ * const adapter = QueueManager.use()
+ *
+ * // Clean up when done
+ * await QueueManager.destroy()
+ * ```
+ */
 declare class QueueManagerSingleton {
     #private;
+    /**
+     * Initialize the queue system with the given configuration.
+     *
+     * This must be called before using the queue system. It:
+     * - Validates the configuration
+     * - Registers adapters
+     * - Auto-discovers and registers job classes from `locations`
+     *
+     * @param config - The queue configuration
+     * @returns This instance for chaining
+     * @throws {E_CONFIGURATION_ERROR} If the configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * await QueueManager.init({
+     *   default: 'redis',
+     *   adapters: {
+     *     redis: redis(),
+     *     postgres: knex(pgConfig),
+     *   },
+     *   locations: ['./jobs/**\/*.js'],
+     * })
+     * ```
+     */
     init(config: QueueManagerConfig): Promise<this>;
+    /**
+     * Get an adapter instance by name.
+     *
+     * Adapter instances are cached and reused. If no name is provided,
+     * the default adapter is returned.
+     *
+     * @param adapter - Adapter name (optional, defaults to the default adapter)
+     * @returns The adapter instance
+     * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called
+     * @throws {E_CONFIGURATION_ERROR} If the adapter is not registered
+     * @throws {E_ADAPTER_INIT_ERROR} If the adapter factory throws
+     *
+     * @example
+     * ```typescript
+     * // Get default adapter
+     * const adapter = QueueManager.use()
+     *
+     * // Get specific adapter
+     * const redisAdapter = QueueManager.use('redis')
+     * ```
+     */
     use(adapter?: string): Adapter;
     /**
-     * Priority: job > queue > global
+     * Get the merged retry configuration for a job.
+     *
+     * Configuration is merged with priority: job > queue > global.
+     * This allows specific jobs or queues to override global defaults.
+     *
+     * @param queue - The queue name
+     * @param jobRetryConfig - Optional job-level retry config
+     * @returns The merged retry configuration
+     *
+     * @example
+     * ```typescript
+     * // Global: maxRetries=3, Queue: maxRetries=5, Job: maxRetries=1
+     * // Result: maxRetries=1 (job wins)
+     * const config = QueueManager.getMergedRetryConfig('emails', { maxRetries: 1 })
+     * ```
      */
     getMergedRetryConfig(queue: string, jobRetryConfig?: RetryConfig): RetryConfig;
+    /**
+     * Get the configured job factory for custom instantiation.
+     *
+     * @returns The job factory function, or undefined if not configured
+     */
+    getJobFactory(): JobFactory | undefined;
+    /**
+     * Clean up all adapter instances and reset state.
+     *
+     * Call this when shutting down the application or when
+     * you need to reinitialize with a new configuration.
+     *
+     * @example
+     * ```typescript
+     * // On application shutdown
+     * await QueueManager.destroy()
+     * ```
+     */
     destroy(): Promise<void>;
 }
+/** Global queue manager singleton */
 declare const QueueManager: QueueManagerSingleton;
 
-export { QueueManager, Worker };
+/**
+ * Job class registry.
+ *
+ * The Locator maintains a mapping of job names to their classes,
+ * allowing the Worker to instantiate jobs by name when processing.
+ *
+ * Jobs are typically registered automatically via `QueueManager.init()`
+ * using the `locations` config option, but can also be registered manually.
+ *
+ * @example
+ * ```typescript
+ * import { Locator } from '@boringnode/queue'
+ * import SendEmailJob from './jobs/send_email_job.js'
+ *
+ * // Manual registration
+ * Locator.register('SendEmailJob', SendEmailJob)
+ *
+ * // Auto-registration via glob (used by QueueManager.init)
+ * await Locator.registerFromGlob(['./jobs/**\/*.js'])
+ *
+ * // Retrieve a job class
+ * const JobClass = Locator.getOrThrow('SendEmailJob')
+ * ```
+ */
+declare class LocatorSingleton {
+    #private;
+    /**
+     * Register a job class with a given name.
+     *
+     * @param name - The job name (usually the class name)
+     * @param JobClass - The job class constructor
+     *
+     * @example
+     * ```typescript
+     * Locator.register('SendEmailJob', SendEmailJob)
+     * ```
+     */
+    register<T extends Job>(name: string, JobClass: JobClass<T>): void;
+    /**
+     * Auto-register job classes from files matching glob patterns.
+     *
+     * Each file should have a default export that is a Job class.
+     * The class name is used as the registration name.
+     *
+     * @param patterns - Glob patterns to match job files
+     * @returns Number of jobs successfully registered
+     *
+     * @example
+     * ```typescript
+     * const count = await Locator.registerFromGlob([
+     *   './jobs/**\/*.js',
+     *   './app/jobs/**\/*.ts'
+     * ])
+     * console.log(`Registered ${count} jobs`)
+     * ```
+     */
+    registerFromGlob(patterns: string[]): Promise<number>;
+    /**
+     * Get a job class by name.
+     *
+     * @param name - The job name to look up
+     * @returns The job class, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const JobClass = Locator.get('SendEmailJob')
+     * if (JobClass) {
+     *   const instance = new JobClass(payload)
+     * }
+     * ```
+     */
+    get<T extends Job = Job>(name: string): JobClass<T> | undefined;
+    /**
+     * Get a job class by name, throwing if not found.
+     *
+     * @param name - The job name to look up
+     * @returns The job class
+     * @throws {E_JOB_NOT_FOUND} If the job is not registered
+     *
+     * @example
+     * ```typescript
+     * const JobClass = Locator.getOrThrow('SendEmailJob')
+     * const instance = new JobClass(payload)
+     * ```
+     */
+    getOrThrow<T extends Job = Job>(name: string): JobClass<T>;
+    /**
+     * Remove all registered jobs.
+     *
+     * Primarily useful for testing.
+     */
+    clear(): void;
+}
+/** Global job class registry singleton */
+declare const Locator: LocatorSingleton;
+
+declare const E_INVALID_DURATION_EXPRESSION: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_BASE_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_MAX_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_MULTIPLIER: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_CONFIGURATION_ERROR: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_JOB_NOT_FOUND: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_JOB_MAX_ATTEMPTS_REACHED: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_JOB_TIMEOUT: new (args: [jobName: string, timeout: number], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_QUEUE_NOT_INITIALIZED: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_ADAPTER_INIT_ERROR: new (args: [adapterName: string, originalMessage: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_NO_JOBS_FOUND: new (args: [patterns: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+
+declare const exceptions_E_ADAPTER_INIT_ERROR: typeof E_ADAPTER_INIT_ERROR;
+declare const exceptions_E_CONFIGURATION_ERROR: typeof E_CONFIGURATION_ERROR;
+declare const exceptions_E_INVALID_BASE_DELAY: typeof E_INVALID_BASE_DELAY;
+declare const exceptions_E_INVALID_DURATION_EXPRESSION: typeof E_INVALID_DURATION_EXPRESSION;
+declare const exceptions_E_INVALID_MAX_DELAY: typeof E_INVALID_MAX_DELAY;
+declare const exceptions_E_INVALID_MULTIPLIER: typeof E_INVALID_MULTIPLIER;
+declare const exceptions_E_JOB_MAX_ATTEMPTS_REACHED: typeof E_JOB_MAX_ATTEMPTS_REACHED;
+declare const exceptions_E_JOB_NOT_FOUND: typeof E_JOB_NOT_FOUND;
+declare const exceptions_E_JOB_TIMEOUT: typeof E_JOB_TIMEOUT;
+declare const exceptions_E_NO_JOBS_FOUND: typeof E_NO_JOBS_FOUND;
+declare const exceptions_E_QUEUE_NOT_INITIALIZED: typeof E_QUEUE_NOT_INITIALIZED;
+declare namespace exceptions {
+  export { exceptions_E_ADAPTER_INIT_ERROR as E_ADAPTER_INIT_ERROR, exceptions_E_CONFIGURATION_ERROR as E_CONFIGURATION_ERROR, exceptions_E_INVALID_BASE_DELAY as E_INVALID_BASE_DELAY, exceptions_E_INVALID_DURATION_EXPRESSION as E_INVALID_DURATION_EXPRESSION, exceptions_E_INVALID_MAX_DELAY as E_INVALID_MAX_DELAY, exceptions_E_INVALID_MULTIPLIER as E_INVALID_MULTIPLIER, exceptions_E_JOB_MAX_ATTEMPTS_REACHED as E_JOB_MAX_ATTEMPTS_REACHED, exceptions_E_JOB_NOT_FOUND as E_JOB_NOT_FOUND, exceptions_E_JOB_TIMEOUT as E_JOB_TIMEOUT, exceptions_E_NO_JOBS_FOUND as E_NO_JOBS_FOUND, exceptions_E_QUEUE_NOT_INITIALIZED as E_QUEUE_NOT_INITIALIZED };
+}
+
+export { Job, Locator, QueueManager, Worker, exceptions as errors };