@cedarjs/jobs 7.1.0 → 7.1.1-next.469

package/dist/bins/cedar-jobs.js

@@ -19,19 +19,100 @@ const parseArgs = (argv) => {
   }
   const parsed = yargs(commandString).usage(
     "Starts the CedarJS Jobs runner to process background jobs\n\nUsage: cedar jobs <command> [options]"
-  ).command("work", "Start a worker and process jobs").command("workoff", "Start a worker and exit after all jobs processed").command("start", "Start workers in daemon mode").command("stop", "Stop any daemonized job workers").command("restart", "Stop and start any daemonized job workers").command("clear", "Clear the job queue").demandCommand(1, "You must specify a mode to start in").example(
+  ).command("work", "Start a worker and process jobs").command("workoff", "Start a worker and exit after all jobs processed").command("start", "Start workers in daemon mode").command("stop", "Stop any daemonized job workers").command("restart", "Stop and start any daemonized job workers").command("clear", "Clear the job queue").command("pause <id>", "Pause a job, so no worker picks it up").command("resume <id>", "Resume a paused job").command(
+    "list",
+    "List the jobs that are waiting to run, running or paused, with their ids"
+  ).option("adapter", {
+    type: "string",
+    description: "pause, resume, list: the adapter that stores the jobs, when the JobManager has several"
+  }).option("limit", {
+    type: "number",
+    default: 100,
+    description: "list: the most jobs to list"
+  }).demandCommand(1, "You must specify a mode to start in").example(
     "cedar jobs work",
     "Start the job workers using the job config and work on jobs until manually stopped"
   ).example(
     "cedar jobs start",
     "Start the job workers using the job config and detach, running in daemon mode"
+  ).example(
+    "cedar jobs pause 42",
+    "Stop job 42 from running until `cedar jobs resume 42`"
   ).help().parse(commandString, (_err, _argv, output) => {
     if (output) {
       const newOutput = output.replaceAll("cedar-jobs.js", "cedar jobs");
       console.log(newOutput);
     }
   });
-  return { command: parsed._[0] };
+  return {
+    command: parsed._[0],
+    id: parseJobId(parsed.id),
+    adapter: typeof parsed.adapter === "string" ? parsed.adapter : void 0,
+    limit: typeof parsed.limit === "number" ? parsed.limit : 100
+  };
+};
+const parseJobId = (value) => {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value !== "string" || value === "") {
+    return void 0;
+  }
+  const number = Number(value);
+  return /^\d+$/.test(value) && Number.isSafeInteger(number) && String(number) === value ? number : value;
+};
+const runPauseCommand = async ({
+  command,
+  id,
+  adapter,
+  limit = 100,
+  manager
+}) => {
+  if (command === "list") {
+    const listed = await manager.listJobs({ adapter, limit });
+    if (listed.length === 0) {
+      return "No jobs are waiting to run";
+    }
+    const rows = [
+      ["ID", "JOB", "QUEUE", "CRON", "STATUS"],
+      ...listed.map((job) => [
+        String(job.id),
+        job.name,
+        job.queue,
+        job.cron ?? "-",
+        [
+          job.pausedAt ? `paused since ${job.pausedAt.toISOString()}` : "",
+          job.running ? "running" : "",
+          !job.pausedAt && !job.running ? `next run ${job.runAt?.toISOString() ?? "-"}` : ""
+        ].filter(Boolean).join(", ")
+      ])
+    ];
+    const widths = rows[0].map(
+      (_, column) => Math.max(...rows.map((row) => row[column].length))
+    );
+    const lines = rows.map(
+      (row) => row.map(
+        (cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column])
+      ).join("  ")
+    );
+    if (listed.length === limit) {
+      lines.push(`(the first ${limit}, use --limit to see more)`);
+    }
+    return lines.join("\n");
+  }
+  if (id === void 0) {
+    throw new Error(`Say which job to ${command} by its id`);
+  }
+  if (command === "pause") {
+    const result2 = await manager.pauseJob(id, { adapter });
+    return result2.alreadyPaused ? `Job ${id} was already paused (since ${result2.pausedAt.toISOString()})` : `Paused job ${id}. It doesn't run until you resume it with \`yarn cedar jobs resume ${id}\``;
+  }
+  const result = await manager.resumeJob(id, { adapter });
+  const nextRun = result.runAt?.toISOString() ?? "-";
+  if (result.wasPaused && !result.runAt) {
+    return `Resumed job ${id}. Its next run time is set when the current run finishes`;
+  }
+  return result.wasPaused ? `Resumed job ${id}. Its next run is at ${nextRun}` : `Job ${id} isn't paused. Its next run is at ${nextRun}`;
 };
 const buildNumWorkers = (config) => {
   const workers = [];
@@ -145,7 +226,7 @@ const findWorkerProcesses = async (id) => {
   });
 };
 const main = async () => {
-  const { command } = parseArgs(process.argv);
+  const { command, id, adapter, limit } = parseArgs(process.argv);
   let jobsConfig;
   try {
     jobsConfig = await loadJobsManager();
@@ -153,6 +234,23 @@ const main = async () => {
     console.error(e);
     process.exit(1);
   }
+  if (command === "pause" || command === "resume" || command === "list") {
+    try {
+      console.log(
+        await runPauseCommand({
+          command,
+          id,
+          adapter,
+          limit,
+          manager: jobsConfig
+        })
+      );
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+    return process.exit(0);
+  }
   const workerConfig = jobsConfig.workers;
   const numWorkers = buildNumWorkers(workerConfig);
   const logger = jobsConfig.logger ?? DEFAULT_LOGGER;
@@ -206,6 +304,9 @@ if (process.env.NODE_ENV !== "test") {
 export {
   buildNumWorkers,
   clearQueue,
+  parseArgs,
+  parseJobId,
+  runPauseCommand,
   startWorkers,
   stopWorkers
 };

package/dist/consts.d.ts

@@ -30,6 +30,15 @@ export declare const DEFAULT_PRIORITY = 50;
 export declare const DEFAULT_WAIT = 0;
 export declare const DEFAULT_WAIT_UNTIL: null;
 export declare const PROCESS_TITLE_PREFIX = "cedar-jobs-worker";
+/** Job keys starting with this are reserved for keys Cedar creates itself */
+export declare const RESERVED_KEY_PREFIX = "cedar:";
+/**
+ * Keys of stored declared schedules start with this, followed by the job's
+ * name and the schedule's own key: `cedar:schedule:ReportJob:nightly`
+ */
+export declare const SCHEDULE_KEY_PREFIX = "cedar:schedule:";
+/** The key of a job's schedule when the job has one and it has no `key` */
+export declare const DEFAULT_SCHEDULE_KEY = "default";
 export declare const DEFAULT_MODEL_NAME = "BackgroundJob";
 /**
  * The name of the exported variable from the jobs config file that contains

package/dist/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC,yBAAyB;AACzB,eAAO,MAAM,mBAAmB,QAAS,CAAA;AACzC;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAA0B,CAAA;AAErD,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAClD,eAAO,MAAM,0BAA0B,QAAQ,CAAA;AAC/C,eAAO,MAAM,cAAc,SAAU,CAAA;AACrC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,eAAO,MAAM,kBAAkB,MAAO,CAAA;AACtC,eAAO,MAAM,oBAAoB,sBAAsB,CAAA;AAEvD,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAC7C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC,yBAAyB;AACzB,eAAO,MAAM,mBAAmB,QAAS,CAAA;AACzC;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAA0B,CAAA;AAErD,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAClD,eAAO,MAAM,0BAA0B,QAAQ,CAAA;AAC/C,eAAO,MAAM,cAAc,SAAU,CAAA;AACrC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,eAAO,MAAM,kBAAkB,MAAO,CAAA;AACtC,eAAO,MAAM,oBAAoB,sBAAsB,CAAA;AACvD,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,WAAW,CAAA;AAC3C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,oBAAoC,CAAA;AACpE,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAE7C,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAC7C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAA"}

package/dist/consts.js

@@ -13,6 +13,9 @@ const DEFAULT_PRIORITY = 50;
 const DEFAULT_WAIT = 0;
 const DEFAULT_WAIT_UNTIL = null;
 const PROCESS_TITLE_PREFIX = "cedar-jobs-worker";
+const RESERVED_KEY_PREFIX = "cedar:";
+const SCHEDULE_KEY_PREFIX = `${RESERVED_KEY_PREFIX}schedule:`;
+const DEFAULT_SCHEDULE_KEY = "default";
 const DEFAULT_MODEL_NAME = "BackgroundJob";
 const DEFAULT_ADAPTER_NAME = "adapter";
 const DEFAULT_LOGGER_NAME = "logger";
@@ -27,11 +30,14 @@ export {
   DEFAULT_MODEL_NAME,
   DEFAULT_PRIORITY,
   DEFAULT_QUEUE,
+  DEFAULT_SCHEDULE_KEY,
   DEFAULT_SLEEP_DELAY,
   DEFAULT_WAIT,
   DEFAULT_WAIT_UNTIL,
   DEFAULT_WORK_QUEUE,
   MAX_BACKOFF_MS,
   MAX_RUNTIME_GRACE_PERIOD,
-  PROCESS_TITLE_PREFIX
+  PROCESS_TITLE_PREFIX,
+  RESERVED_KEY_PREFIX,
+  SCHEDULE_KEY_PREFIX
 };

package/dist/core/Executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Executor.d.ts","sourceRoot":"","sources":["../../src/core/Executor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAA;AAezE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAKvD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,OAAO,CAAA;IACZ,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,eAAO,MAAM,QAAQ;;;;;;CAMpB,CAAA;AAED,qBAAa,QAAQ;;IACnB,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAA;IAClC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;IACnC,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC9C,GAAG,EAAE,OAAO,CAAA;IACZ,WAAW,EAAE,WAAW,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAA;IACxD,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAA;IACtD,gBAAgB,EAAE,WAAW,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC,CAAA;IAClE,oBAAoB,EAAE,WAAW,CAAC,eAAe,CAAC,sBAAsB,CAAC,CAAC,CAAA;gBAE9D,OAAO,EAAE,eAAe;IAsBpC,IAAI,aAAa,WAEhB;IAED;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAgKjC;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM;CAGrC"}
+{"version":3,"file":"Executor.d.ts","sourceRoot":"","sources":["../../src/core/Executor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAA;AAgBzE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAKvD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,OAAO,CAAA;IACZ,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,eAAO,MAAM,QAAQ;;;;;;CAMpB,CAAA;AAED,qBAAa,QAAQ;;IACnB,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAA;IAClC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;IACnC,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC9C,GAAG,EAAE,OAAO,CAAA;IACZ,WAAW,EAAE,WAAW,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAA;IACxD,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAA;IACtD,gBAAgB,EAAE,WAAW,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC,CAAA;IAClE,oBAAoB,EAAE,WAAW,CAAC,eAAe,CAAC,sBAAsB,CAAC,CAAC,CAAA;gBAE9D,OAAO,EAAE,eAAe;IAsBpC,IAAI,aAAa,WAEhB;IAED;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAuKjC;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM;CAGrC"}

package/dist/core/Executor.js

@@ -5,7 +5,8 @@ import {
   DEFAULT_DELETE_FAILED_JOBS,
   DEFAULT_DELETE_SUCCESSFUL_JOBS,
   DEFAULT_LOGGER,
-  MAX_BACKOFF_MS
+  MAX_BACKOFF_MS,
+  SCHEDULE_KEY_PREFIX
 } from "../consts.js";
 import {
   AdapterRequiredError,
@@ -134,12 +135,18 @@ class Executor {
    * called only after `failure()` has recorded that (a throwing `failure()`
    * is logged by `#adapterWrite()` instead). A permanently failed recurring
    * (cron) job is not rescheduled, so its schedule stops until the job is
-   * scheduled again. That is logged at error level, together with how to
-   * restart the schedule
+   * scheduled again (a declared schedule: until the workers restart and sync
+   * it). That is logged at error level, together with how to restart the
+   * schedule
    */
   #logPermanentFailure(reason) {
     const message = `[CedarJS Jobs] Failed job ${this.jobIdentifier}: ${reason}`;
-    if (this.job.cron) {
+    if (this.job.cron && this.job.key?.startsWith(SCHEDULE_KEY_PREFIX)) {
+      this.logger.error(
+        this.job,
+        `${message}. Its declared schedule (cron: '${this.job.cron}') has stopped until the job workers restart, which recreates it`
+      );
+    } else if (this.job.cron) {
       this.logger.error(
         this.job,
         `${message}. Its recurring schedule (cron: '${this.job.cron}') has stopped and the job will not run again. To restart it, schedule the job again with \`later(job, args, { cron: '${this.job.cron}' })\``

package/dist/core/JobManager.d.ts

@@ -1,6 +1,15 @@
+import type { ListedJob, PauseResult, ResumeResult, SyncSchedulesResult } from '../adapters/BaseAdapter/BaseAdapter.js';
 import type { Adapters, BasicLogger, CreateSchedulerArgs, CreateSchedulerConfig, Job, JobDefinition, JobManagerConfig, QueueNames, WorkerConfig } from '../types.js';
 import type { WorkerOptions } from './Worker.js';
 import { Worker } from './Worker.js';
+/** Which adapter `pauseJob()`, `resumeJob()` and `listJobs()` use */
+export interface JobAdapterOptions<TAdapters extends Adapters> {
+    /**
+     * The name of the adapter that stores the job. Can be left out when the
+     * `JobManager` has a single adapter
+     */
+    adapter?: keyof TAdapters;
+}
 export interface CreateWorkerArgs {
     index: number;
     workoff: WorkerOptions['workoff'];
@@ -8,15 +17,82 @@ export interface CreateWorkerArgs {
     processName: string;
 }
 export declare class JobManager<TAdapters extends Adapters, TQueues extends QueueNames, TLogger extends BasicLogger> {
+    #private;
     adapters: TAdapters;
     queues: TQueues;
     logger: TLogger;
     workers: WorkerConfig<TAdapters, TQueues>[];
+    scheduleAdapter: keyof TAdapters | undefined;
     constructor(config: JobManagerConfig<TAdapters, TQueues extends string[] ? never : TQueues, TLogger>);
     createScheduler<TAdapterName extends keyof TAdapters>(schedulerConfig: CreateSchedulerConfig<TAdapters, TAdapterName>): (<TJob extends Job<TQueues, any[]>>(job: TJob, ...argsAndOptions: CreateSchedulerArgs<TJob>) => Promise<Awaited<ReturnType<TAdapters[TAdapterName]["schedule"]>>>) & {
         cancel: (jobId: string | number) => Promise<boolean>;
     };
+    /**
+     * Pauses a job, without a deploy: no worker picks it up until it's resumed
+     * with `resumeJob()`. Works for any job that's waiting to run, recurring
+     * (`cron`) or not. A run that's in progress finishes, and a recurring job's
+     * next run stays paused.
+     *
+     * The pause is stored on the job's row. Code that deletes and recreates
+     * its recurring jobs (like a script that schedules them on every deploy)
+     * creates new rows, which aren't paused.
+     *
+     * Also available as `yarn cedar jobs pause <id>`.
+     *
+     * @param jobId The job's id, as returned by `later()` (or listed by
+     * `listJobs()` and `yarn cedar jobs list`)
+     *
+     * @returns Whether the job was paused already, and since when it's paused
+     *
+     * @example
+     * ```ts
+     * await jobs.pauseJob(42)
+     * ```
+     */
+    pauseJob(jobId: string | number, options?: JobAdapterOptions<TAdapters>): Promise<PauseResult>;
+    /**
+     * Resumes a job paused with `pauseJob()`.
+     *
+     * - A recurring (`cron`) job runs next the next time its cron matches from
+     *   now. Runs missed while it was paused are not made up for.
+     * - A one-off job keeps its run time, so it runs as soon as a worker is
+     *   free when that time has passed.
+     *
+     * Resuming a job that isn't paused changes nothing. Also available as
+     * `yarn cedar jobs resume <id>`.
+     *
+     * @returns Whether the job was paused, and when it runs next
+     */
+    resumeJob(jobId: string | number, options?: JobAdapterOptions<TAdapters>): Promise<ResumeResult>;
+    /**
+     * Lists the jobs that are waiting to run, running or paused, the ones that
+     * run next first, to find a job's id. Completed and failed jobs are left
+     * out. Also available as `yarn cedar jobs list`.
+     *
+     * @param options.limit The most jobs to list. Default: 100
+     */
+    listJobs(options?: JobAdapterOptions<TAdapters> & {
+        limit?: number;
+    }): Promise<ListedJob[]>;
     createJob<TArgs extends unknown[]>(jobDefinition: JobDefinition<TQueues, TArgs>): Job<TQueues, TArgs>;
+    /**
+     * Makes the recurring schedules stored by the schedule adapter match the
+     * `schedules` the jobs declare in `createJob()`: adds missing ones, updates
+     * changed ones and removes the ones that are no longer declared. Safe to
+     * run from several processes at once.
+     *
+     * Every job worker calls this when it starts, so there's usually no need
+     * to call it yourself.
+     *
+     * @param jobs The jobs to read declared schedules from. Defaults to every
+     * job in the project (see `loadAllJobs()`), which is what the sync has to
+     * see to know which stored schedules are no longer declared.
+     *
+     * @returns What the sync did, or `undefined` if there was nothing to sync:
+     * no job declares schedules, and either the adapter can't store them or
+     * there are several adapters and no `scheduleAdapter` names one
+     */
+    syncSchedules(jobs?: Job<TQueues, any[]>[]): Promise<SyncSchedulesResult | undefined>;
     createWorker({ index, workoff, clear, processName }: CreateWorkerArgs): Worker;
 }
 //# sourceMappingURL=JobManager.d.ts.map

package/dist/core/JobManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JobManager.d.ts","sourceRoot":"","sources":["../../src/core/JobManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,GAAG,EACH,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IACjC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,UAAU,CACrB,SAAS,SAAS,QAAQ,EAC1B,OAAO,SAAS,UAAU,EAC1B,OAAO,SAAS,WAAW;IAE3B,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAA;gBAGzC,MAAM,EAAE,gBAAgB,CACtB,SAAS,EAGT,OAAO,SAAS,MAAM,EAAE,GAAG,KAAK,GAAG,OAAO,EAC1C,OAAO,CACR;IAQH,eAAe,CAAC,YAAY,SAAS,MAAM,SAAS,EAClD,eAAe,EAAE,qBAAqB,CAAC,SAAS,EAAE,YAAY,CAAC,KAO7C,IAAI,SAAS,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAC3C,IAAI,qBACU,mBAAmB,CAAC,IAAI,CAAC;wBAc5B,MAAM,GAAG,MAAM;;IAInC,SAAS,CAAC,KAAK,SAAS,OAAO,EAAE,EAC/B,aAAa,EAAE,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,GAC3C,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;IAOtB,YAAY,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,gBAAgB;CAqBtE"}
+{"version":3,"file":"JobManager.d.ts","sourceRoot":"","sources":["../../src/core/JobManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,WAAW,EACX,YAAY,EAEZ,mBAAmB,EACpB,MAAM,wCAAwC,CAAA;AAU/C,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,GAAG,EACH,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,qEAAqE;AACrE,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,QAAQ;IAC3D;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,SAAS,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IACjC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,UAAU,CACrB,SAAS,SAAS,QAAQ,EAC1B,OAAO,SAAS,UAAU,EAC1B,OAAO,SAAS,WAAW;;IAE3B,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAA;IAC3C,eAAe,EAAE,MAAM,SAAS,GAAG,SAAS,CAAA;gBAG1C,MAAM,EAAE,gBAAgB,CACtB,SAAS,EAGT,OAAO,SAAS,MAAM,EAAE,GAAG,KAAK,GAAG,OAAO,EAC1C,OAAO,CACR;IASH,eAAe,CAAC,YAAY,SAAS,MAAM,SAAS,EAClD,eAAe,EAAE,qBAAqB,CAAC,SAAS,EAAE,YAAY,CAAC,KAO7C,IAAI,SAAS,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAC3C,IAAI,qBACU,mBAAmB,CAAC,IAAI,CAAC;wBAc5B,MAAM,GAAG,MAAM;;IAInC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,iBAAiB,CAAC,SAAS,CAAM,GACzC,OAAO,CAAC,WAAW,CAAC;IAmBvB;;;;;;;;;;;;OAYG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,iBAAiB,CAAC,SAAS,CAAM,GACzC,OAAO,CAAC,YAAY,CAAC;IAsBxB;;;;;;OAMG;IACG,QAAQ,CACZ,OAAO,GAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9D,OAAO,CAAC,SAAS,EAAE,CAAC;IA2BvB,SAAS,CAAC,KAAK,SAAS,OAAO,EAAE,EAC/B,aAAa,EAAE,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,GAC3C,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;IAOtB;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,IAAI,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,GAC3B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAgJ3C,YAAY,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,gBAAgB;CAqBtE"}

package/dist/core/JobManager.js

@@ -1,4 +1,13 @@
-import { AdapterNotFoundError } from "../errors.js";
+import { DEFAULT_SCHEDULE_KEY, SCHEDULE_KEY_PREFIX } from "../consts.js";
+import {
+  AdapterNameRequiredError,
+  AdapterNotFoundError,
+  PauseNotImplementedError,
+  ScheduleConfigError,
+  SchedulesNotSupportedError
+} from "../errors.js";
+import { loadAllJobs } from "../loaders.js";
+import { nextCronRunAt } from "../util.js";
 import { Scheduler } from "./Scheduler.js";
 import { Worker } from "./Worker.js";
 class JobManager {
@@ -6,11 +15,13 @@ class JobManager {
   queues;
   logger;
   workers;
+  scheduleAdapter;
   constructor(config) {
     this.adapters = config.adapters;
     this.queues = config.queues;
     this.logger = config.logger;
     this.workers = config.workers;
+    this.scheduleAdapter = config.scheduleAdapter;
   }
   createScheduler(schedulerConfig) {
     const scheduler = new Scheduler({
@@ -28,9 +39,207 @@ class JobManager {
       cancel: (jobId) => scheduler.cancel(jobId)
     });
   }
+  /**
+   * Pauses a job, without a deploy: no worker picks it up until it's resumed
+   * with `resumeJob()`. Works for any job that's waiting to run, recurring
+   * (`cron`) or not. A run that's in progress finishes, and a recurring job's
+   * next run stays paused.
+   *
+   * The pause is stored on the job's row. Code that deletes and recreates
+   * its recurring jobs (like a script that schedules them on every deploy)
+   * creates new rows, which aren't paused.
+   *
+   * Also available as `yarn cedar jobs pause <id>`.
+   *
+   * @param jobId The job's id, as returned by `later()` (or listed by
+   * `listJobs()` and `yarn cedar jobs list`)
+   *
+   * @returns Whether the job was paused already, and since when it's paused
+   *
+   * @example
+   * ```ts
+   * await jobs.pauseJob(42)
+   * ```
+   */
+  async pauseJob(jobId, options = {}) {
+    const adapter = this.#adapter(options.adapter);
+    if (!adapter.pause) {
+      throw new PauseNotImplementedError("pause");
+    }
+    const result = await adapter.pause({ jobId });
+    this.logger.info(
+      result.alreadyPaused ? `[CedarJS Jobs] Job ${jobId} was already paused (since ${result.pausedAt.toISOString()})` : `[CedarJS Jobs] Paused job ${jobId}`
+    );
+    return result;
+  }
+  /**
+   * Resumes a job paused with `pauseJob()`.
+   *
+   * - A recurring (`cron`) job runs next the next time its cron matches from
+   *   now. Runs missed while it was paused are not made up for.
+   * - A one-off job keeps its run time, so it runs as soon as a worker is
+   *   free when that time has passed.
+   *
+   * Resuming a job that isn't paused changes nothing. Also available as
+   * `yarn cedar jobs resume <id>`.
+   *
+   * @returns Whether the job was paused, and when it runs next
+   */
+  async resumeJob(jobId, options = {}) {
+    const adapter = this.#adapter(options.adapter);
+    if (!adapter.resume) {
+      throw new PauseNotImplementedError("resume");
+    }
+    const result = await adapter.resume({ jobId });
+    const nextRun = result.runAt ? `next run at ${result.runAt.toISOString()}` : "next run time set when the current run finishes";
+    this.logger.info(
+      result.wasPaused ? `[CedarJS Jobs] Resumed job ${jobId}, ${nextRun}` : `[CedarJS Jobs] Job ${jobId} isn't paused`
+    );
+    return result;
+  }
+  /**
+   * Lists the jobs that are waiting to run, running or paused, the ones that
+   * run next first, to find a job's id. Completed and failed jobs are left
+   * out. Also available as `yarn cedar jobs list`.
+   *
+   * @param options.limit The most jobs to list. Default: 100
+   */
+  async listJobs(options = {}) {
+    const adapter = this.#adapter(options.adapter);
+    if (!adapter.list) {
+      throw new PauseNotImplementedError("list");
+    }
+    return adapter.list({ limit: options.limit ?? 100 });
+  }
+  #adapter(name) {
+    const names = Object.keys(this.adapters);
+    if (name === void 0 && names.length !== 1) {
+      throw new AdapterNameRequiredError(names);
+    }
+    const adapterName = name ?? names[0];
+    const adapter = this.adapters[adapterName];
+    if (!adapter) {
+      throw new AdapterNotFoundError(String(adapterName));
+    }
+    return adapter;
+  }
   createJob(jobDefinition) {
     return jobDefinition;
   }
+  /**
+   * Makes the recurring schedules stored by the schedule adapter match the
+   * `schedules` the jobs declare in `createJob()`: adds missing ones, updates
+   * changed ones and removes the ones that are no longer declared. Safe to
+   * run from several processes at once.
+   *
+   * Every job worker calls this when it starts, so there's usually no need
+   * to call it yourself.
+   *
+   * @param jobs The jobs to read declared schedules from. Defaults to every
+   * job in the project (see `loadAllJobs()`), which is what the sync has to
+   * see to know which stored schedules are no longer declared.
+   *
+   * @returns What the sync did, or `undefined` if there was nothing to sync:
+   * no job declares schedules, and either the adapter can't store them or
+   * there are several adapters and no `scheduleAdapter` names one
+   */
+  async syncSchedules(jobs) {
+    const allJobs = jobs ?? await loadAllJobs();
+    const declaresSchedules = allJobs.some(
+      (job) => (job.schedules?.length ?? 0) > 0
+    );
+    if (!declaresSchedules && this.scheduleAdapter === void 0 && Object.keys(this.adapters).length !== 1) {
+      return void 0;
+    }
+    const adapterName = this.#scheduleAdapterName();
+    const adapter = this.adapters[adapterName];
+    if (!adapter) {
+      throw new AdapterNotFoundError(String(adapterName));
+    }
+    const schedules = this.#scheduleDefinitions(allJobs, adapter);
+    if (!adapter.syncSchedules) {
+      if (schedules.length > 0) {
+        throw new SchedulesNotSupportedError(String(adapterName));
+      }
+      return void 0;
+    }
+    const result = await adapter.syncSchedules({
+      schedules,
+      keyPrefix: SCHEDULE_KEY_PREFIX
+    });
+    const changes = [
+      ...result.created.map((key) => `created ${key}`),
+      ...result.updated.map((key) => `updated ${key}`),
+      ...result.removed.map((key) => `removed ${key}`)
+    ];
+    if (changes.length > 0) {
+      this.logger.info(
+        `[CedarJS Jobs] Synced declared schedules: ${changes.join(", ")}`
+      );
+    } else {
+      this.logger.debug(
+        `[CedarJS Jobs] Declared schedules are up to date (${result.unchanged.length})`
+      );
+    }
+    return result;
+  }
+  #scheduleAdapterName() {
+    if (this.scheduleAdapter !== void 0) {
+      return this.scheduleAdapter;
+    }
+    const names = Object.keys(this.adapters);
+    if (names.length !== 1) {
+      throw new ScheduleConfigError(
+        `Set \`scheduleAdapter\` in your JobManager config to the adapter that stores the schedules jobs declare. It can only be left out when there is exactly one adapter (found: ${names.join(", ") || "none"})`
+      );
+    }
+    return names[0];
+  }
+  /**
+   * Turns the jobs' declared schedules into what the adapter stores, and
+   * checks them: every schedule needs a key when its job has more than one,
+   * identities must be unique, and every cron expression must parse
+   */
+  #scheduleDefinitions(jobs, adapter) {
+    const scheduler = new Scheduler({ adapter, logger: this.logger });
+    const definitions = [];
+    const owners = /* @__PURE__ */ new Map();
+    for (const job of jobs) {
+      const jobSchedules = job.schedules ?? [];
+      for (const schedule of jobSchedules) {
+        const scheduleKey = schedule.key ?? DEFAULT_SCHEDULE_KEY;
+        if (schedule.key === void 0 && jobSchedules.length > 1) {
+          throw new ScheduleConfigError(
+            `${job.name} declares ${jobSchedules.length} schedules, so each of them needs a \`key\` to tell them apart`
+          );
+        }
+        const key = `${SCHEDULE_KEY_PREFIX}${job.name}:${scheduleKey}`;
+        const owner = `${job.path} (${job.name})`;
+        const otherOwner = owners.get(key);
+        if (otherOwner) {
+          throw new ScheduleConfigError(
+            otherOwner === owner ? `${job.name} declares more than one schedule with the key \`${scheduleKey}\`` : `Both ${otherOwner} and ${owner} declare a schedule with the key \`${scheduleKey}\`. Schedules are identified by the job's name and the schedule's key, so jobs with schedules need unique names`
+          );
+        }
+        owners.set(key, owner);
+        try {
+          nextCronRunAt(schedule.cron);
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          throw new ScheduleConfigError(
+            `The \`${scheduleKey}\` schedule of ${job.name} has an invalid cron expression \`${schedule.cron}\`: ${message}`
+          );
+        }
+        const payload = scheduler.buildPayload({
+          job,
+          args: schedule.args ?? [],
+          options: { cron: schedule.cron }
+        });
+        definitions.push({ ...payload, cron: schedule.cron, key });
+      }
+    }
+    return definitions;
+  }
   createWorker({ index, workoff, clear, processName }) {
     const config = this.workers[index];
     const adapter = this.adapters[config.adapter];

package/dist/core/Scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/core/Scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EAChB,MAAM,wCAAwC,CAAA;AAa/C,OAAO,KAAK,EACV,WAAW,EACX,GAAG,EACH,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAA;AAGpB,UAAU,eAAe,CAAC,QAAQ,SAAS,WAAW;IACpD,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,SAAS,CAAC,QAAQ,SAAS,WAAW;IACjD,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;gBAE5C,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,eAAe,CAAC,QAAQ,CAAC;IAS1D,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE;IAU1E,YAAY,CAAC,IAAI,SAAS,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,EACpD,GAAG,EACH,IAAI,EACJ,OAAO,GACR,EAAE;QACD,GAAG,EAAE,IAAI,CAAA;QACT,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,EAAE,CAAA;QAC3C,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAC7B,GAAG,eAAe;IAgCb,QAAQ,CAAC,IAAI,SAAS,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,EACtD,GAAG,EACH,IAAI,EACJ,OAAO,GACR,EAAE;QACD,GAAG,EAAE,IAAI,CAAA;QACT,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,EAAE,CAAA;QAC3C,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAC7B,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IA+BtD;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CASpC"}
+{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/core/Scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EAChB,MAAM,wCAAwC,CAAA;AAgB/C,OAAO,KAAK,EACV,WAAW,EACX,GAAG,EACH,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAA;AAGpB,UAAU,eAAe,CAAC,QAAQ,SAAS,WAAW;IACpD,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,SAAS,CAAC,QAAQ,SAAS,WAAW;IACjD,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;gBAE5C,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,eAAe,CAAC,QAAQ,CAAC;IAS1D,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE;IAU1E,YAAY,CAAC,IAAI,SAAS,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,EACpD,GAAG,EACH,IAAI,EACJ,OAAO,GACR,EAAE;QACD,GAAG,EAAE,IAAI,CAAA;QACT,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,EAAE,CAAA;QAC3C,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAC7B,GAAG,eAAe;IAyCb,QAAQ,CAAC,IAAI,SAAS,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,EACtD,GAAG,EACH,IAAI,EACJ,OAAO,GACR,EAAE;QACD,GAAG,EAAE,IAAI,CAAA;QACT,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,EAAE,CAAA;QAC3C,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAC7B,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAmCtD;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CASpC"}

package/dist/core/Scheduler.js

@@ -2,13 +2,16 @@ import {
   DEFAULT_LOGGER,
   DEFAULT_PRIORITY,
   DEFAULT_WAIT,
-  DEFAULT_WAIT_UNTIL
+  DEFAULT_WAIT_UNTIL,
+  RESERVED_KEY_PREFIX
 } from "../consts.js";
 import {
   AdapterNotConfiguredError,
   CancelNotImplementedError,
   QueueNotDefinedError,
-  SchedulingError
+  ReservedKeyError,
+  SchedulingError,
+  UniqueKeysNotSupportedError
 } from "../errors.js";
 import { nextCronRunAt } from "../util.js";
 class Scheduler {
@@ -40,6 +43,7 @@ class Scheduler {
     const wait = options?.wait ?? DEFAULT_WAIT;
     const waitUntil = options?.waitUntil ?? DEFAULT_WAIT_UNTIL;
     const cron = options?.cron;
+    const key = options?.key;
     if (!queue) {
       throw new QueueNotDefinedError();
     }
@@ -48,6 +52,9 @@ class Scheduler {
         "Cannot schedule a cron job with wait or waitUntil options"
       );
     }
+    if (key?.toLowerCase().startsWith(RESERVED_KEY_PREFIX)) {
+      throw new ReservedKeyError(key, RESERVED_KEY_PREFIX);
+    }
     return {
       name: job.name,
       path: job.path,
@@ -57,7 +64,10 @@ class Scheduler {
       // matches, just like all following runs
       runAt: cron ? nextCronRunAt(cron) : this.computeRunAt({ wait, waitUntil }),
       queue,
-      priority
+      priority,
+      // Only set when given, so adapters without unique key support never
+      // see the property
+      ...key !== void 0 ? { key } : {}
     };
   }
   async schedule({
@@ -70,6 +80,9 @@ class Scheduler {
       args,
       options
     });
+    if (payload.key !== void 0 && !this.adapter.supportsUniqueKeys) {
+      throw new UniqueKeysNotSupportedError();
+    }
     this.logger.info(payload, `[CedarJS Jobs] Scheduling ${job.name}`);
     try {
       const scheduled = this.adapter.schedule(payload);

package/dist/core/Worker.d.ts

@@ -43,6 +43,14 @@ export declare class Worker {
     lastCheckTime: Date;
     constructor(options: WorkerOptions);
     run(): Promise<void>;
+    /**
+     * Logs a warning listing the paused jobs in this worker's queues, so a
+     * pause that was forgotten shows up whenever a long-running worker starts.
+     * Does nothing when the adapter can't list jobs or there are no paused
+     * ones, and never throws: a failed query is logged and the worker starts
+     * anyway
+     */
+    logPausedJobs(): Promise<void>;
     get queueNames(): string;
 }
 export {};