@bernierllc/nevar-loop-controller

Runtime loop lifecycle management for the Nevar rules engine. Controls opt-in infinite loop execution with heartbeat monitoring and concurrency limits.

Installation

npm install @bernierllc/nevar-loop-controller

Usage

import { LoopController } from '@bernierllc/nevar-loop-controller';

const controller = new LoopController({
  allowInfiniteLoops: true,
  maxConcurrentLoops: 5,
  heartbeatIntervalMs: 5000,
  maxMissedHeartbeats: 3,
});

// Check if loops are allowed
if (controller.isAllowed()) {
  const handle = controller.startLoop('order.monitor');

  if (handle) {
    // Send heartbeats during execution
    controller.heartbeat(handle.id);

    // Inspect loop state
    const state = controller.inspect(handle.id);

    // Pause/resume
    controller.pause(handle.id);
    controller.resume(handle.id);

    // Complete when done
    controller.complete(handle.id);
  }
}

// Kill stale loops that missed heartbeats
const killedIds = controller.checkHeartbeats();

// List all active loops
const active = controller.list();

API

LoopController

Manages the lifecycle of opt-in infinite loops with heartbeat-based health monitoring.

Constructor: new LoopController(config?: Partial<LoopConfig>)

Default config: allowInfiniteLoops: false, maxConcurrentLoops: 0, heartbeatIntervalMs: 5000, maxMissedHeartbeats: 3

• isAllowed() - Returns true if loops are enabled and concurrency limit is greater than zero
• startLoop(triggerKey) - Creates a new loop handle. Returns null if loops are not allowed or at concurrency limit
• heartbeat(loopId) - Records a heartbeat and increments iteration count. Returns false if loop not found or not running
• kill(loopId) - Forcefully terminates a loop
• pause(loopId) - Pauses a running loop
• resume(loopId) - Resumes a paused loop
• complete(loopId) - Marks a loop as completed
• list() - Returns all active (running or paused) loop handles
• inspect(loopId) - Returns the full LoopHandle for a given loop, or null
• checkHeartbeats() - Kills loops that have missed too many heartbeats. Returns array of killed loop IDs
• getConfig() - Returns a copy of the current configuration

LoopControllerError

Error class for loop controller 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.