@camcima/finita 4.1.0 → 4.3.0

package/dist/index.cjs

@@ -42,6 +42,8 @@ __export(index_exports, {
   InvalidSubjectError: () => InvalidSubjectError,
   LockAdapterMutex: () => LockAdapterMutex,
   LockCanNotBeAcquiredError: () => LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError: () => LockCanNotBeReleasedError,
+  LockOwnershipUncertainError: () => LockOwnershipUncertainError,
   MutexFactory: () => MutexFactory,
   Not: () => Not,
   NullMutex: () => NullMutex,
@@ -104,8 +106,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);
@@ -131,8 +135,8 @@ var INTERNAL_CONSTRUCTION_KEY = /* @__PURE__ */ Symbol(
 
 // src/error/FinitaError.ts
 var FinitaError = class _FinitaError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     if (new.target === _FinitaError) {
       throw new TypeError(
         "FinitaError is abstract and cannot be instantiated directly"
@@ -262,11 +266,13 @@ var State = class {
   getName() {
     return this.name;
   }
+  /** Snapshot — the graph is shared by every machine built from the
+   *  process, so callers must never receive the collection itself. */
   getTransitions() {
     if (this._transitions === null) {
       return [];
     }
-    return this._transitions;
+    return Array.from(this._transitions);
   }
   getEventNames() {
     return Array.from(this.events.keys());
@@ -545,9 +551,11 @@ var ProcessBuilder = class _ProcessBuilder {
     }
   }
   /** Transition identity: (fromState, eventName, toState). Used by both the
-   *  conflict check and the build-time dedup — keep them in lockstep. */
+   *  conflict check and the build-time dedup — keep them in lockstep.
+   *  Encoded as a JSON tuple, not a delimiter join: names may contain any
+   *  character, so no delimiter can keep distinct tuples distinct. */
   static transitionKey(t) {
-    return `${t.fromState}\0${t.eventName ?? ""}\0${t.toState}`;
+    return JSON.stringify([t.fromState, t.eventName, t.toState]);
   }
   validateNoConflictingDuplicates() {
     const seen = /* @__PURE__ */ new Map();
@@ -666,12 +674,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 {
@@ -683,7 +709,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,19 +742,34 @@ var NullMutex = class {
 };
 
 // src/internal/OperationQueue.ts
-var OperationQueue = class {
+var OperationQueue = class _OperationQueue {
+  static COMPACT_THRESHOLD = 1024;
   items = [];
+  head = 0;
   enqueue(op) {
     this.items.push(op);
   }
   dequeue() {
-    return this.items.shift();
+    if (this.head >= this.items.length) {
+      return void 0;
+    }
+    const op = this.items[this.head];
+    this.items[this.head] = void 0;
+    this.head++;
+    if (this.head === this.items.length) {
+      this.items = [];
+      this.head = 0;
+    } else if (this.head >= _OperationQueue.COMPACT_THRESHOLD && this.head * 2 >= this.items.length) {
+      this.items = this.items.slice(this.head);
+      this.head = 0;
+    }
+    return op;
   }
   isEmpty() {
-    return this.items.length === 0;
+    return this.head === this.items.length;
   }
   size() {
-    return this.items.length;
+    return this.items.length - this.head;
   }
 };
 
@@ -760,6 +809,27 @@ 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/LockOwnershipUncertainError.ts
+var LockOwnershipUncertainError = class extends FinitaError {
+  code = "lockOwnershipUncertain";
+  constructor(cause) {
+    super(
+      "Operation rejected: a previous lock release failed, so this machine cannot tell whether it still holds the lock. Call releaseLock() and confirm it succeeds, or discard the machine and rebuild it from persisted state.",
+      { cause }
+    );
+    this.name = "LockOwnershipUncertainError";
+  }
+};
+
 // src/error/AutomaticTransitionCycleError.ts
 var AutomaticTransitionCycleError = class extends FinitaError {
   code = "automaticTransitionCycle";
@@ -797,6 +867,18 @@ var QueueLimitExceededError = class extends FinitaError {
   }
 };
 
+// src/util/index.ts
+function isNamed(obj) {
+  return typeof obj === "object" && obj !== null && "getName" in obj && typeof obj.getName === "function";
+}
+function nameOrString(obj) {
+  if (isNamed(obj)) return obj.getName();
+  return String(obj);
+}
+function isPromiseLike(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+
 // src/Statemachine.ts
 var Statemachine = class {
   subject;
@@ -812,6 +894,8 @@ var Statemachine = class {
   running = false;
   idleWaiters = [];
   inSyncCallback = false;
+  /** Set when releasing a held lock fails; see LockOwnershipUncertainError. */
+  ownershipUncertainty = null;
   beforeObservers = [];
   afterObservers = [];
   onChainedOperationError;
@@ -862,8 +946,10 @@ var Statemachine = class {
     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;
@@ -873,15 +959,26 @@ var Statemachine = class {
     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.
+   *
+   * A failed release of a held lock makes every later operation reject with
+   * LockOwnershipUncertainError; a successful call here is how to recover.
+   */
   async releaseLock() {
-    await this.mutex.releaseLock();
+    await this.releaseMutex();
   }
   isLockAcquired() {
     return this.mutex.isAcquired();
@@ -911,8 +1008,14 @@ var Statemachine = class {
    * 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();
     }
@@ -972,6 +1075,10 @@ var Statemachine = class {
     }
   }
   async runOperation(op) {
+    if (this.ownershipUncertainty) {
+      op.reject(new LockOwnershipUncertainError(this.ownershipUncertainty.err));
+      return;
+    }
     if (op.ifStateName !== void 0 && this.currentState.getName() !== op.ifStateName) {
       op.resolve();
       return;
@@ -991,15 +1098,8 @@ var Statemachine = class {
       failure = { err };
     } finally {
       if (acquiredHere && this.autoreleaseLock) {
-        try {
-          await this.mutex.releaseLock();
-        } catch (err) {
-          try {
-            this.onReleaseError?.(err);
-          } catch {
-          }
-          if (!failure) failure = { err };
-        }
+        const releaseFailure = await this.releaseMutex();
+        if (releaseFailure && !failure) failure = releaseFailure;
       }
     }
     if (failure) {
@@ -1008,6 +1108,60 @@ 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.
+   *
+   * A failure while the mutex claimed to hold the lock leaves ownership
+   * uncertain and blocks later operations; a success clears that state. A
+   * failed release of a lock the mutex did not claim (a defensive manual
+   * release) is still reported but changes nothing.
+   *
+   * @returns null on success, or the failure wrapped for the caller to raise.
+   */
+  async releaseMutex() {
+    const held = this.mutex.isAcquired();
+    let failure = null;
+    try {
+      if (!await this.mutex.releaseLock()) {
+        failure = { err: new LockCanNotBeReleasedError() };
+      }
+    } catch (err) {
+      failure = { err };
+    }
+    if (failure) {
+      if (held) this.ownershipUncertainty = failure;
+      const err = failure.err;
+      this.callDiagnosticHook(() => this.onReleaseError?.(err));
+    } else {
+      this.ownershipUncertainty = null;
+    }
+    return failure;
+  }
+  /**
+   * Runs a user diagnostic hook in isolation. Neither a synchronous throw nor
+   * a rejection of a returned promise may reach the drain loop or the host:
+   * an unavailable telemetry backend must not fail an operation or, via an
+   * unhandled rejection, terminate the process. A returned promise is
+   * deliberately not awaited — a slow reporter must not stall the runner.
+   */
+  callDiagnosticHook(hook) {
+    try {
+      const result = hook();
+      if (isPromiseLike(result)) {
+        result.then(void 0, () => {
+        });
+      }
+    } catch {
+    }
+  }
   resolveEvent(name) {
     if (!this.currentState.hasEvent(name)) {
       throw new WrongEventForStateError(this.currentState.getName(), name);
@@ -1079,12 +1233,11 @@ var Statemachine = class {
               () => {
               },
               (err) => {
-                try {
-                  this.onChainedOperationError?.(err, {
+                this.callDiagnosticHook(
+                  () => this.onChainedOperationError?.(err, {
                     eventName: chainedEventName
-                  });
-                } catch {
-                }
+                  })
+                );
               },
               ifStateName
             );
@@ -1220,6 +1373,30 @@ var CompositeCondition = class {
     const names = this.conditions.map((c) => c.getName());
     return `(${names.join(` ${this.joinWord} `)})`;
   }
+  /**
+   * Evaluates children in order, stopping at the first whose result equals
+   * `shortCircuitOn`. A child that returns a plain boolean is consumed
+   * synchronously; only a returned promise is awaited. Awaiting plain values
+   * would yield between children and end the machine's synchronous
+   * re-entrancy guard, so a re-entrant later child would deadlock instead of
+   * throwing ReentrancyError. For the same reason the composite itself
+   * returns a plain boolean when every child it evaluated did.
+   */
+  evaluate(subject, context, shortCircuitOn) {
+    const from = (start) => {
+      for (let i = start; i < this.conditions.length; i++) {
+        const result = this.conditions[i].checkCondition(subject, context);
+        if (isPromiseLike(result)) {
+          return Promise.resolve(result).then(
+            (value) => Boolean(value) === shortCircuitOn ? shortCircuitOn : from(i + 1)
+          );
+        }
+        if (Boolean(result) === shortCircuitOn) return shortCircuitOn;
+      }
+      return !shortCircuitOn;
+    };
+    return from(0);
+  }
 };
 
 // src/condition/AndComposite.ts
@@ -1230,13 +1407,8 @@ var AndComposite = class extends CompositeCondition {
   addAnd(condition) {
     return this.addCondition(condition);
   }
-  async checkCondition(subject, context) {
-    for (const condition of this.conditions) {
-      if (!await condition.checkCondition(subject, context)) {
-        return false;
-      }
-    }
-    return true;
+  checkCondition(subject, context) {
+    return this.evaluate(subject, context, false);
   }
 };
 
@@ -1248,13 +1420,8 @@ var OrComposite = class extends CompositeCondition {
   addOr(condition) {
     return this.addCondition(condition);
   }
-  async checkCondition(subject, context) {
-    for (const condition of this.conditions) {
-      if (await condition.checkCondition(subject, context)) {
-        return true;
-      }
-    }
-    return false;
+  checkCondition(subject, context) {
+    return this.evaluate(subject, context, true);
   }
 };
 
@@ -1267,8 +1434,13 @@ var Not = class {
   getName() {
     return `not ( ${this.condition.getName()} )`;
   }
-  async checkCondition(subject, context) {
-    return !await this.condition.checkCondition(subject, context);
+  /** Stays synchronous for a synchronous child — see CompositeCondition. */
+  checkCondition(subject, context) {
+    const result = this.condition.checkCondition(subject, context);
+    if (isPromiseLike(result)) {
+      return Promise.resolve(result).then((value) => !value);
+    }
+    return !result;
   }
 };
 
@@ -1323,15 +1495,6 @@ var OnEnterObserver = class _OnEnterObserver {
   }
 };
 
-// src/util/index.ts
-function isNamed(obj) {
-  return typeof obj === "object" && obj !== null && "getName" in obj && typeof obj.getName === "function";
-}
-function nameOrString(obj) {
-  if (isNamed(obj)) return obj.getName();
-  return String(obj);
-}
-
 // src/observer/TransitionLogger.ts
 var TransitionLogger = class {
   logger;
@@ -1481,15 +1644,39 @@ 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.
+   *
+   * The clearing is attached to the attempt only after it is stored: an
+   * adapter that throws synchronously settles the attempt before the
+   * assignment would otherwise run, and clearing inside the attempt itself
+   * would then leave the rejected promise cached forever.
+   */
   async acquireLock() {
-    if (!this.acquired) {
-      this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
+    if (this.acquired) {
+      return true;
     }
-    return this.acquired;
+    if (!this.pendingAcquire) {
+      const attempt = (async () => {
+        this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
+        return this.acquired;
+      })();
+      this.pendingAcquire = attempt;
+      const clear = () => {
+        if (this.pendingAcquire === attempt) this.pendingAcquire = null;
+      };
+      attempt.then(clear, clear);
+    }
+    return this.pendingAcquire;
   }
   async releaseLock() {
     if (this.acquired) {
@@ -1533,9 +1720,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;
@@ -1560,6 +1756,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
@@ -1790,6 +1987,8 @@ var GraphBuilder = class {
   InvalidSubjectError,
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError,
+  LockOwnershipUncertainError,
   MutexFactory,
   Not,
   NullMutex,