Quickstart

Get started with Resilience in under 5 minutes

This guide will walk you through installing Resilience and creating your first resilient function.

1. Install the package

   Install Resilience using your preferred package manager:

   npm

   npm install @oldwhisper/resilience
   
2. Wrap a function with resilience

   Import withResilience and wrap any function to add retry logic, timeouts, and more:

   import { withResilience } from '@oldwhisper/resilience';
   
   // Your original function
   async function fetchData(url: string) {
     const response = await fetch(url);
     if (!response.ok) throw new Error('Request failed');
     return response.json();
   }
   
   // Wrap it with resilience features
   const resilientFetch = withResilience(fetchData, {
     name: 'fetchData',
     retries: 3,
     timeoutMs: 5000,
     backoff: { type: 'exponential', baseDelayMs: 100, maxDelayMs: 2000 },
     hooks: {
       onAttempt: ({ name, attempt }) => 
         console.log(`${name}: attempt ${attempt}`),
       onRetry: ({ attempt, delayMs, error }) => 
         console.log(`Retrying after ${delayMs}ms:`, error)
     }
   });
   

   withResilience always returns an async function, even if your original function is synchronous.

3. Call your resilient function

   Use the wrapped function just like the original:

   try {
     const data = await resilientFetch('https://api.example.com/data');
     console.log('Success:', data);
   } catch (error) {
     console.error('Failed after all retries:', error);
   }
   

   The function will automatically:

   • Retry up to 3 times on failure
   • Wait with exponential backoff between retries
   • Timeout after 5 seconds
   • Log attempt and retry information
4. Track metrics with WrapperInit

   Use the WrapperInit class to track function calls and collect metrics:

   import { WrapperInit } from '@oldwhisper/resilience';
   
   function processOrder(orderId: number, amount: number) {
     return orderId + amount;
   }
   
   const metrics = new WrapperInit();
   const resilientProcess = metrics.wrap(processOrder, {
     retries: 2,
     timeoutMs: 1000
   });
   
   await resilientProcess(100, 250);
   await resilientProcess(101, 300);
   
   // Check metrics
   console.log('Total calls:', metrics.functionCalls);
   console.log('Per-function:', metrics.f_store);
   

   The WrapperInit class automatically tracks function attempts through its built-in hooks, giving you instant observability.

What’s happening under the hood?

When you wrap a function with withResilience:

1. First attempt: The function executes normally
2. On failure: If the function throws an error and retries are configured, Resilience catches it
3. Backoff delay: Waits for the calculated delay (fixed or exponential)
4. Retry: Attempts the function again
5. Hooks: Triggers lifecycle hooks at each stage for observability
6. Circuit breaker: If configured, opens after threshold failures to prevent cascading issues

Common configurations

Simple retry with fixed delay

const fn = withResilience(myFunction, {
  retries: 3,
  backoff: { type: 'fixed', delayMs: 1000 }
});

Exponential backoff with jitter

const fn = withResilience(myFunction, {
  retries: 5,
  backoff: { 
    type: 'exponential', 
    baseDelayMs: 100, 
    maxDelayMs: 5000,
    jitter: true 
  }
});

Circuit breaker for protecting downstream services

const fn = withResilience(myFunction, {
  retries: 3,
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeoutMs: 60000
  },
  hooks: {
    onCircuitOpen: ({ name }) => 
      console.log(`Circuit breaker opened for ${name}`),
    onCircuitClosed: ({ name }) => 
      console.log(`Circuit breaker closed for ${name}`)
  }
});

Next steps

Installation

Detailed installation and setup instructions

Core concepts

Learn about retries, backoff strategies, and circuit breakers

Configuration

Complete configuration reference

API reference

Full API documentation