@typeonce/effect-machine 0.18.0 → 0.19.1

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.111
 ```
 
 `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()
     }
   }
 })
@@ -127,6 +130,23 @@ 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
 
 Use `.from(...)` when constructing a new state from fields:
@@ -153,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({
@@ -178,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.
 
@@ -209,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()
 })
 ```
 
@@ -321,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: {
@@ -372,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
@@ -594,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
@@ -646,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.