@quave/agenda 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,380 @@
+# @quave/agenda
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/agenda/agenda@main/agenda.svg" alt="Agenda" width="100" height="100">
+</p>
+
+<p align="center">
+  A light-weight job scheduling library for Node.js
+</p>
+
+> Quave-managed fork of [agenda](https://github.com/agenda/agenda) 6.x (forked at `agenda@6.2.5`, commit `b9c47688`), kept on current dependencies and the newest MongoDB driver. Published as `@quave/agenda` (core) and [`@quave/agenda-mongodb`](../agenda-mongodb) (MongoDB backend).
+
+> **Migrating from agenda v5?** See the upstream [Migration Guide](https://github.com/agenda/agenda/blob/main/docs/migration-guide-v6.md) for all breaking changes.
+
+## Runtime compatibility
+
+Unlike upstream agenda 6.x (ESM-only, Node 18+), this fork ships **dual ESM + CommonJS builds** with an ES2020 emit target, so it also works on older runtimes:
+
+- **Node.js**: 14.13.1+ (CI smoke-tests the built package on Node 14.21).
+- **Meteor 2.x**: supported. Meteor 2.16 runs apps on Node 14.21 with CommonJS module loading — `require('@quave/agenda')` resolves the CJS build. CI runs a full Meteor-style simulation (Node 14 + CJS + mongodb driver 4.17) on every push.
+- Modern ESM projects get the ESM build via the `exports` map automatically.
+
+## Agenda 6.x
+
+Agenda 6.x is a complete TypeScript rewrite with a focus on **modularity** and **flexibility**:
+
+- **Pluggable storage backends** - Choose from MongoDB, PostgreSQL, Redis, or implement your own. Each backend is a separate package - install only what you need.
+
+- **Pluggable notification channels** - Move beyond polling with real-time job notifications via Redis, PostgreSQL LISTEN/NOTIFY, or other pub/sub systems. Jobs get processed immediately when saved, not on the next poll cycle.
+
+- **Modern stack** - ESM-only, Node.js 18+, full TypeScript with strict typing.
+
+See the [6.x Roadmap](https://github.com/agenda/agenda/issues/1610) for details and progress.
+
+## Features
+
+- Minimal overhead job scheduling
+- Pluggable storage backends (MongoDB, PostgreSQL, Redis)
+- TypeScript support with full typing
+- Scheduling via cron or human-readable syntax
+- Configurable concurrency and locking
+- Real-time job notifications (optional)
+- Sandboxed worker execution via fork mode
+- TypeScript decorators for class-based job definitions
+
+## Installation
+
+Install the core package and your preferred backend:
+
+```bash
+# For MongoDB
+npm install @quave/agenda @quave/agenda-mongodb
+
+# For PostgreSQL
+npm install agenda @agendajs/postgres-backend
+
+# For Redis
+npm install agenda @agendajs/redis-backend
+```
+
+**Requirements:**
+- Node.js 18+
+- Database of your choice (MongoDB 4+, PostgreSQL, or Redis)
+
+## Quick Start
+
+```javascript
+import { Agenda } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+
+const agenda = new Agenda({
+  backend: new MongoBackend({ address: 'mongodb://localhost/agenda' })
+});
+
+// Define a job
+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' });
+await agenda.schedule('in 5 minutes', 'send email', { to: 'admin@example.com', subject: 'Report' });
+await agenda.now('send email', { to: 'support@example.com', subject: 'Urgent' });
+```
+
+## Official Backend Packages
+
+| Package | Backend | Notifications | Install |
+|---------|---------|---------------|---------|
+| [`@quave/agenda-mongodb`](https://www.npmjs.com/package/@quave/agenda-mongodb) | MongoDB | Polling only | `npm install @quave/agenda-mongodb` |
+| [`@agendajs/postgres-backend`](https://www.npmjs.com/package/@agendajs/postgres-backend) | PostgreSQL | LISTEN/NOTIFY | `npm install @agendajs/postgres-backend` |
+| [`@agendajs/redis-backend`](https://www.npmjs.com/package/@agendajs/redis-backend) | Redis | Pub/Sub | `npm install @agendajs/redis-backend` |
+
+### Backend Capabilities
+
+| Backend | Storage | Notifications | Notes |
+|---------|:-------:|:-------------:|-------|
+| **MongoDB** (`MongoBackend`) | ✅ | ❌ | Storage only. Combine with external notification channel for real-time. |
+| **PostgreSQL** (`PostgresBackend`) | ✅ | ✅ | Full backend. Uses LISTEN/NOTIFY for notifications. |
+| **Redis** (`RedisBackend`) | ✅ | ✅ | Full backend. Uses Pub/Sub for notifications. |
+| **InMemoryNotificationChannel** | ❌ | ✅ | Notifications only. For single-process/testing. |
+
+## Backend Configuration
+
+### MongoDB
+
+```javascript
+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' })
+});
+
+// Via existing MongoDB connection
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: existingDb })
+});
+
+// With options
+const agenda = new Agenda({
+  backend: new MongoBackend({
+    mongo: db,
+    collection: 'jobs'        // Collection name (default: 'agendaJobs')
+  }),
+  processEvery: '30 seconds', // Job polling interval
+  maxConcurrency: 20,         // Max concurrent jobs
+  defaultConcurrency: 5       // Default per job type
+});
+```
+
+### PostgreSQL
+
+```javascript
+import { Agenda } from '@quave/agenda';
+import { PostgresBackend } from '@agendajs/postgres-backend';
+
+const agenda = new Agenda({
+  backend: new PostgresBackend({
+    connectionString: 'postgresql://user:pass@localhost:5432/mydb'
+  })
+});
+```
+
+### Redis
+
+```javascript
+import { Agenda } from '@quave/agenda';
+import { RedisBackend } from '@agendajs/redis-backend';
+
+const agenda = new Agenda({
+  backend: new RedisBackend({
+    connectionString: 'redis://localhost:6379'
+  })
+});
+```
+
+## Real-Time Notifications
+
+For faster job processing across distributed systems:
+
+```javascript
+import { Agenda, InMemoryNotificationChannel } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  notificationChannel: new InMemoryNotificationChannel()
+});
+```
+
+### Mixing Storage and Notification Backends
+
+You can use MongoDB for storage while using a different system for real-time notifications:
+
+```javascript
+import { Agenda } from '@quave/agenda';
+import { MongoBackend } from '@quave/agenda-mongodb';
+import { RedisBackend } from '@agendajs/redis-backend';
+
+// MongoDB for storage + Redis for real-time notifications
+const redisBackend = new RedisBackend({ connectionString: 'redis://localhost:6379' });
+const agenda = new Agenda({
+  backend: new MongoBackend({ mongo: db }),
+  notificationChannel: redisBackend.notificationChannel
+});
+```
+
+This is useful when you want MongoDB's proven durability and flexible queries for job storage, but need faster real-time notifications across multiple processes.
+
+## API Overview
+
+### Defining Jobs
+
+```javascript
+// Simple async handler
+agenda.define('my-job', async (job) => {
+  console.log('Processing:', job.attrs.data);
+});
+
+// With options
+agenda.define('my-job', async (job) => { /* ... */ }, {
+  concurrency: 10,
+  lockLimit: 5,
+  lockLifetime: 10 * 60 * 1000, // 10 minutes
+  priority: 'high'
+});
+```
+
+### Defining Jobs with Decorators
+
+For a class-based approach, use TypeScript decorators:
+
+```typescript
+import { JobsController, Define, Every, registerJobs, Job } from '@quave/agenda';
+
+@JobsController({ namespace: 'email' })
+class EmailJobs {
+  @Define({ concurrency: 5 })
+  async sendWelcome(job: Job<{ userId: string }>) {
+    console.log('Sending welcome to:', job.attrs.data.userId);
+  }
+
+  @Every('1 hour')
+  async cleanupBounced(job: Job) {
+    console.log('Cleaning up bounced emails');
+  }
+}
+
+registerJobs(agenda, [new EmailJobs()]);
+await agenda.start();
+
+// Schedule using namespaced name
+await agenda.now('email.sendWelcome', { userId: '123' });
+```
+
+See [Decorators Documentation](./docs/decorators.md) for full details.
+
+### Scheduling Jobs
+
+```javascript
+// Run immediately
+await agenda.now('my-job', { userId: '123' });
+
+// Run at specific time
+await agenda.schedule('tomorrow at noon', 'my-job', data);
+await agenda.schedule(new Date('2024-12-25'), 'my-job', data);
+
+// Run repeatedly
+await agenda.every('5 minutes', 'my-job');
+await agenda.every('0 * * * *', 'my-job'); // Cron syntax
+```
+
+### Job Control
+
+```javascript
+// Cancel jobs matching a filter (removes from database)
+await agenda.cancel({ name: 'my-job' });
+await agenda.cancel({ name: 'my-job', data: { userId: 123 } });
+
+// Cancel ALL jobs unconditionally
+await agenda.cancelAll();
+
+// Disable/enable jobs globally (by query)
+await agenda.disable({ name: 'my-job' });  // Disable all jobs matching query
+await agenda.enable({ name: 'my-job' });   // Enable all jobs matching query
+
+// Disable/enable individual jobs
+const job = await agenda.create('my-job', data);
+job.disable();
+await job.save();
+
+// Progress tracking
+agenda.define('long-job', async (job) => {
+  for (let i = 0; i <= 100; i += 10) {
+    await doWork();
+    await job.touch(i); // Report progress 0-100
+  }
+});
+```
+
+### Stopping / Draining
+
+```javascript
+// Stop immediately - unlocks running jobs so other workers can pick them up
+await agenda.stop();
+
+// Drain - waits for running jobs to complete before stopping
+await agenda.drain();
+
+// Drain with timeout (30 seconds) - for cloud platforms with shutdown deadlines
+const result = await agenda.drain(30000);
+if (result.timedOut) {
+    console.log(`${result.running} jobs still running after timeout`);
+}
+
+// Drain with AbortSignal - for external control
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30000);
+await agenda.drain({ signal: controller.signal });
+```
+
+Use `drain()` for graceful shutdowns where you want in-progress jobs to finish their work.
+
+### Events
+
+```javascript
+agenda.on('start', (job) => console.log('Job started:', job.attrs.name));
+agenda.on('complete', (job) => console.log('Job completed:', job.attrs.name));
+agenda.on('success', (job) => console.log('Job succeeded:', job.attrs.name));
+agenda.on('fail', (err, job) => console.log('Job failed:', job.attrs.name, err));
+
+// Job-specific events
+agenda.on('start:send email', (job) => { /* ... */ });
+agenda.on('fail:send email', (err, job) => { /* ... */ });
+```
+
+Use `fail` listeners to capture richer error context, such as stack traces,
+without storing large payloads in `job.attrs.failReason`:
+
+```javascript
+agenda.on('fail', async (err, job) => {
+	await saveJobError({
+		jobId: job.attrs._id,
+		jobName: job.attrs.name,
+		message: err.message,
+		stack: err.stack
+	});
+});
+```
+
+## Custom Backend
+
+For databases other than MongoDB, PostgreSQL, or Redis, implement `AgendaBackend`:
+
+```javascript
+import { AgendaBackend, JobRepository } from '@quave/agenda';
+
+class SQLiteBackend implements AgendaBackend {
+  readonly repository: JobRepository;
+  readonly notificationChannel = undefined; // Or implement NotificationChannel
+
+  async connect() { /* ... */ }
+  async disconnect() { /* ... */ }
+}
+
+const agenda = new Agenda({
+  backend: new SQLiteBackend({ path: './jobs.db' })
+});
+```
+
+See [Custom Backend Driver](https://github.com/agenda/agenda/blob/main/docs/custom-database-driver.md) for details.
+
+## Documentation
+
+- [Full Documentation](https://github.com/agenda/agenda#readme)
+- [Migration Guide (v5 to v6)](https://github.com/agenda/agenda/blob/main/docs/migration-guide-v6.md)
+- [Custom Backend Driver](https://github.com/agenda/agenda/blob/main/docs/custom-database-driver.md)
+- [TypeScript Decorators](./docs/decorators.md)
+- [API Reference](https://agenda.github.io/agenda/)
+
+## Related Packages
+
+**Official Backend Packages:**
+- [@quave/agenda-mongodb](https://www.npmjs.com/package/@quave/agenda-mongodb) - MongoDB backend
+- [@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
+
+**Tools:**
+- [agendash](https://www.npmjs.com/package/agendash) - Web dashboard for Agenda
+- [agenda-rest](https://www.npmjs.com/package/agenda-rest) - REST API for Agenda
+
+## License
+
+MIT

package/dist/Job.d.ts

@@ -0,0 +1,190 @@
+import type { Agenda } from './index.js';
+import { JobParameters, JobId } from './types/JobParameters.js';
+import { JobPriority } from './utils/priority.js';
+/**
+ * @class
+ */
+export declare class Job<DATA = unknown | void> {
+    readonly agenda: Agenda;
+    private readonly byJobProcessor;
+    readonly attrs: JobParameters<DATA>;
+    /** this flag is set to true, if a job got canceled (e.g. due to a timeout or other exception),
+     * you can use it for long running tasks to periodically check if canceled is true,
+     * also touch will check if and throws that the job got canceled
+     */
+    private canceled?;
+    getCanceledMessage(): string | true | Error | undefined;
+    private forkedChild?;
+    cancel(error?: Error): void;
+    /** internal variable to ensure a job does not set unlimited numbers of setTimeouts if the job is not processed
+     * immediately */
+    gotTimerToExecute: boolean;
+    /**
+     * creates a new job object
+     * @param agenda
+     * @param args
+     * @param byJobProcessor
+     */
+    constructor(agenda: Agenda, args: Partial<JobParameters<void>> & {
+        name: string;
+        type: 'normal' | 'single';
+    }, byJobProcessor?: boolean);
+    constructor(agenda: Agenda, args: Partial<JobParameters<DATA>> & {
+        name: string;
+        type: 'normal' | 'single';
+        data: DATA;
+    }, byJobProcessor?: boolean);
+    /**
+     * Fields managed by the job processor that should not be saved by user code.
+     * These are excluded in save() to prevent race conditions between user code and the processor.
+     */
+    private static readonly PROCESSOR_MANAGED_FIELDS;
+    /**
+     * Given a job, turn it into an JobParameters object
+     * @param excludeProcessorFields - If true, excludes fields managed by the job processor
+     */
+    toJson(excludeProcessorFields?: boolean): JobParameters;
+    /**
+     * Sets a job to repeat every X amount of time
+     * @param interval
+     * @param options
+     */
+    repeatEvery(interval: string | number, options?: {
+        timezone?: string;
+        skipImmediate?: boolean;
+    }): this;
+    /**
+     * Sets a job to repeat at a specific time
+     * @param time
+     */
+    repeatAt(time: string): this;
+    /**
+     * Sets the start date for the job.
+     * The job will not run before this date.
+     * @param date - The start date (Date object or string parseable by Date constructor)
+     */
+    startDate(dateInput: Date | string): this;
+    /**
+     * Sets the end date for the job.
+     * The job will not run after this date (nextRunAt will be set to null).
+     * @param date - The end date (Date object or string parseable by Date constructor)
+     */
+    endDate(dateInput: Date | string): this;
+    /**
+     * Sets the days of the week to skip.
+     * The job will not run on these days.
+     * @param days - Array of days to skip (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+     */
+    skipDays(days: number[]): this;
+    /**
+     * if set, a job is forked via node child process and runs in a seperate/own
+     * thread
+     * @param enableForkMode
+     */
+    forkMode(enableForkMode: boolean): this;
+    /**
+     * Prevents the job from running
+     */
+    disable(): this;
+    /**
+     * Allows job to run
+     */
+    enable(): this;
+    /**
+     * Data to ensure is unique for job to be created
+     * @param unique
+     * @param opts
+     */
+    unique(unique: Required<JobParameters<DATA>>['unique'], opts?: JobParameters['uniqueOpts']): this;
+    /**
+     * Configure debounce behavior for this job.
+     * Debouncing delays job execution and resets the timer on subsequent saves,
+     * ensuring the job only runs once after a quiet period.
+     *
+     * IMPORTANT: Requires a unique constraint to be set via `.unique()`.
+     * The unique constraint identifies which jobs should be debounced together.
+     *
+     * @param delay - Debounce window in milliseconds
+     * @param options - Optional configuration (maxWait, strategy)
+     *
+     * @example
+     * ```ts
+     * // Basic trailing debounce - execute 2s after last save
+     * await agenda.create('updateIndex', { entityId: 123 })
+     *   .unique({ 'data.entityId': 123 })
+     *   .debounce(2000)
+     *   .save();
+     *
+     * // With maxWait - guarantee execution within 30s
+     * await agenda.create('syncUser', { userId: 456 })
+     *   .unique({ 'data.userId': 456 })
+     *   .debounce(5000, { maxWait: 30000 })
+     *   .save();
+     *
+     * // Leading strategy - execute immediately, ignore subsequent calls
+     * await agenda.create('notify', { channel: '#alerts' })
+     *   .unique({ 'data.channel': '#alerts' })
+     *   .debounce(60000, { strategy: 'leading' })
+     *   .save();
+     * ```
+     */
+    debounce(delay: number, options?: {
+        maxWait?: number;
+        strategy?: 'trailing' | 'leading';
+    }): this;
+    /**
+     * Schedules a job to run at specified time.
+     * Date constraints (startDate, endDate, skipDays) are applied if set.
+     * @param time
+     */
+    schedule(time: string | Date): this;
+    /**
+     * Sets priority of the job
+     * @param priority priority of when job should be queued
+     */
+    priority(priority: JobPriority): this;
+    /**
+     * Fails the job with a reason (error) specified
+     *
+     * @param reason
+     */
+    fail(reason: Error | string): this;
+    private fetchStatus;
+    /**
+     * A job is running if:
+     * (lastRunAt exists AND lastFinishedAt does not exist)
+     * OR
+     * (lastRunAt exists AND lastFinishedAt exists but the lastRunAt is newer [in time] than lastFinishedAt)
+     * @returns Whether or not job is running at the moment (true for running)
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Saves a job to database
+     */
+    save(): Promise<Job>;
+    /**
+     * Remove the job from database
+     */
+    remove(): Promise<number>;
+    isDead(): Promise<boolean>;
+    isExpired(): Promise<boolean>;
+    /**
+     * Updates "lockedAt" time so the job does not get picked up again
+     * @param progress 0 to 100
+     */
+    touch(progress?: number): Promise<void>;
+    private computeNextRunAt;
+    /**
+     * Handle automatic retry with backoff strategy
+     * @param error - The error that caused the failure
+     */
+    private handleRetry;
+    run(): Promise<void>;
+    runJob(): Promise<void>;
+    private isPromise;
+}
+export type JobWithId = Job & {
+    attrs: JobParameters & {
+        _id: JobId;
+    };
+};