again-ts

Async function retrying written in typescript.

Installation

npm install again-ts

Usage

retry('safe')

The retry('safe') function allows you to execute an async function with retry logic. It never throws and returns a result object indicating success or failure.

import { retry } from 'again-ts';

// Basic usage
const result = await retry('safe', async (ctx) => {
    // ctx contains information about the current attempt
    console.log(`Attempt #${ctx.attempts}`);
    return await someAsyncOperation();
}, {
    retries: 3,
    waitMin: 1000
});

if (result.ok) {
    console.log('Success:', result.value); // result.value is the return value of your function
} else {
    console.error(`Failed after ${result.ctx.attempts} attempts:`, result.ctx.errors);
}

retry('unsafe')

The retry('unsafe') function allows you to execute an async function with retry logic. It doesn't wrap returned value and throws RetryFailedError on failure.

import { retry } from 'again-ts';

// 'unsafe'
try {
    const result = await retry('unsafe', async (ctx) => {
    // ctx contains information about the current attempt
    console.log(`Attempt #${ctx.attempts}`);
    return await someAsyncOperation();
}, {
    retries: 5,
    waitMin: 500
});} catch (err){
    // throws RetryFailedError with errors in .ctx
    console.error(err.message)
    console.error(err.ctx.errors)
}

retryify

retryify wraps an existing function with retry logic, returning a new function that behaves like the original but with built-in retries.

import { retryify } from 'again-ts';

const unstableFetch = async (url: string) => { /* ... */ };

const fetchWithRetry = retryify('safe', unstableFetch, {
    retries: 5,
    factor: 2, // exponential backoff
});

const result = await fetchWithRetry('https://api.example.com');

if (result.ok) {
    // ...
}

API Reference

RetryOptions

| Option | Type | Default | Description | | -------------------- | -------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | | retries | number | 4 | Number of retries (not including the first attempt). Set to Infinity to retry indefinitely. | | timeMax | number | Infinity | Maximum execution time in milliseconds for the entire retry process. | | waitMin | number | 100 | Minimum wait time between attempts in milliseconds. | | waitMax | number | Infinity | Maximum wait time between attempts in milliseconds. | | factor | number | 1 | Exponential backoff factor. Formula: waitMin * factor^(retriesTaken). | | linear | boolean | true | If true, wait time scales linearly with the retry number. | | random | boolean | false | If true, adds randomization to the wait time. | | skipSameErrorCheck | boolean | true | If true, identical consecutive errors are stored separately in the errors array. | | waitIfNotConsumed | boolean | false | If true, waits even when a retry is not consumed (when consumeIf returns false). | | onCatch | (ctx) => void \| Promise<void> | () => null | Function called when an error is caught, before deciding to retry. | | retryIf | (ctx) => boolean \| Promise<boolean> | () => true | Predicate function to determine if a retry should be attempted. | | consumeIf | (ctx) => boolean \| Promise<boolean> | () => true | Predicate function. If it returns false, the retry is not counted towards retriesTaken. | | signal | AbortSignal \| null | null | AbortSignal to cancel the retry process. | | concurrency | number | 1 | Number of concurrent async executions per attempt. |

RetryContext

The context object returned in result and passed to onTry, onCatch, retryIf, consumeIf.

• attempts: Total number of attempts made so far (starts at 1).
• retriesTaken: Number of retries consumed (usually attempts - 1, unless consumeIf returned false).
• errors: Array of errors encountered so far.
• start: Timestamp when the retry process started.
• end: Timestamp when the retry process ended.

License

ISC