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

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @systemfsoftware/xstate-effect
+
+# @systemfsoftware/xstate-effect@0.1.0-beta.8
+
+`join` now fails with the new `ActorFailedError<E>` whenever the joined actor errors, for every kind of actor. Its `cause` is the exact value the actor failed with, typed as the actor's `ErrorFrom`: a `fromEffect` actor's own error, `unknown` for a machine or a `snapshot.children` entry. Breaking: `join` on a `fromEffect` actor no longer fails with the Effect's error directly; read it from `error.cause`, or match the `ActorFailedError` tag first. `ActorStoppedError` is unchanged.
+
+Add `@systemfsoftware/xstate-effect`, the Effect 4 runtime for XState actors, forked from statelyai/xstate's `next` branch at 2146ae26 (MIT). It behaves like upstream's 0.1.0-alpha.7. Under `exactOptionalPropertyTypes`, optional members that can hold `undefined` declare it explicitly. The `effect` peer range is `^4.0.1` (the monorepo catalog had `^4`), so a consumer resolves at least Effect 4.0.1.

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 David Khourshid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# @xstate/effect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> `@systemfsoftware/xstate-effect` is forked from [statelyai/xstate](https://github.com/statelyai/xstate) (`packages/xstate-effect`, branch `next` at `2146ae26ebfc7e6a624b3a1f237f9e6ddc30b9f5`), MIT. The text below is upstream's.
+
+Combine XState's event-driven workflows with Effect services, scopes, clocks and tracing.
+
+- Model approval, cancellation, deadlines and retry as explicit states and events.
+- Invoke Effect tasks when their result determines the next state.
+- Provide services once for the actor and its child logic.
+- Keep actor lifetime inside your Effect application.
+
+This package is experimental. It targets XState v6 alpha and Effect 4.
+
+## Installation
+
+<!-- package name and peer dependencies from package.json -->
+
+```bash
+nix build github:systemfsoftware/xstate#xstate-effect
+```
+
+See the root README's [Install](../../README.md#install) section for wiring a catalog entry. Its peer `@systemfsoftware/xstate` comes from the same flake (`#xstate`), and `effect@^4` from your own package manager.
+
+## XState Effect: Quick start
+
+<!-- public API from src/index.ts; actor lifetime from src/createEffectActor.ts -->
+
+A release waits for approval, expires after 30 seconds, and allows cancellation during deployment. A failed deployment waits for an explicit retry:
+
+<!-- example from examples/effect-workflows/src/approval.ts -->
+
+```ts
+import { createEffectActor, fromEffect, send, setupEffect, waitFor } from '@xstate/effect'
+import { Context, Effect, Schema } from 'effect'
+
+export class Deployments extends Context.Service<
+  Deployments,
+  { readonly deploy: (release: string) => Effect.Effect<string, Error> }
+>()('@app/Deployments') {}
+
+const deploy = fromEffect({
+  schemas: { input: Schema.Struct({ release: Schema.String }) },
+  effect: ({ input }) => Deployments.use((api) => api.deploy(input.release)),
+})
+
+export const approvalMachine = setupEffect({
+  schemas: { input: Schema.Struct({ release: Schema.String }) },
+  actors: { deploy },
+}).createMachine({
+  context: ({ input }) => ({ release: input.release, url: '' }),
+  initial: 'awaitingApproval',
+  states: {
+    awaitingApproval: {
+      after: { 30000: { target: 'expired' } },
+      on: {
+        APPROVE: { target: 'deploying' },
+        CANCEL: { target: 'cancelled' },
+      },
+    },
+    deploying: {
+      invoke: {
+        src: 'deploy',
+        input: ({ context }) => ({ release: context.release }),
+        onDone: ({ context, event }) => ({
+          target: 'deployed',
+          context: { ...context, url: event.output },
+        }),
+        onError: { target: 'failed' },
+      },
+      on: { CANCEL: { target: 'cancelled' } },
+    },
+    failed: {
+      on: {
+        RETRY: { target: 'deploying' },
+        CANCEL: { target: 'cancelled' },
+      },
+    },
+    deployed: { type: 'final' },
+    expired: { type: 'final' },
+    cancelled: { type: 'final' },
+  },
+})
+
+export const program = Effect.gen(function*() {
+  const actor = yield* createEffectActor(approvalMachine, {
+    input: { release: 'v1.2.0' },
+  })
+  // A UI, webhook or CLI can send this event after a person approves.
+  yield* send(actor, { type: 'APPROVE' })
+  const snapshot = yield* waitFor(actor, (s) => s.matches('deployed'), {
+    timeout: '5 seconds',
+  })
+  return snapshot.context.url
+})
+
+export const result = await Effect.runPromise(
+  program.pipe(
+    Effect.scoped,
+    Effect.provideService(Deployments, {
+      // Replace this demo service with your deployment API.
+      deploy: (release) => Effect.succeed(`https://example.com/${release}`),
+    }),
+  ),
+)
+console.log(result) // 'https://example.com/v1.2.0'
+```
+
+The demo service runs locally. Replace it with your deployment API. The machine defines which events are valid in each state; Effect provides the deployment service and owns the actor's lifetime.
+
+Start Effect-backed logic with `createEffectActor` inside an Effect scope.
+
+<details>
+<summary>Runtime and cancellation details</summary>
+
+- `createEffectActor` runs pure XState transitions from an Effect fiber. Its mailbox processes events in order; timers use Effect's `Clock`.
+- Events are processed asynchronously. Read their outcomes with `waitFor`, `join` or `snapshots`.
+- Starting Effect-backed logic with XState's `createActor` produces an error because the Effect host is missing.
+- Leaving an invoking state interrupts its local Effect. It does not undo work already accepted by an external API; model cancellation or rollback explicitly when needed.
+
+</details>
+
+## Guides
+
+| Guide                                              | Examples                                                 |
+| -------------------------------------------------- | -------------------------------------------------------- |
+| [Quick start](docs/quick-start.md)                 | Release approval, expiry, cancellation and retry.        |
+| [Actors](docs/actors.md)                           | Share an actor through a Layer and ManagedRuntime.       |
+| [Observing actors](docs/observing-actors.md)       | Snapshot history, output and streamed reminders.         |
+| [Matching states](docs/matching-states.md)         | Exhaustive matching and per-state context.               |
+| [Effect actor logic](docs/effect-logic.md)         | Report tasks, upload progress and rollout health events. |
+| [Schemas and actions](docs/schemas-and-actions.md) | Runtime event validation and background audit entries.   |
+| [Atoms and React](docs/atoms-and-react.md)         | Registry ownership, approval controls and useSelector.   |
+| [Testing and errors](docs/testing-and-errors.md)   | TestClock, task retries, supervision and typed failures. |
+
+Runnable copies live in [examples/effect-workflows](../../examples/effect-workflows). Their tests verify the docs use the same code.
+
+## Actors
+
+The actor stops and interrupts its hosted Effects when its enclosing scope closes. Use `Effect.scoped` for a bounded program, or `Layer.effect` to share an actor for an application's lifetime.
+
+- Invoked Effect tasks and streams own their resources and release them on completion, failure or cancellation.
+- Background actions use the owning actor's scope.
+- Use `withActorScope` around resource acquisition to keep a resource until the owning actor stops.
+
+Provide Layers outside the actor's scope, so services remain available during cleanup. Dispose a `ManagedRuntime` when its owner shuts down. See [actors](docs/actors.md).
+
+### Requirements
+
+`RequirementsFrom<TLogic>` collects services from declared Effect actions, declared actors and inline invocations, including child machines up to 10 levels deep. `createEffectActor` returns `Effect<EffectActor<TLogic>, never, R | Scope>`. Provided action and actor overrides update that service union. Actor and invocation scopes are supplied automatically.
+
+<details>
+<summary>Requirement limits</summary>
+
+Deeper requirements are not inferred. Provide them explicitly or flatten the machine tree. Inline spawned Effect logic is rejected; register it in `actors` before spawning it.
+
+The actor's later errors are observed through `join` or snapshots. Invalid input rejected during creation is a defect.
+
+</details>
+
+### Observing actors
+
+<!-- actor surface from src/actor.ts -->
+
+| Function      | Use                                                    |
+| ------------- | ------------------------------------------------------ |
+| `send`        | Enqueue an event.                                      |
+| `snapshots`   | Stream the current snapshot and changes.               |
+| `waitFor`     | Await a snapshot predicate, optionally with a timeout. |
+| `join`        | Await final output or failure.                         |
+| `emitted`     | Stream notifications emitted by the actor.             |
+| `inspect`     | Stream system inspection events.                       |
+| `deadLetters` | Observe delivery failures.                             |
+
+`send` and `waitFor` support direct and pipeable usage. See [complete observation examples](docs/observing-actors.md).
+
+### Matching states
+
+<!-- tagged state view from src/state.ts -->
+
+`taggedState(snapshot)` exposes `_tag`, `value`, `context` and `snapshot`. Use `TaggedState<typeof machine>` with Effect's `Match.tag` and `Match.exhaustive`. Per-state context narrows with the tag. See [matching states](docs/matching-states.md).
+
+## Effect actor logic
+
+<!-- fromEffect, fromEffectStream, fromEffectEventStream from src/fromEffect.ts -->
+
+| Function                | Behavior                                             |
+| ----------------------- | ---------------------------------------------------- |
+| `fromEffect`            | Run a task; its success value is the actor's output. |
+| `fromEffectStream`      | Expose the latest stream item as snapshot context.   |
+| `fromEffectEventStream` | Relay stream items to the parent as events.          |
+
+For example, a progress stream can feed an upload UI:
+
+<!-- example from examples/effect-workflows/src/latest-stream.ts -->
+
+```ts
+import { createEffectActor, fromEffectStream, snapshots } from '@xstate/effect'
+import { Effect, Option, Stream } from 'effect'
+
+// Demo upload progress. Replace with your upload SDK's progress stream.
+const uploadProgress = fromEffectStream(Stream.make(0, 25, 60, 100))
+
+const program = Effect.gen(function*() {
+  const actor = yield* createEffectActor(uploadProgress)
+  return yield* snapshots(actor).pipe(
+    Stream.filter((s) => s.context !== undefined),
+    Stream.map((s) => s.context),
+    Stream.runLast,
+    Effect.map(Option.getOrThrow),
+  )
+})
+
+export const result = await Effect.runPromise(Effect.scoped(program))
+console.log(result) // 100
+```
+
+See [Effect actor logic](docs/effect-logic.md) for tasks and a stream that drives rollout transitions.
+
+## Schemas and actions
+
+<!-- schema conversion from src/schema.ts -->
+
+`setupEffect` accepts Effect schemas for input, context, events, output and per-state context. Types are inferred without manual conversion. Add `standardSchemaValidator()` from `xstate/validation` for runtime checks.
+
+### Declared only
+
+<!-- effect action contract from src/setupEffect.ts; spawn guard from src/internal.ts -->
+
+- Register background Effect actions in `setupEffect({ actions })`; enqueue them with explicit arguments.
+- Invoke `fromEffect` logic when the machine needs to wait for a result.
+- Register spawned Effect logic in `actors`, then use `enq.spawn(args.actors.worker)`.
+
+See [schemas and actions](docs/schemas-and-actions.md) for a complete audit example, runtime schema constraints and inline-source pitfalls.
+
+## Atoms and React
+
+<!-- atom surface from src/atom.ts -->
+
+`createActorAtoms` from `@xstate/effect/atom` exposes `actor`, `snapshot`, `result`, `send`, `select` and `state`. Its `Atom.runtime` must provide the logic's services. Pass `{ input }` when the logic requires input; missing or mismatched input is a type error.
+
+- Read atoms with `@effect/atom-react` in React, or an `AtomRegistry` elsewhere.
+- The registry owns their lifetime; dispose it when its owner shuts down.
+- `useSelector` from `@xstate/react` can also read an existing `EffectActor` directly.
+
+See [atoms and React](docs/atoms-and-react.md) for complete examples with imports, runtime setup and cleanup.
+
+## Testing and errors
+
+<!-- error types from src/errors.ts; timeout failure from src/actor.ts -->
+
+- Use `TestClock` to drive deadlines without waiting for real time.
+- `ActorStoppedError` reports a stop before an awaited result.
+- `EffectInterruptedError` reports self-interruption inside Effect logic.
+- Timed waits fail with Effect's `Cause.TimeoutError`.
+- `join` preserves a task's typed failure. Unexpected machine errors have type `unknown`.
+
+See [testing and errors](docs/testing-and-errors.md) for executable deadline, retry and failure examples. Persisted snapshots record actor state; pass one to `createEffectActor(logic, { snapshot })` to resume the actor. See [persisting and restoring](docs/actors.md#persisting-and-restoring).
+
+## Tracing
+
+<!-- span names and attributes from src/internal.ts and src/fromEffect.ts -->
+
+Hosted work uses spans named `fromEffect`, `fromEffectStream`, `fromEffectEventStream` and `action.<name>`. Each carries `xstate.actor.id` and `xstate.actor.address`. Provide a `Tracer` to record and export them.

package/dist/atom.d.ts

@@ -0,0 +1,53 @@
+import { I as EffectActor, c as NotReadyError, p as RequirementsFrom, r as TaggedStateFrom, u as EffectActorOptionsArgs } from "./state-Ch1-WxXd.js";
+import { AnyActorLogic, ErrorFrom, EventFromLogic, SnapshotFrom } from "@systemfsoftware/xstate";
+import { AsyncResult, Atom } from "effect/reactivity";
+/**
+ * Atoms that expose one actor to a reactive UI through
+ * `effect/reactivity`. Read them with the atom bindings for your
+ * framework, such as `@effect/atom-react`.
+ */
+export interface ActorAtoms<TLogic extends AnyActorLogic, ER = never> {
+  /**
+   * The running actor. It starts when the atom is first read and stops when
+   * the atom is released, that is, when nothing reads or mounts it anymore.
+   */
+  readonly actor: Atom.Atom<AsyncResult.AsyncResult<EffectActor<TLogic>, ER>>;
+  /** The actor's current snapshot, updated on every transition. */
+  readonly snapshot: Atom.Atom<AsyncResult.AsyncResult<SnapshotFrom<TLogic>, ER>>;
+  /**
+   * The snapshot as a result: a `Failure` carrying the actor's error once
+   * the actor's status is `error`, so an error boundary can handle it.
+   */
+  readonly result: Atom.Atom<AsyncResult.AsyncResult<SnapshotFrom<TLogic>, ER | ErrorFrom<TLogic>>>;
+  /**
+   * Sends an event to the actor synchronously. Set it with the event, for
+   * example through `useAtomSet` in React. Its value reports the last send:
+   * a `NotReadyError` failure when the runtime is still building, otherwise
+   * success.
+   */
+  readonly send: Atom.Writable<AsyncResult.AsyncResult<void, ER | NotReadyError>, EventFromLogic<TLogic>>;
+  /** Derives an atom of a value selected from the snapshot. */
+  readonly select: <T>(selector: (snapshot: SnapshotFrom<TLogic>) => T) => Atom.Atom<AsyncResult.AsyncResult<T, ER>>;
+  /**
+   * The snapshot as a tagged union over the machine's states, for
+   * `Match.tag` or a `switch` on `_tag`. See `taggedState`.
+   */
+  readonly state: Atom.Atom<AsyncResult.AsyncResult<TaggedStateFrom<SnapshotFrom<TLogic>>, ER>>;
+}
+interface MissingRequirements<T> {
+  readonly 'The runtime does not provide services the logic requires': T;
+}
+/**
+ * Creates atoms for an actor that runs in an `Atom.runtime`. The runtime's
+ * Layer must provide every service the logic requires; a missing service is
+ * a type error on the `runtime` argument. Logic with required input also
+ * requires an options object containing that input.
+ *
+ * The actor is created with `createEffectActor` inside the `actor` atom's
+ * scope, so its lifetime follows the atom: it starts on first read and stops
+ * when the atom is released. Wrap the atoms with `Atom.keepAlive` to pin the
+ * actor for the registry's lifetime, or with `Atom.family` to create one
+ * actor per input.
+ */
+export declare function createActorAtoms<TLogic extends AnyActorLogic, R, ER = never>(runtime: Atom.AtomRuntime<R, ER> & ([RequirementsFrom<TLogic>] extends [R] ? unknown : MissingRequirements<Exclude<RequirementsFrom<TLogic>, R>>), logic: TLogic, ...[options]: EffectActorOptionsArgs<TLogic>): ActorAtoms<TLogic, ER>;
+export { NotReadyError };

package/dist/atom.mjs

@@ -0,0 +1,64 @@
+import { f as NotReadyError, n as createEffectActor, t as taggedState } from "./state-CNrCEIpU.mjs";
+import { Cause } from "effect";
+import { AsyncResult, Atom } from "effect/reactivity";
+// src/atom.ts
+/**
+* Creates atoms for an actor that runs in an `Atom.runtime`. The runtime's
+* Layer must provide every service the logic requires; a missing service is
+* a type error on the `runtime` argument. Logic with required input also
+* requires an options object containing that input.
+*
+* The actor is created with `createEffectActor` inside the `actor` atom's
+* scope, so its lifetime follows the atom: it starts on first read and stops
+* when the atom is released. Wrap the atoms with `Atom.keepAlive` to pin the
+* actor for the registry's lifetime, or with `Atom.family` to create one
+* actor per input.
+*/
+function createActorAtoms(runtime, logic, ...[options]) {
+	const actor = runtime.atom(createEffectActor(logic, options));
+	const snapshot = Atom.make((get) => {
+		const result = get(actor);
+		if (!AsyncResult.isSuccess(result)) return AsyncResult.map(result, (running) => running.getSnapshot());
+		const running = result.value;
+		const publish = () => {
+			get.setSelf(AsyncResult.success(running.getSnapshot()));
+		};
+		const subscription = running.subscribe({
+			next: publish,
+			error: publish,
+			complete: publish
+		});
+		get.addFinalizer(() => {
+			subscription.unsubscribe();
+		});
+		return AsyncResult.success(running.getSnapshot());
+	});
+	const result = Atom.make((get) => {
+		const current = get(snapshot);
+		if (!AsyncResult.isSuccess(current)) return current;
+		const value = current.value;
+		if (value.status === "error") return AsyncResult.failureWithPrevious(Cause.fail(value.error), { previous: get.self() });
+		return current;
+	});
+	const sendAtom = Atom.writable((get) => AsyncResult.map(get(actor), () => void 0), (ctx, event) => {
+		const current = ctx.get(actor);
+		if (AsyncResult.isInitial(current)) ctx.setSelf(AsyncResult.failure(Cause.fail(new NotReadyError())));
+		else if (AsyncResult.isFailure(current)) ctx.setSelf(AsyncResult.map(current, () => void 0));
+		else {
+			current.value.send(event);
+			ctx.setSelf(AsyncResult.success(void 0));
+		}
+	});
+	function select(selector) {
+		return Atom.map(snapshot, (result) => AsyncResult.map(result, selector));
+	}
+	return {
+		actor,
+		snapshot,
+		result,
+		send: sendAtom,
+		select,
+		state: select((current) => taggedState(current))
+	};
+}
+export { NotReadyError, createActorAtoms };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { A as ToStandardSetupStates, C as fromEffectEventStream, D as EffectSetupSchemas, E as EffectSchemaLike, F as withActorScope, I as EffectActor, M as ValidateEffectSetupStates, N as effectActionBrand, O as EffectSetupStateSchema, P as ActorScope, S as fromEffect, T as EffectSchema, _ as EffectSource, a as ActorFailedError, b as EffectStreamSnapshot, d as createEffectActor, f as EffectRequirements, g as EffectSnapshot, h as EffectLogicBrand, i as taggedState, j as ValidateEffectSetupSchemas, k as ToStandardSetupSchemas, l as EffectActorOptions, m as EffectActorLogic, n as TaggedState, o as ActorStoppedError, p as RequirementsFrom, r as TaggedStateFrom, s as EffectInterruptedError, t as StateTag, v as EffectSourceArgs, w as fromEffectStream, x as EffectStreamSource, y as EffectStreamActorLogic } from "./state-Ch1-WxXd.js";
+import { Cause, Duration, Effect, Stream } from "effect";
+import { Actor, ActorLogicValidator, ActorRef, AnyActorRef, AnyEventObject, EmittedFrom, ErrorFrom, ErrorFrom as ErrorFrom$1, EventObject, EventRejection, InspectionEvent, MachineContext, OutputFrom, SetupConfig, SetupReturn, SetupSchemas, SetupStateSchema, SnapshotFrom, Sources, SystemRegistry, SystemRuntime } from "@systemfsoftware/xstate";
+/** The event type accepted by an actor's `send` method. */
+type SendableEventFrom<TActor extends AnyActorRef> = Parameters<TActor['send']>[0];
+/** The event type an actor emits through `actor.on(...)`. */
+type EmittedEventFrom<TActor> = TActor extends EffectActor<infer TLogic> ? EmittedFrom<TLogic> : TActor extends Actor<infer TLogic> ? EmittedFrom<TLogic> : TActor extends ActorRef<any, any, infer TEmitted, any> ? TEmitted : AnyEventObject;
+/** Options for {@link waitFor}. */
+interface WaitForOptions {
+  /**
+   * Fails with `Cause.TimeoutError` when no snapshot satisfies the predicate
+   * within this duration.
+   */
+  readonly timeout: Duration.Input;
+}
+/**
+ * A narrowing snapshot predicate. Named so both of `waitFor`'s call styles
+ * describe the same predicate shape.
+ */
+type SnapshotPredicate<TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>> = (snapshot: SnapshotFrom<TActor>) => snapshot is TNarrowed;
+/**
+ * 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}.
+ */
+export declare const send: {
+  <TActor extends AnyActorRef>(event: SendableEventFrom<TActor>): (actor: TActor) => Effect.Effect<void>;
+  <TActor extends AnyActorRef>(actor: TActor, event: SendableEventFrom<TActor>): Effect.Effect<void>;
+};
+/**
+ * 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.
+ */
+export declare function snapshots<TActor extends AnyActorRef>(actor: TActor): Stream.Stream<SnapshotFrom<TActor>>;
+/**
+ * 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.
+ */
+export declare function emitted<TActor extends AnyActorRef>(actor: TActor): Stream.Stream<EmittedEventFrom<TActor>>;
+/**
+ * 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.
+ */
+export declare const waitFor: {
+  <TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>>(predicate: SnapshotPredicate<TActor, TNarrowed>): (actor: TActor) => Effect.Effect<TNarrowed, ActorStoppedError>;
+  <TActor extends AnyActorRef>(predicate: (snapshot: SnapshotFrom<TActor>) => boolean): (actor: TActor) => Effect.Effect<SnapshotFrom<TActor>, ActorStoppedError>;
+  <TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>>(predicate: SnapshotPredicate<TActor, TNarrowed>, options: WaitForOptions): (actor: TActor) => Effect.Effect<TNarrowed, ActorStoppedError | Cause.TimeoutError>;
+  <TActor extends AnyActorRef>(predicate: (snapshot: SnapshotFrom<TActor>) => boolean, options: WaitForOptions): (actor: TActor) => Effect.Effect<SnapshotFrom<TActor>, ActorStoppedError | Cause.TimeoutError>;
+  <TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>>(actor: TActor, predicate: SnapshotPredicate<TActor, TNarrowed>): Effect.Effect<TNarrowed, ActorStoppedError>;
+  <TActor extends AnyActorRef>(actor: TActor, predicate: (snapshot: SnapshotFrom<TActor>) => boolean): Effect.Effect<SnapshotFrom<TActor>, ActorStoppedError>;
+  <TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>>(actor: TActor, predicate: SnapshotPredicate<TActor, TNarrowed>, options: WaitForOptions): Effect.Effect<TNarrowed, ActorStoppedError | Cause.TimeoutError>;
+  <TActor extends AnyActorRef>(actor: TActor, predicate: (snapshot: SnapshotFrom<TActor>) => boolean, options: WaitForOptions): Effect.Effect<SnapshotFrom<TActor>, ActorStoppedError | Cause.TimeoutError>;
+};
+/**
+ * Joins an actor's final result, like `Fiber.join`: succeeds with its `output`
+ * when it is done, fails with `ActorFailedError` carrying `snapshot.error` when
+ * it errors, and fails with `ActorStoppedError` when it stops without output.
+ * Waits for a still-active actor to settle.
+ */
+export declare function join<TActor extends AnyActorRef>(actor: TActor): Effect.Effect<OutputFrom<TActor>, ActorFailedError<ErrorFrom$1<TActor>> | ActorStoppedError>;
+/**
+ * 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.
+ */
+export declare function inspect(actor: AnyActorRef): Stream.Stream<InspectionEvent>;
+/**
+ * Streams the events the actor's system could not deliver, as reported by
+ * `system.onRejectedEvent`: 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.
+ */
+export declare function deadLetters(actor: AnyActorRef): Stream.Stream<EventRejection>;
+/**
+ * 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.
+ */
+type EffectActionArgs<TContext extends MachineContext = MachineContext, TEvent extends EventObject = EventObject> = {
+  readonly context: TContext;
+  readonly event: TEvent;
+  readonly self: AnyActorRef;
+  readonly parent: AnyActorRef | undefined;
+  readonly children: Record<string, AnyActorRef | undefined>;
+  readonly actions: Record<string, unknown>;
+  readonly actors: Record<string, unknown>;
+  readonly guards: Record<string, unknown>;
+  readonly delays: Record<string, unknown>;
+  readonly system: SystemRuntime<SystemRegistry>;
+  readonly params?: unknown;
+  readonly output?: unknown;
+};
+/**
+ * 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`.
+ */
+type EffectAction<TContext extends MachineContext = MachineContext, TEvent extends EventObject = EventObject, TError = unknown, TRequirements = never> = (args: EffectActionArgs<TContext, TEvent>) => Effect.Effect<void, TError, TRequirements>;
+type AnyEffectAction = EffectAction<any, any, any, any>;
+type EffectActionRequirements<TAction> = TAction extends ((...args: any[]) => infer TResult) ? EffectRequirements<TResult> : never;
+type CoreEffectAction<TAction> = TAction extends ((...args: infer TArgs) => any) ? ((...args: TArgs) => void) & {
+  readonly [effectActionBrand]?: EffectActionRequirements<TAction>;
+} : never;
+type CoreEffectActionMap<TActionMap> = { [K in keyof TActionMap]: CoreEffectAction<TActionMap[K]>; };
+type EffectSetupConfig<TSchemas extends EffectSetupSchemas, TStates extends Record<string, EffectSetupStateSchema>, TActionMap extends Record<string, AnyEffectAction>, TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TValidator extends ActorLogicValidator | undefined, TSourceSchemas extends SetupSchemas = ToStandardSetupSchemas<TSchemas>> = {
+  validator?: TValidator;
+  actions?: TActionMap & Record<string, AnyEffectAction>;
+  actors?: TActorMap;
+  guards?: NonNullable<SetupConfig<TSourceSchemas, ToStandardSetupStates<TStates>, CoreEffectActionMap<TActionMap>, TActorMap, TGuardMap, TDelayMap, TValidator>['guards']>;
+  delays?: NonNullable<SetupConfig<TSourceSchemas, ToStandardSetupStates<TStates>, CoreEffectActionMap<TActionMap>, TActorMap, TGuardMap, TDelayMap, TValidator>['delays']>;
+  schemas?: TSchemas & ([TValidator] extends [ActorLogicValidator] ? ValidateEffectSetupSchemas<TSchemas> : unknown);
+  states?: TStates & ([TValidator] extends [ActorLogicValidator] ? ValidateEffectSetupStates<TStates> : unknown);
+};
+type MergeRecord<TBase, TExtension> = Omit<TBase, keyof TExtension> & TExtension;
+type MergeSetupSchemas<TBaseSchemas extends SetupSchemas, TExtensionSchemas extends SetupSchemas> = { [K in keyof TBaseSchemas | keyof TExtensionSchemas]: K extends 'events' | 'internalEvents' | 'emitted' | 'children' | 'actions' | 'guards' ? MergeRecord<K extends keyof TBaseSchemas ? NonNullable<TBaseSchemas[K]> : {}, K extends keyof TExtensionSchemas ? NonNullable<TExtensionSchemas[K]> : {}> : K extends keyof TExtensionSchemas ? TExtensionSchemas[K] : K extends keyof TBaseSchemas ? TBaseSchemas[K] : never; } extends (infer TMergedSchemas extends SetupSchemas) ? TMergedSchemas : never;
+interface RuntimeValidationDoesNotSupportTransformingSchemas {
+  readonly __xstate_effect_error: 'Runtime validation does not support schemas with different encoded and decoded types';
+}
+type RuntimeValidationCompatibility<TSchemas, TStates, TValidator> = [TValidator] extends [ActorLogicValidator] ? [TSchemas] extends [ValidateEffectSetupSchemas<TSchemas>] ? [TStates] extends [ValidateEffectSetupStates<TStates>] ? unknown : RuntimeValidationDoesNotSupportTransformingSchemas : RuntimeValidationDoesNotSupportTransformingSchemas : unknown;
+declare const inheritedEffectValidator: unique symbol;
+type InheritedEffectValidator = typeof inheritedEffectValidator;
+type ResolveExtendedValidator<TBase, TExtension> = [TExtension] extends [InheritedEffectValidator] ? TBase : Exclude<TExtension, InheritedEffectValidator>;
+type ExtendValidatorConfig<TExtension> = [TExtension] extends [InheritedEffectValidator] ? {
+  validator?: never;
+} : {
+  validator: TExtension;
+};
+type EffectSetupExtensionConfig<TBaseSchemas extends SetupSchemas, TBaseStates extends Record<string, SetupStateSchema>, TBaseValidator extends ActorLogicValidator | undefined, TExtensionSchemas extends EffectSetupSchemas, TExtensionStates extends Record<string, EffectSetupStateSchema>, TExtensionActionMap extends Record<string, AnyEffectAction>, TExtensionActorMap extends Sources['actors'], TExtensionGuardMap extends Sources['guards'], TExtensionDelayMap extends Sources['delays'], TExtensionValidator extends ActorLogicValidator | undefined | InheritedEffectValidator> = EffectSetupConfig<TExtensionSchemas, TExtensionStates, TExtensionActionMap, TExtensionActorMap, TExtensionGuardMap, TExtensionDelayMap, ResolveExtendedValidator<TBaseValidator, TExtensionValidator>, MergeSetupSchemas<TBaseSchemas, ToStandardSetupSchemas<TExtensionSchemas>>> & ExtendValidatorConfig<TExtensionValidator> & RuntimeValidationCompatibility<NoInfer<TBaseSchemas>, NoInfer<TBaseStates>, ResolveExtendedValidator<TBaseValidator, TExtensionValidator>>;
+/**
+ * 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`.
+ */
+type EffectSetupReturn<TStates extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>, TSchemas extends SetupSchemas = {}, TSetupActionMap extends Sources['actions'] = {}, TSetupActorMap extends Sources['actors'] = {}, TSetupGuardMap extends Sources['guards'] = {}, TSetupDelayMap extends Sources['delays'] = {}, TSetupDelays extends string = Extract<keyof TSetupDelayMap, string>, TValidator extends ActorLogicValidator | undefined = undefined> = Omit<SetupReturn<TStates, TSchemas, TSetupActionMap, TSetupActorMap, TSetupGuardMap, TSetupDelayMap, TSetupDelays, SystemRegistry, TValidator>, 'extend'> & {
+  extend<const TExtensionSchemas extends EffectSetupSchemas = {}, const TExtensionStates extends Record<string, EffectSetupStateSchema> = {}, TExtensionActionMap extends Record<string, AnyEffectAction> = {}, TExtensionActorMap extends Sources['actors'] = {}, TExtensionGuardMap extends Sources['guards'] = {}, TExtensionDelayMap extends Sources['delays'] = {}, const TExtensionValidator extends ActorLogicValidator | undefined | InheritedEffectValidator = InheritedEffectValidator>(config: EffectSetupExtensionConfig<TSchemas, TStates, TValidator, TExtensionSchemas, TExtensionStates, TExtensionActionMap, TExtensionActorMap, TExtensionGuardMap, TExtensionDelayMap, TExtensionValidator>): EffectSetupReturn<MergeRecord<TStates, ToStandardSetupStates<TExtensionStates>>, MergeSetupSchemas<TSchemas, ToStandardSetupSchemas<TExtensionSchemas>>, MergeRecord<TSetupActionMap, CoreEffectActionMap<TExtensionActionMap>>, MergeRecord<TSetupActorMap, TExtensionActorMap>, MergeRecord<TSetupGuardMap, TExtensionGuardMap>, MergeRecord<TSetupDelayMap, TExtensionDelayMap>, TSetupDelays | Extract<keyof TExtensionDelayMap, string>, ResolveExtendedValidator<TValidator, TExtensionValidator>>;
+};
+/**
+ * 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`.
+ */
+export declare function setupEffect(): EffectSetupReturn;
+export declare function setupEffect<const TSchemas extends EffectSetupSchemas = {}, const TStates extends Record<string, EffectSetupStateSchema> = Record<string, EffectSetupStateSchema>, TActionMap extends Record<string, AnyEffectAction> = {}, TActorMap extends Sources['actors'] = {}, TGuardMap extends Sources['guards'] = {}, TDelayMap extends Sources['delays'] = {}, const TValidator extends ActorLogicValidator | undefined = undefined>(config: EffectSetupConfig<TSchemas, TStates, TActionMap, TActorMap, TGuardMap, TDelayMap, TValidator>): EffectSetupReturn<ToStandardSetupStates<TStates>, ToStandardSetupSchemas<TSchemas>, CoreEffectActionMap<TActionMap>, TActorMap, TGuardMap, TDelayMap, Extract<keyof TDelayMap, string>, TValidator>;
+export { ActorFailedError, ActorScope, ActorStoppedError, type EffectAction, type EffectActionArgs, EffectActor, type EffectActorLogic, type EffectActorOptions, EffectInterruptedError, type EffectLogicBrand, type EffectSchema, type EffectSchemaLike, type EffectSetupReturn, type EffectSetupSchemas, type EffectSetupStateSchema, type EffectSnapshot, type EffectSource, type EffectSourceArgs, type EffectStreamActorLogic, type EffectStreamSnapshot, type EffectStreamSource, type EmittedEventFrom, type ErrorFrom, type RequirementsFrom, type SendableEventFrom, type StateTag, type TaggedState, type TaggedStateFrom, type WaitForOptions, createEffectActor, fromEffect, fromEffectEventStream, fromEffectStream, taggedState, withActorScope };