@quave/agenda 1.0.0

package/dist/cjs/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;
+    };
+};