agenda 4.4.0 → 5.0.0

package/lib/agenda/jobs.ts

@@ -0,0 +1,31 @@
+import { Filter } from "mongodb";
+import { Agenda } from ".";
+import { Job } from "../job";
+import { createJob } from "../utils";
+
+/**
+ * Finds all jobs matching 'query'
+ * @name Agenda#jobs
+ * @function
+ * @param [query] object for MongoDB
+ * @param [sort] object for MongoDB
+ * @param [limit] number of documents to return from MongoDB
+ * @param [number] of documents to skip in MongoDB
+ * @returns resolves when fails or passes
+ */
+export const jobs = async function (
+  this: Agenda,
+  query: Filter<any> = {},
+  sort = {},
+  limit = 0,
+  skip = 0
+): Promise<Job[]> {
+  const result = await this._collection
+    .find(query) // eslint-disable-line
+    .sort(sort)
+    .limit(limit)
+    .skip(skip)
+    .toArray();
+
+  return result.map((job: any) => createJob(this, job));
+};

package/lib/agenda/lock-limit.ts

@@ -0,0 +1,17 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:locklimit");
+
+/**
+ * Set the default amount jobs that are allowed to be locked at one time (GLOBAL)
+ * @name Agenda#locklimit
+ * @function
+ * @param limit num Lock limit
+ */
+export const lockLimit = function (this: Agenda, limit: number): Agenda {
+  // @NOTE: Is this different than max concurrency?
+  debug("Agenda.lockLimit(%d)", limit);
+  this._lockLimit = limit;
+  return this;
+};

package/lib/agenda/max-concurrency.ts

@@ -0,0 +1,20 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:maxConcurrency");
+
+/**
+ * Set the concurrency for jobs (globally), type does not matter
+ * @name Agenda#maxConcurrency
+ * @function
+ * @param concurrency max concurrency value
+ * @returns agenda instance
+ */
+export const maxConcurrency = function (
+  this: Agenda,
+  concurrency: number
+): Agenda {
+  debug("Agenda.maxConcurrency(%d)", concurrency);
+  this._maxConcurrency = concurrency;
+  return this;
+};

package/lib/agenda/mongo.ts

@@ -0,0 +1,21 @@
+import { AnyError, Collection, Db } from "mongodb";
+import { Agenda } from ".";
+
+/**
+ * Build method used to add MongoDB connection details
+ * @name Agenda#mongo
+ * @function
+ * @param mdb instance of MongoClient to use
+ * @param [collection] name collection we want to use ('agendaJobs')
+ * @param [cb] called when MongoDB connection fails or passes
+ */
+export const mongo = function (
+  this: Agenda,
+  mdb: Db,
+  collection?: string,
+  cb?: (error: AnyError | undefined, collection: Collection<any> | null) => void
+): Agenda {
+  this._mdb = mdb;
+  this.db_init(collection, cb);
+  return this;
+};

package/lib/agenda/name.ts

@@ -0,0 +1,16 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:name");
+
+/**
+ * Set name of queue
+ * @name Agenda#name
+ * @function
+ * @param name name of agenda instance
+ */
+export const name = function (this: Agenda, name: string): Agenda {
+  debug("Agenda.name(%s)", name);
+  this._name = name;
+  return this;
+};

package/lib/agenda/now.ts

@@ -0,0 +1,31 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+import { Job, JobAttributesData } from "../job";
+
+const debug = createDebugger("agenda:now");
+
+/**
+ * Create a job for this exact moment
+ * @name Agenda#now
+ * @function
+ * @param name name of job to schedule
+ * @param data data to pass to job
+ */
+export const now = async function<T extends JobAttributesData> (
+  this: Agenda,
+  name: string,
+  data: T
+): Promise<Job> {
+  debug("Agenda.now(%s, [Object])", name);
+  try {
+    const job = this.create(name, data);
+
+    job.schedule(new Date());
+    await job.save();
+
+    return job;
+  } catch (error) {
+    debug("error trying to create a job for this exact moment");
+    throw error;
+  }
+};

package/lib/agenda/process-every.ts

@@ -0,0 +1,18 @@
+import createDebugger from "debug";
+import humanInterval from "human-interval";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:processEvery");
+
+/**
+ * Set the default process interval
+ * @name Agenda#processEvery
+ * @function
+ * @param time - time to process, expressed in human interval
+ */
+export const processEvery = function (this: Agenda, time: string): Agenda {
+  debug("Agenda.processEvery(%d)", time);
+  // @ts-expect-error
+  this._processEvery = humanInterval(time);
+  return this;
+};

package/lib/agenda/purge.ts

@@ -0,0 +1,19 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:purge");
+
+/**
+ * Removes all jobs from queue
+ * @name Agenda#purge
+ * @function
+ * @returns resolved when job cancelling fails or passes
+ */
+export const purge = async function (
+  this: Agenda
+): Promise<number | undefined> {
+  // @NOTE: Only use after defining your jobs
+  const definedNames = Object.keys(this._definitions);
+  debug("Agenda.purge(%o)", definedNames);
+  return this.cancel({ name: { $not: { $in: definedNames } } });
+};

package/lib/agenda/save-job.ts

@@ -0,0 +1,185 @@
+import createDebugger from "debug";
+import { ObjectId } from "mongodb";
+import { Agenda } from ".";
+import { Job } from "../job";
+import { processJobs } from "../utils";
+
+const debug = createDebugger("agenda:saveJob");
+
+/**
+ * Given a result for findOneAndUpdate() or insert() above, determine whether to process
+ * the job immediately or to let the processJobs() interval pick it up later
+ * @param job job instance
+ * @param result the data returned from the findOneAndUpdate() call or insertOne() call
+ * @access private
+ */
+const processDbResult = async function (this: Agenda, job: Job, result: any) {
+  debug(
+    "processDbResult() called with success, checking whether to process job immediately or not"
+  );
+
+  // We have a result from the above calls
+  // findOneAndUpdate() returns different results than insertOne() so check for that
+  let resultValue = result.insertedId ? result.insertedId : result.value;
+
+  if (resultValue) {
+    let _id: ObjectId;
+    let nextRunAt: Date | null | undefined;
+
+    if (result.insertedId) {
+      _id = result.insertedId;
+      // find the doc using _id
+      const _job = await this._collection.findOne({ _id });
+
+      if (_job) {
+        nextRunAt = _job.nextRunAt;
+      }
+    } else {
+      // If it is an array, grab the first job
+      if (Array.isArray(resultValue)) {
+        resultValue = resultValue[0];
+      }
+
+      _id = resultValue._id;
+      nextRunAt = resultValue.nextRunAt;
+    }
+
+    // Grab ID and nextRunAt from MongoDB and store it as an attribute on Job
+    job.attrs._id = _id;
+    job.attrs.nextRunAt = nextRunAt;
+
+    // If the current job would have been processed in an older scan, process the job immediately
+    if (job.attrs.nextRunAt && job.attrs.nextRunAt < this._nextScanAt) {
+      debug(
+        "[%s:%s] job would have ran by nextScanAt, processing the job immediately",
+        job.attrs.name,
+        resultValue._id
+      );
+      await processJobs.call(this, job);
+    }
+  }
+
+  // Return the Job instance
+  return job;
+};
+
+/**
+ * Save the properties on a job to MongoDB
+ * @name Agenda#saveJob
+ * @function
+ * @param job job to save into MongoDB
+ * @returns resolves when job is saved or errors
+ */
+export const saveJob = async function (this: Agenda, job: Job): Promise<Job> {
+  try {
+    debug("attempting to save a job into Agenda instance");
+
+    // Grab information needed to save job but that we don't want to persist in MongoDB
+    const id = job.attrs._id;
+    const { unique, uniqueOpts } = job.attrs;
+
+    // Store job as JSON and remove props we don't want to store from object
+    const props = job.toJSON();
+    delete props._id;
+    delete props.unique;
+    delete props.uniqueOpts;
+
+    // Store name of agenda queue as last modifier in job data
+    props.lastModifiedBy = this._name;
+    debug("[job %s] set job props: \n%O", id, props);
+
+    // Grab current time and set default query options for MongoDB
+    const now = new Date();
+    const protect = {};
+    let update = { $set: props };
+    debug("current time stored as %s", now.toISOString());
+
+    // If the job already had an ID, then update the properties of the job
+    // i.e, who last modified it, etc
+    if (id) {
+      // Update the job and process the resulting data'
+      debug(
+        "job already has _id, calling findOneAndUpdate() using _id as query"
+      );
+      const result = await this._collection.findOneAndUpdate(
+        { _id: id },
+        update,
+        { returnDocument: "after" }
+      );
+      return await processDbResult.call(this, job, result);
+    }
+
+    if (props.type === "single") {
+      // Job type set to 'single' so...
+      // NOTE: Again, not sure about difference between 'single' here and 'once' in job.js
+      debug('job with type of "single" found');
+
+      // If the nextRunAt time is older than the current time, "protect" that property, meaning, don't change
+      // a scheduled job's next run time!
+      if (props.nextRunAt && props.nextRunAt <= now) {
+        debug(
+          "job has a scheduled nextRunAt time, protecting that field from upsert"
+        );
+        // @ts-expect-error
+        protect.nextRunAt = props.nextRunAt;
+        delete props.nextRunAt;
+      }
+
+      // If we have things to protect, set them in MongoDB using $setOnInsert
+      if (Object.keys(protect).length > 0) {
+        // @ts-expect-error
+        update.$setOnInsert = protect;
+      }
+
+      // Try an upsert
+      // NOTE: 'single' again, not exactly sure what it means
+      debug(
+        'calling findOneAndUpdate() with job name and type of "single" as query'
+      );
+      const result = await this._collection.findOneAndUpdate(
+        {
+          name: props.name,
+          type: "single",
+        },
+        update,
+        {
+          upsert: true,
+          returnDocument: "after",
+        }
+      );
+      return await processDbResult.call(this, job, result);
+    }
+
+    if (unique) {
+      // If we want the job to be unique, then we can upsert based on the 'unique' query object that was passed in
+      const query = job.attrs.unique;
+      query.name = props.name;
+      if (uniqueOpts?.insertOnly) {
+        // @ts-expect-error
+        update = { $setOnInsert: props };
+      }
+
+      // Use the 'unique' query object to find an existing job or create a new one
+      debug(
+        "calling findOneAndUpdate() with unique object as query: \n%O",
+        query
+      );
+      const result = await this._collection.findOneAndUpdate(query, update, {
+        upsert: true,
+        returnDocument: "after",
+      });
+      return await processDbResult.call(this, job, result);
+    }
+
+    // If all else fails, the job does not exist yet so we just insert it into MongoDB
+    debug(
+      "using default behavior, inserting new job via insertOne() with props that were set: \n%O",
+      props
+    );
+    const result = await this._collection.insertOne(props);
+    return await processDbResult.call(this, job, result);
+  } catch (error) {
+    debug("processDbResult() received an error, job was not updated/created");
+    throw error;
+  }
+};

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;