{"id":19501176,"url":"https://github.com/gitbookio/node-tasqueue","last_synced_at":"2026-03-06T22:04:50.053Z","repository":{"id":65514792,"uuid":"52262971","full_name":"GitbookIO/node-tasqueue","owner":"GitbookIO","description":"Node.js job/task-queue library using disque","archived":false,"fork":false,"pushed_at":"2018-07-19T08:17:53.000Z","size":80,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-04-25T19:20:48.839Z","etag":null,"topics":["disque","nodejs","queueing"],"latest_commit_sha":null,"homepage":null,"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/GitbookIO.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2016-02-22T09:41:06.000Z","updated_at":"2022-09-12T07:30:55.000Z","dependencies_parsed_at":"2023-01-26T21:05:16.761Z","dependency_job_id":null,"html_url":"https://github.com/GitbookIO/node-tasqueue","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fnode-tasqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fnode-tasqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fnode-tasqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fnode-tasqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GitbookIO","download_url":"https://codeload.github.com/GitbookIO/node-tasqueue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250912660,"owners_count":21506865,"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":["disque","nodejs","queueing"],"created_at":"2024-11-10T22:11:45.347Z","updated_at":"2026-03-06T22:04:45.003Z","avatar_url":"https://github.com/GitbookIO.png","language":"JavaScript","readme":"# tasqueue\n\n[![npm version](https://badge.fury.io/js/tasqueue.svg)](https://badge.fury.io/js/tasqueue)\n[![Build Status](https://travis-ci.org/GitbookIO/node-tasqueue.svg?branch=master)](https://travis-ci.org/GitbookIO/node-tasqueue)\n\nPromise-based Node.js job/task-queue library using disque.\n\n### How it works\n\n1. Create a client\n2. Register new job types handlers\n3. Push jobs\n\nTasqueue is a job/task-queue library based on [disque](https://www.github.com/antirez/disque) and using [Q](https://github.com/kriskowal/q). It aims to be simple, fast and to handle a high charge.\n\nMonitoring functions of Tasqueue can only be entrusted when using a single-node instance of disque.\n\n### Create a client\n```js\nvar Tasqueue = require('tasqueue');\n\n// Default options\nvar opts = {\n    authPass:      null,            // AUTH password for disque-server\n    host:          'localhost',     // disque-server host\n    port:          7711,            // disque-server port\n    pollDelay:     1000 * 15,       // Polling delay in ms when no workers are available\n    jobTimeout:    1000 * 60 * 60,  // Timeout in ms before a job is considered as failed\n    failedTTL:     60 * 60 * 24,    // Failed jobs TTL in sec\n    completedTTL:  60 * 60 * 24,    // Completed jobs TTL in sec\n    queuedTTL:     60 * 60 * 24,    // Queued jobs TTL in sec\n    activeTTL:     60 * 60 * 1,     // Active job TTL in sec\n    maxAttempts:   60,              // Max reconnection attempts\n    retryMaxDelay: 1000 * 60        // Prevent exponential reconnection delay\n};\n\nvar tasqueue = new Tasqueue(opts);\n```\n\n## Queue API\n\n### `tasqueue.init()`\n_**Async**_:\nInitialize the client.\n\n###### Example\n```js\ntasqueue.init()\n.then(function() {\n    // Start working\n}, function(err) {\n    // Connection to disque-server failed\n});\n```\n\n### `tasqueue.shutdown(timeoutMs, callback)`\n_**Async**_:\nEnd the client.\n\n###### Example\n```js\ntasqueue.init()\n.then(function() {\n    // ...\n    tasqueue.shutdown(1000, function() {\n        console.log('Tasqueue was shut down after at most 1000 ms.');\n    });\n});\n```\n\n### `tasqueue.poll()`\nStart polling and jobs execution. This function should be run only once.\n\n###### Example\n```js\ntasqueue.init()\n.then(function() {\n    tasqueue.poll();\n});\n```\n\n### `tasqueue.registerHandler(handler)`\nRegister a job handler. `handler` should have the following properties:\n\n```js\nvar handler = {\n  type: 'jobType', // {String}  will be used as the queue name\n  concurrency: 5,  // {Integer} max number of concurrent workers for this type, default = 1\n  maxAttempts: 5,  // {Integer} max number of retry for this job type, default = 1\n  exec: function(body) {\n    // do whatever using the body passed for this job\n  }\n};\n```\n\n### `tasqueue.listHandlers()`\nList of registered handlers types as an array.\n\n###### Example\n```js\nvar handler1 = { type: 'type:1', ... };\nvar handler2 = { type: 'type:2', ... };\n\ntasqueue.registerHandler(handler1);\ntasqueue.registerHandler(handler2);\nvar registeredHandlers = tasqueue.listHandlers();\n// registeredHandlers equals ['type:1', 'type:2']\n```\n\n### `tasqueue.pushJob(jobType, body)`\n_**Async**_:\nPush a new job that will be processed by the corresponding `jobType` handler. The worker will call the handler's `exec` function with `body` used as its argument.\n\nWhen successful, returns the added job id.\n\n###### Example\n```js\nvar handler1 = {\n    type: 'type:1',\n    exec: function(body) {\n        console.log('hello '+body.name);\n    }\n};\n\ntasqueue.pushJob('type:1', { name: 'Johan' })\n.then(function(jobId) {\n    // jobId will be a disque id\n});\n\n// After some time...\n// Logs 'hello Johan'\n```\n\n### `tasqueue.getJob(id)`\n_**Async**_:\nReturns a Job object that can be easily manipulated. You can find the API for Jobs a bit below.\n\nThe promise is rejected if the queried job doesn't exist.\n\n###### Example\n```js\ntasqueue.getJob('someDisqueId')\n.then(function(job) {\n    console.log(job.details());\n});\n```\n\n### Count jobs\n_**Async**_:\nReturns the count of jobs by state.\n\n#### `tasqueue.count(state)`\n`state` must be one of `['active', 'queued', 'completed', 'failed']`.\n#### `tasqueue.countActive()`\n#### `tasqueue.countQueued()`\n#### `tasqueue.countCompleted()`\n#### `tasqueue.countFailed()`\n\n### List jobs\n_**Async**_:\nReturns the list of jobs for each state and cursors to paginate through the jobs.\n\n###### Example\n```js\nvar opts = {\n    start: 10,  // Start/skip cursor\n    limit: 10   // Number of jobs to return\n};\n\ntasqueue.listActive(opts)\n.then(function(res) {\n    // res looks like\n    {\n        prev: 0,       // Cursor to get the previous 10 jobs or null\n        next: null,    // Cursor to get the next 10 jobs or null\n        list: [ ... ]  // List of Jobs objects\n    }\n});\n```\n\n#### `tasqueue.list(state)`\n`state` must be one of `['active', 'queued', 'completed', 'failed']`.\n#### `tasqueue.listActive()`\n#### `tasqueue.listQueued()`\n#### `tasqueue.listCompleted()`\n#### `tasqueue.listFailed()`\n\n## Jobs API\n\n### `job.details()`\nGet the job's informations in a pretty form.\n\n###### Example\n```js\ntasqueue.getJob('someId')\n.then(function(job) {\n    console.log(job.details());\n    {\n        id:         {String},\n        type:       {String},\n        body:       {Object},\n        state:      {String} - one of ['queued', 'active', 'completed', 'failed']\n        created:    {Date},\n        ended:      {Date},\n        attempt:    {Number} - Attempt at which the job failed/completed,\n        duration:   {Number} - in ms,\n        result:     {Object} - anything returned by the exec function on success,\n        error:      {Error} - details about why the job failed\n    }\n});\n```\n\n### `job.cancel()`\n_**Async**_:\nCancels the job and set it as failed.\n\nOnly queued jobs may be cancelled. The promise is rejected if the job is not in the `queued` state.\n\n### `job.delete()`\n_**Async**_:\nUtterly delete a job, whichever its state is.\n\n### Events\nTasqueue inherits the Node.js `EventEmitter` class. Below is the list of all events emitted by tasqueue during execution:\n\n#### Client\n\n###### Client connection\n```js\nemit('client:connected', {\n    // disque-server informations client is connected to\n    host: {String},\n    port: {Number}\n});\n```\n\n###### Client closed\n```js\nemit('client:closed');\n```\n\n#### Queue execution\n\n###### Polling jobs\n```js\nemit('client:polling', {\n    types:            {Number}, // Number of available job types that can be processed by this poll\n    availableWorkers: {Number}, // Total number of available workers for these types\n    totalWorkers:     {Number}  // Total number of workers registered\n});\n```\n\n###### Polling delayed\n```js\nemit('client:delaying', {\n    delay: {Number} - tasqueue instance configured/default poll delay\n});\n```\n\n###### No worker available\n```js\nemit('client:no-workers')\n```\n\n###### Error while polling\n```js\nemit('error:polling', error);\n```\n\n#### Jobs\n\n###### Job started\n```js\nemit('job:started', {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### Job successfully pushed\n```js\nemit('job:pushed', {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### Job successfully canceled\n```js\nemit('job:canceled', {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### Job successfully deleted\n```js\nemit('job:deleted', {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### Job re-queued after failure\n```js\nemit('job:requeued', {\n    id:      {String}, // The job id\n    type:    {String}, // The job type\n    attempt: {Number}  // The last failed attempt for this job\n});\n```\n\n###### Job passed\n```js\nemit('job:success', {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### Job failed\n```js\nemit('error:job-failed', error, {\n    id:    {String}, // The job id\n    type:  {String}  // The job type\n});\n```\n\n###### Error canceling a job\n```js\nemit('error:job-cancel', error, {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n###### No handler registered for a job\n```js\nemit('error:no-handler', error, {\n    id:   {String}, // The job id\n    type: {String}  // The job type\n});\n```\n\n#### Handlers\n\n###### Handler successfully registered\n```js\nemit('handler:registered', {\n    handler.type\n});\n```\n\n###### Error: handler already exists\n```js\nemit('error:existing-handler', error, {\n    type: handler.type\n});\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fnode-tasqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitbookio%2Fnode-tasqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fnode-tasqueue/lists"}