Cron job scheduler for
Node.js and JavaScript with
cron,
\n
\n
\n
\n
\n\n\n## Table of Contents\n\n* [Foreword](#foreword)\n* [Install](#install)\n* [Usage and Examples](#usage-and-examples)\n * [Node](#node)\n * [Browser](#browser)\n* [Node.js Email Queue Job Scheduling Example](#nodejs-email-queue-job-scheduling-example)\n* [Instance Options](#instance-options)\n* [Job Options](#job-options)\n* [Job Interval and Timeout Values](#job-interval-and-timeout-values)\n* [Listening for events](#listening-for-events)\n* [Custom error handling](#custom-error-handling)\n* [Cancellation, Retries, Stalled Jobs, and Graceful Reloading](#cancellation-retries-stalled-jobs-and-graceful-reloading)\n* [Interval, Timeout, Date, and Cron Validation](#interval-timeout-date-and-cron-validation)\n* [Writing jobs with Promises and async-await](#writing-jobs-with-promises-and-async-await)\n* [Callbacks, Done, and Completion States](#callbacks-done-and-completion-states)\n* [Long-running jobs](#long-running-jobs)\n* [Complex timeouts and intervals](#complex-timeouts-and-intervals)\n* [Custom Worker Options](#custom-worker-options)\n* [Using functions for jobs](#using-functions-for-jobs)\n* [Concurrency](#concurrency)\n\n\n## Foreword\n\n\nPrevious to creating this, I was relying heavily on [bull][]; having created [@ladjs/bull][] – but due to core issues (and being Redis-backed) it was not the best tool for the job. [Bull][] might have been okay if the core issues were fixed, however since it uses [Redis][] it should not be used for a job queue. From my experience, [Redis][] should only be used for caching and session storage purposes (e.g. CDN or managing user log in state in your application). As of the time of this writing, it has been months and the core bugs with Bull are still unresolved; as more people are continuing to reproduce and comment on the known issues.\n\nSince [workers][] are now readily available in LTS versions of Node, I thought it would be a great time to implement them in a job scheduler environment. Additionally, my research and development of a better anti-spam and anti-phishing classifier with [Spam Scanner][spam-scanner] gave me some necessary insight to using [workers][].\n\nCronJobs was created to give you fine-grained control with simplicity, and has built-in support for workers, sandboxed processes, graceful reloading, cron jobs, dates, human-friendly time representations, and much more. We recommend you to query a persistent database in your jobs, to prevent specific operations from running more than once. CronJobs does not force you to use an additional database layer of [Redis][] or [MongoDB][] to manage job state. In doing so, you should manage boolean job states yourself using queries. For instance, if you have to send a welcome email to users, only send a welcome email to users that do not have a Date value set yet for `welcome_email_sent_at`.\n\n\n## Install\n\n[npm][]:\n\n```sh\nnpm install @deboxsoft/cron-jobs\n```\n\n[yarn][]:\n\n```sh\nyarn add @deboxsoft/cron-jobs\n```\n\n\n## Usage and Examples\n\nThe example below assumes that you have a directory `jobs` in the root of the directory from which you run this example. For example, if the example below is at `/path/to/script.js`, then `/path/to/jobs/` must also exist as a directory. If you wish to disable this feature, then pass `root: false` as an option.\n\nInside this `jobs` directory are individual scripts which are run using [Workers][] per optional timeouts, and additionally, an optional interval or cron expression. The example below contains comments, which help to clarify how this works.\n\nThe option `jobs` passed to a new instance of `CronJobs` (as shown below) is an Array. It contains values which can either be a String (name of a job in the `jobs` directory, which is run on boot) OR it can be an Object with `name`, `path`, `timeout`, and `interval` properties. If you do not supply a `path`, then the path is created using the root directory (defaults to `jobs`) in combination with the `name`. If you do not supply values for `timeout` and/nor `interval`, then these values are defaulted to `0` (which is the default for both, see [index.js](src/index.ts) for more insight into configurable default options).\n\nWe have also documented all [Instance Options](#instance-options) and [Job Options](#job-options) in this README below. Be sure to read those sections so you have a complete understanding of how CronJobs works.\n\n### Node\n\nSince we use [bthreads][], Node v10+ is supported. For versions prior to Node v11.7.0, a ponyfill is provided for [workers][] that uses `child_process`. For versions greater than or equal to Node v11.7.0, it uses [workers][] directly. You can also pass `--experimental-worker` flag for older versions to use `worker_threads` (instead of the `child_process` polyfill). See the official Node.js documentation for more information.\n\n> **NOTE:** If you are using Node versions prior to Node v11.7.0, then in your worker files – you will need to use [bthreads][] instead of [workers][]. For example, you will `const thread = require('bthreads');` at the top of your file, instead of requiring `worker_threads`. This will also require you to install `bthreads` in your project with `npm install bthreads` or `yarn add bthreads`.\n\n```js\nconst path = require('path');\n\n// optional\nconst ms = require('ms');\nconst dayjs = require('dayjs');\nconst Graceful = require('@ladjs/graceful');\nconst Cabin = require('cabin');\n\n// required\nconst CronJobs = require('@deboxsoft/cron-jobs');\n\n//\n// NOTE: see the \"Instance Options\" section below in this README\n// for the complete list of options and their defaults\n//\nconst cronJobs = new CronJobs({\n //\n // NOTE: by default the `logger` is set to `console`\n // however we recommend you to use CabinJS as it\n // will automatically add application and worker metadata\n // to your log output, and also masks sensitive data for you\n //
\n //\n logger: new Cabin(),\n\n //\n // NOTE: instead of passing this Array as an option\n // you can create a `./jobs/index.js` file, exporting\n // this exact same array as `module.exports = [ ... ]`\n // doing so will allow you to keep your job configuration and the jobs\n // themselves all in the same folder and very organized\n //\n // See the \"Job Options\" section below in this README\n // for the complete list of job options and configurations\n //\n jobs: [\n // runs `./jobs/foo.js` on start\n 'foo',\n\n // runs `./jobs/foo-bar.js` on start\n {\n name: 'foo-bar'\n },\n\n // runs `./jobs/some-other-path.js` on start\n {\n name: 'beep',\n path: path.join(__dirname, 'jobs', 'some-other-path')\n },\n\n // runs `./jobs/worker-1.js` on the last day of the month\n {\n name: 'worker-1',\n interval: 'on the last day of the month'\n },\n\n // runs `./jobs/worker-2.js` every other day\n {\n name: 'worker-2',\n interval: 'every 2 days'\n },\n\n // runs `./jobs/worker-3.js` at 10:15am and 5:15pm every day except on Tuesday\n {\n name: 'worker-3',\n interval: 'at 10:15 am also at 5:15pm except on Tuesday'\n },\n\n // runs `./jobs/worker-4.js` at 10:15am every weekday\n {\n name: 'worker-4',\n cron: '15 10 ? * *'\n },\n\n // runs `./jobs/worker-5.js` on after 10 minutes have elapsed\n {\n name: 'worker-5',\n timeout: '10m'\n },\n\n // runs `./jobs/worker-6.js` after 1 minute and every 5 minutes thereafter\n {\n name: 'worker-6',\n timeout: '1m',\n interval: '5m'\n // this is unnecessary but shows you can pass a Number (ms)\n // interval: ms('5m')\n },\n\n // runs `./jobs/worker-7.js` after 3 days and 4 hours\n {\n name: 'worker-7',\n // this example uses `human-interval` parsing\n timeout: '3 days and 4 hours'\n },\n\n // runs `./jobs/worker-8.js` at midnight (once)\n {\n name: 'worker-8',\n timeout: 'at 12:00 am'\n },\n\n // runs `./jobs/worker-9.js` every day at midnight\n {\n name: 'worker-9',\n interval: 'at 12:00 am'\n },\n\n // runs `./jobs/worker-10.js` at midnight on the 1st of every month\n {\n name: 'worker-10',\n cron: '0 0 1 * *'\n },\n\n // runs `./jobs/worker-11.js` at midnight on the last day of month\n {\n name: 'worker-11',\n cron: '0 0 L * *'\n },\n\n // runs `./jobs/worker-12.js` at a specific Date (e.g. in 3 days)\n {\n name: 'worker-12',\n // \n date: dayjs().add(3, 'days').toDate()\n // you can also use momentjs\n // \n // date: moment('1/1/20', 'M/D/YY').toDate()\n // you can pass Date instances (if it's in the past it will not get run)\n // date: new Date()\n },\n\n // runs `./jobs/worker-13.js` on start and every 2 minutes\n {\n name: 'worker-13',\n interval: '2m'\n },\n\n // runs `./jobs/worker-14.js` on start with custom `new Worker` options (see below)\n {\n name: 'worker-14',\n // \n worker: {\n workerData: {\n foo: 'bar',\n beep: 'boop'\n }\n }\n },\n\n // runs `./jobs/worker-15.js` **NOT** on start, but every 2 minutes\n {\n name: 'worker-15',\n timeout: false, // <-- specify `false` here to prevent default timeout (e.g. on start)\n interval: '2m'\n },\n\n // runs `./jobs/worker-16.js` on January 1st, 2022\n // and at midnight on the 1st of every month thereafter\n {\n name: 'worker-16',\n date: dayjs('1-1-2022', 'M-D-YYYY').toDate(),\n cron: '0 0 1 * *'\n }\n ]\n});\n\n// handle graceful reloads, pm2 support, and events like SIGHUP, SIGINT, etc.\nconst graceful = new Graceful({ cronJobss: [cronJobs] });\ngraceful.listen();\n\n// start all jobs (this is the equivalent of reloading a crontab):\ncronJobs.start();\n\n/*\n// start only a specific job:\ncronJobs.start('foo');\n\n// stop all jobs\ncronJobs.stop();\n\n// stop only a specific job:\ncronJobs.stop('beep');\n\n// run all jobs (this does not abide by timeout/interval/cron and spawns workers immediately)\ncronJobs.run();\n\n// run a specific job (...)\ncronJobs.run('beep');\n\n// add a job array after initialization:\ncronJobs.add(['boop']);\n// this must then be started using one of the above methods\n\n// add a job after initialization:\ncronJobs.add('boop');\n// this must then be started using one of the above methods\n\n// remove a job after initialization:\ncronJobs.remove('boop');\n*/\n```\n\n### Browser\n\n> **NOTE:** Browser support is currently unstable [until this GitHub issue](https://github.com/cronJobsjs/cronJobs/issues/27) is resolved. Contributions are welcome!\n\nIf you are using CronJobs in the browser, then please reference the [Web Workers API][web-workers-api] (since it does not use Node.js [worker threads][workers]). If the Web Workers API [is not yet available](https://caniuse.com/#feat=webworkers), then it will be [polyfilled][polyfill] accordingly.\n\n#### VanillaJS\n\nThis is the solution for you if you're just using `\n\n```\n\n#### Bundler\n\nAssuming you are using [browserify][], [webpack][], [rollup][], or another bundler, you can simply follow [Node](#node) usage above.\n\n\n## Node.js Email Queue Job Scheduling Example\n\nA very common use case for a Node.js job scheduler is the sending of emails.\n\nWe highly recommend you to use CronJobs in combination with the [email-templates](https://email-templates.js.org/) package (made by the same author). Not only does it let you easily manage email templates, but it also automatically opens email previews in your browser for you during local development (using [preview-email](https://github.com/forwardemail/preview-email)).\n\nYou will then create in your application a MongoDB \"email\" collection (or SQL table) with the following properties (or SQL columns):\n\n* `template` (String) - the name of the email template\n* `message` (Object) - a Nodemailer message object\n* `locals` (Object) - an Object of locals that are passed to the template for rendering\n\nHere are optional properties/columns that you may want to also add (you'll need to implement the logic yourself as the example provided below does not include it):\n\n* `send_at` (Date) - the Date you want to send an email (should default to current `Date.now()` when record is created, and can be overridden on a per job basis)\n* `sent_at` (Date) - the Date that the email actually got sent (set by your job in CronJobs - you would use this when querying for emails to send, and specifically exclude any emails that have a `sent_at` value sent in your query)\n* `response` (Object) - the mixed Object that is returned from Nodemailer sending the message (you should store this for historical data and so you can detect bounces)\n\nIn your application, you will then need to save a new record into the collection or table (where you want to trigger an email to be queued) with values for these properties.\n\nLastly, you will need to set up CronJobs to fetch from the email collection every minute (you can configure how frequent you wish, however you may want to implement locking, by setting a `is_locked` Boolean property, and subsequently unlocking any jobs locked more than X minutes ago – but **typically this is not needed** unless you are sending thousands of emails and have a slow SMTP transport).\n\n```js\nconst CronJobs = require('cronJobs');\nconst Graceful = require('@ladjs/graceful');\nconst Cabin = require('cabin');\n\n//\n// we recommend using Cabin as it is security-focused\n// and you can easily hook in Slack webhooks and more\n// \n//\nconst logger = new Cabin();\n\nconst cronJobs = new CronJobs({\n logger,\n jobs: [\n {\n // runs `./jobs/email.js` on start and every minute\n name: 'email',\n interval: '1m'\n }\n ]\n});\n```\n\n> Example contents of a file named `./jobs/email.js`:\n\n```js\nconst os = require('os');\nconst { parentPort } = require('worker_threads');\n\nconst Cabin = require('cabin');\nconst Email = require('email-templates');\nconst pMap = require('p-map');\n\n//\n// we recommend using Cabin as it is security-focused\n// and you can easily hook in Slack webhooks and more\n// \n//\nconst logger = new Cabin();\n\n//\n// we recommend using email-templates to\n// create, send, and manage your emails\n// \n//\nconst email = new Email({\n message: {\n // set a default from that will be set on all messages\n // (unless you specifically override it on an individual basis)\n from: 'elon@tesla.com'\n }\n});\n\n// store boolean if the job is cancelled\nlet isCancelled = false;\n\n// how many emails to send at once\nconst concurrency = os.cpus().length;\n\n// example database results\nconst results = [\n {\n template: 'welcome',\n message: {\n to: 'elon@spacex.com'\n },\n locals: {\n foo: 'bar',\n beep: 'boop'\n }\n }\n // ...\n];\n\nasync function mapper(result) {\n // return early if the job was already cancelled\n if (isCancelled) return;\n try {\n const response = await email.send(result);\n logger.info('sent email', { response });\n // here is where you would write to the database that it was sent\n return response;\n } catch (err) {\n // catch the error so if one email fails they all don't fail\n logger.error(err);\n }\n}\n\n// handle cancellation (this is a very simple example)\nif (parentPort)\n parentPort.once('message', message => {\n //\n // TODO: once we can manipulate concurrency option to p-map\n // we could make it `Number.MAX_VALUE` here to speed cancellation up\n // \n //\n if (message === 'cancel') isCancelled = true;\n });\n\n(async () => {\n // query database results for emails not sent\n // and iterate over them with concurrency\n await pMap(results, mapper, { concurrency });\n\n // signal to parent that the job is done\n if (parentPort) parentPort.postMessage('done');\n else process.exit(0);\n})();\n```\n\n> Example contents of a file named `./emails/welcome/html.pug`:\n\n```pug\np Welcome to Tesla\nul\n li\n strong Foo value:\n = ' '\n = foo\n li\n strong Beep value:\n = ' '\n = beep\n```\n\n> Example contents of a file named `./emails/welcome/subject.pug`:\n\n```pug\n= 'Welcome to Tesla'\n```\n\n**NOTE:** We have provided a complete demo example using Express at .\n\n\n## Instance Options\n\nHere is the full list of options and their defaults. See [index.js](index.js) for more insight if necessary.\n\n| Property | Type | Default Value | Description | |\n| ---------------------- | -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |\n| `logger` | Object | `console` | This is the default logger. **We recommend using [Cabin][cabin]** instead of using `console` as your default logger. | |\n| `root` | String | `path.resolve('jobs')` | Set this value to `false` to prevent requiring a root directory of jobs (e.g. if your jobs are not all in one directory). | |\n| `timeout` | Number | `0` | Default timeout for jobs (e.g. a value of `0` means that jobs will start on boot by default unless a job has a property of `timeout` or `interval` defined. Set this to `false` if you do not wish for a default value to be set for jobs. **This value does not apply to jobs with a property of `date`.** | |\n| `interval` | Number | `0` | Default interval for jobs (e.g. a value of `0` means that there is no interval, and a value greater than zero indicates a default interval will be set with this value). **This value does not apply to jobs with a property of `cron`**. | |\n| `jobs` | Array | `[]` | Defaults to an empty Array, but if the `root` directory has a `index.js` file, then it will be used. This allows you to keep your jobs and job definition index in the same place. See [Job Options](#job-options) below, and [Usage and Examples](#usage-and-examples) above for more insight. | |\n| `hasSeconds` | Boolean | `false` | This value is passed to `later` for parsing jobs, and can be overridden on a per job basis. See [later cron parsing](https://breejs.github.io/later/parsers.html#cron) documentation for more insight. Note that setting this to `true` will automatically set `cronValidate` defaults to have `{ preset: 'default', override: { useSeconds: true } }` | |\n| `cronValidate` | Object | `{}` | This value is passed to `cron-validate` for validation of cron expressions. See the [cron-validate](https://github.com/Airfooox/cron-validate) documentation for more insight. | |\n| `closeWorkerAfterMs` | Number | `0` | If you set a value greater than `0` here, then it will terminate workers after this specified time (in milliseconds). **As of v6.0.0, workers now terminate after they have been signaled as \"online\" (as opposed to previous versions which did not take this into account and started the timer when jobs were initially \"run\").** By default there is no termination done, and jobs can run for infinite periods of time. | |\n| `defaultExtension` | String | `js` | This value can either be `js` or `mjs`. The default is `js`, and is the default extension added to jobs that are simply defined with a name and without a path. For example, if you define a job `test`, then it will look for `/path/to/root/test.js` as the file used for workers. | |\n| `worker` | Object | `{}` | These are default options to pass when creating a `new Worker` instance. See the [Worker class](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) documentation for more insight. | |\n| `outputWorkerMetadata` | Boolean | `false` | By default worker metadata is not passed to the second Object argument of `logger`. However if you set this to `true`, then `logger` will be invoked internally with two arguments (e.g. `logger.info('...', { worker: ... })`). This `worker` property contains `isMainThread` (Boolean), `resourceLimits` (Object), and `threadId` (String) properties; all of which correspond to [Workers][] metadata. This can be overridden on a per job basis. | |\n| `errorHandler` | Function | `null` | Set this function to receive a callback when an error is encountered during worker execution (e.g. throws an exception) or when it exits with non-zero code (e.g. `process.exit(1)`). The callback receives two parameters `error` and `workerMetadata`. Important note, when this callback is present default error logging will not be executed. | |\n| `workerMessageHandler` | Function | `null` | Set this function to receive a callback when a worker sends a message through [parentPort.postMessage](https://nodejs.org/docs/latest-v14.x/api/worker_threads.html#worker_threads_port_postmessage_value_transferlist). The callback receives at least two parameters `name` (of the worker) and `message` (coming from `postMessage`), if `outputWorkerMetadata` is enabled additional metadata will be sent to this handler. | |\n\n\n## Job Options\n\nSee [Interval, Timeout, Date, and Cron Validate](#interval-timeout-date-and-cron-validation) below for more insight besides this table:\n\n| Property | Type | Description |\n| ---------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | String | The name of the job. This should match the base file path (e.g. `foo` if `foo.js` is located at `/path/to/jobs/foo.js`) unless `path` option is specified. A value of `index`, `index.js`, and `index.mjs` are reserved values and cannot be used here. |\n| `path` | String | The path of the job or function used for spawning a new [Worker][workers] with. If not specified, then it defaults to the value for `name` plus the default file extension specified under [Instance Options](#instance-options). |\n| `timeout` | Number, Object, String, or Boolean | Sets the duration in milliseconds before the job starts (it overrides the default inherited `timeout` as set in [Instance Options](#instance-options). A value of `0` indicates it will start immediately. This value can be a Number, String, or a Boolean of `false` (which indicates it will NOT inherit the default `timeout` from [Instance Options](#instance-options)). See [Job Interval and Timeout Values](#job-interval-and-timeout-values) below for more insight into how this value is parsed. |\n| `interval` | Number, Object, or String | Sets the duration in milliseconds for the job to repeat itself, otherwise known as its interval (it overrides the default inherited `interval` as set in [Instance Options](#instance-options)). A value of `0` indicates it will not repeat and there will be no interval. If the value is greater than `0` then this value will be used as the interval. See [Job Interval and Timeout Values](#job-interval-and-timeout-values) below for more insight into how this value is parsed. |\n| `date` | Date | This must be a valid JavaScript Date (we use `instance of Date` for comparison). If this value is in the past, then it is not run when jobs are started (or run manually). We recommend using [dayjs][] for creating this date, and then formatting it using the `toDate()` method (e.g. `dayjs().add('3, 'days').toDate()`). You could also use [moment][] or any other JavaScript date library, as long as you convert the value to a Date instance here. |\n| `cron` | String | A cron expression to use as the job's interval, which is validated against [cron-validate][] and parsed by [later][]. |\n| `hasSeconds` | Boolean | Overrides the [Instance Options](#instance-options) `hasSeconds` property if set. Note that setting this to `true` will automatically set `cronValidate` defaults to have `{ preset: 'default', override: { useSeconds: true } }` |\n| `cronValidate` | Object | Overrides the [Instance Options](#instance-options) `cronValidate` property if set. |\n| `closeWorkerAfterMs` | Number | Overrides the [Instance Options](#instance-options) `closeWorkerAfterMs` property if set. |\n| `worker` | Object | Overrides the [Instance Options](#instance-options) `worker` property if set. |\n| `outputWorkerMetadata` | Boolean | Overrides the [Instance Options](#instance-options) `outputWorkerMetadata` property if set. |\n\n\n## Job Interval and Timeout Values\n\nThese values can include Number, Object, and String variable types:\n\n* Number values indicates the number of milliseconds for the timeout or interval\n* Object values must be a [later][] schedule object value (e.g. `later.parse.cron('15 10 * * ? *'))`)\n* String values can be either a [later][], [human-interval][], or [ms][] String values (e.g. [later][] supports Strings such as `every 5 mins`, [human-interval][] supports Strings such as `3 days and 4 hours`, and [ms][] supports Strings such as `4h` for four hours)\n\n\n## Listening for events\n\nCronJobs extends from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) and emits two events:\n\n* `worker created` with an argument of `name`\n* `worker deleted` with an argument of `name`\n\nIf you'd like to know when your workers are created (or deleted), you can do so through this example:\n\n```js\ncronJobs.on('worker created', (name) => {\n console.log('worker created', name);\n console.log(cronJobs.workers[name]);\n});\n\ncronJobs.on('worker deleted', (name) => {\n console.log('worker deleted', name);\n console.log(typeof cronJobs.workers[name] === 'undefined');\n});\n```\n\n\n## Custom error handling\n\nIf you'd like to override default behavior for worker error handling, provide a callback function as `errorHandler` parameter when creating a CronJobs instance.\n\nAn example use-case. If you want to call an external service to record an error (like Honeybadger, Sentry, etc.) along with logging the error internally. You can do so with:\n\n```js\nconst logger = ('../path/to/logger');\nconst errorService = ('../path/to/error-service');\n\nnew JobWorkerManager({\n jobs: [\n {\n name: 'job that sometimes throws errors',\n path: jobFunction\n }\n ],\n errorHandler: (error, workerMetadata) => {\n // workerMetadata will be populated with extended worker information only if\n // CronJobs instance is initialized with parameter `workerMetadata: true`\n if (workerMetadata.threadId) {\n logger.info(`There was an error while running a worker ${workerMetadata.name} with thread ID: ${workerMetadata.threadId}`)\n } else {\n logger.info(`There was an error while running a worker ${workerMetadata.name}`)\n }\n\n logger.error(error);\n errorService.captureException(error);\n }\n});\n```\n\n\n## Cancellation, Retries, Stalled Jobs, and Graceful Reloading\n\nWe recommend that you listen for \"cancel\" event in your worker paths. Doing so will allow you to handle graceful cancellation of jobs. For example, you could use [p-cancelable][]\n\nHere's a quick example of how to do that (e.g. `./jobs/some-worker.js`):\n\n```js\n// \nconst { parentPort } = require('worker_threads');\n\n// ...\n\nfunction cancel() {\n // do cleanup here\n // (if you're using @ladjs/graceful, the max time this can run by default is 5s)\n\n // send a message to the parent that we're ready to terminate\n // (you could do `process.exit(0)` or `process.exit(1)` instead if desired\n // but this is a bit of a cleaner approach for worker termination\n if (parentPort) parentPort.postMessage('cancelled');\n else process.exit(0);\n}\n\nif (parentPort)\n parentPort.once('message', message => {\n if (message === 'cancel') return cancel();\n });\n```\n\nIf you'd like jobs to retry, simply wrap your usage of promises with [p-retry][].\n\nWe leave it up to you to have as much fine-grained control as you wish.\n\nSee [@ladjs/graceful][lad-graceful] for more insight into how this package works.\n\n\n## Interval, Timeout, Date, and Cron Validation\n\nIf you need help writing cron expressions, you can reference [crontab.guru](https://crontab.guru/).\n\nWe support [later][], [human-interval][], or [ms][] String values for both `timeout` and `interval`.\n\nIf you pass a `cron` property, then it is validated against [cron-validate][].\n\nYou can pass a Date as the `date` property, but you cannot combine both `date` and `timeout`.\n\nIf you do pass a Date, then it is only run if it is in the future.\n\nSee [Job Interval and Timeout Values](#job-interval-and-timeout-values) above for more insight.\n\n\n## Writing jobs with Promises and async-await\n\nIf jobs are running with Node pre-[v14.8.0](https://nodejs.org/en/blog/release/v14.8.0/), which [enables top-level async-await](https://github.com/nodejs/node/commit/62bb2e757f) support, here is the working alternative:\n\n```js\nconst { parentPort } = require('worker_threads');\n\nconst delay = require('delay');\nconst ms = require('ms');\n\n(async () => {\n // wait for a promise to finish\n await delay(ms('10s'));\n\n // signal to parent that the job is done\n if (parentPort) parentPort.postMessage('done');\n else process.exit(0);\n})();\n```\n\n\n## Callbacks, Done, and Completion States\n\nTo close out the worker and signal that it is done, you can simply `parentPort.postMessage('done');` and/or `process.exit(0)`.\n\nWhile writing your jobs (which will run in [worker][workers] threads), you should do one of the following:\n\n* Signal to the main thread that the process has completed by sending a \"done\" message (per the example above in [Writing jobs with Promises and async-await](#writing-jobs-with-promises-and-async-await))\n* Exit the process if there is NOT an error with code `0` (e.g. `process.exit(0);`)\n* Throw an error if an error occurs (this will bubble up to the worker event error listener and terminate it)\n* Exit the process if there IS an error with code `1` (e.g. `process.exit(1)`)\n\n\n## Long-running jobs\n\nIf a job is already running, a new worker thread will not be spawned, instead `logger.error` will be invoked with an error message (no error will be thrown, don't worry). This is to prevent bad practices from being used. If you need something to be run more than one time, then make the job itself run the task multiple times. This approach gives you more fine-grained control.\n\nBy default, workers run indefinitely and are not closed until they exit (e.g. via `process.exit(0)` or `process.exit(1)`, OR send to the parent port a \"close\" message, which will subsequently call `worker.close()` to close the worker thread.\n\nIf you wish to specify a maximum time (in milliseconds) that a worker can run, then pass `closeWorkerAfterMs` (Number) either as a default option when creating a `new CronJobs()` instance (e.g. `new CronJobs({ closeWorkerAfterMs: ms('10s') })`) or on a per-job configuration, e.g. `{ name: 'beep', closeWorkerAfterMs: ms('5m') }`.\n\nAs of v6.0.0 when you pass `closeWorkerAfterMs`, the timer will start once the worker is signaled as \"online\" (as opposed to previous versions which did not take this into account).\n\n\n## Complex timeouts and intervals\n\nSince we use [later][], you can pass an instance of `later.parse.recur`, `later.parse.cron`, or `later.parse.text` as the `timeout` or `interval` property values (e.g. if you need to construct something manually).\n\nYou can also use [dayjs][] to construct dates (e.g. from now or a certain date) to millisecond differences using `dayjs().diff(new Date(), 'milliseconds')`. You would then pass that returned Number value as `timeout` or `interval` as needed.\n\n\n## Custom Worker Options\n\nYou can pass a default worker configuration object as `new CronJobs({ worker: { ... } });`.\n\nThese options are passed to the `options` argument when we internally invoke `new Worker(path, options)`.\n\nAdditionally, you can pass custom worker options on a per-job basis through a `worker` property Object on the job definition.\n\nSee [complete documentation](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for options (but you usually don't have to modify these).\n\n\n## Using functions for jobs\n\nIt is highly recommended to use files instead of functions. However, sometimes it is necessary to use functions.\n\nYou can pass a function to be run as a job:\n\n```js\nnew JobWorkerManager({jobs: [someFunction]});\n```\n\n(or)\n\n```js\nnew JobWorkerManager({\n jobs: [\n {\n name: 'job with function',\n path: someFunction\n }\n ]\n});\n```\n\nThe function will be run as if it's in its own file, therefore no variables or dependencies will be shared from the local context by default.\n\nYou should be able to pass data via `worker.workerData` (see [Custom Worker Options](#custom-worker-options)).\n\nNote that you cannot pass a built-in nor bound function.\n\n\n## Concurrency\n\nWe recommend using the following packages in your workers for handling concurrency:\n\n* \n* \n* \n* \n\n\n\n[ms]: https://github.com/vercel/ms\n\n[human-interval]: https://github.com/agenda/human-interval\n\n[npm]: https://www.npmjs.com/\n\n[yarn]: https://yarnpkg.com/\n\n[workers]: https://nodejs.org/api/worker_threads.html\n\n[lad]: https://lad.js.org\n\n[p-retry]: https://github.com/sindresorhus/p-retry\n\n[p-cancelable]: https://github.com/sindresorhus/p-cancelable\n\n[later]: https://breejs.github.io/later/parsers.html\n\n[cron-validate]: https://github.com/Airfooox/cron-validate\n\n[forward-email]: https://github.com/forwardemail/forwardemail.net\n\n[dayjs]: https://github.com/iamkun/dayjs\n\n[sfn-scheduler]: https://github.com/hyurl/sfn-scheduler\n\n[spam-scanner]: https://spamscanner.net\n\n[agenda]: https://github.com/agenda/agenda\n\n[node-cron]: https://github.com/node-cron/node-cron\n\n[kue]: https://github.com/Automattic/kue\n\n[@ladjs/bull]: https://github.com/ladjs/bull\n\n[bull]: https://github.com/OptimalBits/bull\n\n[redis]: https://redis.io/\n\n[mongodb]: https://www.mongodb.com/\n\n[lad-graceful]: https://github.com/ladjs/graceful\n\n[cabin]: https://cabinjs.com\n\n[moment]: https://momentjs.com\n\n[bthreads]: https://github.com/chjj/bthreads\n\n[web-workers-api]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers\n\n[polyfill]: https://github.com/chjj/bthreads/blob/master/lib/browser/polyfill.js\n\n[browserify]: https://github.com/browserify/browserify\n\n[webpack]: https://github.com/webpack/webpack\n\n[rollup]: https://github.com/rollup/rollup\n","readmeFilename":"README.md","description":"
Cron job scheduler for
Node.js and JavaScript with
cron,