@igniter-js/jobs 0.1.0

package/dist/adapter-CcQCatSa.d.ts

@@ -0,0 +1,1411 @@
+import { StandardSchemaV1 } from '@igniter-js/core';
+
+/**
+ * @fileoverview Scope and actor types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/scope
+ */
+/**
+ * Options for defining a scope in the jobs builder.
+ *
+ * @example
+ * ```typescript
+ * const jobs = IgniterJobs.create<AppContext>()
+ *   .addScope('organization', { required: true })
+ *   .addScope('tenant', { required: false })
+ *   .build()
+ * ```
+ */
+interface IgniterJobScopeOptions {
+    /**
+     * Whether the scope identifier is required when dispatching jobs.
+     * If true, all job dispatches must include this scope.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Optional description for the scope (for documentation).
+     */
+    description?: string;
+}
+/**
+ * Options for defining an actor in the jobs builder.
+ *
+ * @example
+ * ```typescript
+ * const jobs = IgniterJobs.create<AppContext>()
+ *   .addActor('user', { description: 'The user who initiated the job' })
+ *   .build()
+ * ```
+ */
+interface IgniterJobActorOptions {
+    /**
+     * Optional description for the actor (for documentation).
+     */
+    description?: string;
+}
+/**
+ * A scope entry attached to a job.
+ *
+ * @example
+ * ```typescript
+ * const scopeEntry: IgniterJobScopeEntry = {
+ *   id: 'org_123',
+ *   tags: { plan: 'enterprise', region: 'us-east-1' },
+ * }
+ * ```
+ */
+interface IgniterJobScopeEntry {
+    /**
+     * The unique identifier for the scope (e.g., organization ID, tenant ID).
+     */
+    id: string;
+    /**
+     * Optional tags for additional metadata.
+     */
+    tags?: Record<string, string | number | boolean>;
+}
+/**
+ * An actor entry attached to a job.
+ *
+ * @example
+ * ```typescript
+ * const actorEntry: IgniterJobActorEntry = {
+ *   id: 'user_456',
+ *   tags: { role: 'admin', email: 'admin@example.com' },
+ * }
+ * ```
+ */
+interface IgniterJobActorEntry {
+    /**
+     * The unique identifier for the actor (e.g., user ID).
+     * Optional to support system-initiated jobs.
+     */
+    id?: string;
+    /**
+     * Optional tags for additional metadata.
+     */
+    tags?: Record<string, string | number | boolean>;
+}
+
+/**
+ * @fileoverview Job definition types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/job
+ */
+
+/**
+ * Backoff strategy for job retries.
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff: 1s, 2s, 4s, 8s, ...
+ * const exponential: IgniterJobBackoff = {
+ *   type: 'exponential',
+ *   delay: 1000,
+ *   maxDelay: 30000,
+ * }
+ *
+ * // Fixed delays: 1s, 1s, 1s, ...
+ * const fixed: IgniterJobBackoff = {
+ *   type: 'fixed',
+ *   delay: 1000,
+ * }
+ *
+ * // Linear delays: 1s, 2s, 3s, 4s, ...
+ * const linear: IgniterJobBackoff = {
+ *   type: 'linear',
+ *   delay: 1000,
+ * }
+ *
+ * // Custom delays: 1s, 5s, 30s
+ * const custom: IgniterJobBackoff = {
+ *   type: 'custom',
+ *   delays: [1000, 5000, 30000],
+ * }
+ * ```
+ */
+type IgniterJobBackoff = {
+    type: 'exponential';
+    delay: number;
+    maxDelay?: number;
+} | {
+    type: 'fixed';
+    delay: number;
+} | {
+    type: 'linear';
+    delay: number;
+} | {
+    type: 'custom';
+    delays: number[];
+};
+/**
+ * Rate limiter configuration for jobs.
+ *
+ * @example
+ * ```typescript
+ * // Max 100 jobs per minute
+ * const limiter: IgniterJobLimiter = {
+ *   max: 100,
+ *   duration: 60000, // 1 minute in milliseconds
+ * }
+ * ```
+ */
+interface IgniterJobLimiter {
+    /**
+     * Maximum number of jobs to process within the duration window.
+     */
+    max: number;
+    /**
+     * Duration window in milliseconds.
+     */
+    duration: number;
+}
+/**
+ * Context passed to job handlers.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TInput - Job input type
+ *
+ * @example
+ * ```typescript
+ * const handler = async (ctx: IgniterJobHandlerContext<AppContext, { userId: string }>) => {
+ *   const { input, context, job, attempt, log, updateProgress } = ctx
+ *
+ *   log('info', `Processing user ${input.userId}`)
+ *   await updateProgress(50)
+ *
+ *   const user = await context.db.users.findById(input.userId)
+ *   return { success: true, user }
+ * }
+ * ```
+ */
+interface IgniterJobHandlerContext<TContext, TInput> {
+    /**
+     * The validated job input data.
+     */
+    input: TInput;
+    /**
+     * Application context provided during build.
+     */
+    context: TContext;
+    /**
+     * Job metadata and identifiers.
+     */
+    job: {
+        /**
+         * Unique job identifier.
+         */
+        id: string;
+        /**
+         * Job name (from addJob).
+         */
+        name: string;
+        /**
+         * Queue name the job belongs to.
+         */
+        queue: string;
+        /**
+         * Unix timestamp when job was created.
+         */
+        timestamp: number;
+    };
+    /**
+     * Current attempt number (1-indexed).
+     */
+    attempt: number;
+    /**
+     * Scope entry if provided during dispatch.
+     */
+    scope?: IgniterJobScopeEntry;
+    /**
+     * Actor entry if provided during dispatch.
+     */
+    actor?: IgniterJobActorEntry;
+    /**
+     * Log a message associated with this job.
+     *
+     * @param level - Log level
+     * @param message - Message to log
+     */
+    log: (level: 'info' | 'warn' | 'error', message: string) => Promise<void>;
+    /**
+     * Update job progress (0-100).
+     *
+     * @param progress - Progress percentage
+     */
+    updateProgress: (progress: number) => Promise<void>;
+}
+/**
+ * Job handler function type.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TInput - Job input type
+ * @typeParam TOutput - Job output type
+ */
+type IgniterJobHandler<TContext, TInput, TOutput> = (ctx: IgniterJobHandlerContext<TContext, TInput>) => Promise<TOutput> | TOutput;
+/**
+ * Hook called when a job fails.
+ */
+type IgniterJobFailureHook<TContext, TInput> = (ctx: IgniterJobHandlerContext<TContext, TInput>, error: Error) => void | Promise<void>;
+/**
+ * Hook called when a job completes successfully.
+ */
+type IgniterJobCompleteHook<TContext, TInput, TOutput> = (ctx: IgniterJobHandlerContext<TContext, TInput>, result: TOutput) => void | Promise<void>;
+/**
+ * Full job definition.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TInput - Job input type
+ * @typeParam TOutput - Job output type
+ *
+ * @example
+ * ```typescript
+ * const sendEmailJob: IgniterJobDefinition<AppContext, SendEmailInput, void> = {
+ *   input: z.object({
+ *     to: z.string().email(),
+ *     subject: z.string(),
+ *     body: z.string(),
+ *   }),
+ *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
+ *   timeout: 30000,
+ *   handler: async (ctx) => {
+ *     await ctx.context.mailer.send(ctx.input)
+ *   },
+ * }
+ * ```
+ */
+interface IgniterJobDefinition<TContext = unknown, TInput = unknown, TOutput = unknown> {
+    /**
+     * Input schema for validation (Zod or StandardSchemaV1 compatible).
+     * Optional but recommended for type safety and runtime validation.
+     */
+    input?: StandardSchemaV1<TInput>;
+    /**
+     * Retry configuration.
+     */
+    retry?: {
+        /**
+         * Maximum number of retry attempts.
+         * @default 3
+         */
+        attempts?: number;
+        /**
+         * Backoff strategy for retries.
+         * @default { type: 'exponential', delay: 1000 }
+         */
+        backoff?: IgniterJobBackoff;
+    };
+    /**
+     * Job timeout in milliseconds.
+     * Job will be failed if it doesn't complete within this time.
+     */
+    timeout?: number;
+    /**
+     * Job priority (higher = more important).
+     * @default 0
+     */
+    priority?: number;
+    /**
+     * Rate limiter configuration.
+     */
+    limiter?: IgniterJobLimiter;
+    /**
+     * Whether to remove job data on completion.
+     * @default false
+     */
+    removeOnComplete?: boolean | {
+        count?: number;
+        age?: number;
+    };
+    /**
+     * Whether to remove job data on failure.
+     * @default false
+     */
+    removeOnFail?: boolean | {
+        count?: number;
+        age?: number;
+    };
+    /**
+     * Job handler function.
+     */
+    handler: IgniterJobHandler<TContext, TInput, TOutput>;
+    /**
+     * Hook called when job fails (after all retries exhausted).
+     */
+    onFailure?: IgniterJobFailureHook<TContext, TInput>;
+    /**
+     * Hook called when job completes successfully.
+     */
+    onComplete?: IgniterJobCompleteHook<TContext, TInput, TOutput>;
+}
+/**
+ * Context passed to cron job handlers.
+ *
+ * @typeParam TContext - Application context type
+ */
+interface IgniterCronHandlerContext<TContext> {
+    /**
+     * Application context provided during build.
+     */
+    context: TContext;
+    /**
+     * Cron job metadata.
+     */
+    cron: {
+        /**
+         * Cron job name.
+         */
+        name: string;
+        /**
+         * Queue name the cron belongs to.
+         */
+        queue: string;
+        /**
+         * Cron expression.
+         */
+        expression: string;
+        /**
+         * Timezone for the cron expression.
+         */
+        timezone?: string;
+        /**
+         * Unix timestamp when cron was triggered.
+         */
+        timestamp: number;
+    };
+    /**
+     * Log a message associated with this cron execution.
+     *
+     * @param level - Log level
+     * @param message - Message to log
+     */
+    log: (level: 'info' | 'warn' | 'error', message: string) => Promise<void>;
+}
+/**
+ * Cron handler function type.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TOutput - Cron output type
+ */
+type IgniterCronHandler<TContext, TOutput> = (ctx: IgniterCronHandlerContext<TContext>) => Promise<TOutput> | TOutput;
+/**
+ * Hook called when a cron job fails.
+ */
+type IgniterCronFailureHook<TContext> = (ctx: IgniterCronHandlerContext<TContext>, error: Error) => void | Promise<void>;
+/**
+ * Full cron job definition.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TOutput - Cron output type
+ *
+ * @example
+ * ```typescript
+ * const dailyCleanup: IgniterCronDefinition<AppContext, void> = {
+ *   expression: '0 0 * * *', // Every day at midnight
+ *   timezone: 'America/New_York',
+ *   handler: async (ctx) => {
+ *     await ctx.context.db.cleanup.expiredSessions()
+ *     ctx.log('info', 'Cleaned up expired sessions')
+ *   },
+ * }
+ * ```
+ */
+interface IgniterCronDefinition<TContext = unknown, TOutput = unknown> {
+    /**
+     * Cron expression (standard cron format).
+     *
+     * @example '0 0 * * *' // Every day at midnight
+     * @example '/5 * * * *' // Every 5 minutes
+     * @example '0 9 * * 1' // Every Monday at 9 AM
+     */
+    expression: string;
+    /**
+     * Timezone for the cron expression.
+     * @default 'UTC'
+     *
+     * @example 'America/New_York'
+     * @example 'Europe/London'
+     */
+    timezone?: string;
+    /**
+     * Whether to run immediately on startup (in addition to the cron schedule).
+     * @default false
+     */
+    runOnStart?: boolean;
+    /**
+     * Whether to skip if the previous run is still executing.
+     * @default true
+     */
+    skipIfRunning?: boolean;
+    /**
+     * Job timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Cron handler function.
+     */
+    handler: IgniterCronHandler<TContext, TOutput>;
+    /**
+     * Hook called when cron job fails.
+     */
+    onFailure?: IgniterCronFailureHook<TContext>;
+}
+/**
+ * Job information returned from management APIs.
+ */
+interface IgniterJobInfo {
+    /**
+     * Unique job ID.
+     */
+    id: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Current job state.
+     */
+    state: IgniterJobStatus;
+    /**
+     * Job input data.
+     */
+    data: unknown;
+    /**
+     * Job result (if completed).
+     */
+    result?: unknown;
+    /**
+     * Error message (if failed).
+     */
+    error?: string;
+    /**
+     * Job progress (0-100).
+     */
+    progress?: number;
+    /**
+     * Number of attempts made.
+     */
+    attempts: number;
+    /**
+     * Unix timestamp when job was created.
+     */
+    timestamp: number;
+    /**
+     * Unix timestamp when job processing started.
+     */
+    processedOn?: number;
+    /**
+     * Unix timestamp when job finished (completed or failed).
+     */
+    finishedOn?: number;
+    /**
+     * Job delay in milliseconds (if delayed).
+     */
+    delay?: number;
+    /**
+     * Job priority.
+     */
+    priority?: number;
+    /**
+     * Scope entry attached to the job.
+     */
+    scope?: IgniterJobScopeEntry;
+    /**
+     * Actor entry attached to the job.
+     */
+    actor?: IgniterJobActorEntry;
+    /**
+     * Additional metadata.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Possible job states.
+ */
+type IgniterJobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+/**
+ * Job counts per state.
+ */
+interface IgniterJobCounts {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+    paused: number;
+}
+/**
+ * Job log entry.
+ */
+interface IgniterJobLog {
+    /**
+     * Log timestamp.
+     */
+    timestamp: Date;
+    /**
+     * Log message.
+     */
+    message: string;
+    /**
+     * Log level.
+     */
+    level: 'info' | 'warn' | 'error';
+}
+
+/**
+ * @fileoverview Queue types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/queue
+ */
+
+/**
+ * Queue configuration for building.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TJobs - Map of job names to definitions
+ * @typeParam TCrons - Map of cron names to definitions
+ */
+interface IgniterQueueConfig<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>> = Record<string, never>> {
+    /**
+     * Queue name (will be prefixed with 'igniter:jobs:').
+     */
+    name: string;
+    /**
+     * Job definitions for this queue.
+     */
+    jobs: TJobs;
+    /**
+     * Cron definitions for this queue.
+     */
+    crons: TCrons;
+}
+/**
+ * Queue information returned from management APIs.
+ */
+interface IgniterQueueInfo {
+    /**
+     * Queue name.
+     */
+    name: string;
+    /**
+     * Whether the queue is currently paused.
+     */
+    isPaused: boolean;
+    /**
+     * Job counts per state.
+     */
+    jobCounts: IgniterJobCounts;
+}
+/**
+ * Options for cleaning jobs from a queue.
+ */
+interface IgniterQueueCleanOptions {
+    /**
+     * Job status(es) to clean.
+     */
+    status: 'completed' | 'failed' | 'delayed' | 'waiting' | 'active' | Array<'completed' | 'failed' | 'delayed' | 'waiting' | 'active'>;
+    /**
+     * Only clean jobs older than this many milliseconds.
+     * @default 0 (clean all matching jobs)
+     */
+    olderThan?: number;
+    /**
+     * Maximum number of jobs to clean.
+     * @default 1000
+     */
+    limit?: number;
+}
+/**
+ * Search filter for queues.
+ */
+interface IgniterQueuesSearchFilter {
+    /**
+     * Filter by queue name (partial match).
+     */
+    name?: string;
+    /**
+     * Filter by paused state.
+     */
+    isPaused?: boolean;
+}
+/**
+ * Search filter for jobs.
+ */
+interface IgniterJobsSearchFilter {
+    /**
+     * Filter by job status(es).
+     */
+    status?: Array<'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused'>;
+    /**
+     * Filter by queue name.
+     */
+    queue?: string;
+    /**
+     * Filter by job name.
+     */
+    jobName?: string;
+    /**
+     * Filter by scope ID.
+     */
+    scopeId?: string;
+    /**
+     * Filter by actor ID.
+     */
+    actorId?: string;
+    /**
+     * Filter by date range.
+     */
+    dateRange?: {
+        from?: Date;
+        to?: Date;
+    };
+    /**
+     * Order results.
+     */
+    orderBy?: 'createdAt:asc' | 'createdAt:desc' | 'priority:asc' | 'priority:desc';
+    /**
+     * Maximum number of results.
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Offset for pagination.
+     * @default 0
+     */
+    offset?: number;
+}
+/**
+ * Search filter for workers.
+ */
+interface IgniterWorkersSearchFilter {
+    /**
+     * Filter by queue name.
+     */
+    queue?: string;
+    /**
+     * Filter by running state.
+     */
+    isRunning?: boolean;
+}
+/**
+ * Search result for jobs.
+ */
+interface IgniterJobSearchResult {
+    /**
+     * Job ID.
+     */
+    id: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Job state.
+     */
+    state: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+    /**
+     * Job data (input).
+     */
+    data: unknown;
+    /**
+     * Job result (if completed).
+     */
+    result?: unknown;
+    /**
+     * Error message (if failed).
+     */
+    error?: string;
+    /**
+     * Job progress (0-100).
+     */
+    progress?: number;
+    /**
+     * Attempt count.
+     */
+    attempts: number;
+    /**
+     * Creation timestamp.
+     */
+    timestamp: number;
+    /**
+     * Processing start timestamp.
+     */
+    processedOn?: number;
+    /**
+     * Finish timestamp.
+     */
+    finishedOn?: number;
+    /**
+     * Scope entry.
+     */
+    scope?: {
+        id: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+    /**
+     * Actor entry.
+     */
+    actor?: {
+        id?: string;
+        tags?: Record<string, string | number | boolean>;
+    };
+}
+
+/**
+ * @fileoverview Event types for @igniter-js/jobs (subscribe pattern)
+ * @module @igniter-js/jobs/types/events
+ */
+
+/**
+ * Job lifecycle event types.
+ */
+type IgniterJobEventType = 'enqueued' | 'started' | 'progress' | 'completed' | 'failed' | 'retrying';
+/**
+ * Base event context passed to subscribers.
+ *
+ * @typeParam TEventType - Full event type string
+ * @typeParam TPayload - Event payload type
+ */
+interface IgniterJobEventContext<TEventType extends string = string, TPayload = unknown> {
+    /**
+     * Full event type (e.g., 'email:sendWelcome:completed').
+     */
+    type: TEventType;
+    /**
+     * Event payload data.
+     */
+    data: TPayload;
+    /**
+     * ISO timestamp when the event occurred.
+     */
+    timestamp: string;
+    /**
+     * Scope entry if the job had one.
+     */
+    scope?: IgniterJobScopeEntry;
+    /**
+     * Actor entry if the job had one.
+     */
+    actor?: IgniterJobActorEntry;
+}
+/**
+ * Unsubscribe function returned from subscribe.
+ */
+type IgniterJobUnsubscribeFn = () => Promise<void>;
+/**
+ * Event handler function.
+ *
+ * @typeParam TContext - Event context type
+ */
+type IgniterJobEventHandler<TContext = IgniterJobEventContext> = (ctx: TContext) => void | Promise<void>;
+/**
+ * Payload for 'enqueued' events.
+ *
+ * @typeParam TInput - Job input type
+ */
+interface IgniterJobEnqueuedPayload<TInput = unknown> {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Job input data.
+     */
+    data: TInput;
+    /**
+     * ISO timestamp when job was enqueued.
+     */
+    enqueuedAt: string;
+}
+/**
+ * Payload for 'started' events.
+ */
+interface IgniterJobStartedPayload {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Current attempt number.
+     */
+    attempt: number;
+    /**
+     * ISO timestamp when job started.
+     */
+    startedAt: string;
+}
+/**
+ * Payload for 'progress' events.
+ */
+interface IgniterJobProgressPayload {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Progress percentage (0-100).
+     */
+    progress: number;
+    /**
+     * ISO timestamp.
+     */
+    timestamp: string;
+}
+/**
+ * Payload for 'completed' events.
+ *
+ * @typeParam TResult - Job result type
+ */
+interface IgniterJobCompletedPayload<TResult = unknown> {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Job result.
+     */
+    result: TResult;
+    /**
+     * Execution duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * ISO timestamp when job completed.
+     */
+    completedAt: string;
+}
+/**
+ * Payload for 'failed' events.
+ */
+interface IgniterJobFailedPayload {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Error message.
+     */
+    error: string;
+    /**
+     * Error stack trace (if available).
+     */
+    stack?: string;
+    /**
+     * Attempt number when failure occurred.
+     */
+    attempt: number;
+    /**
+     * Whether more retries are available.
+     */
+    retriesLeft: number;
+    /**
+     * ISO timestamp when job failed.
+     */
+    failedAt: string;
+}
+/**
+ * Payload for 'retrying' events.
+ */
+interface IgniterJobRetryingPayload {
+    /**
+     * Unique job ID.
+     */
+    jobId: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Previous error message.
+     */
+    error: string;
+    /**
+     * Attempt number being retried.
+     */
+    attempt: number;
+    /**
+     * Delay before next attempt in milliseconds.
+     */
+    delay: number;
+    /**
+     * ISO timestamp.
+     */
+    retryingAt: string;
+}
+/**
+ * Union of all event payloads.
+ */
+type IgniterJobEventPayload = IgniterJobEnqueuedPayload | IgniterJobStartedPayload | IgniterJobProgressPayload | IgniterJobCompletedPayload | IgniterJobFailedPayload | IgniterJobRetryingPayload;
+
+/**
+ * @fileoverview Adapter interface for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/adapter
+ */
+
+/**
+ * Parameters for dispatching a job.
+ */
+interface AdapterDispatchParams {
+    /**
+     * Queue name.
+     */
+    queue: string;
+    /**
+     * Job name.
+     */
+    name: string;
+    /**
+     * Job input data.
+     */
+    data: unknown;
+    /**
+     * Custom job ID (optional).
+     */
+    jobId?: string;
+    /**
+     * Delay before processing in milliseconds.
+     */
+    delay?: number;
+    /**
+     * Job priority.
+     */
+    priority?: number;
+    /**
+     * Max retry attempts.
+     */
+    attempts?: number;
+    /**
+     * Backoff configuration.
+     */
+    backoff?: {
+        type: 'exponential' | 'fixed' | 'linear';
+        delay: number;
+        maxDelay?: number;
+    } | {
+        type: 'custom';
+        delays: number[];
+    };
+    /**
+     * Remove on completion config.
+     */
+    removeOnComplete?: boolean | {
+        count?: number;
+        age?: number;
+    };
+    /**
+     * Remove on failure config.
+     */
+    removeOnFail?: boolean | {
+        count?: number;
+        age?: number;
+    };
+    /**
+     * Scope entry.
+     */
+    scope?: IgniterJobScopeEntry;
+    /**
+     * Actor entry.
+     */
+    actor?: IgniterJobActorEntry;
+}
+/**
+ * Parameters for scheduling a job (delayed or cron).
+ */
+interface AdapterScheduleParams extends AdapterDispatchParams {
+    /**
+     * Schedule job at this specific time.
+     */
+    at?: Date;
+    /**
+     * Cron expression for repeating jobs.
+     */
+    cron?: string;
+    /**
+     * Repeat every N milliseconds.
+     */
+    every?: number;
+    /**
+     * Timezone for cron expression.
+     */
+    timezone?: string;
+}
+/**
+ * Worker configuration for the adapter.
+ */
+interface AdapterWorkerConfig {
+    /**
+     * Queue names to process.
+     */
+    queues: string[];
+    /**
+     * Concurrency per queue.
+     */
+    concurrency: number;
+    /**
+     * Rate limiter config.
+     */
+    limiter?: {
+        max: number;
+        duration: number;
+    };
+    /**
+     * Lock duration in milliseconds.
+     */
+    lockDuration?: number;
+    /**
+     * Callback when worker becomes idle.
+     */
+    onIdle?: () => void;
+}
+/**
+ * Worker handle returned by adapter.
+ */
+interface AdapterWorkerHandle {
+    /**
+     * Worker ID.
+     */
+    id: string;
+    /**
+     * Pause the worker.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the worker.
+     */
+    resume(): Promise<void>;
+    /**
+     * Close the worker.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if worker is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Check if worker is paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Get worker metrics.
+     */
+    getMetrics(): Promise<{
+        processed: number;
+        failed: number;
+        completed: number;
+        active: number;
+        uptime: number;
+    }>;
+}
+/**
+ * Job handler for adapter workers.
+ */
+type AdapterJobHandler = (job: {
+    id: string;
+    name: string;
+    queue: string;
+    data: unknown;
+    attempt: number;
+    timestamp: number;
+    scope?: IgniterJobScopeEntry;
+    actor?: IgniterJobActorEntry;
+    log: (level: 'info' | 'warn' | 'error', message: string) => Promise<void>;
+    updateProgress: (progress: number) => Promise<void>;
+}) => Promise<unknown>;
+/**
+ * Adapter interface for job queue backends.
+ *
+ * Implementations must provide all methods for:
+ * - Job dispatching and scheduling
+ * - Queue management
+ * - Job management
+ * - Event subscriptions
+ * - Worker creation
+ *
+ * @example
+ * ```typescript
+ * class BullMQAdapter implements IgniterJobsAdapter {
+ *   // Implementation
+ * }
+ * ```
+ */
+interface IgniterJobsAdapter {
+    /**
+     * Underlying client reference (e.g., Redis instance).
+     */
+    readonly client: unknown;
+    /**
+     * Dispatch a job for immediate processing.
+     *
+     * @param params - Job dispatch parameters
+     * @returns Job ID
+     */
+    dispatch(params: AdapterDispatchParams): Promise<string>;
+    /**
+     * Schedule a job for future processing.
+     *
+     * @param params - Job schedule parameters
+     * @returns Job ID
+     */
+    schedule(params: AdapterScheduleParams): Promise<string>;
+    /**
+     * Get job information by ID.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     * @returns Job info or null if not found
+     */
+    getJob(queue: string, jobId: string): Promise<IgniterJobInfo | null>;
+    /**
+     * Get job state.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     * @returns Job status
+     */
+    getJobState(queue: string, jobId: string): Promise<IgniterJobStatus | null>;
+    /**
+     * Get job progress.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     * @returns Progress (0-100)
+     */
+    getJobProgress(queue: string, jobId: string): Promise<number>;
+    /**
+     * Get job logs.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     * @returns Array of log entries
+     */
+    getJobLogs(queue: string, jobId: string): Promise<IgniterJobLog[]>;
+    /**
+     * Retry a failed job.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     */
+    retryJob(queue: string, jobId: string): Promise<void>;
+    /**
+     * Remove a job.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     */
+    removeJob(queue: string, jobId: string): Promise<void>;
+    /**
+     * Promote a delayed job to waiting.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     */
+    promoteJob(queue: string, jobId: string): Promise<void>;
+    /**
+     * Move a job to a different state.
+     *
+     * @param queue - Queue name
+     * @param jobId - Job ID
+     * @param state - Target state
+     * @param reason - Optional reason
+     */
+    moveJob(queue: string, jobId: string, state: 'failed' | 'completed', reason?: string): Promise<void>;
+    /**
+     * Retry multiple jobs.
+     *
+     * @param queue - Queue name
+     * @param jobIds - Job IDs
+     */
+    retryJobs(queue: string, jobIds: string[]): Promise<void>;
+    /**
+     * Remove multiple jobs.
+     *
+     * @param queue - Queue name
+     * @param jobIds - Job IDs
+     */
+    removeJobs(queue: string, jobIds: string[]): Promise<void>;
+    /**
+     * Get queue information.
+     *
+     * @param queue - Queue name
+     * @returns Queue info
+     */
+    getQueue(queue: string): Promise<IgniterQueueInfo>;
+    /**
+     * Pause a queue.
+     *
+     * @param queue - Queue name
+     */
+    pauseQueue(queue: string): Promise<void>;
+    /**
+     * Resume a paused queue.
+     *
+     * @param queue - Queue name
+     */
+    resumeQueue(queue: string): Promise<void>;
+    /**
+     * Drain a queue (remove all waiting and delayed jobs).
+     *
+     * @param queue - Queue name
+     * @returns Number of jobs removed
+     */
+    drainQueue(queue: string): Promise<number>;
+    /**
+     * Clean jobs from a queue.
+     *
+     * @param queue - Queue name
+     * @param options - Clean options
+     * @returns Number of jobs removed
+     */
+    cleanQueue(queue: string, options: IgniterQueueCleanOptions): Promise<number>;
+    /**
+     * Obliterate a queue (remove all data).
+     *
+     * @param queue - Queue name
+     * @param options - Obliterate options
+     */
+    obliterateQueue(queue: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Retry all failed jobs in a queue.
+     *
+     * @param queue - Queue name
+     * @returns Number of jobs retried
+     */
+    retryAllFailed(queue: string): Promise<number>;
+    /**
+     * Get job counts for a queue.
+     *
+     * @param queue - Queue name
+     * @returns Job counts per state
+     */
+    getJobCounts(queue: string): Promise<IgniterJobCounts>;
+    /**
+     * List jobs in a queue.
+     *
+     * @param queue - Queue name
+     * @param options - List options
+     * @returns Array of job search results
+     */
+    listJobs(queue: string, options?: {
+        status?: IgniterJobStatus[];
+        start?: number;
+        end?: number;
+    }): Promise<IgniterJobSearchResult[]>;
+    /**
+     * Pause processing of a specific job type.
+     *
+     * @param queue - Queue name
+     * @param jobName - Job name
+     */
+    pauseJobType(queue: string, jobName: string): Promise<void>;
+    /**
+     * Resume processing of a specific job type.
+     *
+     * @param queue - Queue name
+     * @param jobName - Job name
+     */
+    resumeJobType(queue: string, jobName: string): Promise<void>;
+    /**
+     * Subscribe to job events.
+     *
+     * @param pattern - Event pattern (e.g., 'email:*', 'email:sendWelcome:*')
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    subscribe(pattern: string, handler: IgniterJobEventHandler): Promise<IgniterJobUnsubscribeFn>;
+    /**
+     * Create a worker.
+     *
+     * @param config - Worker configuration
+     * @param handler - Job handler
+     * @returns Worker handle
+     */
+    createWorker(config: AdapterWorkerConfig, handler: AdapterJobHandler): Promise<AdapterWorkerHandle>;
+    /**
+     * Search for jobs across queues.
+     *
+     * @param filter - Search filter
+     * @returns Array of matching jobs
+     */
+    searchJobs(filter: {
+        status?: IgniterJobStatus[];
+        queue?: string;
+        jobName?: string;
+        scopeId?: string;
+        actorId?: string;
+        dateRange?: {
+            from?: Date;
+            to?: Date;
+        };
+        orderBy?: 'createdAt:asc' | 'createdAt:desc' | 'priority:asc' | 'priority:desc';
+        limit?: number;
+        offset?: number;
+    }): Promise<IgniterJobSearchResult[]>;
+    /**
+     * Search for queues.
+     *
+     * @param filter - Search filter
+     * @returns Array of queue info
+     */
+    searchQueues(filter: {
+        name?: string;
+        isPaused?: boolean;
+    }): Promise<IgniterQueueInfo[]>;
+    /**
+     * Shutdown the adapter and clean up resources.
+     */
+    shutdown(): Promise<void>;
+}
+
+export type { AdapterDispatchParams as A, IgniterJobLimiter as B, IgniterQueuesSearchFilter as C, IgniterJobsSearchFilter as D, IgniterWorkersSearchFilter as E, IgniterJobEventType as F, IgniterJobEventContext as G, IgniterJobEventPayload as H, IgniterJobsAdapter as I, IgniterJobEnqueuedPayload as J, IgniterJobStartedPayload as K, IgniterJobProgressPayload as L, IgniterJobCompletedPayload as M, IgniterJobFailedPayload as N, IgniterJobRetryingPayload as O, IgniterJobScopeEntry as P, IgniterJobActorEntry as Q, AdapterScheduleParams as a, IgniterJobInfo as b, IgniterJobStatus as c, IgniterJobLog as d, IgniterQueueInfo as e, IgniterQueueCleanOptions as f, IgniterJobCounts as g, IgniterJobSearchResult as h, IgniterJobEventHandler as i, IgniterJobUnsubscribeFn as j, AdapterWorkerConfig as k, AdapterJobHandler as l, AdapterWorkerHandle as m, IgniterJobDefinition as n, IgniterCronDefinition as o, IgniterQueueConfig as p, IgniterJobScopeOptions as q, IgniterJobActorOptions as r, IgniterJobHandler as s, IgniterJobHandlerContext as t, IgniterCronHandler as u, IgniterCronHandlerContext as v, IgniterJobFailureHook as w, IgniterJobCompleteHook as x, IgniterCronFailureHook as y, IgniterJobBackoff as z };