@xstate/effect 0.1.0-alpha.6 → 1.0.0-alpha.10

package/dist/xstate-effect-oxlint.js

@@ -0,0 +1,124 @@
+import { defineRule, definePlugin } from '@oxlint/plugins';
+
+const ENQUEUE_NAMES = new Set(['enq', 'enqueue']);
+const EFFECT_LOGIC_CONSTRUCTORS = new Set(['createEffectLogic', 'createEffectStreamLogic', 'createEffectEventStreamLogic']);
+const isNode = value => typeof value === 'object' && value !== null && 'type' in value && typeof value.type === 'string';
+const rootIdentifier = node => {
+  let current = node;
+  for (;;) {
+    if (current.type === 'CallExpression') {
+      current = current.callee;
+    } else if (current.type === 'MemberExpression') {
+      current = current.object;
+    } else if (current.type === 'Identifier') {
+      return current.name;
+    } else {
+      return undefined;
+    }
+  }
+};
+const returnedExpressions = fn => {
+  if (fn.body === null) {
+    return [];
+  }
+  if (fn.body.type !== 'BlockStatement') {
+    return [fn.body];
+  }
+  const found = [];
+  const visit = node => {
+    if (node.type === 'ReturnStatement') {
+      if (node.argument) {
+        found.push(node.argument);
+      }
+      return;
+    }
+    if (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression' || node.type === 'FunctionDeclaration') {
+      return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'parent') {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (isNode(item)) {
+            visit(item);
+          }
+        }
+      } else if (isNode(value)) {
+        visit(value);
+      }
+    }
+  };
+  visit(fn.body);
+  return found;
+};
+const isPromiseResolve = node => node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'Promise' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'resolve';
+const isEffectExpression = node => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  if (isPromiseResolve(node)) {
+    const [argument] = node.arguments;
+    return argument !== undefined && isEffectExpression(argument);
+  }
+  return rootIdentifier(node) === 'Effect';
+};
+const isInlineEffectLogic = node => node.type === 'CallExpression' && node.callee.type === 'Identifier' && EFFECT_LOGIC_CONSTRUCTORS.has(node.callee.name);
+const isFunctionNode = node => node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression';
+const noInlineEffect = defineRule({
+  create(context) {
+    return {
+      CallExpression(node) {
+        const {
+          callee
+        } = node;
+        if (callee.type === 'MemberExpression' && callee.object.type === 'Identifier' && ENQUEUE_NAMES.has(callee.object.name) && callee.property.type === 'Identifier' && callee.property.name === 'spawn') {
+          const [logic] = node.arguments;
+          if (logic !== undefined && isInlineEffectLogic(logic)) {
+            context.report({
+              messageId: 'inlineSpawn',
+              node: logic
+            });
+          }
+          return;
+        }
+        if (callee.type !== 'Identifier' || !ENQUEUE_NAMES.has(callee.name)) {
+          return;
+        }
+        const [action] = node.arguments;
+        if (action === undefined || !isFunctionNode(action)) {
+          return;
+        }
+        for (const expression of returnedExpressions(action)) {
+          if (isEffectExpression(expression)) {
+            context.report({
+              messageId: 'inlineAction',
+              node: expression
+            });
+          }
+        }
+      }
+    };
+  },
+  meta: {
+    docs: {
+      description: 'Disallow Effects in inline enqueue callbacks and inline Effect logic in enq.spawn; declare them in setupEffect({ actions }) or actors.'
+    },
+    messages: {
+      inlineAction: 'An Effect returned from an inline action is discarded. Declare it in setupEffect({ actions }) and run it with enq(args.actions.name, args).',
+      inlineSpawn: 'Inline Effect logic passed to enq.spawn is invisible to RequirementsFrom and rejected at runtime. Declare it in actors and spawn args.actors.name.'
+    },
+    type: 'problem'
+  }
+});
+var oxlint = definePlugin({
+  meta: {
+    name: 'xstate-effect'
+  },
+  rules: {
+    'no-inline-effect': noInlineEffect
+  }
+});
+
+export { oxlint as default };

package/dist/xstate-effect-test.d.ts

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

package/dist/xstate-effect-test.js

@@ -0,0 +1,11 @@
+/**
+ * Sends one mailbox item and awaits its macrostep publication and immediate
+ * effect scheduling. Ignored events are acknowledged too. Does not await
+ * invoked work, background actions or future timers. Interrupting the waiter
+ * detaches its receipt without retracting the event.
+ */
+function sendAndAwait(actor, event) {
+  return actor._sendAndAwait(event);
+}
+
+export { sendAndAwait };

package/dist/xstate-effect.js

@@ -1,13 +1,13 @@
-import { Schema, Effect, Stream, Exit, Cause, Queue } from 'effect';
-import { createLogic, setup } from 'xstate';
-import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-14a1fecf.js';
-export { d as ActorScope, A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState, w as withActorScope } from './state-14a1fecf.js';
+import { Schema, Effect, Stream, Cause, Exit, Queue, Data } from 'effect';
+import { createStepLogic, setup } from 'xstate';
+import { s as startHostedEffect, r as relayToParent, E as EffectFailure, A as ActorStoppedError, a as causeFromError, b as runHostedEffect } from './state-a3f54e06.js';
+export { e as ActorScope, A as ActorStoppedError, d as EffectActor, E as EffectFailure, g as EffectInterruptedError, f as EventRejectedError, c as createEffectActor, t as taggedState, w as withActorScope } from './state-a3f54e06.js';
 import { dual } from 'effect/Function';
 import 'xstate/durable';
 
 /**
- * An Effect `Schema` accepted by this package. `setupEffect`, `fromEffect`,
- * `fromEffectStream` and `fromEffectEventStream` convert it to a Standard
+ * An Effect `Schema` accepted by this package. `setupEffect`, `createEffectLogic`,
+ * `createEffectStreamLogic` and `createEffectEventStreamLogic` convert it to a Standard
  * Schema, so XState infers the decoded `Schema.Type` without an explicit call
  * to `Schema.toStandardSchemaV1`.
  */
@@ -74,7 +74,7 @@ function toStandardSetupStates(states) {
   }));
 }
 
-const EFFECT_INIT = '@xstate.init';
+const EFFECT_INIT = 'xstate.init';
 const EFFECT_RESOLVE = 'xstate.effect.resolve';
 const EFFECT_REJECT = 'xstate.effect.reject';
 const EFFECT_NEXT = 'xstate.effect.next';
@@ -82,18 +82,17 @@ const EFFECT_COMPLETE = 'xstate.effect.complete';
 const effectLogicBrand = Symbol.for('@xstate/effect/logic');
 
 /**
- * Type-level marker attached to logic created by `fromEffect`,
- * `fromEffectStream` and `fromEffectEventStream`. It carries the logic's
+ * Type-level marker attached to logic created by `createEffectLogic`,
+ * `createEffectStreamLogic` and `createEffectEventStreamLogic`. It carries the logic's
  * failure type and its Effect service requirements, which is how
  * `RequirementsFrom` collects the `R` channel of `createEffectActor` without
  * inspecting the logic at runtime.
  */
 
 /**
- * Snapshot of a `fromEffect` actor. The actor holds no context of its own: it
+ * Snapshot of a `createEffectLogic` actor. The actor holds no context of its own: it
  * is `active` while the Effect runs, `done` with the Effect's success value as
- * `output`, or `error` with the Effect's failure, defect or
- * `EffectInterruptedError` as `error`.
+ * `output`, or `error` with the original `Cause` wrapped in `EffectFailure` as `error`.
  */
 
 /**
@@ -104,40 +103,32 @@ const effectLogicBrand = Symbol.for('@xstate/effect/logic');
  */
 
 /**
- * What `fromEffect` accepts as its Effect: either an Effect value, or a
+ * What `createEffectLogic` accepts as its Effect: either an Effect value, or a
  * function of {@link EffectSourceArgs} returning one. The function form is
  * called once per actor start, so it sees that actor's input.
  */
 
 /**
- * Actor logic produced by `fromEffect` and `fromEffectEventStream`. It is
+ * Actor logic produced by `createEffectLogic` and `createEffectEventStreamLogic`. It is
  * ordinary XState actor logic carrying {@link EffectLogicBrand}, so a machine
  * can invoke or spawn it, and `createEffectActor` can collect its
  * requirements.
  */
 
 /**
- * Snapshot of a `fromEffectStream` actor. `context` holds the most recent
+ * Snapshot of a `createEffectStreamLogic` actor. `context` holds the most recent
  * stream item, or `undefined` before the first one. The actor reaches `done`
  * with no output when the stream completes, and `error` when it fails.
  */
 
 /**
- * Actor logic produced by `fromEffectStream`. Its snapshot is an
+ * Actor logic produced by `createEffectStreamLogic`. Its snapshot is an
  * {@link EffectStreamSnapshot}, so the parent reads the latest item from the
  * child's `context` rather than from events.
  */
 
-function toError(exit) {
-  if (Exit.isSuccess(exit)) {
-    return undefined;
-  }
-  if (Cause.hasInterruptsOnly(exit.cause)) {
-    return new EffectInterruptedError({
-      cause: exit.cause
-    });
-  }
-  return Cause.squash(exit.cause);
+function preserveFailure(error) {
+  return EffectFailure.is(error) ? error : new EffectFailure(Cause.die(error));
 }
 function createSourceArgs(input, self, system) {
   return {
@@ -150,6 +141,32 @@ function createSourceArgs(input, self, system) {
   };
 }
 function brandLogic(logic, error, requirements) {
+  const transition = logic.transition.bind(logic);
+  logic.transition = (snapshot, event, scope) => {
+    try {
+      return transition(snapshot, event, scope);
+    } catch (error) {
+      throw preserveFailure(error);
+    }
+  };
+  const initialTransition = logic.initialTransition.bind(logic);
+  logic.initialTransition = (input, scope) => {
+    try {
+      return initialTransition(input, scope);
+    } catch (error) {
+      throw preserveFailure(error);
+    }
+  };
+  const restoreSnapshot = logic.restoreSnapshot?.bind(logic);
+  if (restoreSnapshot) {
+    logic.restoreSnapshot = (persisted, scope) => {
+      const snapshot = restoreSnapshot(persisted, scope);
+      if (snapshot.status === 'error' && !EffectFailure.is(snapshot.error)) {
+        throw new Error('Cannot restore a serialized Effect failure. Recover the error before persisting the actor.');
+      }
+      return snapshot;
+    };
+  }
   Object.defineProperty(logic, effectLogicBrand, {
     configurable: false,
     enumerable: false,
@@ -163,9 +180,7 @@ function brandLogic(logic, error, requirements) {
 
 /**
  * Creates actor logic that runs an Effect. The actor completes with the
- * Effect's success value as its output and fails with the Effect's error, its
- * squashed defect, or an `EffectInterruptedError` when the Effect interrupts
- * itself. Stopping the actor interrupts the Effect without an error. Accepts
+ * Effect's success value as its output and fails with the original `Cause` wrapped in `EffectFailure`. Stopping the actor interrupts the Effect without an error. Accepts
  * an Effect, a function of {@link EffectSourceArgs} returning one, or a config
  * object with `id`, `schemas`, `validator` and `effect`. The logic must be run
  * under `createEffectActor`, which provides the Effect services it declares.
@@ -174,7 +189,7 @@ function brandLogic(logic, error, requirements) {
  * Effect actor stops.
  */
 
-function fromEffect(sourceOrConfig) {
+function createEffectLogic(sourceOrConfig) {
   const config = typeof sourceOrConfig === 'function' || Effect.isEffect(sourceOrConfig) ? {
     effect: sourceOrConfig
   } : sourceOrConfig;
@@ -187,7 +202,7 @@ function fromEffect(sourceOrConfig) {
       output: toStandardSchema(config.schemas.output)
     } : {})
   } : undefined;
-  const logic = createLogic({
+  const logic = createStepLogic({
     id: config.id,
     validator: config.validator,
     schemas,
@@ -208,15 +223,15 @@ function fromEffect(sourceOrConfig) {
       if (event.type === EFFECT_REJECT) {
         return {
           status: 'error',
-          error: event.error,
+          error: preserveFailure(event.error),
           input: undefined
         };
       }
       if (event.type !== EFFECT_INIT) {
         return;
       }
-      const effect = typeof source === 'function' ? source(createSourceArgs(input, self, system)) : source;
-      enq.effect(() => startHostedEffect(self, Effect.scoped(effect), 'fromEffect', exit => {
+      const effect = Effect.suspend(() => typeof source === 'function' ? source(createSourceArgs(input, self, system)) : source);
+      enq.effect(() => startHostedEffect(self, Effect.scoped(effect), 'createEffectLogic', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -228,7 +243,7 @@ function fromEffect(sourceOrConfig) {
         } else {
           self.send({
             type: EFFECT_REJECT,
-            error: toError(exit)
+            error: new EffectFailure(exit.cause)
           });
         }
       }));
@@ -238,7 +253,7 @@ function fromEffect(sourceOrConfig) {
 }
 
 /**
- * What `fromEffectStream` and `fromEffectEventStream` accept as their stream:
+ * What `createEffectStreamLogic` and `createEffectEventStreamLogic` accept as their stream:
  * either a Stream value, or a function of {@link EffectSourceArgs} returning
  * one. The function form is called once per actor start.
  */
@@ -263,10 +278,10 @@ function toLogicSchemas(schemas) {
  * completes, fails or is interrupted.
  */
 
-function fromEffectStream(sourceOrConfig) {
+function createEffectStreamLogic(sourceOrConfig) {
   const config = resolveStreamConfig(sourceOrConfig);
   const stream = config.stream;
-  const logic = createLogic({
+  const logic = createStepLogic({
     id: config.id,
     validator: config.validator,
     schemas: toLogicSchemas(config.schemas),
@@ -291,14 +306,14 @@ function fromEffectStream(sourceOrConfig) {
       if (event.type === EFFECT_REJECT) {
         return {
           status: 'error',
-          error: event.error,
+          error: preserveFailure(event.error),
           input: undefined
         };
       }
       if (event.type !== EFFECT_INIT) {
         return;
       }
-      const streamValue = typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream;
+      const streamValue = Stream.suspend(() => typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream);
       const consume = Stream.runForEach(streamValue, value => Effect.sync(() => {
         if (self.getSnapshot().status === 'active') {
           self.send({
@@ -307,7 +322,7 @@ function fromEffectStream(sourceOrConfig) {
           });
         }
       }));
-      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'fromEffectStream', exit => {
+      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'createEffectStreamLogic', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -318,7 +333,7 @@ function fromEffectStream(sourceOrConfig) {
         } else {
           self.send({
             type: EFFECT_REJECT,
-            error: toError(exit)
+            error: new EffectFailure(exit.cause)
           });
         }
       }));
@@ -331,14 +346,14 @@ function fromEffectStream(sourceOrConfig) {
  * Creates actor logic that runs a Stream of events and relays each item to the
  * parent machine as an event, the way `fromEventObservable` does. The actor
  * has no output: it reaches `done` when the stream completes and `error` when
- * it fails. Accepts the same forms as `fromEffectStream`. Its resources close
+ * it fails. Accepts the same forms as `createEffectStreamLogic`. Its resources close
  * when the stream completes, fails or is interrupted.
  */
 
-function fromEffectEventStream(sourceOrConfig) {
+function createEffectEventStreamLogic(sourceOrConfig) {
   const config = resolveStreamConfig(sourceOrConfig);
   const stream = config.stream;
-  const logic = createLogic({
+  const logic = createStepLogic({
     id: config.id,
     validator: config.validator,
     schemas: toLogicSchemas(config.schemas),
@@ -358,16 +373,16 @@ function fromEffectEventStream(sourceOrConfig) {
       if (event.type === EFFECT_REJECT) {
         return {
           status: 'error',
-          error: event.error,
+          error: preserveFailure(event.error),
           input: undefined
         };
       }
       if (event.type !== EFFECT_INIT) {
         return;
       }
-      const streamValue = typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream;
+      const streamValue = Stream.suspend(() => typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream);
       const consume = Stream.runForEach(streamValue, value => Effect.sync(() => relayToParent(self, value)));
-      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'fromEffectEventStream', exit => {
+      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'createEffectEventStreamLogic', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -378,7 +393,7 @@ function fromEffectEventStream(sourceOrConfig) {
         } else {
           self.send({
             type: EFFECT_REJECT,
-            error: toError(exit)
+            error: new EffectFailure(exit.cause)
           });
         }
       }));
@@ -549,9 +564,9 @@ const waitFor = dual(args => isActorRef(args[0]), (actor, predicate, options) =>
 
 /**
  * Joins an actor's final result, like `Fiber.join`: succeeds with its `output`
- * when it is done, fails with `snapshot.error` when it errors, and fails with
+ * when it is done, replays an Effect actor's original Cause when it errors, and fails with
  * `ActorStoppedError` when it stops without output. Waits for a still-active
- * actor to settle.
+ * actor to settle. Ordinary XState errors remain typed failures.
  */
 function join(actor) {
   return Effect.callback(resume => {
@@ -560,7 +575,7 @@ function join(actor) {
       if (snapshot.status === 'done') {
         resume(Effect.succeed(snapshot.output));
       } else if (snapshot.status === 'error') {
-        resume(Effect.fail(snapshot.error));
+        resume(Effect.failCause(causeFromError(snapshot.error)));
       } else {
         resume(Effect.fail(stoppedError(actor)));
       }
@@ -659,7 +674,12 @@ function wrapActions(actions) {
     const action = actions[key];
     wrapped[key] = args => {
       // machine.provide can replace Effect actions with plain actions.
-      const result = action(args);
+      let result;
+      try {
+        result = action(args);
+      } catch (error) {
+        result = Effect.die(error);
+      }
       return Effect.isEffect(result) ? runHostedEffect(args.self, result, `action.${key}`) : result;
     };
   }
@@ -710,4 +730,161 @@ function setupEffect(config = {}) {
   }));
 }
 
-export { deadLetters, emitted, fromEffect, fromEffectEventStream, fromEffectStream, inspect, join, send, setupEffect, snapshots, waitFor };
+/** A malformed transport, unsupported JSON value or missing persistence metadata. */
+class SnapshotCodecError extends Data.TaggedError('SnapshotCodecError') {
+  get message() {
+    return `${this.stage} at ${this.path}: ${this.reason}`;
+  }
+}
+function record(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function invalid(stage, path, reason) {
+  throw new SnapshotCodecError({
+    stage,
+    path,
+    reason
+  });
+}
+function checkJson(value, stage, path = '$', ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return;
+  if (typeof value !== 'object') invalid(stage, path, 'Expected lossless JSON; encode this value with a schema');
+  if (ancestors.has(value)) invalid(stage, path, 'Cyclic value');
+  if (Array.isArray(value) && Object.getPrototypeOf(value) !== Array.prototype) invalid(stage, path, 'Unsupported array prototype');
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    invalid(stage, path, 'Unsupported object prototype; supply a reversible schema');
+  }
+  if (Object.getOwnPropertySymbols(value).length) invalid(stage, path, 'Symbol properties are not JSON');
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) invalid(stage, path, 'Array holes or extra properties are not JSON');
+    for (let index = 0; index < value.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor?.enumerable || !('value' in descriptor)) invalid(stage, `${path}[${index}]`, 'Array accessor or hole is not JSON');
+      checkJson(descriptor.value, stage, `${path}[${index}]`, ancestors);
+    }
+    if (Object.getOwnPropertyNames(value).length !== value.length + 1) invalid(stage, path, 'Extra array properties are not JSON');
+  } else {
+    for (const key of Object.getOwnPropertyNames(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor.enumerable || !('value' in descriptor)) invalid(stage, `${path}.${key}`, 'Non-enumerable or accessor property is not JSON');
+      checkJson(descriptor.value, stage, `${path}.${key}`, ancestors);
+    }
+  }
+  ancestors.delete(value);
+}
+function checkSnapshot(value, stage, path = '$.snapshot', machineId) {
+  if (!record(value)) invalid(stage, path, 'Expected a persisted snapshot');
+  if (!['active', 'done', 'stopped', 'error'].includes(String(value.status))) invalid(stage, path, 'Invalid snapshot status');
+  if (value.status === 'error') invalid(stage, path, 'Errored snapshots require an explicit error recovery policy before persistence');
+  if (machineId !== undefined || 'machine' in value) {
+    if (!record(value.machine) || typeof value.machine.id !== 'string' || typeof value.machine.version !== 'string' || !value.machine.version) invalid(stage, `${path}.machine`, 'Expected a versioned machine identity');
+    if (machineId !== undefined && value.machine.id !== machineId) invalid(stage, `${path}.machine.id`, 'Machine identity mismatch');
+  }
+  if ('value' in value || 'machine' in value) {
+    for (const key of ['context', 'value', 'children', 'historyValue', 'timers']) {
+      if (!(key in value)) invalid(stage, `${path}.${key}`, 'Missing machine persistence metadata');
+    }
+    if (!record(value.children) || !record(value.historyValue) || !Array.isArray(value.timers)) invalid(stage, path, 'Invalid machine persistence metadata');
+  }
+  if (record(value.children)) {
+    for (const [id, child] of Object.entries(value.children)) {
+      if (!record(child) || child.src !== undefined && typeof child.src !== 'string') invalid(stage, `${path}.children.${id}`, 'Invalid persisted child');
+      if (child.remote === true) {
+        if (child.snapshot !== undefined) invalid(stage, `${path}.children.${id}`, 'Remote children cannot contain snapshots');
+        continue;
+      }
+      checkSnapshot(child.snapshot, stage, `${path}.children.${id}.snapshot`);
+    }
+  }
+}
+function sameData(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((item, index) => sameData(item, right[index]));
+  if (record(left) && record(right)) {
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && sameData(left[key], right[key]));
+  }
+  return false;
+}
+function checkMetadata(before, after, stage, path = '$.snapshot') {
+  for (const [key, value] of Object.entries(before)) {
+    if (['context', 'input', 'output', 'error', 'stateInputs'].includes(key) || value === undefined) continue;
+    if (key === 'children' && record(value) && record(after.children)) {
+      if (!sameData(Object.keys(value).sort(), Object.keys(after.children).sort())) invalid(stage, `${path}.children`, 'Schema changed persisted children');
+      for (const [id, child] of Object.entries(value)) {
+        const next = after.children[id];
+        if (!record(child) || !record(next)) invalid(stage, `${path}.children.${id}`, 'Schema changed child metadata');
+        for (const childKey of Object.keys(child)) {
+          if (childKey !== 'snapshot' && child[childKey] !== undefined && !sameData(child[childKey], next[childKey])) invalid(stage, `${path}.children.${id}.${childKey}`, 'Schema changed child metadata');
+        }
+        if (record(child.snapshot) && record(next.snapshot)) checkMetadata(child.snapshot, next.snapshot, stage, `${path}.children.${id}.snapshot`);
+      }
+    } else if (!sameData(value, after[key])) {
+      invalid(stage, `${path}.${key}`, 'Schema changed machine persistence metadata');
+    }
+  }
+  if (before.input !== undefined && !('input' in after)) invalid(stage, `${path}.input`, 'Schema removed input');
+  if (before.output !== undefined && !('output' in after)) invalid(stage, `${path}.output`, 'Schema removed output');
+  if (record(before.stateInputs) && (!record(after.stateInputs) || !sameData(Object.keys(before.stateInputs).sort(), Object.keys(after.stateInputs).sort()))) invalid(stage, `${path}.stateInputs`, 'Schema changed state input owners');
+  if ('stateInputs' in before && !('stateInputs' in after)) invalid(stage, `${path}.stateInputs`, 'Schema removed state inputs');
+}
+function checked(stage, run) {
+  return Effect.try({
+    try: run,
+    catch: error => error instanceof SnapshotCodecError ? error : new SnapshotCodecError({
+      stage,
+      path: '$',
+      reason: error instanceof Error ? error.message : String(error)
+    })
+  });
+}
+
+/**
+ * Binds a full bidirectional snapshot schema to a versioned machine. The schema
+ * owns rich values and supported historical versions. Decoding never migrates;
+ * restore or `machineVersions` remains responsible for migration.
+ */
+function createSnapshotCodec(machine, schema) {
+  const format = '@xstate/effect/snapshot';
+  return {
+    encode(snapshot) {
+      return Effect.gen(function* () {
+        yield* checked('encode', () => checkSnapshot(snapshot, 'encode', '$.snapshot', machine.id));
+        const encoded = yield* Schema.encodeUnknownEffect(schema)(snapshot);
+        return yield* checked('encode', () => {
+          checkJson(encoded, 'encode');
+          checkSnapshot(encoded, 'encode', '$.snapshot', machine.id);
+          checkMetadata(snapshot, encoded, 'encode');
+          return JSON.stringify({
+            format,
+            version: 1,
+            logicId: machine.id,
+            snapshot: encoded
+          });
+        });
+      });
+    },
+    decode(json) {
+      return Effect.gen(function* () {
+        const encoded = yield* checked('decode', () => {
+          const envelope = JSON.parse(json);
+          checkJson(envelope, 'decode');
+          if (!record(envelope) || envelope.format !== format || envelope.version !== 1) invalid('decode', '$', 'Unsupported snapshot format or version');
+          if (envelope.logicId !== machine.id) invalid('decode', '$.logicId', 'Machine identity mismatch');
+          checkSnapshot(envelope.snapshot, 'decode', '$.snapshot', machine.id);
+          return envelope.snapshot;
+        });
+        const snapshot = yield* Schema.decodeUnknownEffect(schema)(encoded);
+        yield* checked('decode', () => {
+          checkSnapshot(snapshot, 'decode', '$.snapshot', machine.id);
+          checkMetadata(encoded, snapshot, 'decode');
+        });
+        return snapshot;
+      });
+    }
+  };
+}
+
+export { SnapshotCodecError, createEffectEventStreamLogic, createEffectLogic, createEffectStreamLogic, createSnapshotCodec, deadLetters, emitted, inspect, join, send, setupEffect, snapshots, waitFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/effect",
-  "version": "0.1.0-alpha.6",
+  "version": "1.0.0-alpha.10",
   "type": "module",
   "description": "Effect integration for XState",
   "keywords": [
@@ -14,7 +14,9 @@
   "license": "MIT",
   "exports": {
     "./atom": "./dist/xstate-effect-atom.js",
+    "./test": "./dist/xstate-effect-test.js",
     ".": "./dist/xstate-effect.js",
+    "./oxlint": "./dist/xstate-effect-oxlint.js",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -29,18 +31,29 @@
     "url": "https://github.com/statelyai/xstate/issues"
   },
   "peerDependencies": {
+    "@oxlint/plugins": "^1.76.0",
     "effect": "^4.0.0",
-    "xstate": "^6.0.0-alpha.63"
+    "xstate": "^6.0.0-alpha.71"
   },
   "devDependencies": {
-    "effect": "4.0.0",
-    "xstate": "^6.0.0-alpha.63"
+    "@oxlint/plugins": "^1.76.0",
+    "effect": "4.0.6",
+    "fast-check": "4.10.2",
+    "@xstate/test": "^2.0.0-alpha.4",
+    "xstate": "^6.0.0-alpha.71"
   },
   "preconstruct": {
     "entrypoints": [
       "./index.ts",
-      "./atom.ts"
+      "./atom.ts",
+      "./oxlint.ts",
+      "./test.ts"
     ]
   },
+  "peerDependenciesMeta": {
+    "@oxlint/plugins": {
+      "optional": true
+    }
+  },
   "scripts": {}
 }