machina 6.3.0 → 7.0.0

package/README.md

@@ -76,7 +76,7 @@ light.dispose(); // tears down; all subsequent calls are silent no-ops
 
 `createBehavioralFsm` defines behavior once and applies it to any number of independent client objects. Per-client state lives in a `WeakMap` — no properties are stamped onto the client. The client object IS the context; handlers receive it as `ctx`.
 
-The client type is provided as an explicit type parameter since it can't be inferred from the config.
+The client type can't be inferred from the config, so it's provided via a curried call — `createBehavioralFsm<Connection>()` — that fixes the client type before the config (and its literal state/input names) is inferred from the second call.
 
 ```ts
 import { createBehavioralFsm } from "machina";
@@ -86,7 +86,7 @@ interface Connection {
     retries: number;
 }
 
-const connFsm = createBehavioralFsm<Connection>({
+const connFsm = createBehavioralFsm<Connection>()({
     id: "connectivity",
     initialState: "disconnected",
     states: {

package/dist/index.cjs

@@ -51,6 +51,121 @@ var Emitter = class {
 	}
 };
 
+//#endregion
+//#region src/json-safe.ts
+/**
+* Thrown internally when the walk hits a value that can't survive a
+* serialization boundary. Callers catch this to attach FSM/input context
+* before re-throwing a fully descriptive error — see `path`/`label` below.
+*/
+var NonSerializableValueError = class extends Error {
+	constructor(path, label) {
+		super(`non-serializable value at ${path} (${label})`);
+		this.path = path;
+		this.label = label;
+	}
+};
+/**
+* Deep-clones `value`, throwing `NonSerializableValueError` the moment it
+* finds anything that isn't `null`, a boolean, a finite number, a string, a
+* plain array, or a plain object. `rootPath` seeds the path used in error
+* messages — e.g. `"args"` so a nested failure reads as `args[1].onComplete`.
+*
+* Cloning (rather than just validating) is what keeps a returned snapshot
+* from aliasing live FSM state: mutating the snapshot afterward — or the
+* original value passed into a deferred `handle()` call — can't reach back
+* into the FSM's internal deferred queue.
+*/
+const cloneJsonSafe = (value, rootPath) => {
+	return cloneNode(value, rootPath, /* @__PURE__ */ new Set());
+};
+const cloneNode = (value, path, ancestors) => {
+	if (value === null) return null;
+	switch (typeof value) {
+		case "string":
+		case "boolean": return value;
+		case "number":
+			if (!Number.isFinite(value)) throw new NonSerializableValueError(path, describeNonFiniteNumber(value));
+			return value;
+		case "object": return cloneObject(value, path, ancestors);
+		default: throw new NonSerializableValueError(path, typeof value);
+	}
+};
+const cloneObject = (obj, path, ancestors) => {
+	if (ancestors.has(obj)) throw new NonSerializableValueError(path, "circular reference");
+	if (Array.isArray(obj)) {
+		if (obj.length !== Object.keys(obj).length) throw new NonSerializableValueError(path, "sparse array or array with non-index properties");
+		ancestors.add(obj);
+		const cloned = obj.map((item, i) => cloneNode(item, `${path}[${i}]`, ancestors));
+		ancestors.delete(obj);
+		return cloned;
+	}
+	const proto = Object.getPrototypeOf(obj);
+	if (proto !== Object.prototype && proto !== null) throw new NonSerializableValueError(path, obj.constructor?.name ?? "object");
+	ancestors.add(obj);
+	const cloned = {};
+	for (const key of Object.keys(obj)) {
+		const value = cloneNode(obj[key], `${path}.${key}`, ancestors);
+		Object.defineProperty(cloned, key, {
+			value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	ancestors.delete(obj);
+	return cloned;
+};
+const describeNonFiniteNumber = (n) => {
+	if (Number.isNaN(n)) return "NaN";
+	return n > 0 ? "Infinity" : "-Infinity";
+};
+/**
+* Deep-clones `value` WITHOUT validating it — unlike `cloneJsonSafe`, this
+* never throws. Plain objects/arrays are cloned recursively (so a caller
+* can't alias state back into whatever holds the result); anything else
+* (functions, `Date`/`Map`/class instances, symbols, non-finite numbers,
+* etc.) is passed through by reference as-is.
+*
+* This is `rehydrate()`'s side of the aliasing guarantee: `dehydrate()`
+* validates-and-clones on the way OUT (via `cloneJsonSafe`), but `rehydrate()`
+* trusts the snapshot it's given is already valid data — re-validating on
+* the way IN would be a redundant, unwanted asymmetry (see the build plan's
+* disclosed known gaps). We still need the clone so mutating the caller's
+* snapshot object after `rehydrate()` returns can't reach into the live
+* FSM's internal deferred queue.
+*
+* Cycle-safe: a value that contains itself is returned as-is (by reference)
+* rather than cloned infinitely — there's no validation step here to make
+* that throw, so silently keeping the shared reference is the only option
+* that doesn't hang.
+*/
+const cloneDeep = (value, ancestors = /* @__PURE__ */ new Set()) => {
+	if (value === null || typeof value !== "object") return value;
+	if (ancestors.has(value)) return value;
+	if (Array.isArray(value)) {
+		ancestors.add(value);
+		const cloned = value.map((item) => cloneDeep(item, ancestors));
+		ancestors.delete(value);
+		return cloned;
+	}
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) return value;
+	ancestors.add(value);
+	const cloned = {};
+	for (const key of Object.keys(value)) {
+		const clonedValue = cloneDeep(value[key], ancestors);
+		Object.defineProperty(cloned, key, {
+			value: clonedValue,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	ancestors.delete(value);
+	return cloned;
+};
+
 //#endregion
 //#region src/types.ts
 /**
@@ -78,6 +193,9 @@ const MAX_TRANSITION_DEPTH = 20;
 *   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.
+* @typeParam TBubbles - String literal union of inputs this FSM declares via
+*   `bubbles`. Type-only — carried so `BubblesOfInstance` can extract it from
+*   a constructed instance; nothing at runtime reads this generic.
 */
 var BehavioralFsm = class {
 	id;
@@ -126,15 +244,20 @@ var BehavioralFsm = class {
 	}
 	/**
 	* 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.
+	* (or a catch-all `"*"` handler), or if the current state's `_child` chain
+	* can handle it — the check recurses to the same depth `handle()`'s
+	* delegation can actually reach, so a grandchild-only input answers true
+	* from the root. 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?.["*"]);
+		if (stateObj?.[inputName] ?? stateObj?.["*"]) return true;
+		const childLink = stateObj?._child;
+		return childLink ? childLink.canHandle(client, inputName) : false;
 	}
 	/**
 	* Transition the client back to `initialState`, firing `_onEnter` and
@@ -169,7 +292,7 @@ var BehavioralFsm = class {
 		const meta = this.getOrCreateClientMeta(client);
 		const fromState = meta.state;
 		if (toState === fromState) return;
-		if (!(toState in this.states)) {
+		if (!Object.hasOwn(this.states, toState)) {
 			this.emitter.emit("invalidstate", {
 				stateName: toState,
 				client
@@ -225,25 +348,96 @@ var BehavioralFsm = class {
 		}
 		return meta.state;
 	}
+	rehydrate(client, input) {
+		if (this.disposed) return;
+		if (typeof input === "string") {
+			this.rehydrateCompositePath(client, input);
+			return;
+		}
+		const writes = this.planSnapshotWrites(client, input);
+		for (const write of writes) write();
+	}
 	/**
-	* Silently place `client` at `compositeState` with no lifecycle activity.
-	* Designed to work with `compositeState()`, which produces the dot-path
-	* string that `rehydrate()` consumes.
+	* Snapshot everything machina tracks for `client`: current state, pending
+	* deferred inputs, and — recursively — the same for every `_child` that has
+	* ever seen this client, active or not. Feed the result to the object form
+	* of `rehydrate()` to restore it later, deferrals included.
 	*
-	* No `_onEnter`, no `_onExit`, no `transitioning`/`transitioned` events.
-	* If `compositeState` is a dot-delimited path (`"active.connecting"`), the client
-	* is placed at each level of the hierarchy in turn. Subsequent `handle()` calls
-	* proceed as if the client had reached that state through normal transitions.
+	* Returns `undefined` for a client this FSM has never seen (mirrors
+	* `currentState()`) — the call does NOT trigger initialization.
 	*
-	* Throws synchronously for unknown state names, missing `_child` at an inner level,
-	* or Fsm children in the hierarchy (Fsm owns its context; nothing to rehydrate there).
+	* Throws if any deferred input's args contain a non-serializable value
+	* (function, undefined, symbol, bigint, non-finite number, Date/Map/class
+	* instance, or a circular reference) — naming the input, its `until` target
+	* if any, the FSM id, and the exact value path. Throws for an Fsm child
+	* that's on `client`'s active path *relative to the true root* (consistent
+	* with `rehydrate()`'s conditional throw) — an Fsm owns its own context, so
+	* there's nothing per-client to snapshot. An Fsm child declared at a state
+	* `client` never visited, OR nested under a `BehavioralFsm` child that is
+	* itself off-path from the root, is skipped rather than throwing — neither
+	* has any per-client state to lose, so one Fsm child anywhere in the
+	* hierarchy doesn't disable `dehydrate()` for clients that never reach that
+	* branch, no matter how deeply nested the Fsm child is.
 	*
-	* No-ops silently when disposed.
+	* Meant for clients at rest between `handle()` calls — `currentActionArgs`
+	* (the in-flight args mid-handler) has no meaning here and is excluded.
+	*
+	* @param isOnActivePath - @internal Whether this FSM itself is currently
+	* reachable from the true root's active path. Defaults to `true` for the
+	* public entry point (this FSM IS the root from its own perspective); the
+	* `ChildLink` adapter passes `false` down when recursing into a nested
+	* `BehavioralFsm` child that is itself off-path, so that child's own
+	* Fsm-child checks don't recompute reachability from its dormant local
+	* state alone.
 	*/
-	rehydrate(client, compositeState) {
-		if (this.disposed) return;
+	dehydrate(client, isOnActivePath = true) {
+		const meta = this.clients.get(client);
+		if (!meta) return;
+		const snapshot = {
+			state: meta.state,
+			deferred: meta.deferredQueue.map((item) => this.snapshotDeferredInput(item))
+		};
+		const children = this.collectChildSnapshots(client, meta.state, isOnActivePath);
+		if (children) snapshot.children = children;
+		return snapshot;
+	}
+	/**
+	* @internal
+	* Validates `snapshot` against this level's state graph and recurses into
+	* every declared child, returning write thunks to run only once the WHOLE
+	* tree — every level — validates successfully. Nothing is written here.
+	* Called by the object-form of `rehydrate()` and, recursively, by ChildLink
+	* so a nested BehavioralFsm participates in the same validate-then-write
+	* pass. Not part of the public persistence API — call `rehydrate()` instead.
+	*/
+	planSnapshotWrites(client, snapshot) {
+		if (this.disposed) return [];
+		const { state, deferred, children } = snapshot;
+		if (!Object.hasOwn(this.states, state)) throw new Error(`rehydrate: unknown state "${state}" in FSM "${this.id}". Valid states: ${Object.keys(this.states).join(", ")}`);
+		const writes = [];
+		if (children) for (const stateName of Object.keys(children)) {
+			if (!Object.hasOwn(this.states, stateName)) throw new Error(`rehydrate: unknown state "${stateName}" in FSM "${this.id}" referenced by snapshot.children.`);
+			const childLink = this.states[stateName]?._child;
+			if (!childLink) throw new Error(`rehydrate: state "${stateName}" in FSM "${this.id}" has no _child, but the snapshot has a children["${stateName}"] entry.`);
+			writes.push(...childLink.planRehydrate(client, children[stateName]));
+		}
+		const deferredQueue = deferred.map((item) => ({
+			inputName: item.inputName,
+			args: cloneDeep(item.args),
+			...item.untilState !== void 0 ? { untilState: item.untilState } : {}
+		}));
+		writes.push(() => {
+			if (!this.clients.has(client)) this.knownClients.add(new WeakRef(client));
+			this.clients.set(client, {
+				state,
+				deferredQueue
+			});
+		});
+		return writes;
+	}
+	rehydrateCompositePath(client, compositeState) {
 		const [state, ...rest] = compositeState.split(".");
-		if (!(state in this.states)) throw new Error(`rehydrate: unknown state "${state}" in FSM "${this.id}". Valid states: ${Object.keys(this.states).join(", ")}`);
+		if (!Object.hasOwn(this.states, state)) throw new Error(`rehydrate: unknown state "${state}" in FSM "${this.id}". Valid states: ${Object.keys(this.states).join(", ")}`);
 		if (rest.length > 0) {
 			const childPath = rest.join(".");
 			const childLink = this.states[state]?._child;
@@ -256,6 +450,80 @@ var BehavioralFsm = class {
 			deferredQueue: []
 		});
 	}
+	/**
+	* Walks every declared state's `_child`, dehydrating each one that has ever
+	* seen `client`. The same child instance can be declared under multiple
+	* state names (shared child) — it's dehydrated once and the result is
+	* reused under every declaring state name, matching how the engine already
+	* treats shared children elsewhere (dispose, event subscriptions).
+	*
+	* Declaring names are grouped by `childLink.instance` (the actual FSM
+	* instance, not the `ChildLink` wrapper — `wrapChildLinks()` mints a fresh
+	* wrapper per declaring state, so grouping by wrapper would never hit for a
+	* shared child) BEFORE any `onPath` is computed or any child is dehydrated.
+	* A shared child's `onPath` is the OR of `stateName === activeState` across
+	* every declaring name in its group: at most one declaring name can ever
+	* equal `activeState`, so this combined flag is correct and, critically,
+	* independent of `Object.keys(this.states)` iteration order — computing
+	* `onPath` per-declaring-name and caching whichever one happened to run
+	* first would silently launder an on-path client's Fsm-child throw through
+	* an unrelated off-path declaring name.
+	*
+	* An off-path Fsm child (declared only at states other than `activeState`,
+	* OR nested anywhere under a `BehavioralFsm` child that is itself off-path
+	* relative to the true root) is skipped entirely rather than dehydrated:
+	* Fsm state isn't tracked per-client to begin with, so an off-path Fsm
+	* child has nothing to lose by being skipped — unlike a BehavioralFsm
+	* child's off-path meta, which is real per-client data. `isOnActivePath`
+	* is the inherited "am I even reachable from the root" flag; combining it
+	* with the group's `stateNames.includes(activeState)` check (rather than
+	* using that check alone) is what keeps a nested Fsm grandchild from
+	* throwing when its immediate BehavioralFsm parent is itself off-path —
+	* the parent's own dormant `activeState` is irrelevant once the parent
+	* isn't reachable. This keeps one Fsm child anywhere in the hierarchy from
+	* disabling `dehydrate()` for every client, only for clients actually on
+	* that branch.
+	*/
+	collectChildSnapshots(client, activeState, isOnActivePath) {
+		const declaringNamesByInstance = /* @__PURE__ */ new Map();
+		for (const stateName of Object.keys(this.states)) {
+			const childLink = this.states[stateName]?._child;
+			if (!childLink) continue;
+			const entry = declaringNamesByInstance.get(childLink.instance);
+			if (entry) entry.stateNames.push(stateName);
+			else declaringNamesByInstance.set(childLink.instance, {
+				childLink,
+				stateNames: [stateName]
+			});
+		}
+		let children;
+		for (const { childLink, stateNames } of declaringNamesByInstance.values()) {
+			const onPath = isOnActivePath && stateNames.includes(activeState);
+			if (childLink.instance[MACHINA_TYPE] === "Fsm" && !onPath) continue;
+			const childSnapshot = childLink.dehydrate(client, onPath);
+			if (childSnapshot) {
+				children ??= {};
+				for (const stateName of stateNames) children[stateName] = childSnapshot;
+			}
+		}
+		return children;
+	}
+	snapshotDeferredInput(item) {
+		let clonedArgs;
+		try {
+			clonedArgs = cloneJsonSafe(item.args, "args");
+		} catch (err) {
+			if (!(err instanceof NonSerializableValueError)) throw err;
+			const untilPart = item.untilState ? ` (until "${item.untilState}")` : "";
+			throw new Error(`dehydrate: deferred input "${item.inputName}"${untilPart} in FSM "${this.id}" has a non-serializable value at ${err.path} (${err.label})`);
+		}
+		const snapshot = {
+			inputName: item.inputName,
+			args: clonedArgs
+		};
+		if (item.untilState !== void 0) snapshot.untilState = item.untilState;
+		return snapshot;
+	}
 	on(eventName, callback) {
 		if (this.disposed) return { off() {} };
 		return this.emitter.on(eventName, callback);
@@ -282,8 +550,8 @@ var BehavioralFsm = class {
 			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);
+				if (childLink && !seen.has(childLink.instance)) {
+					seen.add(childLink.instance);
 					childLink.dispose();
 				}
 			}
@@ -309,15 +577,23 @@ var BehavioralFsm = class {
 	/**
 	* 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.
+	* stored for cleanup in dispose(). We deduplicate by `childLink.instance`
+	* (the underlying Fsm/BehavioralFsm instance), not the `ChildLink` wrapper —
+	* `wrapChildLinks()` mints a fresh wrapper per declaring state, so a child
+	* shared across states would otherwise get one subscription PER declaring
+	* state, each independently walking known clients and relaying events. That
+	* silently double-fires client-less relays (Fsm-child events, or a
+	* BehavioralFsm child's custom `emit()` with no `client` in the payload)
+	* whenever two different clients are active on two different declaring
+	* names at once — the same wrapper-vs-instance identity bug
+	* `collectChildSnapshots()` had before its #184 fix.
 	*/
 	setupChildSubscriptions() {
-		const seenChildren = /* @__PURE__ */ new Set();
+		const seenInstances = /* @__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);
+			if (!childLink || seenInstances.has(childLink.instance)) continue;
+			seenInstances.add(childLink.instance);
 			const sub = childLink.onAny((eventName, data) => {
 				if (eventName === "nohandler") {
 					const payload = data;
@@ -363,13 +639,22 @@ var BehavioralFsm = class {
 	}
 	/**
 	* 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.
+	* _child resolves to the same underlying instance as childLink. Returns
+	* false if the client has no meta (never initialized) or is in a state
+	* with a different (or no) child.
+	*
+	* Compares `.instance`, not the `ChildLink` wrapper itself — setupChildSubscriptions()
+	* dedupes subscriptions by instance and keeps only ONE representative wrapper
+	* per shared child, so the client's actual active declaring state may hold a
+	* DIFFERENT wrapper for that same instance (wrapChildLinks() mints one per
+	* declaring state). Comparing wrappers directly would only ever match the one
+	* declaring state whose wrapper happened to be kept for the subscription,
+	* silently breaking relay for every other declaring name of a shared child.
 	*/
 	isChildActiveForClient(client, childLink) {
 		const meta = this.clients.get(client);
 		if (!meta) return false;
-		return this.states[meta.state]?._child === childLink;
+		return (this.states[meta.state]?._child)?.instance === childLink.instance;
 	}
 	/**
 	* The inner handler dispatch — no delegation, no initialization side effects
@@ -480,6 +765,12 @@ function createChildLink(child) {
 		rehydrate(client, compositeState) {
 			child.rehydrate(client, compositeState);
 		},
+		dehydrate(client, isOnActivePath) {
+			return child.dehydrate(client, isOnActivePath);
+		},
+		planRehydrate(client, snapshot) {
+			return child.planSnapshotWrites(client, snapshot);
+		},
 		dispose() {
 			child.dispose();
 		}
@@ -504,43 +795,20 @@ function createChildLink(child) {
 		rehydrate(_client, _compositeState) {
 			throw new Error("rehydrate: cannot rehydrate an Fsm child. Fsm owns its own context; rehydrate is only valid for BehavioralFsm hierarchies.");
 		},
+		dehydrate(_client, _isOnActivePath) {
+			throw new Error("dehydrate: cannot dehydrate an Fsm child. Fsm owns its own context; dehydrate is only valid for BehavioralFsm hierarchies.");
+		},
+		planRehydrate(_client, _snapshot) {
+			throw new Error("rehydrate: cannot rehydrate an Fsm child. Fsm owns its own context; rehydrate is only valid for BehavioralFsm hierarchies.");
+		},
 		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) {
+	if (config === void 0) return (curriedConfig) => new BehavioralFsm(curriedConfig);
 	return new BehavioralFsm(config);
 }
 
@@ -558,6 +826,9 @@ function createBehavioralFsm(config) {
 * @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.
+* @typeParam TBubbles - String literal union of inputs this FSM declares via
+*   `bubbles`. Type-only — carried so `BubblesOfInstance` can extract it from
+*   a constructed instance; nothing at runtime reads this generic.
 */
 var Fsm = class {
 	id;
@@ -594,8 +865,10 @@ var Fsm = class {
 	}
 	/**
 	* 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.
+	* (or a catch-all `"*"` handler), or if the current state's `_child`
+	* chain can handle it (checked recursively, matching `handle()`'s
+	* delegation reach). Does not trigger initialization or any side
+	* effects. Returns false when disposed.
 	*/
 	canHandle(inputName) {
 		if (this.disposed) return false;