@xstate/effect 0.1.0-alpha.2

package/dist/declarations/src/setupEffect.d.ts

@@ -0,0 +1,94 @@
+import { Effect } from 'effect';
+import { type ActorLogicValidator, type AnyActorRef, type EventObject, type MachineContext, type SetupConfig, type SetupReturn, type SetupSchemas, type SetupStateSchema, type Sources, type SystemRegistry, type SystemRuntime } from 'xstate';
+import { effectActionBrand } from "./brands.js";
+import type { EffectRequirements } from "./types.js";
+import { type EffectSetupSchemas, type EffectSetupStateSchema, type ToStandardSetupSchemas, type ToStandardSetupStates, type ValidateEffectSetupSchemas, type ValidateEffectSetupStates } from "./schema.js";
+/**
+ * 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.
+ */
+export 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`.
+ */
+export 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`.
+ */
+export 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 {};

package/dist/declarations/src/state.d.ts

@@ -0,0 +1,44 @@
+import type { AnyMachineSnapshot, AnyStateMachine, MachineContext, MachineSnapshot, SnapshotFrom, StateContextFromStateValue, StateSchema, StateValueFromStateSchema } from 'xstate';
+type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
+type Join<TPrefix extends string, TKey extends string> = TPrefix extends '' ? TKey : `${TPrefix}.${TKey}`;
+/** The tag of the machine itself, used when the root state is parallel. */
+declare 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.
+ */
+export type StateTag<TValue, TPrefix extends string = ''> = string extends TValue ? string : TValue extends string ? Join<TPrefix, TValue> : TValue extends object ? string extends keyof TValue ? string : IsUnion<keyof TValue & string> extends true ? TPrefix extends '' ? typeof MACHINE_TAG : TPrefix : {
+    [K in keyof TValue & string]: StateTag<TValue[K], Join<TPrefix, K>>;
+}[keyof TValue & string] : never;
+type TaggedStateOf<TSnapshot, TValue, TContext extends MachineContext, TSchema extends StateSchema> = TValue extends unknown ? {
+    readonly _tag: StateTag<TValue>;
+    readonly value: TValue;
+    readonly context: StateContextFromStateValue<TSchema, TContext, TValue>;
+    readonly snapshot: TSnapshot;
+} : never;
+/**
+ * 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.
+ */
+export type TaggedStateFrom<TSnapshot> = TSnapshot extends MachineSnapshot<infer TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TOutput, infer _TMeta, infer TSchema> ? TaggedStateOf<TSnapshot, StateValueFromStateSchema<TSchema>, TContext, TSchema> : never;
+/** The tagged state union of a machine. */
+export type TaggedState<TMachine extends AnyStateMachine> = TaggedStateFrom<SnapshotFrom<TMachine>>;
+/**
+ * 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));
+ * ```
+ */
+export declare function taggedState<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot): TaggedStateFrom<TSnapshot>;
+export {};

package/dist/declarations/src/types.d.ts

@@ -0,0 +1,52 @@
+import type { Effect } from 'effect';
+import type { EffectLogicBrand } from "./fromEffect.js";
+import { effectActionBrand } from "./brands.js";
+/** The `R` channel of an Effect type, or `never` for anything else. */
+export type EffectRequirements<T> = T extends Effect.Effect<any, any, infer R> ? R : never;
+type RequirementsFromActions<T> = T extends Record<string, (...args: any[]) => any> ? T[keyof T] extends infer TAction ? TAction extends {
+    readonly [effectActionBrand]?: infer R;
+} ? unknown extends R ? EffectRequirements<TAction extends (...args: any[]) => infer TResult ? TResult : never> : Exclude<R, undefined> : EffectRequirements<TAction extends (...args: any[]) => infer TResult ? TResult : never> : never : never;
+/**
+ * Recursion budget for walking registered child machines. A machine cannot
+ * contain itself as a registered actor type, but deeply nested machine trees
+ * are capped at this depth to keep the conditional type finite.
+ */
+type MaxDepth = 10;
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+type Depth = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+type RequirementsFromActors<T, TDepth extends Depth> = T extends Record<string, any> ? RequirementsFrom<T[keyof T], TDepth> : never;
+/** `invoke` accepts a single config or an array of them. */
+type InvokeEntry<TInvoke> = TInvoke extends readonly (infer U)[] ? U : TInvoke;
+/**
+ * Requirements of the logic passed inline as `invoke.src`. A string `src`
+ * names an actor registered in `setup({ actors })`, whose requirements are
+ * already collected from the actor map, so it contributes nothing here.
+ */
+type RequirementsFromInvoke<TInvoke, TDepth extends Depth> = InvokeEntry<TInvoke> extends infer TEntry ? TEntry extends {
+    src: infer TSrc;
+} ? TSrc extends string ? never : RequirementsFrom<TSrc, TDepth> : never : never;
+/**
+ * Walks the machine's literal config tree (the state schema) collecting
+ * requirements from inline `invoke.src` logic at the root and in every
+ * descendant state node.
+ */
+type RequirementsFromStateSchema<TSchema, TDepth extends Depth> = (TSchema extends {
+    invoke: infer TInvoke;
+} ? RequirementsFromInvoke<TInvoke, TDepth> : never) | (TSchema extends {
+    states: infer TStates;
+} ? TStates extends Record<string, any> ? RequirementsFromStateSchema<TStates[keyof TStates], TDepth> : never : never);
+/**
+ * Collects the Effect service requirements of an actor logic.
+ *
+ * For Effect logic this is the logic's own `R`. For a state machine it is the
+ * union of the requirements of its registered Effect actions, its registered
+ * Effect actors, the Effect logic passed inline as `invoke.src` anywhere in
+ * its state tree, and — recursively — the requirements of any child machine
+ * reached either way (capped at {@link MaxDepth} levels of machine nesting).
+ */
+export type RequirementsFrom<T, TDepth extends Depth = MaxDepth> = T extends EffectLogicBrand<any, infer R> ? R : T extends {
+    readonly _actionMap: infer TActionMap;
+    readonly _actorMap: infer TActorMap;
+    readonly _stateSchema: infer TStateSchema;
+} ? RequirementsFromActions<TActionMap> | ([TDepth] extends [0] ? never : RequirementsFromActors<TActorMap, PrevDepth[TDepth]> | RequirementsFromStateSchema<TStateSchema, PrevDepth[TDepth]>) : never;
+export {};