@map-colonies/cleanup-registry

cleanup-registry

a package for calling async functions to be resolved in a configured loop

Install

npm install @map-colonies/cleanup-registry

Usage

• import cleanup-registry:

import { CleanupRegistry } from '@map-colonies/cleanup-registry';

• create your registry with wished options:

const registry = new CleanupRegistry({
    overallTimeout: 3000,
    preCleanupHook: async (): Promise<void> => Promise.resolve(),
  });

• register your async functions:

registry.register({
    func: myAsyncFunc,
    id: 'funcId',
    timeout: 100,
    timeoutAfterFailure: 300
});

• optionally listen to your wanted events:

registry.on('itemCompleted', (id) => console.info({ msg: 'item completed', id }));
registry.on('itemFailed', (id, error, message) => console.error({ err: error, msg: message, id }));
registry.on('started', () => console.info('started'));
registry.on('finished', (status) =>
    status === 'success' ?
    console.info('finished successfully') :
    console.error({ msg: 'finished with bad status', status })
);

• trigger the registered functions

await registry.trigger();

How it works

The cleanup process as a whole:

flowchart LR
    A[Triggered] -->B{already triggered?}
    B -->|yes| C[AlreadyTriggeredError]
    B -->|no| D((Started))
    D -->E{PreCleanupHook?}
    E -->|yes| F[PreHook]
    F -->|resolves| G
    F -->|rejects| H{ignorePreError?}
    H -->|yes| G[Registry Cleanup]
    H -->|no| I((preFailed))
    E -->|no| G
    G -->J{overallExpired?}
    J -->|yes| K((timeout))
    J -->|no| L{PostCleanupHook?}
    L -->|yes| M[PostHook]
    L -->|no| P
    M -->|resolves| P((success))
    M -->|rejects| N{ignorePostError?}
    N -->|no| O((postFailed))
    N -->|yes| P

Cleaning up the registry will result in each item independent cleanup loop:

flowchart TB
    A{Overall Expired?}
    A -->|yes| B((timeout))
    A -->|no| C[callFunction]
    C -->|resolves| D((itemCompleted))
    C -->|rejests| E((itemFailed))
    E -->F{TimeoutError?}
    F -->|yes| A
    F -->|no| G[delay]
    G --> A

Configuration

RegistryOptions

• overallTimeout: the duration in ms for all the registered functions to complete. when expired new function completion attempts will cease and a finished event with timeout status will be emitted. defaults to 10000.
• preCleanupHook: an async function to be called before any of the registered functions will be called.
• postCleanupHook: an async function to be called after all registered functions have completed.

ItemOptions

• func: an async function for registration
• id: the id to be attached to the item on itemCompleted, itemFailed events and remove function, could be a string or a symbol, if no id is provided a random uuid will be set.
• timeout: the duration in ms for the function to be resolved in a single attempt, when expired itemFailed event will be emitted with a TimeoutError as error. defaults to 1000.
• timeoutAfterFailure: the duration in ms for the function to be delayed after inner function rejection (not due to timeout), only when expired a new attempt will be made. defaults to 500.

TriggerOptions

• ignorePreError: should ignore rejection by preCleanupHook, when falsy and preCleanupHook rejects a finished event with preFailed will be emitted and the cleanup process will stop. defaults to true.
• ignorePostError: should ignore rejection by postCleanupHook, if falsy and postCleanupHook rejects a finished event with postFailed will be emitted. defaults to true.

Events

optionally listen to the following events:

• started: the registry had started the cleanup process.
• itemCompleted: a registered function promise has been resolved, the item id is provided.
• itemFailed: a registered function promise had rejected, this could be due to inner function rejection or the item timed out. the item id, the rejecting error and possibly a message are provided.
• finished: the cleanup process has completed, the finish status is provided. finish status is one of the following statuses:
  • success: all registered functions had completed successfully
  • timeout: the registry timeout had expired before all registered functions have completed
  • preFailed: the preCleanupHook had rejected
  • postFailed: the postCleanupHook had rejected

Tests

npm test