airbag 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# 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
+
+```bash
+npm install airbag
+```
+
+## Quick Start
+
+```ts
+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
+
+```ts
+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.
+
+```ts
+const wrapped = airbag(myAsyncFn, { timeout: 5000, retries: 3 });
+const result = await wrapped(...originalArgs);
+```
+
+### `createAirbagInstance(options?)`
+
+Creates a factory with shared global defaults.
+
+```ts
+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.
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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`:
+
+```ts
+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` |
+
+```ts
+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

package/dist/index.d.mts

@@ -0,0 +1,160 @@
+type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+type AirbagErrorCode = 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'CIRCUIT_OPEN' | 'ABORTED' | 'EXECUTION_FAILED';
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Error;
+};
+interface RetryConfig {
+    count: number;
+    backoff: BackoffStrategy;
+    baseDelay: number;
+    maxDelay: number;
+    jitter: boolean;
+}
+interface CircuitBreakerConfig {
+    enabled: boolean;
+    threshold: number;
+    resetTimeout: number;
+}
+interface ExecutionContext {
+    functionName: string;
+    duration: number;
+    timestamp: number;
+    attempt: number;
+    maxAttempts: number;
+}
+interface AirbagAdapter<TReturn = unknown> {
+    onLoading?: (isLoading: boolean, context: ExecutionContext) => void;
+    onSuccess?: (data: TReturn, context: ExecutionContext) => void;
+    onError?: (error: Error, context: ExecutionContext) => void;
+    onRetry?: (attempt: number, error: Error, context: ExecutionContext) => void;
+    onFinish?: (context: ExecutionContext) => void;
+}
+interface AirbagOptions<TReturn = unknown> {
+    name?: string;
+    timeout?: number;
+    retries?: number;
+    retry?: Partial<RetryConfig>;
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    signal?: AbortSignal;
+    adapter?: AirbagAdapter<TReturn>;
+    onLoading?: AirbagAdapter<TReturn>['onLoading'];
+    onSuccess?: AirbagAdapter<TReturn>['onSuccess'];
+    onError?: AirbagAdapter<TReturn>['onError'];
+    onRetry?: AirbagAdapter<TReturn>['onRetry'];
+    onFinish?: AirbagAdapter<TReturn>['onFinish'];
+}
+interface AirbagResolvedConfig<TReturn = unknown> {
+    name: string;
+    adapter: AirbagAdapter<TReturn>;
+    retry: RetryConfig;
+    timeout: number;
+    circuitBreaker: CircuitBreakerConfig;
+    signal?: AbortSignal;
+}
+/**
+ * Wrapped async function that preserves the original function's
+ * argument types and return type while adding execution orchestration.
+ *
+ * @typeParam TArgs - Tuple of the original function's parameter types
+ * @typeParam TReturn - The resolved type of the original function's promise
+ */
+interface WrappedFunction<TArgs extends unknown[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** Creates a new wrapped function with execution-level option overrides. */
+    with(overrides: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+    /** Resets the circuit breaker state for this wrapped function. */
+    reset(): void;
+}
+interface CircuitBreakerInstance {
+    canExecute(): boolean;
+    recordSuccess(): void;
+    recordFailure(): void;
+    getState(): CircuitBreakerState;
+    reset(): void;
+}
+interface AirbagInstance {
+    /** Wraps an async function with airbag orchestration using instance-level defaults. */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+    /** Merges new options into the instance-level defaults. */
+    configure(options: AirbagOptions): void;
+    /** Returns the fully resolved configuration with current defaults. */
+    getDefaults(): AirbagResolvedConfig;
+}
+
+/**
+ * Wraps an async function with execution orchestration.
+ *
+ * The returned function has the same signature as the original but adds:
+ * - Automatic loading state management
+ * - Configurable retries with exponential backoff
+ * - Timeout enforcement
+ * - Circuit breaker protection
+ * - Structured error reporting via adapters
+ *
+ * @typeParam TArgs - Tuple of the original function's parameter types
+ * @typeParam TReturn - The resolved type of the original function's promise
+ *
+ * @example
+ * ```ts
+ * const safeFetch = airbag(fetchUser, {
+ *   name: 'fetchUser',
+ *   timeout: 5000,
+ *   retry: { count: 3 },
+ *   adapter: {
+ *     onError: (err) => toast.error(err.message),
+ *   },
+ * });
+ *
+ * const user = await safeFetch('user-123');
+ * ```
+ */
+declare function airbag<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+
+/**
+ * Creates a pre-configured airbag instance with shared global defaults.
+ *
+ * All functions wrapped through this instance inherit the global options
+ * before applying their own instance-level and execution-level overrides.
+ *
+ * @example
+ * ```ts
+ * const { wrap } = createAirbagInstance({
+ *   retry: { count: 3 },
+ *   adapter: {
+ *     onError: (err) => logger.error(err),
+ *   },
+ * });
+ *
+ * const safeFetch = wrap(fetchUser, { timeout: 5000 });
+ * const user = await safeFetch('user-123');
+ * ```
+ */
+declare function createAirbagInstance(globalOptions?: AirbagOptions): AirbagInstance;
+
+declare class AirbagError extends Error {
+    readonly code: AirbagErrorCode;
+    readonly context: ExecutionContext;
+    constructor(message: string, code: AirbagErrorCode, context: ExecutionContext, options?: {
+        cause?: Error;
+    });
+}
+declare class TimeoutError extends AirbagError {
+    readonly timeout: number;
+    constructor(context: ExecutionContext, timeout: number);
+}
+declare class RetryExhaustedError extends AirbagError {
+    constructor(context: ExecutionContext, cause: Error);
+}
+declare class CircuitOpenError extends AirbagError {
+    constructor(context: ExecutionContext);
+}
+declare class AbortError extends AirbagError {
+    constructor(context: ExecutionContext);
+}
+
+export { AbortError, type AirbagAdapter, AirbagError, type AirbagErrorCode, type AirbagInstance, type AirbagOptions, type AirbagResolvedConfig, type BackoffStrategy, type CircuitBreakerConfig, type CircuitBreakerInstance, type CircuitBreakerState, CircuitOpenError, type ExecutionContext, type Result, type RetryConfig, RetryExhaustedError, TimeoutError, type WrappedFunction, airbag, createAirbagInstance };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+type AirbagErrorCode = 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'CIRCUIT_OPEN' | 'ABORTED' | 'EXECUTION_FAILED';
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Error;
+};
+interface RetryConfig {
+    count: number;
+    backoff: BackoffStrategy;
+    baseDelay: number;
+    maxDelay: number;
+    jitter: boolean;
+}
+interface CircuitBreakerConfig {
+    enabled: boolean;
+    threshold: number;
+    resetTimeout: number;
+}
+interface ExecutionContext {
+    functionName: string;
+    duration: number;
+    timestamp: number;
+    attempt: number;
+    maxAttempts: number;
+}
+interface AirbagAdapter<TReturn = unknown> {
+    onLoading?: (isLoading: boolean, context: ExecutionContext) => void;
+    onSuccess?: (data: TReturn, context: ExecutionContext) => void;
+    onError?: (error: Error, context: ExecutionContext) => void;
+    onRetry?: (attempt: number, error: Error, context: ExecutionContext) => void;
+    onFinish?: (context: ExecutionContext) => void;
+}
+interface AirbagOptions<TReturn = unknown> {
+    name?: string;
+    timeout?: number;
+    retries?: number;
+    retry?: Partial<RetryConfig>;
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    signal?: AbortSignal;
+    adapter?: AirbagAdapter<TReturn>;
+    onLoading?: AirbagAdapter<TReturn>['onLoading'];
+    onSuccess?: AirbagAdapter<TReturn>['onSuccess'];
+    onError?: AirbagAdapter<TReturn>['onError'];
+    onRetry?: AirbagAdapter<TReturn>['onRetry'];
+    onFinish?: AirbagAdapter<TReturn>['onFinish'];
+}
+interface AirbagResolvedConfig<TReturn = unknown> {
+    name: string;
+    adapter: AirbagAdapter<TReturn>;
+    retry: RetryConfig;
+    timeout: number;
+    circuitBreaker: CircuitBreakerConfig;
+    signal?: AbortSignal;
+}
+/**
+ * Wrapped async function that preserves the original function's
+ * argument types and return type while adding execution orchestration.
+ *
+ * @typeParam TArgs - Tuple of the original function's parameter types
+ * @typeParam TReturn - The resolved type of the original function's promise
+ */
+interface WrappedFunction<TArgs extends unknown[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** Creates a new wrapped function with execution-level option overrides. */
+    with(overrides: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+    /** Resets the circuit breaker state for this wrapped function. */
+    reset(): void;
+}
+interface CircuitBreakerInstance {
+    canExecute(): boolean;
+    recordSuccess(): void;
+    recordFailure(): void;
+    getState(): CircuitBreakerState;
+    reset(): void;
+}
+interface AirbagInstance {
+    /** Wraps an async function with airbag orchestration using instance-level defaults. */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+    /** Merges new options into the instance-level defaults. */
+    configure(options: AirbagOptions): void;
+    /** Returns the fully resolved configuration with current defaults. */
+    getDefaults(): AirbagResolvedConfig;
+}
+
+/**
+ * Wraps an async function with execution orchestration.
+ *
+ * The returned function has the same signature as the original but adds:
+ * - Automatic loading state management
+ * - Configurable retries with exponential backoff
+ * - Timeout enforcement
+ * - Circuit breaker protection
+ * - Structured error reporting via adapters
+ *
+ * @typeParam TArgs - Tuple of the original function's parameter types
+ * @typeParam TReturn - The resolved type of the original function's promise
+ *
+ * @example
+ * ```ts
+ * const safeFetch = airbag(fetchUser, {
+ *   name: 'fetchUser',
+ *   timeout: 5000,
+ *   retry: { count: 3 },
+ *   adapter: {
+ *     onError: (err) => toast.error(err.message),
+ *   },
+ * });
+ *
+ * const user = await safeFetch('user-123');
+ * ```
+ */
+declare function airbag<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: AirbagOptions<TReturn>): WrappedFunction<TArgs, TReturn>;
+
+/**
+ * Creates a pre-configured airbag instance with shared global defaults.
+ *
+ * All functions wrapped through this instance inherit the global options
+ * before applying their own instance-level and execution-level overrides.
+ *
+ * @example
+ * ```ts
+ * const { wrap } = createAirbagInstance({
+ *   retry: { count: 3 },
+ *   adapter: {
+ *     onError: (err) => logger.error(err),
+ *   },
+ * });
+ *
+ * const safeFetch = wrap(fetchUser, { timeout: 5000 });
+ * const user = await safeFetch('user-123');
+ * ```
+ */
+declare function createAirbagInstance(globalOptions?: AirbagOptions): AirbagInstance;
+
+declare class AirbagError extends Error {
+    readonly code: AirbagErrorCode;
+    readonly context: ExecutionContext;
+    constructor(message: string, code: AirbagErrorCode, context: ExecutionContext, options?: {
+        cause?: Error;
+    });
+}
+declare class TimeoutError extends AirbagError {
+    readonly timeout: number;
+    constructor(context: ExecutionContext, timeout: number);
+}
+declare class RetryExhaustedError extends AirbagError {
+    constructor(context: ExecutionContext, cause: Error);
+}
+declare class CircuitOpenError extends AirbagError {
+    constructor(context: ExecutionContext);
+}
+declare class AbortError extends AirbagError {
+    constructor(context: ExecutionContext);
+}
+
+export { AbortError, type AirbagAdapter, AirbagError, type AirbagErrorCode, type AirbagInstance, type AirbagOptions, type AirbagResolvedConfig, type BackoffStrategy, type CircuitBreakerConfig, type CircuitBreakerInstance, type CircuitBreakerState, CircuitOpenError, type ExecutionContext, type Result, type RetryConfig, RetryExhaustedError, TimeoutError, type WrappedFunction, airbag, createAirbagInstance };