Interfaces & Types
This page documents the interfaces and type aliases exported by Zenvark.
Interfaces
BreakerStrategy
Interface for implementing custom breaker strategies.
interface BreakerStrategy {
shouldOpenCircuit(events: CallResultEvent[]): boolean;
}
See Breaker Strategies for implementation examples.
BackoffStrategy
Interface for implementing custom backoff strategies.
interface BackoffStrategy {
getDelayMs(attempt: number): number;
}
See Backoff Strategies for implementation examples.
Telemetry
Interface for telemetry integrations, registered globally with registerZenvarkTelemetry() or per instance with the telemetry option of CircuitBreaker and AdaptiveSemaphore. All methods are optional. @zenvark/prom and @zenvark/otel implement it for Prometheus and OpenTelemetry.
interface Telemetry {
// Circuit breaker
executeCall?<T>(params: ExecuteCallParams<T>): Promise<T>;
executeHealthCheck?(params: ExecuteHealthCheckParams): Promise<void>;
onBreakerInit?(event: { breakerId: string }): void;
onCallEnd?(event: CallEndEvent): void;
onBlockedRequest?(event: { breakerId: string }): void;
onHealthCheckEnd?(event: HealthCheckEndEvent): void; // not for cancelled checks
onStateChange?(event: { breakerId: string; state: CircuitState }): void; // leader only
onRoleChange?(event: RoleChangeEvent): void;
// Adaptive semaphore
onSemaphoreInit?(event: { semaphoreId: string }): void;
onAcquire?(event: AcquireEvent): void;
onRelease?(event: ReleaseEvent): void;
onLimitChange?(event: LimitChangeEvent): void;
onThrottle?(event: { semaphoreId: string }): void;
}
type ExecuteCallParams<T> = {
breakerId: string;
execute: () => Promise<T>;
};
type ExecuteHealthCheckParams = {
breakerId: string;
type: HealthCheckType;
signal: AbortSignal; // aborted when the check is cancelled
execute: () => Promise<void>;
};
type CallEndEvent = {
breakerId: string;
result: CallResult;
durationMs: number;
};
type HealthCheckEndEvent = {
breakerId: string;
type: HealthCheckType;
result: CallResult;
durationMs: number;
};
type RoleChangeEvent = {
breakerId: string;
role: CircuitRole;
state: CircuitState;
};
type AcquireEvent = {
semaphoreId: string;
class?: string;
result: AcquireResult;
waitMs: number;
};
type ReleaseEvent = {
semaphoreId: string;
class?: string;
outcome: LeaseOutcome;
heldMs: number;
};
type LimitChangeEvent = {
semaphoreId: string;
limit: number;
direction: LimitChangeDirection;
};
executeCall and executeHealthCheck should call execute synchronously (before any await), so the work starts inside the integration's context. The breaker settles with the work's own result as soon as it is known, without waiting for the integration: the work runs exactly once even if execute is not called or called twice, and a rejection other than the work's own error is reported through onError. Errors thrown by on* methods are reported through onError too.
See Custom Telemetry Integration for an example.
TelemetryOptions
Per-instance telemetry settings, passed as the telemetry option of CircuitBreaker or AdaptiveSemaphore.
type TelemetryOptions = {
isEnabled?: boolean; // false disables all integrations for this instance
integrations?: Telemetry | Telemetry[]; // replaces the global integrations
};
See Telemetry for usage.
BreakerMetricsRecorder (deprecated)
Interface behind the deprecated metrics option. Implement Telemetry instead; see Migrating from metrics.
interface BreakerMetricsRecorder {
initialize?(breakerId: string): void;
recordCall(params: RecordCallParams): void;
recordBlockedRequest(params: RecordBlockedRequestParams): void;
recordHealthCheck(params: RecordHealthCheckParams): void;
recordStateChange?(params: RecordStateChangeParams): void;
clearState?(breakerId: string): void;
}
Type Aliases
CallResultEvent
Represents a call execution event with timing and outcome information.
type CallResultEvent = {
id: string; // Unique identifier for this call event (Redis stream ID)
callResult: CallResult; // The outcome of the call (SUCCESS or FAILURE)
timestamp: number; // Unix timestamp in milliseconds when the call occurred
};
Used in breaker strategies to evaluate call history and determine if the circuit should open.
RecordCallParams
Parameters for recording a call execution.
type RecordCallParams = {
breakerId: string;
result: CallResult;
durationMs: number;
};
Used by BreakerMetricsRecorder.recordCall() to record successful or failed calls.
RecordBlockedRequestParams
Parameters for recording a blocked request.
type RecordBlockedRequestParams = {
breakerId: string;
};
Used by BreakerMetricsRecorder.recordBlockedRequest() when requests are blocked due to an open circuit.
RecordHealthCheckParams
Parameters for recording a health check execution.
type RecordHealthCheckParams = {
breakerId: string;
type: HealthCheckType;
result: CallResult;
durationMs: number;
};
Used by BreakerMetricsRecorder.recordHealthCheck() to record health check attempts.