@articulate/squiss-jobs

squiss-jobs

SQS-backed job queue.

• Module API
• Instance API
• CLI

Module API

• squiss.create
• squiss.domainify

squiss.create

:: Object -> Object

Parameters

• Object { queueUrl, region, ... }
  Options object. queueUrl is your SQS job queue. region defaults to eu-west-1. Other options are listed here.

Returns

• Object queue
  A queue instance. See Instance API.

Creates a job queue instance. Note that squiss-jobs supplies its own handleMessage function to sqs-consumer, so any that you provide will be overridden. Also, I recommend creating this once with your config and exporting it as a singleton.

const squiss = require('@articulate/squiss-jobs')

const queue = squiss.create({
  queueUrl: process.env.JOBS_URI,
  region:   process.env.AWS_REGION
})

module.exports = queue

squiss.domainify

:: ((*, Function) -> *) -> (*, Function) -> *

Parameters

• Function handler(payload, done)
  The job handler to wrap in a domain.

Returns

• Function wrappedHandler(payload, done)
  The wrapped job handler.

Avoids uncaught exceptions in async jobs by wrapping the job handler in a domain. The expected handler signature is the same as expected by queue.handle.

const squiss = require('@articulate/squiss-jobs')
const queue  = require('../lib/queue')

const foo = (payload, done) => {
  console.log(payload)
  done()
}

queue.handle('foo', squiss.domainify(foo))

Instance API

• queue.handle
• queue.handleMany
• queue.on
• queue.send
• queue.start
• queue.stop

queue.handle

:: (String, (*, Function) -> *) -> Object

Parameters

• String type
  The job type.
• Function handler(payload, done)
  The handler for that job type.

Returns

• Object queue
  The queue instance.

Registers a job handler for a specific job type. If you register another handler for the same type, it will overwrite the first.

Please note the expected handler signature. The payload will have already been deserialized with JSON.parse. To mark the job as complete, simply call done(). Call done(err) with an Error to fail the job and leave it on the queue.

const squiss = require('@articulate/squiss-jobs')
const queue  = require('../lib/queue')

const foo = (payload, done) => {
  console.log(payload)
  done()
}

queue.handle('foo', squiss.domainify(foo))

You may also call queue.handle multiple times to register several job types.

const jobs = require('require-dir')()

for (var type in jobs) {
  queue.handle(type, squiss.domainify(jobs[type]))
}

queue.handleMany

:: (Object) -> Object

Parameters

• Object jobs
  A map of job types to handlers

Returns

• Object queue
  The queue instance.

Similar to queue.handle, but registers multiple jobs in one shot.

const squiss = require('@articulate/squiss-jobs')
const queue  = require('../lib/queue')

const foo = (payload, done) => {
  console.log(payload)
  done()
}

queue.handleMany('foo', { foo: squiss.domainify(foo) }))

You may also call queue.handleMany multiple times to register several sets of jobs.

queue.on

:: (String, Function) -> Object

Parameters

• String type
  The event type.
• Function listener
  The event listener.

Returns

• Object queue
  The queue instance.

Registers event listeners. This is exactly the eventemitter.on function. Events of interest are listed in the sqs-consumer documentation.

const squiss = require('./squiss')

const queue = squiss.create({ /* your config */ })

queue.on('error', console.error)
queue.on('processing_error', console.error)

queue.send

:: (String, *) -> Promise

Parameters

• String type
  The job type.
• Any payload
  The job payload.

Returns

• Promise
  Resolves with the message sent through sqs-producer.

Sends a job into the SQS queue. The payload will be serialized with JSON.stringify, and a random id will be added to the message before sending into the queue. You can recover from enqueueing errors by calling .catch() on the returned promise.

const queue = require('../lib/queue')

queue.send('foo', { bar: 'baz' }).catch(console.error)

queue.start

:: () -> Object

Parameters

None.

Returns

• Object queue
  The queue instance.

Starts pulling jobs off the queuing and processing them one-at-a-time.

const squiss = require('@articulate/squiss-jobs')
const queue  = require('../lib/queue')

const jobs = require('require-dir')()

for (var type in jobs) {
  queue.handle(type, squiss.domainify(jobs[type]))
}

queue.start()

queue.stop

:: () -> Object

Parameters

None.

Returns

• Object queue
  The queue instance.

Stops processing jobs. Because every start needs a stop. You can always start again with queue.start().

CLI

squiss-jobs ships with an executable script of the same name to help you create a personal dev job queue in SQS. The queue name will be ${project-dirname}-jobs-${aws-username}, and will have a RedrivePolicy pushing to a deadletter queue after 3 job failures.

To run the script, you can either install globally with npm i -g squiss-jobs, or install normally and include it in your npm scripts in the package.json. After creating your queues, it will output the job queue URL for you to include in your ENV.

scotts-air:squiss-jobs scott$ squiss-jobs

Copy the following into your .env file:
JOBS_URI=https://queue.amazonaws.com/689543204258/squiss-jobs-jobs-smccormack

Note: The CLI only supports Mac OSX, and requires brew. It will brew install both jq and awscli if not present, and then allow you to configure your AWS creds before continuing.