@camcima/finita 4.0.0 → 4.1.0

package/dist/index.cjs

@@ -52,6 +52,7 @@ __export(index_exports, {
   ProcessBuilder: () => ProcessBuilder,
   ProcessFinalizedError: () => ProcessFinalizedError,
   ProcessNotFoundError: () => ProcessNotFoundError,
+  QueueLimitExceededError: () => QueueLimitExceededError,
   ReentrancyError: () => ReentrancyError,
   ScoreTransition: () => ScoreTransition,
   SingleProcessDetector: () => SingleProcessDetector,
@@ -256,6 +257,7 @@ var State = class {
       throw new Error(`State "${this.name}" transitions already set`);
     }
     this._transitions = new Set(transitions);
+    Object.freeze(this);
   }
   getName() {
     return this.name;
@@ -306,6 +308,7 @@ var Transition = class {
     this.eventName = eventName;
     this.condition = condition;
     this.weight = weight;
+    Object.freeze(this);
   }
   getTargetState() {
     return this.targetState;
@@ -440,12 +443,20 @@ var ProcessBuilder = class _ProcessBuilder {
         { fromState, toState, conditionName }
       );
     }
+    const weight = options.weight ?? 1;
+    if (!Number.isFinite(weight)) {
+      throw new GraphValidationError(
+        "invalidTransitionWeight",
+        `addTransition from "${fromState}" to "${toState}": weight must be a finite number; got ${String(weight)}`,
+        { fromState, toState, eventName, weight }
+      );
+    }
     this.transitionSpecs.push({
       fromState,
       toState,
       eventName,
       condition: options.condition ?? null,
-      weight: options.weight ?? 1
+      weight
     });
     return this;
   }
@@ -453,7 +464,6 @@ var ProcessBuilder = class _ProcessBuilder {
     if (this.built) {
       throw new ProcessFinalizedError(this.processName);
     }
-    this.built = true;
     this.validateInitialState();
     this.validateTransitionEndpoints();
     this.validateNoConflictingDuplicates();
@@ -464,6 +474,7 @@ var ProcessBuilder = class _ProcessBuilder {
       this.validateOrphans(finalStates, initialName);
     }
     const initialState = finalStates.get(initialName);
+    this.built = true;
     return new Process(
       INTERNAL_CONSTRUCTION_KEY,
       this.processName,
@@ -708,6 +719,9 @@ var OperationQueue = class {
   isEmpty() {
     return this.items.length === 0;
   }
+  size() {
+    return this.items.length;
+  }
 };
 
 // src/filter/ActiveTransitionFilter.ts
@@ -772,6 +786,17 @@ var ReentrancyError = class extends FinitaError {
   }
 };
 
+// src/error/QueueLimitExceededError.ts
+var QueueLimitExceededError = class extends FinitaError {
+  code = "queueLimitExceeded";
+  constructor(limit, eventName) {
+    super(
+      `${eventName === null ? "checkTransitions()" : `triggerEvent("${eventName}")`} rejected: the operation queue already holds ${limit} pending operation(s) (maxQueueLength = ${limit}).`
+    );
+    this.name = "QueueLimitExceededError";
+  }
+};
+
 // src/Statemachine.ts
 var Statemachine = class {
   subject;
@@ -782,11 +807,15 @@ var Statemachine = class {
   lastState = null;
   autoreleaseLock;
   maxAutomaticHops;
+  maxQueueLength;
   queue = new OperationQueue();
   running = false;
+  idleWaiters = [];
   inSyncCallback = false;
   beforeObservers = [];
   afterObservers = [];
+  onChainedOperationError;
+  onReleaseError;
   constructor(subject, process, options = {}) {
     this.subject = subject;
     this.process = process;
@@ -801,6 +830,15 @@ var Statemachine = class {
       );
     }
     this.maxAutomaticHops = hops;
+    const maxQueue = options.maxQueueLength ?? Infinity;
+    if (maxQueue !== Infinity && (!Number.isInteger(maxQueue) || maxQueue < 1)) {
+      throw new RangeError(
+        `maxQueueLength must be a positive integer; got ${String(options.maxQueueLength)}`
+      );
+    }
+    this.maxQueueLength = maxQueue;
+    this.onChainedOperationError = options.onChainedOperationError;
+    this.onReleaseError = options.onReleaseError;
   }
   // --- public getters ---
   getCurrentState() {
@@ -817,6 +855,7 @@ var Statemachine = class {
   }
   // --- public observer attach/detach ---
   attachBefore(observer) {
+    if (this.beforeObservers.includes(observer)) return;
     this.beforeObservers.push(observer);
   }
   detachBefore(observer) {
@@ -827,6 +866,7 @@ var Statemachine = class {
     return this.beforeObservers;
   }
   attachAfter(observer) {
+    if (this.afterObservers.includes(observer)) return;
     this.afterObservers.push(observer);
   }
   detachAfter(observer) {
@@ -865,6 +905,21 @@ var Statemachine = class {
       this.enqueueOperation(null, context, resolve, reject);
     });
   }
+  /**
+   * Resolves once the operation queue is empty and the runner is idle —
+   * i.e. every operation enqueued so far, including operations chained via
+   * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+   * machine is already idle. Note this is a quiescence point, not a
+   * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+   */
+  whenIdle() {
+    if (!this.running && this.queue.isEmpty()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.idleWaiters.push(resolve);
+    });
+  }
   /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
    *  the flag is cleared as soon as fn returns (before any promise it returned
    *  is awaited), so concurrent external callers are never affected. This
@@ -886,6 +941,9 @@ var Statemachine = class {
   }
   /** Single entry point to the operation queue — every enqueue kicks the runner. */
   enqueueOperation(eventName, context, resolve, reject, ifStateName) {
+    if (this.queue.size() >= this.maxQueueLength) {
+      throw new QueueLimitExceededError(this.maxQueueLength, eventName);
+    }
     this.queue.enqueue({
       eventName,
       context: context ?? /* @__PURE__ */ new Map(),
@@ -906,6 +964,11 @@ var Statemachine = class {
       }
     } finally {
       this.running = false;
+      if (this.queue.isEmpty() && this.idleWaiters.length > 0) {
+        const waiters = this.idleWaiters;
+        this.idleWaiters = [];
+        for (const waiter of waiters) waiter();
+      }
     }
   }
   async runOperation(op) {
@@ -931,6 +994,10 @@ var Statemachine = class {
         try {
           await this.mutex.releaseLock();
         } catch (err) {
+          try {
+            this.onReleaseError?.(err);
+          } catch {
+          }
           if (!failure) failure = { err };
         }
       }
@@ -1011,7 +1078,13 @@ var Statemachine = class {
               chainedCtx,
               () => {
               },
-              () => {
+              (err) => {
+                try {
+                  this.onChainedOperationError?.(err, {
+                    eventName: chainedEventName
+                  });
+                } catch {
+                }
               },
               ifStateName
             );
@@ -1376,6 +1449,11 @@ var WeightTransition = class {
   innerSelector;
   epsilon;
   constructor(innerSelector, epsilon = 1e-3) {
+    if (!Number.isFinite(epsilon) || epsilon <= 0) {
+      throw new RangeError(
+        `WeightTransition epsilon must be a finite number greater than 0; got ${String(epsilon)}`
+      );
+    }
     this.innerSelector = innerSelector ?? new OneOrNoneActiveTransition();
     this.epsilon = epsilon;
   }
@@ -1384,6 +1462,11 @@ var WeightTransition = class {
     let maxWeight = Number.NEGATIVE_INFINITY;
     for (const transition of all) {
       const weight = transition.getWeight();
+      if (!Number.isFinite(weight)) {
+        throw new RangeError(
+          `WeightTransition: transition weights must be finite numbers; got ${String(weight)}`
+        );
+      }
       if (weight > maxWeight) maxWeight = weight;
     }
     const best = all.filter(
@@ -1558,6 +1641,14 @@ function toMermaidId(name) {
 function escapeMermaidLabel(str) {
   return str.replace(/\\/g, "#92;").replace(/"/g, "#quot;");
 }
+var VALID_DIRECTIONS = /* @__PURE__ */ new Set(["TB", "BT", "LR", "RL"]);
+function assertDirection(value, optionName) {
+  if (!VALID_DIRECTIONS.has(value)) {
+    throw new RangeError(
+      `${optionName} must be one of "TB", "BT", "LR", "RL"; got ${JSON.stringify(value)}`
+    );
+  }
+}
 var GraphBuilder = class {
   nodes = /* @__PURE__ */ new Map();
   edges = [];
@@ -1633,6 +1724,7 @@ var GraphBuilder = class {
   toDot(options) {
     const graph = this.getGraph();
     const rankdir = options?.rankdir ?? "LR";
+    assertDirection(rankdir, "rankdir");
     const lines = [];
     lines.push("digraph {");
     lines.push(`  rankdir=${rankdir};`);
@@ -1652,6 +1744,7 @@ var GraphBuilder = class {
   toMermaid(options) {
     const graph = this.getGraph();
     const direction = options?.direction ?? "LR";
+    assertDirection(direction, "direction");
     const lines = [];
     lines.push(`stateDiagram-v2`);
     lines.push(`  direction ${direction}`);
@@ -1707,6 +1800,7 @@ var GraphBuilder = class {
   ProcessBuilder,
   ProcessFinalizedError,
   ProcessNotFoundError,
+  QueueLimitExceededError,
   ReentrancyError,
   ScoreTransition,
   SingleProcessDetector,