@bernierllc/nevar-lifecycle-events

Typed lifecycle event emitter for observability hooks in the Nevar rules engine. Provides strongly-typed events for trigger processing, rule evaluation, action execution, and loop/circuit management.

Installation

npm install @bernierllc/nevar-lifecycle-events

Usage

import { NevarLifecycleEmitter } from '@bernierllc/nevar-lifecycle-events';

const lifecycle = new NevarLifecycleEmitter();

// Subscribe to rule match events
lifecycle.on('rule.matched', (payload) => {
  console.log('Rule matched:', payload);
});

// Subscribe to action failures
lifecycle.on('action.failed', (payload) => {
  console.error('Action failed:', payload);
});

// One-time listener for first loop detection
lifecycle.once('loop.detected', (payload) => {
  console.warn('Loop detected:', payload);
});

// Emit events from the engine pipeline
await lifecycle.emit('trigger.received', { triggerKey: 'user.created', payload: { email: '[email protected]' } });
await lifecycle.emit('rule.matched', { ruleId: 'rule-123', triggerKey: 'user.created' });

// Clean up
lifecycle.removeAllListeners();

API

NevarLifecycleEmitter

Typed event emitter wrapping @bernierllc/event-emitter with a focused API for Nevar lifecycle events.

• on<T>(event: NevarLifecycleEventType, handler: LifecycleHandler<T>): void - Subscribe to a lifecycle event
• off<T>(event: NevarLifecycleEventType, handler: LifecycleHandler<T>): void - Unsubscribe a handler
• once<T>(event: NevarLifecycleEventType, handler: LifecycleHandler<T>): void - Subscribe for a single firing
• emit<T>(event: NevarLifecycleEventType, payload: T): Promise<void> - Emit an event to all handlers
• listenerCount(event: NevarLifecycleEventType): number - Get listener count for an event
• removeAllListeners(event?: NevarLifecycleEventType): void - Remove listeners for one or all events

LIFECYCLE_EVENT_TYPES

Readonly array of all valid lifecycle event type strings, useful for validation and iteration:

trigger.received, trigger.invalid, context.built, rule.evaluating, rule.matched, rule.skipped, action.executing, action.executed, action.failed, action.retrying, chain.completed, loop.detected, loop.started, loop.heartbeat, loop.killed, circuit.tripped

NevarLifecycleError

Custom error class thrown when lifecycle event emission fails. Chains the original error via cause.

NevarLifecycleEventType (type)

Union type of all valid lifecycle event strings.

LifecycleHandler<T> (type)

Handler function signature: (payload: T) => void | Promise<void>.

Integration Documentation

Logger Integration

This package integrates with @bernierllc/logger for structured logging. Lifecycle event handlers can use logger to record observability data such as rule evaluation timings, action execution traces, and loop detection alerts.

NeverHub Integration

This package supports optional integration with @bernierllc/neverhub-adapter. When NeverHub is available, the lifecycle emitter can be registered for centralized event monitoring and cross-service observability. Graceful degradation is supported when NeverHub is not present.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.