node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

work

view on npm npm module downloads Build Status Dependency Status js-standard-style

work

A first-in-first-out async task queue. Fill the queue with Task instances (using module:work.TaskQueue#push) then (when ready) call module:work.TaskQueue#process to settle each task in the order they were received. During processing, the queue will process module:work.TaskQueue#maxConcurrent tasks at a time. Each task comprises a name, deferred and list of resolvers - each of which will race to settle the deferred first.

Example

var tq = require("work")
var q = require("q")
var http = require("http")
 
var queue = new tq.TaskQueue()
 
// get the football results - it will take between 0 and 2000ms
// and resolve with the result
function resultResolver(deferred){
    setTimeout(function(){
        deferred.resolve("West Ham 1 - Tottenham Hotspur 3")
    }, Math.random() * 2000)
}
 
// but the timeout resolver will reject it after 1000ms
function timeoutResolver(deferred){
    setTimeout(function(){
        deferred.reject(Error("timeout"))
    }, 1000)
}
 
var task = new tq.Task({
    name: "get result",
    resolver: [ resultResolver, timeoutResolver ]
})
 
queue.push(task)
 
task.promise
    .then(function(result){
        console.log(result)
    })
    .catch(function(err){
        console.log("It failed: " + err.message)
    })
 
queue.process()

tq.Queue

queue class for processing promises

Kind: static class of work

new Queue([options])

Param Type Default Description
[options] object
[options.maxConcurrent] number 1
[options.name] string useful for debugging

queue.name : string

useful for debugging

Kind: instance property of Queue

queue.queued : Array

the current task queue

Kind: instance property of Queue

queue.active : Array

The in-progress tasks

Kind: instance property of Queue

queue.maxConcurrent : number

when emptying, specifying the max number of tasks which may run simultaneously.

Kind: instance property of Queue
Default: 1

queue.length : number

queue length

Kind: instance property of Queue

queue.freeSlotCount : number

Kind: instance property of Queue

queue.push(task) ↩︎

add a task to the end of the queue

Kind: instance method of Queue
Chainable

Param Type Description
task Task task instance

queue.shift() ⇒ Task

returns the next task in the queue and adds it to the active list.

Kind: instance method of Queue

queue.process()

process the queue - attempt to resolve each task.

Kind: instance method of Queue
Todo

  • return a promise which resolves on completion

queue.unshift(newTask) ⇒ Task

insert a task at the front of the queue, returning the instance inserted

Kind: instance method of Queue

Param Type Description
newTask Task the task to be inserted

queue.cancel() ⇒ Task

Shifts the next task off the queue and calls .cancel() on it

Kind: instance method of Queue

queue.isEmpty() ⇒

Test whether any tasks are queued or active

Kind: instance method of Queue
Returns: boolean

"occupied"

Emitted at the moment a queue becomes occupied (has at least 1 task)

Kind: event emitted by Queue

"push"

Emitted when a task is added

Kind: event emitted by Queue

Type Description
Task the task that was pushed

"empty"

Emitted after the final task is taken off the queue for processing

Kind: event emitted by Queue

"complete"

Emitted when the queue processing is complete

Kind: event emitted by Queue

"shift"

Emitted when a task is shifted

Kind: event emitted by Queue

Type Description
Task the task that was pushed

"occupied"

Emitted at the moment a queue becomes occupied (has at least 1 task)

Kind: event emitted by Queue

"unshift"

Emitted when a task is unshifted to the front of the queue

Kind: event emitted by Queue

Type Description
Task the task that was pushed

"empty"

Emitted after the final task is taken off the queue for processing

Kind: event emitted by Queue

"cancel"

Emitted when a task is cancelled

Kind: event emitted by Queue

Type Description
Task the task that was cancelled

tq.Task ⇐ module:state-machine

A task defines a piece of work which needs doing now, or in the future. When you create a task you receive a promise for its result. Process the task using task.process().

Kind: static class of work
Extends: module:state-machine

new Task(executor, [options])

Param Type Description
executor function | Array.<function()> the resolver function
[options] object an object containing optional values
[options.name] string a name string, useful for debugging
[options.data] object data used by the resolver function

task.promise : external:Promise

a promise for the completion of the task

Kind: instance property of Task

task.name : string

useful for debug output

Kind: instance property of Task

task.context : string

data for the task

Kind: instance property of Task

task.process()

Process the task - settled the deferred using the supplied resolver function(s). The resolver function is called in the context of the task and receives a deferred, which must be resolved.

Kind: instance method of Task

task.cancel()

a cancelled task fulfils with the value -1

Kind: instance method of Task

"fulfilled"

Emitted when a task fulfills

Kind: event emitted by Task

"resolved"

Emitted when a task is resolved

Kind: event emitted by Task

"rejected"

Emitted when a task is rejected

Kind: event emitted by Task

Type Description
Error the rejection reason

"running"

Emitted when a task starts

Kind: event emitted by Task

Task.eState : enum

The various Task states.

Kind: static enum property of Task
Properties

Name Type Default
PENDING string "pending"
RUNNING string "running"
FULFILLED string "fulfilled"
REJECTED string "rejected"
RESOLVED string "resolved"
CANCELLED string "cancelled"

© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.