@xstate/effect 0.1.0-alpha.2

package/dist/state-9a718be3.js

@@ -0,0 +1,733 @@
+import { Queue, Effect, Scope, Exit, Cause, Context, Fiber, Duration, Data } from 'effect';
+import { stopActor, terminateActor, deliverEvent } from 'xstate';
+import { createDurable } from 'xstate/durable';
+
+/** A mailbox item that reports a failed fire-and-forget action. */
+
+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`.
+ */
+function safeCall(fn, arg) {
+  try {
+    fn?.(arg);
+  } catch (err) {
+    setTimeout(() => {
+      throw 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.
+ */
+class EffectActor {
+  constructor(logic, root, snapshot, _mailbox, _stopExecution, _inspectors) {
+    this.logic = logic;
+    this._mailbox = _mailbox;
+    this._stopExecution = _stopExecution;
+    this._inspectors = _inspectors;
+    this.id = void 0;
+    this.address = void 0;
+    this.sessionId = void 0;
+    /** The actor system that hosts this actor and its children. */
+    this.system = void 0;
+    /** @internal */
+    this._root = void 0;
+    this._snapshot = void 0;
+    this._observers = new Set();
+    this._listeners = new Map();
+    this._settled = false;
+    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(undefined, 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);
+      }
+      return {
+        unsubscribe: () => {}
+      };
+    }
+    this._observers.add(observer);
+    return {
+      unsubscribe: () => {
+        this._observers.delete(observer);
+      }
+    };
+  }
+  on(type, handler) {
+    let listeners = this._listeners.get(type);
+    if (!listeners) {
+      listeners = 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
+   * transition, event delivery and dead letter 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;
+    const status = snapshot.status;
+    if (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);
+      }
+    }
+  }
+
+  /** @internal */
+  get _isSettled() {
+    return this._settled;
+  }
+}
+
+const effectHosts = 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.
+ */
+function withEffectHost(host, fn) {
+  const previous = ambientHost;
+  ambientHost = host;
+  try {
+    return fn();
+  } finally {
+    ambientHost = previous;
+  }
+}
+function createEffectHost(context, scope) {
+  return {
+    context,
+    scope,
+    interruptors: new Map(),
+    subscriptions: new Map()
+  };
+}
+function bindEffectHost(target, host) {
+  effectHosts.set(target, host);
+}
+function findEffectHost(actor) {
+  let current = actor;
+  while (current) {
+    const host = effectHosts.get(current);
+    if (host) {
+      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 || !machine.idMap || 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) {
+    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) {
+    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) {
+    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) {
+    interruptors = 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.
+ *
+ * This mirrors how Effect's own `unstable/reactivity` bridges callback code:
+ * `Effect.runCallbackWith` with the captured services, and a synchronous
+ * interruptor kept per actor.
+ */
+function startHostedEffect(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 interrupt = Effect.runCallbackWith(host.context)(traced, {
+    onExit: exit => {
+      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.
+ */
+function runHostedEffect(actor, effect, spanName) {
+  return new Promise((resolve, reject) => {
+    startHostedEffect(actor, effect, spanName, exit => {
+      if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) {
+        resolve();
+      } else {
+        // Effect failures are arbitrary values, not necessarily Errors.
+        // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+        reject(Cause.squash(exit.cause));
+      }
+    });
+  });
+}
+
+/**
+ * Closes the host scope immediately and runs its finalizers, with the host's
+ * services, on a fiber that `createEffectActor`'s release can await.
+ */
+function closeEffectHost(host) {
+  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);
+  }
+  const finalizers = Scope.closeUnsafe(host.scope, Exit.void);
+  if (finalizers) {
+    host.closing = Effect.runForkWith(host.context)(finalizers);
+  }
+}
+
+/**
+ * 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.
+ */
+function relayToParent(actor, event) {
+  const actorWithParent = actor;
+  if (actorWithParent._parent) {
+    actor.system._relay(actorWithParent, actorWithParent._parent, event);
+  }
+}
+
+const XSTATE_TIMER = 'xstate.timer';
+
+/** Options for {@link createEffectActor}. */
+
+/**
+ * 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(baseContext, Scope.Scope, actorScope);
+    const host = createEffectHost(context, actorScope);
+    const runFork = Effect.runForkWith(context);
+    const runPromise = Effect.runPromiseWith(context);
+    const mailbox = yield* Queue.unbounded();
+    const timers = new Map();
+    // `root` and `actor` are declared after the adapter below; its
+    // callbacks only run once they are initialized.
+    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 = new Set();
+    let rootAnnounced = false;
+    const durable = createDurable(logic, {
+      executeAction: (action, _metadata, runtime) => {
+        // Fire-and-forget: the action starts now and the loop continues.
+        // A rejection reaches the machine as an execution error.
+        try {
+          const result = withEffectHost(host, () => action.exec(runtime));
+          if (result && typeof result.then === 'function') {
+            void Promise.resolve(result).catch(error => {
+              offer({
+                [actionFailure]: true,
+                error
+              });
+            });
+          }
+        } catch (error) {
+          offer({
+            [actionFailure]: true,
+            error
+          });
+        }
+      },
+      spawnActor: (_source, child) => {
+        // Every actor of this execution hosts its Effects here.
+        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 => {
+        // The pure step scope re-materializes the root ref per step and
+        // announces it again; observers should see the root once.
+        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 && !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);
+    };
+
+    // The first transition runs here so the handle is ready when this
+    // Effect succeeds, and the initial actions start before any send.
+    let [snapshot, effects] = durable.initialTransition(options?.input);
+    const root = durable.getActorRef(snapshot);
+    // The root exists from here on; later announcements are step
+    // re-materializations, not new actors.
+    rootAnnounced = true;
+    const actor = new EffectActor(logic, root, snapshot, mailbox, stop, inspectors);
+    bindEffectHost(actor, host);
+    const executeEffects = batch => Effect.promise(() => durable.executeEffects(batch).then(() => undefined, 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, () => undefined));
+        if (item === undefined || stopped) {
+          break;
+        }
+        let event;
+        if (isActionFailure(item)) {
+          const errorEvent = logic.getExecutionErrorEvent?.(snapshot, item.error);
+          if (!errorEvent) {
+            snapshot = errorSnapshot(snapshot, item.error);
+            break;
+          }
+          event = errorEvent;
+        } else {
+          event = item;
+        }
+        try {
+          [snapshot, effects] = durable.transition(snapshot, event);
+        } catch (error) {
+          snapshot = errorSnapshot(snapshot, error);
+          break;
+        }
+        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) {
+      yield* Fiber.join(host.closing);
+    } else {
+      yield* Scope.close(host.scope, Exit.void);
+    }
+  })).pipe(Effect.map(({
+    actor
+  }) => actor));
+}
+
+/**
+ * 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.
+ */
+class EffectInterruptedError 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.
+ */
+class ActorStoppedError extends Data.TaggedError('ActorStoppedError') {
+  get message() {
+    return `Actor "${this.actorId}" ${this.snapshot.status === 'error' ? 'errored' : 'stopped'} before completing`;
+  }
+}
+
+/**
+ * Reported by the `send` atom of `createActorAtoms` when an event is sent
+ * before the actor's runtime has finished building.
+ */
+class NotReadyError extends Data.TaggedError('NotReadyError') {
+  get message() {
+    return 'The actor is not ready yet';
+  }
+}
+
+/** The tag of the machine itself, used when the root state is parallel. */
+const MACHINE_TAG = '(machine)';
+
+/**
+ * The dotted path of a state value: `'idle'`, `'form.editing'`. A parallel
+ * state has no single path, so its tag stops at the parallel state, or is
+ * `'(machine)'` when the machine itself is parallel.
+ */
+
+/**
+ * A machine snapshot as a tagged union over its states. `_tag` is the state's
+ * dotted path and `context` is the context of that state, including any
+ * per-state context schema, so `Match.tag` narrows both.
+ */
+
+/** The tagged state union of a 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 || 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 { ActorStoppedError as A, EffectInterruptedError as E, NotReadyError as N, runHostedEffect as a, EffectActor as b, createEffectActor as c, relayToParent as r, startHostedEffect as s, taggedState as t };