xstate 6.0.0-alpha.39 → 6.0.0-alpha.40

package/dist/{StateMachine-94084ac7.cjs.js → StateMachine-1464d5e4.cjs.js}

@@ -439,6 +439,10 @@ class StateMachine {
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    this.snapshotSchema = void 0;
+    /** Standard Schema for complete events accepted by this machine version. */
+    this.eventSchema = void 0;
     this.sources = void 0;
     /** Runtime options for machine execution. */
     this.options = void 0;
@@ -469,6 +473,134 @@ class StateMachine {
     };
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.snapshotSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected a persisted snapshot.'
+              }]
+            };
+          }
+          const snapshot = {
+            historyValue: {},
+            timers: {},
+            ...value
+          };
+          const contextSchema = this.schemas?.context;
+          let context = snapshot.context;
+          if (contextSchema) {
+            const result = await contextSchema['~standard'].validate(context);
+            if (result.issues) {
+              return {
+                issues: [{
+                  message: `Invalid context for machine '${this.id}' version '${this.version}': ${result.issues[0]?.message}`
+                }]
+              };
+            }
+            context = result.value;
+          }
+          for (const key of ['value', 'children']) {
+            if (!(key in snapshot)) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot is missing '${key}'.`
+                }]
+              };
+            }
+          }
+          if (!['active', 'done', 'error', 'stopped'].includes(snapshot.status)) {
+            return {
+              issues: [{
+                message: 'Persisted snapshot has invalid status.'
+              }]
+            };
+          }
+          for (const key of ['children', 'historyValue', 'timers']) {
+            if (snapshot[key] === null || typeof snapshot[key] !== 'object' || Array.isArray(snapshot[key])) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot has invalid '${key}'.`
+                }]
+              };
+            }
+          }
+          try {
+            this.resolveState({
+              value: snapshot.value,
+              context
+            });
+          } catch (error) {
+            return {
+              issues: [{
+                message: error instanceof Error ? error.message : 'Persisted snapshot has invalid state value.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...snapshot,
+              context
+            }
+          };
+        }
+      }
+    };
+    this.eventSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object' || typeof value.type !== 'string') {
+            return {
+              issues: [{
+                message: 'Expected an event object.'
+              }]
+            };
+          }
+          const event = value;
+          const eventSchemas = this.schemas?.events;
+          const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
+          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
+          if (eventSchemas && !schema && !isFrameworkEvent) {
+            return {
+              issues: [{
+                message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
+              }]
+            };
+          }
+          if (!schema) {
+            return {
+              value: event
+            };
+          }
+          const {
+            type,
+            ...payload
+          } = event;
+          const result = await schema['~standard'].validate(payload);
+          if (result.issues) {
+            return result;
+          }
+          if (result.value === null || typeof result.value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected an event payload.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...result.value,
+              type
+            }
+          };
+        }
+      }
+    };
     this.internalEventDescriptors = this.config.internalEvents ?? [];
     this.options = {
       maxIterations: Infinity,

package/dist/{StateMachine-2f47d890.esm.js → StateMachine-6082c3cf.esm.js}

@@ -437,6 +437,10 @@ class StateMachine {
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    this.snapshotSchema = void 0;
+    /** Standard Schema for complete events accepted by this machine version. */
+    this.eventSchema = void 0;
     this.sources = void 0;
     /** Runtime options for machine execution. */
     this.options = void 0;
@@ -467,6 +471,134 @@ class StateMachine {
     };
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.snapshotSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected a persisted snapshot.'
+              }]
+            };
+          }
+          const snapshot = {
+            historyValue: {},
+            timers: {},
+            ...value
+          };
+          const contextSchema = this.schemas?.context;
+          let context = snapshot.context;
+          if (contextSchema) {
+            const result = await contextSchema['~standard'].validate(context);
+            if (result.issues) {
+              return {
+                issues: [{
+                  message: `Invalid context for machine '${this.id}' version '${this.version}': ${result.issues[0]?.message}`
+                }]
+              };
+            }
+            context = result.value;
+          }
+          for (const key of ['value', 'children']) {
+            if (!(key in snapshot)) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot is missing '${key}'.`
+                }]
+              };
+            }
+          }
+          if (!['active', 'done', 'error', 'stopped'].includes(snapshot.status)) {
+            return {
+              issues: [{
+                message: 'Persisted snapshot has invalid status.'
+              }]
+            };
+          }
+          for (const key of ['children', 'historyValue', 'timers']) {
+            if (snapshot[key] === null || typeof snapshot[key] !== 'object' || Array.isArray(snapshot[key])) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot has invalid '${key}'.`
+                }]
+              };
+            }
+          }
+          try {
+            this.resolveState({
+              value: snapshot.value,
+              context
+            });
+          } catch (error) {
+            return {
+              issues: [{
+                message: error instanceof Error ? error.message : 'Persisted snapshot has invalid state value.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...snapshot,
+              context
+            }
+          };
+        }
+      }
+    };
+    this.eventSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object' || typeof value.type !== 'string') {
+            return {
+              issues: [{
+                message: 'Expected an event object.'
+              }]
+            };
+          }
+          const event = value;
+          const eventSchemas = this.schemas?.events;
+          const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
+          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
+          if (eventSchemas && !schema && !isFrameworkEvent) {
+            return {
+              issues: [{
+                message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
+              }]
+            };
+          }
+          if (!schema) {
+            return {
+              value: event
+            };
+          }
+          const {
+            type,
+            ...payload
+          } = event;
+          const result = await schema['~standard'].validate(payload);
+          if (result.issues) {
+            return result;
+          }
+          if (result.value === null || typeof result.value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected an event payload.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...result.value,
+              type
+            }
+          };
+        }
+      }
+    };
     this.internalEventDescriptors = this.config.internalEvents ?? [];
     this.options = {
       maxIterations: Infinity,

package/dist/{StateMachine-144215d2.development.cjs.js → StateMachine-76ee1d6e.development.cjs.js}

@@ -457,6 +457,10 @@ class StateMachine {
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    this.snapshotSchema = void 0;
+    /** Standard Schema for complete events accepted by this machine version. */
+    this.eventSchema = void 0;
     this.sources = void 0;
     /** Runtime options for machine execution. */
     this.options = void 0;
@@ -498,6 +502,134 @@ class StateMachine {
     }
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.snapshotSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected a persisted snapshot.'
+              }]
+            };
+          }
+          const snapshot = {
+            historyValue: {},
+            timers: {},
+            ...value
+          };
+          const contextSchema = this.schemas?.context;
+          let context = snapshot.context;
+          if (contextSchema) {
+            const result = await contextSchema['~standard'].validate(context);
+            if (result.issues) {
+              return {
+                issues: [{
+                  message: `Invalid context for machine '${this.id}' version '${this.version}': ${result.issues[0]?.message}`
+                }]
+              };
+            }
+            context = result.value;
+          }
+          for (const key of ['value', 'children']) {
+            if (!(key in snapshot)) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot is missing '${key}'.`
+                }]
+              };
+            }
+          }
+          if (!['active', 'done', 'error', 'stopped'].includes(snapshot.status)) {
+            return {
+              issues: [{
+                message: 'Persisted snapshot has invalid status.'
+              }]
+            };
+          }
+          for (const key of ['children', 'historyValue', 'timers']) {
+            if (snapshot[key] === null || typeof snapshot[key] !== 'object' || Array.isArray(snapshot[key])) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot has invalid '${key}'.`
+                }]
+              };
+            }
+          }
+          try {
+            this.resolveState({
+              value: snapshot.value,
+              context
+            });
+          } catch (error) {
+            return {
+              issues: [{
+                message: error instanceof Error ? error.message : 'Persisted snapshot has invalid state value.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...snapshot,
+              context
+            }
+          };
+        }
+      }
+    };
+    this.eventSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object' || typeof value.type !== 'string') {
+            return {
+              issues: [{
+                message: 'Expected an event object.'
+              }]
+            };
+          }
+          const event = value;
+          const eventSchemas = this.schemas?.events;
+          const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
+          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
+          if (eventSchemas && !schema && !isFrameworkEvent) {
+            return {
+              issues: [{
+                message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
+              }]
+            };
+          }
+          if (!schema) {
+            return {
+              value: event
+            };
+          }
+          const {
+            type,
+            ...payload
+          } = event;
+          const result = await schema['~standard'].validate(payload);
+          if (result.issues) {
+            return result;
+          }
+          if (result.value === null || typeof result.value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected an event payload.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...result.value,
+              type
+            }
+          };
+        }
+      }
+    };
     this.internalEventDescriptors = this.config.internalEvents ?? [];
     this.options = {
       maxIterations: Infinity,

package/dist/{StateMachine-da29dd2e.development.esm.js → StateMachine-f8c7feca.development.esm.js}

@@ -455,6 +455,10 @@ class StateMachine {
     /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    this.snapshotSchema = void 0;
+    /** Standard Schema for complete events accepted by this machine version. */
+    this.eventSchema = void 0;
     this.sources = void 0;
     /** Runtime options for machine execution. */
     this.options = void 0;
@@ -496,6 +500,134 @@ class StateMachine {
     }
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.snapshotSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected a persisted snapshot.'
+              }]
+            };
+          }
+          const snapshot = {
+            historyValue: {},
+            timers: {},
+            ...value
+          };
+          const contextSchema = this.schemas?.context;
+          let context = snapshot.context;
+          if (contextSchema) {
+            const result = await contextSchema['~standard'].validate(context);
+            if (result.issues) {
+              return {
+                issues: [{
+                  message: `Invalid context for machine '${this.id}' version '${this.version}': ${result.issues[0]?.message}`
+                }]
+              };
+            }
+            context = result.value;
+          }
+          for (const key of ['value', 'children']) {
+            if (!(key in snapshot)) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot is missing '${key}'.`
+                }]
+              };
+            }
+          }
+          if (!['active', 'done', 'error', 'stopped'].includes(snapshot.status)) {
+            return {
+              issues: [{
+                message: 'Persisted snapshot has invalid status.'
+              }]
+            };
+          }
+          for (const key of ['children', 'historyValue', 'timers']) {
+            if (snapshot[key] === null || typeof snapshot[key] !== 'object' || Array.isArray(snapshot[key])) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot has invalid '${key}'.`
+                }]
+              };
+            }
+          }
+          try {
+            this.resolveState({
+              value: snapshot.value,
+              context
+            });
+          } catch (error) {
+            return {
+              issues: [{
+                message: error instanceof Error ? error.message : 'Persisted snapshot has invalid state value.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...snapshot,
+              context
+            }
+          };
+        }
+      }
+    };
+    this.eventSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object' || typeof value.type !== 'string') {
+            return {
+              issues: [{
+                message: 'Expected an event object.'
+              }]
+            };
+          }
+          const event = value;
+          const eventSchemas = this.schemas?.events;
+          const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
+          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
+          if (eventSchemas && !schema && !isFrameworkEvent) {
+            return {
+              issues: [{
+                message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
+              }]
+            };
+          }
+          if (!schema) {
+            return {
+              value: event
+            };
+          }
+          const {
+            type,
+            ...payload
+          } = event;
+          const result = await schema['~standard'].validate(payload);
+          if (result.issues) {
+            return result;
+          }
+          if (result.value === null || typeof result.value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected an event payload.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...result.value,
+              type
+            }
+          };
+        }
+      }
+    };
     this.internalEventDescriptors = this.config.internalEvents ?? [];
     this.options = {
       maxIterations: Infinity,

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

@@ -5,6 +5,8 @@ import { AnyActorSystem } from "./system.js";
 import type { ActorLogic, ActorLogicTransitionResult, ActorScope, AnyActorLogic, AnyActorRef, AnyActorScope, AnyTransitionDefinition, Equals, EventDescriptor, EmittedFrom, EventObject, EventFromLogic, ExecutableActionObjectFromLogic, HistoryValue, InputFrom, IsAny, MachineContext, MetaObject, OutputFrom, Snapshot, SnapshotFrom, StateValue, StateSchema, SnapshotStatus } from "./types.js";
 import { AnyMachineSchemas, Sources, Next_MachineConfig, MachineOptions } from "./types.v6.js";
 import type { ActorLogicValidator } from "./validation.types.js";
+import type { StandardSchemaV1 } from "./schema.types.js";
+import type { PersistedMachineSnapshot } from "./machineVersion.types.js";
 type CompatibleProvidedActorSource<TExpected extends AnyActorLogic, TActual extends AnyActorLogic> = IsAny<TActual> extends true ? TActual : [OutputFrom<TActual>] extends [OutputFrom<TExpected>] ? [Omit<SnapshotFrom<TActual>, 'input'>] extends [
     Omit<SnapshotFrom<TExpected>, 'input'>
 ] ? [InputFrom<TExpected>] extends [InputFrom<TActual>] ? [EventFromLogic<TExpected>] extends [EventFromLogic<TActual>] ? [EmittedFrom<TActual>] extends [EmittedFrom<TExpected>] ? TActual : never : never : never : never : never;
@@ -21,6 +23,12 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     /** The machine's own version. */
     version?: string;
     schemas: AnyMachineSchemas | undefined;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    readonly snapshotSchema: StandardSchemaV1<unknown, Snapshot<unknown> & PersistedMachineSnapshot & {
+        context: TContext;
+    }>;
+    /** Standard Schema for complete events accepted by this machine version. */
+    readonly eventSchema: StandardSchemaV1<unknown, TEvent>;
     sources: Sources;
     /** Runtime options for machine execution. */
     options: MachineOptions;
@@ -47,7 +55,7 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
         actors?: TProvidedActorMap & ProvidedActors<TActorMap, TProvidedActorMap>;
         guards?: Partial<TGuardMap>;
         delays?: Partial<TDelayMap>;
-    }): StateMachine<TContext, TEvent, TChildren, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig, TActionMap, TActorMap, TGuardMap, TDelayMap>;
+    }): this;
     resolveState(config: {
         value: StateValue;
         context?: TContext;

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

@@ -1,6 +1,6 @@
 import { symbolObservable } from "./symbolObservable.js";
 import { AnyActorSystem, Clock } from "./system.js";
-import type { ActorTrigger, AnyActor, AnyActorLogic, EmittedFrom, EventFromLogic, SendableEventFromLogic, InputFrom, Snapshot, SnapshotFrom, Readable } from "./types.js";
+import type { ActorTrigger, AnyActor, AnyActorLogic, EmittedFrom, EventFromLogic, SendableEventFromLogic, InputFrom, PersistedSnapshotFor, Snapshot, SnapshotFrom, Readable } from "./types.js";
 import { ActorOptions, ActorInstance, ActorRef, InteropSubscribable, Observer, Subscription } from "./types.js";
 export declare const $$ACTOR_TYPE = 1;
 export declare enum ProcessingStatus {
@@ -172,7 +172,7 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstanc
      * Can be restored with {@link ActorOptions.state}
      * @see https://stately.ai/docs/persistence
      */
-    getPersistedSnapshot(): Snapshot<unknown>;
+    getPersistedSnapshot(): Snapshot<unknown> & PersistedSnapshotFor<TLogic>;
     [symbolObservable](): InteropSubscribable<SnapshotFrom<TLogic>>;
     /**
      * Read an actor’s snapshot synchronously.

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

@@ -7,7 +7,7 @@ export { createMachineFromConfig } from "./createMachineFromConfig.js";
 export type { ActionJSON, GuardJSON, InvokeJSON, MachineJSON, StateNodeJSON, TransitionJSON } from "./createMachineFromConfig.js";
 export { machineConfigToJSON, serializeMachine, type CodeExpression } from "./serialize.js";
 export { mapState } from "./mapState.js";
-export { machineVersions, type AdaptEventsOptions, type EventAdapterHandlers, type EventHistorySource, type MigrateSnapshotOptions, type MachineVersionsOptions, type ParsedPersistedSnapshot, type PersistedMachineIdentity, type PersistedSnapshotDataFrom, type PersistedSnapshotSource, type SnapshotMigrationHandlers, type PersistedSnapshotFrom } from "./machineVersions.js";
+export { machineVersions, type AdaptEventsOptions, type EventAdapterHandlers, type EventHistorySource, type MigrateSnapshotOptions, type MachineEventSchema, type MachineSnapshotSchema, type MachineVersionsOptions, type MachineVersionDescriptor, type ParsedPersistedSnapshot, type PersistedMachineIdentity, type PersistedMachineSnapshot, type PersistedSnapshotDataFrom, type PersistedSnapshotSource, type SnapshotMigrationHandlers, type PersistedSnapshotFrom } from "./machineVersions.js";
 export { types, isTypeSchema, type StandardSchemaV1, type TypeSchema } from "./schema.types.js";
 export type { ActorValidationBoundary, ActorValidationEventOrigin, ActorValidationRequest, ActorLogicValidator } from "./validation.types.js";
 export { createSystem, setup } from "./setup.js";

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

@@ -0,0 +1,37 @@
+import type { StandardSchemaV1 } from "./schema.types.js";
+import type { EventObject, Snapshot } from "./types.js";
+/** Durable machine snapshot fields that a historical snapshot schema describes. */
+export type PersistedMachineSnapshot = {
+    status: Snapshot<unknown>['status'];
+    output?: unknown;
+    error?: unknown;
+    value: unknown;
+    context: unknown;
+    children: Record<string, unknown>;
+    historyValue: Record<string, unknown>;
+    timers: Record<string, unknown>;
+    _nextActorId?: number;
+    _nextTimerId?: number;
+    stateInputs?: Record<string, Record<string, unknown>>;
+    machine?: {
+        id: string;
+        version: string;
+    };
+    version?: string;
+    [key: string]: unknown;
+};
+/** A Standard Schema for a complete persisted machine snapshot. */
+export type MachineSnapshotSchema = StandardSchemaV1<unknown, PersistedMachineSnapshot>;
+/** A Standard Schema for a complete persisted event object. */
+export type MachineEventSchema = StandardSchemaV1<unknown, EventObject>;
+/** Schema-backed capabilities for one machine version. */
+export type MachineVersionDescriptor = {
+    id: string;
+    version: string;
+} & ({
+    snapshotSchema: MachineSnapshotSchema;
+    eventSchema?: MachineEventSchema;
+} | {
+    snapshotSchema?: MachineSnapshotSchema;
+    eventSchema: MachineEventSchema;
+});