effect-machine 0.18.0 → 0.19.0

package/README.md

@@ -189,6 +189,53 @@ expect(result.states.map((s) => s._tag)).toEqual(["ReviewingCart", "ChargingCard
 
 `simulate` and `createTestHarness` test transition logic. They do not run `.spawn()` or `.background()` effects.
 
+## React, Solid, and Vue
+
+Use the Effect Atom adapter to connect one actor to any Effect Atom framework binding. The actor remains the state owner. Atom writes send typed events.
+
+```ts
+import { useAtomSet, useAtomValue } from "@effect/atom-react";
+import * as ActorAtom from "effect-machine/atom";
+
+const checkoutAtom = ActorAtom.make(actor);
+
+function CheckoutTotal() {
+  const totalCents = useAtomValue(checkoutAtom, (state) =>
+    "totalCents" in state ? state.totalCents : 0,
+  );
+  const send = useAtomSet(checkoutAtom);
+
+  return <button onClick={() => send(CheckoutEvent.Submit)}>Pay {totalCents}</button>;
+}
+```
+
+`useAtomValue` subscribes to the selected value. It does not render again when another state field changes. Use `ActorAtom.select` when you need a reusable selector or a custom equality function:
+
+```ts
+const totalAtom = ActorAtom.select(
+  checkoutAtom,
+  (state) => ("totalCents" in state ? { cents: state.totalCents } : { cents: 0 }),
+  (value, next) => value.cents === next.cents,
+);
+```
+
+The selected Atom stays writable. `useAtomSet(totalAtom)` still sends checkout events. Solid uses the same Atom with `@effect/atom-solid`. Vue uses the same Atom with `@effect/atom-vue`.
+
+Runnable React and Solid package examples are in `examples/react` and `examples/solid`.
+
+```bash
+bun run example:react
+bun run example:solid
+```
+
+Each example creates the actor through `Atom.make(Machine.scoped(...))`. React reads it with `useAtomSuspense`. Solid reads it with `useAtomResource` inside a Suspense boundary. The Atom scope owns actor cleanup.
+
+Each example has a framework performance test. The React test counts component renders. The Solid test counts reactive computations. Both tests prove that an unrelated selector does not update.
+
+The React example uses Motion `AnimatePresence`. The Solid example uses `solid-transition-group`. Both examples keep the old screen mounted for a 200 ms exit after the machine enters `Done`.
+
+The terminal `Done` state keeps the displayed `count` and `label`. The old screen stays valid without a local retained-value hook. Keep exit data in the terminal state or handle the terminal variant in the selector. Do not cache the last non-null selector value.
+
 ## Cluster
 
 When the same machine needs to run behind `@effect/cluster`, turn it into an entity:

package/dist/atom.d.ts

@@ -0,0 +1,31 @@
+import { ActorRef } from "./actor.js";
+import * as Atom from "effect/unstable/reactivity/Atom";
+//#region src/atom.d.ts
+/**
+ * A writable Atom projection of an actor.
+ *
+ * The Atom value is the current actor state. Atom writes send actor events.
+ */
+type ActorAtom<State, Event> = Atom.Writable<State, Event>;
+/**
+ * Make a writable Atom from an actor.
+ *
+ * The actor stays the single state owner. The Atom follows recovery,
+ * supervision restarts, and normal transitions through the actor's
+ * SubscriptionRef.
+ */
+declare const make: <State extends {
+  readonly _tag: string;
+}, Event>(actor: ActorRef<State, Event>) => ActorAtom<State, Event>;
+/**
+ * Select part of an actor state.
+ *
+ * The selected Atom stays writable. Writes still send events to the actor.
+ * The equality function controls when Atom subscribers receive a new value.
+ */
+declare const select: {
+  <State, Selection>(selector: (state: State) => Selection, equals?: (value: Selection, next: Selection) => boolean): <Event>(self: ActorAtom<State, Event>) => ActorAtom<Selection, Event>;
+  <State, Event, Selection>(self: ActorAtom<State, Event>, selector: (state: State) => Selection, equals?: (value: Selection, next: Selection) => boolean): ActorAtom<Selection, Event>;
+};
+//#endregion
+export { ActorAtom, make, select };

package/dist/atom.js

@@ -0,0 +1,29 @@
+import { dual } from "effect/Function";
+import * as Atom from "effect/unstable/reactivity/Atom";
+//#region src/atom.ts
+/**
+* Effect Atom integration for actors.
+*
+* The adapter keeps the actor as the state owner. Atom registries observe the
+* actor's SubscriptionRef and write events through its synchronous boundary.
+*/
+/**
+* Make a writable Atom from an actor.
+*
+* The actor stays the single state owner. The Atom follows recovery,
+* supervision restarts, and normal transitions through the actor's
+* SubscriptionRef.
+*/
+const make = (actor) => {
+	const state = Atom.subscriptionRef(actor.state);
+	return Atom.writable((get) => get(state), (_ctx, event) => actor.sync.send(event));
+};
+/**
+* Select part of an actor state.
+*
+* The selected Atom stays writable. Writes still send events to the actor.
+* The equality function controls when Atom subscribers receive a new value.
+*/
+const select = dual((args) => Atom.isAtom(args[0]), (self, selector, equals = Object.is) => Atom.withEquality(Atom.map(self, selector), equals));
+//#endregion
+export { make, select };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -21,6 +21,12 @@
         "types": "./dist/cluster/index.d.ts",
         "default": "./dist/cluster/index.js"
       }
+    },
+    "./atom": {
+      "import": {
+        "types": "./dist/atom.d.ts",
+        "default": "./dist/atom.js"
+      }
     }
   },
   "publishConfig": {
@@ -34,8 +40,11 @@
     "fmt:check": "oxfmt --check",
     "test": "bun test --tsconfig-override=tsconfig.json",
     "test:watch": "bun test --watch",
+    "example:react": "bun run --cwd examples/react dev",
+    "example:solid": "bun run --cwd examples/solid dev",
+    "examples:gate": "bun run --cwd examples/react gate && bun run --cwd examples/solid gate",
     "bench": "bun benchmark/core.ts",
-    "gate": "concurrently -n type,lint,fmt,test,build -c blue,yellow,magenta,green,cyan \"bun run typecheck\" \"bun run lint:fix\" \"bun run fmt\" \"bun run test\" \"bun run build\"",
+    "gate": "concurrently -n type,lint,fmt,test,build,examples -c blue,yellow,magenta,green,cyan,white \"bun run typecheck\" \"bun run lint:fix\" \"bun run fmt\" \"bun run test\" \"bun run build\" \"bun run examples:gate\"",
     "prepare": "lefthook install && effect-tsgo patch",
     "version": "changeset version",
     "build": "bun --bun tsdown",
@@ -44,17 +53,33 @@
   "devDependencies": {
     "@changesets/changelog-github": "1.0.0",
     "@changesets/cli": "3.0.1",
+    "@effect/atom-react": "4.0.0-rc.112",
+    "@effect/atom-solid": "4.0.0-rc.112",
     "@effect/tsgo": "0.38.0",
+    "@solidjs/testing-library": "0.8.10",
+    "@testing-library/react": "16.3.3",
     "@types/bun": "1.4.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitejs/plugin-react": "6.1.1",
     "concurrently": "10.0.5",
     "effect": "4.0.0-rc.112",
     "effect-bun-test": "0.3.0",
+    "jsdom": "30.0.1",
     "lefthook": "2.1.12",
+    "motion": "13.1.1",
     "oxfmt": "0.65.0",
     "oxlint": "1.80.0",
     "oxlint-plugin-effect": "0.11.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "solid-js": "1.9.15",
+    "solid-transition-group": "0.3.0",
     "tsdown": "0.22.14",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vite-plugin-solid": "2.11.14",
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "effect": ">=4.0.0-rc.112 <5"