machina 4.0.2 → 6.1.0

package/dist/index.cjs

@@ -0,0 +1,661 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/emitter.ts
+/**
+* Minimal typed event emitter used internally by Fsm and BehavioralFsm.
+*
+* Two listener categories exist at runtime: named listeners (keyed by event
+* name) and wildcard listeners (keyed as `"*"`). The wildcard fires on EVERY
+* emit, regardless of event name, and its callback receives both the event
+* name and the data. Named listeners receive only the data.
+*
+* @typeParam TEventMap - Record mapping event names to their payload types.
+*   Constrains `on()` and `emit()` to matching event/payload pairs.
+*/
+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();
+	}
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* Symbol used as a property key to identify machina FSM instances at runtime.
+* Each class stamps itself with a MachinaType value so the ChildLink adapter
+* can dispatch handle()/canHandle()/reset() correctly without circular imports.
+*/
+const MACHINA_TYPE = Symbol("machina.type");
+
+//#endregion
+//#region src/behavioral-fsm.ts
+const MAX_TRANSITION_DEPTH = 20;
+/**
+* Defines FSM behavior (states + transitions) while tracking per-client state
+* in a `WeakMap`. A single `BehavioralFsm` instance can drive any number of
+* independent client objects simultaneously — each gets its own state,
+* deferred queue, and lifecycle.
+*
+* Prefer `createBehavioralFsm()` over constructing this directly — the factory
+* infers all generic parameters from the config object.
+*
+* All public methods silently no-op after `dispose()` is called.
+*
+* @typeParam TClient - The client object type. Must be an object (non-primitive)
+*   so it can serve as a WeakMap key.
+* @typeParam TStateNames - String literal union of valid state names.
+* @typeParam TInputNames - String literal union of valid input names.
+*/
+var BehavioralFsm = class {
+	id;
+	initialState;
+	[MACHINA_TYPE] = "BehavioralFsm";
+	states;
+	emitter = new Emitter();
+	clients = /* @__PURE__ */ new WeakMap();
+	knownClients = /* @__PURE__ */ new Set();
+	childSubscriptions = [];
+	disposed = false;
+	transitionDepth = 0;
+	constructor(config) {
+		this.id = config.id;
+		this.initialState = config.initialState;
+		this.states = config.states;
+		this.wrapChildLinks();
+		this.setupChildSubscriptions();
+	}
+	/**
+	* 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 childLink = this.states[meta.state]?._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 → 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 childLink = this.states[meta.state]?._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();
+	}
+	/**
+	* 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 childLink = this.states[stateName]?._child;
+			if (!childLink || seenChildren.has(childLink)) continue;
+			seenChildren.add(childLink);
+			const sub = childLink.onAny((eventName, data) => {
+				if (eventName === "nohandler") {
+					const payload = data;
+					if (payload.client !== void 0) this.bubbleNohandler(payload.client, childLink, payload.inputName, payload.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, payload.inputName, payload.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;
+		return this.states[meta.state]?._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);
+	}
+};
+/**
+* Internal factory called by `wrapChildLinks()` during construction.
+* Wraps a raw Fsm or BehavioralFsm instance in a uniform `ChildLink` adapter
+* so the parent engine doesn't need to know which type it's talking to.
+*
+* Users never call this directly — they assign an FSM instance to `_child`
+* in their state config and `wrapChildLinks()` handles the wrapping.
+*/
+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 {
+		instance: child,
+		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 {
+		instance: child,
+		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")}`);
+}
+/**
+* Create a behavioral FSM (one definition, many clients) from a config object.
+*
+* Generic parameters are inferred automatically:
+* - `TClient` must be provided explicitly as a type parameter (it can't be
+*   inferred from the config since no `context` property exists at the FSM level).
+* - `TStates` is captured with `const` inference to preserve string literal
+*   types, enabling compile-time validation of transition targets and `handle()`
+*   input names.
+*
+* State names, input names, and all handler signatures derive from `TStates`.
+*
+* @example
+* ```ts
+* interface Connection { url: string; retries: number; }
+*
+* const connFsm = createBehavioralFsm<Connection>({
+*   id: "connectivity",
+*   initialState: "disconnected",
+*   states: {
+*     disconnected: { connect: "connecting" },
+*     connecting:   { connected: "online", failed: "disconnected" },
+*     online:       { disconnect: "disconnected" },
+*   },
+* });
+*
+* const conn = { url: "wss://example.com", retries: 0 };
+* connFsm.handle(conn, "connect");
+* ```
+*/
+function createBehavioralFsm(config) {
+	return new BehavioralFsm(config);
+}
+
+//#endregion
+//#region src/fsm.ts
+/**
+* Single-client FSM. Wraps a BehavioralFsm and uses the config's `context`
+* object as the implicit client, so callers never pass a client argument.
+*
+* Prefer `createFsm()` over constructing this directly — the factory infers
+* all generic parameters from the config object.
+*
+* All public methods silently no-op after `dispose()` is called.
+*
+* @typeParam TCtx - The context type, inferred from `config.context`.
+* @typeParam TStateNames - String literal union of valid state names.
+* @typeParam TInputNames - String literal union of valid input names.
+*/
+var Fsm = class {
+	id;
+	initialState;
+	[MACHINA_TYPE] = "Fsm";
+	states;
+	bfsm;
+	context;
+	emitter = new Emitter();
+	disposed = false;
+	constructor(config) {
+		this.id = config.id;
+		this.initialState = config.initialState;
+		this.context = config.context ?? {};
+		this.bfsm = new BehavioralFsm(config);
+		this.states = config.states;
+		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);
+	}
+	/**
+	* 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();
+	}
+};
+/**
+* Create a single-client FSM from a config object.
+*
+* Generic parameters are inferred automatically:
+* - `TCtx` comes from `config.context` (defaults to `{}` if omitted).
+* - `TStates` is captured with `const` inference to preserve string literal
+*   types, enabling compile-time validation of transition targets and `handle()`
+*   input names.
+*
+* State names, input names, and all handler signatures derive from `TStates`.
+*
+* @example
+* ```ts
+* const light = createFsm({
+*   id: "traffic-light",
+*   initialState: "green",
+*   context: { tickCount: 0 },
+*   states: {
+*     green:  { timeout: "yellow" },
+*     yellow: { timeout: "red" },
+*     red:    { timeout: "green" },
+*   },
+* });
+*
+* light.handle("timeout"); // transitions green → yellow
+* ```
+*/
+function createFsm(config) {
+	return new Fsm(config);
+}
+
+//#endregion
+exports.BehavioralFsm = BehavioralFsm;
+exports.Fsm = Fsm;
+exports.MACHINA_TYPE = MACHINA_TYPE;
+exports.createBehavioralFsm = createBehavioralFsm;
+exports.createFsm = createFsm;
+//# sourceMappingURL=index.cjs.map