boxy-workers

TL;DR

const workers = createWorkers()

workers.useInterval(
  (ctx) => {
    /* do stuff */
  },
  {
    interval: 200,
  },
)

workers.useCron(
  (ctx) => {
    /* do stuff */
  },
  {
    crontab: '* * * * * *',
  },
)

await workers.start()

/* ... */

await workers.stop()

Methods

createWorkers([options])

Create a new pool of workers.

Example

createWorkers({ state: { foo: 'bar' }, startupDuration: 30000 })

Options

| Name | Type | Default | Description | | --------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | state | Object | {} | An object containing custom values. | | startupDuration | Object | 60000 | The ramp-up duration during which workers are started. The duration between workers setup is this duration divided by the number of workers. Expressed in milliseconds. |

#useInterval(func, [options])

Adds an "interval" worker to the workers pool. Interval workers execute a callback every X milliseconds.

Example

workers.useInterval(
  ({ name, shouldWorkerStop, state, app: { state: appState } }) => {
    /* do stuff */
  },
  {
    interval: 200,
    /* state */
    /* name */
    /* workAtStartup */
  },
)

Function

The worker function.

| Name | Type | Description | | -------------------- | -------- | --------------------------------------------------------------- | | ctx | Object | A context object. | | ctx.name | String | The name of the worker. | | ctx.shouldWorkerStop | Function | Returns true if the worker pool's stop() method was called. | | ctx.state | Object | A object, local to this worker. | | ctx.app.state | Object | A state object, global to the worker pool. |

Options

| Name | Type | Default | Description | | ------------- | ------- | -------------- | --------------------------------------------------------------------------------------------- | | interval | Number | required | The interval of the worker. Expressed in milliseconds. | | state | Object | {} | The initial value of the local state object for this worker. Will be modified by side-effect. | | name | String | interval-{n} | The name of the worker. | | workAtStartup | Boolean | false | Whether the worker should run once at startup, before the interval. |

#useCron(func, [options])

Adds a "cron" worker to the workers pool. Cron workers execute a callback at specific times, as defined by the crontab rule.

Example

workers.useCron(
  ({ name, shouldWorkerStop, state, app: { state: appState } }) => {
    /* do stuff */
  },
  {
    crontab: '* * * * * *',
    /* options */
    /* state */
    /* name */
  },
)

Function

The worker function.

| Name | Type | Description | | -------------------- | -------- | --------------------------------------------------------------- | | ctx | Object | A context object. | | ctx.name | String | The name of the worker. | | ctx.shouldWorkerStop | Function | Returns true if the worker pool's stop() method was called. | | ctx.state | Object | A object, local to this worker. | | ctx.app.state | Object | A state object, global to the worker pool. |

Options

| Name | Type | Default | Description | | ------- | ------ | ------------ | -------------------------------------------------------------------------------------------------------------- | | crontab | String | required | The crontab rule of the worker. | | options | Object | {} | The cron options, directly passed to node-cron (see here). | | state | Object | {} | The initial value of the local state object for this worker. Will be modified by side-effect. | | name | String | cron-{n} | The name of the worker. |

#start()

Starts the workers pool. You can await this method to wait for all workers setups to be done.

Example

await workers.start()

#stop()

Stops the workers pool. You can await this method to wait for all workers to be stopped.

Example

await workers.stop()

#onError(func)

Adds and event handler when an error happens.

Example

workers.onError((error, ctx) => {
  /* do stuff */
})

Function parameters

| Name | Type | Description | | -------------------- | -------- | --------------------------------------------------------------- | | error | Error | The error that was thrown. | | ctx | Object | A context object. | | ctx.name | String | The name of the worker. | | ctx.shouldWorkerStop | Function | Returns true if the worker pool's stop() method was called. | | ctx.state | Object | A object, local to this worker. | | ctx.app.state | Object | A state object, global to the worker pool. |

#useBeforeStart(func)

Calls a function hook before the workers initialization has started. If you use an async function, all workers will start after your function has run.

Example

workers.useBeforeStart((ctx) => {
  /* do stuff */
})

Function parameters

| Name | Type | Description | | ------------- | ------ | ------------------------------------------ | | ctx | Object | A context object. | | ctx.app.state | Object | A state object, global to the worker pool. |