@igniter-js/jobs 0.1.0 → 0.1.1

package/dist/adapter-PiDCQWQd.d.ts

@@ -0,0 +1,529 @@
+import { Redis } from 'ioredis';
+import { StandardSchemaV1 } from '@igniter-js/core';
+
+/**
+ * Options for defining a scope used to isolate jobs (single scope supported by spec).
+ */
+interface IgniterJobsScopeOptions {
+    /** Whether the scope is mandatory when dispatching jobs. */
+    required?: boolean;
+    /** Optional human-friendly description. */
+    description?: string;
+}
+/**
+ * Represents a single scope entry.
+ *
+ * @example
+ * ```typescript
+ * const scope: IgniterJobsScopeEntry<'organization'> = {
+ *   type: 'organization',
+ *   id: 'org_123',
+ *   tags: { plan: 'pro' },
+ * }
+ * ```
+ */
+interface IgniterJobsScopeEntry<TScope extends string = string> {
+    /** Scope type (e.g., organization, workspace). */
+    type: TScope;
+    /** Scope identifier (string or number). */
+    id: string | number;
+    /** Optional tags for telemetry or auditing. */
+    tags?: Record<string, unknown>;
+}
+/**
+ * Registry type for scope definition.
+ */
+type IgniterJobsScopeDefinition<TScope extends string = string> = Record<TScope, IgniterJobsScopeOptions>;
+
+/**
+ * Options for scheduling a job dispatch.
+ */
+interface IgniterJobsScheduleOptions {
+    /**
+     * Absolute date/time to run the job.
+     *
+     * @example
+     * ```typescript
+     * at: new Date('2025-01-01T10:00:00Z')
+     * ```
+     */
+    at?: Date;
+    /**
+     * Delay in milliseconds before running the job.
+     */
+    delay?: number;
+    /**
+     * Cron expression for repeating jobs.
+     *
+     * @example "0 2 * * *" // every day at 02:00
+     */
+    cron?: string;
+    /**
+     * Repeat every N milliseconds (mutually exclusive with cron).
+     */
+    every?: number;
+    /**
+     * Maximum number of executions for repeating jobs.
+     */
+    maxExecutions?: number;
+    /**
+     * Timezone used when evaluating cron expressions.
+     */
+    tz?: string;
+    /**
+     * Skip execution on weekends when true.
+     */
+    skipWeekends?: boolean;
+    /**
+     * Restrict execution to business hours (24h format).
+     */
+    businessHours?: {
+        start: number;
+        end: number;
+        timezone?: string;
+    };
+    /**
+     * Only execute during business hours when true.
+     */
+    onlyBusinessHours?: boolean;
+    /**
+     * Array of day indices (0-6) that are allowed for execution.
+     */
+    onlyWeekdays?: number[];
+    /**
+     * Dates to skip execution (ISO strings or Date objects).
+     */
+    skipDates?: Array<string | Date>;
+}
+
+/**
+ * @fileoverview Schema helpers for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/schema
+ */
+
+/**
+ * A schema accepted by `@igniter-js/jobs` for input validation.
+ *
+ * Supports:
+ * - Standard Schema v1 (when available)
+ * - Zod-like schemas (with `_input`/`_output` and `safeParse`/`parse`)
+ */
+type IgniterJobsSchema = StandardSchemaV1<any, any> | {
+    readonly _input?: unknown;
+    readonly _output?: unknown;
+    parse: (value: unknown) => unknown;
+    safeParse?: (value: unknown) => {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: unknown;
+    };
+};
+type IgniterJobsInferSchemaInput<TSchema> = TSchema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<TSchema> : TSchema extends {
+    _input?: infer TInput;
+} ? TInput : unknown;
+type IgniterJobsInferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TSchema> : TSchema extends {
+    _output?: infer TOutput;
+} ? TOutput : unknown;
+
+/**
+ * Rate limiter configuration applied to job dispatch or worker level.
+ */
+interface IgniterJobsLimiter {
+    /** Maximum number of jobs allowed within the duration window. */
+    max: number;
+    /** Duration of the window in milliseconds. */
+    duration: number;
+}
+/**
+ * Options controlling job dispatch behavior.
+ */
+interface IgniterJobsInvokeOptions {
+    jobId?: string;
+    priority?: number;
+    delay?: number;
+    attempts?: number;
+    removeOnComplete?: boolean | number;
+    removeOnFail?: boolean | number;
+    metadata?: Record<string, unknown>;
+    limiter?: IgniterJobsLimiter;
+}
+/**
+ * Runtime execution context passed to handlers.
+ */
+interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> {
+    input: IgniterJobsInferSchemaInput<TInput>;
+    context: TContext;
+    job: {
+        id: string;
+        name: string;
+        queue: string;
+        attemptsMade: number;
+        /**
+         * Timestamp when the job was created (when available).
+         *
+         * Some adapters may not provide this information for synthetic executions.
+         */
+        createdAt?: Date;
+        metadata?: Record<string, unknown>;
+    };
+    scope?: IgniterJobsScopeEntry;
+}
+/**
+ * Hook context shared by lifecycle handlers.
+ */
+interface IgniterJobsHookContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> extends IgniterJobsExecutionContext<TContext, TInput> {
+    startedAt?: Date;
+    duration?: number;
+}
+type IgniterJobsStartHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput>) => void | Promise<void>;
+type IgniterJobsSuccessHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+    result: TResult;
+}) => void | Promise<void>;
+type IgniterJobsFailureHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+    error: Error;
+    isFinalAttempt: boolean;
+}) => void | Promise<void>;
+type IgniterJobsProgressHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+    progress: number;
+    message?: string;
+}) => void | Promise<void>;
+/**
+ * Definition of a job registered on a queue.
+ */
+interface IgniterJobDefinition<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> extends IgniterJobsInvokeOptions {
+    /** Optional input schema for validation. */
+    input?: TInput;
+    /** Optional output schema (validation handled externally). */
+    output?: IgniterJobsSchema;
+    /** Optional queue override (creates child queue in adapters). */
+    queue?: string;
+    /** Job handler implementation. */
+    handler: (context: IgniterJobsExecutionContext<TContext, TInput>) => Promise<TResult> | TResult;
+    /** Lifecycle hooks */
+    onStart?: IgniterJobsStartHook<TContext, TInput>;
+    onProgress?: IgniterJobsProgressHook<TContext, TInput>;
+    onSuccess?: IgniterJobsSuccessHook<TContext, TInput, TResult>;
+    onFailure?: IgniterJobsFailureHook<TContext, TInput>;
+}
+/**
+ * Definition for cron-style recurring tasks.
+ */
+interface IgniterCronDefinition<TContext, TResult = unknown> {
+    /** Cron expression (5 or 6 fields depending on engine). */
+    cron: string;
+    /** Timezone used when evaluating cron expressions. */
+    tz?: string;
+    /** Maximum number of executions for this schedule (adapter-dependent). */
+    maxExecutions?: number;
+    /** Skip executions on weekends when true (adapter-dependent). */
+    skipWeekends?: boolean;
+    /** Restrict executions to business hours when true (adapter-dependent). */
+    onlyBusinessHours?: boolean;
+    /** Business hours config used when `onlyBusinessHours` is enabled. */
+    businessHours?: {
+        start: number;
+        end: number;
+        timezone?: string;
+    };
+    /** Only execute on these weekdays (0=Sunday..6=Saturday). */
+    onlyWeekdays?: number[];
+    /** Dates to skip execution (ISO strings or Date objects). */
+    skipDates?: Array<string | Date>;
+    /** Optional start date for the schedule (adapter-dependent). */
+    startDate?: Date;
+    /** Optional end date for the schedule (adapter-dependent). */
+    endDate?: Date;
+    handler: (context: Omit<IgniterJobsExecutionContext<TContext, unknown>, 'input'>) => Promise<TResult> | TResult;
+}
+/**
+ * Supported job states for management queries.
+ */
+type IgniterJobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+/**
+ * Result shape for job inspection calls.
+ */
+interface IgniterJobSearchResult<TResult = unknown> {
+    id: string;
+    name: string;
+    queue: string;
+    status: IgniterJobStatus;
+    input: unknown;
+    result?: TResult;
+    error?: string;
+    progress: number;
+    attemptsMade: number;
+    priority: number;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    metadata?: Record<string, unknown>;
+    scope?: IgniterJobsScopeEntry;
+}
+/**
+ * Management counts for a queue.
+ */
+interface IgniterJobCounts {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+    paused: number;
+}
+/**
+ * Parameters accepted by `.dispatch()`.
+ *
+ * @example
+ * ```typescript
+ * await jobs.email.sendWelcome.dispatch({
+ *   input: { email: 'user@example.com' },
+ *   delay: 5000,
+ *   priority: 10,
+ *   scope: { type: 'organization', id: 'org_1' },
+ * })
+ * ```
+ */
+type IgniterJobsDispatchParams<TInput = unknown> = {
+    input: TInput;
+    scope?: IgniterJobsScopeEntry;
+} & IgniterJobsInvokeOptions;
+/**
+ * Parameters accepted by `.schedule()`.
+ *
+ * Scheduling options are applied in addition to base dispatch options.
+ */
+type IgniterJobsScheduleParams<TInput = unknown> = IgniterJobsDispatchParams<TInput> & IgniterJobsScheduleOptions;
+
+/**
+ * Queue configuration produced by `IgniterQueueBuilder`.
+ */
+interface IgniterJobsQueue<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCron extends Record<string, IgniterCronDefinition<TContext, any>>> {
+    name: string;
+    jobs: TJobs;
+    crons: TCron;
+    defaultJobOptions?: Partial<IgniterJobDefinition<TContext, any, any>>;
+}
+/**
+ * Information about a queue used by management APIs.
+ */
+interface IgniterJobsQueueInfo {
+    name: string;
+    isPaused: boolean;
+    jobCounts: IgniterJobCounts;
+}
+/**
+ * Filter for cleaning queues.
+ */
+interface IgniterJobsQueueCleanOptions {
+    status: IgniterJobStatus | IgniterJobStatus[];
+    olderThan?: number;
+    limit?: number;
+}
+/**
+ * Queue-level management operations exposed by adapters.
+ */
+interface IgniterJobsQueueManager {
+    list(): Promise<IgniterJobsQueueInfo[]>;
+    get(name: string): Promise<IgniterJobsQueueInfo | null>;
+    getJobCounts(name: string): Promise<IgniterJobCounts>;
+    getJobs(name: string, filter?: {
+        status?: IgniterJobStatus[];
+        limit?: number;
+        offset?: number;
+    }): Promise<IgniterJobSearchResult[]>;
+    pause(name: string): Promise<void>;
+    resume(name: string): Promise<void>;
+    isPaused(name: string): Promise<boolean>;
+    drain(name: string): Promise<number>;
+    clean(name: string, options: IgniterJobsQueueCleanOptions): Promise<number>;
+    obliterate(name: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+}
+
+/**
+ * Metrics reported by a worker.
+ */
+interface IgniterJobsWorkerMetrics {
+    processed: number;
+    failed: number;
+    avgDuration: number;
+    concurrency: number;
+    uptime: number;
+}
+/**
+ * Handlers invoked during worker lifecycle.
+ */
+interface IgniterJobsWorkerHandlers {
+    onActive?: (ctx: {
+        job: IgniterJobSearchResult;
+    }) => void | Promise<void>;
+    onSuccess?: (ctx: {
+        job: IgniterJobSearchResult;
+        result: unknown;
+    }) => void | Promise<void>;
+    onFailure?: (ctx: {
+        job: IgniterJobSearchResult;
+        error: Error;
+    }) => void | Promise<void>;
+    onIdle?: () => void | Promise<void>;
+}
+/**
+ * Worker configuration passed to adapters.
+ */
+interface IgniterJobsWorkerBuilderConfig {
+    queues: string[];
+    concurrency?: number;
+    limiter?: IgniterJobsLimiter;
+    handlers?: IgniterJobsWorkerHandlers;
+}
+/**
+ * Handle returned by adapter worker creation.
+ */
+interface IgniterJobsWorkerHandle {
+    readonly id: string;
+    readonly queues: string[];
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isClosed(): boolean;
+    getMetrics(): Promise<IgniterJobsWorkerMetrics>;
+}
+
+/**
+ * Base shape for any jobs event emitted by the package.
+ */
+interface IgniterJobsEvent<TType extends string = string, TPayload = unknown> {
+    type: TType;
+    data: TPayload;
+    timestamp: Date;
+    scope?: IgniterJobsScopeEntry;
+}
+/**
+ * Handler signature for subscribe/listen APIs.
+ */
+type IgniterJobsEventHandler<TEvent extends IgniterJobsEvent = IgniterJobsEvent> = (event: TEvent) => void | Promise<void>;
+/**
+ * Telemetry instance expected by the jobs package.
+ *
+ * This interface mirrors the public API of `IgniterTelemetry` from `@igniter-js/telemetry`.
+ * It is intentionally defined here to avoid a hard dependency on the telemetry package,
+ * which is an optional peer dependency.
+ *
+ * The jobs runtime calls `telemetry.emit(eventName, { attributes })` during job lifecycle
+ * events (enqueued, started, completed, failed, etc.).
+ *
+ * @example
+ * ```typescript
+ * import { IgniterTelemetry } from '@igniter-js/telemetry'
+ * import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs'
+ *
+ * const telemetry = IgniterTelemetry.create()
+ *   .withService('my-api')
+ *   .withEnvironment('production')
+ *   .addEvents(IgniterJobsTelemetryEvents)
+ *   .build()
+ *
+ * const jobs = IgniterJobs.create()
+ *   .withTelemetry(telemetry)
+ *   // ...
+ *   .build()
+ * ```
+ */
+interface IgniterJobsTelemetry {
+    /**
+     * Emits a telemetry event with optional attributes.
+     *
+     * @param name - The event name (e.g., 'igniter.jobs.job.completed')
+     * @param input - Optional emit configuration containing attributes, level, etc.
+     */
+    emit(name: string, input?: {
+        attributes?: Record<string, string | number | boolean | null>;
+        level?: string;
+    }): void;
+    /**
+     * The service name configured on the telemetry instance.
+     */
+    readonly service: string;
+    /**
+     * The environment name configured on the telemetry instance.
+     */
+    readonly environment: string;
+}
+
+/**
+ * Dispatch parameters forwarded to adapters.
+ */
+type IgniterJobsAdapterDispatchParams = {
+    queue: string;
+    jobName: string;
+} & IgniterJobsDispatchParams;
+/**
+ * Schedule parameters forwarded to adapters.
+ */
+type IgniterJobsAdapterScheduleParams = {
+    queue: string;
+    jobName: string;
+} & IgniterJobsScheduleParams;
+/**
+ * Job log entry returned by management APIs.
+ */
+interface IgniterJobsJobLog {
+    timestamp: Date;
+    message: string;
+    level: 'info' | 'warn' | 'error';
+}
+/**
+ * Adapter contract for jobs backends.
+ */
+interface IgniterJobsAdapter {
+    readonly client: unknown;
+    readonly queues: IgniterJobsQueueManager;
+    dispatch(params: IgniterJobsAdapterDispatchParams): Promise<string>;
+    schedule(params: IgniterJobsAdapterScheduleParams): Promise<string>;
+    getJob(jobId: string, queue?: string): Promise<IgniterJobSearchResult | null>;
+    getJobState(jobId: string, queue?: string): Promise<IgniterJobStatus | null>;
+    getJobLogs(jobId: string, queue?: string): Promise<IgniterJobsJobLog[]>;
+    getJobProgress(jobId: string, queue?: string): Promise<number>;
+    retryJob(jobId: string, queue?: string): Promise<void>;
+    removeJob(jobId: string, queue?: string): Promise<void>;
+    promoteJob(jobId: string, queue?: string): Promise<void>;
+    moveJobToFailed(jobId: string, reason: string, queue?: string): Promise<void>;
+    retryManyJobs(jobIds: string[], queue?: string): Promise<void>;
+    removeManyJobs(jobIds: string[], queue?: string): Promise<void>;
+    getQueueInfo(queue: string): Promise<IgniterJobsQueueInfo | null>;
+    getQueueJobCounts(queue: string): Promise<IgniterJobCounts>;
+    listQueues(): Promise<IgniterJobsQueueInfo[]>;
+    pauseQueue(queue: string): Promise<void>;
+    resumeQueue(queue: string): Promise<void>;
+    drainQueue(queue: string): Promise<number>;
+    cleanQueue(queue: string, options: IgniterJobsQueueCleanOptions): Promise<number>;
+    obliterateQueue(queue: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    retryAllInQueue(queue: string): Promise<number>;
+    pauseJobType(queue: string, jobName: string): Promise<void>;
+    resumeJobType(queue: string, jobName: string): Promise<void>;
+    searchJobs(filter: Record<string, unknown>): Promise<IgniterJobSearchResult[]>;
+    searchQueues(filter: Record<string, unknown>): Promise<IgniterJobsQueueInfo[]>;
+    searchWorkers(filter: Record<string, unknown>): Promise<IgniterJobsWorkerHandle[]>;
+    createWorker(config: IgniterJobsWorkerBuilderConfig): Promise<IgniterJobsWorkerHandle>;
+    getWorkers(): Map<string, IgniterJobsWorkerHandle>;
+    publishEvent(channel: string, payload: unknown): Promise<void>;
+    subscribeEvent(channel: string, handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    registerJob(queueName: string, jobName: string, definition: IgniterJobDefinition<any, any, any>): void;
+    registerCron(queueName: string, cronName: string, definition: IgniterCronDefinition<any, any>): void;
+    shutdown(): Promise<void>;
+}
+/**
+ * BullMQ adapter options - primarily Redis connection.
+ */
+interface IgniterJobsBullMQAdapterOptions {
+    redis: Redis;
+}
+
+export type { IgniterJobsInvokeOptions as A, IgniterJobsExecutionContext as B, IgniterJobsHookContext as C, IgniterJobsStartHook as D, IgniterJobsSuccessHook as E, IgniterJobsFailureHook as F, IgniterJobsProgressHook as G, IgniterJobsScopeEntry as H, IgniterJobsAdapter as I, IgniterJobsScheduleOptions as J, IgniterJobsWorkerMetrics as K, IgniterJobsInferSchemaOutput as L, IgniterJobsQueueManager as a, IgniterJobsBullMQAdapterOptions as b, IgniterJobDefinition as c, IgniterCronDefinition as d, IgniterJobsAdapterDispatchParams as e, IgniterJobsAdapterScheduleParams as f, IgniterJobSearchResult as g, IgniterJobStatus as h, IgniterJobsJobLog as i, IgniterJobsQueueInfo as j, IgniterJobsQueueCleanOptions as k, IgniterJobsWorkerHandle as l, IgniterJobsWorkerBuilderConfig as m, IgniterJobsEventHandler as n, IgniterJobCounts as o, IgniterJobsQueue as p, IgniterJobsScopeDefinition as q, IgniterJobsTelemetry as r, IgniterJobsInferSchemaInput as s, IgniterJobsDispatchParams as t, IgniterJobsScheduleParams as u, IgniterJobsLimiter as v, IgniterJobsWorkerHandlers as w, IgniterJobsScopeOptions as x, IgniterJobsSchema as y, IgniterJobsEvent as z };