effect-machine 0.17.0 → 0.18.0

package/dist/inspection.js

@@ -17,10 +17,11 @@ const makeInspector = (onInspect) => ({ onInspect });
 const makeInspectorEffect = (onInspect) => ({ onInspect });
 const inspectionEffect = (inspector, event) => {
 	const result = inspector.onInspect(event);
-	return Effect.isEffect(result) ? result : Effect.void;
+	if (Effect.isEffect(result)) return result;
+	return Effect.void;
 };
-const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.catchCause(() => Effect.void)), {
-	concurrency: "unbounded",
+const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.ignoreCause), {
+	concurrency: 16,
 	discard: true
 }) });
 const inspectionSpanName = (event) => {
@@ -40,7 +41,11 @@ const inspectionTraceName = (event) => {
 		case "@machine.event": return `machine.event ${event.event._tag}`;
 		case "@machine.transition": return `machine.transition ${event.fromState._tag}->${event.toState._tag}`;
 		case "@machine.effect": return `machine.effect ${event.effectType}`;
-		case "@machine.task": return `machine.task ${event.phase}${event.taskName === void 0 ? "" : ` ${event.taskName}`}`;
+		case "@machine.task": {
+			let taskSuffix = "";
+			if (event.taskName !== void 0) taskSuffix = ` ${event.taskName}`;
+			return `machine.task ${event.phase}${taskSuffix}`;
+		}
 		case "@machine.error": return `machine.error ${event.phase}`;
 		case "@machine.stop": return `machine.stop ${event.finalState._tag}`;
 	}
@@ -71,12 +76,16 @@ const inspectionAttributes = (event) => {
 			"machine.state.current": event.state._tag,
 			"machine.effect.kind": event.effectType
 		};
-		case "@machine.task": return {
-			...shared,
-			"machine.state.current": event.state._tag,
-			"machine.task.phase": event.phase,
-			...event.taskName === void 0 ? {} : { "machine.task.name": event.taskName }
-		};
+		case "@machine.task": {
+			const taskNameAttribute = {};
+			if (event.taskName !== void 0) taskNameAttribute["machine.task.name"] = event.taskName;
+			return {
+				...shared,
+				"machine.state.current": event.state._tag,
+				"machine.task.phase": event.phase,
+				...taskNameAttribute
+			};
+		}
 		case "@machine.error": return {
 			...shared,
 			"machine.phase": event.phase,
@@ -89,19 +98,21 @@ const inspectionAttributes = (event) => {
 	}
 };
 const tracingInspector = (options) => ({ onInspect: (event) => {
-	const spanName = typeof options?.spanName === "function" ? options.spanName(event) : options?.spanName;
+	let spanName = void 0;
+	if (typeof options?.spanName === "function") spanName = options.spanName(event);
+	else spanName = options?.spanName;
 	const traceName = options?.eventName?.(event) ?? inspectionTraceName(event);
 	const attributes = {
 		...inspectionAttributes(event),
 		...options?.attributes?.(event) ?? {}
 	};
-	return Effect.gen(function* () {
+	return Effect.fn("effect-machine.inspector.trace")(function* () {
 		const currentSpan = yield* Effect.option(Effect.currentSpan);
 		if (Option.isSome(currentSpan)) currentSpan.value.event(traceName, BigInt(event.timestamp) * 1000000n, {
 			actorId: event.actorId,
 			inspectionType: event.type
 		});
-	}).pipe(Effect.withSpan(spanName ?? inspectionSpanName(event), { attributes }));
+	})().pipe(Effect.withSpan(spanName ?? inspectionSpanName(event), { attributes }));
 } });
 /**
 * Console inspector that logs events in a readable format

package/dist/internal/brands.d.ts

@@ -1,5 +1,4 @@
 import { Brand } from "effect";
-
 //#region src/internal/brands.d.ts
 type StateTypeId = "effect-machine/StateTypeId";
 type EventTypeId = "effect-machine/EventTypeId";

package/dist/internal/event-advancement.d.ts

@@ -0,0 +1,50 @@
+//#region src/internal/event-advancement.d.ts
+interface AdvancementStep<S, A> {
+  readonly state: S;
+  readonly transitioned: boolean;
+  readonly stateChanged: boolean;
+  readonly shouldStop: boolean;
+  readonly value: A;
+}
+interface PostponedStep<I, A> {
+  readonly input: I;
+  readonly value: A;
+}
+interface EventAdvancementOptions<S, I, A, R> {
+  readonly initial: S;
+  readonly isFinal: (state: S) => boolean;
+  readonly shouldPostpone: (state: S, input: I) => boolean;
+  readonly postpone: (state: S, input: I) => Effect.Effect<PostponedStep<I, A>, never, R>;
+  readonly process: (state: S, input: I, draining: boolean) => Effect.Effect<AdvancementStep<S, A>, never, R>;
+  readonly commit?: (previousState: S, input: I, step: AdvancementStep<S, A>) => Effect.Effect<void, never, R>;
+  readonly discard?: (input: I) => Effect.Effect<void, never, R>;
+}
+interface AdvancementResult<S, A> {
+  readonly state: S;
+  readonly value: A | undefined;
+  readonly stopped: boolean;
+  readonly postponed: boolean;
+}
+declare const makeEventAdvancement: <S, I, A, R>(options: EventAdvancementOptions<S, I, A, R>) => {
+  advance: (input: I) => Effect.Effect<{
+    state: S;
+    value: undefined;
+    stopped: true;
+    postponed: false;
+  } | {
+    state: S;
+    value: A;
+    stopped: false;
+    postponed: true;
+  } | {
+    state: S;
+    value: A;
+    stopped: boolean;
+    postponed: false;
+  }, never, R>;
+  close: () => Effect.Effect<void, never, R>;
+  readonly state: S;
+  readonly stopped: boolean;
+};
+//#endregion
+export { AdvancementResult, AdvancementStep, EventAdvancementOptions, PostponedStep, makeEventAdvancement };

package/dist/internal/event-advancement.js

@@ -0,0 +1,79 @@
+import { Effect } from "effect";
+//#region src/internal/event-advancement.ts
+/**
+* Event advancement policy shared by live and offline machine execution.
+*
+* Owns postponed event order, cascading drain, and terminal state handling.
+* Callers supply the effects that execute one event.
+*
+* @internal
+*/
+const makeEventAdvancement = (options) => {
+	let state = options.initial;
+	let stopped = options.isFinal(state);
+	const postponed = [];
+	const advance = (input) => Effect.gen(function* () {
+		const postponedStep = (entry) => options.postpone(state, entry);
+		if (stopped) return {
+			state,
+			value: void 0,
+			stopped: true,
+			postponed: false
+		};
+		if (options.shouldPostpone(state, input)) {
+			const result = yield* postponedStep(input);
+			postponed.push(result.input);
+			return {
+				state,
+				value: result.value,
+				stopped,
+				postponed: true
+			};
+		}
+		const previousState = state;
+		const first = yield* options.process(previousState, input, false);
+		state = first.state;
+		if (options.commit !== void 0) yield* options.commit(previousState, input, first);
+		stopped = first.shouldStop || options.isFinal(state);
+		let stateChanged = first.stateChanged;
+		while (!stopped && stateChanged && postponed.length > 0) {
+			stateChanged = false;
+			const drained = postponed.splice(0);
+			for (const entry of drained) {
+				if (options.shouldPostpone(state, entry)) {
+					postponed.push(entry);
+					continue;
+				}
+				const drainedPreviousState = state;
+				const step = yield* options.process(drainedPreviousState, entry, true);
+				state = step.state;
+				if (options.commit !== void 0) yield* options.commit(drainedPreviousState, entry, step);
+				stopped = step.shouldStop || options.isFinal(state);
+				stateChanged = stateChanged || step.stateChanged;
+				if (stopped) break;
+			}
+		}
+		return {
+			state,
+			value: first.value,
+			stopped,
+			postponed: false
+		};
+	});
+	const close = () => Effect.gen(function* () {
+		if (options.discard !== void 0) for (const input of postponed) yield* options.discard(input);
+		postponed.length = 0;
+	});
+	return {
+		advance,
+		close,
+		get state() {
+			return state;
+		},
+		get stopped() {
+			return stopped;
+		}
+	};
+};
+//#endregion
+export { makeEventAdvancement };

package/dist/internal/inspection.d.ts

@@ -1,11 +1,7 @@
-import { InspectionEvent, InspectorService } from "../inspection.js";
-import { Effect } from "effect";
-
+import { ProcessEventHooks } from "./transition.js";
+import { InspectorService } from "../inspection.js";
 //#region src/internal/inspection.d.ts
-/**
- * Emit an inspection event with timestamp from Clock.
- * @internal
- */
-declare const emitWithTimestamp: <S, E>(inspector: InspectorService<S, E> | undefined, makeEvent: (timestamp: number) => InspectionEvent<S, E>) => Effect.Effect<void, never, never>;
+/** Adapt the Inspector service to the transition kernel. */
+declare const makeInspectionHooks: <S, E>(actorId: string, inspector: InspectorService<S, E>) => ProcessEventHooks<S, E>;
 //#endregion
-export { emitWithTimestamp };
+export { makeInspectionHooks };

package/dist/internal/inspection.js

@@ -1,4 +1,4 @@
-import { Clock, Effect } from "effect";
+import { Cause, Clock, Effect } from "effect";
 //#region src/internal/inspection.ts
 /**
 * Emit an inspection event with timestamp from Clock.
@@ -7,14 +7,35 @@ import { Clock, Effect } from "effect";
 const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* (inspector, makeEvent) {
 	if (inspector === void 0) return;
 	const event = makeEvent(yield* Clock.currentTimeMillis);
-	const result = yield* Effect.sync(() => {
-		try {
-			return inspector.onInspect(event);
-		} catch {
-			return;
-		}
-	});
-	if (Effect.isEffect(result)) yield* result.pipe(Effect.catchCause(() => Effect.void));
+	const result = yield* Effect.try(() => inspector.onInspect(event)).pipe(Effect.orElseSucceed(() => void 0));
+	if (Effect.isEffect(result)) yield* result.pipe(Effect.ignoreCause);
+});
+/** Adapt the Inspector service to the transition kernel. */
+const makeInspectionHooks = (actorId, inspector) => ({
+	onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.effect",
+		actorId,
+		effectType: "spawn",
+		state,
+		timestamp
+	})),
+	onTransition: (from, to, event) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.transition",
+		actorId,
+		fromState: from,
+		toState: to,
+		event,
+		timestamp
+	})),
+	onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.error",
+		actorId,
+		phase: info.phase,
+		state: info.state,
+		event: info.event,
+		error: Cause.pretty(info.cause),
+		timestamp
+	}))
 });
 //#endregion
-export { emitWithTimestamp };
+export { emitWithTimestamp, makeInspectionHooks };

package/dist/internal/machine-definition.d.ts

@@ -0,0 +1,16 @@
+//#region src/internal/machine-definition.d.ts
+interface Transition<State, Event, R> {
+  readonly stateTag: string;
+  readonly eventTag: string;
+  readonly handler: TransitionHandler<State, Event, State, R>;
+  readonly reenter?: boolean;
+}
+interface SpawnEffect<State, Event, R> {
+  readonly stateTag: string;
+  readonly handler: StateEffectHandler<State, Event, R>;
+}
+interface BackgroundEffect<State, Event, R> {
+  readonly handler: StateEffectHandler<State, Event, R>;
+}
+//#endregion
+export { BackgroundEffect, SpawnEffect, Transition };

package/dist/internal/runtime.d.ts

@@ -1,161 +1 @@
-import { NoReplyError } from "../errors.js";
-import { MachineContextTag, SlotsDef } from "../slot.js";
-import { ActorExit } from "../supervision.js";
-import { ProcessEventHooks, ProcessEventResult } from "./transition.js";
-import { Machine } from "../machine.js";
-import { ActorSystemService } from "../actor.js";
-import { Deferred, Effect, Queue, Ref, Scope, SubscriptionRef } from "effect";
-
-//#region src/internal/runtime.d.ts
-/** @internal */
-type RuntimeQueuedEvent<E> = {
-  readonly _tag: "send";
-  readonly event: E;
-} | {
-  readonly _tag: "sendWait";
-  readonly event: E;
-  readonly done: Deferred.Deferred<void, unknown>;
-} | {
-  readonly _tag: "call";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<ProcessEventResult<{
-    readonly _tag: string;
-  }>, unknown>;
-} | {
-  readonly _tag: "ask";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<unknown, NoReplyError>;
-} | {
-  readonly _tag: "drain";
-  readonly done: Deferred.Deferred<void>;
-};
-/**
- * Resources owned by the actor cell (stable across generations).
- * When provided, createRuntime uses these instead of allocating its own.
- * @internal
- */
-interface RuntimeCellResources<S, E> {
-  readonly stateRef: SubscriptionRef.SubscriptionRef<S>;
-  readonly eventQueue: Queue.Queue<RuntimeQueuedEvent<E>>;
-  readonly stoppedRef: Ref.Ref<boolean>;
-}
-/** @internal */
-interface RuntimeHandle<S, E> {
-  /** Enqueue a fire-and-forget event */
-  readonly send: (event: E) => Effect.Effect<void>;
-  /** Enqueue event and wait for processing to complete (for RPC Send). Fails on defect. */
-  readonly sendWait: (event: E) => Effect.Effect<void, unknown>;
-  /** Enqueue an ask event, returns the reply value */
-  readonly ask: (event: E) => Effect.Effect<unknown, NoReplyError>;
-  /** Get current state */
-  readonly getState: Effect.Effect<S>;
-  /** SubscriptionRef for state observation (WatchState streaming) */
-  readonly stateRef: SubscriptionRef.SubscriptionRef<S>;
-  /** Whether the runtime has stopped (final state reached) */
-  readonly isStopped: Effect.Effect<boolean>;
-  /** Stop the runtime (interrupt event loop, clean up) */
-  readonly stop: Effect.Effect<void>;
-  /**
-   * Start the runtime — fork event loop, background effects, spawn effects.
-   * Idempotent: first caller runs initialization, subsequent callers await completion.
-   * Events sent before start() are queued and processed when start() runs.
-   */
-  readonly start: Effect.Effect<void>;
-  /** @internal — raw event queue for direct enqueue (actor.ts uses this for pendingReplies tracking) */
-  readonly _queue: Queue.Queue<RuntimeQueuedEvent<E>>;
-  /** @internal — stopped ref for direct access */
-  readonly _stoppedRef: Ref.Ref<boolean>;
-  /**
-   * Exit deferred — set exactly once with the exit reason when the runtime stops.
-   * Final state → ActorExit.Final, explicit stop → ActorExit.Stopped, defect → ActorExit.Defect.
-   */
-  readonly exitDeferred: Deferred.Deferred<ActorExit<S>>;
-  /**
-   * Actor scope — owns background fibers for this generation.
-   * Closing this scope interrupts all background fibers.
-   */
-  readonly actorScope: Scope.Closeable;
-}
-/** @internal */
-interface RuntimeLifecycleHooks<S, E> {
-  /** Before processEventCore — actor emits @machine.event inspection */
-  readonly onEvent?: (state: S, event: E) => Effect.Effect<void>;
-  /** After SubscriptionRef.set on transition — actor notifies listeners, annotates spans */
-  readonly onStateChange?: (result: ProcessEventResult<S>, event: E) => Effect.Effect<void>;
-  /** After reply settlement when transition occurred — actor publishes to transitionsPubSub */
-  readonly onProcessed?: (result: ProcessEventResult<S>, event: E) => Effect.Effect<void>;
-  /** When final state detected in event loop — actor emits @machine.stop */
-  readonly onFinal?: (state: S) => Effect.Effect<void>;
-  /** Before stop resource cleanup — actor emits @machine.stop, settles pending replies */
-  readonly onShutdown?: () => Effect.Effect<void>;
-  /** Before initial spawn effects — actor emits @machine.effect inspection */
-  readonly onInitialSpawnEffects?: (state: S) => Effect.Effect<void>;
-}
-/** @internal */
-interface RuntimeConfig<S, E> {
-  readonly actorId: string;
-  readonly hooks?: ProcessEventHooks<S, E>;
-  /**
-   * Cell-owned resources. When provided, the runtime uses the cell's stateRef,
-   * eventQueue, and stoppedRef instead of creating its own.
-   * Used by actor.ts for supervision (cell owns stable resources across generations).
-   */
-  readonly cellResources?: RuntimeCellResources<S, E>;
-  /**
-   * Custom queue factory. Default: `Queue.unbounded()`.
-   * Use `Queue.sliding(n)` or `Queue.dropping(n)` for bounded queues.
-   * Ignored when cellResources is provided.
-   */
-  readonly queueFactory?: Effect.Effect<Queue.Queue<RuntimeQueuedEvent<E>>>;
-  /** Lifecycle callbacks for actor-specific concerns */
-  readonly lifecycle?: RuntimeLifecycleHooks<S, E>;
-  /** Wrap each processQueued invocation — actor uses for span annotations */
-  readonly wrapProcess?: (state: S, event: E, inner: Effect.Effect<ProcessQueuedResult<S>>) => Effect.Effect<ProcessQueuedResult<S>>;
-  /** Called after self.spawn succeeds — actor tracks children */
-  readonly onChildSpawned?: (childId: string, child: unknown) => Effect.Effect<void>;
-  /** Skip registering stop as scope finalizer — actor manages its own lifecycle */
-  readonly skipFinalizer?: boolean;
-  /** Prefix for child actor IDs in self.spawn. Entity-machine uses `${actorId}/`. Default: no prefix. */
-  readonly childIdPrefix?: string;
-}
-/** @internal */
-interface ProcessQueuedResult<S> {
-  readonly shouldStop: boolean;
-  readonly stateChanged: boolean;
-  readonly result: ProcessEventResult<S>;
-}
-/**
- * Create a runtime for a machine. Returns a handle for sending events
- * and querying state. The runtime owns:
- * - Event loop fiber
- * - Postpone buffer
- * - Background effects (under actorScope)
- * - State scope (spawn effects)
- * - Final state detection
- * - Exit reason via exitDeferred
- *
- * Resources (stateRef, eventQueue, stoppedRef) are either cell-provided
- * or allocated fresh by the runtime.
- *
- * @internal
- */
-declare const createRuntime: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, system: ActorSystemService, config: RuntimeConfig<S, E>) => Effect.Effect<{
-  stop: Effect.Effect<void, never, never>;
-  start: Effect.Effect<void, unknown, Exclude<R, MachineContextTag> | Exclude<Exclude<R, MachineContextTag>, Scope.Scope>>;
-  send: (event: E) => Effect.Effect<void>;
-  sendWait: (event: E) => Effect.Effect<void, unknown>;
-  ask: (event: E) => Effect.Effect<unknown, NoReplyError>;
-  getState: Effect.Effect<S, never, never>;
-  stateRef: SubscriptionRef.SubscriptionRef<S>;
-  isStopped: Effect.Effect<boolean>;
-  _queue: Queue.Queue<RuntimeQueuedEvent<E>, never>;
-  _stoppedRef: Ref.Ref<boolean>;
-  exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
-  actorScope: Scope.Closeable;
-}, never, Scope.Scope>;
-//#endregion
-export { ProcessQueuedResult, RuntimeCellResources, RuntimeConfig, RuntimeHandle, RuntimeLifecycleHooks, RuntimeQueuedEvent, createRuntime };
+export {}