@cedarjs/jobs 7.0.1-next.314 → 7.0.1-next.466

package/dist/adapters/BaseAdapter/BaseAdapter.d.ts

@@ -7,6 +7,38 @@ export interface SchedulePayload {
     runAt: Date;
     queue: string;
     priority: number;
+    /**
+     * The job's unique key, if it was scheduled with one. Only passed to
+     * adapters that set `supportsUniqueKeys`. While a job with this key is
+     * still queued, the adapter must not add another one (see
+     * `ScheduleJobOptions['key']`)
+     */
+    key?: string | undefined;
+}
+/** A recurring schedule declared in code, as passed to `syncSchedules()` */
+export interface ScheduleDefinition extends SchedulePayload {
+    cron: string;
+    /**
+     * The schedule's identity: `SCHEDULE_KEY_PREFIX`, the job's name and the
+     * schedule's own key, like `cedar:schedule:ReportJob:nightly`
+     */
+    key: string;
+}
+export interface SyncSchedulesOptions {
+    /** Every schedule declared in the app's code */
+    schedules: ScheduleDefinition[];
+    /**
+     * Every schedule key starts with this prefix. Stored schedules with this
+     * prefix that are not in `schedules` must be removed
+     */
+    keyPrefix: string;
+}
+/** The keys of the schedules `syncSchedules()` touched, by what it did */
+export interface SyncSchedulesResult {
+    created: string[];
+    updated: string[];
+    removed: string[];
+    unchanged: string[];
 }
 export interface FindArgs {
     processName: string;
@@ -18,6 +50,11 @@ export interface BaseAdapterOptions {
 }
 export interface SuccessOptions<TJob extends BaseJob = BaseJob> {
     job: TJob;
+    /**
+     * When set, the job is a recurring (cron) job and has to run again at this
+     * time. The adapter must store it as the job's new `runAt` and reset the
+     * job's attempt count to 0
+     */
     runAt: Date | undefined;
     deleteJob?: boolean;
 }
@@ -30,10 +67,10 @@ export interface FailureOptions<TJob extends BaseJob = BaseJob> {
     job: TJob;
     deleteJob?: boolean;
     /**
-     * Present when the job is failed directly, without a preceding `error()`
-     * call for the same attempt (currently: when the job exceeded
-     * `maxRuntime`), so the adapter can record what went wrong in a single
-     * write
+     * The error of the attempt that failed the job (it exceeded `maxRuntime`,
+     * or it was the `maxAttempts`th attempt). There is no preceding `error()`
+     * call for that attempt, so the adapter records the error in the same
+     * write that marks the job as failed
      */
     error?: Error;
 }
@@ -41,6 +78,57 @@ export interface CancelOptions {
     /** The id of the job to cancel, as returned by `schedule()` */
     jobId: string | number;
 }
+export interface PauseOptions {
+    /** The id of the job to pause, as returned by `schedule()` */
+    jobId: string | number;
+}
+export interface PauseResult {
+    /** `true` when the job was paused already, and nothing changed */
+    alreadyPaused: boolean;
+    /** When the job was paused */
+    pausedAt: Date;
+}
+export interface ResumeOptions {
+    /** The id of the job to resume, as returned by `schedule()` */
+    jobId: string | number;
+}
+export interface ResumeResult {
+    /** `false` when the job wasn't paused, and nothing changed */
+    wasPaused: boolean;
+    /**
+     * When the job runs next. `null` for a recurring job with a run in
+     * progress: the worker sets its next run time when that run finishes
+     */
+    runAt: Date | null;
+}
+export interface ListJobsOptions {
+    /** The most jobs to return, the ones that run next first */
+    limit: number;
+    /**
+     * Only list jobs in these queues. All queues when left out or `['*']`
+     */
+    queues?: string[];
+    /**
+     * Only list paused jobs. A worker uses this when it starts, to warn about
+     * paused jobs in its queues
+     */
+    paused?: boolean;
+}
+/** A job waiting to run, running or paused, as `list()` returns it */
+export interface ListedJob {
+    id: string | number;
+    name: string;
+    queue: string;
+    /** Set for a recurring job */
+    cron: string | null;
+    /** When the job runs next (or would, if it weren't paused) */
+    runAt: Date | null;
+    /** When the job was paused, or `null` when it isn't */
+    pausedAt: Date | null;
+    /** Whether a worker is running the job right now */
+    running: boolean;
+    attempts: number;
+}
 /**
  * Base class for all job adapters. Provides a common interface for scheduling
  * jobs. At a minimum, you must implement the `schedule` method in your adapter.
@@ -49,9 +137,15 @@ export interface CancelOptions {
  * be used to configure your custom adapter. If `options.logger` is included
  * you can access it via `this.logger`
  */
-export declare abstract class BaseAdapter<TOptions extends BaseAdapterOptions = BaseAdapterOptions, TScheduleReturn = void | Promise<void>> {
+export declare abstract class BaseAdapter<TOptions extends BaseAdapterOptions = BaseAdapterOptions, TScheduleReturn = unknown> {
     options: TOptions;
     logger: NonNullable<TOptions['logger']>;
+    /**
+     * Whether `schedule()` honors `payload.key` (see `SchedulePayload['key']`).
+     * Scheduling a job with a `key` through an adapter that doesn't throws a
+     * `UniqueKeysNotSupportedError`, so a key is never silently ignored
+     */
+    readonly supportsUniqueKeys: boolean;
     constructor(options: TOptions);
     abstract schedule(payload: SchedulePayload): TScheduleReturn;
     /**
@@ -59,19 +153,26 @@ export declare abstract class BaseAdapter<TOptions extends BaseAdapterOptions =
      */
     abstract find(args: FindArgs): PossibleBaseJob | Promise<PossibleBaseJob>;
     /**
-     * Called when a job has successfully completed
+     * Called when a job has successfully completed.
+     *
+     * When `options.runAt` is set the job is a recurring (cron) job that has to
+     * run again at that time. The adapter must then store the new `runAt` and
+     * reset the job's attempt count to 0, so that `attempts` (which the worker
+     * compares against `maxAttempts` and uses for the retry backoff) counts
+     * consecutive failures of a single run rather than every run of the job
      */
     abstract success(options: SuccessOptions): void | Promise<void>;
     /**
-     * Called when an attempt to run a job produced an error.
+     * Called when an attempt to run a job produced an error and the job will
+     * be retried.
      * This should update the stored job with the new `options.runAt` so that it
      * will be retried
      */
     abstract error(options: ErrorOptions): void | Promise<void>;
     /**
-     * Called when a job will not be retried: it has either errored more than
-     * maxAttempts times, or exceeded maxRuntime (in which case
-     * `options.error` contains the timeout error to record)
+     * Called, instead of `error()`, when a job will not be retried: it has
+     * either errored maxAttempts times, or exceeded maxRuntime.
+     * `options.error` contains the error to record
      */
     abstract failure(options: FailureOptions): void | Promise<void>;
     /**
@@ -88,5 +189,49 @@ export declare abstract class BaseAdapter<TOptions extends BaseAdapterOptions =
      * cancellation and `later.cancel()` will throw a `CancelNotImplementedError`
      */
     cancel?(options: CancelOptions): boolean | Promise<boolean>;
+    /**
+     * Makes the stored recurring schedules match `options.schedules`, the ones
+     * declared in code. Called by every job worker when it starts, so several
+     * calls can run at the same time and must not create duplicates:
+     * - a declared schedule without a stored job is created, with its `runAt`
+     *   at the next match of its `cron`
+     * - a stored schedule whose job name, path, args, queue, priority or cron
+     *   differ from the declaration is updated
+     * - a stored schedule (key starting with `options.keyPrefix`) that is not
+     *   declared any more is removed
+     *
+     * This method is optional: declaring `schedules` on a job with an adapter
+     * that doesn't implement it makes the workers throw a
+     * `SchedulesNotSupportedError` when they start
+     */
+    syncSchedules?(options: SyncSchedulesOptions): SyncSchedulesResult | Promise<SyncSchedulesResult>;
+    /**
+     * Pause a job, so that no worker picks it up until it's resumed. A run in
+     * progress finishes, and a recurring job's next run stays paused: `success()`
+     * and `error()` must keep the pause when they reschedule the job.
+     *
+     * Throws a `JobIdNotFoundError` when no job has the id, and a
+     * `JobNotActiveError` when the job has completed or failed for good.
+     *
+     * This method is optional, together with `resume()`: adapters that don't
+     * implement it don't support pausing, and `jobs.pauseJob()` throws a
+     * `PauseNotImplementedError`
+     */
+    pause?(options: PauseOptions): PauseResult | Promise<PauseResult>;
+    /**
+     * Resume a paused job. A recurring job runs next at the next match of its
+     * cron from now, so runs missed while it was paused are not made up for. A
+     * one-off job keeps its run time, so it runs right away when that has
+     * passed. A job that isn't paused is left as it is.
+     *
+     * Throws like `pause()`
+     */
+    resume?(options: ResumeOptions): ResumeResult | Promise<ResumeResult>;
+    /**
+     * List the jobs that are waiting to run, running or paused (not the
+     * completed or failed ones), the ones that run next first. Used by
+     * `yarn cedar jobs list` to find a job's id. Optional
+     */
+    list?(options: ListJobsOptions): ListedJob[] | Promise<ListedJob[]>;
 }
 //# sourceMappingURL=BaseAdapter.d.ts.map

package/dist/adapters/BaseAdapter/BaseAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/BaseAdapter/BaseAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAG3E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,KAAK,EAAE,IAAI,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO;IAC5D,GAAG,EAAE,IAAI,CAAA;IACT,KAAK,EAAE,IAAI,GAAG,SAAS,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO;IAC1D,GAAG,EAAE,IAAI,CAAA;IACT,KAAK,EAAE,IAAI,CAAA;IACX,KAAK,EAAE,KAAK,CAAA;CACb;AAED,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO;IAC5D,GAAG,EAAE,IAAI,CAAA;IACT,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,8BAAsB,WAAW,CAC/B,QAAQ,SAAS,kBAAkB,GAAG,kBAAkB,EACxD,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtC,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;gBAE3B,OAAO,EAAE,QAAQ;IAU7B,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe;IAE5D;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE/D;;OAEG;IACH,QAAQ,CAAC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtC;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAC5D"}
+{"version":3,"file":"BaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/BaseAdapter/BaseAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/BaseAdapter/BaseAdapter.js

@@ -2,6 +2,12 @@ import { DEFAULT_LOGGER } from "../../consts.js";
 class BaseAdapter {
   options;
   logger;
+  /**
+   * Whether `schedule()` honors `payload.key` (see `SchedulePayload['key']`).
+   * Scheduling a job with a `key` through an adapter that doesn't throws a
+   * `UniqueKeysNotSupportedError`, so a key is never silently ignored
+   */
+  supportsUniqueKeys = false;
   constructor(options) {
     this.options = options;
     this.logger = options?.logger ?? DEFAULT_LOGGER;

package/dist/adapters/PrismaAdapter/PrismaAdapter.d.ts

@@ -1,9 +1,11 @@
 import type { BaseJob } from '../../types.js';
-import type { BaseAdapterOptions, SchedulePayload, FindArgs, SuccessOptions, ErrorOptions, FailureOptions, CancelOptions } from '../BaseAdapter/BaseAdapter.js';
+import type { BaseAdapterOptions, ListedJob, ListJobsOptions, PauseOptions, PauseResult, ResumeOptions, ResumeResult, SchedulePayload, SyncSchedulesOptions, SyncSchedulesResult, FindArgs, SuccessOptions, ErrorOptions, FailureOptions, CancelOptions } from '../BaseAdapter/BaseAdapter.js';
 import { BaseAdapter } from '../BaseAdapter/BaseAdapter.js';
 export interface PrismaJob extends BaseJob {
     id: number;
     handler: string;
+    queue: string;
+    priority: number;
     /** Null once the job has completed or permanently failed */
     runAt: Date | null;
     cron: string | null | undefined;
@@ -13,8 +15,27 @@ export interface PrismaJob extends BaseJob {
     lockedBy: string | null;
     lastError: string | null;
     failedAt: Date | null;
+    /**
+     * When the job was paused, or null when it isn't. Workers don't pick up a
+     * paused job. Undefined when the model has no `pausedAt` column
+     */
+    pausedAt?: Date | null;
     createdAt: Date;
     updatedAt: Date;
+    /**
+     * The job's unique key. Only queued jobs and active recurring jobs hold
+     * their key, it's null once a worker has picked up a non-recurring job.
+     * Undefined when the model has no `key` column
+     */
+    key?: string | null;
+}
+/** What `schedule()` returns: the stored job */
+export interface ScheduledPrismaJob extends PrismaJob {
+    /**
+     * `true` when the job was scheduled with a `key` and a job with that key
+     * was already queued. No new job was added, and this is the queued job
+     */
+    alreadyQueued: boolean;
 }
 interface PrismaAdapterDelegate {
     findFirst(args: Record<string, unknown>): Promise<any>;
@@ -25,6 +46,8 @@ interface PrismaAdapterDelegate {
     update(args: Record<string, unknown>): Promise<unknown>;
     create(args: Record<string, unknown>): Promise<unknown>;
     deleteMany(args?: Record<string, unknown>): Promise<unknown>;
+    /** Every Prisma delegate has it. Only `syncSchedules()` and `list()` use it */
+    findMany?(args: Record<string, unknown>): Promise<any[]>;
 }
 interface DelegateLike {
     findFirst: (...args: any[]) => any;
@@ -81,12 +104,15 @@ export interface PrismaAdapterOptions<TDb extends object = object> extends BaseA
  *   lockedBy  String?
  *   lastError String?
  *   failedAt  DateTime?
+ *   pausedAt  DateTime?
  *   createdAt DateTime  \@default(now())
  *   updatedAt DateTime  \@updatedAt
  * }
  * ```
  */
-export declare class PrismaAdapter<TDb extends object = object> extends BaseAdapter<PrismaAdapterOptions<TDb>, Promise<PrismaJob>> {
+export declare class PrismaAdapter<TDb extends object = object> extends BaseAdapter<PrismaAdapterOptions<TDb>, Promise<ScheduledPrismaJob>> {
+    #private;
+    readonly supportsUniqueKeys = true;
     db: TDb;
     model: DelegateKey<TDb> | string;
     accessor: PrismaAdapterDelegate;
@@ -102,7 +128,24 @@ export declare class PrismaAdapter<TDb extends object = object> extends BaseAdap
     success({ job, runAt, deleteJob }: SuccessOptions<PrismaJob>): Promise<void>;
     error({ job, runAt, error }: ErrorOptions<PrismaJob>): Promise<void>;
     failure({ job, deleteJob, error }: FailureOptions<PrismaJob>): Promise<void>;
-    schedule({ name, path, args, runAt, cron, queue, priority, }: SchedulePayload): Promise<PrismaJob>;
+    /**
+     * Schedules a job by creating a new record in the background job table.
+     * Returns the created job so that callers get access to its `id` (to cancel
+     * it later, poll its status, etc.)
+     *
+     * With a `key`, the `key` column's unique constraint makes sure only one
+     * queued job holds the key, also when several processes schedule at once.
+     * If the insert hits the constraint, the job that holds the key is
+     * returned with `alreadyQueued: true` instead
+     */
+    schedule({ name, path, args, runAt, cron, queue, priority, key, }: SchedulePayload): Promise<ScheduledPrismaJob>;
+    /**
+     * Makes the stored declared schedules match `schedules`. Each schedule is
+     * one row, identified by its unique `key`, so concurrent syncs can't create
+     * duplicates: an insert that hits the unique constraint compares against
+     * (and if needed updates) the row the other sync created instead
+     */
+    syncSchedules({ schedules, keyPrefix, }: SyncSchedulesOptions): Promise<SyncSchedulesResult>;
     /**
      * Cancels a job by marking it as permanently failed so no worker will pick
      * it up (or retry it, if it's currently being worked on).
@@ -113,6 +156,28 @@ export declare class PrismaAdapter<TDb extends object = object> extends BaseAdap
      * its lock goes stale.
      */
     cancel({ jobId }: CancelOptions): Promise<boolean>;
+    /**
+     * Pauses a job by setting its `pausedAt`, which `find()` leaves out. A run
+     * in progress finishes, and `success()` and `error()` keep `pausedAt` when
+     * they reschedule the job
+     */
+    pause({ jobId }: PauseOptions): Promise<PauseResult>;
+    /**
+     * Resumes a paused job. A recurring job runs next at the next match of its
+     * cron from now, and, unless it's running, starts that run with a clean
+     * slate (`attempts` reset to 0, like after a successful run). A running
+     * job keeps its `attempts` and `runAt`: `attempts` identifies the run's
+     * claim (see `#claimedBy()`), and the worker sets the next run time when
+     * the run finishes, so a run that finishes while this write is under way
+     * keeps the run time it set, and the result's `runAt` is `null`. A one-off
+     * job keeps its `runAt`
+     */
+    resume({ jobId }: ResumeOptions): Promise<ResumeResult>;
+    /**
+     * Lists the jobs that haven't completed or failed for good, the ones that
+     * run next first
+     */
+    list({ limit, queues, paused, }: ListJobsOptions): Promise<ListedJob[]>;
     clear(): Promise<void>;
 }
 export {};

package/dist/adapters/PrismaAdapter/PrismaAdapter.d.ts.map

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