lllguard

Github npm

Lightweight Circuit Breaker for Node.js (Zero Dependencies)
의존성 제로, 시스템 셧다운을 막아주는 초경량 서킷 브레이커.

⚡ Features

• 📦 ESM Native Only: Designed exclusively for modern ECMAScript Modules (import/export).
• 🛡️ Fail Fast Protection: Prevents cascading failures by blocking requests immediately when external services are down.
• 🔄 Auto Recovery: Automatically tests the connection after a timeout (Half-Open state) and restores traffic if successful.

🚀 Installation / 설치

npm install lllguard

⚠️ Prerequisite / 필수 조건: This package is ESM-only. Ensure "type": "module" is set in your package.json.

본 패키지는 ESM 전용입니다. package.json에 "type": "module"이 설정되어 있어야 합니다.

🧠 State Machine / 상태 머신

LLLGuard operates on three core states:

• 🟢 CLOSED (정상): All requests pass through normally. (모든 요청 정상 통과)

• 🔴 OPEN (차단): External API is failing. All requests are rejected instantly to save resources. (에러 폭주로 인한 차단. 요청 즉시 거절)

• 🟡 HALF_OPEN (정찰): After a timeout, allows one request to test if the external API has recovered. (차단 시간 종료 후, 상태 복구를 위해 한 번 찔러보는 대기 모드)

💻 Usage / 사용법

🇺🇸 English Guide

Wrap your fragile async functions (like API calls) with LLLGuard. If it fails consistently, the circuit will OPEN and protect your server.

import { LllGuard, CircuitBreakerError } from 'lllguard';

// Circuit opens after 5 failures, recovers after 10 seconds.
const guard = new LllGuard({ 
  failureThreshold: 5, 
  recoveryTimeout: 10000 
});

try {
  const data = await guard.execute(async () => {
    return await fetch('[https://unstable-api.com/data](https://unstable-api.com/data)');
  });
  console.log(data);
} catch (error) {
  if (error instanceof CircuitBreakerError) {
    console.error("Blocked by lll-guard. Wait for recovery.");
  } else {
    console.error("API Error:", error.message);
  }
}

🇰🇷 한국어 가이드

불안정한 비동기 함수(외부 API 호출 등)를 LLLGuard로 감싸서 실행하세요. 에러가 연속으로 발생하면 차단기가 내려가고 내 서버의 리소스를 보호합니다.

import { LllGuard, CircuitBreakerError } from 'lllguard';

// 5번 실패하면 차단기를 내리고, 10초(10000ms) 뒤에 복구를 시도합니다.
const guard = new LllGuard({ 
  failureThreshold: 5, 
  recoveryTimeout: 10000 
});

try {
  const data = await guard.execute(async () => {
    return await fetch('[https://unstable-api.com/data](https://unstable-api.com/data)');
  });
  console.log(data);
} catch (error) {
  if (error instanceof CircuitBreakerError) {
    console.error("차단기가 내려가 요청이 거절되었습니다.");
  } else {
    console.error("API 호출 중 에러 발생:", error.message);
  }
}