The Problem with Existing Resilience Libraries

Developers often face the challenge of making asynchronous operations more robust. Whether it's a database query, an internal API call, or a file operation, these tasks can fail. Existing solutions in the TypeScript ecosystem, however, frequently come with significant baggage. Many are tightly coupled to HTTP clients, requiring you to integrate them with libraries like axios-retry or p-retry. Others demand a more object-oriented approach, forcing you to wrap your functions within classes that expose a specific .execute() method. This boilerplate can be cumbersome and unnecessary when the goal is simply to add resilience to an arbitrary asynchronous function without introducing substantial dependencies.

This is where houhou steps in, aiming to provide a lightweight, flexible, and dependency-free solution.

Introducing Houhou: Composable Resilience Policies

Houhou is a new TypeScript library designed to address these limitations. Its core proposition is simple: wrap any asynchronous function with customizable resilience policies, including retries, timeouts, and circuit breakers, all while maintaining the original function's signature. This means you can adopt houhou without altering how you call your existing asynchronous code. The library boasts a minimal footprint, consisting of approximately 500 lines of code and, crucially, zero external dependencies.

The library's architecture is built around the concept of composable policies. You can chain these policies together to create sophisticated resilience strategies tailored to specific needs. For instance, a database operation might benefit from a few retries with a short delay, followed by a timeout if it still doesn't complete. An external API call might require a circuit breaker in addition to retries and timeouts to prevent cascading failures.

Consider a typical scenario where you need to fetch data from a third-party service. Without houhou, you might write custom retry logic, handle timeouts manually, and perhaps implement a basic circuit breaker pattern. With houhou, this becomes significantly cleaner:

import { houhou } from houhou;
import { retry, timeout, circuitBreaker } from houhou;

async function fetchUserData(userId: string) {
  // ... actual data fetching logic ...
  return userData;
}

const resilientFetchUserData = houhou(
  fetchUserData,
  retry({ times: 3, delay: 100 }),
  timeout({ ms: 5000 }),
  circuitBreaker({ window: 60000, threshold: 5 })
);

// Usage remains the same
const data = await resilientFetchUserData("user-123");

Key Resilience Policies Explained

Houhou implements several fundamental resilience patterns, each configurable to meet specific operational needs:

Retry Policy

The retry policy allows an operation to be automatically re-executed if it fails. This is particularly useful for transient network issues or temporary service unavailability. Houhou's retry policy is configurable with parameters such as the number of times to retry and the delay between retries. The delay can be fixed, or it can implement exponential backoff, a common strategy to avoid overwhelming a struggling service.

For example, you might configure a retry policy to attempt an operation up to 5 times, with an initial delay of 200ms that doubles with each subsequent retry. This prevents immediate, repeated failures and gives the underlying system time to recover.

Timeout Policy

Timeouts are crucial for preventing operations from hanging indefinitely. A timeout policy ensures that an asynchronous function call will be aborted if it does not complete within a specified duration. This is essential for maintaining application responsiveness and preventing resource exhaustion. Houhou allows you to set a millisecond-based timeout, after which the operation is cancelled and an error is thrown.

Imagine a critical data loading function. Setting a timeout prevents the UI from freezing if the data source becomes unresponsive. If the timeout is reached, the application can gracefully degrade or inform the user of the issue.

Circuit Breaker Policy

The circuit breaker pattern is a more advanced resilience mechanism designed to prevent repeated calls to a service that is known to be failing. It acts like an electrical circuit breaker: if too many calls fail within a given period, the breaker