effect-machine 0.13.0 → 0.15.0

package/dist/slot.js

@@ -1,31 +1,29 @@
-import { ServiceMap } from "effect";
+import { Schema, ServiceMap } from "effect";
 //#region src/slot.ts
 /**
-* Slot module - schema-based, parameterized guards and effects.
+* Slot module — unified, schema-based parameterized slots.
 *
-* Guards and Effects are defined with schemas for their parameters,
-* and provided implementations receive typed parameters plus machine context.
+* Replaces the split Guards/Effects API with a single `Slot.define` + `Slot.fn`.
+* Each slot declares its parameter schema and (optional) return schema.
+* Handlers receive only params — machine context is accessed via `yield* machine.Context`.
 *
 * @example
 * ```ts
 * import { Slot } from "effect-machine"
 * import { Schema } from "effect"
 *
-* const MyGuards = Slot.Guards({
-*   canRetry: { max: Schema.Number },
-*   isValid: {},  // no params
-* })
-*
-* const MyEffects = Slot.Effects({
-*   fetchData: { url: Schema.String },
-*   notify: { message: Schema.String },
+* const MySlots = Slot.define({
+*   canRetry: Slot.fn({ max: Schema.Number }, Schema.Boolean),
+*   isValid: Slot.fn({}, Schema.Boolean),
+*   fetchData: Slot.fn({ url: Schema.String }),
+*   notify: Slot.fn({ message: Schema.String }),
 * })
 *
 * // Used in handlers:
-* .on(State.X, Event.Y, ({ guards, effects }) =>
+* .on(State.X, Event.Y, ({ slots }) =>
 *   Effect.gen(function* () {
-*     if (yield* guards.canRetry({ max: 3 })) {
-*       yield* effects.fetchData({ url: "/api" })
+*     if (yield* slots.canRetry({ max: 3 })) {
+*       yield* slots.fetchData({ url: "/api" })
 *       return State.Next
 *     }
 *     return state
@@ -36,62 +34,97 @@ import { ServiceMap } from "effect";
 * @module
 */
 /**
-* Shared Context tag for all machines.
-* Single module-level tag instead of per-machine allocation.
-* @internal
-*/
-const MachineContextTag = ServiceMap.Service("@effect-machine/Context");
-/**
-* Generic slot schema factory. Used internally by Guards() and Effects().
-* @internal
-*/
-const createSlotSchema = (tag, slotTag, definitions) => ({
-	_tag: tag,
-	definitions,
-	_createSlots: (resolve) => {
-		const slots = {};
-		for (const name of Object.keys(definitions)) {
-			const slot = (params) => resolve(name, params);
-			Object.defineProperty(slot, "_tag", {
-				value: slotTag,
-				enumerable: true
-			});
-			Object.defineProperty(slot, "name", {
-				value: name,
-				enumerable: true
-			});
-			slots[name] = slot;
-		}
-		return slots;
-	}
-});
-/**
-* Create a guards schema with parameterized guard definitions.
+* Define a single slot function with parameter schema and optional return schema.
 *
 * @example
 * ```ts
-* const MyGuards = Slot.Guards({
-*   canRetry: { max: Schema.Number },
-*   isValid: {},
-* })
+* // Guard-like: returns boolean
+* Slot.fn({ max: Schema.Number }, Schema.Boolean)
+*
+* // Effect-like: returns void (default)
+* Slot.fn({ url: Schema.String })
+*
+* // No params, returns boolean
+* Slot.fn({}, Schema.Boolean)
 * ```
 */
-const Guards = (definitions) => createSlotSchema("GuardsSchema", "GuardSlot", definitions);
+const fn = (fields, returnSchema) => {
+	return {
+		_tag: "SlotFnDef",
+		fields,
+		returnSchema,
+		inputSchema: Object.keys(fields).length > 0 ? Schema.Struct(fields) : Schema.Void,
+		outputSchema: returnSchema ?? Schema.Void
+	};
+};
 /**
-* Create an effects schema with parameterized effect definitions.
+* Shared Context tag for all machines.
+* Single module-level tag instead of per-machine allocation.
+* @internal
+*/
+const MachineContextTag = ServiceMap.Service("@effect-machine/Context");
+/**
+* Define a set of slots with parameter and return schemas.
 *
 * @example
 * ```ts
-* const MyEffects = Slot.Effects({
-*   fetchData: { url: Schema.String },
-*   notify: { message: Schema.String },
+* const MySlots = Slot.define({
+*   canRetry: Slot.fn({ max: Schema.Number }, Schema.Boolean),
+*   fetchData: Slot.fn({ url: Schema.String }),
+*   notify: Slot.fn({ message: Schema.String }),
 * })
 * ```
 */
-const Effects = (definitions) => createSlotSchema("EffectsSchema", "EffectSlot", definitions);
+const define = (definitions) => {
+	const names = Object.keys(definitions);
+	const requestSchemas = [];
+	const resultSchemas = [];
+	const invocationSchemas = [];
+	for (const name of names) {
+		const def = definitions[name];
+		if (def === void 0) continue;
+		requestSchemas.push(Schema.TaggedStruct("SlotRequest", {
+			name: Schema.Literal(name),
+			params: def.inputSchema
+		}));
+		resultSchemas.push(Schema.TaggedStruct("SlotResult", {
+			name: Schema.Literal(name),
+			result: def.outputSchema
+		}));
+		invocationSchemas.push(Schema.TaggedStruct("SlotInvocation", {
+			name: Schema.Literal(name),
+			params: def.inputSchema,
+			result: def.outputSchema
+		}));
+	}
+	const buildUnion = (schemas) => schemas.length === 0 ? Schema.Never : Schema.Union(schemas);
+	return {
+		_tag: "SlotsSchema",
+		definitions,
+		requestSchema: buildUnion(requestSchemas),
+		resultSchema: buildUnion(resultSchemas),
+		invocationSchema: buildUnion(invocationSchemas),
+		_createSlots: (resolve) => {
+			const slots = {};
+			for (const name of names) {
+				const slot = (params) => resolve(name, params);
+				Object.defineProperty(slot, "_tag", {
+					value: "Slot",
+					enumerable: true
+				});
+				Object.defineProperty(slot, "name", {
+					value: name,
+					enumerable: true
+				});
+				slots[name] = slot;
+			}
+			return slots;
+		}
+	};
+};
 const Slot = {
-	Guards,
-	Effects
+	fn,
+	define
 };
 //#endregion
-export { Effects, Guards, MachineContextTag, Slot };
+export { MachineContextTag, Slot, define, fn };

package/dist/testing.d.ts

@@ -1,10 +1,10 @@
 import { AssertionError } from "./errors.js";
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { MachineContext, ProvideSlots, SlotsDef } from "./slot.js";
 import { Machine, MachineRef } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 
 //#region src/testing.d.ts
-type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD>;
+type MachineInput<S, E, R, SD extends SlotsDef = Record<string, never>> = Machine<S, E, R, any, any, SD>;
 /**
  * Result of simulating events through a machine
  */
@@ -15,7 +15,7 @@ interface SimulationResult<S> {
 /**
  * Simulate a sequence of events through a machine without running an actor.
  * Useful for testing state transitions in isolation.
- * Does not run onEnter/spawn/background effects, but does run guard/effect slots
+ * Does not run onEnter/spawn/background effects, but does run slots
  * within transition handlers.
  *
  * @example
@@ -36,8 +36,8 @@ declare const simulate: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], options?: {
-  slots?: Record<string, any>;
+}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], options?: {
+  slots?: ProvideSlots<SD, any>;
 } | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
@@ -49,8 +49,8 @@ declare const assertReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string, options?: {
-  slots?: Record<string, any>;
+}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], expectedTag: string, options?: {
+  slots?: ProvideSlots<SD, any>;
 } | undefined) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine follows a specific path of state tags
@@ -68,8 +68,8 @@ declare const assertPath: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[], options?: {
-  slots?: Record<string, any>;
+}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], expectedPath: readonly string[], options?: {
+  slots?: ProvideSlots<SD, any>;
 } | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
@@ -91,8 +91,8 @@ declare const assertNeverReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string, options?: {
-  slots?: Record<string, any>;
+}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], forbiddenTag: string, options?: {
+  slots?: ProvideSlots<SD, any>;
 } | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
@@ -108,18 +108,18 @@ interface TestHarness<S, E, R> {
 /**
  * Options for creating a test harness
  */
-interface TestHarnessOptions<S, E> {
+interface TestHarnessOptions<S, E, SD extends SlotsDef = Record<string, never>> {
   /**
    * Called after each transition with the previous state, event, and new state.
    * Useful for logging or spying on transitions.
    */
   readonly onTransition?: (from: S, event: E, to: S) => void;
-  /** Slot handler implementations for machines with guards/effects. */
-  readonly slots?: Record<string, any>;
+  /** Slot handler implementations. */
+  readonly slots?: ProvideSlots<SD, any>;
 }
 /**
  * Create a test harness for step-by-step testing.
- * Does not run onEnter/spawn/background effects, but does run guard/effect slots
+ * Does not run onEnter/spawn/background effects, but does run slots
  * within transition handlers.
  *
  * @example Basic usage
@@ -142,7 +142,7 @@ declare const createTestHarness: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, options?: TestHarnessOptions<S, E> | undefined) => Effect.Effect<{
+}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, options?: TestHarnessOptions<S, E, SD> | undefined) => Effect.Effect<{
   state: SubscriptionRef.SubscriptionRef<S>;
   send: (event: E) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
   getState: Effect.Effect<S, never, never>;

package/dist/testing.js

@@ -1,6 +1,6 @@
 import { stubSystem } from "./internal/utils.js";
-import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { AssertionError } from "./errors.js";
+import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { materializeMachine } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.ts
@@ -16,7 +16,7 @@ const makeDummySelf = (label) => {
 /**
 * Simulate a sequence of events through a machine without running an actor.
 * Useful for testing state transitions in isolation.
-* Does not run onEnter/spawn/background effects, but does run guard/effect slots
+* Does not run onEnter/spawn/background effects, but does run slots
 * within transition handlers.
 *
 * @example
@@ -122,7 +122,7 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 });
 /**
 * Create a test harness for step-by-step testing.
-* Does not run onEnter/spawn/background effects, but does run guard/effect slots
+* Does not run onEnter/spawn/background effects, but does run slots
 * within transition handlers.
 *
 * @example Basic usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -56,7 +56,7 @@
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.42"
+    "effect": "4.0.0-beta.43"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
@@ -81,6 +81,6 @@
     }
   },
   "overrides": {
-    "effect": "4.0.0-beta.42"
+    "effect": "4.0.0-beta.43"
   }
 }

package/v3/dist/actor.d.ts

@@ -1,9 +1,9 @@
-import { ActorExit, Supervision } from "./supervision.js";
 import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { EffectsDef, GuardsDef } from "./slot.js";
+import { ProvideSlots, SlotsDef } from "./slot.js";
+import { ActorExit, Supervision } from "./supervision.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
-import { Machine } from "./machine.js";
+import { Lifecycle, Machine } from "./machine.js";
 import { RuntimeQueuedEvent } from "./internal/runtime.js";
 import { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
 
@@ -54,6 +54,12 @@ interface ActorRef<State extends {
   readonly state: SubscriptionRef.SubscriptionRef<State>;
   /** Stop the actor gracefully. */
   readonly stop: Effect.Effect<void>;
+  /**
+   * Start the actor — fork event loop, background effects, spawn effects.
+   * Called automatically by `system.spawn`. For `Machine.spawn`, the caller
+   * must call `start` explicitly. Events sent before start() are queued.
+   */
+  readonly start: Effect.Effect<void>;
   /** Get current state snapshot. */
   readonly snapshot: Effect.Effect<State>;
   /** Check if current state matches tag. */
@@ -96,7 +102,7 @@ interface ActorRef<State extends {
   readonly awaitExit: Effect.Effect<ActorExit<State>>;
   /**
    * Watch another actor. Returns an Effect that resolves with the exit reason
-   * when the watched actor terminally stops. Ignores restarts.
+   * when the watched actor terminally stops. Ignores restarts (Step 3).
    * Built on the other actor's exitDeferred — authoritative, not system events.
    */
   readonly watch: (other: {
@@ -148,14 +154,20 @@ type SystemEventListener = (event: SystemEvent) => void;
 interface ActorSystem {
   /**
    * Spawn a new actor with the given machine.
+   *
+   * @example
+   * ```ts
+   * const actor = yield* system.spawn("my-actor", machine);
+   * ```
    */
   readonly spawn: <S extends {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R>(id: string, machine: Machine<S, E, R, any, any, any, any>, options?: {
-    slots?: Record<string, any>;
-    supervision?: Supervision.Policy;
+  }, R, SD extends SlotsDef = Record<string, never>>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
+    readonly supervision?: Supervision.Policy;
+    readonly slots?: ProvideSlots<SD, any>;
+    readonly lifecycle?: Lifecycle<S, E>;
   }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
@@ -198,18 +210,19 @@ declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, start: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine.
- * Uses the shared runtime kernel with lifecycle hooks for actor-specific concerns.
+ * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
  */
 declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: {
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
   initialState?: S;
-  supervision?: Supervision.Policy; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  supervision?: Supervision.Policy;
+  lifecycle?: Lifecycle<S, E>; /** @internal Called by system after each restart — emits ActorRestarted system event */
   onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
 } | undefined) => Effect.Effect<ActorRef<S, E>, never, never>;
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
@@ -222,6 +235,6 @@ declare const makeSystem: () => Effect.Effect<ActorSystem, never, Scope.Scope>;
 /**
  * Default ActorSystem layer
  */
-declare const Default: Layer.Layer<ActorSystem, never, Scope.Scope>;
+declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
 export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };