@camcima/finita 4.2.0 → 4.3.0

package/dist/index.js

@@ -60,8 +60,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"
@@ -191,11 +191,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());
@@ -474,9 +476,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();
@@ -663,19 +667,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;
   }
 };
 
@@ -724,6 +743,18 @@ var LockCanNotBeReleasedError = class extends FinitaError {
   }
 };
 
+// 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";
@@ -761,6 +792,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;
@@ -776,6 +819,8 @@ var Statemachine = class {
   running = false;
   idleWaiters = [];
   inSyncCallback = false;
+  /** Set when releasing a held lock fails; see LockOwnershipUncertainError. */
+  ownershipUncertainty = null;
   beforeObservers = [];
   afterObservers = [];
   onChainedOperationError;
@@ -853,6 +898,9 @@ var Statemachine = class {
    * 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.releaseMutex();
@@ -952,6 +1000,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;
@@ -992,9 +1044,15 @@ var Statemachine = class {
    * 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()) {
@@ -1004,13 +1062,31 @@ var Statemachine = class {
       failure = { err };
     }
     if (failure) {
-      try {
-        this.onReleaseError?.(failure.err);
-      } catch {
-      }
+      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);
@@ -1082,12 +1158,11 @@ var Statemachine = class {
               () => {
               },
               (err) => {
-                try {
-                  this.onChainedOperationError?.(err, {
+                this.callDiagnosticHook(
+                  () => this.onChainedOperationError?.(err, {
                     eventName: chainedEventName
-                  });
-                } catch {
-                }
+                  })
+                );
               },
               ifStateName
             );
@@ -1223,6 +1298,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
@@ -1233,13 +1332,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);
   }
 };
 
@@ -1251,13 +1345,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);
   }
 };
 
@@ -1270,8 +1359,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;
   }
 };
 
@@ -1326,15 +1420,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;
@@ -1495,19 +1580,27 @@ var LockAdapterMutex = class {
    * 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) {
       return true;
     }
-    this.pendingAcquire ??= (async () => {
-      try {
+    if (!this.pendingAcquire) {
+      const attempt = (async () => {
         this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
         return this.acquired;
-      } finally {
-        this.pendingAcquire = null;
-      }
-    })();
+      })();
+      this.pendingAcquire = attempt;
+      const clear = () => {
+        if (this.pendingAcquire === attempt) this.pendingAcquire = null;
+      };
+      attempt.then(clear, clear);
+    }
     return this.pendingAcquire;
   }
   async releaseLock() {
@@ -1819,6 +1912,7 @@ export {
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
   LockCanNotBeReleasedError,
+  LockOwnershipUncertainError,
   MutexFactory,
   Not,
   NullMutex,