effect-machine 0.17.0 → 0.18.0

package/v3/dist/inspection.d.ts

@@ -1,151 +0,0 @@
-import { Context, Effect, Schema } from "effect";
-
-//#region src/inspection.d.ts
-/**
- * Resolve a type param: if it's a Schema, extract `.Type`; otherwise use as-is.
- */
-type ResolveType<T> = T extends Schema.Schema<infer A> ? A : T;
-/**
- * Event emitted when an actor is spawned
- */
-interface SpawnEvent<S> {
-  readonly type: "@machine.spawn";
-  readonly actorId: string;
-  readonly initialState: S;
-  readonly timestamp: number;
-}
-/**
- * Event emitted when an actor receives an event
- */
-interface EventReceivedEvent<S, E> {
-  readonly type: "@machine.event";
-  readonly actorId: string;
-  readonly state: S;
-  readonly event: E;
-  readonly timestamp: number;
-}
-/**
- * Event emitted when a transition occurs
- */
-interface TransitionEvent<S, E> {
-  readonly type: "@machine.transition";
-  readonly actorId: string;
-  readonly fromState: S;
-  readonly toState: S;
-  readonly event: E;
-  readonly timestamp: number;
-}
-/**
- * Event emitted when a spawn effect runs
- */
-interface EffectEvent<S> {
-  readonly type: "@machine.effect";
-  readonly actorId: string;
-  readonly effectType: "spawn";
-  readonly state: S;
-  readonly timestamp: number;
-}
-interface TaskEvent<S> {
-  readonly type: "@machine.task";
-  readonly actorId: string;
-  readonly state: S;
-  readonly taskName?: string;
-  readonly phase: "start" | "success" | "failure" | "interrupt";
-  readonly error?: string;
-  readonly timestamp: number;
-}
-/**
- * Event emitted when a transition handler or spawn effect fails with a defect
- */
-interface ErrorEvent<S, E> {
-  readonly type: "@machine.error";
-  readonly actorId: string;
-  readonly phase: "transition" | "spawn";
-  readonly state: S;
-  readonly event: E;
-  readonly error: string;
-  readonly timestamp: number;
-}
-/**
- * Event emitted when an actor stops
- */
-interface StopEvent<S> {
-  readonly type: "@machine.stop";
-  readonly actorId: string;
-  readonly finalState: S;
-  readonly timestamp: number;
-}
-/**
- * Union of all inspection events
- */
-type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
-/**
- * Convenience alias for untyped inspection events.
- * Useful for general-purpose inspectors that don't need specific state/event types.
- * State and event fields are typed as `{ readonly _tag: string }` so discriminated
- * access to `_tag` works without casting.
- */
-type AnyInspectionEvent = InspectionEvent<{
-  readonly _tag: string;
-}, {
-  readonly _tag: string;
-}>;
-/**
- * Inspector interface for observing machine behavior
- */
-type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void>;
-interface Inspector<S, E> {
-  readonly onInspect: InspectorHandler<S, E>;
-}
-/**
- * Inspector service tag - optional service for machine introspection
- * Uses `any` types to allow variance flexibility when providing the service
- */
-declare const Inspector: Context.Tag<Inspector<any, any>, Inspector<any, any>>;
-/**
- * Create an inspector from a callback function.
- *
- * Type params accept either raw tagged types or Schema constructors:
- * - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
- * - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
- * - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
- */
-declare const makeInspector: <S = {
-  readonly _tag: string;
-}, E = {
-  readonly _tag: string;
-}>(onInspect: InspectorHandler<ResolveType<S>, ResolveType<E>>) => Inspector<ResolveType<S>, ResolveType<E>>;
-declare const makeInspectorEffect: <S = {
-  readonly _tag: string;
-}, E = {
-  readonly _tag: string;
-}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void>) => Inspector<ResolveType<S>, ResolveType<E>>;
-declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<Inspector<S, E>>) => Inspector<S, E>;
-interface TracingInspectorOptions<S, E> {
-  readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
-  readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
-  readonly eventName?: (event: InspectionEvent<S, E>) => string;
-}
-declare const tracingInspector: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}>(options?: TracingInspectorOptions<S, E>) => Inspector<S, E>;
-/**
- * Console inspector that logs events in a readable format
- */
-declare const consoleInspector: () => Inspector<{
-  readonly _tag: string;
-}, {
-  readonly _tag: string;
-}>;
-/**
- * Collecting inspector that stores events in an array for testing
- */
-declare const collectingInspector: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}>(events: InspectionEvent<S, E>[]) => Inspector<S, E>;
-//#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/v3/dist/inspection.js

@@ -1,128 +0,0 @@
-import { Context, Effect, Option } from "effect";
-//#region src/inspection.ts
-/**
-* Inspector service tag - optional service for machine introspection
-* Uses `any` types to allow variance flexibility when providing the service
-*/
-const Inspector = Context.GenericTag("@effect/machine/Inspector");
-/**
-* Create an inspector from a callback function.
-*
-* Type params accept either raw tagged types or Schema constructors:
-* - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
-* - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
-* - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
-*/
-const makeInspector = (onInspect) => ({ onInspect });
-const makeInspectorEffect = (onInspect) => ({ onInspect });
-const inspectionEffect = (inspector, event) => {
-	const result = inspector.onInspect(event);
-	return Effect.isEffect(result) ? result : Effect.void;
-};
-const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.catchAllCause(() => Effect.void)), {
-	concurrency: "unbounded",
-	discard: true
-}) });
-const inspectionSpanName = (event) => {
-	switch (event.type) {
-		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
-		case "@machine.event": return `Machine.inspect ${event.event._tag}`;
-		case "@machine.transition": return `Machine.inspect ${event.fromState._tag}->${event.toState._tag}`;
-		case "@machine.effect": return `Machine.inspect ${event.effectType}`;
-		case "@machine.task": return `Machine.inspect task:${event.phase}`;
-		case "@machine.error": return `Machine.inspect ${event.phase}`;
-		case "@machine.stop": return `Machine.inspect ${event.finalState._tag}`;
-	}
-};
-const inspectionTraceName = (event) => {
-	switch (event.type) {
-		case "@machine.spawn": return `machine.spawn ${event.initialState._tag}`;
-		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.error": return `machine.error ${event.phase}`;
-		case "@machine.stop": return `machine.stop ${event.finalState._tag}`;
-	}
-};
-const inspectionAttributes = (event) => {
-	const shared = {
-		"machine.actor.id": event.actorId,
-		"machine.inspection.type": event.type
-	};
-	switch (event.type) {
-		case "@machine.spawn": return {
-			...shared,
-			"machine.state.initial": event.initialState._tag
-		};
-		case "@machine.event": return {
-			...shared,
-			"machine.state.current": event.state._tag,
-			"machine.event.tag": event.event._tag
-		};
-		case "@machine.transition": return {
-			...shared,
-			"machine.state.from": event.fromState._tag,
-			"machine.state.to": event.toState._tag,
-			"machine.event.tag": event.event._tag
-		};
-		case "@machine.effect": return {
-			...shared,
-			"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.error": return {
-			...shared,
-			"machine.phase": event.phase,
-			"machine.state.current": event.state._tag
-		};
-		case "@machine.stop": return {
-			...shared,
-			"machine.state.final": event.finalState._tag
-		};
-	}
-};
-const tracingInspector = (options) => ({ onInspect: (event) => {
-	const spanName = typeof options?.spanName === "function" ? options.spanName(event) : options?.spanName;
-	const traceName = options?.eventName?.(event) ?? inspectionTraceName(event);
-	const attributes = {
-		...inspectionAttributes(event),
-		...options?.attributes?.(event) ?? {}
-	};
-	return Effect.gen(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 }));
-} });
-/**
-* Console inspector that logs events in a readable format
-*/
-const consoleInspector = () => makeInspectorEffect((event) => {
-	const prefix = `[${event.actorId}]`;
-	switch (event.type) {
-		case "@machine.spawn": return Effect.log(`${prefix} spawned -> ${event.initialState._tag}`);
-		case "@machine.event": return Effect.log(`${prefix} received ${event.event._tag} in ${event.state._tag}`);
-		case "@machine.transition": return Effect.log(`${prefix} ${event.fromState._tag} -> ${event.toState._tag}`);
-		case "@machine.effect": return Effect.log(`${prefix} ${event.effectType} effect in ${event.state._tag}`);
-		case "@machine.task": return Effect.log(`${prefix} task ${event.phase} ${event.taskName ?? "<unnamed>"} in ${event.state._tag}`);
-		case "@machine.error": return Effect.log(`${prefix} error in ${event.phase} ${event.state._tag} - ${String(event.error)}`);
-		case "@machine.stop": return Effect.log(`${prefix} stopped in ${event.finalState._tag}`);
-	}
-});
-/**
-* Collecting inspector that stores events in an array for testing
-*/
-const collectingInspector = (events) => ({ onInspect: (event) => {
-	events.push(event);
-} });
-//#endregion
-export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/v3/dist/internal/brands.d.ts

@@ -1,50 +0,0 @@
-import { Brand } from "effect";
-
-//#region src/internal/brands.d.ts
-type StateTypeId = "effect-machine/StateTypeId";
-type EventTypeId = "effect-machine/EventTypeId";
-interface StateBrand extends Brand.Brand<StateTypeId> {}
-interface EventBrand extends Brand.Brand<EventTypeId> {}
-type BrandedState = {
-  readonly _tag: string;
-} & StateBrand;
-type BrandedEvent = {
-  readonly _tag: string;
-} & EventBrand;
-type SchemaIdTypeId = "effect-machine/SchemaIdTypeId";
-/**
- * Brand that captures the schema definition type D.
- * Two schemas with identical definition shapes will have compatible brands.
- * Different definitions = incompatible brands.
- */
-interface SchemaIdBrand<_D extends Record<string, unknown>> extends Brand.Brand<SchemaIdTypeId> {}
-/**
- * Full state brand: combines base state brand with schema-specific brand
- */
-type FullStateBrand<D extends Record<string, unknown>> = StateBrand & SchemaIdBrand<D>;
-/**
- * Full event brand: combines base event brand with schema-specific brand
- */
-type FullEventBrand<D extends Record<string, unknown>> = EventBrand & SchemaIdBrand<D>;
-/**
- * Brand that carries the reply type for an event variant.
- * Present only on events defined with Event.reply().
- */
-type ReplyTypeId = "effect-machine/ReplyTypeId";
-interface ReplyTypeBrand<R> extends Brand.Brand<ReplyTypeId> {
-  readonly _ReplyType: R;
-}
-/**
- * Extract the reply type from a branded event value.
- * Returns `never` if the event has no reply schema.
- */
-type ExtractReply<E> = E extends ReplyTypeBrand<infer R> ? R : never;
-/**
- * Value or constructor for a tagged type.
- * Accepts both plain values (empty structs) and constructor functions (non-empty structs).
- */
-type TaggedOrConstructor<T extends {
-  readonly _tag: string;
-}> = T | ((...args: never[]) => T);
-//#endregion
-export { BrandedEvent, BrandedState, EventBrand, EventTypeId, ExtractReply, FullEventBrand, FullStateBrand, ReplyTypeBrand, ReplyTypeId, SchemaIdBrand, StateBrand, StateTypeId, TaggedOrConstructor };

package/v3/dist/internal/inspection.d.ts

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

package/v3/dist/internal/inspection.js

@@ -1,20 +0,0 @@
-import { Clock, Effect } from "effect";
-//#region src/internal/inspection.ts
-/**
-* Emit an inspection event with timestamp from Clock.
-* @internal
-*/
-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.catchAllCause(() => Effect.void));
-});
-//#endregion
-export { emitWithTimestamp };

package/v3/dist/internal/runtime.d.ts

@@ -1,161 +0,0 @@
-import { NoReplyError } from "../errors.js";
-import { SlotsDef } from "../slot.js";
-import { ActorExit } from "../supervision.js";
-import { ProcessEventHooks, ProcessEventResult } from "./transition.js";
-import { Machine } from "../machine.js";
-import { ActorSystem } 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.CloseableScope;
-}
-/** @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: ActorSystem, config: RuntimeConfig<S, E>) => Effect.Effect<{
-  stop: Effect.Effect<void, never, never>;
-  start: Effect.Effect<void, unknown, unknown>;
-  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>>;
-  _stoppedRef: Ref.Ref<boolean>;
-  exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
-  actorScope: Scope.CloseableScope;
-}, never, Scope.Scope>;
-//#endregion
-export { ProcessQueuedResult, RuntimeCellResources, RuntimeConfig, RuntimeHandle, RuntimeLifecycleHooks, RuntimeQueuedEvent, createRuntime };