effect-machine 0.12.0 → 0.14.0

package/dist/machine.js

@@ -1,19 +1,19 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { Inspector } from "./inspection.js";
 import { getTag, makeDeferReply, makeReply, stubSystem } from "./internal/utils.js";
-import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
+import { ProvisionValidationError, SlotCodecError, SlotProvisionError } from "./errors.js";
+import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { Inspector } from "./inspection.js";
 import { MachineContextTag } from "./slot.js";
-import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandler, shouldPostpone } from "./internal/transition.js";
 import { createActor } from "./actor.js";
-import { Cause, Effect, Exit, Option, Scope } from "effect";
+import { Cause, Effect, Exit, Option, Random, Schema, Scope } from "effect";
 //#region src/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
-	BuiltMachine: () => BuiltMachine,
 	Machine: () => Machine,
 	deferReply: () => deferReply,
 	findTransitions: () => findTransitions,
 	make: () => make,
+	materializeMachine: () => materializeMachine,
 	replay: () => replay,
 	reply: () => reply,
 	spawn: () => spawn
@@ -28,22 +28,40 @@ const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspec
 	timestamp
 })));
 /**
-* A finalized machine ready for spawning.
+* Bind slot handlers to a machine, returning a fresh copy with handlers installed.
+* If no handlers provided and machine has no slots, returns the machine as-is.
+* Validates that all required slots are provided and no extra slots are given.
 *
-* Created by calling `.build()` on a `Machine`. This is the only type
-* accepted by `Machine.spawn` and `ActorSystem.spawn` (regular overload).
-* Testing utilities (`simulate`, `createTestHarness`, etc.) still accept `Machine`.
+* @internal — used by spawn, replay, simulate, test harness, entity-machine
 */
-var BuiltMachine = class {
-	/** @internal */
-	_inner;
-	/** @internal */
-	constructor(machine) {
-		this._inner = machine;
-	}
-	get initial() {
-		return this._inner.initial;
+const materializeMachine = (machine, handlers) => {
+	if (handlers === void 0) {
+		if (machine._slotsSchema !== void 0 && Object.keys(machine._slotsSchema.definitions).length > 0) throw new ProvisionValidationError({
+			missing: Object.keys(machine._slotsSchema.definitions),
+			extra: []
+		});
+		return machine;
 	}
+	const requiredSlots = /* @__PURE__ */ new Set();
+	if (machine._slotsSchema !== void 0) for (const name of Object.keys(machine._slotsSchema.definitions)) requiredSlots.add(name);
+	const providedSlots = new Set(Object.keys(handlers));
+	const missing = [];
+	const extra = [];
+	for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
+	for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
+	if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
+		missing,
+		extra
+	});
+	const result = new Machine(machine.initial, machine.stateSchema, machine.eventSchema, machine._slotsSchema, machine._slotValidation);
+	result._transitions = [...machine._transitions];
+	result._finalStates = new Set(machine._finalStates);
+	result._spawnEffects = [...machine._spawnEffects];
+	result._backgroundEffects = [...machine._backgroundEffects];
+	result._postponeRules = [...machine._postponeRules];
+	result._replySchemas = machine._replySchemas;
+	if (machine._slotsSchema !== void 0) for (const name of Object.keys(machine._slotsSchema.definitions)) result._slotHandlers.set(name, handlers[name]);
+	return result;
 };
 /**
 * Machine definition with fluent builder API.
@@ -54,8 +72,7 @@ var BuiltMachine = class {
 * - `R`: Effect requirements
 * - `_SD`: State schema definition (for compile-time validation)
 * - `_ED`: Event schema definition (for compile-time validation)
-* - `GD`: Guard definitions
-* - `EFD`: Effect definitions
+* - `SD`: Slot definitions
 */
 var Machine = class Machine {
 	initial;
@@ -64,11 +81,10 @@ var Machine = class Machine {
 	/** @internal */ _backgroundEffects;
 	/** @internal */ _finalStates;
 	/** @internal */ _postponeRules;
-	/** @internal */ _guardsSchema;
-	/** @internal */ _effectsSchema;
-	/** @internal */ _guardHandlers;
-	/** @internal */ _effectHandlers;
+	/** @internal */ _slotsSchema;
+	/** @internal */ _slotHandlers;
 	/** @internal */ _slots;
+	/** @internal */ _slotValidation;
 	stateSchema;
 	eventSchema;
 	/** @internal */ _replySchemas;
@@ -92,53 +108,73 @@ var Machine = class Machine {
 	get postponeRules() {
 		return this._postponeRules;
 	}
-	get guardsSchema() {
-		return this._guardsSchema;
-	}
-	get effectsSchema() {
-		return this._effectsSchema;
+	get slotsSchema() {
+		return this._slotsSchema;
 	}
 	get replySchemas() {
 		return this._replySchemas;
 	}
 	/** @internal */
-	constructor(initial, stateSchema, eventSchema, guardsSchema, effectsSchema) {
+	constructor(initial, stateSchema, eventSchema, slotsSchema, slotValidation = true) {
 		this.initial = initial;
 		this._transitions = [];
 		this._spawnEffects = [];
 		this._backgroundEffects = [];
 		this._finalStates = /* @__PURE__ */ new Set();
 		this._postponeRules = [];
-		this._guardsSchema = guardsSchema;
-		this._effectsSchema = effectsSchema;
+		this._slotsSchema = slotsSchema;
 		this._replySchemas = eventSchema?._replySchemas ?? /* @__PURE__ */ new Map();
-		this._guardHandlers = /* @__PURE__ */ new Map();
-		this._effectHandlers = /* @__PURE__ */ new Map();
+		this._slotHandlers = /* @__PURE__ */ new Map();
+		this._slotValidation = slotValidation;
 		this.stateSchema = stateSchema;
 		this.eventSchema = eventSchema;
-		this._slots = {
-			guards: this._guardsSchema !== void 0 ? this._guardsSchema._createSlots((name, params) => Effect.flatMap(Effect.serviceOption(this.Context), (maybeCtx) => {
-				if (Option.isNone(maybeCtx)) return Effect.die("MachineContext not available");
-				const ctx = maybeCtx.value;
-				const handler = this._guardHandlers.get(name);
-				if (handler === void 0) return Effect.die(new SlotProvisionError({
-					slotName: name,
-					slotType: "guard"
-				}));
-				const result = handler(params, ctx);
-				return typeof result === "boolean" ? Effect.succeed(result) : result;
-			})) : {},
-			effects: this._effectsSchema !== void 0 ? this._effectsSchema._createSlots((name, params) => Effect.flatMap(Effect.serviceOption(this.Context), (maybeCtx) => {
-				if (Option.isNone(maybeCtx)) return Effect.die("MachineContext not available");
-				const ctx = maybeCtx.value;
-				const handler = this._effectHandlers.get(name);
-				if (handler === void 0) return Effect.die(new SlotProvisionError({
-					slotName: name,
-					slotType: "effect"
-				}));
-				return handler(params, ctx);
-			})) : {}
-		};
+		const validators = slotValidation && slotsSchema !== void 0 ? new Map(Object.entries(slotsSchema.definitions).map(([name, def]) => [name, {
+			decodeInput: Schema.decodeUnknownSync(def.inputSchema),
+			decodeOutput: Schema.decodeUnknownSync(def.outputSchema)
+		}])) : void 0;
+		const resolve = (name, params) => Effect.flatMap(Effect.serviceOption(this.Context), (maybeCtx) => {
+			if (Option.isNone(maybeCtx)) return Effect.die("MachineContext not available");
+			const handler = this._slotHandlers.get(name);
+			if (handler === void 0) return Effect.die(new SlotProvisionError({
+				slotName: name,
+				slotType: "slot"
+			}));
+			const validatedParams = validators !== void 0 ? (() => {
+				try {
+					const v = validators.get(name);
+					return v !== void 0 ? v.decodeInput(params) : params;
+				} catch (e) {
+					return Effect.die(new SlotCodecError({
+						slotName: name,
+						phase: "input",
+						message: e instanceof Error ? e.message : String(e)
+					}));
+				}
+			})() : params;
+			if (Effect.isEffect(validatedParams)) return validatedParams;
+			const result = handler(validatedParams);
+			let resultEffect;
+			if (result === void 0 || result === null) resultEffect = Effect.void;
+			else if (Effect.isEffect(result)) resultEffect = result;
+			else resultEffect = Effect.succeed(result);
+			if (validators !== void 0) {
+				const v = validators.get(name);
+				if (v !== void 0) return Effect.flatMap(resultEffect, (value) => {
+					try {
+						const decoded = v.decodeOutput(value);
+						return Effect.succeed(decoded);
+					} catch (e) {
+						return Effect.die(new SlotCodecError({
+							slotName: name,
+							phase: "output",
+							message: e instanceof Error ? e.message : String(e)
+						}));
+					}
+				});
+			}
+			return resultEffect;
+		});
+		this._slots = this._slotsSchema !== void 0 ? this._slotsSchema._createSlots(resolve) : {};
 	}
 	from(stateOrStates, build) {
 		build(new TransitionScope(this, Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates]));
@@ -186,42 +222,19 @@ var Machine = class Machine {
 		invalidateIndex(this);
 		return this;
 	}
-	/**
-	* State-scoped effect that is forked on state entry and automatically cancelled on state exit.
-	* Use effect slots defined via `Slot.Effects` for the actual work.
-	*
-	* @example
-	* ```ts
-	* const MyEffects = Slot.Effects({
-	*   fetchData: { url: Schema.String },
-	* });
-	*
-	* machine
-	*   .spawn(State.Loading, ({ effects, state }) => effects.fetchData({ url: state.url }))
-	*   .build({
-	*     fetchData: ({ url }, { self }) =>
-	*       Effect.gen(function* () {
-	*         yield* Effect.addFinalizer(() => Effect.log("Leaving Loading"));
-	*         const data = yield* Http.get(url);
-	*         yield* self.send(Event.Loaded({ data }));
-	*       }),
-	*   });
-	* ```
-	*/
-	spawn(state, handler) {
-		const stateTag = getTag(state);
-		this._spawnEffects.push({
-			stateTag,
-			handler
-		});
+	spawn(stateOrStates, handler) {
+		const states = Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates];
+		for (const s of states) {
+			const stateTag = getTag(s);
+			this._spawnEffects.push({
+				stateTag,
+				handler
+			});
+		}
 		invalidateIndex(this);
 		return this;
 	}
-	/**
-	* State-scoped task that runs on entry and sends success/failure events.
-	* Interrupts do not emit failure events.
-	*/
-	task(state, run, options) {
+	task(stateOrStates, run, options) {
 		const handler = Effect.fn("effect-machine.task")(function* (ctx) {
 			yield* emitTaskInspection({
 				actorId: ctx.actorId,
@@ -237,7 +250,8 @@ var Machine = class Machine {
 					taskName: options.name,
 					phase: "success"
 				});
-				yield* ctx.self.send(options.onSuccess(exit.value, ctx));
+				const successEvent = options.onSuccess !== void 0 ? options.onSuccess(exit.value, ctx) : exit.value;
+				yield* ctx.self.send(successEvent);
 				yield* Effect.yieldNow;
 				return;
 			}
@@ -265,7 +279,7 @@ var Machine = class Machine {
 			}
 			return yield* Effect.failCause(cause).pipe(Effect.orDie);
 		});
-		return this.spawn(state, handler);
+		return this.spawn(stateOrStates, handler);
 	}
 	/**
 	* State timeout — gen_statem's `state_timeout`.
@@ -299,22 +313,14 @@ var Machine = class Machine {
 	}
 	/**
 	* Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
-	* Use effect slots defined via `Slot.Effects` for the actual work.
 	*
 	* @example
 	* ```ts
-	* const MyEffects = Slot.Effects({
-	*   heartbeat: {},
-	* });
-	*
-	* machine
-	*   .background(({ effects }) => effects.heartbeat())
-	*   .build({
-	*     heartbeat: (_, { self }) =>
-	*       Effect.forever(
-	*         Effect.sleep("30 seconds").pipe(Effect.andThen(self.send(Event.Ping)))
-	*       ),
-	*   });
+	* machine.background(({ self }) =>
+	*   Effect.forever(
+	*     Effect.sleep("30 seconds").pipe(Effect.andThen(self.send(Event.Ping))),
+	*   ),
+	* );
 	* ```
 	*/
 	background(handler) {
@@ -355,43 +361,8 @@ var Machine = class Machine {
 		this._finalStates.add(stateTag);
 		return this;
 	}
-	/**
-	* Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
-	*
-	* - Machines with slots: pass implementations as the first argument.
-	* - Machines without slots: call with no arguments.
-	*/
-	build(...args) {
-		const handlers = args[0];
-		if (handlers !== void 0) {
-			const requiredSlots = /* @__PURE__ */ new Set();
-			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) requiredSlots.add(name);
-			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) requiredSlots.add(name);
-			const providedSlots = new Set(Object.keys(handlers));
-			const missing = [];
-			const extra = [];
-			for (const name of requiredSlots) if (!providedSlots.has(name)) missing.push(name);
-			for (const name of providedSlots) if (!requiredSlots.has(name)) extra.push(name);
-			if (missing.length > 0 || extra.length > 0) throw new ProvisionValidationError({
-				missing,
-				extra
-			});
-			const result = new Machine(this.initial, this.stateSchema, this.eventSchema, this._guardsSchema, this._effectsSchema);
-			result._transitions = [...this._transitions];
-			result._finalStates = new Set(this._finalStates);
-			result._spawnEffects = [...this._spawnEffects];
-			result._backgroundEffects = [...this._backgroundEffects];
-			result._postponeRules = [...this._postponeRules];
-			result._replySchemas = this._replySchemas;
-			const anyHandlers = handlers;
-			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) result._guardHandlers.set(name, anyHandlers[name]);
-			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) result._effectHandlers.set(name, anyHandlers[name]);
-			return new BuiltMachine(result);
-		}
-		return new BuiltMachine(this);
-	}
 	static make(config) {
-		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
+		return new Machine(config.initial, config.state, config.event, config.slots, config.slotValidation ?? true);
 	}
 };
 var TransitionScope = class {
@@ -410,27 +381,42 @@ var TransitionScope = class {
 };
 const make = Machine.make;
 /**
-* Spawn an actor from a built machine.
+* Spawn an actor from a machine.
+*
+* For machines with slots, pass implementations via `{ slots: { ... } }`.
+*
+* @example
+* ```ts
+* // No slots
+* const actor = yield* Machine.spawn(machine);
 *
-* Options:
-* - `id` — custom actor ID (default: random)
-* - `hydrate` — restore from a previously-saved state snapshot.
-*   The actor starts in the hydrated state and re-runs spawn effects
-*   for that state (timers, scoped resources, etc.). Transition history
-*   is not replayed — only the current state's entry effects run.
+* // With slots
+* const actor = yield* Machine.spawn(machine, {
+*   slots: { canRetry: ({ max }) => attempts < max },
+* });
 *
-* Persistence is composed in userland by observing `actor.changes`
-* and saving snapshots to your own storage.
+* // With persistence
+* const actor = yield* Machine.spawn(machine, {
+*   persist: {
+*     load: () => storage.get("actor-state"),
+*     save: (state) => storage.set("actor-state", state),
+*   },
+* });
+* ```
 */
-const spawn = Effect.fn("effect-machine.spawn")(function* (built, idOrOptions) {
+const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions) {
 	const opts = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
-	const actor = yield* createActor(opts?.id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner, { initialState: opts?.hydrate });
+	const actor = yield* createActor(opts?.id ?? `actor-${(yield* Random.next).toString(36).slice(2)}`, materializeMachine(machine, opts?.slots), {
+		initialState: opts?.hydrate,
+		supervision: opts?.supervision,
+		persist: opts?.persist
+	});
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
 	return actor;
 });
-const replay = Effect.fn("effect-machine.replay")(function* (built, events, options) {
-	const machine = built._inner;
+const replay = Effect.fn("effect-machine.replay")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
 	let state = options?.from ?? machine.initial;
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];
@@ -476,4 +462,4 @@ const replay = Effect.fn("effect-machine.replay")(function* (built, events, opti
 const reply = makeReply;
 const deferReply = makeDeferReply;
 //#endregion
-export { BuiltMachine, Machine, deferReply, findTransitions, machine_exports, make, replay, reply, spawn };
+export { Machine, deferReply, findTransitions, machine_exports, make, materializeMachine, replay, reply, spawn };

package/dist/schema.d.ts

@@ -81,6 +81,20 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
     <R>(cases: MatchCases<D, R>): (value: VariantsUnion<D> & Brand) => R;
     <R>(value: VariantsUnion<D> & Brand, cases: MatchCases<D, R>): R;
   };
+  /**
+   * Union-level derive: copies fields from `source` into the same variant,
+   * overriding with `partial`. Preserves the specific variant subtype.
+   *
+   * Dispatches to the per-variant `derive` based on `source._tag`.
+   *
+   * @example
+   * ```ts
+   * // Instead of switching on _tag to call per-variant derive:
+   * const updated = AgentLoopState.derive(state, { queue: newQueue })
+   * // If state is StreamingState, returns StreamingState (not LoopState)
+   * ```
+   */
+  readonly derive: <S extends VariantsUnion<D> & Brand>(source: S, partial?: Partial<Omit<S, "_tag">>) => S;
   /**
    * Reply schemas per variant tag. Only populated for event schemas
    * with variants defined via `Event.reply()`.

package/dist/schema.js

@@ -67,6 +67,7 @@ const buildMachineSchema = (definition) => {
 				for (const key of fieldNames) if (key in source) result[key] = source[key];
 				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) {
 					if (RESERVED_DERIVE_KEYS.has(key)) continue;
+					if (!fieldNames.has(key)) continue;
 					result[key] = value;
 				}
 				return result;
@@ -78,7 +79,7 @@ const buildMachineSchema = (definition) => {
 		};
 	}
 	const variantArray = Object.values(variants);
-	if (variantArray.length === 0) throw new InvalidSchemaError({});
+	if (variantArray.length === 0) throw new InvalidSchemaError({ message: "Schema must have at least one variant" });
 	const unionSchema = variantArray.length === 1 ? variantArray[0] : Schema.Union(variantArray);
 	const $is = (tag) => (u) => typeof u === "object" && u !== null && "_tag" in u && u._tag === tag;
 	const $match = (valueOrCases, maybeCases) => {
@@ -111,12 +112,20 @@ const buildMachineSchema = (definition) => {
 */
 const createMachineSchema = (definition) => {
 	const { schema, variants, constructors, _definition, replySchemas, $is, $match } = buildMachineSchema(definition);
+	const derive = (source, partial) => {
+		const ctor = constructors[source._tag];
+		if (ctor === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
+		const deriveFn = ctor.derive;
+		if (deriveFn === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
+		return deriveFn(source, partial);
+	};
 	return Object.assign(Object.create(schema), {
 		variants,
 		_definition,
 		_replySchemas: replySchemas,
 		$is,
 		$match,
+		derive,
 		...constructors
 	});
 };