effect-machine 0.2.4 → 0.3.1

package/README.md

@@ -25,13 +25,13 @@ npm install effect-machine effect
 
 ```ts
 import { Effect, Schema } from "effect";
-import { Machine, State, Event, Slot } from "effect-machine";
+import { Machine, State, Event, Slot, type BuiltMachine } from "effect-machine";
 
 // Define state schema - states ARE schemas
 const OrderState = State({
   Pending: { orderId: Schema.String },
   Processing: { orderId: Schema.String },
-  Shipped: { trackingId: Schema.String },
+  Shipped: { orderId: Schema.String, trackingId: Schema.String },
   Cancelled: {},
 });
 
@@ -54,36 +54,36 @@ const orderMachine = Machine.make({
   effects: OrderEffects,
   initial: OrderState.Pending({ orderId: "order-1" }),
 })
-  .on(OrderState.Pending, OrderEvent.Process, ({ state }) =>
-    OrderState.Processing({ orderId: state.orderId }),
+  .on(OrderState.Pending, OrderEvent.Process, ({ state }) => OrderState.Processing.derive(state))
+  .on(OrderState.Processing, OrderEvent.Ship, ({ state, event }) =>
+    OrderState.Shipped.derive(state, { trackingId: event.trackingId }),
   )
-  .on(OrderState.Processing, OrderEvent.Ship, ({ event }) =>
-    OrderState.Shipped({ trackingId: event.trackingId }),
-  )
-  .on(OrderState.Pending, OrderEvent.Cancel, () => OrderState.Cancelled)
-  .on(OrderState.Processing, OrderEvent.Cancel, () => OrderState.Cancelled)
+  // Cancel from any state
+  .onAny(OrderEvent.Cancel, () => OrderState.Cancelled)
   // Effect runs when entering Processing, cancelled on exit
   .spawn(OrderState.Processing, ({ effects, state }) =>
     effects.notifyWarehouse({ orderId: state.orderId }),
   )
-  .provide({
-    notifyWarehouse: ({ orderId }) => Effect.log(`Warehouse notified: ${orderId}`),
-  })
   .final(OrderState.Shipped)
-  .final(OrderState.Cancelled);
+  .final(OrderState.Cancelled)
+  .build({
+    notifyWarehouse: ({ orderId }) => Effect.log(`Warehouse notified: ${orderId}`),
+  });
 
-// Run as actor (simple)
+// Run as actor (simple — no scope required)
 const program = Effect.gen(function* () {
   const actor = yield* Machine.spawn(orderMachine);
 
   yield* actor.send(OrderEvent.Process);
   yield* actor.send(OrderEvent.Ship({ trackingId: "TRACK-123" }));
 
-  const state = yield* actor.snapshot;
-  console.log(state); // Shipped { trackingId: "TRACK-123" }
+  const state = yield* actor.waitFor(OrderState.Shipped);
+  console.log(state); // Shipped { orderId: "order-1", trackingId: "TRACK-123" }
+
+  yield* actor.stop;
 });
 
-Effect.runPromise(Effect.scoped(program));
+Effect.runPromise(program);
 ```
 
 ## Core Concepts
@@ -102,6 +102,34 @@ MyState.Idle; // Value (no parens)
 MyState.Loading({ url: "/api" }); // Constructor
 ```
 
+### State.derive()
+
+Construct new states from existing ones — picks overlapping fields, applies overrides:
+
+```ts
+// Same-state: preserve fields, override specific ones
+.on(State.Active, Event.Update, ({ state, event }) =>
+  State.Active.derive(state, { count: event.count })
+)
+
+// Cross-state: picks only target fields from source
+.on(State.Processing, Event.Ship, ({ state, event }) =>
+  State.Shipped.derive(state, { trackingId: event.trackingId })
+)
+```
+
+### Multi-State Transitions
+
+Handle the same event from multiple states:
+
+```ts
+// Array of states — handler receives union type
+.on([State.Draft, State.Review], Event.Cancel, () => State.Cancelled)
+
+// Wildcard — fires from any state (specific .on() takes priority)
+.onAny(Event.Cancel, () => State.Cancelled)
+```
+
 ### Guards and Effects as Slots
 
 Define parameterized guards and effects, provide implementations:
@@ -126,7 +154,7 @@ machine
   )
   // Fetch runs when entering Loading, auto-cancelled if state changes
   .spawn(MyState.Loading, ({ effects, state }) => effects.fetchData({ url: state.url }))
-  .provide({
+  .build({
     canRetry: ({ max }, { state }) => state.attempts < max,
     fetchData: ({ url }, { self }) =>
       Effect.gen(function* () {
@@ -189,49 +217,62 @@ See the [primer](./primer/) for comprehensive documentation:
 
 ### Building
 
-| Method                                    | Purpose                      |
-| ----------------------------------------- | ---------------------------- |
-| `Machine.make({ state, event, initial })` | Create machine               |
-| `.on(State.X, Event.Y, handler)`          | Add transition               |
-| `.reenter(State.X, Event.Y, handler)`     | Force re-entry on same state |
-| `.spawn(State.X, handler)`                | State-scoped effect          |
-| `.task(State.X, run, { onSuccess })`      | State-scoped task            |
-| `.background(handler)`                    | Machine-lifetime effect      |
-| `.provide({ slot: impl })`                | Provide implementations      |
-| `.final(State.X)`                         | Mark final state             |
-| `.persist(config)`                        | Enable persistence           |
+| Method                                    | Purpose                                                     |
+| ----------------------------------------- | ----------------------------------------------------------- |
+| `Machine.make({ state, event, initial })` | Create machine                                              |
+| `.on(State.X, Event.Y, handler)`          | Add transition                                              |
+| `.on([State.X, State.Y], Event.Z, h)`     | Multi-state transition                                      |
+| `.onAny(Event.X, handler)`                | Wildcard transition (any state)                             |
+| `.reenter(State.X, Event.Y, handler)`     | Force re-entry on same state                                |
+| `.spawn(State.X, handler)`                | State-scoped effect                                         |
+| `.task(State.X, run, { onSuccess })`      | State-scoped task                                           |
+| `.background(handler)`                    | Machine-lifetime effect                                     |
+| `.final(State.X)`                         | Mark final state                                            |
+| `.build({ slot: impl })`                  | Provide implementations, returns `BuiltMachine` (terminal)  |
+| `.build()`                                | Finalize no-slot machine, returns `BuiltMachine` (terminal) |
+| `.persist(config)`                        | Enable persistence                                          |
+
+### State Constructors
+
+| Method                                 | Purpose                        |
+| -------------------------------------- | ------------------------------ |
+| `State.X.derive(source)`               | Pick target fields from source |
+| `State.X.derive(source, { field: v })` | Pick fields + apply overrides  |
+| `State.$is("X")(value)`                | Type guard                     |
+| `State.$match(value, { X: fn, ... })`  | Pattern matching               |
 
 ### Running
 
-| Method                       | Purpose                                  |
-| ---------------------------- | ---------------------------------------- |
-| `Machine.spawn(machine)`     | Spawn actor (simple, no registry)        |
-| `Machine.spawn(machine, id)` | Spawn actor with custom ID               |
-| `system.spawn(id, machine)`  | Spawn via ActorSystem (registry/persist) |
+| Method                       | Purpose                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Machine.spawn(machine)`     | Single actor, no registry. Caller manages lifetime via `actor.stop`. Auto-cleans up if `Scope` present. |
+| `Machine.spawn(machine, id)` | Same as above with custom ID                                                                            |
+| `system.spawn(id, machine)`  | Registry, lookup by ID, bulk ops, persistence. Cleans up on system teardown.                            |
 
 ### Testing
 
-| Function                                   | Description                |
-| ------------------------------------------ | -------------------------- |
-| `simulate(machine, events)`                | Run events, get all states |
-| `createTestHarness(machine)`               | Step-by-step testing       |
-| `assertPath(machine, events, path)`        | Assert exact path          |
-| `assertReaches(machine, events, tag)`      | Assert final state         |
-| `assertNeverReaches(machine, events, tag)` | Assert state never visited |
+| Function                                   | Description                                                      |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `simulate(machine, events)`                | Run events, get all states (accepts `Machine` or `BuiltMachine`) |
+| `createTestHarness(machine)`               | Step-by-step testing (accepts `Machine` or `BuiltMachine`)       |
+| `assertPath(machine, events, path)`        | Assert exact path                                                |
+| `assertReaches(machine, events, tag)`      | Assert final state                                               |
+| `assertNeverReaches(machine, events, tag)` | Assert state never visited                                       |
 
 ### Actor
 
-| Method                | Description       |
-| --------------------- | ----------------- |
-| `actor.send(event)`   | Queue event       |
-| `actor.snapshot`      | Get current state |
-| `actor.matches(tag)`  | Check state tag   |
-| `actor.can(event)`    | Can handle event? |
-| `actor.changes`       | Stream of changes |
-| `actor.waitFor(fn)`   | Wait for match    |
-| `actor.awaitFinal`    | Wait final state  |
-| `actor.sendAndWait`   | Send + wait       |
-| `actor.subscribe(fn)` | Sync callback     |
+| Method                           | Description                        |
+| -------------------------------- | ---------------------------------- |
+| `actor.send(event)`              | Queue event                        |
+| `actor.sendSync(event)`          | Fire-and-forget (sync, for UI)     |
+| `actor.snapshot`                 | Get current state                  |
+| `actor.matches(tag)`             | Check state tag                    |
+| `actor.can(event)`               | Can handle event?                  |
+| `actor.changes`                  | Stream of changes                  |
+| `actor.waitFor(State.X)`         | Wait for state (constructor or fn) |
+| `actor.awaitFinal`               | Wait final state                   |
+| `actor.sendAndWait(ev, State.X)` | Send + wait for state              |
+| `actor.subscribe(fn)`            | Sync callback                      |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -25,7 +25,7 @@
     "fmt:check": "oxfmt --check",
     "test": "bun test",
     "test:watch": "bun test --watch",
-    "gate": "concurrently -n type,lint,fmt,test -c blue,yellow,magenta,green \"bun run typecheck\" \"bun run lint\" \"bun run fmt\" \"bun run test\"",
+    "gate": "concurrently -n type,lint,fmt,test -c blue,yellow,magenta,green \"bun run typecheck\" \"bun run lint:fix\" \"bun run fmt\" \"bun run test\"",
     "prepare": "lefthook install || true && effect-language-service patch",
     "version": "changeset version",
     "release": "changeset publish"