@quave/agenda-mongodb 1.0.0

package/LICENSE.md

@@ -0,0 +1,25 @@
+## License
+(The MIT License)
+
+Copyright (c) 2013 Ryan Schmukler <ryan@slingingcode.com>
+
+Copyright (c) 2022-2026 Simon Tretter <s.tretter@gmail.com>
+
+Contributors: Mikael Korpela, Alexis Tyler, Vasyl Boroviak, Haris Sulaiman, Loris Guignard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# @quave/agenda-mongodb
+
+> Quave-managed fork of [@agendajs/mongo-backend](https://github.com/agenda/agenda) (forked at `4.0.2`, commit `b9c47688`). MongoDB backend for [`@quave/agenda`](../agenda).
+
+## Runtime compatibility
+
+- **mongodb driver**: `^4.17.0 || ^5.0.0 || ^6.0.0 || ^7.0.0` (peer dependency). Driver 4.17 is the line bundled with Meteor 2.x; the repository normalizes the `findOneAndUpdate` result-shape difference between driver 4/5 (ModifyResult) and 6/7 (document) automatically. Tests run against both driver 7.x and 4.17.
+- **Node.js**: 14.13.1+ for the package itself (dual ESM + CommonJS builds, ES2020 target); your chosen mongodb driver sets its own floor (driver 6 needs Node 16.20+, driver 7 needs Node 20.19+).
+- **Meteor 2.x**: supported — pass the app's existing driver-4 `Db` handle via `new MongoBackend({ mongo: db })`. CI runs a Meteor-style simulation (Node 14 + CommonJS + driver 4.17) on every push.
+
+MongoDB backend for [Agenda](https://www.npmjs.com/package/agenda) job scheduler.
+
+## Installation
+
+```bash
+npm install @quave/agenda @quave/agenda-mongodb
+# or
+pnpm add @quave/agenda @quave/agenda-mongodb
+# or
+yarn add @quave/agenda @quave/agenda-mongodb
+```
+
+**Requirements:**
+- Node.js 18+
+- MongoDB 4+
+
+## Usage
+
+```typescript
+import { Agenda } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+
+// Via connection string
+const agenda = new Agenda({
+  backend: new MongoBackend({
+    address: 'mongodb://localhost/agenda'
+  })
+});
+
+// Or via existing MongoDB connection
+import { MongoClient } from 'mongodb';
+
+const client = await MongoClient.connect('mongodb://localhost');
+const db = client.db('agenda');
+
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db })
+});
+
+// Define jobs
+agenda.define('send-email', async (job) => {
+  const { to, subject } = job.attrs.data;
+  await sendEmail(to, subject);
+});
+
+// Start processing
+await agenda.start();
+
+// Schedule jobs
+await agenda.every('1 hour', 'send-email', { to: 'user@example.com', subject: 'Hello' });
+```
+
+## Configuration Options
+
+```typescript
+interface IMongoBackendConfig {
+  /** MongoDB connection string */
+  address?: string;
+
+  /** Existing MongoDB database instance */
+  mongo?: Db;
+
+  /** Collection name for jobs (default: 'agendaJobs') */
+  collection?: string;
+
+  /** MongoDB client options */
+  options?: MongoClientOptions;
+
+  /** Name to identify this Agenda instance (stored as lastModifiedBy) */
+  name?: string;
+
+  /** Whether to create indexes on connect (default: true) */
+  ensureIndex?: boolean;
+
+  /** Sort order for job queries */
+  sort?: { [key: string]: SortDirection };
+}
+```
+
+### Full Example with Options
+
+```typescript
+const agenda = new Agenda({
+  backend: new MongoBackend({
+    address: 'mongodb://localhost/agenda',
+    collection: 'jobs',           // Custom collection name
+    sort: { nextRunAt: 'asc', priority: 'desc' }
+  }),
+  processEvery: '30 seconds',     // Job polling interval
+  maxConcurrency: 20,             // Max concurrent jobs
+  defaultConcurrency: 5           // Default per job type
+});
+```
+
+## Real-Time Notifications
+
+MongoBackend provides storage only and uses polling to check for new jobs. For real-time job processing across distributed systems, you have several options:
+
+### Option 1: MongoDB Change Streams (Native)
+
+If your MongoDB deployment is a replica set (even a single-node replica set works), you can use `MongoChangeStreamNotificationChannel` for native real-time notifications without any external dependencies:
+
+```typescript
+import { Agenda } from '@quave/agenda';
+import { MongoBackend, MongoChangeStreamNotificationChannel } from '@quave/agenda-mongodb';
+
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  notificationChannel: new MongoChangeStreamNotificationChannel({ db })
+});
+
+// Jobs are processed immediately when created (no polling delay)
+await agenda.start();
+await agenda.now('myJob'); // Triggers instant processing
+```
+
+**Requirements:**
+- MongoDB replica set (single-node replica sets work fine)
+- WiredTiger storage engine (default since MongoDB 3.2)
+
+**Configuration options:**
+```typescript
+const channel = new MongoChangeStreamNotificationChannel({
+  db: mongoDb,                    // Required: MongoDB database instance
+  collection: 'agendaJobs',       // Optional: collection name (default: 'agendaJobs')
+  resumeToken: savedToken,        // Optional: resume from specific point
+  fullDocument: true              // Optional: include full document on updates (default: true)
+});
+```
+
+### Option 2: In-Memory (Single Process)
+
+```typescript
+import { Agenda, InMemoryNotificationChannel } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+
+// For single-process apps (testing/development)
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  notificationChannel: new InMemoryNotificationChannel()
+});
+```
+
+### Option 3: Redis Pub/Sub (Multi-Process)
+
+```typescript
+import { Agenda } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+import { RedisBackend } from '@agendajs/redis-backend';
+
+// For production: use Redis for notifications
+const redisBackend = new RedisBackend({ connectionString: 'redis://localhost:6379' });
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  notificationChannel: redisBackend.notificationChannel
+});
+```
+
+## Database Index
+
+By default, MongoBackend automatically creates the `findAndLockNextJobIndex` index on connect for optimal job query performance. The index includes:
+
+```javascript
+{
+  "name": 1,
+  "nextRunAt": 1,
+  "priority": -1,
+  "lockedAt": 1,
+  "disabled": 1
+}
+```
+
+To disable automatic index creation (e.g., if you manage indexes separately):
+
+```typescript
+const backend = new MongoBackend({
+  mongo: db,
+  ensureIndex: false  // Skip automatic index creation
+});
+```
+
+### Additional Indexes
+
+If you use **Agendash**, add this index for better dashboard performance:
+
+```javascript
+db.agendaJobs.createIndex({
+  "nextRunAt": -1,
+  "lastRunAt": -1,
+  "lastFinishedAt": -1
+}, { name: "agendash" })
+```
+
+If you have job definitions with thousands of instances, this index can improve lock queries:
+
+```javascript
+db.agendaJobs.createIndex({
+  "name": 1,
+  "disabled": 1,
+  "lockedAt": 1
+}, { name: "findAndLockDeadJobs" })
+```
+
+## Job Logging
+
+MongoBackend includes a built-in `MongoJobLogger` that stores structured job lifecycle events in a dedicated MongoDB collection (`agenda_logs` by default). The logger is lightweight and only creates its collection on first use.
+
+### Automatic Usage
+
+When you enable logging in Agenda, the backend's built-in logger is used automatically:
+
+```typescript
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  logging: true  // Uses MongoJobLogger automatically
+});
+```
+
+### Standalone Usage
+
+You can also use `MongoJobLogger` independently — for example, to log to MongoDB while using a different backend for storage:
+
+```typescript
+import { MongoJobLogger } from '@quave/agenda-mongodb';
+
+const logger = new MongoJobLogger({
+  mongo: db,                        // Required: MongoDB database instance
+  logCollection: 'agenda_logs'      // Optional: collection name (default: 'agenda_logs')
+});
+
+// Use with any backend
+import { RedisBackend } from '@agendajs/redis-backend';
+const agenda = new Agenda({
+  backend: new RedisBackend({ connectionString: 'redis://...' }),
+  logging: logger
+});
+```
+
+### Querying Logs
+
+```typescript
+const { entries, total } = await agenda.getLogs({
+  jobName: 'send-email',
+  level: 'error',
+  limit: 50,
+  sort: 'desc'
+});
+
+// Clear old logs
+await agenda.clearLogs({ to: new Date(Date.now() - 30 * 86400000) });
+```
+
+See the [Agenda README](https://github.com/agenda/agenda#persistent-job-logging) for full logging documentation.
+
+## Related Packages
+
+- [agenda](https://www.npmjs.com/package/agenda) - Core scheduler
+- [@agendajs/postgres-backend](https://www.npmjs.com/package/@agendajs/postgres-backend) - PostgreSQL backend with LISTEN/NOTIFY
+- [@agendajs/redis-backend](https://www.npmjs.com/package/@agendajs/redis-backend) - Redis backend with Pub/Sub
+
+## License
+
+MIT

package/dist/MongoBackend.d.ts

@@ -0,0 +1,58 @@
+import type { AgendaBackend, JobRepository, NotificationChannel, JobLogger } from '@quave/agenda';
+import type { MongoBackendConfig } from './types.js';
+/**
+ * MongoDB backend for Agenda.
+ * Provides storage via MongoDB. Does not provide notifications (uses polling).
+ *
+ * @example
+ * ```typescript
+ * import { Agenda } from '@quave/agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * // Via connection string
+ * const backend = new MongoBackend({ address: 'mongodb://localhost/agenda' });
+ *
+ * // Via existing connection
+ * const backend = new MongoBackend({ mongo: existingDb });
+ *
+ * // With persistent job event logging
+ * const backend = new MongoBackend({ mongo: existingDb, logging: true });
+ *
+ * const agenda = new Agenda({ backend, logging: true });
+ * ```
+ */
+export declare class MongoBackend implements AgendaBackend {
+    private config;
+    readonly name = "MongoDB";
+    private _repository;
+    private _ownsConnection;
+    private _logger;
+    /**
+     * MongoDB does not provide a notification channel.
+     * For real-time notifications with MongoDB, use a separate notification
+     * channel like Redis pub/sub.
+     */
+    readonly notificationChannel: NotificationChannel | undefined;
+    constructor(config: MongoBackendConfig);
+    get repository(): JobRepository;
+    /**
+     * The job logger for persistent event logging.
+     * Always available; Agenda decides whether to activate it via its `logging` config.
+     */
+    get logger(): JobLogger;
+    /**
+     * Whether this backend owns its database connection.
+     * True if created from address (connection string), false if mongo Db was passed in.
+     */
+    get ownsConnection(): boolean;
+    /**
+     * Connect to MongoDB and initialize the collection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from MongoDB.
+     * Only closes the connection if we created it (i.e., from connection string).
+     * If an existing Db instance was passed in, this is a no-op.
+     */
+    disconnect(): Promise<void>;
+}

package/dist/MongoBackend.js

@@ -0,0 +1,82 @@
+import { MongoJobRepository } from './MongoJobRepository.js';
+import { MongoJobLogger } from './MongoJobLogger.js';
+/**
+ * MongoDB backend for Agenda.
+ * Provides storage via MongoDB. Does not provide notifications (uses polling).
+ *
+ * @example
+ * ```typescript
+ * import { Agenda } from '@quave/agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * // Via connection string
+ * const backend = new MongoBackend({ address: 'mongodb://localhost/agenda' });
+ *
+ * // Via existing connection
+ * const backend = new MongoBackend({ mongo: existingDb });
+ *
+ * // With persistent job event logging
+ * const backend = new MongoBackend({ mongo: existingDb, logging: true });
+ *
+ * const agenda = new Agenda({ backend, logging: true });
+ * ```
+ */
+export class MongoBackend {
+    constructor(config) {
+        this.config = config;
+        this.name = 'MongoDB';
+        /**
+         * MongoDB does not provide a notification channel.
+         * For real-time notifications with MongoDB, use a separate notification
+         * channel like Redis pub/sub.
+         */
+        this.notificationChannel = undefined;
+        // Determine if we own the connection (not passed in by user)
+        this._ownsConnection = !('mongo' in config);
+        this._repository = new MongoJobRepository({
+            ...('mongo' in config
+                ? { mongo: config.mongo, db: { collection: config.collection } }
+                : {
+                    db: { address: config.address, collection: config.collection, options: config.options }
+                }),
+            ensureIndex: config.ensureIndex,
+            sort: config.sort
+        });
+        // Always create the logger (lightweight; only initializes on first use when Agenda activates it)
+        this._logger = new MongoJobLogger(config.logCollection);
+    }
+    get repository() {
+        return this._repository;
+    }
+    /**
+     * The job logger for persistent event logging.
+     * Always available; Agenda decides whether to activate it via its `logging` config.
+     */
+    get logger() {
+        return this._logger;
+    }
+    /**
+     * Whether this backend owns its database connection.
+     * True if created from address (connection string), false if mongo Db was passed in.
+     */
+    get ownsConnection() {
+        return this._ownsConnection;
+    }
+    /**
+     * Connect to MongoDB and initialize the collection.
+     */
+    async connect() {
+        await this._repository.connect();
+        // Initialize the job logger with the shared database connection
+        await this._logger.setDb(this._repository.getDb());
+    }
+    /**
+     * Disconnect from MongoDB.
+     * Only closes the connection if we created it (i.e., from connection string).
+     * If an existing Db instance was passed in, this is a no-op.
+     */
+    async disconnect() {
+        await this._repository.disconnect();
+    }
+}
+//# sourceMappingURL=MongoBackend.js.map

package/dist/MongoBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MongoBackend.js","sourceRoot":"","sources":["../src/MongoBackend.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,YAAY;IAcxB,YAAoB,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;QAbrC,SAAI,GAAG,SAAS,CAAC;QAM1B;;;;WAIG;QACM,wBAAmB,GAAoC,SAAS,CAAC;QAGzE,6DAA6D;QAC7D,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,IAAI,kBAAkB,CAAC;YACzC,GAAG,CAAC,OAAO,IAAI,MAAM;gBACpB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE;gBAChE,CAAC,CAAC;oBACA,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;iBACvF,CAAC;YACJ,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;SACjB,CAAC,CAAC;QAEH,iGAAiG;QACjG,IAAI,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,IAAI,cAAc;QACjB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACZ,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QAEjC,gEAAgE;QAChE,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU;QACf,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;IACrC,CAAC;CACD"}

package/dist/MongoChangeStreamNotificationChannel.d.ts

@@ -0,0 +1,96 @@
+import type { Db, ResumeToken } from 'mongodb';
+import type { JobNotification, NotificationChannelConfig } from '@quave/agenda';
+import { BaseNotificationChannel } from '@quave/agenda';
+/**
+ * Configuration for MongoChangeStreamNotificationChannel
+ */
+export interface MongoChangeStreamNotificationChannelConfig extends NotificationChannelConfig {
+    /**
+     * MongoDB database instance.
+     * Required - must be connected to a replica set.
+     */
+    db?: Db;
+    /**
+     * Collection name to watch (default: 'agendaJobs')
+     */
+    collection?: string;
+    /**
+     * Resume token to resume watching from a specific point.
+     * Useful for recovering from disconnections.
+     */
+    resumeToken?: ResumeToken;
+    /**
+     * Whether to use fullDocument: 'updateLookup' for update events.
+     * This fetches the full document on updates but adds latency.
+     * Default: true (required for proper notification data)
+     */
+    fullDocument?: boolean;
+}
+/**
+ * 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 declare class MongoChangeStreamNotificationChannel extends BaseNotificationChannel {
+    private db?;
+    private collectionName;
+    private collection?;
+    private changeStream?;
+    private resumeToken?;
+    private useFullDocument;
+    constructor(config?: MongoChangeStreamNotificationChannelConfig);
+    /**
+     * Set the MongoDB database instance.
+     * Used when the channel is created before the database connection.
+     */
+    setDb(db: Db): void;
+    /**
+     * Get the last resume token for reconnection purposes.
+     * Store this token to resume watching from the same point after restart.
+     */
+    getResumeToken(): ResumeToken | undefined;
+    connect(): Promise<void>;
+    private handleChange;
+    private extractFullDocument;
+    private buildNotification;
+    private handleConnectionLoss;
+    disconnect(): Promise<void>;
+    /**
+     * 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.
+     */
+    publish(_notification: JobNotification): Promise<void>;
+}