machina 6.0.0 → 6.1.0

package/dist/index.js

@@ -1,656 +0,0 @@
-'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