{"id":31890430,"url":"https://github.com/metcoder95/fuse-box","last_synced_at":"2026-01-12T09:39:38.602Z","repository":{"id":314966223,"uuid":"1052260632","full_name":"metcoder95/fuse-box","owner":"metcoder95","description":"Easy to use resiliency library for all kind of workloads.","archived":false,"fork":false,"pushed_at":"2025-12-15T08:03:20.000Z","size":43,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-16T14:30:56.266Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metcoder95.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yaml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"metcoder95"}},"created_at":"2025-09-07T18:19:16.000Z","updated_at":"2025-09-07T18:19:22.000Z","dependencies_parsed_at":"2025-09-15T23:42:13.112Z","dependency_job_id":"6a15c98c-8ab8-4d0f-8607-e3a9289e2b3e","html_url":"https://github.com/metcoder95/fuse-box","commit_stats":null,"previous_names":["metcoder95/fuse-box"],"tags_count":0,"template":false,"template_full_name":"metcoder95/lib_template","purl":"pkg:github/metcoder95/fuse-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffuse-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffuse-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffuse-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffuse-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metcoder95","download_url":"https://codeload.github.com/metcoder95/fuse-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffuse-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T07:48:07.264Z","updated_at":"2026-01-12T09:39:38.596Z","avatar_url":"https://github.com/metcoder95.png","language":"JavaScript","funding_links":["https://github.com/sponsors/metcoder95"],"categories":[],"sub_categories":[],"readme":"# `@metcoder95/fusebox`\n\n\u003e Utilitary library for applying resiliency workflows to protect workloads.\n\n`fusebox` allows you to wrap functions (workloads) with protective patterns like **Retry**, **Fallback**, and **Circuit Breaker**. These patterns can be composed to build robust and resilient applications.\n\n## Installation\n\n```bash\nnpm install @metcoder95/fusebox\n```\n\n## Usage\n\nThe `FuseBox` class is the main entry point. Use it to compose workflows and wrap your target functions.\n\n### Quick Start\n\n```javascript\nimport { FuseBox, Workflows } from '@metcoder95/fusebox';\n\nconst fusebox = new FuseBox();\n\n// A workload that simulates failure\nconst unstableWorkload = async () =\u003e {\n  if (Math.random() \u003e 0.5) throw new Error('Random connection failure');\n  return 'Success!';\n};\n\n// 1. Configure the pipeline\n// Order matters: workflows are added sequentially, wrapping the previous ones.\n// Here: Fallback wraps Retry, which wraps the Workload.\n// [Fallback] -\u003e [Retry] -\u003e [Workload]\nconst protectedWorkload = fusebox\n  .addWorkflows(\n    Workflows.Retry({\n      retries: 3,\n      delay: 100,\n    }),\n    Workflows.Fallback({\n      value: 'Service unavailable, please try again later.',\n    })\n  )\n  .protect(unstableWorkload);\n\n// 2. Execute\nconst result = await protectedWorkload();\nconsole.log(result);\n```\n\n## Workflow Composition\n\nWorkflows are applied in the order they are passed to `addWorkflows`. Each new workflow **wraps** the previously composed pipeline.\n\n**Example:**\n\n```javascript\nfusebox.addWorkflows(Retry, Fallback);\n```\n\nStructure: `Fallback(Retry(Workload))`\n\nExecution flow:\n\n1.  **Fallback** starts.\n2.  **Fallback** executes **Retry**.\n3.  **Retry** executes the **Workload**.\n4.  If **Workload** fails:\n    - **Retry** intercepts the error and retries.\n    - If retries perform successfully, **Fallback** receives success.\n    - If retries are exhausted, **Retry** throws.\n5.  **Fallback** catches the final error from **Retry** and provides the fallback value.\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Fallback\n    participant Retry\n    participant Workload\n\n    User-\u003e\u003eFallback: Call\n    Fallback-\u003e\u003eRetry: Call\n    Retry-\u003e\u003eWorkload: Call\n\n    opt Failure\n        Workload--xRetry: Error\n        Retry-\u003e\u003eWorkload: Retry 1..N\n    end\n\n    alt Success\n        Workload--\u003e\u003eRetry: Result\n        Retry--\u003e\u003eFallback: Result\n    else Failure (Retries Exhausted)\n        Workload--xRetry: Error\n        Retry--xFallback: Error\n        Note right of Fallback: Returns Fallback Value\n    end\n\n    Fallback--\u003e\u003eUser: Final Result\n```\n\n## Available Workflows\n\n### Retry\n\nRetries the workload upon failure.\n\n```javascript\nWorkflows.Retry({\n  retries: 3, // Max number of retries (default: 3)\n  delay: 200, // Initial delay in ms (default: 200)\n  backoff: 2, // Exponential backoff factor (default: 2)\n  maxDelay: 10000, // Max delay cap in ms (default: 10000)\n});\n```\n\n### Fallback\n\nProvides a static value, or executes a function when the workflow fails.\n\n```javascript\nWorkflows.Fallback({\n  value: 'Backup Value', // Can be a value, a synchronous function, or a promise-returning function\n  handleAbort: false, // If true, fallback is triggered even if the workload was aborted (default: false)\n});\n```\n\n### Circuit Breaker\n\nPrevents execution of a workload that is failing repeatedly, allowing the system to recover.\n\n- **Closed**: Requests go through. Failures count towards the threshold.\n- **Open**: Request fails immediately with an error. Stays open for `timeout` ms.\n- **Half-Open**: Allows limited requests to test if the system recovered.\n\n```javascript\nWorkflows.CircuitBreaker({\n  attempts: 3,        // Con consecutive failures to open the circuit (default: 3)\n  successAttempts: 1, // Consecutive successes needed to close the circuit (default: 1)\n  timeout: 1000       // Duration the circuit stays Open before testing (default: 1000 ms)\n  weight: 1       // Ratio sampling to aplying a custom discrete distribution. It should be between 0 and 1\n})\n```\n\n## Custom Workflows\n\nYou can create your own workflows to implement custom logic such as logging, metrics collection, or specialized error handling.\n\nA workflow matches the signature:\n`(next: Workflow) =\u003e (workload: Function, handler: FuseBoxWorkloadHandler) =\u003e void`\n\nThe `handler` object allows you to intercept the execution lifecycle:\n\n- `onStart(abort)`: Called when execution begins.\n  - The `abort` function can be called to cancel execution of the workload.\n- `onComplete(result)`: Called on success.\n- `onError(error)`: Called on failure.\n\n**Example: Logging Workflow**\n\n```javascript\n/*\n  The `next` function represents the next step in the pipeline.\n  You call it to proceed with the execution.\n*/\nconst LoggingWorkflow = (next) =\u003e (workload, handler) =\u003e {\n  // Call the next workflow (or the workload itself)\n  // We pass a proxy handler to intercept events\n  next(workload, {\n    onStart(abort) {\n      console.log('Starting execution...');\n      // Make sure to propagate the event!\n      handler.onStart(abort);\n    },\n    onComplete(result) {\n      console.log('Execution success');\n      handler.onComplete(result);\n    },\n    onError(error) {\n      console.error('Execution failed', error);\n      handler.onError(error);\n    },\n  });\n};\n\n// Usage\nfusebox.addWorkflows(LoggingWorkflow);\n```\n\n## API Reference\n\n### `FuseBox`\n\nThe orchestrator class.\n\n- `constructor()`: Initializes a new FuseBox instance.\n- `addWorkflows(...workflows)`: Adds single or multiple workflows to the chain.\n  - `workflows`: Array of workflow functions or variable arguments.\n- `protect(workload)`: Wraps a function with the configured workflows.\n  - Returns: A version of the function with the workflows applied.\n\n### TypeScript Support\n\n`fusebox` ships with TypeScript definitions. Types are exported for direct usage:\n\n```typescript\nimport {\n  FuseBox,\n  Workflows,\n  RetryWorkflowOptions,\n  FallbackWorkflowOptions,\n  CircuitBreakerWorkflowOptions,\n  FuseBoxWorkloadHandler,\n  FuxeBoxWorkloadOnError,\n  FuxeBoxWorkloadOnComplete,\n  FuseBoxAbortCallback,\n  FuseBoxWorkload,\n  FuseBoxWorkflow\n} from 'fusebox';\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetcoder95%2Ffuse-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetcoder95%2Ffuse-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetcoder95%2Ffuse-box/lists"}