{"id":17377,"library":"supra-http","title":"Supra HTTP Client with Circuit Breaking","description":"Supra-http is a fast HTTP client for Node.js that integrates a circuit breaker pattern to enhance resilience in distributed systems. It is built on top of the 'opossum' library for robust circuit breaking capabilities, allowing it to gracefully handle failures in remote services and prevent cascading outages. The package is currently at version 1.8.5. While the project description mentions forthcoming documentation, the last update on GitHub was in March 2023, and the last npm publish was also over a year ago, suggesting a maintenance or possibly abandoned status rather than active development. Its key differentiators include built-in circuit breaking and reported performance advantages over alternatives like `request` and `requestretry` according to its benchmarks. It supports gzip and brotli decompression for Node.js versions 10.17.x and above.","status":"maintenance","version":"1.8.5","language":"javascript","source_language":"en","source_url":"https://github.com/Trendyol/supra","tags":["javascript","typescript"],"install":[{"cmd":"npm install supra-http","lang":"bash","label":"npm"},{"cmd":"yarn add supra-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add supra-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core circuit breaking logic and functionality.","package":"opossum","optional":false}],"imports":[{"note":"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.","wrong":"const SupraClient = require('supra-http');","symbol":"SupraClient","correct":"import SupraClient from 'supra-http';\nconst client = new SupraClient();"},{"note":"The primary interaction is via the `request` method on an instantiated client object. There is no direct named export for `request`.","symbol":"request","correct":"import SupraClient from 'supra-http';\nconst client = new SupraClient();\nclient.request('apiCallName', 'https://my-api/endpoint', { method: 'get' });"},{"note":"Since the library ships TypeScript types, importing type definitions directly is good practice for type-checking when configuring the circuit breaker.","symbol":"CircuitBreakerOptions","correct":"import type { CircuitBreakerOptions } from 'supra-http';"}],"quickstart":{"code":"import SupraClient from 'supra-http';\n\nconst client = new SupraClient();\n\nasync function fetchData() {\n  try {\n    // Example GET request with basic circuit breaking options\n    const response = await client.request('myApiGetCall', 'https://jsonplaceholder.typicode.com/todos/1', {\n      method: 'get',\n      json: true,\n      timeout: 2000, // Request timeout\n      errorThresholdPercentage: 50, // 50% errors to trip the circuit\n      resetTimeout: 10000, // How long to wait before trying again (half-open state)\n      enabled: true // Enable circuit breaker for this call\n    });\n    console.log('API Response:', response.json);\n  } catch (error) {\n    console.error('API Call Failed or Circuit Tripped:', error.message);\n    // Implement fallback logic here if needed\n  }\n}\n\nfetchData();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.8.5"},{"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.","message":"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.","severity":"breaking","affected_versions":"<=1.8.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Error: CircuitBreaker is open"},{"fix":"Ensure you are instantiating the client: `import SupraClient from 'supra-http'; const client = new SupraClient(); client.request(...)`.","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()`.","error":"TypeError: client.request is not a function"},{"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.","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.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: connect ETIMEDOUT"}],"ecosystem":"npm","meta_description":null}