@bernierllc/nevar-loop-detector

Static and runtime loop detection for the Nevar rules engine. Analyzes rule sets for potential evaluation cycles at registration time and tracks runtime emit chains.

Installation

npm install @bernierllc/nevar-loop-detector

Usage

import { LoopDetector, ChainTracker } from '@bernierllc/nevar-loop-detector';
import type { Rule } from '@bernierllc/nevar-types';

// Static analysis: detect cycles in rule definitions
const detector = new LoopDetector();
const analysis = detector.analyze(rules);

if (analysis.hasLoops) {
  for (const loop of analysis.loops) {
    console.log('Cycle:', loop.chain.join(' -> '));
    console.log('All rules opted in:', loop.allOptedIn);
    console.log('Rule IDs:', loop.ruleIds);
  }
}

// Runtime tracking: detect cycles during emit chain execution
const tracker = new ChainTracker();

const isCycle = tracker.enter('order.created', 'ctx-123');
if (isCycle) {
  // This trigger+context pair was already seen in this chain
}

console.log(tracker.getDepth()); // current chain depth
tracker.reset(); // clear for next chain

API

LoopDetector

Static loop analysis for rule sets. Builds a graph of trigger-to-deferred-trigger relationships and detects cycles using depth-first search.

• analyze(rules: Rule[]) - Returns a LoopAnalysis with hasLoops: boolean and loops: DetectedLoop[]. Each DetectedLoop contains the chain of trigger keys forming the cycle, ruleIds involved, and whether allOptedIn to looping.

ChainTracker

Runtime cycle detection for emit chains. Tracks (triggerKey, contextId) pairs within a single emit chain.

• enter(triggerKey, contextId) - Records entry into a trigger evaluation. Returns true if a cycle is detected (pair already seen), false on first occurrence
• getDepth() - Returns the current chain depth
• reset() - Clears all recorded entries and resets depth

LoopDetectorError

Error class for loop detection failures. Extends Error with code and context properties.

Integration Documentation

Logger Integration

This package does not integrate with @bernierllc/logger. As a core package, logger integration is optional and not included by default. Consumers should handle logging at the service layer.

NeverHub Integration

This package does not integrate with @bernierllc/neverhub-adapter. As a core package, NeverHub integration is not applicable. NeverHub registration should be handled by service-layer packages that compose this package.

License

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