agenda 6.0.0 → 6.2.0

package/dist/notifications/BaseNotificationChannel.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import type { NotificationChannel, NotificationChannelConfig, JobNotification, NotificationHandler, NotificationChannelState } from '../types/NotificationChannel.js';
+import type { NotificationChannel, NotificationChannelConfig, JobNotification, NotificationHandler, NotificationChannelState, JobStateNotification, StateNotificationHandler } from '../types/NotificationChannel.js';
 /**
  * Internal config type with all properties required
  */
@@ -19,6 +19,7 @@ interface ResolvedNotificationChannelConfig {
 export declare abstract class BaseNotificationChannel extends EventEmitter implements NotificationChannel {
     protected _state: NotificationChannelState;
     protected handlers: Set<NotificationHandler>;
+    protected stateHandlers: Set<StateNotificationHandler>;
     protected reconnectAttempts: number;
     protected reconnectTimeout?: ReturnType<typeof setTimeout>;
     protected readonly config: ResolvedNotificationChannelConfig;
@@ -30,6 +31,16 @@ export declare abstract class BaseNotificationChannel extends EventEmitter imple
     abstract publish(notification: JobNotification): Promise<void>;
     subscribe(handler: NotificationHandler): () => void;
     protected notifyHandlers(notification: JobNotification): Promise<void>;
+    /**
+     * Notify all registered state handlers of a state notification.
+     * Subclasses should call this when receiving state notifications.
+     */
+    protected notifyStateHandlers(notification: JobStateNotification): Promise<void>;
+    /**
+     * Subscribe to state notifications.
+     * Default implementation manages the stateHandlers set.
+     */
+    subscribeState(handler: StateNotificationHandler): () => void;
     protected scheduleReconnect(): void;
     protected clearReconnect(): void;
 }

package/dist/notifications/BaseNotificationChannel.js

@@ -6,6 +6,7 @@ import { EventEmitter } from 'events';
 export class BaseNotificationChannel extends EventEmitter {
     _state = 'disconnected';
     handlers = new Set();
+    stateHandlers = new Set();
     reconnectAttempts = 0;
     reconnectTimeout;
     config;
@@ -51,6 +52,35 @@ export class BaseNotificationChannel extends EventEmitter {
         }
         await Promise.allSettled(promises);
     }
+    /**
+     * Notify all registered state handlers of a state notification.
+     * Subclasses should call this when receiving state notifications.
+     */
+    async notifyStateHandlers(notification) {
+        const promises = [];
+        for (const handler of this.stateHandlers) {
+            try {
+                const result = handler(notification);
+                if (result instanceof Promise) {
+                    promises.push(result);
+                }
+            }
+            catch (error) {
+                this.emit('error', error);
+            }
+        }
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Subscribe to state notifications.
+     * Default implementation manages the stateHandlers set.
+     */
+    subscribeState(handler) {
+        this.stateHandlers.add(handler);
+        return () => {
+            this.stateHandlers.delete(handler);
+        };
+    }
     scheduleReconnect() {
         if (!this.config.reconnect.enabled) {
             return;

package/dist/notifications/BaseNotificationChannel.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseNotificationChannel.js","sourceRoot":"","sources":["../../src/notifications/BaseNotificationChannel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseNotificationChannel.js","sourceRoot":"","sources":["../../src/notifications/BaseNotificationChannel.ts"],"names":[],"mappings":"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"}

package/dist/notifications/InMemoryNotificationChannel.d.ts

@@ -1,4 +1,4 @@
-import type { NotificationChannelConfig, JobNotification } from '../types/NotificationChannel.js';
+import type { NotificationChannelConfig, JobNotification, JobStateNotification } from '../types/NotificationChannel.js';
 import { BaseNotificationChannel } from './BaseNotificationChannel.js';
 /**
  * In-memory notification channel for testing and single-process scenarios.
@@ -9,4 +9,5 @@ export declare class InMemoryNotificationChannel extends BaseNotificationChannel
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     publish(notification: JobNotification): Promise<void>;
+    publishState(notification: JobStateNotification): Promise<void>;
 }

package/dist/notifications/InMemoryNotificationChannel.js

@@ -14,6 +14,7 @@ export class InMemoryNotificationChannel extends BaseNotificationChannel {
     async disconnect() {
         this.clearReconnect();
         this.handlers.clear();
+        this.stateHandlers.clear();
         this.setState('disconnected');
     }
     async publish(notification) {
@@ -22,5 +23,11 @@ export class InMemoryNotificationChannel extends BaseNotificationChannel {
         }
         await this.notifyHandlers(notification);
     }
+    async publishState(notification) {
+        if (this._state !== 'connected') {
+            throw new Error('Cannot publish state: channel not connected');
+        }
+        await this.notifyStateHandlers(notification);
+    }
 }
 //# sourceMappingURL=InMemoryNotificationChannel.js.map

package/dist/notifications/InMemoryNotificationChannel.js.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryNotificationChannel.js","sourceRoot":"","sources":["../../src/notifications/InMemoryNotificationChannel.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,uBAAuB;IACvE,YAAY,SAAoC,EAAE;QACjD,KAAK,CAAC,MAAM,CAAC,CAAC;IACf,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU;QACf,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,YAA6B;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;CACD"}
+{"version":3,"file":"InMemoryNotificationChannel.js","sourceRoot":"","sources":["../../src/notifications/InMemoryNotificationChannel.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,uBAAuB;IACvE,YAAY,SAAoC,EAAE;QACjD,KAAK,CAAC,MAAM,CAAC,CAAC;IACf,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU;QACf,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,YAA6B;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,YAAkC;QACpD,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,IAAI,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC9C,CAAC;CACD"}

package/dist/types/AgendaBackend.d.ts

@@ -1,5 +1,6 @@
 import type { JobRepository } from './JobRepository.js';
 import type { NotificationChannel } from './NotificationChannel.js';
+import type { JobLogger } from './JobLogger.js';
 /**
  * Unified backend interface for Agenda.
  *
@@ -29,6 +30,13 @@ export interface AgendaBackend {
      * If not provided, Agenda falls back to periodic polling.
      */
     readonly notificationChannel?: NotificationChannel;
+    /**
+     * Job logger for persistent job event logging.
+     * Backends provide a logger that stores events in a dedicated table/collection.
+     * The logger is lightweight and only initializes its storage on first use.
+     * Agenda activates this logger when the user enables logging via `logging: true`.
+     */
+    readonly logger?: JobLogger;
     /**
      * Whether the backend owns its database connection.
      * - true: backend created the connection (e.g., from connection string)

package/dist/types/AgendaConfig.d.ts

@@ -6,4 +6,5 @@ export interface AgendaConfig {
     defaultLockLimit: number;
     lockLimit: number;
     defaultLockLifetime: number;
+    removeOnComplete: boolean;
 }

package/dist/types/DrainOptions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Options for the drain() method
+ */
+export interface DrainOptions {
+    /**
+     * Maximum time in milliseconds to wait for jobs to complete.
+     * If not specified, drain() will wait indefinitely.
+     */
+    timeout?: number;
+    /**
+     * AbortSignal to cancel the drain operation.
+     * When aborted, drain() will resolve immediately with the current state.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result of the drain() operation
+ */
+export interface DrainResult {
+    /**
+     * Number of jobs that completed during the drain
+     */
+    completed: number;
+    /**
+     * Number of jobs still running when drain finished
+     * (only non-zero if timeout was hit or signal was aborted)
+     */
+    running: number;
+    /**
+     * Whether the drain finished because the timeout was reached
+     */
+    timedOut: boolean;
+    /**
+     * Whether the drain finished because the signal was aborted
+     */
+    aborted: boolean;
+}

package/dist/types/DrainOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DrainOptions.js.map

package/dist/types/DrainOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DrainOptions.js","sourceRoot":"","sources":["../../src/types/DrainOptions.ts"],"names":[],"mappings":""}

package/dist/types/JobDefinition.d.ts

@@ -34,6 +34,15 @@ export interface JobDefinition<DATA = unknown> {
      * ```
      */
     backoff?: BackoffStrategy;
+    /** Automatically remove this job from database after successful completion (one-time jobs only) */
+    removeOnComplete?: boolean;
+    /**
+     * Enable or disable persistent logging for this job definition.
+     * When `false`, no log entries are written for jobs of this type,
+     * even if a global job logger is configured.
+     * Defaults to `true` (logging enabled when a job logger is configured).
+     */
+    logging?: boolean;
     filePath: string | undefined;
     fn: DefinitionProcessor<DATA, void | ((error?: Error) => void)>;
 }

package/dist/types/JobLogger.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Log level for job event entries.
+ */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+/**
+ * Job lifecycle events that are logged.
+ */
+export type JobLogEvent = 'start' | 'success' | 'fail' | 'complete' | 'retry' | 'retry:exhausted' | 'locked' | 'expired';
+/**
+ * A structured log entry for a job lifecycle event.
+ */
+export interface JobLogEntry {
+    /** Unique identifier (assigned by the storage backend) */
+    _id?: string;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Log severity level */
+    level: LogLevel;
+    /** The lifecycle event type */
+    event: JobLogEvent;
+    /** The job ID (if applicable) */
+    jobId?: string;
+    /** The job name */
+    jobName: string;
+    /** Human-readable message describing the event */
+    message: string;
+    /** Duration of execution in milliseconds (for success/complete events) */
+    duration?: number;
+    /** Error message (for fail events) */
+    error?: string;
+    /** Number of failures (for fail/retry events) */
+    failCount?: number;
+    /** Delay before the next retry in milliseconds (for retry events) */
+    retryDelay?: number;
+    /** The retry attempt number (for retry events) */
+    retryAttempt?: number;
+    /** The name of the Agenda instance that logged this event */
+    agendaName?: string;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Query options for retrieving log entries.
+ */
+export interface JobLogQuery {
+    /** Filter by job ID */
+    jobId?: string;
+    /** Filter by job name */
+    jobName?: string;
+    /** Filter by log level(s) */
+    level?: LogLevel | LogLevel[];
+    /** Filter by event type(s) */
+    event?: JobLogEvent | JobLogEvent[];
+    /** Filter entries from this date (inclusive) */
+    from?: Date;
+    /** Filter entries up to this date (inclusive) */
+    to?: Date;
+    /** Maximum number of entries to return (default: 50) */
+    limit?: number;
+    /** Number of entries to skip for pagination */
+    offset?: number;
+    /** Sort direction by timestamp (default: 'desc') */
+    sort?: 'asc' | 'desc';
+}
+/**
+ * Result of a log query including entries and total count (for pagination).
+ */
+export interface JobLogQueryResult {
+    /** The log entries matching the query */
+    entries: JobLogEntry[];
+    /** Total number of entries matching the query (ignoring limit/offset) */
+    total: number;
+}
+/**
+ * Pluggable interface for persistent job event logging.
+ *
+ * Implement this interface to store job lifecycle logs in your preferred backend.
+ * Each backend package (mongo, postgres, redis) provides a built-in implementation
+ * that stores logs in a dedicated table/collection alongside the jobs.
+ *
+ * @example
+ * ```typescript
+ * // Enable backend's built-in logger
+ * const agenda = new Agenda({
+ *   backend: new PostgresBackend({ connectionString: '...', logging: true }),
+ *   logging: true
+ * });
+ *
+ * // Query logs
+ * const result = await agenda.getLogs({ jobName: 'myJob', limit: 100 });
+ * ```
+ */
+export interface JobLogger {
+    /**
+     * Write a log entry.
+     * Called automatically by Agenda for each job lifecycle event.
+     * Implementations should be fast and non-blocking.
+     */
+    log(entry: Omit<JobLogEntry, '_id'>): Promise<void>;
+    /**
+     * Query log entries with optional filtering and pagination.
+     * Used by agendash to display logs.
+     */
+    getLogs(query?: JobLogQuery): Promise<JobLogQueryResult>;
+    /**
+     * Delete log entries matching the query.
+     * If no query is provided, deletes ALL log entries.
+     * Returns the number of deleted entries.
+     */
+    clearLogs(query?: JobLogQuery): Promise<number>;
+}

package/dist/types/JobLogger.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=JobLogger.js.map

package/dist/types/JobLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobLogger.js","sourceRoot":"","sources":["../../src/types/JobLogger.ts"],"names":[],"mappings":""}

package/dist/types/NotificationChannel.d.ts

@@ -10,6 +10,42 @@ export interface JobNotification {
     timestamp: Date;
     source?: string;
 }
+/**
+ * Types of job state events that can be published
+ */
+export type JobStateType = 'start' | 'progress' | 'success' | 'fail' | 'complete' | 'retry';
+/**
+ * Notification payload sent when a job's state changes during execution.
+ * This enables bi-directional communication so that all subscribers
+ * can receive job lifecycle events (start, success, fail, complete, etc.)
+ */
+export interface JobStateNotification {
+    type: JobStateType;
+    jobId: JobId;
+    jobName: string;
+    timestamp: Date;
+    source?: string;
+    /** Progress percentage (0-100) for 'progress' events */
+    progress?: number;
+    /** Error message for 'fail' events */
+    error?: string;
+    /** Failure count for 'fail' events */
+    failCount?: number;
+    /** Scheduled retry time for 'retry' events */
+    retryAt?: Date;
+    /** Retry attempt number for 'retry' events */
+    retryAttempt?: number;
+    /** Job execution duration in ms for 'complete' events */
+    duration?: number;
+    /** When the job started for 'complete' events */
+    lastRunAt?: Date;
+    /** When the job finished for 'complete' events */
+    lastFinishedAt?: Date;
+}
+/**
+ * Handler function for processing job state notifications
+ */
+export type StateNotificationHandler = (notification: JobStateNotification) => void | Promise<void>;
 /**
  * Handler function for processing job notifications
  */
@@ -68,4 +104,17 @@ export interface NotificationChannel {
      */
     off(event: 'stateChange', listener: (state: NotificationChannelState) => void): this;
     off(event: 'error', listener: (error: Error) => void): this;
+    /**
+     * Publish a job state notification (bi-directional communication).
+     * Optional - only implement if the channel supports state notifications.
+     * @param notification - The state notification to publish
+     */
+    publishState?(notification: JobStateNotification): Promise<void>;
+    /**
+     * Subscribe to job state notifications (bi-directional communication).
+     * Optional - only implement if the channel supports state notifications.
+     * @param handler - Function to call when a state notification is received
+     * @returns Unsubscribe function
+     */
+    subscribeState?(handler: StateNotificationHandler): () => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenda",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Light weight job scheduler for Node.js",
   "type": "module",
   "main": "dist/index.js",