@mantaq/core 0.0.1 → 0.0.2

package/README.md

@@ -177,8 +177,8 @@ const actor = new Actor({
   initial: idleState,
   setup: (m) => {
     m.effect(loadingState, ({ state, emit, clock }) => {
-      // state.payload is unknown — cast to the known shape
-      const { url } = state.payload as { url: string };
+      // state.payload is typed to the state's declared payload: { url: string }
+      const url = state.payload.url;
       clock.setTimeout(1000, () => {
         emit(doneEvent.create());
       });

package/dist/{actor-internal-CfZDmHJ3.d.mts → actor-internal-CBU_EDPZ.d.mts}

@@ -61,21 +61,22 @@ interface Clock {
 }
 //#endregion
 //#region src/actor-internal.d.ts
-interface Snapshot {
+interface Snapshot<C = unknown> {
   path: string[];
-  regions: Record<string, Snapshot>;
+  context: C;
+  regions: Record<string, Snapshot<unknown>>;
   done?: boolean;
 }
-interface AnyActor {
+interface AnyActor<C = Record<string, unknown>> {
   state: AnyStateRef;
   clock: Clock;
   regions: Record<string, AnyActor>;
   send(event: AnyEventRef | InternalEvent): void;
-  snapshot(): Snapshot;
-  on(event: "change", fn: (snapshot: Snapshot) => void): () => void;
+  snapshot(): Snapshot<C>;
+  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
   on(event: "done", fn: () => void): () => void;
   settled(): Promise<void>;
-  context?: Record<string, unknown>;
+  context?: C;
   options?: {
     transitions?: Record<string, Record<string, unknown>>;
     effects?: Record<string, unknown[]>;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CreatedOfEvent, c as event, d as state, i as AnyEventRef, l as AnyStateRef, n as Snapshot, o as EventRef, r as Clock, s as InternalEvent, t as AnyActor, u as StateRef } from "./actor-internal-CfZDmHJ3.mjs";
+import { a as CreatedOfEvent, c as event, d as state, i as AnyEventRef, l as AnyStateRef, n as Snapshot, o as EventRef, r as Clock, s as InternalEvent, t as AnyActor, u as StateRef } from "./actor-internal-CBU_EDPZ.mjs";
 //#region src/real-clock.d.ts
 declare class RealClock implements Clock {
   #private;
@@ -38,23 +38,31 @@ declare class VirtualClock implements Clock {
   setDrain(fn: () => void): void;
 }
 //#endregion
+//#region src/context.d.ts
+declare class Context<T> {
+  #private;
+  constructor(get: () => T, set: (value: T) => void);
+  get(): T;
+  set(value: T): void;
+}
+//#endregion
 //#region src/actor-types.d.ts
 type CreatedOf<E extends AnyEventRef> = E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never;
 type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
   isFinal: false;
 }>;
-interface EffectInput<ActorContext> {
+interface EffectInput<ActorContext, Payload = unknown> {
   signal: AbortSignal;
   state: {
     name: string;
-    payload: unknown;
+    payload: Payload;
   };
   event: InternalEvent;
-  context: ActorContext;
+  context: Context<ActorContext>;
   emit: (event: InternalEvent) => void;
   clock: Clock;
 }
-type EffectFn<ActorContext> = (input: EffectInput<ActorContext>) => void;
+type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void;
 type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
   state?: AllowedState | {
     state: AllowedState;
@@ -68,8 +76,9 @@ type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmi
 //#endregion
 //#region src/builder.d.ts
 type EventIdOf<E extends AnyEventRef> = E extends EventRef<infer Id, object | void> ? Id : never;
+type PayloadOf<S extends AnyStateRef> = S extends StateRef<infer _Name, infer Payload, infer _IsFinal> ? Payload : never;
 type TransitionHandler<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, opts: {
-  context: ActorContext;
+  context: Context<ActorContext>;
   actor: AnyActor;
 }) => TransitionResult<States[number], string>;
 interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
@@ -79,14 +88,14 @@ interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
 declare class ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> {
   #private;
   on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
-    context: ActorContext;
+    context: Context<ActorContext>;
     actor: AnyActor;
   }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
   onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
-    context: ActorContext;
+    context: Context<ActorContext>;
     actor: AnyActor;
   }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
-  effect<S extends States[number]>(stateRef: S, fn: EffectFn<ActorContext>): this;
+  effect<S extends States[number]>(stateRef: S, fn: EffectFn<ActorContext, PayloadOf<S>>): this;
   /** @internal */ build(): BuiltMaps<States, ActorContext>;
 }
 type SetupFn<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
@@ -130,7 +139,7 @@ interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs ext
   regions?: Record<string, AnyActor>;
 }
 type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = Record<string, Record<string, ((event: InternalEvent, options: {
-  context: ActorContext;
+  context: Context<ActorContext>;
   actor: AnyActor;
 }) => TransitionResult<States[number], string>) | undefined>>;
 declare class Actor<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>> {
@@ -141,11 +150,11 @@ declare class Actor<const States extends readonly AnyStateRef[], const Inputs ex
   get regions(): Record<string, AnyActor>;
   get options(): InternalActorOptions<States, Inputs, Internal, Outputs, ActorContext>;
   constructor(options: ActorOptions<States, Inputs, Internal, Outputs, ActorContext>);
-  on(event: "change", fn: (snapshot: Snapshot) => void): () => void;
+  on(event: "change", fn: (snapshot: Snapshot<ActorContext>, prev: Snapshot<ActorContext>) => void): () => void;
   on(event: "done", fn: () => void): () => void;
   settled(): Promise<void>;
   send(event: CreatedOf$1<Inputs[number]>): void;
-  snapshot(): Snapshot;
+  snapshot(): Snapshot<ActorContext>;
 }
 //#endregion
-export { Actor, type ActorBuilder, type AnyActor, type AnyEventRef, type AnyStateRef, type Clock, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, EventRef, type InternalEvent, type NonFinalStateRef, RealClock, type SetupFn, type Snapshot, StateRef, VirtualClock, event, state };
+export { Actor, type ActorBuilder, type AnyActor, type AnyEventRef, type AnyStateRef, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, EventRef, type InternalEvent, type NonFinalStateRef, RealClock, type SetupFn, type Snapshot, StateRef, VirtualClock, event, state };

package/dist/index.mjs

@@ -254,8 +254,13 @@ var InternalQueue = class {
 var Subscribers = class {
 	change = /* @__PURE__ */ new Set();
 	done = /* @__PURE__ */ new Set();
+	#last = null;
+	seed(snapshot) {
+		this.#last = snapshot;
+	}
 	addChange(fn) {
 		this.change.add(fn);
+		if (this.#last) fn(this.#last, this.#last);
 		return () => this.change.delete(fn);
 	}
 	addDone(fn) {
@@ -263,7 +268,9 @@ var Subscribers = class {
 		return () => this.done.delete(fn);
 	}
 	emitChange(snapshot) {
-		for (const fn of this.change) fn(snapshot);
+		const prev = this.#last ?? snapshot;
+		this.#last = snapshot;
+		for (const fn of this.change) fn(snapshot, prev);
 	}
 	emitDone() {
 		for (const fn of this.done) fn();
@@ -275,12 +282,13 @@ var Subscribers = class {
 };
 //#endregion
 //#region src/snapshot.ts
-function buildSnapshot(s, regions) {
+function buildSnapshot(s, regions, context) {
 	const path = [s.name];
 	const regionSnapshots = {};
 	for (const [regionName, child] of Object.entries(regions)) regionSnapshots[regionName] = child.snapshot();
 	const snap = {
 		path,
+		context,
 		regions: regionSnapshots
 	};
 	if (s.isFinal) snap.done = true;
@@ -320,6 +328,22 @@ function parseTarget(step) {
 	};
 }
 //#endregion
+//#region src/context.ts
+var Context = class {
+	#get;
+	#set;
+	constructor(get, set) {
+		this.#get = get;
+		this.#set = set;
+	}
+	get() {
+		return this.#get();
+	}
+	set(value) {
+		this.#set(value);
+	}
+};
+//#endregion
 //#region src/builder.ts
 var ActorBuilder = class {
 	#transitions = {};
@@ -358,6 +382,9 @@ var Actor = class {
 	state;
 	clock;
 	#context;
+	#contextHandle;
+	#lastState;
+	#lastContext;
 	#options;
 	#regions = {};
 	#children = /* @__PURE__ */ new Map();
@@ -407,6 +434,12 @@ var Actor = class {
 		if (!stateNames.has(initState.name)) console.warn(`[Actor] initial state "${initState.name}" not found in declared states [${[...stateNames].join(", ")}]`);
 		this.state = initState;
 		this.#context = options.context ?? {};
+		this.#lastState = initState;
+		this.#lastContext = this.#context;
+		this.#contextHandle = new Context(() => this.#context, (value) => {
+			this.#context = value;
+		});
+		this.#subs.seed(this.snapshot());
 		if (options.regions) for (const [key, child] of Object.entries(options.regions)) {
 			this.#regions[key] = child;
 			const result = setOutputHandler(child, (event) => {
@@ -420,19 +453,23 @@ var Actor = class {
 	on(event, fn) {
 		if (event === "change") {
 			const cb = fn;
-			this.#subs.change.add(cb);
-			cb(this.snapshot());
-			return () => this.#subs.change.delete(cb);
+			return this.#subs.addChange(cb);
 		}
 		const cb = fn;
-		this.#subs.done.add(cb);
-		return () => this.#subs.done.delete(cb);
+		return this.#subs.addDone(cb);
 	}
 	settled() {
 		return this.#queue.settled();
 	}
 	send(event) {
 		this.#dispatch(event);
+		this.#emitChangeIfDirty();
+	}
+	#emitChangeIfDirty() {
+		if (this.state === this.#lastState && this.#context === this.#lastContext) return;
+		this.#lastState = this.state;
+		this.#lastContext = this.#context;
+		this.#subs.emitChange(this.snapshot());
 	}
 	#dispatch(event) {
 		if (this.state.isFinal) return;
@@ -445,7 +482,7 @@ var Actor = class {
 	}
 	#applyStateStep(event, transition) {
 		const step = transition(event, {
-			context: this.#context,
+			context: this.#contextHandle,
 			actor: this
 		});
 		if (step.emit) this.#queue.push(...step.emit);
@@ -457,7 +494,7 @@ var Actor = class {
 	}
 	#applyAnyStep(event, transition, allowTransition) {
 		const step = transition(event, {
-			context: this.#context,
+			context: this.#contextHandle,
 			actor: this
 		});
 		if (step.state && allowTransition) this.#applyTransition(event, step);
@@ -468,7 +505,7 @@ var Actor = class {
 		return false;
 	}
 	snapshot() {
-		return buildSnapshot(this.state, this.#regions);
+		return buildSnapshot(this.state, this.#regions, this.#context);
 	}
 	#pushEvent(event) {
 		this.#queue.push(event);
@@ -484,7 +521,6 @@ var Actor = class {
 		if (!resolved) return;
 		this.state = resolved.state;
 		this.#runEffects(event, resolved.payload);
-		this.#subs.emitChange(this.snapshot());
 		if (this.state.isFinal) this.#subs.emitDone();
 	}
 	#runEffects(event, statePayload) {
@@ -498,7 +534,7 @@ var Actor = class {
 			state: this.state,
 			statePayload,
 			event,
-			context: this.#context,
+			context: this.#contextHandle,
 			emit: (e) => {
 				this.#queue.push(e);
 				this.#drainInternal();
@@ -528,6 +564,7 @@ var Actor = class {
 			});
 		} finally {
 			this.#draining = false;
+			this.#emitChangeIfDirty();
 		}
 		if (budgetExceeded) console.warn(`[Actor] internal event budget (${this.#internalBudget}) exceeded — possible emit loop. Actor halting.`);
 	}
@@ -554,4 +591,4 @@ var EventRef = class {
 	}
 };
 //#endregion
-export { Actor, EventRef, RealClock, StateRef, VirtualClock, event, state };
+export { Actor, Context, EventRef, RealClock, StateRef, VirtualClock, event, state };

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { s as InternalEvent, t as AnyActor } from "./actor-internal-CfZDmHJ3.mjs";
+import { s as InternalEvent, t as AnyActor } from "./actor-internal-CBU_EDPZ.mjs";
 import { Either } from "@mantaq/utils";
 //#region src/internal-registry.d.ts
 interface ActorInternal {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
     "vite-plus": "0.2.8",
     "vitest": "4.1.10",
-    "@mantaq/pbt": "0.0.1"
+    "@mantaq/pbt": "0.0.2"
   },
   "scripts": {
     "build": "vp pack",