{"id":16223683,"url":"https://github.com/lykmapipo/kue-scheduler","last_synced_at":"2025-04-04T15:08:47.651Z","repository":{"id":30269199,"uuid":"33820643","full_name":"lykmapipo/kue-scheduler","owner":"lykmapipo","description":"A job scheduler utility for kue, backed by redis and built for node.js","archived":false,"fork":false,"pushed_at":"2022-12-09T06:00:19.000Z","size":1634,"stargazers_count":245,"open_issues_count":57,"forks_count":47,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-26T17:53:16.582Z","etag":null,"topics":["every","kue","nodejs","now","redis","scheduler"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lykmapipo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-12T14:45:41.000Z","updated_at":"2025-01-20T20:52:17.000Z","dependencies_parsed_at":"2023-01-14T16:39:24.642Z","dependency_job_id":null,"html_url":"https://github.com/lykmapipo/kue-scheduler","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lykmapipo%2Fkue-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lykmapipo%2Fkue-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lykmapipo%2Fkue-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lykmapipo%2Fkue-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lykmapipo","download_url":"https://codeload.github.com/lykmapipo/kue-scheduler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198461,"owners_count":20900080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["every","kue","nodejs","now","redis","scheduler"],"created_at":"2024-10-10T12:19:44.404Z","updated_at":"2025-04-04T15:08:47.629Z","avatar_url":"https://github.com/lykmapipo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kue-scheduler\n\n[![Build Status](https://travis-ci.org/lykmapipo/kue-scheduler.svg?branch=master)](https://travis-ci.org/lykmapipo/kue-scheduler)\n[![Dependency Status](https://img.shields.io/david/lykmapipo/kue-scheduler.svg?style=flat)](https://david-dm.org/lykmapipo/kue-scheduler)\n[![npm version](https://badge.fury.io/js/kue-scheduler.svg)](https://badge.fury.io/js/kue-scheduler)\n\nA job scheduler utility for [kue](https://github.com/Automattic/kue), backed by [redis](http://redis.io) and built for [node.js](http://nodejs.org) with support of schedules restore on system restart.\n\nScheduling API is heavily inspired and borrowed from [agenda](https://github.com/rschmukler/agenda) and others.\n\n*Note!: expiry key notification are now enabled by default, if provided kue options has a permission to do so unless explicit disabled by passing `skipConfig` option when creating `kue` instance*\n\n*Note!: kue-scheduler v0.6.0 is a refactored version of previous kue-scheduler to allow redis data structure and schedule queue best practice. API is the same but some of internal working may not work as previous ones*\n\n## Requirements\n- [NodeJS v13.14+](https://nodejs.org)\n- [Redis v2.8+](https://redis.io/)\n- [kue 0.10.5+](https://github.com/Automattic/kue)\n- If `kue-scheduler` failed to enable keyspace notification(s) automatic, then you have to enable them using `redis-cli` \n```sh\n$ redis-cli config set notify-keyspace-events Ex\n```\n\n\n## Installation\n```\n$ npm install --save kue kue-scheduler\n```\n\n## Usage\n\n\n### Schedule a non unique job to run every after specified time interval\nUse this if you want to maintain different(multiple) job instances on every run\n\nExample `schedule a job to run every two seconds from now`\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('every', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run every 2 seconds\nQueue.every('2 seconds', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('every', function(job, done) {\n    ...\n    done();\n});\n```\n\n### Schedule a unique job to run every after specified time interval\nUse this if you want to maintain a single job instance on every run.\n\nExample `schedule a job to run every two seconds from now`\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('unique_every', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal')\n            .unique('unique_every');\n\n//schedule it to run every 2 seconds\nQueue.every('2 seconds', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('unique_every', function(job, done) {\n    ...\n    done();\n});\n```\n\n### Schedule a unique job to run every after specified time interval, using cron and timezone\n\n\nExample `schedule a job to run every 10 seconds from now`\nsee http://momentjs.com/timezone/ for timezones names.\n\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('unique_every', { timezone: 'Europe/Amsterdam' })\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal')\n            .unique('unique_every');\n\n//schedule it to run every 10 seconds\nQueue.every('*/10 * * * * *', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('unique_every', function(job, done) {\n    ...\n    done();\n});\n```\n\n### Schedule a non unique job to run only once after specified interval elapsed\nUse this if you want to maintain different(multiple) job instances on every run\n\nExample `schedule a job to run only once two seconds from now`\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('schedule', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run once 2 seconds from now\nQueue.schedule('2 seconds from now', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('schedule', function(job, done) {\n    ...\n    done();\n});\n```\n\n### Schedule a unique job to run only once after specified interval elapsed\nUse this if you want to maintain a single job instance on every run.\n\nExample `schedule a job to run only once two seconds from now`\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('unique_schedule', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal')\n            .unique('unique_schedule');\n\n//schedule it to run once 2 seconds from now\nQueue.schedule('2 seconds from now', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('unique_schedule', function(job, done) {\n    ...\n    done();\n});\n```\n\n\n### Schedule a job to run now\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('now', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run now\nQueue.now(job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('now', function(job, done) {\n    ...\n    done();\n});\n```\n\n## Options\n`kue-scheduler` support all `kue` options with addition of the following\n\n- `restore:boolen` - tells `kue-scheduler` to try to restore schedules in case of restarts or other causes. By default its not enable. When enable use `restore error` and `restore success` queue events to communicate with the scheduler.\n\nExample\n```js\nvar options = {\n        prefix: 'w',\n        skipConfig: false,\n        redis: {\n          port: 6379,\n          host: '127.0.0.1',\n          db: 2\n        },\n        restore: true\n      };\n...\n\nQueue = kue.createQueue(options);\n\n```\n\n- `worker:boolen` - tells `kue-scheduler` to listen and process job. Default to `true`. If set to `false` you need another `kue-scheduler` instance to process the scheduled jobs from other process\n\nExample\n```js\n//create scheduler instance(process)\nvar scheduler = kue.createQueue({\n    restore:true,\n    worker:false\n});\n\n//in separate process create an instance that will process works\nvar worker = kue.createQueue({\n    restore:true,\n    worker:true\n});\nworker.process(...);\n\n...\n\n```\n\n- `skipConfig:boolen` - tells `kue-scheduler` to skip enabling enabling key expiry notification.\nExample\n```js\n//create scheduler instance(process) with skipConfig\nvar scheduler = kue.createQueue({\n    skipConfig:true\n});\n```\n*Note! if you experience the following error: `ReplyError: ERR unknown command 'config'`, which will happen if you're using a redis instance with the config command disabled (AWS Elasticache for example) you must call createQueue with the `skipConfig` option and manually ensure that the `notify-keyspace-events` configuration key is set to `Ex`.*\n\n## API\n\n### `clear(done)`\nClear all `kue` and `kue-scheduler` redis data. Clean up if performed atomically with fail all or success all guarantee.\n\nExample\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//perform cleanup\nQueue.clear(function(error,response){\n    ...\n});\n```\n\n### `enableExpiryNotifications()`\nEnable `redis key expiry notifications`.\n\nExample\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//enable expiry key notifications\nQueue.enableExpiryNotifications();\n```\n\n### `every(interval, job, [done])`\nRuns a given `job instance` every after a given `interval`. If `unique key` is provided only single instance job will exists otherwise on every run new job instance will be used.\n\n`interval` can either be a [human-interval](https://github.com/rschmukler/human-interval) `String` format or a [cron](https://github.com/ncb000gt/node-cron) `String` format.\n\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('every', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run every 2 seconds\nQueue.every('2 seconds', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('every', function(job, done) {\n    ...\n    done();\n});\n```\n\n\n### `schedule(when, job)`\nSchedules a given `job instance` to run once at a given time. `when` can either be a `Date instance` or a [date.js](https://github.com/matthewmueller/date) `String` such as `tomorrow at 5pm`. If `unique key` is provided only single instance job will exists otherwise on every run new job istance will be used.\n\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('schedule', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run once 2 seconds from now\nQueue.schedule('2 seconds from now', job);\n\n\n//somewhere process your scheduled jobs\nQueue.process('schedule', function(job, done) {\n    ...\n    done();\n});\n```\n\n### `now(job)`\nSchedules a given `job instance` to run once immediately.\n\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//create a job instance\nvar job = Queue\n            .createJob('now', data)\n            .attempts(3)\n            .backoff(backoff)\n            .priority('normal');\n\n//schedule it to run now\nQueue.now(job);\n\n//somewhere process your scheduled jobs\nQueue.process('now', function(job, done) {\n    ...\n    done();\n});\n```\n\n### `remove([id|job|criteria], done)`\nRemove either scheduled job with its expiry key and schedule data or non-scheduled job. A criteria may contain `jobExpiryKey`, `jobDataKey` or `unique identifier` of the job in case of `unique jobs`\n\n#### Example: Remove `every` schedule job\n```js\n//using instance\nQueue.remove(`\u003cjobInstance\u003e`, function(error, response) {\n    ...\n});\n\n//using id\nQueue.remove(`\u003cjobId\u003e`, function(error, response) {\n    ...\n});\n\n//using criteria\nQueue.remove({\n    unique: 'every_mail'\n}, function(error, response) {\n    ...\n});\n```\n\n#### Example: Remove `scheduled or now` job\n```js\n//using instance\nQueue.remove(`\u003cjobInstance\u003e`, function(error, response) {\n    ...\n});\n\n//using id\nQueue.remove(`\u003cjobId\u003e`, function(error, response) {\n    ...\n});\n\n//using criteria\nQueue.remove({\n    unique: 'every_mail'\n}, function(error, response) {\n    ...\n});\n```\n\n### `restore(done)`\nEnforce `kue-scheduler` to restore schedules in cases that may cause your application to miss redis key expiry events. You may enable `restore` using options but in some scenario you may invoke `restore` by yourself.\n\nExample\n```js\nvar kue = require('kue-scheduler');\nvar Queue = kue.createQueue();\n\n//perform cleanup\nQueue.restore(function(error, schedules){\n    ...\n\n});\n```\n\n\n## Events\nCurrently the only way to interact with `kue-scheduler` is through its events. `kue-scheduler` fires `schedule error`, `schedule success`, `already scheduled`,`lock error`, `unlock error`, `restore success`, `restore error` and `scheduler unknown job expiry key` events.\n\n### `schedule error`\nUse it to interact with `kue-scheduler` to get notified when an error occur.\n\n```js\n//listen on scheduler errors\nQueue.on('schedule error', function(error) {\n    ...\n});\n\nvar job = Queue\n    .createJob('now', data)\n    .attempts(3)\n    .backoff(backoff)\n    .priority('normal');\n\nQueue.now(job);\n```\n\n### `schedule success`\nUse it to interact with `kue-scheduler` to obtained instance of current scheduled job. \n\n*Note: Use this event to attach instance level job events* \n\n```js\n//listen on success scheduling\nQueue.on('schedule success', function(job) {\n    ...\n});\n\nvar job = Queue\n    .createJob('now', data)\n    .attempts(3)\n    .backoff(backoff)\n    .priority('normal');\n\nQueue.now(job);\n```\n\n### `already scheduled`\nUse it to interact with `kue-scheduler` to be notified if the current instance of job is unique and already schedule to run.\n\n*Note: Use this event to attach instance level job events* \n\n```js\n//listen on already scheduled jobs\nQueue.on('already scheduled', function(job) {\n    ...\n});\n\nvar job = Queue\n    .createJob('now', data)\n    .attempts(3)\n    .backoff(backoff)\n    .priority('normal');\n\nQueue.now(job);\n```\n\n### `lock error`\nUse it to interact with `kue-scheduler` to get notified when a [lock](https://github.com/mike-marcacci/node-redlock) error occured.\n\n```js\n//listen on scheduler errors\nQueue.on('lock error', function(error) {\n    ...\n});\n\nvar job = Queue\n    .createJob('now', data)\n    .attempts(3)\n    .backoff(backoff)\n    .priority('normal');\n\nQueue.now(job);\n```\n\n### `unlock error`\nUse it to interact with `kue-scheduler` to get notified when [unlock](https://github.com/mike-marcacci/node-redlock) error occured.\n\n```js\n//listen on scheduler errors\nQueue.on('unlock error', function(error) {\n    ...\n});\n\nvar job = Queue\n    .createJob('now', data)\n    .attempts(3)\n    .backoff(backoff)\n    .priority('normal');\n\nQueue.now(job);\n```\n\n### `scheduler unknown job expiry key`\nFired when `kue-scheduler` receive unknown key event from redis. Use it to be notified on unknown key(s) events.\n\n```js\nQueue\n    .on('scheduler unknown job expiry key', function(message) {\n\n        expect(Queue._isJobExpiryKey(message)).to.be.false;\n\n    });\n```\n\n### `restore success`\nFired when `kue-scheduler` successfully restore previous schedules.\n\n```js\nQueue\n    .on('restore success', function() {\n    \n    ...\n\n    });\n```\n\n### `restore error`\nFired when `kue-scheduler` failed to restore previous schedules.\n\n```js\nQueue\n    .on('restore error', function(error) {\n    \n    ...\n\n    });\n```\n\n## Testing\n* Clone this repository\n\n* Install all development dependencies\n```sh\n$ npm install\n```\n\n* Then run test\n```sh\n$ npm test\n```\n\n## Contribute\nIt will be nice, if you open an issue first so that we can know what is going on, then, fork this repo and push in your ideas. Do not forget to add a bit of test(s) of what value you adding.\n\n## License \n\n(The MIT License)\n\nCopyright (c) 2011 lykmapipo \u0026\u0026 Contributors\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flykmapipo%2Fkue-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flykmapipo%2Fkue-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flykmapipo%2Fkue-scheduler/lists"}