@mantaq/traversal 0.0.2 → 0.1.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AnyActor, Context, Snapshot } from "@mantaq/core";
+import { AnyActor, Context, Snapshot, TransitionInfo } from "@mantaq/core";
 //#region src/types.d.ts
 interface GraphNode {
   id: string;
@@ -49,7 +49,7 @@ interface HistoryEntry {
 //#region src/graph.d.ts
 declare const INITIAL_NODE_ID = "__initial__";
 declare function collectActiveStates(snapshot: Snapshot, prefix: string, activeSet: Set<string>): void;
-declare function buildGraph(actor: AnyActor, options?: {
+declare function buildGraph<C>(actor: AnyActor<C>, options?: {
   internalIds?: Set<string>;
   sampleContext?: Record<string, unknown>;
   sampleContexts?: Record<string, Record<string, unknown>>;
@@ -73,21 +73,25 @@ declare class History {
 }
 //#endregion
 //#region src/instrument.d.ts
-interface InstrumentedActor {
+interface InstrumentedActor<C = Record<string, unknown>> {
   history: History;
   send(event: unknown): void;
   state: AnyActor["state"];
-  snapshot(): Snapshot<Record<string, unknown>>;
+  snapshot(): Snapshot<C>;
   regions: Record<string, AnyActor>;
-  context?: Record<string, unknown>;
+  context?: C;
   clock: AnyActor["clock"];
-  on(event: "change", fn: (snapshot: Snapshot<Record<string, unknown>>, prev: Snapshot<Record<string, unknown>>) => void): () => void;
-  on(event: "error", fn: (error: unknown) => void): () => void;
+  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
+  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
   on(event: "done", fn: () => void): () => void;
+  recover(target: {
+    state: AnyActor["state"];
+    context: C;
+  }): void;
   settled(): Promise<void>;
   options?: AnyActor["options"];
 }
-declare function instrument(actor: AnyActor): InstrumentedActor;
+declare function instrument<C>(actor: AnyActor<C>): InstrumentedActor<C>;
 //#endregion
 //#region src/algorithms.d.ts
 declare function reachable(graph: ActorGraph, fromId: string, toId: string): boolean;

package/dist/index.mjs

@@ -8,7 +8,7 @@ function collectActiveStates(snapshot, prefix, activeSet) {
 	if (!currentName) return;
 	const fullId = nodeId(prefix, currentName);
 	activeSet.add(fullId);
-	if (snapshot.regions && !snapshot.done) for (const [regionName, regionSnap] of Object.entries(snapshot.regions)) collectActiveStates(regionSnap, regionName, activeSet);
+	if (snapshot.regions && !snapshot.done && !snapshot.error) for (const [regionName, regionSnap] of Object.entries(snapshot.regions)) collectActiveStates(regionSnap, regionName, activeSet);
 }
 function nodeId(prefix, name) {
 	return prefix ? `${prefix}.${name}` : name;
@@ -26,13 +26,16 @@ function buildNodesFromStates(states, activeSet, pathPrefix) {
 }
 function invokeHandler(handler, eventId, context, actor) {
 	return Either.from(() => {
-		const result = handler({ id: eventId }, {
+		const result = handler({
+			type: eventId,
+			payload: {}
+		}, {
 			context: new Context(() => context, () => {}),
 			actor
 		});
 		return {
 			targetName: result?.state?.name,
-			emitNames: result?.emit?.map((e) => e.id).filter((id) => Boolean(id)) ?? []
+			emitNames: result?.emit?.map((e) => e.type).filter((type) => Boolean(type)) ?? []
 		};
 	});
 }
@@ -220,11 +223,7 @@ function buildGraph(actor, options) {
 			edges
 		};
 	}), (error) => {
-		console.error("[mantaq/traversal] buildGraph failed:", error);
-		return {
-			nodes: [],
-			edges: []
-		};
+		throw error;
 	}, (result) => result);
 }
 //#endregion
@@ -272,8 +271,8 @@ var History = class {
 };
 //#endregion
 //#region src/instrument.ts
-function wrapWithProxy(actor, hooks) {
-	const { history, origSend, pendingEventId } = hooks;
+function wrapWithProxy(actor, history) {
+	const origSend = actor.send.bind(actor);
 	return {
 		get history() {
 			return history;
@@ -294,48 +293,45 @@ function wrapWithProxy(actor, hooks) {
 			return actor.options;
 		},
 		send(event) {
-			const { id: eventId } = trackSendEvent(history, event);
-			pendingEventId.value = eventId;
-			try {
-				origSend(event);
-			} finally {
-				pendingEventId.value = void 0;
-			}
+			trackSendEvent(history, event);
+			origSend(event);
 		},
 		snapshot() {
 			return actor.snapshot();
 		},
 		on: actor.on.bind(actor),
+		recover: actor.recover.bind(actor),
 		settled: actor.settled.bind(actor)
 	};
 }
-function recordTransition(history, from, to, eventId) {
+function recordTransition(history, rec) {
 	history.append({
 		type: "transition",
 		data: {
-			from,
-			event: eventId,
-			to,
+			from: rec.from,
+			event: rec.event,
+			to: rec.to,
 			timestamp: Date.now()
 		}
 	});
+	if (!rec.transitioned) return;
 	history.append({
 		type: "state_visit",
 		data: {
-			stateName: to,
+			stateName: rec.to,
 			timestamp: Date.now()
 		}
 	});
-	history.append({
+	if ((rec.effects[rec.to] ?? []).length > 0) history.append({
 		type: "effect",
 		data: {
-			stateName: to,
+			stateName: rec.to,
 			timestamp: Date.now()
 		}
 	});
 }
 function trackSendEvent(history, event) {
-	const eventId = event?.id ?? "unknown";
+	const eventId = event?.type ?? "unknown";
 	history.append({
 		type: "send",
 		data: {
@@ -343,13 +339,9 @@ function trackSendEvent(history, event) {
 			timestamp: Date.now()
 		}
 	});
-	return { id: eventId };
 }
 function instrument(actor) {
 	const history = new History();
-	const origSend = actor.send.bind(actor);
-	let prevStateName = actor.state.name;
-	const pendingEventId = { value: void 0 };
 	history.append({
 		type: "state_visit",
 		data: {
@@ -357,17 +349,16 @@ function instrument(actor) {
 			timestamp: Date.now()
 		}
 	});
-	const wrapped = wrapWithProxy(actor, {
-		history,
-		origSend,
-		pendingEventId
-	});
-	actor.on("change", () => {
-		const currentName = actor.state.name;
-		if (currentName !== prevStateName) {
-			recordTransition(history, prevStateName, currentName, pendingEventId.value ?? "unknown");
-			prevStateName = currentName;
-		}
+	const wrapped = wrapWithProxy(actor, history);
+	const effectsByState = actor.options?.effects ?? {};
+	actor.on("transition", ({ event, from, to, transitioned }) => {
+		recordTransition(history, {
+			from,
+			to,
+			event: event.type,
+			transitioned,
+			effects: effectsByState
+		});
 	});
 	return wrapped;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/traversal",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "description": "Graph extraction, traversal algorithms, and runtime tracking for mantaq actors.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/core": "0.0.2",
-    "@mantaq/utils": "0.0.1"
+    "@mantaq/core": "0.2.0",
+    "@mantaq/utils": "0.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",