@xstate/effect 0.1.0-alpha.2

package/dist/xstate-effect.js

@@ -0,0 +1,702 @@
+import { Schema, Effect, Stream, Exit, Cause, Queue } from 'effect';
+import { createLogic, setup } from 'xstate';
+import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-9a718be3.js';
+export { A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState } from './state-9a718be3.js';
+import { dual } from 'effect/Function';
+import 'xstate/durable';
+
+/**
+ * An Effect `Schema` accepted by this package. `setupEffect`, `fromEffect`,
+ * `fromEffectStream` and `fromEffectEventStream` convert it to a Standard
+ * Schema, so XState infers the decoded `Schema.Type` without an explicit call
+ * to `Schema.toStandardSchemaV1`.
+ */
+
+/**
+ * Either an Effect {@link EffectSchema} or a Standard Schema. Every schema
+ * position in this package accepts both, so Effect schemas and schemas from
+ * other libraries can be mixed in one machine.
+ */
+
+/**
+ * The `schemas` option of `setupEffect`: XState's `SetupSchemas` with every
+ * schema position widened to {@link EffectSchemaLike}. Covers `context`,
+ * `input`, `output` and the per-key records for `events`, `internalEvents`,
+ * `emitted` and `children`.
+ */
+
+/**
+ * One node of the `states` option of `setupEffect`: the schemas declared for
+ * that state, and the same shape recursively for its child states. It is
+ * XState's `SetupStateSchema` with Effect schemas allowed in every schema
+ * position.
+ */
+
+function isStandardSchema(value) {
+  return !!value && (typeof value === 'object' || typeof value === 'function') && '~standard' in value;
+}
+function toStandardSchema(schema) {
+  if (Schema.isSchema(schema)) {
+    return Schema.toStandardSchemaV1(schema);
+  }
+  return schema;
+}
+function mapSchemaRecord(value) {
+  return Object.fromEntries(Object.keys(value).map(key => {
+    const entry = value[key];
+    if (Schema.isSchema(entry) || isStandardSchema(entry)) {
+      return [key, toStandardSchema(entry)];
+    }
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      return [key, mapSchemaRecord(entry)];
+    }
+    return [key, entry];
+  }));
+}
+function toStandardSetupSchemas(schemas) {
+  return schemas ? mapSchemaRecord(schemas) : undefined;
+}
+function toStandardSetupStates(states) {
+  if (!states) {
+    return undefined;
+  }
+  return Object.fromEntries(Object.keys(states).map(key => {
+    const state = states[key];
+    return [key, {
+      ...state,
+      ...(state.schemas ? {
+        schemas: mapSchemaRecord(state.schemas)
+      } : undefined),
+      ...(state.states ? {
+        states: toStandardSetupStates(state.states)
+      } : undefined)
+    }];
+  }));
+}
+
+const EFFECT_INIT = '@xstate.init';
+const EFFECT_RESOLVE = 'xstate.effect.resolve';
+const EFFECT_REJECT = 'xstate.effect.reject';
+const EFFECT_NEXT = 'xstate.effect.next';
+const EFFECT_COMPLETE = 'xstate.effect.complete';
+const effectLogicBrand = Symbol.for('@xstate/effect/logic');
+
+/**
+ * Type-level marker attached to logic created by `fromEffect`,
+ * `fromEffectStream` and `fromEffectEventStream`. It carries the logic's
+ * failure type and its Effect service requirements, which is how
+ * `RequirementsFrom` collects the `R` channel of `createEffectActor` without
+ * inspecting the logic at runtime.
+ */
+
+/**
+ * Snapshot of a `fromEffect` actor. The actor holds no context of its own: it
+ * is `active` while the Effect runs, `done` with the Effect's success value as
+ * `output`, or `error` with the Effect's failure, defect or
+ * `EffectInterruptedError` as `error`.
+ */
+
+/**
+ * Argument passed to the function form of an Effect source. It gives the
+ * source the actor's `input`, its own reference (`self`), the actor `system`,
+ * and `emit` for publishing events that `actor.on(...)` and `emitted(actor)`
+ * observe.
+ */
+
+/**
+ * What `fromEffect` accepts as its Effect: either an Effect value, or a
+ * function of {@link EffectSourceArgs} returning one. The function form is
+ * called once per actor start, so it sees that actor's input.
+ */
+
+/**
+ * Actor logic produced by `fromEffect` and `fromEffectEventStream`. It is
+ * ordinary XState actor logic carrying {@link EffectLogicBrand}, so a machine
+ * can invoke or spawn it, and `createEffectActor` can collect its
+ * requirements.
+ */
+
+/**
+ * Snapshot of a `fromEffectStream` actor. `context` holds the most recent
+ * stream item, or `undefined` before the first one. The actor reaches `done`
+ * with no output when the stream completes, and `error` when it fails.
+ */
+
+/**
+ * Actor logic produced by `fromEffectStream`. Its snapshot is an
+ * {@link EffectStreamSnapshot}, so the parent reads the latest item from the
+ * child's `context` rather than from events.
+ */
+
+function toError(exit) {
+  if (Exit.isSuccess(exit)) {
+    return undefined;
+  }
+  if (Cause.hasInterruptsOnly(exit.cause)) {
+    return new EffectInterruptedError({
+      cause: exit.cause
+    });
+  }
+  return Cause.squash(exit.cause);
+}
+function createSourceArgs(input, self, system) {
+  return {
+    input,
+    self,
+    system,
+    emit: event => {
+      void system.emitEvent(self, event);
+    }
+  };
+}
+function brandLogic(logic, error, requirements) {
+  Object.defineProperty(logic, effectLogicBrand, {
+    configurable: false,
+    enumerable: false,
+    value: {
+      error,
+      requirements
+    }
+  });
+  return logic;
+}
+
+/**
+ * Creates actor logic that runs an Effect. The actor completes with the
+ * Effect's success value as its output and fails with the Effect's error, its
+ * squashed defect, or an `EffectInterruptedError` when the Effect interrupts
+ * itself. Stopping the actor interrupts the Effect without an error. Accepts
+ * an Effect, a function of {@link EffectSourceArgs} returning one, or a config
+ * object with `id`, `schemas`, `validator` and `effect`. The logic must be run
+ * under `createEffectActor`, which provides the Effect services it declares.
+ */
+
+function fromEffect(sourceOrConfig) {
+  const config = typeof sourceOrConfig === 'function' || Effect.isEffect(sourceOrConfig) ? {
+    effect: sourceOrConfig
+  } : sourceOrConfig;
+  const source = config.effect;
+  const schemas = config.schemas ? {
+    ...(config.schemas.input ? {
+      input: toStandardSchema(config.schemas.input)
+    } : {}),
+    ...(config.schemas.output ? {
+      output: toStandardSchema(config.schemas.output)
+    } : {})
+  } : undefined;
+  const logic = createLogic({
+    id: config.id,
+    validator: config.validator,
+    schemas,
+    context: undefined,
+    run: ({
+      event,
+      input,
+      self,
+      system
+    }, enq) => {
+      if (event.type === EFFECT_RESOLVE) {
+        return {
+          status: 'done',
+          output: event.output,
+          input: undefined
+        };
+      }
+      if (event.type === EFFECT_REJECT) {
+        return {
+          status: 'error',
+          error: event.error,
+          input: undefined
+        };
+      }
+      if (event.type !== EFFECT_INIT) {
+        return;
+      }
+      const effect = typeof source === 'function' ? source(createSourceArgs(input, self, system)) : source;
+      enq.effect(() => startHostedEffect(self, effect, 'fromEffect', exit => {
+        if (self.getSnapshot().status !== 'active') {
+          return;
+        }
+        if (Exit.isSuccess(exit)) {
+          self.send({
+            type: EFFECT_RESOLVE,
+            output: exit.value
+          });
+        } else {
+          self.send({
+            type: EFFECT_REJECT,
+            error: toError(exit)
+          });
+        }
+      }));
+    }
+  });
+  return brandLogic(logic, undefined, undefined);
+}
+
+/**
+ * What `fromEffectStream` and `fromEffectEventStream` accept as their stream:
+ * either a Stream value, or a function of {@link EffectSourceArgs} returning
+ * one. The function form is called once per actor start.
+ */
+
+function resolveStreamConfig(sourceOrConfig) {
+  return typeof sourceOrConfig === 'function' || Stream.isStream(sourceOrConfig) ? {
+    stream: sourceOrConfig
+  } : sourceOrConfig;
+}
+function toLogicSchemas(schemas) {
+  return schemas?.input ? {
+    input: toStandardSchema(schemas.input)
+  } : undefined;
+}
+
+/**
+ * Creates actor logic that runs a Stream and exposes its most recent item as
+ * the actor's `context`. The actor reaches `done` when the stream completes
+ * and `error` when it fails. Accepts a Stream, a function of
+ * {@link EffectSourceArgs} returning one, or a config object with `id`,
+ * `schemas`, `validator` and `stream`.
+ */
+
+function fromEffectStream(sourceOrConfig) {
+  const config = resolveStreamConfig(sourceOrConfig);
+  const stream = config.stream;
+  const logic = createLogic({
+    id: config.id,
+    validator: config.validator,
+    schemas: toLogicSchemas(config.schemas),
+    context: undefined,
+    run: ({
+      event,
+      input,
+      self,
+      system
+    }, enq) => {
+      if (event.type === EFFECT_NEXT) {
+        return {
+          context: event.value
+        };
+      }
+      if (event.type === EFFECT_COMPLETE) {
+        return {
+          status: 'done',
+          input: undefined
+        };
+      }
+      if (event.type === EFFECT_REJECT) {
+        return {
+          status: 'error',
+          error: event.error,
+          input: undefined
+        };
+      }
+      if (event.type !== EFFECT_INIT) {
+        return;
+      }
+      const streamValue = typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream;
+      const consume = Stream.runForEach(streamValue, value => Effect.sync(() => {
+        if (self.getSnapshot().status === 'active') {
+          self.send({
+            type: EFFECT_NEXT,
+            value
+          });
+        }
+      }));
+      enq.effect(() => startHostedEffect(self, consume, 'fromEffectStream', exit => {
+        if (self.getSnapshot().status !== 'active') {
+          return;
+        }
+        if (Exit.isSuccess(exit)) {
+          self.send({
+            type: EFFECT_COMPLETE
+          });
+        } else {
+          self.send({
+            type: EFFECT_REJECT,
+            error: toError(exit)
+          });
+        }
+      }));
+    }
+  });
+  return brandLogic(logic, undefined, undefined);
+}
+
+/**
+ * Creates actor logic that runs a Stream of events and relays each item to the
+ * parent machine as an event, the way `fromEventObservable` does. The actor
+ * has no output: it reaches `done` when the stream completes and `error` when
+ * it fails. Accepts the same forms as `fromEffectStream`.
+ */
+
+function fromEffectEventStream(sourceOrConfig) {
+  const config = resolveStreamConfig(sourceOrConfig);
+  const stream = config.stream;
+  const logic = createLogic({
+    id: config.id,
+    validator: config.validator,
+    schemas: toLogicSchemas(config.schemas),
+    context: undefined,
+    run: ({
+      event,
+      input,
+      self,
+      system
+    }, enq) => {
+      if (event.type === EFFECT_COMPLETE) {
+        return {
+          status: 'done',
+          input: undefined
+        };
+      }
+      if (event.type === EFFECT_REJECT) {
+        return {
+          status: 'error',
+          error: event.error,
+          input: undefined
+        };
+      }
+      if (event.type !== EFFECT_INIT) {
+        return;
+      }
+      const streamValue = typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream;
+      const consume = Stream.runForEach(streamValue, value => Effect.sync(() => relayToParent(self, value)));
+      enq.effect(() => startHostedEffect(self, consume, 'fromEffectEventStream', exit => {
+        if (self.getSnapshot().status !== 'active') {
+          return;
+        }
+        if (Exit.isSuccess(exit)) {
+          self.send({
+            type: EFFECT_COMPLETE
+          });
+        } else {
+          self.send({
+            type: EFFECT_REJECT,
+            error: toError(exit)
+          });
+        }
+      }));
+    }
+  });
+  return brandLogic(logic, undefined, undefined);
+}
+
+/** The event type accepted by an actor's `send` method. */
+
+/** The event type an actor emits through `actor.on(...)`. */
+
+/** Options for {@link waitFor}. */
+
+const noopSubscription = {
+  unsubscribe: () => {}
+};
+function actorId(actor) {
+  return actor.id ?? '(unknown)';
+}
+
+/**
+ * Marks an already-errored actor's error as observed, so XState does not
+ * report it as unhandled: the caller consumes it as a typed failure.
+ */
+function observeError(actor) {
+  actor.subscribe({
+    error: () => {}
+  }).unsubscribe();
+}
+function stoppedError(actor) {
+  return new ActorStoppedError({
+    actorId: actorId(actor),
+    snapshot: actor.getSnapshot()
+  });
+}
+function isActorRef(value) {
+  return typeof value === 'object' && value !== null && typeof value.send === 'function' && typeof value.getSnapshot === 'function';
+}
+
+/**
+ * Sends an event to an actor. The returned Effect always succeeds: the event
+ * is enqueued, like `actor.send(event)`, and processed on the actor's own
+ * fiber. An event that cannot be delivered (for example to a stopped actor)
+ * is reported as a dead letter, observable with {@link deadLetters}.
+ */
+const send = dual(2, (actor, event) => Effect.sync(() => {
+  actor.send(event);
+}));
+
+/**
+ * Streams an actor's snapshots, starting with the current one. The stream ends
+ * when the actor completes or stops, and emits the error snapshot before
+ * ending when the actor errors. Interrupting the stream unsubscribes from the
+ * actor.
+ */
+function snapshots(actor) {
+  return Stream.callback(queue => Effect.acquireRelease(Effect.sync(() => {
+    const current = actor.getSnapshot();
+    Queue.offerUnsafe(queue, current);
+    if (current.status !== 'active') {
+      observeError(actor);
+      Queue.endUnsafe(queue);
+      return noopSubscription;
+    }
+    return actor.subscribe({
+      next: snapshot => {
+        Queue.offerUnsafe(queue, snapshot);
+      },
+      error: () => {
+        Queue.offerUnsafe(queue, actor.getSnapshot());
+        Queue.endUnsafe(queue);
+      },
+      complete: () => {
+        Queue.endUnsafe(queue);
+      }
+    });
+  }), subscription => Effect.sync(() => {
+    subscription.unsubscribe();
+  })));
+}
+
+/**
+ * Streams every event an actor emits, as delivered to `actor.on('*', …)`. The
+ * stream ends when the actor completes, errors or stops. Interrupting the
+ * stream removes the listener.
+ */
+function emitted(actor) {
+  return Stream.callback(queue => Effect.acquireRelease(Effect.sync(() => {
+    const listener = actor.on('*', event => {
+      Queue.offerUnsafe(queue, event);
+    });
+    if (actor.getSnapshot().status !== 'active') {
+      Queue.endUnsafe(queue);
+      return [listener, noopSubscription];
+    }
+    const subscription = actor.subscribe({
+      error: () => {
+        Queue.endUnsafe(queue);
+      },
+      complete: () => {
+        Queue.endUnsafe(queue);
+      }
+    });
+    return [listener, subscription];
+  }), ([listener, subscription]) => Effect.sync(() => {
+    listener.unsubscribe();
+    subscription.unsubscribe();
+  })));
+}
+
+/**
+ * Waits for the first actor snapshot that satisfies `predicate`, succeeding
+ * immediately when the current snapshot already does. Fails with
+ * `ActorStoppedError` if the actor stops or errors first, and with
+ * `Cause.TimeoutError` when `options.timeout` elapses. Interrupting the Effect
+ * unsubscribes from the actor.
+ */
+const waitFor = dual(args => isActorRef(args[0]), (actor, predicate, options) => {
+  const waiting = Effect.callback(resume => {
+    const current = actor.getSnapshot();
+    if (predicate(current)) {
+      resume(Effect.succeed(current));
+      return;
+    }
+    if (current.status !== 'active') {
+      observeError(actor);
+      resume(Effect.fail(stoppedError(actor)));
+      return;
+    }
+    let settled = false;
+    // oxlint-disable-next-line prefer-const
+    let subscription; // avoid TDZ when settling synchronously
+    const dispose = () => {
+      settled = true;
+      subscription?.unsubscribe();
+    };
+    subscription = actor.subscribe({
+      next: snapshot => {
+        if (settled || !predicate(snapshot)) {
+          return;
+        }
+        dispose();
+        resume(Effect.succeed(snapshot));
+      },
+      error: () => {
+        if (settled) {
+          return;
+        }
+        dispose();
+        resume(Effect.fail(stoppedError(actor)));
+      },
+      complete: () => {
+        if (settled) {
+          return;
+        }
+        dispose();
+        resume(Effect.fail(stoppedError(actor)));
+      }
+    });
+    if (settled) {
+      subscription.unsubscribe();
+    }
+    return Effect.sync(dispose);
+  });
+  return options === undefined ? waiting : Effect.timeout(waiting, options.timeout);
+});
+
+/**
+ * Joins an actor's final result, like `Fiber.join`: succeeds with its `output`
+ * when it is done, fails with `snapshot.error` when it errors, and fails with
+ * `ActorStoppedError` when it stops without output. Waits for a still-active
+ * actor to settle.
+ */
+function join(actor) {
+  return Effect.callback(resume => {
+    const settle = () => {
+      const snapshot = actor.getSnapshot();
+      if (snapshot.status === 'done') {
+        resume(Effect.succeed(snapshot.output));
+      } else if (snapshot.status === 'error') {
+        resume(Effect.fail(snapshot.error));
+      } else {
+        resume(Effect.fail(stoppedError(actor)));
+      }
+    };
+    if (actor.getSnapshot().status !== 'active') {
+      observeError(actor);
+      settle();
+      return;
+    }
+    let settled = false;
+    // oxlint-disable-next-line prefer-const
+    let subscription; // avoid TDZ when settling synchronously
+    const dispose = () => {
+      settled = true;
+      subscription?.unsubscribe();
+    };
+    const onSettled = () => {
+      if (settled) {
+        return;
+      }
+      dispose();
+      settle();
+    };
+    subscription = actor.subscribe({
+      error: onSettled,
+      complete: onSettled
+    });
+    if (settled) {
+      subscription.unsubscribe();
+    }
+    return Effect.sync(dispose);
+  });
+}
+
+/**
+ * Streams the inspection events of the actor's system, as delivered to
+ * `system.inspect(…)`. The stream runs until it is interrupted or its scope
+ * closes.
+ */
+function inspect(actor) {
+  return Stream.callback(queue => Effect.acquireRelease(Effect.sync(() => {
+    const observer = inspectionEvent => {
+      Queue.offerUnsafe(queue, inspectionEvent);
+    };
+    const inspectable = actor;
+    return inspectable.inspect ? inspectable.inspect(observer) : actor.system.inspect(observer);
+  }), subscription => Effect.sync(() => {
+    subscription.unsubscribe();
+  })));
+}
+
+/**
+ * Streams the events the actor's system could not deliver: sends to a
+ * stopped actor, invalid external events and internal events sent from
+ * outside their owner. A dead letter is not an actor error. The stream runs
+ * until it is interrupted or its scope closes.
+ */
+function deadLetters(actor) {
+  return Stream.filter(inspect(actor), event => event.type === '@xstate.deadletter');
+}
+
+/**
+ * Argument an Effect action receives. It mirrors the v6 action argument
+ * object: the machine's `context` and the `event` that caused the transition,
+ * the actor itself and its family (`self`, `parent`, `children`), the
+ * registered `actions`, `actors`, `guards` and `delays`, the actor `system`,
+ * and the `params` and `output` the transition passed along.
+ */
+
+/**
+ * An action registered with `setupEffect({ actions })`. It is called
+ * synchronously during the transition with the arguments the transition
+ * enqueued, and returns an Effect that runs afterwards in the actor's Effect
+ * context. The Effect is interrupted when the actor stops; its failures and
+ * defects route to the state's `onError`.
+ */
+
+/**
+ * What `setupEffect` returns: the XState `SetupReturn` with an `extend` method
+ * that also accepts Effect schemas and Effect-returning actions. Call
+ * `createMachine` on it to build a machine whose registered actions and actors
+ * contribute to `RequirementsFrom`.
+ */
+
+function wrapActions(actions) {
+  if (!actions) {
+    return undefined;
+  }
+  const wrapped = {};
+  for (const key of Object.keys(actions)) {
+    const action = actions[key];
+    wrapped[key] = args => {
+      const result = action(args);
+      return Effect.isEffect(result) ? runHostedEffect(args.self, result, `action.${key}`) : result;
+    };
+  }
+  return wrapped;
+}
+
+/**
+ * Makes `machine.provide` host Effect-returning action overrides the same way
+ * `setupEffect` hosts declared actions.
+ */
+function decorateMachine(machine) {
+  const provide = machine.provide.bind(machine);
+  machine.provide = sources => decorateMachine(provide({
+    ...sources,
+    actions: wrapActions(sources.actions)
+  }));
+  return machine;
+}
+function decorateEffectSetup(effectSetup) {
+  const createMachine = effectSetup.createMachine.bind(effectSetup);
+  effectSetup.createMachine = config => decorateMachine(createMachine(config));
+  const extend = effectSetup.extend;
+  const extendAny = extend;
+  effectSetup.extend = extension => decorateEffectSetup(extendAny({
+    ...extension,
+    schemas: toStandardSetupSchemas(extension.schemas),
+    states: toStandardSetupStates(extension.states),
+    actions: wrapActions(extension.actions)
+  }));
+  return effectSetup;
+}
+
+/**
+ * The Effect-aware form of XState's `setup`. It accepts Effect `Schema` values
+ * wherever `setup` accepts Standard Schemas, and actions that return an
+ * Effect, which it wraps so the transition stays synchronous while the Effect
+ * runs in the actor's Effect context. Everything else, including `actors`,
+ * `guards`, `delays` and `extend`, behaves as in `setup`. Machines built from
+ * it must be started with `createEffectActor`.
+ */
+
+function setupEffect(config = {}) {
+  return decorateEffectSetup(setup({
+    ...config,
+    schemas: toStandardSetupSchemas(config.schemas),
+    states: toStandardSetupStates(config.states),
+    actions: wrapActions(config.actions)
+  }));
+}
+
+export { deadLetters, emitted, fromEffect, fromEffectEventStream, fromEffectStream, inspect, join, send, setupEffect, snapshots, waitFor };