Function setupArvoMachine

  • setupArvoMachine<TContext, TSelfContract, TServiceContracts, TActions, TGuards, TTag, TMeta>(param): {
        createMachine: (<const TConfig>(config: TConfig & {
            id: string;
            version?: TSelfContract["version"];
        }) => ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, StateMachine<TContext, {
            [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
        }[keyof TServiceContracts], {}, never, ToParameterizedObject<TActions & {
            enqueueArvoEvent: EnqueueArvoEventActionParam;
        }>, ToParameterizedObject<TGuards>, never, {} | {} | {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
            [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
        }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
            [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                | null
                | string
                | number
                | boolean>>
        }[keyof TServiceContracts], TMeta, any>>);
    }

  • Establishes the foundation for creating Arvo-compatible state machines.

    Designed for synchronous state machine orchestrations in Arvo's event-driven architecture. Builds upon XState with Arvo-specific constraints to enforce predictable state transitions.

    Type Parameters

    • TContext extends MachineContext
    • TSelfContract extends VersionedArvoContract<any, any>
    • TServiceContracts extends Record<string, VersionedArvoContract<any, any>>
    • TActions extends Record<string, NonReducibleUnknown> = {}
    • TGuards extends Record<string, NonReducibleUnknown> = {}
    • TTag extends string = string
    • TMeta extends MetaObject = MetaObject

    Parameters

    • param: {
          actions?: {
              [K in string | number | symbol]: ActionFunction<TContext, {
                  [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
              }[keyof TServiceContracts], {
                  [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
              }[keyof TServiceContracts], TActions[K], never, ToParameterizedObject<TActions>, ToParameterizedObject<TGuards>, never, {
                  [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                      | null
                      | string
                      | number
                      | boolean>>
              }[keyof TServiceContracts]>
          };
          contracts: {
              self: TSelfContract;
              services: TServiceContracts;
          };
          guards?: {
              [K in string | number | symbol]: ((args: {
                  context: TContext;
                  event: {
                      [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
                  }[keyof TServiceContracts];
              }, params: TGuards[K]) => boolean)
          };
          schemas?: unknown;
          types?: Omit<SetupTypes<TContext, {
              [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
          }[keyof TServiceContracts], {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
              [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
          }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
              [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                  | null
                  | string
                  | number
                  | boolean>>
          }[keyof TServiceContracts], TMeta>,
              | "output"
              | "emitted"
              | "input"
              | "children">;
      }
      • Optionalactions?: {
            [K in string | number | symbol]: ActionFunction<TContext, {
                [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
            }[keyof TServiceContracts], {
                [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
            }[keyof TServiceContracts], TActions[K], never, ToParameterizedObject<TActions>, ToParameterizedObject<TGuards>, never, {
                [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                    | null
                    | string
                    | number
                    | boolean>>
            }[keyof TServiceContracts]>
        }

        Named action implementations that can be referenced throughout the machine. Actions perform side effects like data transformations, context updates, and event emissions. Each action receives the current context and event, along with any parameters defined in its type.

        For more information, see xstate action docs

        Example

        actions: {
          updateUser: ({ context, event }, params) => {
            // Transform and update context
          },
          logEvent: ({ event }) => {
            // Log for debugging
          }
        }
      • contracts: {
            self: TSelfContract;
            services: TServiceContracts;
        }

        Contract definitions for the machine's event interface. Defines what events the machine accepts, emits, and exchanges with services.

        • self: TSelfContract

          Self contract defining the machine's initialization input structure and the completion output structure when the machine finishes execution.

        • services: TServiceContracts

          Service contracts defining the event interfaces for external services. Each service specifies the events it accepts and emits, enabling type-safe communication between the machine and its dependencies.

      • Optionalguards?: {
            [K in string | number | symbol]: ((args: {
                context: TContext;
                event: {
                    [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
                }[keyof TServiceContracts];
            }, params: TGuards[K]) => boolean)
        }

        Named guard implementations that control conditional state transitions. Guards are boolean functions that determine whether a transition should occur based on the current context and event. They enable dynamic flow control without side effects.

        For more information, see xstate guard docs

        Example

        guards: {
          isAuthorized: ({ context, event }, params) => {
            return context.user.role === 'admin';
          },
          hasRequiredData: ({ context }) => {
            return context.data !== null;
          }
        }
      • Optionalschemas?: unknown
      • Optionaltypes?: Omit<SetupTypes<TContext, {
            [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
        }[keyof TServiceContracts], {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
            [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
        }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
            [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                | null
                | string
                | number
                | boolean>>
        }[keyof TServiceContracts], TMeta>,
            | "output"
            | "emitted"
            | "input"
            | "children">

        Type definitions for the machine's internal structure. Specifies the shape of context and other variables used throughout the machine's lifecycle. These types enable full type inference and safety.

    Returns {
        createMachine: (<const TConfig>(config: TConfig & {
            id: string;
            version?: TSelfContract["version"];
        }) => ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, StateMachine<TContext, {
            [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
        }[keyof TServiceContracts], {}, never, ToParameterizedObject<TActions & {
            enqueueArvoEvent: EnqueueArvoEventActionParam;
        }>, ToParameterizedObject<TGuards>, never, {} | {} | {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
            [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
        }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
            [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                | null
                | string
                | number
                | boolean>>
        }[keyof TServiceContracts], TMeta, any>>);
    }

    • createMachine: (<const TConfig>(config: TConfig & {
          id: string;
          version?: TSelfContract["version"];
      }) => ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, StateMachine<TContext, {
          [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
      }[keyof TServiceContracts], {}, never, ToParameterizedObject<TActions & {
          enqueueArvoEvent: EnqueueArvoEventActionParam;
      }>, ToParameterizedObject<TGuards>, never, {} | {} | {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
          [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
      }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
          [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
              | null
              | string
              | number
              | boolean>>
      }[keyof TServiceContracts], TMeta, any>>)

      Creates an Arvo-compatible state machine with the specified configuration.

      Constructs a fully-typed state machine that orchestrates event-driven workflows using the contracts and types defined in setup. The machine enforces synchronous execution and validates configuration against Arvo constraints.

      For more information, see xstate state machine docs

      Returns

      A configured Arvo machine ready for execution

      Throws

      When configuration violates Arvo constraints (see setupArvoMachine docs)

      Example

      const machine = setup.createMachine({
        id: 'machineV100',
        initial: 'verifying',
        context: ({ input }) => ({
          userId: input.data.userId,
          verified: false
        }),
        states: {
          verifying: {
            on: {
              'com.user.verified': {
                target: 'active',
                actions: { type: 'updateUser' }
              }
            }
          },
          active: {
            type: 'final'
          }
        }
      });
        • <const TConfig>(config): ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, StateMachine<TContext, {
              [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
          }[keyof TServiceContracts], {}, never, ToParameterizedObject<TActions & {
              enqueueArvoEvent: EnqueueArvoEventActionParam;
          }>, ToParameterizedObject<TGuards>, never, {} | {} | {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
              [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
          }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
              [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                  | null
                  | string
                  | number
                  | boolean>>
          }[keyof TServiceContracts], TMeta, any>>

        • Creates an Arvo-compatible XState machine.

          Type Parameters

          • const TConfig extends Omit<StateNodeConfig<DoNotInfer<TContext>, DoNotInfer<{
                [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
            }[keyof TServiceContracts]>, never, DoNotInfer<ToParameterizedObject<TActions & {
                enqueueArvoEvent: EnqueueArvoEventActionParam;
            }>>, DoNotInfer<ToParameterizedObject<TGuards>>, never, DoNotInfer<TTag>, DoNotInfer<input<TSelfContract["emits"][`arvo.orc.${ExtractOrchestratorType<(...)>}.done`]> & {
                __id?: {
                    deduplication: (...) | (...);
                    value: string;
                };
            }>, DoNotInfer<{
                [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]>, (...)[(...)]["type"], Record<string,
                    | (...)
                    | (...)
                    | (...)
                    | (...)
                    | (...)>>
            }[keyof TServiceContracts]>, DoNotInfer<TMeta>>, "output"> & ({ version?: string | undefined; output?: (input<TSelfContract["emits"][`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]> & { ...; }) | Mapper<...> | undefined; } & ({ ...; } | { ...; }))

          Parameters

          Returns ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, StateMachine<TContext, {
              [K in string | number | symbol]: InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>
          }[keyof TServiceContracts], {}, never, ToParameterizedObject<TActions & {
              enqueueArvoEvent: EnqueueArvoEventActionParam;
          }>, ToParameterizedObject<TGuards>, never, {} | {} | {}, TTag, InferZodSchema<TSelfContract["accepts"]["schema"]>, {
              [K in string]: InferArvoEvent<ArvoEvent<InferZodSchema<(...)[(...)]>, Record<string, any>, K>>
          }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], {
              [K in string | number | symbol]: EnqueueArvoEventActionParam<input<(...)[(...)]["accepts"]["schema"]>, TServiceContracts[K]["accepts"]["type"], Record<string,
                  | null
                  | string
                  | number
                  | boolean>>
          }[keyof TServiceContracts], TMeta, any>>

    Throws

    When configuration violates Arvo constraints:

    • Using actors or delays (async behavior not supported)
    • Overriding reserved enqueueArvoEvent action name
    • Machine version mismatch with contract version
    • Using invoke or after in state configurations
    • Service contracts with duplicate URIs (multiple versions of same contract)
    • Circular dependency (self contract URI matches a service contract URI)

Settings

Member Visibility