npm package: @ron2395/service-fuse
Description: A lightweight, event-driven circuit breaker for async dependencies like services, databases, queues, and SDKs.
Author: ron2395
Latest version: 0.2.0

# service-fuse

A lightweight and flexible circuit breaker for async dependencies (services, databases, queues, SDKs)

This library is built for real systems: APIs that sometimes fail, partial outages,
maintenance windows, and the need to observe what is happening without guessing.

It is intentionally simple on the surface and flexible underneath.

---

## Why this exists

Most circuit breaker libraries are either too opinionated, hard to observe,
hard to extend, or unsafe in strict TypeScript.

This one is designed to be predictable, observable, testable,
and safe in both JavaScript and TypeScript.

No background threads.
No magic retries.
No hidden state.

---

## Features

- Window‑based failure tracking (default)
- Pluggable failure tracking strategies
- In‑memory store by default (custom stores supported)
- Half‑open / probe recovery
- Manual trip support
- Structured events for logging & metrics
- First‑class TypeScript support
- Zero‑config JavaScript usage

---

## Installation

```bash
npm install @ron2395/service-fuse
```

---

## Basic usage

```ts
import { createCircuitBreaker } from '@ron2395/service-fuse';

const breaker = createCircuitBreaker({
  config: {
    failureThreshold: 10,
    failureWindow: 60_000,
    openWindowMs: 120_000,
    probeAfterMs: 30_000,
    requiredSuccessStreak: 3,
    // evictionTTL: 10 * 60000 //optional
  },
});

await breaker.execute('identifier', async () => {
  return callService();
});
```

---

## Handling open circuits

When a circuit opens, execution is short-circuited and a CircuitOpenError is thrown.

```ts
import { CircuitOpenError } from '@ron2395/service-fuse';

try {
  await breaker.execute('identifier', callService);
} catch (err) {
  if (err instanceof CircuitOpenError) {
    console.log('Circuit open until:', new Date(err.openUntil));
    return;
  }
  throw err;
}
```

### CircuitOpenError

```ts
class CircuitOpenError extends Error {
  identifier: string;
  openUntil: number;
  reason: 'THRESHOLD' | 'PROBE_FAILURE' | 'MANUAL' | 'POLICY';
}
```

---

## Events & Observability

The breaker emits structured events for every important state and transition.

`reason` indicates why a circuit is unavailable (threshold breach, probe failure, manual override, or policy decision) and is consistent across open, short-circuit events, and CircuitOpenError.

Internally, the breaker also tracks how a circuit was opened (e.g. threshold breach vs manual vs policy), but this detail is not a part of the public API.

### Subscribing to events
```ts
const breaker = createCircuitBreaker({
  config,
  onEvent(event) {
    switch (event.type) {
      case 'open':
        console.log('Circuit opened', event.identifier, event.openUntil);
        break;

      case 'failure':
        console.log('Failure count', event.failureCount);
        break;

      case 'short_circuit':
        console.log('Short-circuited until', event.openUntil);
        break;
    }
  },
});
```

### Event Types
All events include:
```ts
{
  identifier: string;
  timestamp: number;
}
```
- attempt
```ts
{
  type: 'attempt';
  wasProbe: boolean;
}
```
- success
```ts
{
  type: 'success';
  wasProbe: boolean;
}
```
- failure
```ts
{
  type: 'failure';
  failureCount: number;
  wasProbe: boolean;
}
```
- open
```ts
{
  type: 'open';
  reason: 'THRESHOLD' | 'PROBE_FAILURE' | 'MANUAL' | 'POLICY';
  openUntil: number;
  failureCount: number;
  from: 'closed' | 'half_open';
}
```
- half_open
```ts
{
  type: 'half_open';
  from: 'open';
}
```
- close
```ts
{
  type: 'close';
  from: 'half_open' | 'open';
}
```
- short_circuit
```ts
{
  type: 'short_circuit';
  openUntil: number;
  reason: 'THRESHOLD' | 'PROBE_FAILURE' | 'MANUAL' | 'POLICY';
}
```

---

## Manual Trip
You can force-open a circuit as needed:

### Signature
```ts
tripImmediately(
  identifier: CircuitKey,
  opts?: {
    reason?: "MANUAL" | "POLICY";
  }
): void
```

### Manual trip (default behavior)
```ts
breaker.tripImmediately('identifier') //reason = 'MANUAL'
```

### Policy-driven trip
```ts
breaker.tripImmediately('identifier', { reason: 'POLICY' })  //reason = 'POLICY'
```

This:
- Opens the circuit immediately.
- Bypasses all counters, thresholds and retry logic.
- Emits an open event.
- Prevents execution until recovery.

---

## Probe/Recovery Behavior

When a circuit opens:
1. Requests are short-circuited.
2. After probeAfterMs, the circuit enters half-open.
3. One request is allowed as a probe.
4. If probe succeeds → circuit closes.
5. If probe fails → circuit stays open.
6. Probe behavior is customizable via config.

---

## Custom failure logic

By default, every error counts as a failure in a rolling time window.

However, this is customizable.

### Example: only fail on 5xx

```ts
await breaker.execute('identifier', async () => {
  const res = await callService();
  if (res.status >= 500) {
    throw new Error('Server error');
  }
  return res;
});
```

### Advanced: custom failure tracker

```ts
createCircuitBreaker({
  config,
  createFailureTracker: (cfg) => new WindowFailureTracker(cfg),
});
```

- Any tracker implementing:
```ts
interface FailureTracker {
  recordFailure(timestamp: number): void;
  recordSuccess(timestamp: number): void
  shouldTrip(timestamp: number): boolean;
  reset(): void;
}
```

---

## Lazy Eviction

Inactive circuit identifiers can be automatically evicted from memory after a configurable TTL.
Eviction is lazy (checked on access) and does not emit events.

Enable via `evictionTTL` in config (disabled by default).

---

## Stores

A store is responsible for persisting circuit state per identifier. Circuit state storage is pluggable.

A store must:
- return the same state object for a given identifier
- preserve state across calls
- not mutate state unexpectedly

```ts
import { createCircuitBreaker, MemoryStore } from '@ron2395/service-fuse';

createCircuitBreaker({
   config,
   store: new MemoryStore(), //default
})
```

Available options are:
- Memory Store (default).
- Hybrid Store (Redis for state + Memory for failures)
- Custom Store (Own implementation)

### Custom Store


> [!NOTE]
> The default MemoryStore is suitable for single-process usage.

> [!WARNING]
> For multi-process or distributed systems, implement a custom store (e.g. Redis-backed).

> [!TIP]
> A distributed store implementation will be added to future versions.

---

## JavaScript Support

Out of the box support for JavaScipt:

```js
const { createCircuitBreaker } = require('@ron2395/service-fuse');

const breaker = createCircuitBreaker({ config });

breaker.execute('identifier', async () => {
  return callService();
});
```

---

## License

MIT