@quave/agenda 1.0.0

package/dist/Job.js

@@ -0,0 +1,689 @@
+import date from 'date.js';
+import debug from 'debug';
+import { fork } from 'child_process';
+import { datefields } from './types/JobParameters.js';
+import { parsePriority } from './utils/priority.js';
+import { computeFromInterval, computeFromRepeatAt } from './utils/nextRunAt.js';
+import { applyAllDateConstraints } from './utils/dateConstraints.js';
+const log = debug('agenda:job');
+/**
+ * @class
+ */
+export class Job {
+    getCanceledMessage() {
+        return typeof this.canceled === 'object'
+            ? this.canceled?.message || this.canceled
+            : this.canceled;
+    }
+    cancel(error) {
+        this.canceled = error || true;
+        if (this.forkedChild) {
+            try {
+                this.forkedChild.send('cancel');
+                log('canceled child', this.attrs.name, this.attrs._id);
+            }
+            catch {
+                log('cannot send cancel to child');
+            }
+        }
+    }
+    constructor(agenda, args, byJobProcessor = false) {
+        this.agenda = agenda;
+        this.byJobProcessor = byJobProcessor;
+        this.attrs = {
+            ...args,
+            // Set defaults if undefined
+            nextRunAt: args.nextRunAt === undefined ? new Date() : args.nextRunAt,
+            priority: parsePriority(args.priority),
+            type: args.type
+        };
+    }
+    /**
+     * Given a job, turn it into an JobParameters object
+     * @param excludeProcessorFields - If true, excludes fields managed by the job processor
+     */
+    toJson(excludeProcessorFields = false) {
+        const result = {};
+        const attrs = this.attrs;
+        for (const key of Object.keys(attrs)) {
+            if (Object.hasOwnProperty.call(attrs, key)) {
+                // Skip processor-managed fields if requested
+                if (excludeProcessorFields && Job.PROCESSOR_MANAGED_FIELDS.has(key)) {
+                    continue;
+                }
+                result[key] =
+                    datefields.includes(key) && attrs[key]
+                        ? new Date(attrs[key])
+                        : attrs[key];
+            }
+        }
+        return result;
+    }
+    /**
+     * Sets a job to repeat every X amount of time
+     * @param interval
+     * @param options
+     */
+    repeatEvery(interval, options = {}) {
+        this.attrs.repeatInterval = interval;
+        this.attrs.repeatTimezone = options.timezone;
+        if (options.skipImmediate) {
+            // Set the lastRunAt time to the nextRunAt so that the new nextRunAt will be computed in reference to the current value.
+            this.attrs.lastRunAt = this.attrs.nextRunAt || new Date();
+            this.computeNextRunAt();
+            this.attrs.lastRunAt = undefined;
+        }
+        else {
+            this.computeNextRunAt();
+        }
+        return this;
+    }
+    /**
+     * Sets a job to repeat at a specific time
+     * @param time
+     */
+    repeatAt(time) {
+        this.attrs.repeatAt = time;
+        return 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) {
+        const d = new Date(dateInput);
+        if (Number.isNaN(d.getTime())) {
+            throw new Error(`Invalid start date: ${dateInput}`);
+        }
+        this.attrs.startDate = d;
+        return 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) {
+        const d = new Date(dateInput);
+        if (Number.isNaN(d.getTime())) {
+            throw new Error(`Invalid end date: ${dateInput}`);
+        }
+        this.attrs.endDate = d;
+        return 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) {
+        // Validate days
+        for (const day of days) {
+            if (day < 0 || day > 6 || !Number.isInteger(day)) {
+                throw new Error(`Invalid skip day: ${day}. Must be an integer 0-6 (0=Sunday, 6=Saturday)`);
+            }
+        }
+        this.attrs.skipDays = [...new Set(days)]; // Remove duplicates
+        return this;
+    }
+    /**
+     * if set, a job is forked via node child process and runs in a seperate/own
+     * thread
+     * @param enableForkMode
+     */
+    forkMode(enableForkMode) {
+        this.attrs.fork = enableForkMode;
+        return this;
+    }
+    /**
+     * Prevents the job from running
+     */
+    disable() {
+        this.attrs.disabled = true;
+        return this;
+    }
+    /**
+     * Allows job to run
+     */
+    enable() {
+        this.attrs.disabled = false;
+        return this;
+    }
+    /**
+     * Data to ensure is unique for job to be created
+     * @param unique
+     * @param opts
+     */
+    unique(unique, opts) {
+        this.attrs.unique = unique;
+        this.attrs.uniqueOpts = opts;
+        return 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, options) {
+        const debounceOpts = {
+            delay,
+            maxWait: options?.maxWait,
+            strategy: options?.strategy ?? 'trailing'
+        };
+        this.attrs.uniqueOpts = {
+            ...this.attrs.uniqueOpts,
+            debounce: debounceOpts
+        };
+        return this;
+    }
+    /**
+     * Schedules a job to run at specified time.
+     * Date constraints (startDate, endDate, skipDays) are applied if set.
+     * @param time
+     */
+    schedule(time) {
+        const d = new Date(time);
+        let nextRunAt = Number.isNaN(d.getTime()) ? date(time) : d;
+        // Apply date constraints if any are set
+        if (this.attrs.startDate || this.attrs.endDate || this.attrs.skipDays) {
+            nextRunAt = applyAllDateConstraints(nextRunAt, {
+                startDate: this.attrs.startDate,
+                endDate: this.attrs.endDate,
+                skipDays: this.attrs.skipDays,
+                timezone: this.attrs.repeatTimezone
+            });
+        }
+        this.attrs.nextRunAt = nextRunAt;
+        return this;
+    }
+    /**
+     * Sets priority of the job
+     * @param priority priority of when job should be queued
+     */
+    priority(priority) {
+        this.attrs.priority = parsePriority(priority);
+        return this;
+    }
+    /**
+     * Fails the job with a reason (error) specified
+     *
+     * @param reason
+     */
+    fail(reason) {
+        // Fork-mode children reject with plain serialized payloads (objects or
+        // strings), so normalize anything that is not an Error/string to keep
+        // failReason a string as its type promises.
+        let failReason;
+        if (reason instanceof Error) {
+            failReason = reason.message;
+        }
+        else if (typeof reason === 'string') {
+            failReason = reason;
+        }
+        else if (typeof reason === 'object' &&
+            reason !== null &&
+            typeof reason.message === 'string') {
+            failReason = reason.message;
+        }
+        else {
+            try {
+                failReason = JSON.stringify(reason) ?? String(reason);
+            }
+            catch {
+                failReason = String(reason);
+            }
+        }
+        this.attrs.failReason = failReason;
+        this.attrs.failCount = (this.attrs.failCount || 0) + 1;
+        const now = new Date();
+        this.attrs.failedAt = now;
+        this.attrs.lastFinishedAt = now;
+        log('[%s:%s] fail() called [%d] times so far', this.attrs.name, this.attrs._id, this.attrs.failCount);
+        return this;
+    }
+    async fetchStatus() {
+        const result = await this.agenda.db.queryJobs({ id: this.attrs._id?.toString() });
+        if (!result.jobs || result.jobs.length === 0) {
+            // @todo: should we just return false instead? a finished job could have been removed from database,
+            // and then this would throw...
+            throw new Error(`job with id ${this.attrs._id} not found in database`);
+        }
+        this.attrs.lastRunAt = result.jobs[0].lastRunAt;
+        this.attrs.lockedAt = result.jobs[0].lockedAt;
+        this.attrs.lastFinishedAt = result.jobs[0].lastFinishedAt;
+    }
+    /**
+     * 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)
+     */
+    async isRunning() {
+        if (!this.byJobProcessor || this.attrs.fork) {
+            // we have no job definition, therfore we are not the job processor, but a client call
+            // so we get the real state from database
+            await this.fetchStatus();
+        }
+        if (!this.attrs.lastRunAt) {
+            return false;
+        }
+        if (!this.attrs.lastFinishedAt) {
+            return true;
+        }
+        if (this.attrs.lockedAt &&
+            this.attrs.lastRunAt.getTime() > this.attrs.lastFinishedAt.getTime()) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Saves a job to database
+     */
+    async save() {
+        if (this.agenda.forkedWorker) {
+            const warning = new Error('calling save() on a Job during a forkedWorker has no effect!');
+            log('WARNING: %s %s', warning.message, warning.stack);
+            return this;
+        }
+        // ensure db connection is ready
+        await this.agenda.ready;
+        // save() is only called by user code (the job processor uses saveJobState() directly),
+        // so we always exclude processor-managed fields to prevent race conditions
+        const result = await this.agenda.db.saveJob(this.toJson(true), {
+            lastModifiedBy: this.agenda.attrs.name || undefined
+        });
+        // Update attrs from result
+        this.attrs._id = result._id;
+        this.attrs.nextRunAt = result.nextRunAt;
+        this.attrs.debounceStartedAt = result.debounceStartedAt;
+        // Publish notification for real-time processing if channel is configured
+        if (this.agenda.hasNotificationChannel()) {
+            await this.agenda.publishJobNotification(this);
+        }
+        return this;
+    }
+    /**
+     * Remove the job from database
+     */
+    remove() {
+        return this.agenda.cancel({ id: this.attrs._id });
+    }
+    async isDead() {
+        return this.isExpired();
+    }
+    async isExpired() {
+        if (!this.byJobProcessor || this.attrs.fork) {
+            // we have no job definition, therfore we are not the job processor, but a client call
+            // so we get the real state from database
+            await this.fetchStatus();
+        }
+        const definition = this.agenda.definitions[this.attrs.name];
+        if (!definition) {
+            throw new Error(`Undefined job ${this.attrs.name}`);
+        }
+        const lockDeadline = new Date(Date.now() - definition.lockLifetime);
+        // This means a job has "expired", as in it has not been "touched" within the lockoutTime
+        // Remove from local lock
+        if (this.attrs.lockedAt && this.attrs.lockedAt < lockDeadline) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Updates "lockedAt" time so the job does not get picked up again
+     * @param progress 0 to 100
+     */
+    async touch(progress) {
+        if (this.canceled) {
+            throw new Error(`job ${this.attrs.name} got canceled already: ${this.canceled}!`);
+        }
+        this.attrs.lockedAt = new Date();
+        this.attrs.progress = progress;
+        await this.agenda.db.saveJobState(this.attrs, {
+            lastModifiedBy: this.agenda.attrs.name || undefined
+        });
+        // Publish progress state notification if progress was provided (fire-and-forget)
+        if (progress !== undefined) {
+            this.agenda.publishJobStateNotification(this, 'progress', {
+                progress
+            });
+        }
+    }
+    computeNextRunAt() {
+        try {
+            if (this.attrs.repeatInterval) {
+                const nextRunAt = computeFromInterval(this.attrs);
+                this.attrs.nextRunAt = nextRunAt;
+                if (nextRunAt) {
+                    log('[%s:%s] nextRunAt set to [%s]', this.attrs.name, this.attrs._id, nextRunAt.toISOString());
+                }
+                else {
+                    log('[%s:%s] nextRunAt set to null (date constraints)', this.attrs.name, this.attrs._id);
+                }
+            }
+            else if (this.attrs.repeatAt) {
+                const nextRunAt = computeFromRepeatAt(this.attrs);
+                this.attrs.nextRunAt = nextRunAt;
+                if (nextRunAt) {
+                    log('[%s:%s] nextRunAt set to [%s]', this.attrs.name, this.attrs._id, nextRunAt.toISOString());
+                }
+                else {
+                    log('[%s:%s] nextRunAt set to null (date constraints)', this.attrs.name, this.attrs._id);
+                }
+            }
+            else {
+                this.attrs.nextRunAt = null;
+            }
+        }
+        catch (error) {
+            this.attrs.nextRunAt = null;
+            this.fail(error);
+        }
+        return this;
+    }
+    /**
+     * Handle automatic retry with backoff strategy
+     * @param error - The error that caused the failure
+     */
+    async handleRetry(error) {
+        const definition = this.agenda.definitions[this.attrs.name];
+        // No backoff strategy configured - skip auto-retry
+        if (!definition?.backoff) {
+            return;
+        }
+        const context = {
+            attempt: this.attrs.failCount || 1,
+            error,
+            jobName: this.attrs.name,
+            jobData: this.attrs.data
+        };
+        const retryDelay = definition.backoff(context);
+        if (retryDelay === null) {
+            // No more retries - emit exhausted event
+            log('[%s:%s] retry attempts exhausted after %d failures', this.attrs.name, this.attrs._id, this.attrs.failCount);
+            this.agenda.logJobEvent({
+                level: 'warn',
+                event: 'retry:exhausted',
+                jobId: this.attrs._id?.toString(),
+                jobName: this.attrs.name,
+                message: `retry exhausted after ${this.attrs.failCount} failures: ${error.message}`,
+                error: error.message,
+                failCount: this.attrs.failCount
+            });
+            this.agenda.emit('retry exhausted', error, this);
+            this.agenda.emit(`retry exhausted:${this.attrs.name}`, error, this);
+            return;
+        }
+        // Schedule retry
+        const nextRunAt = new Date(Date.now() + retryDelay);
+        this.attrs.nextRunAt = nextRunAt;
+        log('[%s:%s] scheduling retry #%d in %dms (at %s)', this.attrs.name, this.attrs._id, this.attrs.failCount, retryDelay, nextRunAt.toISOString());
+        this.agenda.logJobEvent({
+            level: 'info',
+            event: 'retry',
+            jobId: this.attrs._id?.toString(),
+            jobName: this.attrs.name,
+            message: `retry #${this.attrs.failCount} scheduled in ${retryDelay}ms`,
+            retryDelay,
+            retryAttempt: this.attrs.failCount ?? undefined,
+            error: error.message
+        });
+        this.agenda.emit('retry', this, {
+            attempt: this.attrs.failCount,
+            delay: retryDelay,
+            nextRunAt,
+            error
+        });
+        this.agenda.emit(`retry:${this.attrs.name}`, this, {
+            attempt: this.attrs.failCount,
+            delay: retryDelay,
+            nextRunAt,
+            error
+        });
+        // Publish retry state notification for cross-process event propagation (fire-and-forget)
+        this.agenda.publishJobStateNotification(this, 'retry', {
+            retryAt: nextRunAt,
+            retryAttempt: this.attrs.failCount,
+            error: error.message
+        });
+    }
+    async run() {
+        this.attrs.lastRunAt = new Date();
+        log('[%s:%s] setting lastRunAt to: %s', this.attrs.name, this.attrs._id, this.attrs.lastRunAt.toISOString());
+        this.computeNextRunAt();
+        await this.agenda.db.saveJobState(this.attrs, {
+            lastModifiedBy: this.agenda.attrs.name || undefined
+        });
+        let succeeded = false;
+        try {
+            this.agenda.emit('start', this);
+            this.agenda.emit(`start:${this.attrs.name}`, this);
+            log('[%s:%s] starting job', this.attrs.name, this.attrs._id);
+            this.agenda.logJobEvent({
+                level: 'info',
+                event: 'start',
+                jobId: this.attrs._id?.toString(),
+                jobName: this.attrs.name,
+                message: `job started`
+            });
+            // Publish start state notification for cross-process event propagation (fire-and-forget)
+            this.agenda.publishJobStateNotification(this, 'start', {
+                lastRunAt: this.attrs.lastRunAt
+            });
+            if (this.attrs.fork) {
+                if (!this.agenda.forkHelper) {
+                    throw new Error('no forkHelper specified, you need to set a path to a helper script');
+                }
+                const { forkHelper } = this.agenda;
+                await new Promise((resolve, reject) => {
+                    this.forkedChild = fork(forkHelper.path, [
+                        this.attrs.name,
+                        this.attrs._id.toString(),
+                        this.agenda.definitions[this.attrs.name].filePath || ''
+                    ], forkHelper.options);
+                    let childError;
+                    this.forkedChild.on('close', code => {
+                        if (code) {
+                            log('fork parameters: %O name=%s id=%s filePath=%s', forkHelper, this.attrs.name, this.attrs._id, this.agenda.definitions[this.attrs.name].filePath);
+                            const error = new Error(`child process exited with code: ${code}`);
+                            log('fork child error: %s %O', error.message, childError || this.canceled);
+                            reject(childError || this.canceled || error);
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                    this.forkedChild.on('message', message => {
+                        // console.log(`Message from child.js: ${message}`, JSON.stringify(message));
+                        if (typeof message === 'string') {
+                            try {
+                                childError = JSON.parse(message);
+                            }
+                            catch {
+                                childError = message;
+                            }
+                        }
+                        else {
+                            childError = message;
+                        }
+                    });
+                });
+            }
+            else {
+                await this.runJob();
+            }
+            this.attrs.lastFinishedAt = new Date();
+            this.agenda.emit('success', this);
+            this.agenda.emit(`success:${this.attrs.name}`, this);
+            log('[%s:%s] has succeeded', this.attrs.name, this.attrs._id);
+            const successDuration = this.attrs.lastFinishedAt.getTime() - (this.attrs.lastRunAt?.getTime() || 0);
+            this.agenda.logJobEvent({
+                level: 'info',
+                event: 'success',
+                jobId: this.attrs._id?.toString(),
+                jobName: this.attrs.name,
+                message: `job succeeded`,
+                duration: successDuration
+            });
+            succeeded = true;
+            // Publish success state notification for cross-process event propagation (fire-and-forget)
+            this.agenda.publishJobStateNotification(this, 'success', {
+                lastRunAt: this.attrs.lastRunAt,
+                lastFinishedAt: this.attrs.lastFinishedAt,
+                duration: this.attrs.lastFinishedAt.getTime() - (this.attrs.lastRunAt?.getTime() || 0)
+            });
+        }
+        catch (error) {
+            log('[%s:%s] unknown error occurred', this.attrs.name, this.attrs._id);
+            this.fail(error);
+            this.agenda.emit('fail', error, this);
+            this.agenda.emit(`fail:${this.attrs.name}`, error, this);
+            log('[%s:%s] has failed [%s]', this.attrs.name, this.attrs._id, error.message);
+            this.agenda.logJobEvent({
+                level: 'error',
+                event: 'fail',
+                jobId: this.attrs._id?.toString(),
+                jobName: this.attrs.name,
+                message: `job failed: ${error.message}`,
+                error: error.message,
+                failCount: this.attrs.failCount
+            });
+            // Publish fail state notification for cross-process event propagation (fire-and-forget)
+            this.agenda.publishJobStateNotification(this, 'fail', {
+                error: error.message,
+                failCount: this.attrs.failCount
+            });
+            // Handle automatic retry with backoff strategy
+            await this.handleRetry(error);
+        }
+        finally {
+            this.forkedChild = undefined;
+            this.attrs.lockedAt = undefined;
+            try {
+                await this.agenda.db.saveJobState(this.attrs, {
+                    lastModifiedBy: this.agenda.attrs.name || undefined
+                });
+                log('[%s:%s] was saved successfully to database', this.attrs.name, this.attrs._id);
+            }
+            catch (err) {
+                // in case this fails, we ignore it
+                // this can e.g. happen if the job gets removed during the execution
+                log('[%s:%s] was not saved to database', this.attrs.name, this.attrs._id, err);
+            }
+            this.agenda.emit('complete', this);
+            this.agenda.emit(`complete:${this.attrs.name}`, this);
+            log('[%s:%s] job finished at [%s] and was unlocked', this.attrs.name, this.attrs._id, this.attrs.lastFinishedAt);
+            const completeDuration = this.attrs.lastFinishedAt && this.attrs.lastRunAt
+                ? this.attrs.lastFinishedAt.getTime() - this.attrs.lastRunAt.getTime()
+                : undefined;
+            this.agenda.logJobEvent({
+                level: 'info',
+                event: 'complete',
+                jobId: this.attrs._id?.toString(),
+                jobName: this.attrs.name,
+                message: `job complete`,
+                duration: completeDuration
+            });
+            // Publish complete state notification for cross-process event propagation (fire-and-forget)
+            const duration = this.attrs.lastFinishedAt && this.attrs.lastRunAt
+                ? this.attrs.lastFinishedAt.getTime() - this.attrs.lastRunAt.getTime()
+                : undefined;
+            this.agenda.publishJobStateNotification(this, 'complete', {
+                lastRunAt: this.attrs.lastRunAt,
+                lastFinishedAt: this.attrs.lastFinishedAt,
+                duration
+            });
+            // Auto-remove completed one-time jobs
+            if (succeeded && !this.attrs.nextRunAt) {
+                const definition = this.agenda.definitions[this.attrs.name];
+                const shouldRemove = definition?.removeOnComplete ?? this.agenda.attrs.removeOnComplete;
+                if (shouldRemove) {
+                    try {
+                        await this.remove();
+                        log('[%s:%s] auto-removed completed one-time job', this.attrs.name, this.attrs._id);
+                    }
+                    catch (err) {
+                        log('[%s:%s] failed to auto-remove job', this.attrs.name, this.attrs._id, err);
+                    }
+                }
+            }
+        }
+    }
+    async runJob() {
+        const definition = this.agenda.definitions[this.attrs.name];
+        if (!definition) {
+            log('[%s:%s] has no definition, can not run', this.attrs.name, this.attrs._id);
+            throw new Error('Undefined job');
+        }
+        if (definition.fn.length === 2) {
+            log('[%s:%s] process function being called', this.attrs.name, this.attrs._id);
+            await new Promise((resolve, reject) => {
+                try {
+                    const result = definition.fn(this, error => {
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                    if (this.isPromise(result)) {
+                        result.catch((error) => reject(error));
+                    }
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        }
+        else {
+            log('[%s:%s] process function being called', this.attrs.name, this.attrs._id);
+            await definition.fn(this);
+        }
+    }
+    isPromise(value) {
+        return !!(value && typeof value.then === 'function');
+    }
+}
+/**
+ * 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.
+ */
+Job.PROCESSOR_MANAGED_FIELDS = new Set([
+    'lockedAt',
+    'lastRunAt',
+    'lastFinishedAt',
+    'failedAt',
+    'failCount',
+    'failReason',
+    'progress'
+]);
+//# sourceMappingURL=Job.js.map