agenda 4.3.0 → 5.0.0

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

package/lib/job/save.ts

@@ -0,0 +1,11 @@
+import { Job } from ".";
+
+/**
+ * Saves a job into the MongoDB
+ * @name Job#
+ * @function
+ * @returns instance of Job resolved after job is saved or errors
+ */
+export const save = async function (this: Job): Promise<Job> {
+  return this.agenda.saveJob(this);
+};

package/lib/job/schedule.ts

@@ -0,0 +1,15 @@
+// @ts-expect-error
+import date from "date.js";
+import { Job } from ".";
+
+/**
+ * Schedules a job to run at specified time
+ * @name Job#schedule
+ * @function
+ * @param time schedule a job to run "then"
+ */
+export const schedule = function (this: Job, time: string | Date): Job {
+  const d = new Date(time);
+  this.attrs.nextRunAt = Number.isNaN(d.getTime()) ? date(time) : d;
+  return this;
+};

package/lib/job/set-shouldsaveresult.ts

@@ -0,0 +1,10 @@
+import { Job } from ".";
+
+/**
+ * Sets the flag if the return value of the job should be persisted
+ * @param shouldSaveResult flag if the return value of the job should be persisted
+ */
+export const setShouldSaveResult = function (this: Job, shouldSaveResult: boolean): Job {
+  this.attrs.shouldSaveResult = shouldSaveResult;
+  return this;
+};

package/lib/job/to-json.ts

@@ -0,0 +1,36 @@
+import { Job, JobAttributes } from ".";
+
+/**
+ * Given a job, turn it into an object we can store in Mongo
+ * @name Job#toJSON
+ * @function
+ * @returns json object from Job
+ */
+export const toJson = function (this: Job): Partial<JobAttributes> {
+  const attrs = this.attrs || {};
+  const result = {};
+
+  for (const prop in attrs) {
+    if ({}.hasOwnProperty.call(attrs, prop)) {
+      // @ts-expect-error index signature missing
+      result[prop] = attrs[prop];
+    }
+  }
+
+  const dates = [
+    "lastRunAt",
+    "lastFinishedAt",
+    "nextRunAt",
+    "failedAt",
+    "lockedAt",
+  ];
+  dates.forEach((d) => {
+    // @ts-expect-error index signature missing
+    if (result[d]) {
+      // @ts-expect-error index signature missing
+      result[d] = new Date(result[d]);
+    }
+  });
+
+  return result;
+};

package/lib/job/touch.ts

@@ -0,0 +1,11 @@
+import { Job } from ".";
+
+/**
+ * Updates "lockedAt" time so the job does not get picked up again
+ * @name Job#touch
+ * @function
+ */
+export const touch = async function (this: Job): Promise<Job> {
+  this.attrs.lockedAt = new Date();
+  return this.save();
+};

package/lib/job/unique.ts

@@ -0,0 +1,18 @@
+import { Job } from ".";
+
+/**
+ * Data to ensure is unique for job to be created
+ * @name Job#unique
+ * @function
+ * @param unique mongo data query for unique
+ * @param options unique options
+ */
+export const unique = function (
+  this: Job,
+  unique: any,
+  options?: { insertOnly: boolean }
+): Job {
+  this.attrs.unique = unique;
+  this.attrs.uniqueOpts = options;
+  return this;
+};

package/lib/utils/create-job.ts

@@ -0,0 +1,13 @@
+import { Agenda } from "../agenda";
+import { Job, JobAttributes } from "../job";
+
+/**
+ * Create Job object from data
+ * @param {Object} agenda instance of Agenda
+ * @param {Object} jobData job data
+ * @returns {Job} returns created job
+ */
+export const createJob = (agenda: Agenda, jobData: JobAttributes): Job => {
+  jobData.agenda = agenda;
+  return new Job(jobData);
+};

package/lib/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./create-job";
+export * from "./parse-priority";
+export * from "./process-jobs";

package/lib/utils/parse-priority.ts

@@ -0,0 +1,37 @@
+import { JobPriority } from "../agenda/define";
+
+/**
+ * Internal method to turn priority into a number
+ * @param priority string to parse into number
+ */
+export const parsePriority = (priority: string | number): number => {
+  if (typeof priority === "number") {
+    return priority;
+  }
+
+  switch (priority) {
+    case "lowest": {
+      return JobPriority.lowest;
+    }
+
+    case "low": {
+      return JobPriority.low;
+    }
+
+    case "normal": {
+      return JobPriority.normal;
+    }
+
+    case "high": {
+      return JobPriority.high;
+    }
+
+    case "highest": {
+      return JobPriority.highest;
+    }
+
+    default: {
+      return JobPriority.normal;
+    }
+  }
+};