@igniter-js/jobs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1107 @@
+import { IgniterLogger, IgniterError } from '@igniter-js/core';
+import { IgniterTelemetry } from '@igniter-js/telemetry';
+import { n as IgniterJobDefinition, o as IgniterCronDefinition, p as IgniterQueueConfig, I as IgniterJobsAdapter, q as IgniterJobScopeOptions, r as IgniterJobActorOptions, l as AdapterJobHandler } from './adapter-CcQCatSa.js';
+export { A as AdapterDispatchParams, a as AdapterScheduleParams, k as AdapterWorkerConfig, m as AdapterWorkerHandle, y as IgniterCronFailureHook, u as IgniterCronHandler, v as IgniterCronHandlerContext, Q as IgniterJobActorEntry, z as IgniterJobBackoff, x as IgniterJobCompleteHook, M as IgniterJobCompletedPayload, g as IgniterJobCounts, J as IgniterJobEnqueuedPayload, G as IgniterJobEventContext, i as IgniterJobEventHandler, H as IgniterJobEventPayload, F as IgniterJobEventType, N as IgniterJobFailedPayload, w as IgniterJobFailureHook, s as IgniterJobHandler, t as IgniterJobHandlerContext, b as IgniterJobInfo, B as IgniterJobLimiter, d as IgniterJobLog, L as IgniterJobProgressPayload, O as IgniterJobRetryingPayload, P as IgniterJobScopeEntry, h as IgniterJobSearchResult, K as IgniterJobStartedPayload, c as IgniterJobStatus, j as IgniterJobUnsubscribeFn, D as IgniterJobsSearchFilter, f as IgniterQueueCleanOptions, e as IgniterQueueInfo, C as IgniterQueuesSearchFilter, E as IgniterWorkersSearchFilter } from './adapter-CcQCatSa.js';
+
+/**
+ * @fileoverview Configuration types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/config
+ */
+
+/**
+ * Full configuration for IgniterJobs.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TQueues - Map of queue names to queue configs
+ * @typeParam TScope - Scope key (only one allowed)
+ * @typeParam TActor - Actor key (only one allowed)
+ */
+interface IgniterJobsConfig<TContext = unknown, TQueues extends Record<string, IgniterQueueConfig<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
+    /**
+     * Queue adapter (required).
+     */
+    adapter: IgniterJobsAdapter;
+    /**
+     * Application context provider (required).
+     * Called for each job to get the context.
+     */
+    context: () => TContext | Promise<TContext>;
+    /**
+     * Queue configurations.
+     */
+    queues: TQueues;
+    /**
+     * Scope definition (only one allowed).
+     * Used for multi-tenancy.
+     */
+    scope?: TScope extends never ? never : {
+        key: TScope;
+        options?: IgniterJobScopeOptions;
+    };
+    /**
+     * Actor definition (only one allowed).
+     * Used for auditing.
+     */
+    actor?: TActor extends never ? never : {
+        key: TActor;
+        options?: IgniterJobActorOptions;
+    };
+    /**
+     * Telemetry instance for observability.
+     */
+    telemetry?: IgniterTelemetry;
+    /**
+     * Custom logger.
+     */
+    logger?: IgniterLogger;
+    /**
+     * Default job options applied to all jobs.
+     */
+    defaults?: {
+        /**
+         * Default retry configuration.
+         */
+        retry?: {
+            attempts?: number;
+            backoff?: {
+                type: 'exponential' | 'fixed' | 'linear';
+                delay: number;
+                maxDelay?: number;
+            };
+        };
+        /**
+         * Default timeout in milliseconds.
+         */
+        timeout?: number;
+        /**
+         * Default remove on complete config.
+         */
+        removeOnComplete?: boolean | {
+            count?: number;
+            age?: number;
+        };
+        /**
+         * Default remove on fail config.
+         */
+        removeOnFail?: boolean | {
+            count?: number;
+            age?: number;
+        };
+    };
+}
+/**
+ * Builder state for IgniterJobs configuration.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TQueues - Map of queue names to queue configs
+ * @typeParam TScope - Scope key
+ * @typeParam TActor - Actor key
+ */
+interface IgniterJobsBuilderState<TContext = unknown, TQueues extends Record<string, IgniterQueueConfig<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
+    adapter?: IgniterJobsAdapter;
+    context?: () => TContext | Promise<TContext>;
+    queues: TQueues;
+    scope?: {
+        key: TScope;
+        options?: IgniterJobScopeOptions;
+    };
+    actor?: {
+        key: TActor;
+        options?: IgniterJobActorOptions;
+    };
+    telemetry?: IgniterTelemetry;
+    logger?: IgniterLogger;
+    defaults?: IgniterJobsConfig<TContext>['defaults'];
+}
+/**
+ * Builder state for IgniterQueue configuration.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TJobs - Map of job names to definitions
+ * @typeParam TCrons - Map of cron names to definitions
+ */
+interface IgniterQueueBuilderState<TContext = unknown, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>> = Record<string, never>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>> = Record<string, never>> {
+    name: string;
+    jobs: TJobs;
+    crons: TCrons;
+}
+
+/**
+ * @fileoverview Worker types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/worker
+ */
+/**
+ * Worker handle returned from worker.start().
+ */
+interface IgniterWorkerHandle {
+    /**
+     * Unique worker ID.
+     */
+    readonly id: string;
+    /**
+     * Pause the worker (stops processing new jobs).
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the worker.
+     */
+    resume(): Promise<void>;
+    /**
+     * Close the worker gracefully.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if worker is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Check if worker is paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Get worker metrics.
+     */
+    getMetrics(): Promise<IgniterWorkerMetrics>;
+}
+/**
+ * Worker metrics.
+ */
+interface IgniterWorkerMetrics {
+    /**
+     * Total jobs processed.
+     */
+    processed: number;
+    /**
+     * Total jobs failed.
+     */
+    failed: number;
+    /**
+     * Total jobs completed successfully.
+     */
+    completed: number;
+    /**
+     * Currently active jobs.
+     */
+    active: number;
+    /**
+     * Worker uptime in milliseconds.
+     */
+    uptime: number;
+}
+/**
+ * Worker builder state.
+ */
+interface IgniterWorkerBuilderState {
+    /**
+     * Queue names to process.
+     */
+    queues: string[];
+    /**
+     * Concurrency per queue.
+     */
+    concurrency: number;
+    /**
+     * Lock duration in milliseconds.
+     */
+    lockDuration?: number;
+    /**
+     * Rate limiter configuration.
+     */
+    limiter?: {
+        max: number;
+        duration: number;
+    };
+    /**
+     * Callback when worker becomes idle.
+     */
+    onIdle?: () => void;
+}
+
+/**
+ * @fileoverview Builder for creating IgniterJobs instances
+ * @module @igniter-js/jobs/builders/igniter-jobs
+ *
+ * @description
+ * Provides a fluent builder API for configuring and creating IgniterJobs instances.
+ * Supports adapter configuration, context provider, queues, scopes, actors, and telemetry.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterJobs, IgniterQueue } from '@igniter-js/jobs'
+ * import { BullMQAdapter } from '@igniter-js/jobs/adapters'
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis()
+ *
+ * const emailQueue = IgniterQueue.create<AppContext>('email')
+ *   .addJob('sendWelcome', { ... })
+ *   .build()
+ *
+ * const jobs = IgniterJobs.create<AppContext>()
+ *   .withAdapter(BullMQAdapter.create({ redis }))
+ *   .withContext(() => ({ db, mailer }))
+ *   .addQueue(emailQueue)
+ *   .addScope('organization')
+ *   .addActor('user')
+ *   .build()
+ * ```
+ */
+
+/**
+ * Builder for creating IgniterJobs instances.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TQueues - Map of queue names to queue configs
+ * @typeParam TScope - Scope key (only one allowed)
+ * @typeParam TActor - Actor key (only one allowed)
+ */
+declare class IgniterJobsBuilder<TContext = unknown, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
+    private readonly state;
+    private constructor();
+    /**
+     * Create a new IgniterJobs builder.
+     *
+     * @returns A new IgniterJobsBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const jobs = IgniterJobs.create<AppContext>()
+     *   .withAdapter(...)
+     *   .build()
+     * ```
+     */
+    static create<TContext = unknown>(): IgniterJobsBuilder<TContext>;
+    /**
+     * Configure the queue adapter (required).
+     *
+     * @param adapter - The queue adapter (e.g., BullMQAdapter)
+     * @returns The builder with adapter configured
+     *
+     * @example
+     * ```typescript
+     * .withAdapter(BullMQAdapter.create({ redis }))
+     * ```
+     */
+    withAdapter(adapter: IgniterJobsAdapter): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    /**
+     * Configure the application context provider (required).
+     * This function is called for each job to provide the application context.
+     *
+     * @param contextFn - Function that returns the application context
+     * @returns The builder with context configured
+     *
+     * @example
+     * ```typescript
+     * .withContext(() => ({
+     *   db: prisma,
+     *   mailer: mailerService,
+     *   cache: redis,
+     * }))
+     * ```
+     */
+    withContext(contextFn: () => TContext | Promise<TContext>): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    /**
+     * Add a queue to the jobs instance.
+     *
+     * @param queue - Queue configuration from IgniterQueue.create().build()
+     * @returns The builder with the queue added
+     *
+     * @example
+     * ```typescript
+     * const emailQueue = IgniterQueue.create<AppContext>('email')
+     *   .addJob('sendWelcome', { ... })
+     *   .build()
+     *
+     * const jobs = IgniterJobs.create<AppContext>()
+     *   .addQueue(emailQueue)
+     *   .build()
+     * ```
+     */
+    addQueue<TQueueState extends IgniterQueueBuilderState<TContext, any, any>>(queue: TQueueState): IgniterJobsBuilder<TContext, TQueues & {
+        [K in TQueueState['name']]: TQueueState;
+    }, TScope, TActor>;
+    /**
+     * Add a scope for multi-tenancy (only one scope allowed).
+     * Scopes are used to isolate jobs by organization, tenant, etc.
+     *
+     * @param key - Scope key (e.g., 'organization', 'tenant')
+     * @param options - Optional scope configuration
+     * @returns The builder with scope configured
+     *
+     * @example
+     * ```typescript
+     * .addScope('organization', { required: true })
+     * ```
+     */
+    addScope<TScopeKey extends string>(key: TScope extends never ? TScopeKey : never, options?: IgniterJobScopeOptions): IgniterJobsBuilder<TContext, TQueues, TScopeKey, TActor>;
+    /**
+     * Add an actor for auditing (only one actor type allowed).
+     * Actors are used to track who initiated jobs.
+     *
+     * @param key - Actor key (e.g., 'user', 'system')
+     * @param options - Optional actor configuration
+     * @returns The builder with actor configured
+     *
+     * @example
+     * ```typescript
+     * .addActor('user', { description: 'The user who initiated the job' })
+     * ```
+     */
+    addActor<TActorKey extends string>(key: TActor extends never ? TActorKey : never, options?: IgniterJobActorOptions): IgniterJobsBuilder<TContext, TQueues, TScope, TActorKey>;
+    /**
+     * Configure telemetry for observability (optional).
+     *
+     * @param telemetry - IgniterTelemetry instance
+     * @returns The builder with telemetry configured
+     *
+     * @example
+     * ```typescript
+     * .withTelemetry(telemetry)
+     * ```
+     */
+    withTelemetry(telemetry: IgniterTelemetry): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    /**
+     * Configure a custom logger (optional).
+     *
+     * @param logger - Logger instance
+     * @returns The builder with logger configured
+     *
+     * @example
+     * ```typescript
+     * .withLogger(customLogger)
+     * ```
+     */
+    withLogger(logger: IgniterLogger): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    /**
+     * Configure default job options applied to all jobs.
+     *
+     * @param defaults - Default job configuration
+     * @returns The builder with defaults configured
+     *
+     * @example
+     * ```typescript
+     * .withDefaults({
+     *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
+     *   timeout: 30000,
+     *   removeOnComplete: { count: 1000 },
+     * })
+     * ```
+     */
+    withDefaults(defaults: {
+        retry?: {
+            attempts?: number;
+            backoff?: {
+                type: 'exponential' | 'fixed' | 'linear';
+                delay: number;
+                maxDelay?: number;
+            };
+        };
+        timeout?: number;
+        removeOnComplete?: boolean | {
+            count?: number;
+            age?: number;
+        };
+        removeOnFail?: boolean | {
+            count?: number;
+            age?: number;
+        };
+    }): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    /**
+     * Build the IgniterJobs instance.
+     * Validates configuration and returns a fully typed jobs instance.
+     *
+     * @returns The IgniterJobs instance with proxy for typed access
+     *
+     * @throws {IgniterJobsError} If adapter is not configured
+     * @throws {IgniterJobsError} If context is not configured
+     * @throws {IgniterJobsError} If no queues are defined
+     *
+     * @example
+     * ```typescript
+     * const jobs = IgniterJobs.create<AppContext>()
+     *   .withAdapter(adapter)
+     *   .withContext(() => context)
+     *   .addQueue(emailQueue)
+     *   .build()
+     *
+     * // Now use with full type safety
+     * await jobs.email.sendWelcome.dispatch({ userId: '123' })
+     * ```
+     */
+    build(): IgniterJobsInstance<TContext, TQueues, TScope, TActor>;
+}
+/**
+ * Type for the built IgniterJobs instance.
+ * Provides typed access to queues, jobs, and management APIs.
+ */
+type IgniterJobsInstance<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> = {
+    [QueueName in keyof TQueues]: IgniterQueueProxy<TContext, TQueues[QueueName]['jobs'], TQueues[QueueName]['crons'], TScope, TActor>;
+} & {
+    subscribe: IgniterJobsGlobalSubscribe;
+    search: IgniterJobsSearch;
+    worker: IgniterJobsWorkerBuilder<TQueues>;
+    shutdown: () => Promise<void>;
+};
+/**
+ * Queue proxy type providing access to jobs and queue management.
+ */
+type IgniterQueueProxy<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>>, TScope extends string, TActor extends string> = {
+    [JobName in keyof TJobs]: IgniterJobProxy<TContext, TJobs[JobName] extends IgniterJobDefinition<TContext, infer TInput, infer TOutput> ? TInput : unknown, TJobs[JobName] extends IgniterJobDefinition<TContext, infer TInput, infer TOutput> ? TOutput : unknown, TScope, TActor>;
+} & {
+    subscribe: (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
+    list: (options?: {
+        status?: string[];
+        limit?: number;
+    }) => Promise<any[]>;
+    get: () => IgniterQueueManagement;
+};
+/**
+ * Job proxy type providing dispatch, schedule, and job management.
+ */
+interface IgniterJobProxy<TContext, TInput, TOutput, TScope extends string, TActor extends string> {
+    dispatch: IgniterJobDispatch<TInput, TScope, TActor>;
+    schedule: IgniterJobSchedule<TInput, TScope, TActor>;
+    get: (jobId: string) => IgniterJobManagement;
+    many: (jobIds: string[]) => IgniterJobBatchManagement;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    subscribe: (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
+}
+/**
+ * Job dispatch function type.
+ */
+type IgniterJobDispatch<TInput, TScope extends string, TActor extends string> = (input: TInput, options?: IgniterJobDispatchOptions<TScope, TActor>) => Promise<string>;
+/**
+ * Job dispatch options.
+ */
+interface IgniterJobDispatchOptions<TScope extends string, TActor extends string> {
+    jobId?: string;
+    delay?: number;
+    priority?: number;
+    scope?: TScope extends never ? never : {
+        id: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+    actor?: TActor extends never ? never : {
+        id?: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+}
+/**
+ * Job schedule function type.
+ */
+type IgniterJobSchedule<TInput, TScope extends string, TActor extends string> = (params: {
+    input: TInput;
+    at?: Date;
+    cron?: string;
+    every?: number;
+    timezone?: string;
+    jobId?: string;
+    scope?: TScope extends never ? never : {
+        id: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+    actor?: TActor extends never ? never : {
+        id?: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+}) => Promise<string>;
+/**
+ * Single job management operations.
+ */
+interface IgniterJobManagement {
+    retrieve: () => Promise<any>;
+    retry: () => Promise<void>;
+    remove: () => Promise<void>;
+    state: () => Promise<string | null>;
+    progress: () => Promise<number>;
+    logs: () => Promise<any[]>;
+    promote: () => Promise<void>;
+    move: (state: 'failed' | 'completed', reason?: string) => Promise<void>;
+}
+/**
+ * Batch job management operations.
+ */
+interface IgniterJobBatchManagement {
+    retry: () => Promise<void>;
+    remove: () => Promise<void>;
+}
+/**
+ * Queue management operations.
+ */
+interface IgniterQueueManagement {
+    retrieve: () => Promise<any>;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    drain: () => Promise<number>;
+    clean: (options: {
+        status: string | string[];
+        olderThan?: number;
+        limit?: number;
+    }) => Promise<number>;
+    obliterate: (options?: {
+        force?: boolean;
+    }) => Promise<void>;
+    retryAll: () => Promise<number>;
+}
+/**
+ * Global subscribe function.
+ */
+type IgniterJobsGlobalSubscribe = (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
+/**
+ * Search function.
+ */
+interface IgniterJobsSearch {
+    (target: 'queues', filter?: any): Promise<any[]>;
+    (target: 'jobs', filter?: any): Promise<any[]>;
+    (target: 'workers', filter?: any): Promise<any[]>;
+}
+/**
+ * Worker builder interface.
+ */
+interface IgniterJobsWorkerBuilder<TQueues> {
+    create: () => IgniterJobsWorkerConfig<TQueues>;
+}
+/**
+ * Worker configuration builder.
+ */
+interface IgniterJobsWorkerConfig<TQueues> {
+    forQueues: (...queues: (keyof TQueues)[]) => IgniterJobsWorkerConfig<TQueues>;
+    withConcurrency: (concurrency: number) => IgniterJobsWorkerConfig<TQueues>;
+    withLockDuration: (duration: number) => IgniterJobsWorkerConfig<TQueues>;
+    withLimiter: (config: {
+        max: number;
+        duration: number;
+    }) => IgniterJobsWorkerConfig<TQueues>;
+    onIdle: (callback: () => void) => IgniterJobsWorkerConfig<TQueues>;
+    start: () => Promise<any>;
+}
+/**
+ * Convenience alias for IgniterJobsBuilder.create().
+ *
+ * @example
+ * ```typescript
+ * import { IgniterJobs } from '@igniter-js/jobs'
+ *
+ * const jobs = IgniterJobs.create<AppContext>()
+ *   .withAdapter(adapter)
+ *   .withContext(() => context)
+ *   .addQueue(emailQueue)
+ *   .build()
+ * ```
+ */
+declare const IgniterJobs: {
+    create: typeof IgniterJobsBuilder.create;
+};
+
+/**
+ * @fileoverview Builder for creating IgniterQueue instances
+ * @module @igniter-js/jobs/builders/igniter-queue
+ *
+ * @description
+ * Provides a fluent builder API for defining queues with jobs and cron jobs.
+ * Queues group related jobs together and provide type-safe job definitions.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterQueue } from '@igniter-js/jobs'
+ * import { z } from 'zod'
+ *
+ * const emailQueue = IgniterQueue.create<AppContext>('email')
+ *   .addJob('sendWelcome', {
+ *     input: z.object({
+ *       userId: z.string(),
+ *       email: z.string().email(),
+ *     }),
+ *     retry: { attempts: 3 },
+ *     handler: async (ctx) => {
+ *       await ctx.context.mailer.send({
+ *         to: ctx.input.email,
+ *         template: 'welcome',
+ *       })
+ *     },
+ *   })
+ *   .addCron('cleanupExpired', {
+ *     expression: '0 0 * * *',
+ *     handler: async (ctx) => {
+ *       await ctx.context.db.cleanup.expiredSessions()
+ *     },
+ *   })
+ *   .build()
+ * ```
+ */
+
+/**
+ * Builder for creating queue configurations.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TJobs - Map of job names to definitions
+ * @typeParam TCrons - Map of cron names to definitions
+ */
+declare class IgniterQueueBuilder<TContext = unknown, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>> = Record<string, never>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>> = Record<string, never>> {
+    private readonly state;
+    private constructor();
+    /**
+     * Create a new queue builder.
+     *
+     * @param name - Queue name (kebab-case, e.g., 'email', 'payment-processing')
+     * @returns A new IgniterQueueBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const emailQueue = IgniterQueue.create<AppContext>('email')
+     * ```
+     */
+    static create<TContext = unknown>(name: string): IgniterQueueBuilder<TContext>;
+    /**
+     * Add a job definition to the queue.
+     *
+     * @param name - Job name (camelCase, e.g., 'sendWelcome', 'processPayment')
+     * @param definition - Job definition with input schema, handler, retry config, etc.
+     * @returns The builder with the new job added
+     *
+     * @example
+     * ```typescript
+     * .addJob('sendWelcome', {
+     *   input: z.object({
+     *     userId: z.string(),
+     *     email: z.string().email(),
+     *   }),
+     *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
+     *   handler: async (ctx) => {
+     *     await ctx.context.mailer.send({
+     *       to: ctx.input.email,
+     *       template: 'welcome',
+     *     })
+     *   },
+     * })
+     * ```
+     */
+    addJob<TName extends string, TInput, TOutput = void>(name: TName extends keyof TJobs ? never : TName, definition: IgniterJobDefinition<TContext, TInput, TOutput>): IgniterQueueBuilder<TContext, TJobs & {
+        [K in TName]: IgniterJobDefinition<TContext, TInput, TOutput>;
+    }, TCrons>;
+    /**
+     * Add a cron job definition to the queue.
+     *
+     * @param name - Cron job name (camelCase)
+     * @param definition - Cron definition with expression, handler, etc.
+     * @returns The builder with the new cron added
+     *
+     * @example
+     * ```typescript
+     * .addCron('cleanupExpired', {
+     *   expression: '0 0 * * *', // Every day at midnight
+     *   timezone: 'America/New_York',
+     *   handler: async (ctx) => {
+     *     await ctx.context.db.cleanup.expiredSessions()
+     *   },
+     * })
+     * ```
+     */
+    addCron<TName extends string, TOutput = void>(name: TName extends keyof TCrons ? never : TName, definition: IgniterCronDefinition<TContext, TOutput>): IgniterQueueBuilder<TContext, TJobs, TCrons & {
+        [K in TName]: IgniterCronDefinition<TContext, TOutput>;
+    }>;
+    /**
+     * Build the queue configuration.
+     *
+     * @returns The queue configuration ready to be registered with IgniterJobs
+     *
+     * @example
+     * ```typescript
+     * const emailQueue = IgniterQueue.create<AppContext>('email')
+     *   .addJob('sendWelcome', { ... })
+     *   .build()
+     * ```
+     */
+    build(): IgniterQueueBuilderState<TContext, TJobs, TCrons>;
+}
+/**
+ * Convenience alias for IgniterQueueBuilder.create().
+ * Use this to create queue configurations with a fluent API.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterQueue } from '@igniter-js/jobs'
+ *
+ * const emailQueue = IgniterQueue.create<AppContext>('email')
+ *   .addJob('sendWelcome', { ... })
+ *   .build()
+ * ```
+ */
+declare const IgniterQueue: {
+    create: typeof IgniterQueueBuilder.create;
+};
+
+/**
+ * @fileoverview Builder for creating workers
+ * @module @igniter-js/jobs/builders/igniter-worker
+ */
+
+/**
+ * Builder for configuring and starting workers.
+ *
+ * @example
+ * ```typescript
+ * const worker = await jobs.worker
+ *   .create()
+ *   .forQueues('email', 'payment')
+ *   .withConcurrency(10)
+ *   .withLimiter({ max: 100, duration: 60000 })
+ *   .start()
+ * ```
+ */
+declare class IgniterWorkerBuilder {
+    private state;
+    private adapter;
+    private jobHandler;
+    private availableQueues;
+    constructor(adapter: IgniterJobsAdapter, jobHandler: AdapterJobHandler, availableQueues: string[]);
+    /**
+     * Specify which queues this worker should process.
+     * If not called, worker processes all queues.
+     *
+     * @param queues - Queue names to process
+     * @returns The builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .forQueues('email', 'payment')
+     * ```
+     */
+    forQueues(...queues: string[]): this;
+    /**
+     * Set the concurrency level (jobs processed in parallel per queue).
+     *
+     * @param concurrency - Number of parallel jobs
+     * @returns The builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withConcurrency(10)
+     * ```
+     */
+    withConcurrency(concurrency: number): this;
+    /**
+     * Set the lock duration in milliseconds.
+     * Jobs are locked for this duration while being processed.
+     *
+     * @param duration - Lock duration in milliseconds
+     * @returns The builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withLockDuration(30000) // 30 seconds
+     * ```
+     */
+    withLockDuration(duration: number): this;
+    /**
+     * Configure rate limiting for the worker.
+     *
+     * @param config - Rate limiter configuration
+     * @returns The builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withLimiter({ max: 100, duration: 60000 }) // 100 jobs per minute
+     * ```
+     */
+    withLimiter(config: {
+        max: number;
+        duration: number;
+    }): this;
+    /**
+     * Set a callback to be called when the worker becomes idle.
+     *
+     * @param callback - Idle callback
+     * @returns The builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .onIdle(() => console.log('Worker is idle'))
+     * ```
+     */
+    onIdle(callback: () => void): this;
+    /**
+     * Start the worker.
+     *
+     * @returns Worker handle for management
+     *
+     * @example
+     * ```typescript
+     * const worker = await jobs.worker
+     *   .create()
+     *   .forQueues('email')
+     *   .start()
+     *
+     * // Later
+     * await worker.pause()
+     * await worker.close()
+     * ```
+     */
+    start(): Promise<IgniterWorkerHandle>;
+}
+
+/**
+ * @fileoverview IgniterJobs runtime class with proxy-based API
+ * @module @igniter-js/jobs/core/igniter-jobs
+ */
+
+/**
+ * Configuration passed to IgniterJobsRuntime.
+ */
+interface IgniterJobsRuntimeConfig<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> {
+    adapter: IgniterJobsAdapter;
+    context: () => TContext | Promise<TContext>;
+    queues: TQueues;
+    scope?: {
+        key: TScope;
+        options?: IgniterJobScopeOptions;
+    };
+    actor?: {
+        key: TActor;
+        options?: IgniterJobActorOptions;
+    };
+    telemetry?: IgniterTelemetry;
+    logger?: IgniterLogger;
+    defaults?: {
+        retry?: {
+            attempts?: number;
+            backoff?: any;
+        };
+        timeout?: number;
+        removeOnComplete?: boolean | {
+            count?: number;
+            age?: number;
+        };
+        removeOnFail?: boolean | {
+            count?: number;
+            age?: number;
+        };
+    };
+}
+/**
+ * Main runtime class for IgniterJobs.
+ * Creates proxy-based API for type-safe job access.
+ */
+declare class IgniterJobsRuntime<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> {
+    private readonly config;
+    private readonly queueNames;
+    constructor(config: IgniterJobsRuntimeConfig<TContext, TQueues, TScope, TActor>);
+    /**
+     * Create the main proxy that provides queue access and global methods.
+     */
+    private createProxy;
+    /**
+     * Create a proxy for a specific queue.
+     */
+    private createQueueProxy;
+    /**
+     * Create a proxy for a specific job.
+     */
+    private createJobProxy;
+    /**
+     * Dispatch a job.
+     */
+    private dispatchJob;
+    /**
+     * Schedule a job for future execution.
+     */
+    private scheduleJob;
+    /**
+     * Create job management methods.
+     */
+    private createJobManagement;
+    /**
+     * Create batch job management methods.
+     */
+    private createJobBatchManagement;
+    /**
+     * Create queue management methods.
+     */
+    private createQueueManagement;
+    /**
+     * Pause a specific job type.
+     */
+    private pauseJobType;
+    /**
+     * Resume a specific job type.
+     */
+    private resumeJobType;
+    /**
+     * Subscribe to events for a specific job.
+     */
+    private subscribeToJob;
+    /**
+     * Create queue-level subscribe.
+     */
+    private createQueueSubscribe;
+    /**
+     * List jobs in a queue.
+     */
+    private listQueueJobs;
+    /**
+     * Create global subscribe.
+     */
+    private createGlobalSubscribe;
+    /**
+     * Create search function.
+     */
+    private createSearch;
+    /**
+     * Create worker builder.
+     */
+    private createWorkerBuilder;
+    /**
+     * Create the job handler function for workers.
+     */
+    private createJobHandler;
+    /**
+     * Shutdown the jobs instance.
+     */
+    private shutdown;
+}
+
+/**
+ * @fileoverview Error class and error codes for @igniter-js/jobs
+ * @module @igniter-js/jobs/errors
+ */
+
+/**
+ * All possible error codes for IgniterJobs.
+ * Use these codes for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await jobs.email.sendWelcome.dispatch(input)
+ * } catch (error) {
+ *   if (error instanceof IgniterJobsError) {
+ *     switch (error.code) {
+ *       case 'JOBS_ADAPTER_REQUIRED':
+ *         // Handle missing adapter
+ *         break
+ *       case 'JOBS_DISPATCH_FAILED':
+ *         // Handle dispatch failure
+ *         break
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare const IGNITER_JOBS_ERROR_CODES: {
+    readonly JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED";
+    readonly JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED";
+    readonly JOBS_QUEUE_REQUIRED: "JOBS_QUEUE_REQUIRED";
+    readonly JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID";
+    readonly JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND";
+    readonly JOBS_QUEUE_ALREADY_EXISTS: "JOBS_QUEUE_ALREADY_EXISTS";
+    readonly JOBS_QUEUE_NAME_INVALID: "JOBS_QUEUE_NAME_INVALID";
+    readonly JOBS_QUEUE_PAUSE_FAILED: "JOBS_QUEUE_PAUSE_FAILED";
+    readonly JOBS_QUEUE_RESUME_FAILED: "JOBS_QUEUE_RESUME_FAILED";
+    readonly JOBS_QUEUE_DRAIN_FAILED: "JOBS_QUEUE_DRAIN_FAILED";
+    readonly JOBS_QUEUE_CLEAN_FAILED: "JOBS_QUEUE_CLEAN_FAILED";
+    readonly JOBS_QUEUE_OBLITERATE_FAILED: "JOBS_QUEUE_OBLITERATE_FAILED";
+    readonly JOBS_JOB_NOT_FOUND: "JOBS_JOB_NOT_FOUND";
+    readonly JOBS_JOB_ALREADY_EXISTS: "JOBS_JOB_ALREADY_EXISTS";
+    readonly JOBS_JOB_NAME_INVALID: "JOBS_JOB_NAME_INVALID";
+    readonly JOBS_JOB_HANDLER_REQUIRED: "JOBS_JOB_HANDLER_REQUIRED";
+    readonly JOBS_CRON_NOT_FOUND: "JOBS_CRON_NOT_FOUND";
+    readonly JOBS_CRON_ALREADY_EXISTS: "JOBS_CRON_ALREADY_EXISTS";
+    readonly JOBS_CRON_EXPRESSION_INVALID: "JOBS_CRON_EXPRESSION_INVALID";
+    readonly JOBS_CRON_HANDLER_REQUIRED: "JOBS_CRON_HANDLER_REQUIRED";
+    readonly JOBS_DISPATCH_FAILED: "JOBS_DISPATCH_FAILED";
+    readonly JOBS_SCHEDULE_FAILED: "JOBS_SCHEDULE_FAILED";
+    readonly JOBS_INPUT_REQUIRED: "JOBS_INPUT_REQUIRED";
+    readonly JOBS_INPUT_VALIDATION_FAILED: "JOBS_INPUT_VALIDATION_FAILED";
+    readonly JOBS_SCOPE_REQUIRED: "JOBS_SCOPE_REQUIRED";
+    readonly JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED";
+    readonly JOBS_SCOPE_INVALID: "JOBS_SCOPE_INVALID";
+    readonly JOBS_ACTOR_ALREADY_DEFINED: "JOBS_ACTOR_ALREADY_DEFINED";
+    readonly JOBS_ACTOR_INVALID: "JOBS_ACTOR_INVALID";
+    readonly JOBS_GET_FAILED: "JOBS_GET_FAILED";
+    readonly JOBS_RETRY_FAILED: "JOBS_RETRY_FAILED";
+    readonly JOBS_REMOVE_FAILED: "JOBS_REMOVE_FAILED";
+    readonly JOBS_PROMOTE_FAILED: "JOBS_PROMOTE_FAILED";
+    readonly JOBS_MOVE_FAILED: "JOBS_MOVE_FAILED";
+    readonly JOBS_STATE_FAILED: "JOBS_STATE_FAILED";
+    readonly JOBS_PROGRESS_FAILED: "JOBS_PROGRESS_FAILED";
+    readonly JOBS_LOGS_FAILED: "JOBS_LOGS_FAILED";
+    readonly JOBS_WORKER_CREATE_FAILED: "JOBS_WORKER_CREATE_FAILED";
+    readonly JOBS_WORKER_START_FAILED: "JOBS_WORKER_START_FAILED";
+    readonly JOBS_WORKER_STOP_FAILED: "JOBS_WORKER_STOP_FAILED";
+    readonly JOBS_WORKER_NOT_FOUND: "JOBS_WORKER_NOT_FOUND";
+    readonly JOBS_WORKER_ALREADY_RUNNING: "JOBS_WORKER_ALREADY_RUNNING";
+    readonly JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED";
+    readonly JOBS_UNSUBSCRIBE_FAILED: "JOBS_UNSUBSCRIBE_FAILED";
+    readonly JOBS_EVENT_EMIT_FAILED: "JOBS_EVENT_EMIT_FAILED";
+    readonly JOBS_SEARCH_FAILED: "JOBS_SEARCH_FAILED";
+    readonly JOBS_SEARCH_INVALID_TARGET: "JOBS_SEARCH_INVALID_TARGET";
+    readonly JOBS_SHUTDOWN_FAILED: "JOBS_SHUTDOWN_FAILED";
+    readonly JOBS_HANDLER_FAILED: "JOBS_HANDLER_FAILED";
+    readonly JOBS_HANDLER_TIMEOUT: "JOBS_HANDLER_TIMEOUT";
+};
+/**
+ * Type for all possible error codes.
+ */
+type IgniterJobsErrorCode = keyof typeof IGNITER_JOBS_ERROR_CODES;
+/**
+ * Options for creating an IgniterJobsError.
+ */
+interface IgniterJobsErrorOptions {
+    /**
+     * Error code from IGNITER_JOBS_ERROR_CODES.
+     */
+    code: IgniterJobsErrorCode;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * HTTP status code (for REST API responses).
+     * @default 500
+     */
+    statusCode?: number;
+    /**
+     * Original error that caused this error.
+     */
+    cause?: Error;
+    /**
+     * Additional details for debugging.
+     */
+    details?: Record<string, unknown>;
+    /**
+     * Logger instance for logging the error.
+     */
+    logger?: IgniterLogger;
+}
+/**
+ * Custom error class for @igniter-js/jobs.
+ * Extends IgniterError for consistent error handling across the Igniter ecosystem.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterJobsError({
+ *   code: 'JOBS_DISPATCH_FAILED',
+ *   message: 'Failed to dispatch job to queue',
+ *   statusCode: 500,
+ *   details: { queue: 'email', job: 'sendWelcome' },
+ * })
+ * ```
+ */
+declare class IgniterJobsError extends IgniterError {
+    /**
+     * Error code for programmatic handling.
+     */
+    readonly code: IgniterJobsErrorCode;
+    /**
+     * Additional error details.
+     */
+    readonly details?: Record<string, unknown>;
+    constructor(options: IgniterJobsErrorOptions);
+    /**
+     * Convert error to a plain object for serialization.
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+export { AdapterJobHandler, IGNITER_JOBS_ERROR_CODES, IgniterCronDefinition, IgniterJobActorOptions, IgniterJobDefinition, IgniterJobScopeOptions, IgniterJobs, IgniterJobsAdapter, IgniterJobsBuilder, type IgniterJobsBuilderState, type IgniterJobsConfig, IgniterJobsError, type IgniterJobsErrorCode, IgniterJobsRuntime, IgniterQueue, IgniterQueueBuilder, type IgniterQueueBuilderState, IgniterQueueConfig, IgniterWorkerBuilder, type IgniterWorkerBuilderState, type IgniterWorkerHandle, type IgniterWorkerMetrics };