zenvark

library1.2.0jsnpmunverified

A distributed circuit breaker coordinated via Redis for high-availability applications. Current stable version is 1.2.0, released as an npm package with TypeScript types. The library uses Redis Streams for state coordination across multiple instances, supports multiple breaker strategies (consecutive, count-based, time-based) and backoff strategies (constant, exponential), includes built-in leader election for health checks, and offers optional Prometheus metrics via @zenvark/prom. It differentiates by focusing on distributed environments with leader election and Redis-backed coordination, unlike single-process circuit breakers.

devops

npm install zenvark

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZENVARK

zenvark

devopsjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CircuitBreaker

✓ import { CircuitBreaker } from 'zenvark'

✗ import CircuitBreaker from 'zenvark'

CircuitBreaker is a named export, not a default export. ESM-only package; no CommonJS support.

ConsecutiveBreaker

✓ import { ConsecutiveBreaker } from 'zenvark'

✗ import { ConsecutiveBreaker } from 'zenvark/strategies'

All breaker strategies are exported from the main package entry, not from subpaths.

CircuitOpenError

✓ import { CircuitOpenError } from 'zenvark'

✗ const CircuitOpenError = require('zenvark').CircuitOpenError

The package is ESM-only since v1.2.0. Using require() will cause a runtime error with Node >=22.

Redis

✓ import { Redis } from 'ioredis'

✗ import { Redis } from 'zenvark'

Redis client is from the separate ioredis package, not part of zenvark.

Creates a distributed circuit breaker using Redis, with consecutive failure threshold, constant backoff, and health check.

import { Redis } from "ioredis"; import { CircuitBreaker, ConsecutiveBreaker, ConstantBackoff, CircuitOpenError, } from "zenvark"; const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379"); const circuitBreaker = new CircuitBreaker({ id: "my-service-api", redis, breaker: new ConsecutiveBreaker({ threshold: 5 }), health: { backoff: new ConstantBackoff({ delayMs: 5000 }), async check(type, signal) { const response = await fetch("https://api.example.com/health", { signal, }); if (!response.ok) throw new Error("Health check failed"); }, }, }); await circuitBreaker.start(); try { const result = await circuitBreaker.execute(async () => { return await fetch("https://api.example.com/data"); }); console.log("Success:", result); } catch (err) { if (err instanceof CircuitOpenError) { console.log("Circuit is open - request blocked"); } } await circuitBreaker.stop();

Debug

Known issues

gotchaioredis must be installed as a separate dependency; zenvark does not bundle a Redis client.

fix

Run 'npm install ioredis' alongside zenvark.

affects: >=1.0.0

breakingThe package is ESM-only since v1.2.0 and does not provide a CommonJS entry. Using require() will fail.

fix

Use import syntax or set 'type': 'module' in package.json. For Node <22, upgrade to Node >=22 or use a previous version.

affects: >=1.2.0

gotchaAll classes (CircuitBreaker, ConsecutiveBreaker, etc.) are named exports, not default exports.

fix

Use import { CircuitBreaker } from 'zenvark' instead of import CircuitBreaker from 'zenvark'.

affects: >=1.0.0

gotchaConstructor options for CircuitBreaker require a Redis instance (ioredis) and a breaker strategy. Missing either will cause runtime errors.

fix

Ensure options.redis is a valid ioredis.Redis instance and options.breaker is one of ConsecutiveBreaker or CountBreaker.

affects: >=1.0.0

deprecatedThe 'backoff' option in health config accepts only ConstantBackoff or ExponentialBackoff instances. Passing a plain object may not work as expected.

fix

Instantiate a backoff strategy explicitly: new ConstantBackoff({ delayMs: 5000 }).

affects: >=1.0.0

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND: Cannot find package 'ioredis' imported from ...

ioredis is not installed or not in node_modules.

fix

Run 'npm install ioredis' to add the required peer dependency.

TypeError: circuitBreaker.start is not a function

Using default import instead of named import: import CircuitBreaker from 'zenvark'

fix

Change to import { CircuitBreaker } from 'zenvark'.

Error: Redis connection error: connect ECONNREFUSED ...

Redis server is not running or connection string is incorrect.

fix

Start Redis server or provide correct REDIS_URL environment variable.

SyntaxError: Cannot use import statement outside a module

The package is ESM-only and running in a CommonJS project without proper configuration.

fix

Add 'type': 'module' to package.json or rename .js files to .mjs.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

ioredisrequiredRequired for Redis communication; must be installed separately as a peer dependency.

Agent activity

23 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/zenvark/zenvark ↗

packagezenvark ↗

homepagehttps://zenvark.github.io/zenvark ↗