@typeonce/effect-machine 0.17.0 → 0.19.0

package/README.md

@@ -34,7 +34,7 @@ Cluster and are exposed only through explicit integration boundaries.
 ## Install
 
 ```sh
-pnpm add @typeonce/effect-machine effect@4.0.0-rc.109
+pnpm add @typeonce/effect-machine effect@4.0.0-rc.110
 ```
 
 `effect` is an exact peer dependency. Install the version above and upgrade it
@@ -49,11 +49,14 @@ import { Machine } from "@typeonce/effect-machine"
 import { Effect, Schema, Stream } from "effect"
 
 const State = Schema.TaggedUnion({
-  Idle: {},
   Running: { count: Schema.Number }
 })
 
-const States = Machine.states(State.cases)
+const States = Machine.states({
+  Idle: {},
+  Running: State.cases.Running
+})
+
 const CounterEvent = Machine.events(
   Schema.TaggedUnion({
     Start: {},
@@ -66,7 +69,7 @@ const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
   events: CounterEvent,
-  initial: (to) => to.Idle().resolve(({ target }) => target.from())
+  initial: (to) => to.Idle()
 })
 
 const Counter = CounterDefinition.handle({
@@ -78,7 +81,7 @@ const Counter = CounterDefinition.handle({
   Running: {
     on: {
       Increment: (to) => to.full.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
-      Stop: (to) => to.full.Idle().resolve(({ target }) => target.from())
+      Stop: (to) => to.full.Idle()
     }
   }
 })
@@ -122,7 +125,27 @@ Keep one-off topology inline in `Machine.states`. Use `Machine.state` only when
 the same active state definition is mounted more than once; tagged schemas are
 already reusable without it. For repeated finite regions, derive names with
 `States.path(...)` so every literal in the path family is checked against the
-complete tree. Type full-snapshot helpers as `Machine.Snapshot<typeof States>`.
+complete tree. Type full-snapshot helpers as `Machine.Snapshot<typeof States>`
+or `Machine.Snapshot<typeof machine>`, schema-backed state payloads as
+`Machine.Value<typeof States, Path>`, and path-rooted snapshots as
+`Machine.SnapshotAt<typeof States, Path>`.
+
+### Make invalid states unrepresentable
+
+Treat topology as a domain contract, not as file organization. A parallel state
+declares the full Cartesian product of its regions, so use it only when every
+combination has a coherent meaning. If one region must inspect another before
+entering a state safely, prefer a compound hierarchy that makes the forbidden
+combination impossible. `matches` remains useful for views, tests, and genuine
+coordination between independent regions; it should not repair an invalid
+state product.
+
+Keep state-scoped Effects beneath the state that guarantees their resources,
+and enforce command availability in the machine rather than only by disabling
+UI controls. When entering an inactive compound or parallel state's declared
+default, select `.initial`; explicitly construct descendants only for a
+non-default configuration or a complete replacement of an already-active
+parallel root.
 
 ### Construct state through builders
 
@@ -150,7 +173,8 @@ const handlers = {
 }
 ```
 
-Omit `schema` when a state represents control flow but owns no data:
+Omit `schema` when a state represents control flow but owns no data. Use `{}`
+instead of defining an empty tagged schema:
 
 ```ts
 const States = Machine.states({
@@ -175,6 +199,11 @@ Schema-less states remain active, targetable, matchable, and visible through
 their handler `state` is `undefined`, and `get` / `getWithParents` accept only
 schema-backed paths. Add a schema later if the state starts owning data.
 
+Keep data-bearing state schemas together in a named `Schema.TaggedUnion` and
+reference its cases from the topology. For a standalone state schema whose
+class identity is useful, declare a named `Schema.TaggedClass`. Do not bury
+one-off tagged schema declarations inside `Machine.states`.
+
 Put data on the narrowest state where it is valid. If sibling phases share
 data, put it on their compound parent.
 
@@ -206,7 +235,7 @@ const definition = Machine.make({
   events: CommandEvent,
   internalEvents: InternalEvent,
   emittedEvents: Emissions,
-  initial: (to) => to.Idle().resolve(({ target }) => target.from())
+  initial: (to) => to.Idle()
 })
 ```
 
@@ -318,7 +347,7 @@ const child = Machine.make({
   states: ChildStates.states,
   events: ChildEvents,
   parent: Machine.parent(ParentEvents),
-  initial: (to) => to.Working().resolve(({ target }) => target.from())
+  initial: (to) => to.Working()
 }).handle({
   Working: {
     on: {
@@ -369,9 +398,13 @@ paths. `parent` always means the owning machine target.
 | `target.history` | Restoring a declared history node        | The remembered configuration or its typed default |
 
 Every required transition handler selects a target from its inline `to`
-builder. A bare selection uses the target schema's default construction; call
-`.resolve(...)` when construction depends on handler context. An absent handler
-ignores the trigger; `to.none` handles
+builder. Return a bare selection such as `to.full.Idle()` when the selected
+builder supports zero-argument construction; the machine applies the same
+default construction as `target.from()`. This includes empty schemas and
+schemas whose constructor fields are all optional or defaulted. TypeScript
+rejects the bare form when state data or nested configuration is required.
+Call `.resolve(...)` when construction depends on handler context or the
+transition needs to enqueue commands. An absent handler ignores the trigger; `to.none` handles
 it and retains queued commands, raised events, and emitted events without
 selecting a destination. Concrete destinations stay narrowed inside their
 resolver, and `to.branches({...})` gives the resolver only the declared named
@@ -437,37 +470,35 @@ arbitrary asynchronous Effects do not run inside planning.
 State-scoped work starts on entry and is interrupted on exit:
 
 ```ts
-Loading: {
-  invoke: Machine.invoke({
-    id: "save-document",
-    effect: () => saveDocument,
-    onDone: (to) => to.full.Saved().resolve(({ output, target }) => target.from({ id: output.id })),
-    onFailure: (to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: String(error) }))
-  })
-}
-
-Waiting: {
-  invoke: Machine.invoke({
-    id: "save-timeout",
-    after: "3 seconds",
-    onDone: (to) => to.full.Failed().resolve(({ target }) => target.from({ message: "Timed out" }))
-  })
-}
+machine.handle({
+  Loading: {
+    invoke: (from) =>
+      from.effect("save-document", () => saveDocument)
+        .onDone((to) => to.full.Saved().resolve(({ output, target }) => target.from({ id: output.id })))
+        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
+  },
+  Waiting: {
+    invoke: (from) =>
+      from.timer("save-timeout", "3 seconds")
+        .onDone((to) => to.full.Failed().resolve(({ target }) => target.from({ message: "Timed out" })))
+  }
+})
 ```
 
-Use `effect` for one Effect, `stream` for a sequence of externally produced
-values, `after` for a cancellable delay, `logic` for a reusable process, and
-`child` for a complete child statechart—all through
-`Machine.invoke({...})`. The helper is an identity at runtime and preserves
-owner-context and source-channel inference across lifecycle handlers, including
-for state-dependent Effects:
+The state-local `from` selector starts an `effect`, `stream`, `timer`, reusable
+`logic`, or complete `child` statechart. The selected source determines which
+lifecycle methods the chain requires and which methods are available. For
+example, an Effect with non-`never` output and error channels must handle both;
+the completed chain is the value returned by the callback:
 
 ```ts
-invoke: Machine.invoke({
-  id: "load-document",
-  effect: ({ state }) => loadDocument(state.documentId),
-  onDone: (to) => to.full.Ready().resolve(({ output, target }) => target.from({ document: output })),
-  onFailure: (to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: error.message }))
+machine.handle({
+  Loading: {
+    invoke: (from) =>
+      from.effect("load-document", ({ state }) => loadDocument(state.documentId))
+        .onDone((to) => to.full.Ready().resolve(({ output, target }) => target.from({ document: output })))
+        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: error.message })))
+  }
 })
 ```
 
@@ -476,15 +507,18 @@ is mapped by `onElement`, and the next element is not pulled until that parent
 macrostep commits:
 
 ```ts
-invoke: Machine.invoke({
-  id: "channel",
-  stream: () => channelMessages,
-  onElement: (to) =>
-    to.none.resolve(({ element }, enqueue) => {
-      enqueue.raise(Events.MessageReceived({ message: element }))
-    }),
-  onDone: (to) => to.none,
-  onFailure: (to) => to.full.Failed().resolve(({ error, target }) => target.from({ error }))
+machine.handle({
+  Listening: {
+    invoke: (from) =>
+      from.stream("channel", () => channelMessages)
+        .onElement((to) =>
+          to.none.resolve(({ element }, enqueue) => {
+            enqueue.raise(Events.MessageReceived({ message: element }))
+          })
+        )
+        .onDone((to) => to.none)
+        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ error })))
+  }
 })
 ```
 
@@ -493,10 +527,10 @@ current configuration, or call `.resolve(...)` when the transition only needs
 to enqueue commands. A block resolver may omit its return because it is
 contextually typed to return `undefined`.
 
-Inside `.handle(...)`, `Machine.invoke(...)` receives the owning machine's
-public input and declared parent protocol contextually. Its source and lifecycle
-callbacks can send through `self` and `parent` while retaining the invoked
-Effect's output and error inference:
+Inside `.handle(...)`, `from` receives the owning machine's public input and
+declared parent protocol contextually. Source and lifecycle callbacks can send
+through `self` and `parent` while retaining the invoked Effect's output and
+error inference:
 
 ```ts
 const machine = Machine.make({
@@ -506,36 +540,47 @@ const machine = Machine.make({
   // ...
 }).handle({
   Saving: {
-    invoke: Machine.invoke({
-      id: "notify-parent",
-      effect: () => saveDocument,
-      onDone: (to) =>
-        to.none.resolve(({ parent, self }, enqueue) => {
-          enqueue.sendTo(self, Commands.Save())
-          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-        }),
-      onFailure: (to) => to.none
-    })
+    invoke: (from) =>
+      from.effect("notify-parent", () => saveDocument)
+        .onDone((to) =>
+          to.none.resolve(({ parent, self }, enqueue) => {
+            enqueue.sendTo(self, Commands.Save())
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          })
+        )
+        .onFailure((to) => to.none)
   }
 })
 ```
 
-The standard `Machine.invoke(...)` form retains exact `self` and `parent`
-typing even when the definition is named separately; no intermediate
-definition method is required.
+Return an array of completed chains to compose multiple state-owned activities.
+The source computation itself, process logic, or `Machine.child(id, machine)`
+descriptor can be named and reused; the invocation chain stays local so its
+transitions retain the exact owning state and machine protocols.
 
-A direct `invoke: { ... }` object is also supported when its lifecycle handlers
-do not need source-derived context. Reuse one exported
-`Machine.child(id, machine)` descriptor for invocation, `sendTo`, and child
-lookup.
+```ts
+const refreshCache = Cache.refresh
+
+machine.handle({
+  Active: {
+    invoke: (from) => [
+      from.effect("refresh-cache", () => refreshCache).onDone((to) => to.none).onFailure((to) => to.none),
+      from.timer("expire-session", "5 minutes").onDone((to) => to.full.Expired())
+    ]
+  }
+})
+```
 
 `onDone` is required for a non-`never` output, and `onFailure` is required for a
-non-`never` typed error; each handler is omitted when its channel is `never`.
-Defects, interruption, and source-construction failures terminate the owning
-runtime. Effect sources are always factories evaluated when their state is
-entered. Use `effect: () => Effect.sleep(...)` for a generic Effect, while
-`after` keeps timers explicit and makes static durations visible through
-activity inspection.
+non-`never` typed error. Streams additionally require `onElement` when their
+element channel is non-`never` and always require `onDone`; logic and child
+chains optionally expose `onSnapshot`. A handled method disappears from the
+next builder step, so every reachable lifecycle channel is handled exactly
+once. Defects, interruption, and source-construction failures terminate the
+owning runtime. Effect sources are factories evaluated when their state is
+entered. Use an Effect containing `Effect.sleep(...)` for generic work, while
+`from.timer(...)` keeps timer intent explicit and makes static durations visible
+through activity inspection.
 
 ## Reactivity
 
@@ -579,6 +624,14 @@ const decoded = yield * Machine.decodeSnapshot(machine, encoded)
 const ref = yield * Machine.resume(machine, decoded)
 ```
 
+Decoded snapshots are local runtime values and may contain class instances or
+other process-local data. `encodeSnapshot` is the persistence boundary: it uses
+each declared schema's canonical JSON codec and succeeds only when every active
+state value, completion output, and history value is JSON. Rich values such as
+dates and bigints use their schema-defined JSON representation; cyclic or
+non-JSON values fail with `MachineSchemaEncodeError` instead of escaping to a
+later `JSON.stringify` crash.
+
 Resumption restores logical state, values, completion, and history metadata.
 It creates a fresh runtime: active invokes restart, timers restart at their
 full duration, and prior fibers, subscriptions, queues, and child runtimes are
@@ -631,11 +684,11 @@ Each ESM entrypoint is independent and tree-shakeable.
 Every package directly under [`examples/`](./examples) has its own lockfile and
 `check` script.
 
-| Example                             | What it demonstrates                                                                                                                                                                                                     |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [Playground](./examples/playground) | Five focused React examples: atomic turnstile commands, state-scoped traffic-light timers, microwave safety across parallel regions, a service-backed media player, and a worker-hosted machine synchronized across tabs |
-| [Pokémon](./examples/pokemon)       | Compound and parallel states, invoked child machines, typed emissions, Atom reactivity, and a live Effect service                                                                                                        |
-| [Platformer](./examples/platformer) | Nested parallel statecharts, typed deep history, raised events, state-scoped timers, deterministic model tests, and a playable SVG adapter                                                                               |
+| Example                             | What it demonstrates                                                                                                                                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Playground](./examples/playground) | Five focused React examples: atomic turnstile commands, state-scoped traffic-light timers, hierarchical microwave safety, a resource-owned media player, and a worker-hosted machine synchronized across tabs |
+| [Pokémon](./examples/pokemon)       | Compound workflow states, invoked child machines, typed emissions, Atom reactivity, and a live Effect service                                                                                                 |
+| [Platformer](./examples/platformer) | Nested parallel statecharts, typed deep history, raised events, state-scoped timers, deterministic model tests, and a playable SVG adapter                                                                    |
 
 The playground is the shortest path from one concept to working code. The
 standalone examples show larger composition and ownership boundaries.