@camcima/finita 4.0.0 → 4.2.0

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   InvalidSubjectError: () => InvalidSubjectError,
   LockAdapterMutex: () => LockAdapterMutex,
   LockCanNotBeAcquiredError: () => LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError: () => LockCanNotBeReleasedError,
   MutexFactory: () => MutexFactory,
   Not: () => Not,
   NullMutex: () => NullMutex,
@@ -52,6 +53,7 @@ __export(index_exports, {
   ProcessBuilder: () => ProcessBuilder,
   ProcessFinalizedError: () => ProcessFinalizedError,
   ProcessNotFoundError: () => ProcessNotFoundError,
+  QueueLimitExceededError: () => QueueLimitExceededError,
   ReentrancyError: () => ReentrancyError,
   ScoreTransition: () => ScoreTransition,
   SingleProcessDetector: () => SingleProcessDetector,
@@ -103,8 +105,10 @@ var Event = class {
       await observer.update(this, args);
     }
   }
+  /** Snapshot — detaching later does not change an already-returned list,
+   *  and mutating it does not change the event's registrations. */
   getObservers() {
-    return this.observers;
+    return [...this.observers];
   }
   getMetadata() {
     return Object.fromEntries(this.metadata);
@@ -256,6 +260,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 +311,7 @@ var Transition = class {
     this.eventName = eventName;
     this.condition = condition;
     this.weight = weight;
+    Object.freeze(this);
   }
   getTargetState() {
     return this.targetState;
@@ -440,12 +446,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 +467,6 @@ var ProcessBuilder = class _ProcessBuilder {
     if (this.built) {
       throw new ProcessFinalizedError(this.processName);
     }
-    this.built = true;
     this.validateInitialState();
     this.validateTransitionEndpoints();
     this.validateNoConflictingDuplicates();
@@ -464,6 +477,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,
@@ -655,12 +669,30 @@ var ProcessBuilder = class _ProcessBuilder {
 var AmbiguousTransitionError = class extends FinitaError {
   code = "ambiguousTransition";
   activeCount;
-  constructor(activeCount) {
-    super(`More than one transition is active! (active count: ${activeCount})`);
+  /** The competing transitions — what you need to resolve the ambiguity. */
+  candidates;
+  constructor(activeCount, candidates = []) {
+    const list = Array.from(candidates, (c) => Object.freeze({ ...c }));
+    const detail = list.length > 0 ? ` Candidates: ${list.map(describeCandidate).join("; ")}.` : "";
+    super(
+      `More than one transition is active! (active count: ${activeCount})${detail}`
+    );
     this.name = "AmbiguousTransitionError";
     this.activeCount = activeCount;
+    this.candidates = Object.freeze(list);
   }
 };
+function describeCandidate(candidate) {
+  const parts = [`-> "${candidate.targetStateName}"`];
+  parts.push(
+    candidate.eventName === null ? "on <automatic>" : `on event "${candidate.eventName}"`
+  );
+  if (candidate.conditionName !== null) {
+    parts.push(`if ${candidate.conditionName}`);
+  }
+  parts.push(`weight ${candidate.weight}`);
+  return parts.join(" ");
+}
 
 // src/selector/OneOrNoneActiveTransition.ts
 var OneOrNoneActiveTransition = class {
@@ -672,7 +704,15 @@ var OneOrNoneActiveTransition = class {
       case 1:
         return arr[0];
       default:
-        throw new AmbiguousTransitionError(arr.length);
+        throw new AmbiguousTransitionError(
+          arr.length,
+          arr.map((transition) => ({
+            targetStateName: transition.getTargetState().getName(),
+            eventName: transition.getEventName(),
+            conditionName: transition.getConditionName(),
+            weight: transition.getWeight()
+          }))
+        );
     }
   }
 };
@@ -708,6 +748,9 @@ var OperationQueue = class {
   isEmpty() {
     return this.items.length === 0;
   }
+  size() {
+    return this.items.length;
+  }
 };
 
 // src/filter/ActiveTransitionFilter.ts
@@ -746,6 +789,15 @@ var LockCanNotBeAcquiredError = class extends FinitaError {
   }
 };
 
+// src/error/LockCanNotBeReleasedError.ts
+var LockCanNotBeReleasedError = class extends FinitaError {
+  code = "lockCanNotBeReleased";
+  constructor(message = "Lock can not be released! releaseLock() returned false; the lock may still be held.") {
+    super(message);
+    this.name = "LockCanNotBeReleasedError";
+  }
+};
+
 // src/error/AutomaticTransitionCycleError.ts
 var AutomaticTransitionCycleError = class extends FinitaError {
   code = "automaticTransitionCycle";
@@ -772,6 +824,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 +845,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 +868,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,31 +893,43 @@ var Statemachine = class {
   }
   // --- public observer attach/detach ---
   attachBefore(observer) {
+    if (this.beforeObservers.includes(observer)) return;
     this.beforeObservers.push(observer);
   }
   detachBefore(observer) {
     const idx = this.beforeObservers.indexOf(observer);
     if (idx >= 0) this.beforeObservers.splice(idx, 1);
   }
+  /** Snapshot — detaching later does not change an already-returned list,
+   *  and mutating it does not change the machine's registrations. */
   getBeforeObservers() {
-    return this.beforeObservers;
+    return [...this.beforeObservers];
   }
   attachAfter(observer) {
+    if (this.afterObservers.includes(observer)) return;
     this.afterObservers.push(observer);
   }
   detachAfter(observer) {
     const idx = this.afterObservers.indexOf(observer);
     if (idx >= 0) this.afterObservers.splice(idx, 1);
   }
+  /** Snapshot — see getBeforeObservers. */
   getAfterObservers() {
-    return this.afterObservers;
+    return [...this.afterObservers];
   }
   // --- public locking ---
   async acquireLock() {
     return this.mutex.acquireLock();
   }
+  /**
+   * Releases the mutex. A failed release — whether the mutex throws or
+   * returns false — is reported to the onReleaseError hook; it is not thrown,
+   * so manual lock management keeps its existing control flow. Inspect
+   * isLockAcquired() (or the hook) to learn whether the lock was actually
+   * freed.
+   */
   async releaseLock() {
-    await this.mutex.releaseLock();
+    await this.releaseMutex();
   }
   isLockAcquired() {
     return this.mutex.isAcquired();
@@ -865,6 +953,27 @@ 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.
+   *
+   * Like triggerEvent/checkTransitions, this may not be called from inside an
+   * observer or condition of the same machine: the machine cannot reach idle
+   * while the runner is blocked on that very callback, so awaiting it there
+   * always deadlocks.
+   */
+  whenIdle() {
+    this.assertNotReentrant("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 +995,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 +1018,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) {
@@ -928,11 +1045,8 @@ var Statemachine = class {
       failure = { err };
     } finally {
       if (acquiredHere && this.autoreleaseLock) {
-        try {
-          await this.mutex.releaseLock();
-        } catch (err) {
-          if (!failure) failure = { err };
-        }
+        const releaseFailure = await this.releaseMutex();
+        if (releaseFailure && !failure) failure = releaseFailure;
       }
     }
     if (failure) {
@@ -941,6 +1055,36 @@ var Statemachine = class {
       op.resolve();
     }
   }
+  /**
+   * Releases the mutex, normalizing its two failure modes into one result: a
+   * thrown error, and a false return — the failure signal MutexInterface /
+   * LockAdapterInterface define (a PostgreSQL advisory unlock that returns
+   * false, a Redis DEL that removed nothing). A false return means the lock
+   * may still be held, so it must never be mistaken for a successful release.
+   *
+   * Every failure is surfaced through the diagnostic hook — when the
+   * operation also failed, the rejection carries the operation error and this
+   * hook is the only place the release error appears.
+   *
+   * @returns null on success, or the failure wrapped for the caller to raise.
+   */
+  async releaseMutex() {
+    let failure = null;
+    try {
+      if (!await this.mutex.releaseLock()) {
+        failure = { err: new LockCanNotBeReleasedError() };
+      }
+    } catch (err) {
+      failure = { err };
+    }
+    if (failure) {
+      try {
+        this.onReleaseError?.(failure.err);
+      } catch {
+      }
+    }
+    return failure;
+  }
   resolveEvent(name) {
     if (!this.currentState.hasEvent(name)) {
       throw new WrongEventForStateError(this.currentState.getName(), name);
@@ -1011,7 +1155,13 @@ var Statemachine = class {
               chainedCtx,
               () => {
               },
-              () => {
+              (err) => {
+                try {
+                  this.onChainedOperationError?.(err, {
+                    eventName: chainedEventName
+                  });
+                } catch {
+                }
               },
               ifStateName
             );
@@ -1376,6 +1526,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 +1539,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(
@@ -1398,15 +1558,31 @@ var LockAdapterMutex = class {
   lockAdapter;
   resourceName;
   acquired = false;
+  pendingAcquire = null;
   constructor(lockAdapter, resourceName) {
     this.lockAdapter = lockAdapter;
     this.resourceName = resourceName;
   }
+  /**
+   * Overlapping calls share one underlying acquire: the `acquired` flag is
+   * only set after the adapter resolves, so without this both callers would
+   * pass the check and acquire twice on a non-idempotent adapter (database
+   * advisory locks, redis SET NX). The pending promise is cleared once it
+   * settles, so a failed acquire can still be retried.
+   */
   async acquireLock() {
-    if (!this.acquired) {
-      this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
-    }
-    return this.acquired;
+    if (this.acquired) {
+      return true;
+    }
+    this.pendingAcquire ??= (async () => {
+      try {
+        this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
+        return this.acquired;
+      } finally {
+        this.pendingAcquire = null;
+      }
+    })();
+    return this.pendingAcquire;
   }
   async releaseLock() {
     if (this.acquired) {
@@ -1450,9 +1626,18 @@ var Factory = class {
   afterObservers = /* @__PURE__ */ new Set();
   transitionSelector = null;
   mutexFactory = null;
-  constructor(processDetector, stateNameDetector) {
+  options;
+  /**
+   * @param options Engine options applied to every machine this factory
+   * creates — back-pressure (maxQueueLength), the automatic-hop bound, lock
+   * autorelease, and the onChainedOperationError / onReleaseError diagnostic
+   * sinks. Without them, factory-created machines would silently run on
+   * defaults, which is precisely where those sinks matter most.
+   */
+  constructor(processDetector, stateNameDetector, options = {}) {
     this.processDetector = processDetector;
     this.stateNameDetector = stateNameDetector ?? null;
+    this.options = { ...options };
   }
   setMutexFactory(factory) {
     this.mutexFactory = factory;
@@ -1477,6 +1662,7 @@ var Factory = class {
     const stateName = this.stateNameDetector ? this.stateNameDetector.detectCurrentStateName(subject) : void 0;
     const mutex = this.mutexFactory ? await this.mutexFactory.createMutex(subject) : void 0;
     const sm = new Statemachine(subject, process, {
+      ...this.options,
       initialStateName: stateName ?? void 0,
       transitionSelector: this.transitionSelector ?? void 0,
       mutex: mutex ?? void 0
@@ -1558,6 +1744,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 +1827,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 +1847,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}`);
@@ -1697,6 +1893,7 @@ var GraphBuilder = class {
   InvalidSubjectError,
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError,
   MutexFactory,
   Not,
   NullMutex,
@@ -1707,6 +1904,7 @@ var GraphBuilder = class {
   ProcessBuilder,
   ProcessFinalizedError,
   ProcessNotFoundError,
+  QueueLimitExceededError,
   ReentrancyError,
   ScoreTransition,
   SingleProcessDetector,