agenda 4.4.0 → 5.0.0

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;
+};

package/lib/job/remove.ts

@@ -0,0 +1,10 @@
+import { Job } from ".";
+
+/**
+ * Remove the job from MongoDB
+ * @name Job#remove
+ * @function
+ */
+export const remove = async function (this: Job): Promise<number | undefined> {
+  return this.agenda.cancel({ _id: this.attrs._id });
+};

package/lib/job/repeat-at.ts

@@ -0,0 +1,12 @@
+import { Job } from ".";
+
+/**
+ * Sets a job to repeat at a specific time
+ * @name Job#repeatAt
+ * @function
+ * @param time time to repeat job at (human readable or number)
+ */
+export const repeatAt = function (this: Job, time: string): Job {
+  this.attrs.repeatAt = time;
+  return this;
+};

package/lib/job/repeat-every.ts

@@ -0,0 +1,40 @@
+import { Job } from ".";
+
+export interface JobOptions {
+  timezone?: string;
+  startDate?: Date | number;
+  endDate?: Date | number;
+  skipDays?: string;
+  skipImmediate?: boolean;
+}
+
+/**
+ * Sets a job to repeat every X amount of time
+ * @name Job#repeatEvery
+ * @function
+ * @param interval repeat every X
+ * @param options options to use for job
+ */
+export const repeatEvery = function (
+  this: Job,
+  interval: string,
+  options: JobOptions = {}
+): Job {
+  this.attrs.repeatInterval = interval;
+  this.attrs.repeatTimezone = options.timezone ? options.timezone : null;
+  // Following options are added to handle start day
+  // and cases like run job every x days (skip some days)
+  this.attrs.startDate = options.startDate ?? null;
+  this.attrs.endDate = options.endDate ?? null;
+  this.attrs.skipDays = options.skipDays ?? null;
+  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;
+};

package/lib/job/run.ts

@@ -0,0 +1,125 @@
+import createDebugger from "debug";
+import { Job } from ".";
+
+const debug = createDebugger("agenda:job");
+
+/**
+ * Internal method (RUN)
+ * @name Job#run
+ * @function
+ */
+export const run = async function (this: Job): Promise<Job> {
+  const { agenda } = this;
+  const definition = agenda._definitions[this.attrs.name];
+
+  // @TODO: this lint issue should be looked into: https://eslint.org/docs/rules/no-async-promise-executor
+  // eslint-disable-next-line no-async-promise-executor
+  return new Promise(async (resolve, reject) => {
+    this.attrs.lastRunAt = new Date();
+    debug(
+      "[%s:%s] setting lastRunAt to: %s",
+      this.attrs.name,
+      this.attrs._id,
+      this.attrs.lastRunAt.toISOString()
+    );
+    this.computeNextRunAt();
+    await this.save();
+
+    let finished = false;
+    const jobCallback = async (error?: Error, result?: unknown) => {
+      // We don't want to complete the job multiple times
+      if (finished) {
+        return;
+      }
+
+      finished = true;
+
+      if (error) {
+        this.fail(error);
+      } else {
+        this.attrs.lastFinishedAt = new Date();
+
+        if(this.attrs.shouldSaveResult && result) {
+          this.attrs.result = result;
+        }
+      }
+
+      this.attrs.lockedAt = null;
+
+      await this.save().catch((error: Error) => {
+        debug(
+          "[%s:%s] failed to be saved to MongoDB",
+          this.attrs.name,
+          this.attrs._id
+        );
+        reject(error);
+      });
+      debug(
+        "[%s:%s] was saved successfully to MongoDB",
+        this.attrs.name,
+        this.attrs._id
+      );
+
+      if (error) {
+        agenda.emit("fail", error, this);
+        agenda.emit("fail:" + this.attrs.name, error, this);
+        debug(
+          "[%s:%s] has failed [%s]",
+          this.attrs.name,
+          this.attrs._id,
+          error.message
+        );
+      } else {
+        agenda.emit("success", this);
+        agenda.emit("success:" + this.attrs.name, this);
+        debug("[%s:%s] has succeeded", this.attrs.name, this.attrs._id);
+      }
+
+      agenda.emit("complete", this);
+      agenda.emit("complete:" + this.attrs.name, this);
+      debug(
+        "[%s:%s] job finished at [%s] and was unlocked",
+        this.attrs.name,
+        this.attrs._id,
+        this.attrs.lastFinishedAt
+      );
+      // Curiously, we still resolve successfully if the job processor failed.
+      // Agenda is not equipped to handle errors originating in user code, so, we leave them to inspect the side-effects of job.fail()
+      resolve(this);
+    };
+
+    try {
+      agenda.emit("start", this);
+      agenda.emit("start:" + this.attrs.name, this);
+      debug("[%s:%s] starting job", this.attrs.name, this.attrs._id);
+      if (!definition) {
+        debug(
+          "[%s:%s] has no definition, can not run",
+          this.attrs.name,
+          this.attrs._id
+        );
+        throw new Error("Undefined job");
+      }
+
+      if (definition.fn.length === 2) {
+        debug(
+          "[%s:%s] process function being called",
+          this.attrs.name,
+          this.attrs._id
+        );
+        await definition.fn(this, jobCallback);
+      } else {
+        debug(
+          "[%s:%s] process function being called",
+          this.attrs.name,
+          this.attrs._id
+        );
+        const result = await definition.fn(this);
+        await jobCallback(undefined, result);
+      }
+    } catch (error) {
+      debug("[%s:%s] unknown error occurred", this.attrs.name, this.attrs._id);
+      await jobCallback(error as Error);
+    }
+  });
+};