Poli-C

Poli-C (pronounced "policy") is a fault tolerance utility for JavaScript. Inspired by Polly for .NET, this library's aim is to help applications handle transient failures in asynchronous actions.

API Reference and Documentation

Supported Policies

• RetryPolicy - Sometimes you just need to try again.
• CircuitBreakerPolicy - Don't kick services while they are down.

Installation

Using yarn:

yarn add poli-c

Or npm:

npm install --save poli-c

Then if using TypeScript or a module bundler such as webpack:

import Policy from 'poli-c'; // TypeScript
import { Policy } from 'poli-c'; // ES6

// or if not using ES6 modules
const { Policy } = require('poli-c');

RetryPolicy Examples

Basic

Retry forever

import { Policy } from 'poli-c';

...

const policy = Policy.waitAndRetryForever({ sleepDurationProvider: 1000 });

async function fetchThings() {
    const response = await fetch('https://servicethatmightfail.com/v1/things');
    const things = await response.json();
    return things;
}

...
const things = await policy.executeAsync(fetchThings);
...

Or not

const policy = Policy.waitAndRetry({ retryCount: 3, sleepDurationProvider: 1000 });

...
const things = await policy.executeAsync(fetchThings)
...

Additionally, control when the policy retries on error

const policy = Policy
    .handleError(error => error instanceof FetchError)
    .waitAndRetryForever({ sleepDurationProvider: 1000 });

async function fetchThings() {
    const response = await fetch('https://servicethatmightfail.com/v1/things');
    if (response.status !== 404 && !response.ok) {
        // if the request fails the policy will execute the action again
        throw new FetchError(response);
    }

    // but if parsing the JSON fails the action won't be retried
    const things = await response.json();
    return things;
}

...
const things = await policy.executeAsync(fetchThings);

With cancellation

The asynchronous function will be passed a cancellation token if one is provided to executeAsync. This allows for a cooperative cancellation approach (borrowed from the .NET framework). If canceled, executeAsync will currently return undefined.

import { Policy, CancellationTokenSource } from 'poli-c';

...

const policy = Policy.waitAndRetryForever({ sleepDurationProvider: 1000 });

async function fetchThings(cancellationToken) {
    const response = await cancelableFetch('https://servicethatmightfail.com/v1/things', cancellationToken);
    const things = await response.json();
    return things;
}

...

const cts = new CancellationTokenSource();
const promise = policy.executeAsync(fetchThings, cts.token);

// eventually cancel the execution
const timeout = setTimeout(() => {
    cts.cancel();
}, maxRequestTime);

const things = await promise;
if (!things) {
    // canceled
} else {
    // not canceled
    clearTimeout(timeout);
}
...

Until a valid result is obtained

import { Policy } from 'poli-c';

...

const policy = Policy
    .waitAndRetryForever({ sleepDurationProvider: 1000 })
    .untilValidResult(job => job.isComplete);

async function getJob(jobId) {
    const response = await fetch(`https://jobService.com/v1/jobs/${jobId}`);
    const job = await response.json();
    return job;
}

async function waitForJobCompletion(newJob, cancellationToken) {
    const completedJob = await policy.executeAsync(() => getJob(newJob.id), cancellationToken);
}

With exponential backoff

The library includes two backoff algorithms (full and equal jitter as described here) that are available for use.

import { Policy, backoffs } from 'poli-c';

...

const policy = Policy.waitAndRetry({ retryCount: 3, sleepDurationProvider: backoffs.fullJitter });

async function fetchThings() {
    const response = await fetch('https://servicethatmightfail.com/v1/things');
    const things = await response.json();
    return things;
}

...
const things = await policy.executeAsync(fetchThings);
...

Additionally, a custom backoff algorithm can be used:

const policy = Policy.waitAndRetry({ retryCount: 3, sleepDurationProvider: ({ retryAttempt }) => 1000 * retryAttempt });

CircuitBreakerPolicy Examples

Basic

import { Policy } from 'poli-c'; // ES6

const policy = Policy
    .handleError(error => error instanceof FetchError)
    .circuitBreaker({
        samplingDurationMs: 5000,
        failureThreshold: 0.75,
        minimumThroughput: 4,
        breakDurationMs: 5000,
    });

async function fetchThings() {
    const response = await fetch('https://servicethatmightfail.com/v1/things');
    if (response.status !== 404 && !response.ok) {
        throw new FetchError(response);
    }

    const things = await response.json();
    return things;
}

...

try {
    const things = await policy.executeAsync(fetchThings);
    return things;
} catch (e) {
    // this error may have been thrown immediately by circuit breaker if the
    // failure threshold has been met in the sampling period
    log(e);
}

Need more information about different policies and their APIs? See the API Reference!