Sometimes you need to create a whole bunch of asynchronous tasks that can
a. run to completion b. fail with certainty c. fail with some probability d. get cancelled before completion/failure
For example, you might to mock up a whole bunch of emails to test a mail queue. Or, you want to test your promise code and you want to run it against a bunch of promise generating async tasks that may or may not fails.
This library provides a simple abstraction to perform the above.
npm install job-mock
The package is written in ES2015 and can be compiled to ES5 using npm run compile
. This step is run automatically
on installation.
The following will generate a job named email
that will complete in 100ms
without fail. On completion, it
resolves to the return value of fn
, which will be executed in the context of job
with whatever parameters are
passed to job.run(//params)
.
let Job = require('job-mock')
let delay = 100
, filaProb = 0
, fn = function(msg) {
return msg
}
let job = new Job('email', delay, failProb, fn)
let emailMsg = {
from: 'JoeBlow@someemail.com',
to: 'JanDoe@someemail.com',
subject: 'Important message',
message: 'Yabadabadoo!'
}
job.run(emailMsg)
.then( console.log.bind(console) ) // 100ms later, logs emailMsg back
A job can be canceled before it completes, but only if it is already running
let Job = require('job-mock')
let delay = 1000
let job = new Job('email')
job.run(emailMsg)
.then( console.log.bind(console) ) // won't get here because job is not completed
.catch( console.error.bind(console ) // [CancellationError: `Job canceled by user`]
job.cancel(100)
.then( console.log.bind(console) ) // true - indicated job was successfully cancelled
Trying to cancel a job that has not started or has already terminated will return false
, but not generate any errors.
You can also cause a job to fail with a certain probability by setting failProb
. The value 0
(default) guarantees
the job will complete (assuming the function itself does not throw), and a value 1
guarantees it will fail.
let Job = require('job')
let emailMessages = [ { //emailMsg }, { //emailMsg } ... { // emailMsg } ] // emailMessages.length=1000
let result = emailMessages.map( emailMessage => {
return new Job('email', 10, 0.1)
.run()
.catch( (err) => return null )
}) // `result` will have about 100 `null` values
constructor(name, delay, failProb, fn, errorHandler)
run(params)
- return a cancellablePromise
for return value ofjob.fn(param)
, with a delay ofjob.delay
cancel(delay)
- cancel job's promise indelay
ms, if it is still running and resolve totrue
, elsefalse
isRunning()
- returnsisPending
value of job's promisedisplay()
- returns a human friendly string representation of the job's propertiesstartLog(logFunction)
- enables debug logging with givenlogFunction
stopLog
- stops the logger
fn
- synchronous orPromise
returning function that return job's main return valueerrorHandler
- [optioal] handler to handle rejection of job's promise in its final.catch
block - default just rethrowsdelay
- ms delay from start to end of task executionfailProb
- probability that task's promise will be rejected, to simulate a failure
name
- a string represation of the job, consisting of{name}_{id}
, wherename
is provided to constructor andid
is internally generated (and stored inid
startTime
- timestamp for when task started runningdoneTime
- timestamp for when task completed, ornull
if failed or cancelledfailTime
- timestamp for when task failed, ornull
if completed or cancelledcancelTime
- timestamp for when task was cancelled, ornull
if completed or failedrunTime
- length of time task ran before being cancelled, failing or completingid
- internally generated unique 32-bit (and growing as needed in case of excessive collisions) identifier for job
You can pass a logging function (e.g. Winston.info
) to job.startLog
to start the logger, or invoke job.stopLog()
to stop the debug logger.
The package and its tests are written in ES2015, with scripts to compile to ES5. To run the tests,
npm install // in same directory as module's `package.json`
npm test // will compiles tests using Babel and execute the tests