agenda 4.3.0 → 5.0.0

package/lib/agenda/schedule.ts

@@ -0,0 +1,79 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+import { Job, JobAttributesData } from "../job";
+
+const debug = createDebugger("agenda:schedule");
+
+/**
+ * Schedule a job or jobs at a specific time
+ * @name Agenda#schedule
+ * @function
+ * @param when when the job gets run
+ * @param names array of job names to run
+ * @param data data to send to job
+ * @returns job or jobs created
+ */
+export function schedule<T extends JobAttributesData>(this: Agenda, when: string | Date, names: string, data: T): Promise<Job>;
+export function schedule<T extends JobAttributesData>(this: Agenda, when: string | Date, names: string[], data: T): Promise<Job[]>;
+export function schedule<T extends JobAttributesData> (
+  this: Agenda,
+  when: string | Date,
+  names: string | string[],
+  data: T,
+): Promise<Job | Job[]> {
+  /**
+   * Internal method that creates a job with given date
+   * @param when when the job gets run
+   * @param name of job to run
+   * @param data data to send to job
+   * @returns instance of new job
+   */
+  const createJob = async (
+    when: string | Date,
+    name: string,
+    data: any
+  ): Promise<Job> => {
+    const job = this.create(name, data);
+
+    await job.schedule(when).save();
+
+    return job;
+  };
+
+  /**
+   * Internal helper method that calls createJob on a names array
+   * @param when when the job gets run
+   * @param names names of jobs to run
+   * @param data data to send to job
+   * @returns jobs that were created
+   */
+  const createJobs = async (
+    when: string | Date,
+    names: string[],
+    data: any
+  ): Promise<Job[]> => {
+    try {
+      const createJobList: Array<Promise<Job>> = [];
+      names.map((name) => createJobList.push(createJob(when, name, data)));
+      debug("Agenda.schedule()::createJobs() -> all jobs created successfully");
+      return Promise.all(createJobList);
+    } catch (error) {
+      debug(
+        "Agenda.schedule()::createJobs() -> error creating one or more of the jobs"
+      );
+      throw error;
+    }
+  };
+
+  if (typeof names === "string") {
+    debug("Agenda.schedule(%s, %O, [%O], cb)", when, names);
+    return createJob(when, names, data);
+  }
+
+  if (Array.isArray(names)) {
+    debug("Agenda.schedule(%s, %O, [%O])", when, names);
+    return createJobs(when, names, data);
+  }
+
+  throw new TypeError("Name must be string or array of strings")
+};

package/lib/agenda/sort.ts

@@ -0,0 +1,17 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:sort");
+
+/**
+ * Set the sort query for finding next job
+ * Default is { nextRunAt: 1, priority: -1 }
+ * @name Agenda#sort
+ * @function
+ * @param query sort query object for MongoDB
+ */
+export const sort = function (this: Agenda, query: any): Agenda {
+  debug("Agenda.sort([Object])");
+  this._sort = query;
+  return this;
+};

package/lib/agenda/start.ts

@@ -0,0 +1,30 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+import { processJobs } from "../utils";
+
+const debug = createDebugger("agenda:start");
+
+/**
+ * Starts processing jobs using processJobs() methods, storing an interval ID
+ * This method will only resolve if a db has been set up beforehand.
+ * @name Agenda#start
+ * @function
+ * @returns resolves if db set beforehand, returns undefined otherwise
+ */
+export const start = async function (this: Agenda): Promise<void | unknown> {
+  if (this._processInterval) {
+    debug("Agenda.start was already called, ignoring");
+    return this._ready;
+  }
+
+  await this._ready;
+  debug(
+    "Agenda.start called, creating interval to call processJobs every [%dms]",
+    this._processEvery
+  );
+  this._processInterval = setInterval(
+    processJobs.bind(this),
+    this._processEvery
+  );
+  process.nextTick(processJobs.bind(this));
+};

package/lib/agenda/stop.ts

@@ -0,0 +1,49 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:stop");
+
+/**
+ * Clear the interval that processes the jobs
+ * @name Agenda#stop
+ * @function
+ * @returns resolves when job unlocking fails or passes
+ */
+export const stop = async function (this: Agenda): Promise<void> {
+  /**
+   * Internal method to unlock jobs so that they can be re-run
+   * NOTE: May need to update what properties get set here, since job unlocking seems to fail
+   * @access private
+   * @returns resolves when job unlocking fails or passes
+   */
+  const _unlockJobs = async (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      debug("Agenda._unlockJobs()");
+      const jobIds = this._lockedJobs.map((job) => job.attrs._id);
+
+      if (jobIds.length === 0) {
+        debug("no jobs to unlock");
+        resolve();
+      }
+
+      debug("about to unlock jobs with ids: %O", jobIds);
+      this._collection.updateMany(
+        { _id: { $in: jobIds } },
+        { $set: { lockedAt: null } },
+        (error) => {
+          if (error) {
+            reject(error);
+          }
+
+          this._lockedJobs = [];
+          resolve();
+        }
+      );
+    });
+  };
+
+  debug("Agenda.stop called, clearing interval for processJobs()");
+  clearInterval(this._processInterval);
+  this._processInterval = undefined;
+  return _unlockJobs();
+};

package/lib/cjs.ts

@@ -0,0 +1,5 @@
+// old common js export (see index.ts for module exports)
+
+import { Agenda } from "./agenda";
+module.exports = Agenda;
+module.exports.Agenda = Agenda;

package/lib/index.ts

@@ -0,0 +1,11 @@
+// module export, beware: cjs.ts is exported as main entry point!
+export * from "./agenda";
+export * from "./job";
+
+export { DefineOptions, JobPriority, Processor } from "./agenda/define";
+export { JobOptions } from "./job/repeat-every";
+
+import { Agenda } from "./agenda";
+export { Agenda };
+
+export default Agenda;

package/lib/job/compute-next-run-at.ts

@@ -0,0 +1,191 @@
+import { Job } from ".";
+import * as parser from "cron-parser";
+import humanInterval from "human-interval";
+import createDebugger from "debug";
+import moment from "moment-timezone";
+// @ts-expect-error
+import date from "date.js";
+
+const debug = createDebugger("agenda:job");
+
+/**
+ * Internal method used to compute next time a job should run and sets the proper values
+ * @name Job#computeNextRunAt
+ * @function
+ */
+export const computeNextRunAt = function (this: Job): Job {
+  const interval = this.attrs.repeatInterval;
+  const timezone = this.attrs.repeatTimezone;
+  const { repeatAt } = this.attrs;
+  const previousNextRunAt = this.attrs.nextRunAt || new Date();
+  this.attrs.nextRunAt = undefined;
+
+  const dateForTimezone = (date: Date): moment.Moment => {
+    const mdate: moment.Moment = moment(date);
+    if (timezone) {
+      mdate.tz(timezone);
+    }
+
+    return mdate;
+  };
+
+  /**
+   * Internal method that computes the interval
+   */
+  const computeFromInterval = () => {
+    debug(
+      "[%s:%s] computing next run via interval [%s]",
+      this.attrs.name,
+      this.attrs._id,
+      interval
+    );
+    const dateNow = new Date();
+    let lastRun: Date = this.attrs.lastRunAt || dateNow;
+    let { startDate, endDate, skipDays } = this.attrs;
+    lastRun = dateForTimezone(lastRun).toDate();
+    const cronOptions: any = { currentDate: lastRun };
+    if (timezone) {
+      cronOptions.tz = timezone;
+    }
+
+    try {
+      let cronTime = parser.parseExpression(interval!, cronOptions);
+      let nextDate: Date | null = cronTime.next().toDate();
+      if (
+        nextDate.getTime() === lastRun.getTime() ||
+        nextDate.getTime() <= previousNextRunAt.getTime()
+      ) {
+        // Handle cronTime giving back the same date for the next run time
+        cronOptions.currentDate = new Date(lastRun.getTime() + 1000);
+        cronTime = parser.parseExpression(interval!, cronOptions);
+        nextDate = cronTime.next().toDate();
+      }
+
+      // If start date is present, check if the nextDate should be larger or equal to startDate. If not set startDate as nextDate
+      if (startDate) {
+        startDate = moment
+          .tz(moment(startDate).format("YYYY-MM-DD HH:mm"), timezone!)
+          .toDate();
+        if (startDate > nextDate) {
+          cronOptions.currentDate = startDate;
+          cronTime = parser.parseExpression(interval!, cronOptions);
+          nextDate = cronTime.next().toDate();
+        }
+      }
+
+      // If job has run in the past and skipDays is not null, add skipDays to nextDate
+      if (dateNow > lastRun && skipDays !== null) {
+        try {
+          nextDate = new Date(
+            nextDate.getTime() + (humanInterval(skipDays) ?? 0)
+          );
+        } catch {}
+      }
+
+      // If endDate is less than the nextDate, set nextDate to null to stop the job from running further
+      if (endDate) {
+        const endDateDate: Date = moment
+          .tz(moment(endDate).format("YYYY-MM-DD HH:mm"), timezone!)
+          .toDate();
+        if (nextDate > endDateDate) {
+          nextDate = null;
+        }
+      }
+
+      this.attrs.nextRunAt = nextDate;
+      debug(
+        "[%s:%s] nextRunAt set to [%s]",
+        this.attrs.name,
+        this.attrs._id,
+        this.attrs.nextRunAt?.toISOString()
+      );
+      // Either `xo` linter or Node.js 8 stumble on this line if it isn't just ignored
+    } catch {
+      debug(
+        "[%s:%s] failed nextRunAt based on interval [%s]",
+        this.attrs.name,
+        this.attrs._id,
+        interval
+      );
+      // Nope, humanInterval then!
+      try {
+        if (!this.attrs.lastRunAt && humanInterval(interval)) {
+          this.attrs.nextRunAt = lastRun;
+          debug(
+            "[%s:%s] nextRunAt set to [%s]",
+            this.attrs.name,
+            this.attrs._id,
+            this.attrs.nextRunAt.toISOString()
+          );
+        } else {
+          this.attrs.nextRunAt = new Date(
+            lastRun.getTime() + (humanInterval(interval) ?? 0)
+          );
+          debug(
+            "[%s:%s] nextRunAt set to [%s]",
+            this.attrs.name,
+            this.attrs._id,
+            this.attrs.nextRunAt.toISOString()
+          );
+        }
+        // Either `xo` linter or Node.js 8 stumble on this line if it isn't just ignored
+      } catch {}
+    } finally {
+      if (!this.attrs.nextRunAt?.getTime()) {
+        this.attrs.nextRunAt = undefined;
+        debug(
+          "[%s:%s] failed to calculate nextRunAt due to invalid repeat interval",
+          this.attrs.name,
+          this.attrs._id
+        );
+        this.fail(
+          "failed to calculate nextRunAt due to invalid repeat interval"
+        );
+      }
+    }
+  };
+
+  /**
+   * Internal method to compute next run time from the repeat string
+   */
+  const computeFromRepeatAt = () => {
+    const lastRun = this.attrs.lastRunAt || new Date();
+    const nextDate: Date = date(repeatAt);
+
+    // If you do not specify offset date for below test it will fail for ms
+    const offset = Date.now();
+    if (offset === date(repeatAt, offset).getTime()) {
+      this.attrs.nextRunAt = undefined;
+      debug(
+        "[%s:%s] failed to calculate repeatAt due to invalid format",
+        this.attrs.name,
+        this.attrs._id
+      );
+      this.fail("failed to calculate repeatAt time due to invalid format");
+    } else if (nextDate.getTime() === lastRun.getTime()) {
+      this.attrs.nextRunAt = date("tomorrow at ", repeatAt);
+      debug(
+        "[%s:%s] nextRunAt set to [%s]",
+        this.attrs.name,
+        this.attrs._id,
+        this.attrs.nextRunAt?.toISOString()
+      );
+    } else {
+      this.attrs.nextRunAt = date(repeatAt);
+      debug(
+        "[%s:%s] nextRunAt set to [%s]",
+        this.attrs.name,
+        this.attrs._id,
+        this.attrs.nextRunAt?.toISOString()
+      );
+    }
+  };
+
+  if (interval) {
+    computeFromInterval();
+  } else if (repeatAt) {
+    computeFromRepeatAt();
+  }
+
+  return this;
+};

package/lib/job/disable.ts

@@ -0,0 +1,11 @@
+import { Job } from ".";
+
+/**
+ * Prevents the job type from running
+ * @name Job#disable
+ * @function
+ */
+export const disable = function (this: Job): Job {
+  this.attrs.disabled = true;
+  return this;
+};

package/lib/job/enable.ts

@@ -0,0 +1,11 @@
+import { Job } from ".";
+
+/**
+ * Allows job type to run
+ * @name Job#enable
+ * @function
+ */
+export const enable = function (this: Job): Job {
+  this.attrs.disabled = false;
+  return this;
+};

package/lib/job/fail.ts

@@ -0,0 +1,29 @@
+import createDebugger from "debug";
+import { Job } from ".";
+
+const debug = createDebugger("agenda:job");
+
+/**
+ * Fails the job with a reason (error) specified
+ * @name Job#fail
+ * @function
+ * @param reason reason job failed
+ */
+export const fail = function (this: Job, reason: string | Error): Job {
+  if (reason instanceof Error) {
+    reason = reason.message;
+  }
+
+  this.attrs.failReason = reason;
+  this.attrs.failCount = (this.attrs.failCount || 0) + 1;
+  const now = new Date();
+  this.attrs.failedAt = now;
+  this.attrs.lastFinishedAt = now;
+  debug(
+    "[%s:%s] fail() called [%d] times so far",
+    this.attrs.name,
+    this.attrs._id,
+    this.attrs.failCount
+  );
+  return this;
+};

package/lib/job/index.ts

@@ -0,0 +1,221 @@
+import { toJson } from "./to-json";
+import { computeNextRunAt } from "./compute-next-run-at";
+import { repeatEvery } from "./repeat-every";
+import { repeatAt } from "./repeat-at";
+import { disable } from "./disable";
+import { enable } from "./enable";
+import { unique } from "./unique";
+import { schedule } from "./schedule";
+import { priority } from "./priority";
+import { fail } from "./fail";
+import { run } from "./run";
+import { isRunning } from "./is-running";
+import { save } from "./save";
+import { remove } from "./remove";
+import { touch } from "./touch";
+import { setShouldSaveResult } from "./set-shouldsaveresult";
+import { parsePriority } from "../utils";
+import { Agenda } from "../agenda";
+import { JobPriority } from "../agenda/define";
+import * as mongodb from "mongodb";
+
+type Modify<T, R> = Omit<T, keyof R> & R
+
+export interface JobAttributesData {
+  [key: string]: any;
+}
+export interface JobAttributes<
+  T extends JobAttributesData = JobAttributesData
+> {
+  /**
+   * The record identity.
+   */
+  _id: mongodb.ObjectId;
+
+  agenda: Agenda;
+
+  /**
+   * The type of the job (single|normal).
+   */
+  type: string;
+
+  /**
+   * The name of the job.
+   */
+  name: string;
+
+  /**
+   * Job's state
+   */
+  disabled?: boolean;
+
+  /**
+   * Date/time the job will run next.
+   */
+  nextRunAt?: Date | null;
+
+  /**
+   * Date/time the job was locked.
+   */
+  lockedAt?: Date | null;
+
+  /**
+   * The priority of the job.
+   */
+  priority: number | string;
+
+  /**
+   * The job details.
+   */
+  data: T;
+
+  unique?: any;
+  uniqueOpts?: {
+    insertOnly: boolean;
+  };
+
+  /**
+   * How often the job is repeated using a human-readable or cron format.
+   */
+  repeatInterval?: string;
+
+  /**
+   * The timezone that conforms to [moment-timezone](http://momentjs.com/timezone/).
+   */
+  repeatTimezone?: string | null;
+
+  repeatAt?: string;
+
+  /**
+   * Date/time the job was last run.
+   */
+  lastRunAt?: Date;
+
+  /**
+   * Date/time the job last finished running.
+   */
+  lastFinishedAt?: Date;
+
+  startDate?: Date | number | null;
+  endDate?: Date | number | null;
+  skipDays?: string | null;
+
+  /**
+   * The reason the job failed.
+   */
+  failReason?: string;
+
+  /**
+   * The number of times the job has failed.
+   */
+  failCount?: number;
+
+  /**
+   * The date/time the job last failed.
+   */
+  failedAt?: Date;
+
+  /**
+   * Date/time the job was last modified.
+   */
+  lastModifiedBy?: string;
+
+  /**
+   * Should the return value of the job be persisted.
+   */
+  shouldSaveResult?: boolean;
+
+  /**
+   * Result of the finished job.
+   */
+  result?: unknown;
+}
+
+/**
+ * @class
+ * @param {Object} args - Job Options
+ * @property {Object} agenda - The Agenda instance
+ * @property {Object} attrs
+ */
+class Job<T extends JobAttributesData = JobAttributesData> {
+  /**
+   * The agenda that created the job.
+   */
+  agenda: Agenda;
+
+  /**
+   * The database record associated with the job.
+   */
+  attrs: JobAttributes<T>;
+
+  toJSON!: typeof toJson;
+  computeNextRunAt!: typeof computeNextRunAt;
+  repeatEvery!: typeof repeatEvery;
+  repeatAt!: typeof repeatAt;
+  disable!: typeof disable;
+  enable!: typeof enable;
+  unique!: typeof unique;
+  schedule!: typeof schedule;
+  priority!: typeof priority;
+  fail!: typeof fail;
+  run!: typeof run;
+  isRunning!: typeof isRunning;
+  save!: typeof save;
+  remove!: typeof remove;
+  touch!: typeof touch;
+  setShouldSaveResult!: typeof setShouldSaveResult;
+
+  constructor(options: Modify<JobAttributes<T>, { _id?: mongodb.ObjectId; }>) {
+    const { agenda, type, nextRunAt, ...args } = options ?? {};
+
+    // Save Agenda instance
+    this.agenda = agenda;
+
+    // Set priority
+    args.priority =
+      args.priority === undefined
+        ? JobPriority.normal
+        : parsePriority(args.priority);
+
+    // Set shouldSaveResult option
+    args.shouldSaveResult = args.shouldSaveResult || false
+
+    // Set attrs to args
+    const attrs: any = {};
+    for (const key in args) {
+      if ({}.hasOwnProperty.call(args, key)) {
+        // @ts-expect-error
+        attrs[key] = args[key];
+      }
+    }
+
+    // Set defaults if undefined
+    this.attrs = {
+      ...attrs,
+      // NOTE: What is the difference between 'once' here and 'single' in agenda/index.js?
+      name: attrs.name || "",
+      priority: attrs.priority,
+      type: type || "once",
+      nextRunAt: nextRunAt || new Date(),
+    };
+  }
+}
+
+Job.prototype.toJSON = toJson;
+Job.prototype.computeNextRunAt = computeNextRunAt;
+Job.prototype.repeatEvery = repeatEvery;
+Job.prototype.repeatAt = repeatAt;
+Job.prototype.disable = disable;
+Job.prototype.enable = enable;
+Job.prototype.unique = unique;
+Job.prototype.schedule = schedule;
+Job.prototype.priority = priority;
+Job.prototype.fail = fail;
+Job.prototype.run = run;
+Job.prototype.isRunning = isRunning;
+Job.prototype.save = save;
+Job.prototype.remove = remove;
+Job.prototype.touch = touch;
+Job.prototype.setShouldSaveResult = setShouldSaveResult;
+
+export { Job };

package/lib/job/is-running.ts

@@ -0,0 +1,29 @@
+import { Job } from ".";
+
+/**
+ * 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)
+ * @name Job#isRunning
+ * @function
+ * @returns Whether or not job is running at the moment (true for running)
+ */
+export const isRunning = function (this: Job): boolean {
+  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;
+};

package/lib/job/priority.ts

@@ -0,0 +1,11 @@
+import { Job } from ".";
+import { parsePriority } from "../utils";
+
+/**
+ * Sets priority of the job
+ * @param priority priority of when job should be queued
+ */
+export const priority = function (this: Job, priority: string): Job {
+  this.attrs.priority = parsePriority(priority);
+  return this;
+};