@fintoc/checkpoint

Tired of always failing in life? Well, we cannot help with that. But we can help you fail less in a node application.

!npm packagenpm-imgnpm-url !Downloadsdownloads-imgdownloads-url !Code Coveragecodecov-imgcodecov-url
checkpoint is the ultimate flaky code helper. With modern days applications, where we must integrate with external services, which can fail. We have to figure out a way of retrying our code. We must go back to somewhere we know we where fine. We must return to a checkpoint.

Install

npm install @fintoc/checkpoint

Usage

import { checkpoint, retry } from '@fintoc/checkpoint';

// we define how many retries we can make
await checkpoint({ retries: 3 }, () => {
  // do some awesome stuff
  // ...
  // ...

  // this is weird, this number should not be bigger than the other
  if (someNumber < otherNumber) retry();

  try {
    // solving SAT in polynomial time
  } catch (error) {
    // this error is a flaky one, we should just retry
    retry();
  }
});

Nested Checkpoints

At one point or another, we might want to set different checkpoints, and to go back to which ever checkpoint we want. We can do this by specifying a name for a specific checkpoint.

await checkpoint({ name: 'first' }, async () => {
  // doing really important stuff
  // ...

  await checkpoint({ name: 'second' }, () => {

    if (somethingHappends) {
      // something went horrible, we must go even further back
      retry('first');
    }
  });
});

On Retry Callback

We might have to perfom some operations in order to come back to a useful state in order to retry our code. We can set this by using the onRetry callback option.

function onRetry() {
  a = 0;
}
await checkpoint({ onRetry }, () => {

  // a changes its value

  if (someThingHappends) {
     retry(); // a will start at 0 at the next try
  }
});

Checkpoint Options

The checkpoint options are as followed:

{
  name: 'checkpointId', // checkpoint name to reference in retries, defaults to null
  logger: console.log, // function to log the checkpoint execution, defaults to null
  retries: 3, // how many retries are available before raising an error, defaults to 1
  onRetry: () => { // specify a callback before retrying
    // do things
  },
  onFailure: () => { // specify a callback when retry limit is reached
    // raise custom error or whatever you want
  },
}

Return Value

Additionally, the checkpoint function returns the value of the callback function passed as its parameter (if the function reaches a return value before any retry or exception). In the case in which the checkpoint reaches the retry limit, then the checkpoint returns the value of the onFailure function

function onFailure() {
  return 'failed'
}

// returnValue might endup being 'failed' or 'success'
const returnValue = await checkpoint({ onFailure }, () => {
  ...
  // it may retry at some point
  ...
  return 'success'
});