machina 4.0.1 → 6.0.0

package/dist/index.js

@@ -0,0 +1,656 @@
+'use strict';
+
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, cb) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(cb);
+    return {
+      off: () => {
+        set.delete(cb);
+      }
+    };
+  }
+  /**
+   * Emit a named event, notifying wildcard listeners first, then named listeners.
+   *
+   * Wildcard listeners receive `(eventName, data)`; named listeners receive
+   * only `data`. The firing order (wildcards before named) is intentional —
+   * it lets relay listeners (like Fsm's bfsm proxy) observe all events
+   * before specific subscribers react.
+   */
+  emit(event, data) {
+    const wildcards = this.listeners.get("*");
+    if (wildcards) {
+      for (const cb of wildcards) {
+        cb(event, data);
+      }
+    }
+    const named = this.listeners.get(event);
+    if (named) {
+      for (const cb of named) {
+        cb(data);
+      }
+    }
+  }
+  /**
+   * Remove all listeners (named and wildcard).
+   *
+   * Existing `Subscription` objects remain valid — their `off()` closures
+   * hold a reference to the now-empty Set, so calling them is harmless.
+   * Called by `dispose()` to prevent memory retention after an FSM shuts down.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/types.ts
+var MACHINA_TYPE = /* @__PURE__ */ Symbol("machina.type");
+
+// src/behavioral-fsm.ts
+var MAX_TRANSITION_DEPTH = 20;
+var BehavioralFsm = class {
+  id;
+  initialState;
+  // Type discriminant — lets ChildLink adapter identify this at runtime
+  [MACHINA_TYPE] = "BehavioralFsm";
+  states;
+  emitter = new Emitter();
+  clients = /* @__PURE__ */ new WeakMap();
+  // Tracks all initialized clients so the Fsm-child nohandler listener can
+  // find which clients need bubbling (Fsm events have no client in payload).
+  // WeakRef prevents retention; clients clean themselves up naturally.
+  knownClients = /* @__PURE__ */ new Set();
+  // Subscriptions to child FSM wildcard events, keyed by state name.
+  // Set up once during construction, torn down in dispose().
+  childSubscriptions = [];
+  disposed = false;
+  transitionDepth = 0;
+  constructor(config) {
+    this.id = config.id;
+    this.initialState = config.initialState;
+    this.states = config.states;
+    this.wrapChildLinks();
+    this.setupChildSubscriptions();
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Dispatch an input to the given client's current state handler.
+   *
+   * Delegation order: if the current state has a `_child` FSM that can
+   * handle the input, it is dispatched there. If the child emits `nohandler`,
+   * the input bubbles up to this FSM's local handler. If no handler exists
+   * here either, `nohandler` is emitted on this FSM's emitter.
+   *
+   * No-ops silently when disposed.
+   */
+  handle(client, inputName, ...args) {
+    if (this.disposed) {
+      return;
+    }
+    const meta = this.getOrCreateClientMeta(client);
+    meta.currentActionArgs = args;
+    const stateObj = this.states[meta.state];
+    const childLink = stateObj?._child;
+    if (childLink) {
+      if (childLink.canHandle(client, inputName)) {
+        try {
+          childLink.handle(client, inputName, ...args);
+        } finally {
+          meta.currentActionArgs = void 0;
+        }
+        return;
+      }
+    }
+    this.handleLocally(client, inputName, args, meta);
+  }
+  /**
+   * Returns true if the client's current state has a handler for `inputName`
+   * (or a catch-all `"*"` handler). Does NOT initialize the client — no
+   * `_onEnter`, no events, no side effects. Unseen clients are treated as
+   * if they were already in `initialState`. Returns false when disposed.
+   */
+  canHandle(client, inputName) {
+    if (this.disposed) {
+      return false;
+    }
+    const state = this.clients.get(client)?.state ?? this.initialState;
+    const stateObj = this.states[state];
+    return !!(stateObj?.[inputName] ?? stateObj?.["*"]);
+  }
+  /**
+   * Transition the client back to `initialState`, firing `_onEnter` and
+   * lifecycle events as if entering it fresh. No-ops when disposed.
+   */
+  reset(client) {
+    if (this.disposed) {
+      return;
+    }
+    this.transition(client, this.initialState);
+  }
+  /**
+   * Returns the client's current state, or `undefined` if the client has
+   * never been initialized (i.e. `handle()`, `transition()`, or `reset()`
+   * have never been called for it). Does NOT trigger initialization.
+   */
+  currentState(client) {
+    return this.clients.get(client)?.state;
+  }
+  /**
+   * Directly transition `client` to `toState`, running the full lifecycle:
+   * `_onExit` for the current state → `transitioning` event → update state →
+   * `_onEnter` for new state → `transitioned` event → child reset → deferred
+   * queue replay → bounce (if `_onEnter` returned a state name).
+   *
+   * Same-state transitions are silently ignored. Transitions to unknown state
+   * names emit `invalidstate` instead of throwing. Throws if the transition
+   * depth exceeds `MAX_TRANSITION_DEPTH` (likely an `_onEnter` → transition loop).
+   *
+   * No-ops when disposed.
+   */
+  transition(client, toState) {
+    if (this.disposed) {
+      return;
+    }
+    const meta = this.getOrCreateClientMeta(client);
+    const fromState = meta.state;
+    if (toState === fromState) {
+      return;
+    }
+    if (!(toState in this.states)) {
+      this.emitter.emit("invalidstate", { stateName: toState, client });
+      return;
+    }
+    this.transitionDepth++;
+    if (this.transitionDepth > MAX_TRANSITION_DEPTH) {
+      this.transitionDepth = 0;
+      throw new Error(
+        `Max transition depth (${MAX_TRANSITION_DEPTH}) exceeded in FSM "${this.id}". Likely an infinite _onEnter \u2192 transition loop.`
+      );
+    }
+    try {
+      const curStateObj = this.states[fromState];
+      const newStateObj = this.states[toState];
+      if (curStateObj?._onExit && typeof curStateObj._onExit === "function") {
+        const exitArgs = this.buildHandlerArgs(client, "", meta);
+        curStateObj._onExit(exitArgs);
+      }
+      meta.state = toState;
+      const payload = { fromState, toState, client };
+      this.emitter.emit("transitioning", payload);
+      let bounceTarget = void 0;
+      if (newStateObj?._onEnter && typeof newStateObj._onEnter === "function") {
+        const enterArgs = this.buildHandlerArgs(client, "", meta);
+        bounceTarget = newStateObj._onEnter(enterArgs);
+      }
+      this.emitter.emit("transitioned", payload);
+      const childLink = newStateObj?._child;
+      if (childLink) {
+        childLink.reset(client);
+      }
+      this.processQueue(client, meta);
+      if (typeof bounceTarget === "string" && meta.state === toState) {
+        this.transition(client, bounceTarget);
+      }
+    } finally {
+      this.transitionDepth--;
+    }
+  }
+  /**
+   * Returns the client's state as a dot-delimited path including any active
+   * child FSM states (e.g. `"active.connecting.retrying"`). Returns just the
+   * current state name when no child is active. Returns `""` for clients that
+   * have never been initialized (unlike `currentState()` which returns `undefined`).
+   */
+  compositeState(client) {
+    const meta = this.clients.get(client);
+    if (!meta) {
+      return "";
+    }
+    const stateObj = this.states[meta.state];
+    const childLink = stateObj?._child;
+    if (childLink) {
+      const childComposite = childLink.compositeState(client);
+      if (childComposite) {
+        return `${meta.state}.${childComposite}`;
+      }
+    }
+    return meta.state;
+  }
+  on(eventName, callback) {
+    if (this.disposed) {
+      return { off() {
+      } };
+    }
+    return this.emitter.on(eventName, callback);
+  }
+  /**
+   * Emit a custom event through the FSM. Built-in lifecycle events are
+   * emitted automatically — this is for user-defined events from handlers.
+   * No-ops when disposed.
+   */
+  emit(eventName, data) {
+    if (this.disposed) {
+      return;
+    }
+    this.emitter.emit(eventName, data);
+  }
+  /**
+   * Permanently shut down this FSM. Irreversible — all subsequent method
+   * calls become silent no-ops. Tears down child subscriptions, clears all
+   * listeners, and cascades disposal to child FSMs (unless `preserveChildren`
+   * is set). The same child appearing in multiple states is disposed once.
+   */
+  dispose(options) {
+    this.disposed = true;
+    for (const sub of this.childSubscriptions) {
+      sub.off();
+    }
+    if (!options?.preserveChildren) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const stateName of Object.keys(this.states)) {
+        const childLink = this.states[stateName]?._child;
+        if (childLink && !seen.has(childLink)) {
+          seen.add(childLink);
+          childLink.dispose();
+        }
+      }
+    }
+    this.emitter.clear();
+  }
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+  /**
+   * Walks all states at construction time, detects raw FSM instances assigned
+   * to _child, and wraps them into ChildLink adapters via createChildLink().
+   * Must run BEFORE setupChildSubscriptions() so the subscriptions see
+   * ChildLink objects, not raw FSM instances.
+   */
+  wrapChildLinks() {
+    for (const stateName of Object.keys(this.states)) {
+      const stateObj = this.states[stateName];
+      const rawChild = stateObj?._child;
+      if (!rawChild) {
+        continue;
+      }
+      if (typeof rawChild !== "object") {
+        throw new Error(
+          `State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got ${String(rawChild)}`
+        );
+      }
+      if (!(MACHINA_TYPE in rawChild)) {
+        throw new Error(
+          `State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got a plain object`
+        );
+      }
+      stateObj._child = createChildLink(rawChild);
+    }
+  }
+  /**
+   * Walks all states at construction time, finds states with _child, and
+   * subscribes once to each unique child's wildcard events. Subscriptions are
+   * stored for cleanup in dispose(). We deduplicate by child reference to
+   * avoid double-subscribing when the same child appears in multiple states.
+   */
+  setupChildSubscriptions() {
+    const seenChildren = /* @__PURE__ */ new Set();
+    for (const stateName of Object.keys(this.states)) {
+      const stateObj = this.states[stateName];
+      const childLink = stateObj?._child;
+      if (!childLink || seenChildren.has(childLink)) {
+        continue;
+      }
+      seenChildren.add(childLink);
+      const sub = childLink.onAny((eventName, data) => {
+        if (eventName === "nohandler") {
+          const payload2 = data;
+          if (payload2.client !== void 0) {
+            this.bubbleNohandler(
+              payload2.client,
+              childLink,
+              payload2.inputName,
+              payload2.args ?? []
+            );
+          } else {
+            for (const ref of this.knownClients) {
+              const client = ref.deref();
+              if (client === void 0) {
+                this.knownClients.delete(ref);
+                continue;
+              }
+              this.bubbleNohandler(
+                client,
+                childLink,
+                payload2.inputName,
+                payload2.args ?? []
+              );
+            }
+          }
+          return;
+        }
+        const payload = data;
+        if (payload && typeof payload === "object" && "client" in payload) {
+          if (this.isChildActiveForClient(payload.client, childLink)) {
+            this.emitter.emit(eventName, data);
+          }
+        } else {
+          for (const ref of this.knownClients) {
+            const client = ref.deref();
+            if (!client) {
+              this.knownClients.delete(ref);
+              continue;
+            }
+            if (this.isChildActiveForClient(client, childLink)) {
+              this.emitter.emit(eventName, data);
+              break;
+            }
+          }
+        }
+      });
+      this.childSubscriptions.push(sub);
+    }
+  }
+  /**
+   * Bubbles a child nohandler to the parent for the given client.
+   * Only fires if the client is currently in a state that has this childLink.
+   * Extracted from the lambda in setupChildSubscriptions to keep it readable.
+   */
+  bubbleNohandler(client, childLink, inputName, args) {
+    if (!this.isChildActiveForClient(client, childLink)) {
+      return;
+    }
+    const meta = this.clients.get(client);
+    meta.currentActionArgs = args;
+    this.handleLocally(client, inputName, args, meta);
+  }
+  /**
+   * Returns true if the given client is currently in a parent state whose
+   * _child is the specified childLink. Returns false if the client has no
+   * meta (never initialized) or is in a state with a different (or no) child.
+   */
+  isChildActiveForClient(client, childLink) {
+    const meta = this.clients.get(client);
+    if (!meta) {
+      return false;
+    }
+    const parentStateObj = this.states[meta.state];
+    return parentStateObj?._child === childLink;
+  }
+  /**
+   * The inner handler dispatch — no delegation, no initialization side effects
+   * beyond what getOrCreateClientMeta already did. Called by handle() after
+   * the delegation check, and by the nohandler child listener for bubbling.
+   */
+  handleLocally(client, inputName, args, meta) {
+    const stateObj = this.states[meta.state];
+    const handler = stateObj?.[inputName] ?? stateObj?.["*"];
+    if (!handler) {
+      this.emitter.emit("nohandler", { inputName, args, client });
+      meta.currentActionArgs = void 0;
+      return;
+    }
+    try {
+      this.emitter.emit("handling", { inputName, client });
+      const handlerArgs = this.buildHandlerArgs(client, inputName, meta);
+      let targetState = void 0;
+      if (typeof handler === "string") {
+        targetState = handler;
+      } else if (typeof handler === "function") {
+        targetState = handler(handlerArgs, ...args);
+      }
+      this.emitter.emit("handled", { inputName, client });
+      if (typeof targetState === "string") {
+        this.transition(client, targetState);
+      }
+    } finally {
+      meta.currentActionArgs = void 0;
+    }
+  }
+  getOrCreateClientMeta(client) {
+    let meta = this.clients.get(client);
+    if (meta) {
+      return meta;
+    }
+    meta = {
+      state: void 0,
+      deferredQueue: []
+    };
+    this.clients.set(client, meta);
+    this.knownClients.add(new WeakRef(client));
+    this.transition(client, this.initialState);
+    return meta;
+  }
+  buildHandlerArgs(client, inputName, meta) {
+    return {
+      ctx: client,
+      inputName,
+      defer: (opts) => {
+        if (!meta.currentActionArgs) {
+          return;
+        }
+        const deferred = {
+          inputName,
+          args: [...meta.currentActionArgs],
+          untilState: opts?.until
+        };
+        meta.deferredQueue.push(deferred);
+        this.emitter.emit("deferred", { inputName, client });
+      },
+      emit: (evtName, evtData) => {
+        this.emitter.emit(evtName, evtData);
+      }
+    };
+  }
+  processQueue(client, meta) {
+    const toReplay = [];
+    const remaining = [];
+    for (const item of meta.deferredQueue) {
+      if (item.untilState === void 0 || item.untilState === meta.state) {
+        toReplay.push(item);
+      } else {
+        remaining.push(item);
+      }
+    }
+    meta.deferredQueue = remaining;
+    for (const item of toReplay) {
+      this.handle(client, item.inputName, ...item.args);
+    }
+  }
+};
+function createChildLink(child) {
+  if (!child || typeof child !== "object") {
+    throw new Error(
+      `createChildLink: expected an Fsm or BehavioralFsm instance, got ${String(child)}`
+    );
+  }
+  const childType = child[MACHINA_TYPE];
+  if (childType === "BehavioralFsm") {
+    return {
+      canHandle(client, inputName) {
+        return child.canHandle(client, inputName);
+      },
+      handle(client, inputName, ...args) {
+        child.handle(client, inputName, ...args);
+      },
+      reset(client) {
+        child.transition(client, child.initialState);
+      },
+      onAny(callback) {
+        return child.on("*", callback);
+      },
+      compositeState(client) {
+        return child.compositeState(client);
+      },
+      dispose() {
+        child.dispose();
+      }
+    };
+  }
+  if (childType === "Fsm") {
+    return {
+      canHandle(_client, inputName) {
+        return child.canHandle(inputName);
+      },
+      handle(_client, inputName, ...args) {
+        child.handle(inputName, ...args);
+      },
+      reset(_client) {
+        child.reset();
+      },
+      onAny(callback) {
+        return child.on("*", callback);
+      },
+      compositeState(_client) {
+        return child.compositeState();
+      },
+      dispose() {
+        child.dispose();
+      }
+    };
+  }
+  throw new Error(
+    `createChildLink: expected an Fsm or BehavioralFsm instance, got [MACHINA_TYPE] = ${String(childType ?? "undefined")}`
+  );
+}
+function createBehavioralFsm(config) {
+  return new BehavioralFsm(config);
+}
+
+// src/fsm.ts
+var Fsm = class {
+  id;
+  // Type discriminant — lets ChildLink adapter identify this at runtime
+  [MACHINA_TYPE] = "Fsm";
+  bfsm;
+  context;
+  // FsmEventMap is an interface, which lacks the implicit index signature
+  // that Emitter's Record<string, unknown> constraint needs. The mapped type
+  // BehavioralFsmEventMap doesn't have this issue. Intersect with Record to
+  // satisfy the constraint while preserving typed event signatures.
+  emitter = new Emitter();
+  disposed = false;
+  constructor(config) {
+    this.id = config.id;
+    this.context = config.context ?? {};
+    this.bfsm = new BehavioralFsm(config);
+    this.bfsm.on("*", (eventName, data) => {
+      if (data && typeof data === "object" && "client" in data) {
+        const { client: _, ...payload } = data;
+        this.emitter.emit(eventName, payload);
+      } else {
+        this.emitter.emit(eventName, data);
+      }
+    });
+    this.bfsm.transition(this.context, config.initialState);
+  }
+  // -------------------------------------------------------------------------
+  // Public API — same as BehavioralFsm, minus the client parameter
+  // -------------------------------------------------------------------------
+  /**
+   * Dispatch an input to the current state's handler.
+   * If a `_child` FSM in the current state can handle it, delegation occurs
+   * there first; unhandled inputs bubble up to the parent.
+   * No-ops silently when disposed.
+   */
+  handle(inputName, ...args) {
+    if (this.disposed) {
+      return;
+    }
+    this.bfsm.handle(this.context, inputName, ...args);
+  }
+  /**
+   * Returns true if the current state has a handler for `inputName`
+   * (or a catch-all `"*"` handler). Does not trigger initialization
+   * or any side effects. Returns false when disposed.
+   */
+  canHandle(inputName) {
+    if (this.disposed) {
+      return false;
+    }
+    return this.bfsm.canHandle(this.context, inputName);
+  }
+  /**
+   * Transition back to `initialState`, firing `_onEnter` and lifecycle
+   * events as if entering it fresh. No-ops silently when disposed.
+   */
+  reset() {
+    if (this.disposed) {
+      return;
+    }
+    this.bfsm.reset(this.context);
+  }
+  /**
+   * Returns the current state name. Always defined — Fsm eagerly
+   * initializes into `initialState` during construction.
+   */
+  currentState() {
+    return this.bfsm.currentState(this.context);
+  }
+  /**
+   * Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
+   * lifecycle events. Same-state transitions are silently ignored.
+   * No-ops when disposed.
+   */
+  transition(toState) {
+    if (this.disposed) {
+      return;
+    }
+    this.bfsm.transition(this.context, toState);
+  }
+  /**
+   * Returns the current state as a dot-delimited path that includes
+   * any active child FSM states (e.g. `"active.connecting.retrying"`).
+   * Returns just the current state name when no child is active.
+   */
+  compositeState() {
+    return this.bfsm.compositeState(this.context);
+  }
+  on(eventName, callback) {
+    if (this.disposed) {
+      return { off() {
+      } };
+    }
+    return this.emitter.on(eventName, callback);
+  }
+  /**
+   * Emit a custom event through the FSM. Built-in lifecycle events are
+   * emitted automatically — this is for user-defined events from handlers.
+   * Routes through the BehavioralFsm so all relay paths are consistent.
+   * No-ops when disposed.
+   */
+  emit(eventName, data) {
+    if (this.disposed) {
+      return;
+    }
+    this.bfsm.emit(eventName, data);
+  }
+  /**
+   * Permanently shut down this FSM. Irreversible — all subsequent method
+   * calls become silent no-ops. Clears all listeners and cascades disposal
+   * to child FSMs (unless `preserveChildren` is set).
+   */
+  dispose(options) {
+    this.disposed = true;
+    this.bfsm.dispose(options);
+    this.emitter.clear();
+  }
+};
+function createFsm(config) {
+  return new Fsm(config);
+}
+
+exports.BehavioralFsm = BehavioralFsm;
+exports.Fsm = Fsm;
+exports.createBehavioralFsm = createBehavioralFsm;
+exports.createFsm = createFsm;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map