npm package: @storebox/workers
Description: ## TL;DR
Latest version: 2.0.3

# boxy-workers

## TL;DR

```js
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

```js
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

```js
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

```js
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](https://github.com/node-cron/node-cron#options)). |
| 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

```js
await workers.start()
```

### `#stop()`

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

#### Example

```js
await workers.stop()
```

### `#onError(func)`

Adds and event handler when an error happens.

#### Example

```js
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

```js
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. |