Automatically retry subscriptions with exponential backoff.
npm install retry-subscription
Collection subscription is defined as a function returning an Async Iterable, whose first emission represent initial collection state, and subsequent emissions represent live changes:
type CollectionSubscription = (
signal: AbortSignal,
) => AsyncIterable<Array<CollectionSubscriptionUpdate<Key, Value>>>;
type CollectionSubscriptionUpdate<Key extends string | number, Value> = {
/**
* Unique key of the item in the collection.
*/
key: Key;
/**
* `undefined` if the item was removed from the collection.
*/
value?: Value | undefined;
};To add retries to a collection subscription, wrap it with
retryCollectionSubscription:
function retryCollectionSubscription<Key extends string | number, Value>(
subscribe: (
signal: AbortSignal,
) => AsyncIterable<Array<CollectionSubscriptionUpdate<Key, Value>>>,
options?: RetryCollectionSubscriptionOptions<Value>,
): AsyncIterable<Array<CollectionSubscriptionUpdate<Key, Value>>>;When an error happens, retryCollectionSubscription schedules a retry after
exponential backoff that grows with each attempt. Upon initial emission after
retry, attempt number is reset, the previous collection state is compared
against the received initial state, and the resulting Async Iterable only emits
the changes that happened during retry attempts.
Supported options:
type RetryCollectionSubscriptionOptions<Value, Revision = Value> = {
/**
* Signal that can be used to abort retry backoff delays. It is also passed to
* the inner subscription.
*/
signal?: AbortSignal;
/**
* Starting delay before first retry attempt in milliseconds.
*
* Defaults to 1000.
*
* Example: if `baseMs` is 100, then retries will be attempted in 100ms,
* 200ms, 400ms etc (not counting jitter).
*/
baseMs?: number;
/**
* Maximum delay between attempts in milliseconds.
*
* Defaults to 15 seconds.
*
* Example: if `baseMs` is 1000 and `maxDelayMs` is 3000, then retries will be
* attempted in 1000ms, 2000ms, 3000ms, 3000ms etc (not counting jitter).
*/
maxDelayMs?: number;
/**
* Maximum for the total number of attempts.
*
* Defaults to `Infinity`.
*/
maxAttempts?: number;
/**
* Called when an error is thrown by inner subscription, before setting delay
* timer.
*
* If at the time of error the inner subscription was initialized (i.e. has
* had initial emission), then the `attempt` and `delayMs` will be
* `undefined`, and the retry will happen immediately.
*
* If the error happened before initialization, then the `attempt` will start
* from 0 and will be incremented with each attempt, and the retry will happen
* after exponential backoff.
*
* Rethrow error from this callback to prevent further retries.
*/
onError?: (
error: unknown,
attempt: number | undefined,
delayMs: number | undefined,
) => void;
/**
* If the value has a field that is changed each time the collection item
* changes, consider returning supplying `getRevision` function that returns
* it. This way, less memory will be needed to store the state, and less CPU
* will be needed for diffing algorithm on resubscription.
*
* Defaults to identity function, i.e. the revision is the whole value.
*/
getRevision?: (value: Value) => Revision;
/**
* Equality function used by diffing algorithm on resubscription.
*
* Defaults to deep equality.
*/
equality?: (a: Revision, b: Revision) => boolean;
};All functions are also exported in form of
IxJS operators from
retry-subscription/ix module.