airbag

Airbag

Execution Orchestration Layer for JavaScript/TypeScript.

Replace imperative try/catch/finally blocks with declarative async function wrappers. Airbag handles loading states, error catching, retries with exponential backoff, timeouts, and circuit breaking — fully type-safe with zero runtime dependencies.

Install

npm install airbag

Quick Start

import { airbag } from 'airbag';

interface User {
  id: string;
  name: string;
}

const fetchUser = async (id: string): Promise<User> => {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json() as Promise<User>;
};

const safeFetchUser = airbag(fetchUser, {
  timeout: 5000,
  retries: 3,
  onLoading: (loading) => spinner.toggle(loading),
  onSuccess: (user) => toast.success(`Loaded ${user.name}`),
  onError: (err) => toast.error(err.message),
});

// Fully type-safe — same signature as fetchUser
const user = await safeFetchUser('user-123');

Configuration Hierarchy

Three levels of configuration merged in order of specificity:

Global → Instance → Execution

import { createAirbagInstance } from 'airbag';

// Level 1: Global defaults
const { wrap } = createAirbagInstance({
  retries: 3,
  timeout: 10000,
  onError: (err) => logger.error(err),
});

// Level 2: Instance options (merged over global)
const safeFetch = wrap(fetchUser, {
  name: 'fetchUser',
  timeout: 5000,
});

// Level 3: Execution overrides (merged over instance)
const user = await safeFetch.with({ timeout: 15000 })('user-123');

API

airbag(fn, options?)

Wraps an async function with execution orchestration.

const wrapped = airbag(myAsyncFn, { timeout: 5000, retries: 3 });
const result = await wrapped(...originalArgs);

createAirbagInstance(options?)

Creates a factory with shared global defaults.

const { wrap, configure, getDefaults } = createAirbagInstance({ retries: 2 });

wrapped.with(overrides)

Creates a new wrapped function with execution-level overrides while sharing the same circuit breaker state.

const urgent = wrapped.with({ timeout: 2000 });
const result = await urgent(...args);

wrapped.reset()

Resets the circuit breaker state back to closed.

Options

Option	Type	Default	Description
name	string	'anonymous'	Identifier for logging and error messages
timeout	number	30000	Timeout in ms (0 disables)
retries	number	0	Shorthand for retry.count
retry.count	number	0	Number of retries after initial failure
retry.backoff	'exponential' | 'linear' | 'fixed'	'exponential'	Backoff strategy between retries
retry.baseDelay	number	1000	Base delay in ms
retry.maxDelay	number	30000	Maximum delay cap in ms
retry.jitter	boolean	true	Randomize delays to avoid thundering herd
circuitBreaker.enabled	boolean	false	Enable the circuit breaker
circuitBreaker.threshold	number	5	Consecutive failures before opening
circuitBreaker.resetTimeout	number	60000	Ms before probing with a half-open attempt
signal	AbortSignal	—	Cancel execution via AbortController

Callbacks

Lifecycle callbacks can be passed flat at the top level — no nesting required:

airbag(fetchUser, {
  retries: 3,
  onSuccess: (user) => toast.success(user.name),
  onError: (err) => toast.error(err.message),
});

For reusable callback sets, group them in an adapter object instead:

const logger: AirbagAdapter = {
  onError: (err, ctx) => log.error(ctx.functionName, err),
  onFinish: (ctx) => log.info(`Done in ${ctx.duration}ms`),
};

airbag(fetchUser, { retries: 3, adapter: logger });

If both flat callbacks and an adapter are provided, the adapter takes precedence.

Every callback receives an ExecutionContext:

interface ExecutionContext {
  functionName: string;
  duration: number;
  timestamp: number;
  attempt: number;
  maxAttempts: number;
}

Error Types

All errors extend AirbagError with a code and context property:

Error	Code	When
TimeoutError	TIMEOUT	Promise exceeded the configured timeout
RetryExhaustedError	RETRY_EXHAUSTED	All retry attempts failed
CircuitOpenError	CIRCUIT_OPEN	Circuit breaker blocked execution
AbortError	ABORTED	Execution cancelled via AbortSignal

import { TimeoutError, RetryExhaustedError } from 'airbag';

const result = await safeFetch('id').catch((err) => {
  if (err instanceof TimeoutError) {
    // err.timeout — the configured timeout in ms
    // err.context — execution metadata
  }
  if (err instanceof RetryExhaustedError) {
    // err.cause — the last error that caused the final failure
  }
});

License

MIT