@quave/agenda-mongodb 1.0.0

package/dist/MongoChangeStreamNotificationChannel.js

@@ -0,0 +1,248 @@
+import debug from 'debug';
+import { BaseNotificationChannel, toJobId } from '@quave/agenda';
+const log = debug('agenda:mongo:changestream');
+/**
+ * MongoDB Change Stream notification channel.
+ *
+ * Uses MongoDB Change Streams to watch for job changes in real-time.
+ * This eliminates the need for polling and provides instant notifications
+ * when jobs are created or updated.
+ *
+ * **Requirements:**
+ * - MongoDB must be deployed as a replica set (even single-node replica sets work)
+ * - WiredTiger storage engine (default since MongoDB 3.2)
+ *
+ * **How it works:**
+ * - Watches the jobs collection for insert/update/replace operations
+ * - When a job with `nextRunAt` is modified, handlers are notified
+ * - The `publish()` method is a no-op since Change Streams automatically
+ *   detect job changes from any source
+ *
+ * @example
+ * ```typescript
+ * import { Agenda } from '@quave/agenda';
+ * import { MongoBackend, MongoChangeStreamNotificationChannel } from '@quave/agenda-mongodb';
+ *
+ * const backend = new MongoBackend({ mongo: db });
+ * const channel = new MongoChangeStreamNotificationChannel({ db });
+ *
+ * const agenda = new Agenda({
+ *   backend,
+ *   notificationChannel: channel
+ * });
+ * ```
+ */
+export class MongoChangeStreamNotificationChannel extends BaseNotificationChannel {
+    constructor(config = {}) {
+        super(config);
+        this.db = config.db;
+        this.collectionName = config.collection ?? 'agendaJobs';
+        this.resumeToken = config.resumeToken;
+        this.useFullDocument = config.fullDocument ?? true;
+    }
+    /**
+     * Set the MongoDB database instance.
+     * Used when the channel is created before the database connection.
+     */
+    setDb(db) {
+        if (this._state === 'connected') {
+            throw new Error('Cannot set database while channel is connected');
+        }
+        this.db = db;
+    }
+    /**
+     * Get the last resume token for reconnection purposes.
+     * Store this token to resume watching from the same point after restart.
+     */
+    getResumeToken() {
+        return this.resumeToken;
+    }
+    async connect() {
+        log('connecting change stream notification channel (current state=%s)', this._state);
+        this.clearReconnect();
+        // Idempotent: a second connect() must not leak the active change stream.
+        if (this._state === 'connected' && this.changeStream) {
+            log('already connected, ignoring connect()');
+            return;
+        }
+        if (!this.db) {
+            throw new Error('MongoChangeStreamNotificationChannel requires a MongoDB database instance. ' +
+                'Provide it via config.db or call setDb() before connecting.');
+        }
+        try {
+            this.setState('connecting');
+            log('getting collection: %s', this.collectionName);
+            this.collection = this.db.collection(this.collectionName);
+            // Build the aggregation pipeline to filter relevant changes
+            const pipeline = [
+                {
+                    $match: {
+                        // Watch for job inserts, updates, and replacements
+                        operationType: { $in: ['insert', 'update', 'replace'] }
+                    }
+                }
+            ];
+            // Change stream options
+            const options = {};
+            // Use fullDocument lookup to get the complete document on updates
+            // This is required to get job data on update events
+            if (this.useFullDocument) {
+                options.fullDocument = 'updateLookup';
+            }
+            // Resume from a specific token if provided
+            if (this.resumeToken) {
+                options.resumeAfter = this.resumeToken;
+                log('resuming from token: %O', this.resumeToken);
+            }
+            log('creating change stream with options: %O', options);
+            // Create the change stream
+            this.changeStream = this.collection.watch(pipeline, options);
+            // Handle change events
+            this.changeStream.on('change', (change) => {
+                this.handleChange(change);
+            });
+            // Handle errors
+            this.changeStream.on('error', (error) => {
+                log('change stream error: %O', error);
+                this.emit('error', error);
+                if (this._state === 'connected') {
+                    this.handleConnectionLoss();
+                }
+            });
+            // Handle stream close - only treat as connection loss if we didn't initiate it
+            this.changeStream.on('close', () => {
+                log('change stream closed (state=%s)', this._state);
+                // Only handle as connection loss if we're still in connected state
+                // (not if we're disconnecting or already disconnected)
+                if (this._state === 'connected') {
+                    this.handleConnectionLoss();
+                }
+            });
+            log('change stream connected, watching collection: %s', this.collectionName);
+            this.setState('connected');
+        }
+        catch (error) {
+            log('connection failed: %O', error);
+            this.emit('error', error);
+            this.scheduleReconnect();
+            throw error;
+        }
+    }
+    handleChange(change) {
+        try {
+            log('received change event: operationType=%s', change.operationType);
+            // Store resume token for recovery
+            if (change._id) {
+                this.resumeToken = change._id;
+            }
+            // Get the full document based on operation type
+            const fullDocument = this.extractFullDocument(change);
+            if (!fullDocument) {
+                log('change event without full document (operationType=%s), skipping', change.operationType);
+                return;
+            }
+            log('extracted fullDocument: name=%s, nextRunAt=%s, disabled=%s', fullDocument.name, fullDocument.nextRunAt, fullDocument.disabled);
+            // Only notify for jobs that have a nextRunAt (scheduled to run)
+            if (!fullDocument.nextRunAt) {
+                log('job has no nextRunAt, skipping notification');
+                return;
+            }
+            // Skip disabled jobs
+            if (fullDocument.disabled) {
+                log('job is disabled, skipping notification');
+                return;
+            }
+            // Build notification from the document
+            const notification = this.buildNotification(fullDocument);
+            log('received change notification: %O', notification);
+            this.notifyHandlers(notification).catch((err) => {
+                this.emit('error', err);
+            });
+        }
+        catch (error) {
+            log('error processing change event: %O', error);
+            this.emit('error', error);
+        }
+    }
+    extractFullDocument(change) {
+        // Handle insert events
+        if (change.operationType === 'insert') {
+            const insertChange = change;
+            return insertChange.fullDocument;
+        }
+        // Handle update events (requires fullDocument: 'updateLookup' option)
+        if (change.operationType === 'update') {
+            const updateChange = change;
+            if (updateChange.fullDocument) {
+                return updateChange.fullDocument;
+            }
+            log('update event missing fullDocument - ensure fullDocument option is set');
+            return null;
+        }
+        // Handle replace events
+        if (change.operationType === 'replace') {
+            const replaceChange = change;
+            return replaceChange.fullDocument;
+        }
+        return null;
+    }
+    buildNotification(doc) {
+        return {
+            jobId: toJobId(String(doc._id)),
+            jobName: doc.name,
+            nextRunAt: doc.nextRunAt ? new Date(doc.nextRunAt) : null,
+            priority: doc.priority || 0,
+            timestamp: new Date(),
+            source: 'changestream'
+        };
+    }
+    handleConnectionLoss() {
+        log('handling connection loss');
+        if (this.changeStream) {
+            try {
+                this.changeStream.close().catch(() => {
+                    // Ignore close errors
+                });
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.changeStream = undefined;
+        }
+        this.scheduleReconnect();
+    }
+    async disconnect() {
+        log('disconnecting change stream notification channel');
+        this.clearReconnect();
+        // Set state first to prevent close event from triggering reconnection
+        this.setState('disconnected');
+        if (this.changeStream) {
+            try {
+                await this.changeStream.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.changeStream = undefined;
+        }
+        this.handlers.clear();
+    }
+    /**
+     * Publish a job notification.
+     *
+     * **Note:** This method is a no-op for Change Stream notifications.
+     * Change Streams automatically detect job changes in the database,
+     * so explicit publishing is not required. This method exists only
+     * to satisfy the NotificationChannel interface.
+     *
+     * All job saves to the watched collection will automatically trigger
+     * notifications to all subscribers.
+     */
+    async publish(_notification) {
+        // No-op: Change Streams automatically detect database changes.
+        // When a job is saved to MongoDB, the change stream will pick it up
+        // and notify all handlers automatically.
+        log('publish called (no-op for change stream - changes detected automatically)');
+    }
+}
+//# sourceMappingURL=MongoChangeStreamNotificationChannel.js.map

package/dist/MongoChangeStreamNotificationChannel.js.map

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

package/dist/MongoJobLogger.d.ts

@@ -0,0 +1,46 @@
+import type { Db } from 'mongodb';
+import type { JobLogger, JobLogEntry, JobLogQuery, JobLogQueryResult } from '@quave/agenda';
+/**
+ * MongoDB implementation of JobLogger.
+ * Stores job lifecycle events in a dedicated MongoDB collection.
+ *
+ * @example
+ * ```typescript
+ * // Via backend (automatic connection sharing):
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * const backend = new MongoBackend({
+ *   mongo: db,
+ *   logging: true // enables MongoJobLogger with 'agenda_logs' collection
+ * });
+ *
+ * // Standalone (e.g., log to Mongo while using Postgres for storage):
+ * import { MongoJobLogger } from '@quave/agenda-mongodb';
+ *
+ * const logger = new MongoJobLogger({ db: existingDb });
+ * const agenda = new Agenda({
+ *   backend: new PostgresBackend({ connectionString: '...' }),
+ *   logging: logger
+ * });
+ * ```
+ */
+export declare class MongoJobLogger implements JobLogger {
+    private collection;
+    private readonly collectionName;
+    private initialized;
+    constructor(options?: {
+        db?: Db;
+        collectionName?: string;
+    } | string);
+    /**
+     * Set the database instance and initialize the collection.
+     * Called by MongoBackend after the repository connects,
+     * or automatically when a db is provided in the constructor.
+     */
+    setDb(db: Db): Promise<void>;
+    private ensureIndexes;
+    log(entry: Omit<JobLogEntry, '_id'>): Promise<void>;
+    getLogs(query?: JobLogQuery): Promise<JobLogQueryResult>;
+    clearLogs(query?: JobLogQuery): Promise<number>;
+    private buildFilter;
+}

package/dist/MongoJobLogger.js

@@ -0,0 +1,142 @@
+import debug from 'debug';
+const log = debug('agenda:mongo:logger');
+/**
+ * MongoDB implementation of JobLogger.
+ * Stores job lifecycle events in a dedicated MongoDB collection.
+ *
+ * @example
+ * ```typescript
+ * // Via backend (automatic connection sharing):
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * const backend = new MongoBackend({
+ *   mongo: db,
+ *   logging: true // enables MongoJobLogger with 'agenda_logs' collection
+ * });
+ *
+ * // Standalone (e.g., log to Mongo while using Postgres for storage):
+ * import { MongoJobLogger } from '@quave/agenda-mongodb';
+ *
+ * const logger = new MongoJobLogger({ db: existingDb });
+ * const agenda = new Agenda({
+ *   backend: new PostgresBackend({ connectionString: '...' }),
+ *   logging: logger
+ * });
+ * ```
+ */
+export class MongoJobLogger {
+    constructor(options) {
+        this.initialized = false;
+        if (typeof options === 'string') {
+            // Legacy: constructor(collectionName)
+            this.collectionName = options;
+        }
+        else {
+            this.collectionName = options?.collectionName ?? 'agenda_logs';
+            if (options?.db) {
+                this.collection = options.db.collection(this.collectionName);
+            }
+        }
+    }
+    /**
+     * Set the database instance and initialize the collection.
+     * Called by MongoBackend after the repository connects,
+     * or automatically when a db is provided in the constructor.
+     */
+    async setDb(db) {
+        this.collection = db.collection(this.collectionName);
+        await this.ensureIndexes();
+    }
+    async ensureIndexes() {
+        if (this.initialized || !this.collection)
+            return;
+        this.initialized = true;
+        log('creating indexes for %s collection', this.collectionName);
+        await this.collection.createIndex({ timestamp: -1 }, { name: 'agenda_logs_timestamp_idx' });
+        await this.collection.createIndex({ jobId: 1, timestamp: -1 }, { name: 'agenda_logs_job_id_idx' });
+        await this.collection.createIndex({ jobName: 1, timestamp: -1 }, { name: 'agenda_logs_job_name_idx' });
+        log('indexes created for %s collection', this.collectionName);
+    }
+    async log(entry) {
+        if (!this.collection) {
+            log('collection not initialized, skipping log entry');
+            return;
+        }
+        await this.ensureIndexes();
+        await this.collection.insertOne({ ...entry });
+    }
+    async getLogs(query) {
+        if (!this.collection) {
+            return { entries: [], total: 0 };
+        }
+        const filter = this.buildFilter(query);
+        const sort = { timestamp: query?.sort === 'asc' ? 1 : -1 };
+        const limit = query?.limit ?? 50;
+        const offset = query?.offset ?? 0;
+        const [entries, total] = await Promise.all([
+            this.collection
+                .find(filter)
+                .sort(sort)
+                .skip(offset)
+                .limit(limit)
+                .toArray()
+                .then(docs => docs.map(doc => ({
+                _id: doc._id.toHexString(),
+                timestamp: doc.timestamp,
+                level: doc.level,
+                event: doc.event,
+                jobId: doc.jobId,
+                jobName: doc.jobName,
+                message: doc.message,
+                duration: doc.duration,
+                error: doc.error,
+                failCount: doc.failCount,
+                retryDelay: doc.retryDelay,
+                retryAttempt: doc.retryAttempt,
+                agendaName: doc.agendaName,
+                meta: doc.meta
+            }))),
+            this.collection.countDocuments(filter)
+        ]);
+        return { entries, total };
+    }
+    async clearLogs(query) {
+        if (!this.collection) {
+            return 0;
+        }
+        const filter = this.buildFilter(query);
+        const result = await this.collection.deleteMany(filter);
+        return result.deletedCount;
+    }
+    buildFilter(query) {
+        if (!query)
+            return {};
+        const filter = {};
+        if (query.jobId) {
+            filter.jobId = query.jobId;
+        }
+        if (query.jobName) {
+            filter.jobName = query.jobName;
+        }
+        if (query.level) {
+            filter.level = Array.isArray(query.level)
+                ? { $in: query.level }
+                : query.level;
+        }
+        if (query.event) {
+            filter.event = Array.isArray(query.event)
+                ? { $in: query.event }
+                : query.event;
+        }
+        if (query.from || query.to) {
+            const timestampFilter = {};
+            if (query.from)
+                timestampFilter.$gte = query.from;
+            if (query.to)
+                timestampFilter.$lte = query.to;
+            filter.timestamp = timestampFilter;
+        }
+        return filter;
+    }
+}
+//# sourceMappingURL=MongoJobLogger.js.map

package/dist/MongoJobLogger.js.map

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

package/dist/MongoJobRepository.d.ts

@@ -0,0 +1,84 @@
+import { Collection, Db, ObjectId } from 'mongodb';
+import type { JobParameters, JobId, JobsQueryOptions, JobsResult, JobsOverview, JobRepository, JobRepositoryOptions, RemoveJobsOptions } from '@quave/agenda';
+import type { MongoJobRepositoryConfig } from './types.js';
+/**
+ * Internal MongoDB document type with ObjectId for _id
+ * This is what's actually stored in MongoDB, separate from the public JobParameters interface
+ */
+type MongoJobDocument = Omit<JobParameters, '_id'> & {
+    _id?: ObjectId;
+};
+/**
+ * @class
+ * MongoDB implementation of JobRepository
+ */
+export declare class MongoJobRepository implements JobRepository {
+    private connectOptions;
+    collection: Collection<MongoJobDocument>;
+    private mongoClient?;
+    private _db?;
+    private ownsConnection;
+    constructor(connectOptions: MongoJobRepositoryConfig);
+    private createConnection;
+    getJobById(id: string): Promise<JobParameters | null>;
+    /**
+     * Convert a SortDirection value to MongoDB's numeric sort direction
+     */
+    private toMongoSortDirection;
+    /**
+     * findOneAndUpdate that tolerates both driver result shapes: driver 6+
+     * returns the document (or null) directly, while drivers 4/5 — e.g. the
+     * mongodb driver bundled with Meteor 2.x — return a ModifyResult wrapper
+     * with the document under `value`.
+     */
+    private findOneAndUpdateDoc;
+    /**
+     * Convert generic sort options to MongoDB sort
+     */
+    private toMongoSort;
+    /**
+     * Query jobs with database-agnostic options.
+     * Handles state computation and filtering internally.
+     */
+    queryJobs(options?: JobsQueryOptions): Promise<JobsResult>;
+    /**
+     * Get overview statistics for jobs grouped by name.
+     * Returns counts of jobs in each state for each job name.
+     */
+    getJobsOverview(): Promise<JobsOverview[]>;
+    /**
+     * Get all distinct job names
+     */
+    getDistinctJobNames(): Promise<string[]>;
+    getQueueSize(): Promise<number>;
+    removeJobs(options: RemoveJobsOptions): Promise<number>;
+    /**
+     * Build a MongoDB filter from RemoveJobsOptions
+     */
+    private buildFilterFromOptions;
+    disableJobs(options: RemoveJobsOptions): Promise<number>;
+    enableJobs(options: RemoveJobsOptions): Promise<number>;
+    purgeAllJobs(): Promise<number>;
+    unlockJob(job: JobParameters): Promise<void>;
+    /**
+     * Internal method to unlock jobs so that they can be re-run
+     */
+    unlockJobs(jobIds: (JobId | string)[]): Promise<void>;
+    lockJob(job: JobParameters, options: JobRepositoryOptions | undefined): Promise<JobParameters | undefined>;
+    getNextJobToRun(jobName: string, nextScanAt: Date, lockDeadline: Date, now: Date | undefined, options: JobRepositoryOptions | undefined): Promise<JobParameters | undefined>;
+    /**
+     * Get the underlying MongoDB Db instance (for use by job logger).
+     */
+    getDb(): Db;
+    connect(): Promise<void>;
+    private database;
+    disconnect(): Promise<void>;
+    saveJobState(job: JobParameters, options: JobRepositoryOptions | undefined): Promise<void>;
+    /**
+     * Save a job to the database (insert or update)
+     * @param job Job parameters to save
+     * @returns The saved job parameters with ID
+     */
+    saveJob<DATA = unknown>(job: JobParameters<DATA>, options: JobRepositoryOptions | undefined): Promise<JobParameters<DATA>>;
+}
+export {};