nodeshift

opossum: Add Circuit Breakers to Node.js Functions

Opossum is a JavaScript circuit-breaker library for Node.js asynchronous functions. It monitors failures and timeouts, fails fast when a service is unhealthy, and can run a fallback while the circuit is open.

QuietJavaScriptApache-2.0Node.jsLibraryDeveloper Tools
Stars
1.7k
Forks
115
Stars, last 30 days
+1
Last commit
3 months ago
Contributors
44

Our take

Quietno commits in the last 90 days

Health score

37/100

How it is scored
Activity
31
Community
74
Issues
21
Pull requests
20

+1 stars in the last 30 days

Opossum is a focused circuit-breaker library with a recent release and a broad contributor base, though its measured activity is currently quiet.

Good fit if

  • You need circuit breaking, timeouts, and optional fallbacks for asynchronous Node.js work.
  • Your runtime is a supported Node.js version, and the event and statistics APIs suit your monitoring needs.
  • You want an Apache-2.0-licensed library with Prometheus or Hystrix metrics available through companion projects.

Look elsewhere if

  • Your runtime is older than Node.js 22 or outside the versions supported by the package.
  • You need a project with recent ongoing commits or recent issue and pull-request activity; none was recorded in the measured 90-day period.
  • You need a circuit-breaker solution for a platform other than Node.js or a browser bundle.
All health signals
Last commit2026-08-21 (3 months ago)
Commits, last 90 days0
Releases, last 12 months1 (latest v10.0.0, 2026-06-24)
Contributors44 (top contributor: 33% of commits)
Issues closed, last 90 days0
Pull requests merged, last 90 days0
Project age10 years

Checked on 2026-11-20 with the GitHub API.

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

1,692

Forks

115

Change since Nov 19, 2026: -1 stars·0 forks

Overview

Opossum is a JavaScript circuit-breaker library for Node.js. It wraps asynchronous functions, monitors their outcomes, and fails fast when failures cross a configured threshold, helping applications avoid repeatedly waiting on an unhealthy dependency. A fallback function can provide an alternate result while the circuit is open.

It is aimed at Node.js applications that call unreliable services or perform other operations that may fail or stall. The library also provides breaker events and statistics for application-level handling and monitoring, and supports browser bundling as well as Node.js use.

Key Features

  • Opens a circuit when the observed failure rate crosses a configurable threshold, then allows a test call after a reset timeout.
  • Applies timeouts to protected actions and supports AbortController signals to cancel ongoing requests.
  • Runs optional fallback functions when calls fail or the breaker is open.
  • Emits events for successes, failures, timeouts, state transitions, fallbacks, and other breaker activity.
  • Tracks rolling statistics, with helpers to export and restore breaker state and status.
  • Supports call coalescing and caching to reduce repeated work for equivalent calls.
  • Provides integrations for Prometheus and the Hystrix Dashboard through companion modules.

Use Cases

  • A Node.js API team can guard calls to an unreliable upstream service and fail quickly rather than letting requests wait on repeated failures.
  • An application can use fallbacks to return a degraded response when a network or disk operation is unavailable.
  • Teams running serverless or ephemeral containers can export and restore breaker state or statistics across instances.
  • A browser application can bundle Opossum to guard AJAX calls against slow or failing endpoints.

What you need

Detected in the repository

  • Node.js ^26 || ^24 || ^22 (from package.json)
  • A test suite and automated checks on GitHub Actions

License in plain words

Apache-2.0permissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the license, the NOTICE file and a note of your changes
  • Share your changes: no
  • Includes an explicit patent grant from the contributors:

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

npm install opossum

Wrap an asynchronous function in a CircuitBreaker and call it with breaker.fire(). See the README and documentation for configuration and examples.

Considerations

  • The project is marked Quiet because it had no commits in the measured 90-day period. It did publish a release within the last year, and its contributor base is not concentrated in one person.
  • The measured period also showed no issues closed or pull requests merged, so adopters should assess whether the current maintenance pace meets their needs.
  • The package requires Node.js versions ^22, ^24, or ^26 according to its package metadata.
  • Opossum reports failures based on the protected action. With Fetch, HTTP error responses do not reject automatically, so the action must check response status and throw when appropriate.
  • The README notes that repeated breaker creation can contribute to EventEmitter listener warnings, and recommends shutting down breakers when they are no longer needed.
  • The README links TypeScript definitions maintained in DefinitelyTyped rather than presenting typings as part of this repository.

Found this useful?

Share it with someone who would like opossum.