xstate 6.0.0-alpha.7 → 6.0.0-alpha.71

package/dist/xstate-validation.cjs.d.mts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/validation/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLXZhbGlkYXRpb24uY2pzLmQubXRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL3ZhbGlkYXRpb24vaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/xstate-validation.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/validation/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLXZhbGlkYXRpb24uY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvdmFsaWRhdGlvbi9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

package/dist/xstate-validation.cjs.js

@@ -0,0 +1,330 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var createActor = require('./createActor-f4978450.cjs.js');
+
+const actorValidationErrorSymbol = Symbol.for('xstate.actorValidationError');
+
+/** @experimental */
+
+/** @experimental */
+
+/**
+ * A structured failure produced by `standardSchemaValidator()`.
+ *
+ * @experimental
+ */
+class ActorValidationError extends Error {
+  constructor(options) {
+    super(getMessage(options), {
+      cause: options.cause
+    });
+    this[actorValidationErrorSymbol] = true;
+    this.reason = void 0;
+    this.boundary = void 0;
+    this.logicId = void 0;
+    this.stateNodeId = void 0;
+    this.eventType = void 0;
+    this.eventOrigin = void 0;
+    this.childId = void 0;
+    this.issues = void 0;
+    this.cause = void 0;
+    this.name = 'ActorValidationError';
+    this.reason = options.reason;
+    this.boundary = options.boundary;
+    this.logicId = options.logicId;
+    this.stateNodeId = options.stateNodeId;
+    this.eventType = options.eventType;
+    this.eventOrigin = options.eventOrigin;
+    this.childId = options.childId;
+    this.issues = options.issues;
+    this.cause = options.cause;
+  }
+}
+
+/** @experimental */
+function isActorValidationError(value) {
+  return !!(value && typeof value === 'object' && actorValidationErrorSymbol in value);
+}
+
+/** @experimental */
+
+/**
+ * Creates a synchronous, assertion-only Standard Schema validator.
+ *
+ * @experimental
+ */
+function standardSchemaValidator(options = {}) {
+  const unknownEvents = options.unknownEvents ?? 'error';
+  const unknownEmitted = options.unknownEmitted ?? 'error';
+  const checkTarget = target => {
+    if (!target.schema) {
+      if (target.boundary === 'event' && unknownEvents === 'error') {
+        return createError(target, 'unknownEvent');
+      }
+      if (target.boundary === 'emitted' && unknownEmitted === 'error') {
+        return createError(target, 'unknownEmitted');
+      }
+      return undefined;
+    }
+    let result;
+    try {
+      result = target.schema['~standard'].validate(target.value);
+    } catch (cause) {
+      return createError(target, 'schemaThrew', undefined, cause);
+    }
+    if (isPromiseLike(result)) {
+      void Promise.resolve(result).catch(() => {});
+      return createError(target, 'asyncValidationUnsupported');
+    }
+    if (result.issues) {
+      return createError(target, 'invalid', result.issues);
+    }
+    return undefined;
+  };
+
+  // Event schemas describe the payload, so `type` is removed before
+  // validation. A schema that reports an issue at `type` declares the key
+  // itself (e.g. one reused from a discriminated union), so it is checked
+  // against the complete event instead.
+  const checkEventTarget = (target, event) => {
+    const error = checkTarget({
+      ...target,
+      value: getPayload(event)
+    });
+    return error?.issues?.some(isTypeIssue) ? checkTarget({
+      ...target,
+      value: event
+    }) : error;
+  };
+  const checkEvent = (logic, event, eventOrigin) => {
+    const schemas = getSchemas(logic);
+    if (event.type.startsWith('xstate.') || event.type.startsWith('@xstate.')) {
+      return undefined;
+    }
+    const eventSchemas = schemas?.events;
+    const internalEventSchemas = schemas?.internalEvents;
+    const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
+    if (!eventSchemas && !internalEventSchemas) {
+      return undefined;
+    }
+    return checkEventTarget({
+      schema,
+      boundary: 'event',
+      logicId: getLogicId(logic),
+      eventType: event.type,
+      eventOrigin
+    }, event);
+  };
+  const checkEmitted = (logic, effects) => {
+    const schemas = getSchemas(logic);
+    if (!schemas?.emitted) {
+      return undefined;
+    }
+    for (const effect of effects) {
+      if (effect.kind !== 'emit') {
+        continue;
+      }
+      const error = checkEventTarget({
+        schema: schemas.emitted[effect.event.type],
+        boundary: 'emitted',
+        logicId: getLogicId(logic),
+        eventType: effect.event.type
+      }, effect.event);
+      if (error) {
+        return error;
+      }
+    }
+    return undefined;
+  };
+  const checkMachineResult = (machine, snapshot) => {
+    let error = checkTarget({
+      schema: machine.schemas?.context,
+      value: snapshot.context,
+      boundary: 'context',
+      logicId: machine.id
+    });
+    if (error) {
+      return error;
+    }
+    for (const stateNode of snapshot.nodes) {
+      // the root state node reuses the machine-level `schemas` object, which is
+      // already validated above and elsewhere; those are not state-local
+      if (stateNode === machine.root) {
+        continue;
+      }
+      error = checkTarget({
+        schema: stateNode.schemas?.context,
+        value: snapshot.context,
+        boundary: 'state.context',
+        logicId: machine.id,
+        stateNodeId: stateNode.id
+      });
+      if (error) {
+        return error;
+      }
+      if (stateNode.schemas?.input) {
+        error = checkTarget({
+          schema: stateNode.schemas.input,
+          value: snapshot._stateInputs[stateNode.id],
+          boundary: 'state.input',
+          logicId: machine.id,
+          stateNodeId: stateNode.id
+        });
+        if (error) {
+          return error;
+        }
+      }
+    }
+    for (const childId of Object.keys(machine.schemas?.children ?? {})) {
+      const child = snapshot.children[childId];
+      if (child !== undefined) {
+        error = checkTarget({
+          schema: machine.schemas.children[childId],
+          value: child,
+          boundary: 'child',
+          logicId: machine.id,
+          childId
+        });
+        if (error) {
+          return error;
+        }
+      }
+    }
+    for (const timer of snapshot.timers) {
+      if (timer.type === '@xstate.raise') {
+        error = checkEvent(machine, timer.event, 'raised');
+        if (error) {
+          return error;
+        }
+      }
+    }
+    return undefined;
+  };
+  return {
+    check(request) {
+      const {
+        logic
+      } = request;
+      const schemas = getSchemas(logic);
+      if (request.kind === 'input') {
+        return checkTarget({
+          schema: schemas?.input,
+          value: request.input,
+          boundary: 'input',
+          logicId: getLogicId(logic)
+        });
+      }
+      if (request.kind === 'event') {
+        return checkEvent(logic, request.event, request.eventOrigin);
+      }
+      const {
+        snapshot,
+        effects
+      } = request;
+      if (isStateMachine(logic)) {
+        const error = checkMachineResult(logic, snapshot);
+        if (error) {
+          return error;
+        }
+      }
+      if (snapshot.status === 'done') {
+        const error = checkTarget({
+          schema: schemas?.output,
+          value: snapshot.output,
+          boundary: 'output',
+          logicId: getLogicId(logic)
+        });
+        if (error) {
+          return error;
+        }
+      }
+      return checkEmitted(logic, effects);
+    }
+  };
+}
+function createError(request, reason, issues, cause) {
+  return new ActorValidationError({
+    reason,
+    boundary: request.boundary,
+    ...(request.logicId === undefined ? {} : {
+      logicId: request.logicId
+    }),
+    ...(request.stateNodeId === undefined ? {} : {
+      stateNodeId: request.stateNodeId
+    }),
+    ...(request.eventType === undefined ? {} : {
+      eventType: request.eventType
+    }),
+    ...(request.eventOrigin === undefined ? {} : {
+      eventOrigin: request.eventOrigin
+    }),
+    ...(request.childId === undefined ? {} : {
+      childId: request.childId
+    }),
+    ...(issues === undefined ? {} : {
+      issues
+    }),
+    ...(cause === undefined ? {} : {
+      cause
+    })
+  });
+}
+function isStateMachine(logic) {
+  return 'root' in logic && 'schemas' in logic;
+}
+function getSchemas(logic) {
+  if (isStateMachine(logic)) {
+    return logic.schemas;
+  }
+  return logic.config?.schemas;
+}
+function findEventSchema(schemas, eventType) {
+  if (!schemas) {
+    return undefined;
+  }
+  if (Object.hasOwn(schemas, eventType)) {
+    return schemas[eventType];
+  }
+  const descriptor = Object.keys(schemas).find(key => createActor.matchesEventDescriptor(eventType, key));
+  return descriptor === undefined ? undefined : schemas[descriptor];
+}
+function getLogicId(logic) {
+  return 'id' in logic && typeof logic.id === 'string' ? logic.id : undefined;
+}
+function getPayload(event) {
+  const {
+    type: _,
+    ...payload
+  } = event;
+  return payload;
+}
+function isTypeIssue(issue) {
+  const segment = issue.path?.[0];
+  return (typeof segment === 'object' ? segment.key : segment) === 'type';
+}
+function getMessage(options) {
+  const subject = options.eventType !== undefined ? ` "${options.eventType}"` : options.childId !== undefined ? ` "${options.childId}"` : '';
+  switch (options.reason) {
+    case 'unknownEvent':
+      return `Unknown event${subject}`;
+    case 'unknownEmitted':
+      return `Unknown emitted event${subject}`;
+    case 'asyncValidationUnsupported':
+      return `Async schema validation is unsupported for ${options.boundary}${subject}`;
+    case 'transformationUnsupported':
+      return `Schema transformations are unsupported for ${options.boundary}${subject}`;
+    case 'schemaThrew':
+      return `Schema threw while validating ${options.boundary}${subject}`;
+    case 'invalid':
+      return `Invalid ${options.boundary}${subject}`;
+  }
+}
+function isPromiseLike(value) {
+  return !!value && typeof value.then === 'function';
+}
+
+exports.ActorValidationError = ActorValidationError;
+exports.isActorValidationError = isActorValidationError;
+exports.standardSchemaValidator = standardSchemaValidator;

package/dist/xstate-validation.cjs.mjs

@@ -0,0 +1,5 @@
+export {
+  ActorValidationError,
+  isActorValidationError,
+  standardSchemaValidator
+} from "./xstate-validation.cjs.js";

package/dist/xstate-validation.development.cjs.js

@@ -0,0 +1,330 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var createActor = require('./createActor-2136a8ad.development.cjs.js');
+
+const actorValidationErrorSymbol = Symbol.for('xstate.actorValidationError');
+
+/** @experimental */
+
+/** @experimental */
+
+/**
+ * A structured failure produced by `standardSchemaValidator()`.
+ *
+ * @experimental
+ */
+class ActorValidationError extends Error {
+  constructor(options) {
+    super(getMessage(options), {
+      cause: options.cause
+    });
+    this[actorValidationErrorSymbol] = true;
+    this.reason = void 0;
+    this.boundary = void 0;
+    this.logicId = void 0;
+    this.stateNodeId = void 0;
+    this.eventType = void 0;
+    this.eventOrigin = void 0;
+    this.childId = void 0;
+    this.issues = void 0;
+    this.cause = void 0;
+    this.name = 'ActorValidationError';
+    this.reason = options.reason;
+    this.boundary = options.boundary;
+    this.logicId = options.logicId;
+    this.stateNodeId = options.stateNodeId;
+    this.eventType = options.eventType;
+    this.eventOrigin = options.eventOrigin;
+    this.childId = options.childId;
+    this.issues = options.issues;
+    this.cause = options.cause;
+  }
+}
+
+/** @experimental */
+function isActorValidationError(value) {
+  return !!(value && typeof value === 'object' && actorValidationErrorSymbol in value);
+}
+
+/** @experimental */
+
+/**
+ * Creates a synchronous, assertion-only Standard Schema validator.
+ *
+ * @experimental
+ */
+function standardSchemaValidator(options = {}) {
+  const unknownEvents = options.unknownEvents ?? 'error';
+  const unknownEmitted = options.unknownEmitted ?? 'error';
+  const checkTarget = target => {
+    if (!target.schema) {
+      if (target.boundary === 'event' && unknownEvents === 'error') {
+        return createError(target, 'unknownEvent');
+      }
+      if (target.boundary === 'emitted' && unknownEmitted === 'error') {
+        return createError(target, 'unknownEmitted');
+      }
+      return undefined;
+    }
+    let result;
+    try {
+      result = target.schema['~standard'].validate(target.value);
+    } catch (cause) {
+      return createError(target, 'schemaThrew', undefined, cause);
+    }
+    if (isPromiseLike(result)) {
+      void Promise.resolve(result).catch(() => {});
+      return createError(target, 'asyncValidationUnsupported');
+    }
+    if (result.issues) {
+      return createError(target, 'invalid', result.issues);
+    }
+    return undefined;
+  };
+
+  // Event schemas describe the payload, so `type` is removed before
+  // validation. A schema that reports an issue at `type` declares the key
+  // itself (e.g. one reused from a discriminated union), so it is checked
+  // against the complete event instead.
+  const checkEventTarget = (target, event) => {
+    const error = checkTarget({
+      ...target,
+      value: getPayload(event)
+    });
+    return error?.issues?.some(isTypeIssue) ? checkTarget({
+      ...target,
+      value: event
+    }) : error;
+  };
+  const checkEvent = (logic, event, eventOrigin) => {
+    const schemas = getSchemas(logic);
+    if (event.type.startsWith('xstate.') || event.type.startsWith('@xstate.')) {
+      return undefined;
+    }
+    const eventSchemas = schemas?.events;
+    const internalEventSchemas = schemas?.internalEvents;
+    const schema = findEventSchema(internalEventSchemas, event.type) ?? findEventSchema(eventSchemas, event.type);
+    if (!eventSchemas && !internalEventSchemas) {
+      return undefined;
+    }
+    return checkEventTarget({
+      schema,
+      boundary: 'event',
+      logicId: getLogicId(logic),
+      eventType: event.type,
+      eventOrigin
+    }, event);
+  };
+  const checkEmitted = (logic, effects) => {
+    const schemas = getSchemas(logic);
+    if (!schemas?.emitted) {
+      return undefined;
+    }
+    for (const effect of effects) {
+      if (effect.kind !== 'emit') {
+        continue;
+      }
+      const error = checkEventTarget({
+        schema: schemas.emitted[effect.event.type],
+        boundary: 'emitted',
+        logicId: getLogicId(logic),
+        eventType: effect.event.type
+      }, effect.event);
+      if (error) {
+        return error;
+      }
+    }
+    return undefined;
+  };
+  const checkMachineResult = (machine, snapshot) => {
+    let error = checkTarget({
+      schema: machine.schemas?.context,
+      value: snapshot.context,
+      boundary: 'context',
+      logicId: machine.id
+    });
+    if (error) {
+      return error;
+    }
+    for (const stateNode of snapshot.nodes) {
+      // the root state node reuses the machine-level `schemas` object, which is
+      // already validated above and elsewhere; those are not state-local
+      if (stateNode === machine.root) {
+        continue;
+      }
+      error = checkTarget({
+        schema: stateNode.schemas?.context,
+        value: snapshot.context,
+        boundary: 'state.context',
+        logicId: machine.id,
+        stateNodeId: stateNode.id
+      });
+      if (error) {
+        return error;
+      }
+      if (stateNode.schemas?.input) {
+        error = checkTarget({
+          schema: stateNode.schemas.input,
+          value: snapshot._stateInputs[stateNode.id],
+          boundary: 'state.input',
+          logicId: machine.id,
+          stateNodeId: stateNode.id
+        });
+        if (error) {
+          return error;
+        }
+      }
+    }
+    for (const childId of Object.keys(machine.schemas?.children ?? {})) {
+      const child = snapshot.children[childId];
+      if (child !== undefined) {
+        error = checkTarget({
+          schema: machine.schemas.children[childId],
+          value: child,
+          boundary: 'child',
+          logicId: machine.id,
+          childId
+        });
+        if (error) {
+          return error;
+        }
+      }
+    }
+    for (const timer of snapshot.timers) {
+      if (timer.type === '@xstate.raise') {
+        error = checkEvent(machine, timer.event, 'raised');
+        if (error) {
+          return error;
+        }
+      }
+    }
+    return undefined;
+  };
+  return {
+    check(request) {
+      const {
+        logic
+      } = request;
+      const schemas = getSchemas(logic);
+      if (request.kind === 'input') {
+        return checkTarget({
+          schema: schemas?.input,
+          value: request.input,
+          boundary: 'input',
+          logicId: getLogicId(logic)
+        });
+      }
+      if (request.kind === 'event') {
+        return checkEvent(logic, request.event, request.eventOrigin);
+      }
+      const {
+        snapshot,
+        effects
+      } = request;
+      if (isStateMachine(logic)) {
+        const error = checkMachineResult(logic, snapshot);
+        if (error) {
+          return error;
+        }
+      }
+      if (snapshot.status === 'done') {
+        const error = checkTarget({
+          schema: schemas?.output,
+          value: snapshot.output,
+          boundary: 'output',
+          logicId: getLogicId(logic)
+        });
+        if (error) {
+          return error;
+        }
+      }
+      return checkEmitted(logic, effects);
+    }
+  };
+}
+function createError(request, reason, issues, cause) {
+  return new ActorValidationError({
+    reason,
+    boundary: request.boundary,
+    ...(request.logicId === undefined ? {} : {
+      logicId: request.logicId
+    }),
+    ...(request.stateNodeId === undefined ? {} : {
+      stateNodeId: request.stateNodeId
+    }),
+    ...(request.eventType === undefined ? {} : {
+      eventType: request.eventType
+    }),
+    ...(request.eventOrigin === undefined ? {} : {
+      eventOrigin: request.eventOrigin
+    }),
+    ...(request.childId === undefined ? {} : {
+      childId: request.childId
+    }),
+    ...(issues === undefined ? {} : {
+      issues
+    }),
+    ...(cause === undefined ? {} : {
+      cause
+    })
+  });
+}
+function isStateMachine(logic) {
+  return 'root' in logic && 'schemas' in logic;
+}
+function getSchemas(logic) {
+  if (isStateMachine(logic)) {
+    return logic.schemas;
+  }
+  return logic.config?.schemas;
+}
+function findEventSchema(schemas, eventType) {
+  if (!schemas) {
+    return undefined;
+  }
+  if (Object.hasOwn(schemas, eventType)) {
+    return schemas[eventType];
+  }
+  const descriptor = Object.keys(schemas).find(key => createActor.matchesEventDescriptor(eventType, key));
+  return descriptor === undefined ? undefined : schemas[descriptor];
+}
+function getLogicId(logic) {
+  return 'id' in logic && typeof logic.id === 'string' ? logic.id : undefined;
+}
+function getPayload(event) {
+  const {
+    type: _,
+    ...payload
+  } = event;
+  return payload;
+}
+function isTypeIssue(issue) {
+  const segment = issue.path?.[0];
+  return (typeof segment === 'object' ? segment.key : segment) === 'type';
+}
+function getMessage(options) {
+  const subject = options.eventType !== undefined ? ` "${options.eventType}"` : options.childId !== undefined ? ` "${options.childId}"` : '';
+  switch (options.reason) {
+    case 'unknownEvent':
+      return `Unknown event${subject}`;
+    case 'unknownEmitted':
+      return `Unknown emitted event${subject}`;
+    case 'asyncValidationUnsupported':
+      return `Async schema validation is unsupported for ${options.boundary}${subject}`;
+    case 'transformationUnsupported':
+      return `Schema transformations are unsupported for ${options.boundary}${subject}`;
+    case 'schemaThrew':
+      return `Schema threw while validating ${options.boundary}${subject}`;
+    case 'invalid':
+      return `Invalid ${options.boundary}${subject}`;
+  }
+}
+function isPromiseLike(value) {
+  return !!value && typeof value.then === 'function';
+}
+
+exports.ActorValidationError = ActorValidationError;
+exports.isActorValidationError = isActorValidationError;
+exports.standardSchemaValidator = standardSchemaValidator;

package/dist/xstate-validation.development.cjs.mjs

@@ -0,0 +1,5 @@
+export {
+  ActorValidationError,
+  isActorValidationError,
+  standardSchemaValidator
+} from "./xstate-validation.development.cjs.js";