Pipsqueak
Pipsqueak is an in memory interval based task scheduler, with support for promises, callbacks and synchronous functions. Pipsqueak is also the name of a Hamster. Hamsters like running in circles. A bit like an interval based task scheduler, but more cute.
Advantages Over setInterval / setTimeout
Pipsqueak allows you to:
- Monitor a task's lifecycle through
begin
,end
anderror
events - Reduce the boilerplate code associated with setTimeout/setInterval
- Randomly stagger execution when running multiple instances
- Configure intervals in human readable form
- Prevent overlapping tasks
- Stop worrying about unref
Promise API
const promiseApi: pipsqueak = ; const factory = { ;} const p = start;
n.b. In order for the promise to be re-evaluated a factory must be used
Callback API
const callbackApi: pipsqueak = ; const task = ; const p = start;
n.b. the results are an array
Synchronous API
const synchronousApi: pipsqueak = ; const task = ; const p = start;
Output
begin: example/39195fc7-7035-48a2-9f73-ef6476ff3fdd
end: example/39195fc7-7035-48a2-9f73-ef6476ff3fdd 2018-02-10T22:41:51.025Z
begin: example/2c3fc5c6-c5dd-4233-8979-21b047b443b6
end: example/2c3fc5c6-c5dd-4233-8979-21b047b443b6 2018-02-10T22:41:56.028Z
begin: example/aa6b7d7f-608b-4469-b874-18fda2457a45
end: example/aa6b7d7f-608b-4469-b874-18fda2457a45 2018-02-10T22:42:01.029Z
Advanced Usage
Multiple tasks
You can specify multiple tasks by passing pipsqueak an array instead of a map
const promiseApi: pipsqueak = ; const factory = { ;} const tasks = name: 'example-1' factory: factory interval: '1s' delay: '1s' name: 'example-2' factory: factory interval: '5s' const p = start;
Intervals / Delays
You must set an interval, but an initial delay is optional. Values may be integers, parsable strings or if you want a random duration, an object containing max
and optional min
properties.
const promiseApi: pipsqueak = ; const factory = { ;} const interval = min: '1m' max: '5m' ;const delay = max: '1m' ;const p = start;
Stopping
Calling stop will cancel any schedule runs and prevent new runs from being scheduled. You can specify a shutdown timeout at a task level
const tasks = name: 'example-1' factory: factory interval: '1s' timeout: '2s' name: 'example-2' factory: factory interval: '5s' timeout: '5s'
Promise API
const promiseApi: pipsqueak = ; const p = startp;
Callback API
const callbackApi: pipsqueak = ; const p = start;p
Synchronous API
Synchronous tasks are blocking, so there's no need to wait for them
Poking Tasks
You can force a task or tasks to run by poking them.
const p = start;p;p;p;
If pipsqueak is stopped, or the task was running or disabled, poking it will have no effect. If pipsqueak was not started, the task will be run once, but not scheduled. If pipsqueak was started, the next schedule will be cancelled, the task will be run once and rescheduled.
Disabling Tasks
If you want to configure, but disable a specific tasks (maybe because it should only run under specific conditions, set disabled
to true, e.g.
Events
begin
Emitted whenever the task begins.
Property | Type | Description |
---|---|---|
name | String | The supplied task runner name. |
run | UUID | Uniquely identifies the run. |
iteration | Integer | The number of times the task has been executed |
timestamp | Integer | The current time in millis |
end
Emitted whenever the task finishes.
Property | Type | Description |
---|---|---|
name | String | The supplied task runner name. |
run | UUID | Uniquely identifies the run. |
iteration | Integer | The number of times the task has been executed |
timestamp | Integer | The current time in millis |
result | Mixed | The result of the task, passed the the callback, resolved or returned |
error
Emitted whenever the task errors.
Property | Type | Description |
---|---|---|
name | String | The supplied task runner name. |
run | UUID | Uniquely identifies the run. |
iteration | Integer | The number of times the task has been executed |
timestamp | Integer | Uniquely identifies the run. |
error | Error | The error object thrown, rejected or passed to the callback |
Debug
To run with debug enabled set DEBUG=pipsqueak