agenda 4.3.0 → 5.0.0

package/lib/agenda/create.ts

@@ -0,0 +1,22 @@
+import createDebugger from "debug";
+import { Job, JobAttributesData } from "../job";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:create");
+
+/**
+ * Given a name and some data, create a new job
+ * @name Agenda#create
+ * @function
+ * @param name name of job
+ * @param data data to set for job
+ */
+export const create = function<T extends JobAttributesData> (this: Agenda, name: string, data: T): Job {
+  debug("Agenda.create(%s, [Object])", name);
+  const priority = this._definitions[name]
+    ? this._definitions[name].priority
+    : 0;
+  const shouldSaveResult = this._definitions[name] ? this._definitions[name].shouldSaveResult || false : false
+  const job = new Job({ name, data, type: "normal", priority, shouldSaveResult, agenda: this });
+  return job;
+};

package/lib/agenda/database.ts

@@ -0,0 +1,63 @@
+import createDebugger from "debug";
+import { AnyError, Collection, MongoClient, MongoClientOptions } from "mongodb";
+import { Agenda } from ".";
+import { hasMongoProtocol } from "./has-mongo-protocol";
+
+const debug = createDebugger("agenda:database");
+
+/**
+ * Connect to the spec'd MongoDB server and database.
+ *
+ * NOTE:
+ * If `url` includes auth details then `options` must specify: { 'uri_decode_auth': true }. This does Auth on
+ * the specified database, not the Admin database. If you are using Auth on the Admin DB and not on the Agenda DB,
+ * then you need to authenticate against the Admin DB and then pass the MongoDB instance into the constructor
+ * or use Agenda.mongo(). If your app already has a MongoDB connection then use that. ie. specify config.mongo in
+ * the constructor or use Agenda.mongo().
+ * @name Agenda#database
+ * @function
+ * @param url MongoDB server URI
+ * @param [collection] name of collection to use. Defaults to `agendaJobs`
+ * @param [options] options for connecting
+ * @param [cb] callback of MongoDB connection
+ */
+export const database = function (
+  this: Agenda,
+  url: string,
+  collection?: string,
+  options: MongoClientOptions = {},
+  cb?: (error: AnyError | undefined, collection: Collection<any> | null) => void
+): Agenda | void {
+  if (!hasMongoProtocol(url)) {
+    url = "mongodb://" + url;
+  }
+
+  collection = collection || "agendaJobs";
+
+  MongoClient.connect(url, options, (error, client) => {
+    if (error) {
+      debug("error connecting to MongoDB using collection: [%s]", collection);
+      if (cb) {
+        cb(error, null);
+      } else {
+        throw error;
+      }
+
+      return;
+    }
+
+    debug(
+      "successful connection to MongoDB using collection: [%s]",
+      collection
+    );
+
+    if (client) {
+      this._db = client;
+      this._mdb = client.db();
+      this.db_init(collection, cb);
+    } else {
+      throw new Error("Mongo Client is undefined");
+    }
+  });
+  return this;
+};

package/lib/agenda/db-init.ts

@@ -0,0 +1,45 @@
+import createDebugger from "debug";
+import { AnyError, Collection } from "mongodb";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:db_init");
+
+/**
+ * Setup and initialize the collection used to manage Jobs.
+ * @name Agenda#dbInit
+ * @function
+ * @param collection name or undefined for default 'agendaJobs'
+ * @param [cb] called when the db is initialized
+ */
+export const dbInit = function (
+  this: Agenda,
+  collection = "agendaJobs",
+  cb?: (error: AnyError | undefined, collection: Collection<any> | null) => void
+): void {
+  debug("init database collection using name [%s]", collection);
+  this._collection = this._mdb.collection(collection);
+  if (this._disableAutoIndex) {
+    debug("skipping auto index creation");
+    this.emit("ready");
+    return;
+  }
+
+  debug("attempting index creation");
+  this._collection.createIndex(
+    this._indices,
+    { name: "findAndLockNextJobIndex" },
+    (error) => {
+      if (error) {
+        debug("index creation failed");
+        this.emit("error", error);
+      } else {
+        debug("index creation success");
+        this.emit("ready");
+      }
+
+      if (cb) {
+        cb(error, this._collection);
+      }
+    }
+  );
+};

package/lib/agenda/default-concurrency.ts

@@ -0,0 +1,19 @@
+import { Agenda } from ".";
+import createDebugger from "debug";
+
+const debug = createDebugger("agenda:defaultConcurrency");
+
+/**
+ * Set the default concurrency for each job
+ * @name Agenda#defaultConcurrency
+ * @function
+ * @param concurrency default concurrency
+ */
+export const defaultConcurrency = function (
+  this: Agenda,
+  concurrency: number
+): Agenda {
+  debug("Agenda.defaultConcurrency(%d)", concurrency);
+  this._defaultConcurrency = concurrency;
+  return this;
+};

package/lib/agenda/default-lock-lifetime.ts

@@ -0,0 +1,17 @@
+import { Agenda } from ".";
+import createDebugger from "debug";
+
+const debug = createDebugger("agenda:defaultLockLifetime");
+
+/**
+ * Set the default lock time (in ms)
+ * Default is 10 * 60 * 1000 ms (10 minutes)
+ * @name Agenda#defaultLockLifetime
+ * @function
+ * @param {Number} ms time in ms to set default lock
+ */
+export const defaultLockLifetime = function (this: Agenda, ms: number): Agenda {
+  debug("Agenda.defaultLockLifetime(%d)", ms);
+  this._defaultLockLifetime = ms;
+  return this;
+};

package/lib/agenda/default-lock-limit.ts

@@ -0,0 +1,17 @@
+import { Agenda } from ".";
+import createDebugger from "debug";
+
+const debug = createDebugger("agenda:defaultLockLimit");
+
+/**
+ * Set default lock limit per job type
+ * @name Agenda#defaultLockLimit
+ * @function
+ * @param {Number} num Lock limit per job
+ * @returns {Agenda} agenda instance
+ */
+export const defaultLockLimit = function (this: Agenda, times: number): Agenda {
+  debug("Agenda.defaultLockLimit(%d)", times);
+  this._defaultLockLimit = times;
+  return this;
+};

package/lib/agenda/define.ts

@@ -0,0 +1,85 @@
+import { Agenda } from ".";
+import createDebugger from "debug";
+import { Job } from "../job";
+
+const debug = createDebugger("agenda:define");
+
+export enum JobPriority {
+  highest = 20,
+  high = 10,
+  normal = 0,
+  low = -10,
+  lowest = -20,
+}
+
+export interface DefineOptions {
+  /**
+   * Maximum number of that job that can be running at once (per instance of agenda)
+   */
+  concurrency?: number;
+
+  /**
+   * Maximum number of that job that can be locked at once (per instance of agenda)
+   */
+  lockLimit?: number;
+
+  /**
+   * Interval in ms of how long the job stays locked for (see multiple job processors for more info). A job will
+   * automatically unlock if done() is called.
+   */
+  lockLifetime?: number;
+
+  /**
+   * (lowest|low|normal|high|highest|number) specifies the priority of the job. Higher priority jobs will run
+   * first.
+   */
+  priority?: JobPriority;
+
+  /**
+   * Should the return value of the job be persisted
+   */
+  shouldSaveResult?: boolean;
+}
+
+export type Processor<T> =
+  | ((job: Job<T>) => Promise<void>)
+  | ((job: Job<T>, done: () => void) => void);
+
+/**
+ * Setup definition for job
+ * Method is used by consumers of lib to setup their functions
+ * @name Agenda#define
+ * @function
+ * @param name name of job
+ * @param options options for job to run
+ * @param [processor] function to be called to run actual job
+ */
+export const define = function<T> (
+  this: Agenda,
+  name: string,
+  options: DefineOptions | Processor<T>,
+  processor?: Processor<T>
+): void {
+  if (processor === undefined) {
+    processor = options as Processor<T>;
+    options = {};
+  }
+
+  this._definitions[name] = {
+    fn: processor,
+    concurrency:
+      (options as DefineOptions).concurrency || this._defaultConcurrency, // `null` is per interface definition of DefineOptions not valid
+    lockLimit: (options as DefineOptions).lockLimit || this._defaultLockLimit,
+    priority: (options as DefineOptions).priority || JobPriority.normal,
+    lockLifetime:
+      (options as DefineOptions).lockLifetime || this._defaultLockLifetime,
+    running: 0,
+    locked: 0,
+    shouldSaveResult: (options as DefineOptions).shouldSaveResult || false
+  };
+  debug(
+    "job [%s] defined with following options: \n%O",
+    name,
+    this._definitions[name]
+  );
+};

package/lib/agenda/disable.ts

@@ -0,0 +1,28 @@
+import createDebugger from "debug";
+import { Filter } from "mongodb";
+import { Agenda } from ".";
+const debug = createDebugger("agenda:disable");
+
+/**
+ * Disables any jobs matching the passed MongoDB query by setting the `disabled` flag to `true`
+ * @name Agenda#disable
+ * @function
+ * @param query MongoDB query to use when enabling
+ * @returns {Promise<number>} Resolved with the number of disabled job instances.
+ */
+export const disable = async function (
+  this: Agenda,
+  query: Filter<unknown> = {}
+): Promise<number> {
+  debug("attempting to disable all jobs matching query", query);
+  try {
+    const { modifiedCount } = await this._collection.updateMany(query, {
+      $set: { disabled: true },
+    });
+    debug("%s jobs disabled");
+    return modifiedCount;
+  } catch (error) {
+    debug("error trying to mark jobs as `disabled`");
+    throw error;
+  }
+};

package/lib/agenda/drain.ts

@@ -0,0 +1,30 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+
+const debug = createDebugger("agenda:drain");
+
+/**
+ * Clear the interval that processes the jobs
+ * @name Agenda#drain
+ * @function
+ * @returns resolves when all running jobs completes
+ */
+export const drain = async function (this: Agenda): Promise<void> {
+    return new Promise((resolve) => {
+        debug("Agenda.drain called, clearing interval for processJobs()");
+        clearInterval(this._processInterval);
+        this._processInterval = undefined;
+
+        if (this._runningJobs.length === 0) {
+            resolve();
+        } else {
+            debug("Agenda.drain waiting for jobs to finish");
+            this.on('complete', () => {
+                // running jobs are removed after the event
+                if (this._runningJobs.length === 1) {
+                    resolve();
+                }
+            });
+        }
+    });
+};

package/lib/agenda/enable.ts

@@ -0,0 +1,29 @@
+import createDebugger from "debug";
+import { Filter } from "mongodb";
+import { Agenda } from ".";
+const debug = createDebugger("agenda:enable");
+
+/**
+ * Enables any jobs matching the passed MongoDB query by setting the `disabled` flag to `false`
+ * @name Agenda#enable
+ * @function
+ * @param query MongoDB query to use when enabling
+ * @caller client code, Agenda.purge(), Job.remove()
+ * @returns {Promise<Number>} A promise that contains the number of removed documents when fulfilled.
+ */
+export const enable = async function (
+  this: Agenda,
+  query: Filter<unknown> = {}
+): Promise<number> {
+  debug("attempting to enable all jobs matching query", query);
+  try {
+    const { modifiedCount } = await this._collection.updateMany(query, {
+      $set: { disabled: false },
+    });
+    debug("%s jobs enabled", modifiedCount);
+    return modifiedCount;
+  } catch (error) {
+    debug("error trying to mark jobs as `enabled`");
+    throw error;
+  }
+};

package/lib/agenda/every.ts

@@ -0,0 +1,86 @@
+import createDebugger from "debug";
+import { Agenda } from ".";
+import { Job, JobAttributesData } from "../job";
+import { JobOptions } from "../job/repeat-every";
+
+const debug = createDebugger("agenda:every");
+
+/**
+ * Creates a scheduled job with given interval and name/names of the job to run
+ * @name Agenda#every
+ * @function
+ * @param interval - run every X interval
+ * @param names - String or strings of jobs to schedule
+ * @param data - data to run for job
+ * @param options - options to run job for
+ * @returns Job/s created. Resolves when schedule fails or passes
+ */
+export const every = async function<T extends JobAttributesData> (
+  this: Agenda,
+  interval: string,
+  names: string | string[],
+  data?: T,
+  options?: JobOptions
+): Promise<any> {
+  /**
+   * Internal method to setup job that gets run every interval
+   * @param interval run every X interval
+   * @param name String job to schedule
+   * @param [data] data to run for job
+   * @param [options] options to run job for
+   * @returns instance of job
+   */
+  const createJob = async<T extends JobAttributesData> (
+    interval: string,
+    name: string,
+    data?: T,
+    options?: JobOptions
+  ): Promise<Job> => {
+    const job = this.create(name, data || {});
+
+    job.attrs.type = "single";
+    job.repeatEvery(interval, options);
+    return job.save();
+  };
+
+  /**
+   * Internal helper method that uses createJob to create jobs for an array of names
+   * @param interval run every X interval
+   * @param names Strings of jobs to schedule
+   * @param [data] data to run for job
+   * @param [options] options to run job for
+   * @return array of jobs created
+   */
+  const createJobs = async (
+    interval: string,
+    names: string[],
+    data?: T,
+    options?: JobOptions
+  ): Promise<Job[] | undefined> => {
+    try {
+      const jobs: Array<Promise<Job>> = [];
+      names.map((name) => jobs.push(createJob(interval, name, data, options)));
+
+      debug("every() -> all jobs created successfully");
+
+      return Promise.all(jobs);
+    } catch (error) {
+      // @TODO: catch - ignore :O
+      debug("every() -> error creating one or more of the jobs", error);
+    }
+  };
+
+  if (typeof names === "string") {
+    debug("Agenda.every(%s, %O, %O)", interval, names, options);
+    const jobs = await createJob(interval, names, data, options);
+
+    return jobs;
+  }
+
+  if (Array.isArray(names)) {
+    debug("Agenda.every(%s, %s, %O)", interval, names, options);
+    const jobs = await createJobs(interval, names, data, options);
+
+    return jobs;
+  }
+};

package/lib/agenda/find-and-lock-next-job.ts

@@ -0,0 +1,78 @@
+import createDebugger from "debug";
+import { createJob } from "../utils";
+import { Agenda } from ".";
+import { Job } from "../job";
+import { ReturnDocument } from "mongodb";
+
+const debug = createDebugger("agenda:internal:_findAndLockNextJob");
+
+/**
+ * Find and lock jobs
+ * @name Agenda#findAndLockNextJob
+ * @function
+ * @param jobName name of job to try to lock
+ * @param definition definition used to tell how job is run
+ * @access protected
+ * @caller jobQueueFilling() only
+ */
+export const findAndLockNextJob = async function (
+  this: Agenda,
+  jobName: string,
+  definition: any
+): Promise<Job | undefined> {
+  const now = new Date();
+  const lockDeadline = new Date(Date.now().valueOf() - definition.lockLifetime);
+  debug("_findAndLockNextJob(%s, [Function])", jobName);
+
+  const JOB_PROCESS_WHERE_QUERY = {
+    $and: [
+      {
+        name: jobName,
+        disabled: { $ne: true },
+      },
+      {
+        $or: [
+          {
+            lockedAt: { $eq: null },
+            nextRunAt: { $lte: this._nextScanAt },
+          },
+          {
+            lockedAt: { $lte: lockDeadline },
+          },
+        ],
+      },
+    ],
+  };
+
+  /**
+   * Query used to set a job as locked
+   * @type {{$set: {lockedAt: Date}}}
+   */
+  const JOB_PROCESS_SET_QUERY = { $set: { lockedAt: now } };
+
+  /**
+   * Query used to affect what gets returned
+   * @type {{returnOriginal: boolean, sort: object}}
+   */
+  const JOB_RETURN_QUERY = { returnDocument: ReturnDocument.AFTER, sort: this._sort };
+
+  // Find ONE and ONLY ONE job and set the 'lockedAt' time so that job begins to be processed
+  const result = await this._collection.findOneAndUpdate(
+    JOB_PROCESS_WHERE_QUERY,
+    JOB_PROCESS_SET_QUERY,
+    JOB_RETURN_QUERY
+  );
+
+  let job: Job | undefined = undefined;
+  if (result.value) {
+    debug(
+      "found a job available to lock, creating a new job on Agenda with id [%s]",
+      result.value._id
+    );
+
+    // @ts-ignore
+    job = createJob(this, result.value);
+  }
+
+  return job;
+};

package/lib/agenda/has-mongo-protocol.ts

@@ -0,0 +1,8 @@
+/**
+ * Given a mongo connection url will check if it contains the mongo
+ * @param url URL to be tested
+ * @returns whether or not the url is a valid mongo URL
+ */
+export const hasMongoProtocol = function (url: string): boolean {
+  return /mongodb(?:\+srv)?:\/\/.*/.exec(url) !== null;
+};