@quave/agenda 1.0.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,498 @@
+import { EventEmitter } from 'events';
+import { ForkOptions } from 'child_process';
+import type { JobDefinition } from './types/JobDefinition.js';
+import type { AgendaConfig } from './types/AgendaConfig.js';
+import type { AgendaBackend } from './types/AgendaBackend.js';
+import type { NotificationChannel, JobStateNotification, JobStateType } from './types/NotificationChannel.js';
+import type { JobRepository } from './types/JobRepository.js';
+import type { AgendaStatus } from './types/AgendaStatus.js';
+import type { JobsQueryOptions, JobsResult, JobsOverview } from './types/JobQuery.js';
+import type { RemoveJobsOptions } from './types/JobRepository.js';
+import type { DrainOptions, DrainResult } from './types/DrainOptions.js';
+import type { JobLogger, JobLogEntry, JobLogQuery, JobLogQueryResult } from './types/JobLogger.js';
+import { Job, JobWithId } from './Job.js';
+import { JobPriority } from './utils/priority.js';
+/**
+ * Agenda configuration options
+ */
+export interface AgendaOptions {
+    /** Unified backend for storage and optionally notifications */
+    backend: AgendaBackend;
+    /** Name to identify this agenda instance */
+    name?: string;
+    /** Default number of concurrent jobs per job type */
+    defaultConcurrency?: number;
+    /** How often to poll for new jobs (string like '5 seconds' or milliseconds) */
+    processEvery?: string | number;
+    /** Maximum number of concurrent jobs globally */
+    maxConcurrency?: number;
+    /** Default max locked jobs per job type */
+    defaultLockLimit?: number;
+    /** Global max locked jobs */
+    lockLimit?: number;
+    /** Default lock lifetime in milliseconds */
+    defaultLockLifetime?: number;
+    /** Automatically remove one-time jobs from database after successful completion */
+    removeOnComplete?: boolean;
+    /** Fork helper configuration for sandboxed workers */
+    forkHelper?: {
+        path: string;
+        options?: ForkOptions;
+    };
+    /** Whether this is a forked worker instance */
+    forkedWorker?: boolean;
+    /**
+     * Override notification channel from backend.
+     * Use this to mix storage from one system with notifications from another.
+     * e.g., MongoDB storage + Redis notifications
+     */
+    notificationChannel?: NotificationChannel;
+    /**
+     * Enable persistent job event logging (stored in the backend's database).
+     *
+     * Disabled by default. When enabled, all job lifecycle events (start, success,
+     * fail, complete, retry, etc.) are persisted and can be queried via
+     * `agenda.getLogs()` or viewed in agendash.
+     *
+     * Options:
+     * - `true` — use the backend's built-in logger, all jobs are logged
+     * - `false` / omitted — no logging (default)
+     * - `JobLogger` — use a custom logger instance, all jobs are logged
+     * - `{ logger?: JobLogger, default?: boolean }` — fine-grained control:
+     *   - `logger`: custom `JobLogger` (omit to use backend's built-in logger)
+     *   - `default`: whether job definitions are logged by default (`true` = all logged,
+     *     `false` = only jobs with `logging: true` in their definition are logged).
+     *     Defaults to `true`.
+     *
+     * Per-job definitions can override the default via `define('job', fn, { logging: false })`.
+     *
+     * @example
+     * ```typescript
+     * // Enable — log all jobs using backend's logger
+     * const agenda = new Agenda({ backend, logging: true });
+     *
+     * // Enable — opt-in per job (logger configured, but off by default)
+     * const agenda = new Agenda({ backend, logging: { default: false } });
+     * agenda.define('important', handler, { logging: true });  // logged
+     * agenda.define('noisy', handler);                         // NOT logged
+     *
+     * // Enable — custom logger (e.g., log to Postgres while using Mongo for storage)
+     * const agenda = new Agenda({ backend, logging: myPostgresJobLogger });
+     *
+     * // Enable — custom logger + opt-in per job
+     * const agenda = new Agenda({
+     *   backend,
+     *   logging: { logger: myPostgresJobLogger, default: false }
+     * });
+     *
+     * // Query logs
+     * const { entries } = await agenda.getLogs({ jobName: 'myJob', limit: 100 });
+     * ```
+     */
+    logging?: boolean | JobLogger | {
+        logger?: JobLogger;
+        default?: boolean;
+    };
+}
+/**
+ * Details provided when a job is scheduled for retry
+ */
+export interface RetryDetails {
+    /** The retry attempt number (1-based) */
+    attempt: number;
+    /** Delay in milliseconds before the retry */
+    delay: number;
+    /** When the retry will be executed */
+    nextRunAt: Date;
+    /** The error that caused the failure */
+    error: Error;
+}
+/**
+ * Event names that Agenda emits
+ */
+export type AgendaEventName = 'ready' | 'error' | 'fail' | 'success' | 'start' | 'complete' | 'retry' | 'retry exhausted' | `fail:${string}` | `success:${string}` | `start:${string}` | `complete:${string}` | `retry:${string}` | `retry exhausted:${string}`;
+/**
+ * @class
+ */
+export declare class Agenda extends EventEmitter {
+    readonly attrs: AgendaConfig;
+    readonly forkedWorker?: boolean;
+    readonly forkHelper?: {
+        path: string;
+        options?: ForkOptions;
+    };
+    private backend;
+    db: JobRepository;
+    private notificationChannel?;
+    private stateSubscriptionUnsubscribe?;
+    /**
+     * The persistent job logger for storing job lifecycle events in the database.
+     * Disabled by default. Enable via `logging: true` (uses backend's built-in logger)
+     * or by passing a custom `JobLogger` implementation.
+     */
+    jobLogger?: JobLogger;
+    /**
+     * Default logging behavior for job definitions that don't explicitly set `logging`.
+     * When `true` (default when logging is enabled), all jobs are logged.
+     * When `false`, only jobs with `logging: true` in their definition are logged.
+     */
+    loggingDefault: boolean;
+    on(event: 'ready', listener: () => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    on(event: 'fail', listener: (error: Error, job: JobWithId, remote?: false) => void): this;
+    on(event: 'fail', listener: (error: string, job: JobStateNotification, remote: true) => void): this;
+    on(event: 'success', listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: 'success', listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: 'start', listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: 'start', listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: 'complete', listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: 'complete', listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: 'progress', listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: 'progress', listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: 'retry', listener: (job: JobWithId, details: RetryDetails, remote?: false) => void): this;
+    on(event: 'retry', listener: (job: JobStateNotification, details: RetryDetails, remote: true) => void): this;
+    on(event: 'retry exhausted', listener: (error: Error, job: JobWithId) => void): this;
+    on(event: `fail:${string}`, listener: (error: Error, job: JobWithId, remote?: false) => void): this;
+    on(event: `fail:${string}`, listener: (error: string, job: JobStateNotification, remote: true) => void): this;
+    on(event: `success:${string}`, listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: `success:${string}`, listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: `start:${string}`, listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: `start:${string}`, listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: `complete:${string}`, listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: `complete:${string}`, listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: `progress:${string}`, listener: (job: JobWithId, remote?: false) => void): this;
+    on(event: `progress:${string}`, listener: (job: JobStateNotification, remote: true) => void): this;
+    on(event: `retry:${string}`, listener: (job: JobWithId, details: RetryDetails, remote?: false) => void): this;
+    on(event: `retry:${string}`, listener: (job: JobStateNotification, details: RetryDetails, remote: true) => void): this;
+    on(event: `retry exhausted:${string}`, listener: (error: Error, job: JobWithId) => void): this;
+    readonly definitions: {
+        [name: string]: JobDefinition;
+    };
+    private jobProcessor?;
+    readonly ready: Promise<void>;
+    isActiveJobProcessor(): boolean;
+    runForkedJob(jobId: string): Promise<void>;
+    getRunningStats(fullDetails?: boolean): Promise<AgendaStatus>;
+    /**
+     * @param config - Agenda configuration with backend
+     * @param cb - Optional callback after Agenda is ready
+     */
+    constructor(config: AgendaOptions, cb?: (error?: Error) => void);
+    /**
+     * Cancels any jobs matching the passed options, and removes them from the database.
+     * @param options Options for which jobs to cancel
+     */
+    cancel(options: RemoveJobsOptions): Promise<number>;
+    /**
+     * Disables any jobs matching the passed options, preventing them from being run.
+     * @param options Options for which jobs to disable
+     * @returns Number of jobs disabled
+     */
+    disable(options: RemoveJobsOptions): Promise<number>;
+    /**
+     * Enables any jobs matching the passed options, allowing them to be run.
+     * @param options Options for which jobs to enable
+     * @returns Number of jobs enabled
+     */
+    enable(options: RemoveJobsOptions): Promise<number>;
+    /**
+     * Set name of queue
+     * @param name
+     */
+    name(name: string): Agenda;
+    /**
+     * Set the time how often the job processor checks for new jobs to process
+     * @param time
+     */
+    processEvery(time: string | number): Agenda;
+    /**
+     * Set the concurrency for jobs (globally), type does not matter
+     * @param num
+     */
+    maxConcurrency(num: number): Agenda;
+    /**
+     * Set the default concurrency for each job
+     * @param num number of max concurrency
+     */
+    defaultConcurrency(num: number): Agenda;
+    /**
+     * Set the default amount jobs that are allowed to be locked at one time (GLOBAL)
+     * @param num
+     */
+    lockLimit(num: number): Agenda;
+    /**
+     * Set default lock limit per job type
+     * @param num
+     */
+    defaultLockLimit(num: number): Agenda;
+    /**
+     * Set the default lock time (in ms)
+     * Default is 10 * 60 * 1000 ms (10 minutes)
+     * @param ms
+     */
+    defaultLockLifetime(ms: number): Agenda;
+    /**
+     * Set a notification channel for real-time job notifications
+     * @param channel - The notification channel implementation
+     */
+    notifyVia(channel: NotificationChannel): Agenda;
+    /**
+     * Check if a notification channel is configured
+     */
+    hasNotificationChannel(): boolean;
+    /**
+     * Check if persistent job logging is enabled
+     */
+    hasJobLogger(): boolean;
+    /**
+     * Log a job lifecycle event to the persistent job logger (fire-and-forget).
+     * Does nothing if no job logger is configured or if logging is disabled
+     * for the job definition (respects per-definition `logging` and the global `loggingDefault`).
+     * @internal
+     */
+    logJobEvent(entry: Omit<JobLogEntry, '_id' | 'timestamp' | 'agendaName'>): void;
+    /**
+     * Query persistent job logs.
+     * Returns empty result if no job logger is configured.
+     */
+    getLogs(query?: JobLogQuery): Promise<JobLogQueryResult>;
+    /**
+     * Clear persistent job logs matching the query.
+     * Returns 0 if no job logger is configured.
+     */
+    clearLogs(query?: JobLogQuery): Promise<number>;
+    /**
+     * Publish a job notification to the notification channel
+     * @internal
+     */
+    publishJobNotification(job: Job): Promise<void>;
+    /**
+     * Publish a job state notification to the notification channel.
+     * This enables bi-directional communication so that all subscribers
+     * can receive job lifecycle events (start, success, fail, complete, etc.)
+     * @internal
+     */
+    publishJobStateNotification(job: Job, type: JobStateType, extra?: Partial<Omit<JobStateNotification, 'type' | 'jobId' | 'jobName' | 'timestamp' | 'source'>>): void;
+    /**
+     * Subscribe to state notifications and re-emit them as regular events.
+     * This allows `agenda.on('success:jobName', ...)` to work across processes.
+     * @internal
+     */
+    private subscribeToStateNotifications;
+    /**
+     * Query jobs with database-agnostic options.
+     * Returns jobs with computed states and supports filtering by state.
+     *
+     * @param options - Query options (name, state, search, pagination)
+     * @returns Jobs with computed states and total count
+     */
+    queryJobs(options?: JobsQueryOptions): Promise<JobsResult>;
+    /**
+     * Get overview statistics for jobs grouped by name.
+     * Returns counts of jobs in each state for each job name.
+     *
+     * @returns Array of job overviews with state counts
+     */
+    getJobsOverview(): Promise<JobsOverview[]>;
+    /**
+     * Removes all orphaned jobs (jobs whose names are not currently defined).
+     * @note: Only use after defining your jobs
+     */
+    purge(): Promise<number>;
+    /**
+     * Removes ALL jobs from the database unconditionally.
+     * Use with caution — this cannot be undone.
+     * @returns Number of jobs removed
+     */
+    cancelAll(): Promise<number>;
+    /**
+     * Setup definition for job
+     * Method is used by consumers of lib to setup their functions
+     * BREAKING CHANGE in v4: options moved from 2nd to 3rd parameter!
+     * @param name
+     * @param processor
+     * @param options
+     */
+    define<DATA = any>(name: string, processor: (agendaJob: Job<DATA>, done: (error?: Error) => void) => void, options?: Partial<Pick<JobDefinition, 'lockLimit' | 'lockLifetime' | 'concurrency' | 'backoff' | 'removeOnComplete' | 'logging'>> & {
+        priority?: JobPriority;
+    }): void;
+    define<DATA = any>(name: string, processor: (agendaJob: Job<DATA>) => Promise<void>, options?: Partial<Pick<JobDefinition, 'lockLimit' | 'lockLifetime' | 'concurrency' | 'backoff' | 'removeOnComplete' | 'logging'>> & {
+        priority?: JobPriority;
+    }): void;
+    /**
+     * Internal helper method that uses createJob to create jobs for an array of names
+     * @param names - Job names to schedule
+     * @param createJob - Factory function to create each job
+     * @returns Array of created jobs
+     */
+    private createJobs;
+    /**
+     * Given a name and some data, create a new job
+     * @param name
+     */
+    create(name: string): Job<void>;
+    create<DATA = unknown>(name: string, data: DATA): Job<DATA>;
+    /**
+     * Creates a scheduled job with given interval and name/names of the job to run
+     * @param interval
+     * @param names
+     * @param data
+     * @param options
+     */
+    every(interval: string | number, names: string[], data?: undefined, options?: {
+        timezone?: string;
+        skipImmediate?: boolean;
+        forkMode?: boolean;
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<void>[]>;
+    every(interval: string | number, name: string, data?: undefined, options?: {
+        timezone?: string;
+        skipImmediate?: boolean;
+        forkMode?: boolean;
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<void>>;
+    every<DATA = unknown>(interval: string | number, names: string[], data: DATA, options?: {
+        timezone?: string;
+        skipImmediate?: boolean;
+        forkMode?: boolean;
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>[]>;
+    every<DATA = unknown>(interval: string | number, name: string, data: DATA, options?: {
+        timezone?: string;
+        skipImmediate?: boolean;
+        forkMode?: boolean;
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>>;
+    /**
+     * Schedule a job or jobs at a specific time
+     * @param when
+     * @param names
+     * @param data
+     * @param options
+     */
+    schedule<DATA = void>(when: string | Date, names: string[], data?: undefined, options?: {
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>[]>;
+    schedule<DATA = void>(when: string | Date, names: string, data?: undefined, options?: {
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>>;
+    schedule<DATA = unknown>(when: string | Date, names: string[], data: DATA, options?: {
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>[]>;
+    schedule<DATA = unknown>(when: string | Date, name: string, data: DATA, options?: {
+        startDate?: Date | string;
+        endDate?: Date | string;
+        skipDays?: number[];
+    }): Promise<Job<DATA>>;
+    /**
+     * Create a job for this exact moment
+     * @param name
+     */
+    now<DATA = void>(name: string): Promise<Job<DATA>>;
+    now<DATA = unknown>(name: string, data: DATA): Promise<Job<DATA>>;
+    /**
+     * Create a debounced job that combines rapid submissions into a single execution.
+     * Requires a unique key to identify which jobs should be debounced together.
+     *
+     * @param name - Job name
+     * @param data - Job data
+     * @param uniqueKey - Unique constraint to identify jobs (e.g., { 'data.userId': 123 })
+     * @param debounceMs - Debounce delay in milliseconds
+     * @param options - Optional debounce options (maxWait, strategy)
+     *
+     * @example
+     * ```ts
+     * // Debounce search index updates by entity type
+     * await agenda.nowDebounced(
+     *   'updateSearchIndex',
+     *   { entityType: 'products' },
+     *   { 'data.entityType': 'products' },
+     *   2000
+     * );
+     *
+     * // With maxWait to guarantee execution within 30s
+     * await agenda.nowDebounced(
+     *   'syncUser',
+     *   { userId: 123 },
+     *   { 'data.userId': 123 },
+     *   5000,
+     *   { maxWait: 30000 }
+     * );
+     * ```
+     */
+    nowDebounced<DATA = unknown>(name: string, data: DATA, uniqueKey: Record<string, unknown>, debounceMs: number, options?: {
+        maxWait?: number;
+        strategy?: 'trailing' | 'leading';
+    }): Promise<Job<DATA>>;
+    /**
+     * Starts processing jobs using processJobs() methods, storing an interval ID
+     * This method will only resolve if a db has been set up beforehand.
+     */
+    start(): Promise<void>;
+    /**
+     * Clear the interval that processes the jobs and unlocks all currently locked jobs
+     * @param closeConnection - Whether to close the database connection.
+     *   Defaults to backend.ownsConnection (true if backend created the connection,
+     *   false if connection was passed in by user).
+     */
+    stop(closeConnection?: boolean): Promise<void>;
+    /**
+     * Waits for all currently running jobs to finish before stopping.
+     * This allows for a graceful shutdown where jobs complete their work.
+     * Unlike stop(), this method waits for running jobs to complete instead of unlocking them.
+     *
+     * @param options - Drain options or timeout in milliseconds
+     *   - `timeout`: Maximum time to wait for jobs to complete
+     *   - `signal`: AbortSignal to cancel the drain operation
+     *   - `closeConnection`: Whether to close the database connection (default: backend.ownsConnection)
+     * @returns DrainResult with completion statistics
+     *
+     * @example
+     * // Wait indefinitely for all jobs to complete
+     * await agenda.drain();
+     *
+     * @example
+     * // Wait up to 30 seconds
+     * const result = await agenda.drain(30000);
+     * if (result.timedOut) console.log(`${result.running} jobs still running`);
+     *
+     * @example
+     * // Use AbortSignal for external control
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 30000);
+     * await agenda.drain({ signal: controller.signal });
+     */
+    drain(options?: number | (DrainOptions & {
+        closeConnection?: boolean;
+    })): Promise<DrainResult>;
+}
+export * from './types/AgendaConfig.js';
+export * from './types/JobDefinition.js';
+export * from './types/JobParameters.js';
+export * from './types/DbOptions.js';
+export * from './Job.js';
+export * from './types/JobQuery.js';
+export * from './types/JobRepository.js';
+export * from './types/NotificationChannel.js';
+export * from './types/AgendaBackend.js';
+export * from './types/AgendaStatus.js';
+export * from './types/DrainOptions.js';
+export * from './notifications/index.js';
+export * from './types/JobLogger.js';
+export { applyAllDateConstraints, applyDateRangeConstraints, applySkipDays, shouldSkipDay, isWithinDateRange } from './utils/dateConstraints.js';
+export * from './decorators/index.js';
+export { backoffStrategies, constant, linear, exponential, combine, when, type BackoffStrategy, type BackoffContext, type BackoffOptions, type ExponentialBackoffOptions, type LinearBackoffOptions } from './utils/backoff.js';