Supra HTTP Client with Circuit Breaking

Common errors

• Error: CircuitBreaker is open

  cause The configured failure threshold was met or exceeded, causing the circuit breaker to 'trip' and enter the OPEN state, preventing further requests to the protected service.
  fix This is expected behavior. Implement a `catch` block for `client.request` to handle this error. Provide a graceful fallback mechanism (e.g., returning cached data, a default value, or queuing the request) instead of failing the entire operation. Configure `resetTimeout` to allow the circuit to automatically transition to `HALF_OPEN` state to re-test the service.

• TypeError: client.request is not a function

  cause The `supra-http` client needs to be instantiated before its methods, like `request`, can be called. This error often occurs when attempting to call `supra-http.request()` directly after import without `new SupraClient()`.
  fix Ensure you are instantiating the client: `import SupraClient from 'supra-http'; const client = new SupraClient(); client.request(...)`.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: connect ETIMEDOUT

  cause The underlying HTTP request timed out or failed to connect, and the promise was not handled with a `.catch()` block. This is a common network error or an issue with the target API.
  fix Always chain a `.catch()` method or use `try...catch` with `await` to handle potential network errors and timeouts from `client.request` promises. Adjust the `timeout` option in `client.request` if the default is too aggressive for your target service.

Warnings

• gotcha The README states that for gzip and brotli decompression, Node.js version 10.17.x or higher is required, even though the `engines` field in `package.json` specifies `>=10.16`. This minor version difference can lead to unexpected decompression failures if running on exactly Node.js 10.16.x.
  Fix: Ensure your Node.js environment is at least version 10.17.0 for full decompression support, or consider upgrading to a more recent LTS version of Node.js for better compatibility and security.
• deprecated The package appears to be in maintenance mode, with the last commit on GitHub in March 2023 and the last npm publish around the same time. The README mentions 'Documentation will be released soon,' which is outdated. This indicates limited or no active development, meaning it may not receive updates for newer Node.js versions, security patches, or feature enhancements.
  Fix: For new projects, consider more actively maintained HTTP clients with circuit breaking capabilities or standalone circuit breaker libraries. For existing projects, be aware that you might need to fork or contribute fixes yourself for future compatibility or security issues.
• breaking As `supra-http` relies on `opossum` for its circuit breaking logic, major updates to `opossum` could introduce breaking changes to how circuit breaker options are configured or how events are emitted, potentially affecting `supra-http`'s behavior. The `opossum` library has had releases up to version 9.0.0 (May 2025) since `supra-http`'s last update.
  Fix: Review the `opossum` changelog for any major version updates beyond what `supra-http` was initially built against. If upgrading `supra-http` or its dependencies, thoroughly test circuit breaker behavior, especially configuration options like `errorThresholdPercentage`, `resetTimeout`, and `fallback` functions.

Install

• npm install supra-http npm
• yarn add supra-http yarn
• pnpm add supra-http pnpm

Imports

• SupraClient
  wrong:

  const SupraClient = require('supra-http');

  correct:

  import SupraClient from 'supra-http';
  const client = new SupraClient();

  The README suggests a default export that is then instantiated. For modern Node.js environments supporting ESM, the `import` syntax is preferred. CommonJS `require` might work but is not idiomatic for newer projects.
• request

  import SupraClient from 'supra-http';
  const client = new SupraClient();
  client.request('apiCallName', 'https://my-api/endpoint', { method: 'get' });

  The primary interaction is via the `request` method on an instantiated client object. There is no direct named export for `request`.
• CircuitBreakerOptions

  import type { CircuitBreakerOptions } from 'supra-http';

  Since the library ships TypeScript types, importing type definitions directly is good practice for type-checking when configuring the circuit breaker.

Quickstart

This quickstart demonstrates how to instantiate `supra-http` and make a GET request to a public API with explicit circuit breaker configuration, including error handling for when the circuit trips or the request fails.

import SupraClient from 'supra-http';

const client = new SupraClient();

async function fetchData() {
  try {
    // Example GET request with basic circuit breaking options
    const response = await client.request('myApiGetCall', 'https://jsonplaceholder.typicode.com/todos/1', {
      method: 'get',
      json: true,
      timeout: 2000, // Request timeout
      errorThresholdPercentage: 50, // 50% errors to trip the circuit
      resetTimeout: 10000, // How long to wait before trying again (half-open state)
      enabled: true // Enable circuit breaker for this call
    });
    console.log('API Response:', response.json);
  } catch (error) {
    console.error('API Call Failed or Circuit Tripped:', error.message);
    // Implement fallback logic here if needed
  }
}

fetchData();