@camcima/finita 4.1.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,
@@ -104,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);
@@ -666,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 {
@@ -683,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()
+          }))
+        );
     }
   }
 };
@@ -760,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";
@@ -862,8 +900,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 +913,23 @@ 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.
+   */
   async releaseLock() {
-    await this.mutex.releaseLock();
+    await this.releaseMutex();
   }
   isLockAcquired() {
     return this.mutex.isAcquired();
@@ -911,8 +959,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();
     }
@@ -991,15 +1045,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 +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);
@@ -1481,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) {
@@ -1533,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;
@@ -1560,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
@@ -1790,6 +1893,7 @@ var GraphBuilder = class {
   InvalidSubjectError,
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError,
   MutexFactory,
   Not,
   NullMutex,