@systemfsoftware/xstate-effect 0.0.0-stage → 0.1.0-beta.8

package/dist/state-CNrCEIpU.mjs

@@ -0,0 +1,607 @@
+import { Cause, Clock, Context, Data, Duration, Effect, Exit, Fiber, Queue, Scope } from "effect";
+import { dual } from "effect/Function";
+import { deliverEvent, isMachineSnapshot, stopActor, terminateActor } from "@systemfsoftware/xstate";
+import { createDurable } from "@systemfsoftware/xstate/durable";
+// src/errors.ts
+/**
+* The failure an Effect-backed actor reports when its Effect was interrupted
+* by something other than the actor being stopped, such as `Effect.interrupt`,
+* losing an `Effect.race`, or an `Effect.timeout` that interrupts.
+*/
+var EffectInterruptedError = class extends Data.TaggedError("EffectInterruptedError") {
+	get message() {
+		return "Effect was interrupted before the actor completed";
+	}
+};
+/**
+* Reported by `waitFor` when the actor stops or errors before a snapshot
+* matches, and by `join` when the actor stops without output. `join` reports
+* an errored actor's own `snapshot.error` instead.
+*/
+var ActorStoppedError = class extends Data.TaggedError("ActorStoppedError") {
+	get message() {
+		return `Actor "${this.actorId}" ${this.snapshot.status === "error" ? "errored" : "stopped"} before completing`;
+	}
+};
+var ActorFailedError = class extends Data.TaggedError("@systemfsoftware/xstate-effect/errors/ActorFailedError") {
+	get message() {
+		return "The actor failed";
+	}
+};
+/**
+* Reported by the `send` atom of `createActorAtoms` when an event is sent
+* before the actor's runtime has finished building.
+*/
+var NotReadyError = class extends Data.TaggedError("NotReadyError") {
+	get message() {
+		return "The actor is not ready yet";
+	}
+};
+// src/actorScope.ts
+const ActorScopeService = Context.Service()("@systemfsoftware/xstate-effect/actorScope");
+/** The owning Effect actor's scope, supplied by `createEffectActor`. */
+var ActorScope = class extends ActorScopeService {};
+/**
+* Acquires resources in the owning actor's scope. Their finalizers run when
+* that actor stops, even if the invoking task finishes or is cancelled first.
+*/
+function withActorScope(effect) {
+	return ActorScope.use((scope) => Scope.provide(effect, scope));
+}
+// src/reportUnhandledError.ts
+const reportUnhandledError = (error) => {
+	Effect.runCallback(Effect.sleep(Duration.millis(1)), { onExit: () => {
+		throw error;
+	} });
+};
+// src/effectActor.ts
+const actionFailure = Symbol.for("@xstate/effect/actionFailure");
+function isActionFailure(value) {
+	return typeof value === "object" && value !== null && actionFailure in value;
+}
+const symbolObservable = (() => typeof Symbol === "function" && Symbol.observable || "@@observable")();
+/**
+* Calls a listener and reports an exception it throws without letting it
+* escape into the interpreter, matching core's `safeCall`.
+*/
+const safeCall = dual(2, (fn, arg) => {
+	try {
+		fn?.(arg);
+	} catch (err) {
+		reportUnhandledError(err);
+	}
+});
+function toObserver(nextHandler, errorHandler, completionHandler) {
+	if (typeof nextHandler === "object") return nextHandler;
+	return {
+		next: nextHandler,
+		error: errorHandler,
+		complete: completionHandler
+	};
+}
+/**
+* The handle `createEffectActor` returns. It implements XState's `ActorRef`
+* contract (`send`, `getSnapshot`, `subscribe`, `on`), so it works with
+* `useSelector`, this package's actor functions and the inspection APIs, while
+* the actor itself is driven by an Effect fiber over pure transitions.
+*/
+var EffectActor = class {
+	logic;
+	_mailbox;
+	_stopExecution;
+	_inspectors;
+	id;
+	address;
+	sessionId;
+	/** The actor system that hosts this actor and its children. */
+	system;
+	/** @internal */
+	_root;
+	_snapshot;
+	_observers = /* @__PURE__ */ new Set();
+	_listeners = /* @__PURE__ */ new Map();
+	_settled = false;
+	constructor(logic, root, snapshot, _mailbox, _stopExecution, _inspectors) {
+		this.logic = logic;
+		this._mailbox = _mailbox;
+		this._stopExecution = _stopExecution;
+		this._inspectors = _inspectors;
+		this._root = root;
+		this.id = root.id;
+		this.address = root.address;
+		this.sessionId = root.sessionId;
+		this.system = root.system;
+		this._snapshot = snapshot;
+	}
+	getSnapshot() {
+		return this._snapshot;
+	}
+	getPersistedSnapshot() {
+		return this.logic.getPersistedSnapshot(this._snapshot);
+	}
+	/** Sends an event; the actor processes it on its own fiber. */
+	send(event) {
+		if (this._settled) {
+			this.system.deadLetter(void 0, this._root, event, "stopped");
+			return;
+		}
+		Queue.offerUnsafe(this._mailbox, event);
+	}
+	/** Stops the actor, its children and every Effect it hosts. */
+	stop() {
+		this._stopExecution();
+		return this;
+	}
+	subscribe(nextListenerOrObserver, errorListener, completeListener) {
+		const observer = toObserver(nextListenerOrObserver, errorListener, completeListener);
+		if (this._settled) {
+			const snapshot = this._snapshot;
+			if (snapshot.status === "error") safeCall(observer.error, snapshot.error);
+			else safeCall(observer.complete, void 0);
+			return { unsubscribe: () => {} };
+		}
+		this._observers.add(observer);
+		return { unsubscribe: () => {
+			this._observers.delete(observer);
+		} };
+	}
+	on(type, handler) {
+		let listeners = this._listeners.get(type);
+		if (listeners === void 0) {
+			listeners = /* @__PURE__ */ new Set();
+			this._listeners.set(type, listeners);
+		}
+		const listener = handler;
+		listeners.add(listener);
+		return { unsubscribe: () => {
+			listeners.delete(listener);
+		} };
+	}
+	/** @internal Delivers an emitted event to `on` listeners. */
+	_emit(event) {
+		const listeners = [...this._listeners.get(event.type) ?? [], ...this._listeners.get("*") ?? []];
+		for (const listener of listeners) safeCall(listener, event);
+	}
+	/**
+	* Observes the inspection events of this actor and its children: every
+	* actor creation and transition of the execution.
+	*/
+	inspect(observer) {
+		const handler = typeof observer === "function" ? observer : (event) => observer.next?.(event);
+		this._inspectors.add(handler);
+		return { unsubscribe: () => {
+			this._inspectors.delete(handler);
+		} };
+	}
+	[symbolObservable]() {
+		return this;
+	}
+	toJSON() {
+		return {
+			xstate$$type: 1,
+			id: this.id
+		};
+	}
+	/** @internal Publishes a snapshot produced by the execution loop. */
+	_publish(snapshot) {
+		this._snapshot = snapshot;
+		if (snapshot.status === "active") {
+			for (const observer of this._observers) safeCall(observer.next, snapshot);
+			return;
+		}
+		this._settle(snapshot);
+	}
+	/** @internal Marks the actor stopped and notifies observers. */
+	_settle(snapshot) {
+		if (this._settled) return;
+		this._snapshot = snapshot;
+		this._settled = true;
+		const observers = [...this._observers];
+		this._observers.clear();
+		const status = snapshot.status;
+		if (status === "done") for (const observer of observers) safeCall(observer.next, snapshot);
+		for (const observer of observers) if (status === "error") safeCall(observer.error, snapshot.error);
+		else safeCall(observer.complete, void 0);
+	}
+	/** @internal */
+	get _isSettled() {
+		return this._settled;
+	}
+};
+// src/internal.ts
+const effectHosts = /* @__PURE__ */ new WeakMap();
+let ambientHost;
+/**
+* Runs `fn` with `host` as the ambient host, so Effects started synchronously
+* inside it (declared actions executed by an execution loop) resolve their
+* host without an identity binding.
+*/
+const withEffectHost = dual(2, (host, fn) => {
+	const previous = ambientHost;
+	ambientHost = host;
+	try {
+		return fn();
+	} finally {
+		ambientHost = previous;
+	}
+});
+const createEffectHost = dual(2, (context, scope) => ({
+	context,
+	scope,
+	interruptors: /* @__PURE__ */ new Map(),
+	subscriptions: /* @__PURE__ */ new Map(),
+	fibers: /* @__PURE__ */ new Set()
+}));
+const bindEffectHost = dual(2, (target, host) => {
+	effectHosts.set(target, host);
+});
+function findEffectHost(actor) {
+	let current = actor;
+	while (current !== void 0) {
+		const host = effectHosts.get(current);
+		if (host !== void 0) return host;
+		current = current._parent;
+	}
+	return ambientHost;
+}
+/**
+* Rejects Effect logic that a machine spawned inline. Only declared actors
+* (`setup({ actors })`) and `invoke` sources are visible to
+* `RequirementsFrom`, so anything else would infer `R = never` and fail
+* later with a missing service.
+*
+* A spawned declared actor carries its registered key as `src`; an invoked
+* child carries the id of the `invoke` entry that created it.
+*/
+function assertDeclaredLogic(actor) {
+	const self = actor;
+	const parent = self._parent;
+	const machine = parent?.logic;
+	if (machine?.sources === void 0 || machine.idMap === void 0 || typeof self.src === "string") return;
+	if (Object.values(machine.sources.actors ?? {}).includes(self.logic)) return;
+	for (const stateNode of machine.idMap.values()) for (const definition of stateNode.invoke ?? []) if (definition.id === self.id) return;
+	throw new Error(`Effect logic spawned by "${parent.id}" must be declared in setup({ actors }). Spawn a declared actor instead, for example enq.spawn(args.actors.name).`);
+}
+function requireEffectHost(actor) {
+	assertDeclaredLogic(actor);
+	const host = findEffectHost(actor);
+	if (host === void 0) throw new Error("Effect-backed actor logic must be created with createEffectActor().");
+	return host;
+}
+function untrackEffect(actor, host, interrupt) {
+	const interruptors = host.interruptors.get(actor);
+	if (interruptors === void 0) return;
+	interruptors.delete(interrupt);
+	if (interruptors.size === 0) {
+		host.interruptors.delete(actor);
+		host.subscriptions.get(actor)?.unsubscribe();
+		host.subscriptions.delete(actor);
+	}
+}
+function cleanupActorEffects(actor, host) {
+	const interruptors = host.interruptors.get(actor);
+	if (interruptors !== void 0) {
+		host.interruptors.delete(actor);
+		for (const interrupt of interruptors) interrupt();
+	}
+	host.subscriptions.get(actor)?.unsubscribe();
+	host.subscriptions.delete(actor);
+}
+function trackEffect(actor, host, interrupt) {
+	let interruptors = host.interruptors.get(actor);
+	if (interruptors === void 0) {
+		interruptors = /* @__PURE__ */ new Set();
+		host.interruptors.set(actor, interruptors);
+		host.subscriptions.set(actor, actor.subscribe({
+			passive: true,
+			error: () => cleanupActorEffects(actor, host),
+			complete: () => cleanupActorEffects(actor, host)
+		}));
+	}
+	interruptors.add(interrupt);
+}
+/**
+* Runs an Effect in the actor's host context. The Effect is interrupted when
+* the actor stops or when the returned function is called; `onExit` is not
+* called after that.
+*
+* The fiber belongs to the host scope, so closing the owning actor also
+* waits for asynchronous invocation finalizers.
+*/
+const startHostedEffect = dual(4, (actor, effect, spanName, onExit) => {
+	const host = requireEffectHost(actor);
+	let active = true;
+	const traced = Effect.withSpan(spanName, { attributes: {
+		"xstate.actor.id": actor.id,
+		"xstate.actor.address": actor.address
+	} }, { captureStackTrace: false })(effect);
+	const cancel = () => {
+		if (!active) return;
+		active = false;
+		untrackEffect(actor, host, cancel);
+		interrupt();
+	};
+	const fiber = Fiber.runIn(Effect.runForkWith(host.context)(traced), host.scope);
+	const interrupt = () => fiber.interruptUnsafe();
+	host.fibers.add(fiber);
+	fiber.addObserver((exit) => {
+		host.fibers.delete(fiber);
+		if (!active) return;
+		active = false;
+		untrackEffect(actor, host, cancel);
+		onExit(exit);
+	});
+	if (active) trackEffect(actor, host, cancel);
+	return cancel;
+});
+/**
+* Runs an Effect in the actor's host context and settles when it exits.
+* Interruption settles without error; failures and defects reject with the
+* squashed cause so the actor's error handling can observe them.
+*/
+const runHostedEffect = dual(3, (actor, effect, spanName) => Effect.runPromise(Effect.callback((resume) => {
+	startHostedEffect(actor, effect, spanName, (exit) => {
+		if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) resume(Effect.void);
+		else resume(Effect.failCause(exit.cause));
+	});
+})));
+/**
+* Finishes hosted task cleanup before closing the owning actor's resources.
+* `createEffectActor`'s release awaits this fiber before its parent scope closes.
+*/
+function closeEffectHost(host) {
+	if (host.closing !== void 0) return;
+	for (const [actor, interruptors] of host.interruptors) {
+		host.interruptors.delete(actor);
+		for (const interrupt of interruptors) interrupt();
+		host.subscriptions.get(actor)?.unsubscribe();
+		host.subscriptions.delete(actor);
+	}
+	host.closing = Effect.runForkWith(host.context)(Effect.forEach([...host.fibers], (fiber) => Fiber.interrupt(fiber), {
+		concurrency: "unbounded",
+		discard: true
+	}).pipe(Effect.andThen(Scope.close(host.scope, Exit.void))));
+}
+/**
+* Delivers a stream item to the parent as an event. This runs outside a
+* transition, so it uses the system relay like core's observable logic does.
+*/
+const relayToParent = dual(2, (actor, event) => {
+	const actorWithParent = actor;
+	if (actorWithParent._parent !== void 0) actor.system._relay(actorWithParent, actorWithParent._parent, event);
+});
+// src/createEffectActor.ts
+const XSTATE_TIMER = "xstate.timer";
+const XSTATE_INIT = "@xstate.init";
+/**
+* Creates and starts an actor as an Effect interpreter over pure transitions.
+*
+* Each step is `transition(snapshot, event)`, a pure function that returns
+* the next snapshot and the actions to run. An Effect fiber owns the loop:
+* the mailbox is a `Queue`, timers are `Effect.sleep` fibers on the Effect
+* `Clock`, and declared Effect actions run as forked Effects in the actor's
+* `Scope` with the services captured here. Child actors are started as live
+* XState actors whose Effects run in the same host.
+*
+* The actor is a scoped resource: it stops, and every Effect it hosts is
+* interrupted, when the enclosing `Scope` closes. The returned Effect never
+* fails; the actor's own outcome is its snapshot status, read with `join`.
+*/
+function createEffectActor(logic, ...[options]) {
+	return Effect.acquireRelease(Effect.gen(function* () {
+		const parentScope = yield* Effect.scope;
+		const actorScope = yield* Scope.fork(parentScope);
+		const baseContext = yield* Effect.context();
+		const context = Context.add(Context.add(baseContext, Scope.Scope, actorScope), ActorScope, actorScope);
+		const host = createEffectHost(context, actorScope);
+		const runFork = Effect.runForkWith(context);
+		const runPromise = Effect.runPromiseWith(context);
+		const mailbox = yield* Queue.unbounded();
+		const timers = /* @__PURE__ */ new Map();
+		let stopped = false;
+		const isRoot = (candidate) => candidate.address === durable.rootAddress;
+		const offer = (item) => {
+			if (!stopped) Queue.offerUnsafe(mailbox, item);
+		};
+		const timerKey = (source, id) => `${source.sessionId}:${id}`;
+		const inspectors = /* @__PURE__ */ new Set();
+		let rootAnnounced = false;
+		const clock = Context.get(context, Clock.Clock);
+		const durable = createDurable(logic, {
+			now: () => clock.currentTimeMillisUnsafe(),
+			executeAction: (action, _metadata, runtime) => {
+				try {
+					const result = withEffectHost(host, () => action.exec(runtime));
+					if (result !== void 0 && typeof result.then === "function") Promise.resolve(result).catch((error) => {
+						offer({
+							[actionFailure]: true,
+							error
+						});
+					});
+				} catch (error) {
+					offer({
+						[actionFailure]: true,
+						error
+					});
+				}
+			},
+			spawnActor: (_source, child) => {
+				bindEffectHost(child, host);
+			},
+			startActor: (child) => {
+				child.start();
+			},
+			stopActor: (child) => {
+				if (!isRoot(child)) stopActor(child);
+			},
+			terminateActor: (child, termination) => {
+				if (!isRoot(child)) terminateActor(child, termination);
+			},
+			sendEvent: (source, target, event) => {
+				if (isRoot(target)) {
+					offer(event);
+					return;
+				}
+				deliverEvent(source, target, event);
+			},
+			emitEvent: (source, event) => {
+				if (isRoot(source)) {
+					actor._emit(event);
+					return;
+				}
+				source._emit(event);
+			},
+			scheduleTimer: (source, id, delay) => {
+				const key = timerKey(source, id);
+				timers.get(key)?.interruptUnsafe();
+				const fiber = Fiber.runIn(runFork(Effect.andThen(Effect.sleep(Duration.millis(delay)), Effect.sync(() => {
+					timers.delete(key);
+					const timerEvent = {
+						type: XSTATE_TIMER,
+						id
+					};
+					if (isRoot(source)) offer(timerEvent);
+					else deliverEvent(source, source, timerEvent);
+				}))), actorScope);
+				timers.set(key, fiber);
+			},
+			cancelTimer: (source, id) => {
+				const key = timerKey(source, id);
+				timers.get(key)?.interruptUnsafe();
+				timers.delete(key);
+			},
+			cancelAllTimers: (source) => {
+				for (const [key, fiber] of timers) if (key.startsWith(`${source.sessionId}:`)) {
+					fiber.interruptUnsafe();
+					timers.delete(key);
+				}
+			},
+			waitForEvent: () => runPromise(Queue.take(mailbox))
+		}, { inspect: (event) => {
+			if (event.type === "@xstate.actor" && event.actorRef.address === durable.rootAddress) {
+				if (rootAnnounced) return;
+				rootAnnounced = true;
+			}
+			for (const inspector of inspectors) safeCall(inspector, event);
+		} });
+		const errorSnapshot = (snapshot, error) => ({
+			...snapshot,
+			status: "error",
+			error
+		});
+		const stopChildren = (snapshot) => {
+			const children = snapshot.children;
+			for (const child of Object.values(children ?? {})) if (child !== void 0 && !isRoot(child)) stopActor(child);
+		};
+		const stop = () => {
+			if (stopped) return;
+			stopped = true;
+			for (const fiber of timers.values()) fiber.interruptUnsafe();
+			timers.clear();
+			const current = actor.getSnapshot();
+			if (current) stopChildren(current);
+			runFork(Queue.shutdown(mailbox));
+			if (!actor._isSettled) actor._settle({
+				...actor.getSnapshot(),
+				status: "stopped"
+			});
+			closeEffectHost(host);
+		};
+		let [snapshot, effects] = options?.snapshot !== void 0 ? durable.restore(options.snapshot) : durable.initialTransition(options?.input);
+		const initial = snapshot;
+		if (options?.snapshot !== void 0 && !isMachineSnapshot(initial) && initial.status === "active") {
+			const [started, startEffects] = durable.transition(snapshot, {
+				type: XSTATE_INIT,
+				input: "input" in initial ? initial.input : void 0
+			});
+			snapshot = started;
+			effects = [...effects, ...startEffects];
+		}
+		const root = durable.getActorRef(snapshot);
+		bindEffectHost(root, host);
+		rootAnnounced = true;
+		const actor = new EffectActor(logic, root, snapshot, mailbox, stop, inspectors);
+		bindEffectHost(actor, host);
+		const executeEffects = (batch) => Effect.promise(() => durable.executeEffects(batch).then(() => void 0, (error) => {
+			offer({
+				[actionFailure]: true,
+				error
+			});
+		}));
+		const loop = Effect.gen(function* () {
+			yield* executeEffects(effects);
+			while (snapshot.status === "active" && !stopped) {
+				const item = yield* Effect.promise(() => durable.waitForEvent().then((event) => event, () => void 0));
+				if (item === void 0 || stopped) break;
+				let event;
+				if (isActionFailure(item)) {
+					const errorEvent = logic.getExecutionErrorEvent?.(snapshot, item.error);
+					if (errorEvent === void 0) {
+						snapshot = errorSnapshot(snapshot, item.error);
+						break;
+					}
+					event = errorEvent;
+				} else event = item;
+				const transitioned = yield* Effect.exit(Effect.sync(() => durable.transition(snapshot, event)));
+				if (Exit.isFailure(transitioned)) {
+					snapshot = errorSnapshot(snapshot, Cause.squash(transitioned.cause));
+					break;
+				}
+				[snapshot, effects] = transitioned.value;
+				actor._publish(snapshot);
+				yield* executeEffects(effects);
+			}
+			if (!stopped) {
+				actor._publish(snapshot);
+				if (snapshot.status !== "active") {
+					stopChildren(snapshot);
+					closeEffectHost(host);
+				}
+			}
+		});
+		yield* Effect.forkIn(loop, actorScope);
+		return {
+			actor,
+			host
+		};
+	}), ({ actor, host }) => Effect.gen(function* () {
+		actor.stop();
+		if (host.closing !== void 0) yield* Fiber.join(host.closing);
+		else yield* Scope.close(host.scope, Exit.void);
+	})).pipe(Effect.map(({ actor }) => actor));
+}
+// src/state.ts
+/** The tag of the machine itself, used when the root state is parallel. */
+const MACHINE_TAG = "(machine)";
+/** Computes the dotted path tag of a state value. */
+function stateTag(value, prefix = "") {
+	if (typeof value === "string") return prefix !== "" ? `${prefix}.${value}` : value;
+	const keys = Object.keys(value);
+	if (keys.length !== 1) return prefix !== "" ? prefix : MACHINE_TAG;
+	const key = keys[0];
+	return stateTag(value[key], prefix !== "" ? `${prefix}.${key}` : key);
+}
+/**
+* Views a machine snapshot as a tagged union member for `Match.tag`,
+* `Match.tags` or a `switch` on `_tag`.
+*
+* @example
+*
+* ```ts
+* const view = Match.type<TaggedStateFrom<typeof snapshot>>().pipe(
+*   Match.tag('loading', ({ context }) => `Loading ${context.id}`),
+*   Match.tag('done', () => 'Done'),
+*   Match.exhaustive
+* );
+* view(taggedState(snapshot));
+* ```
+*/
+function taggedState(snapshot) {
+	return {
+		_tag: stateTag(snapshot.value),
+		value: snapshot.value,
+		context: snapshot.context,
+		snapshot
+	};
+}
+export { startHostedEffect as a, withActorScope as c, EffectInterruptedError as d, NotReadyError as f, runHostedEffect as i, ActorFailedError as l, createEffectActor as n, EffectActor as o, relayToParent as r, ActorScope as s, taggedState as t, ActorStoppedError as u };