@typeonce/effect-machine 0.9.0 → 0.11.0

package/README.md

@@ -25,7 +25,7 @@ Define schemas first, derive the state topology, then add behavior:
 
 ```ts
 import { Machine } from "@typeonce/effect-machine"
-import { Effect, Schema } from "effect"
+import { Effect, Schema, Stream } from "effect"
 
 const State = Schema.TaggedUnion({
   Idle: {},
@@ -39,11 +39,12 @@ const Event = Schema.TaggedUnion({
 })
 
 const States = Machine.defineStates(State.cases)
+const CounterEvent = Machine.events(Event)
 
 const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
-  events: [Event],
+  events: CounterEvent,
   initial: () => States.initial.Idle.from()
 })
 
@@ -61,8 +62,6 @@ const Counter = CounterDefinition.handle({
   }
 })
 
-const CounterEvent = Machine.events(Counter)
-
 const program = Effect.gen(function*() {
   const ref = yield* Machine.start(Counter)
   yield* ref.send(CounterEvent.Start())
@@ -71,8 +70,8 @@ const program = Effect.gen(function*() {
 ```
 
 `Machine.start` returns a `MachineRef` with `send`, `state`, `snapshot`,
-`changes`, `join`, and `stop`. Sending enqueues an event; observe `changes` or
-use the testing probe when work must be causally acknowledged.
+`changes`, `emissions`, `join`, and `stop`. Sending enqueues an event; observe
+`changes` or use the testing probe when work must be causally acknowledged.
 
 ## Modeling workflow
 
@@ -80,9 +79,11 @@ Use this order to preserve inference and keep boundaries explicit:
 
 1. Define domain, state, public-event, internal-event, and emitted-event schemas.
 2. Declare topology with `Machine.defineStates`.
-3. Create the protocol and initializer with `Machine.make`.
-4. Implement every active state with `.handle(...)`.
-5. Add runtime, Atom, testing, or cluster adapters at the application boundary.
+3. Create public and internal event descriptors with `Machine.events` and
+   `Machine.internalEvents`.
+4. Create the machine protocol and initializer with `Machine.make`.
+5. Implement every active state with `.handle(...)`.
+6. Add runtime, Atom, testing, or cluster adapters at the application boundary.
 
 ### Construct state through builders
 
@@ -96,7 +97,18 @@ States.initial.Form.from({ draft: "" }, (form) => form.Editing.from())
 The machine runs these inputs through the state schema while planning. Schema
 defaults, refinements, and tagged-class identity are therefore preserved, and
 decode failures remain typed machine failures. Pass a value directly only when
-it is already decoded, such as a value returned by `Machine.retag`.
+it is already decoded.
+
+When sibling states share fields, remove the source discriminator and pass the
+remaining fields through the target schema:
+
+```ts
+Submit: ;
+;(({ state, target }) => {
+  const { _tag: _, ...fields } = state
+  return target.local.Saving.from({ ...fields, attempt: 1 })
+})
+```
 
 Omit `schema` when a state represents control flow but owns no data:
 
@@ -122,10 +134,11 @@ schema-backed paths. Add a schema later if the state starts owning data.
 Put data on the narrowest state where it is valid. If sibling phases share
 data, put it on their compound parent.
 
-### Separate public and internal events
+### Separate inputs, raised events, and emissions
 
-`events` is the public command protocol. Invoke results, timer deliveries,
-raised events, and child emissions belong in `internalEvents`:
+`events` is the public actor-input protocol. Events raised to the same machine
+belong in `internalEvents`. Ephemeral outward notifications have their own
+`emittedEvents` protocol:
 
 ```ts
 const Command = Schema.TaggedUnion({ Save: {} })
@@ -133,46 +146,132 @@ const Internal = Schema.TaggedUnion({
   Saved: { id: Schema.String },
   SaveFailed: { message: Schema.String }
 })
+const Emitted = Schema.TaggedUnion({
+  SaveObserved: { id: Schema.String }
+})
+
+export const CommandEvent = Machine.events(Command)
+export type PublicCommandEvent = Machine.EventOf<typeof CommandEvent>
+const InternalEvent = Machine.internalEvents(Internal)
+const Emissions = Machine.emittedEvents(Emitted)
 
 const definition = Machine.make({
   states: States.states,
-  events: [Command],
-  internalEvents: [Internal],
+  events: CommandEvent,
+  internalEvents: InternalEvent,
+  emittedEvents: Emissions,
   initial: () => States.initial.Idle.from()
 })
-
-const CommandEvent = Machine.events(definition)
-const InternalEvent = Machine.internalEvents(definition)
 ```
 
 Handlers see both protocols. Typed `send` and `Machine.plan` accept only public
 events. Event tags must be unique and public/internal tags must be disjoint.
 
-Use `Machine.events(machine)` and `Machine.internalEvents(machine)` as the
-standard constructors for their respective protocols:
+Export the descriptor returned by `Machine.events` instead of exporting its
+schemas. This keeps the deferred constructors as the standard way to create
+events without exposing schema `.make` methods:
 
 ```ts
 ref.send(CommandEvent.Save())
 enqueue.raise(InternalEvent.Saved({ id: "entry-1" }))
+enqueue.emit(Emissions.SaveObserved({ id: "entry-1" }))
 ```
 
 The returned constructors preserve each schema's make input, including required
 fields and constructor defaults. They defer schema construction until delivery,
 so invalid values fail planning or the running machine with
 `MachineSchemaDecodeError` instead of throwing at the call site.
+Schemas with an open discriminator such as `_tag: Schema.String` remain valid
+protocols but cannot expose a finite constructor set; pass a complete event
+object to `send` or `Machine.plan` for those events.
+
+`ref.emissions` is a hot `Stream`: it publishes only notifications produced
+after subscription, replays nothing, and completes when the actor terminates.
+Snapshots remain separate and stateful: `ref.changes` begins with the current
+lifecycle snapshot and then follows later changes. Use `Machine.prepare` when
+an observer must be installed before initial-entry actions run:
+
+```ts
+const prepared = yield * Machine.prepare(machine)
+
+yield * prepared.emissions.pipe(
+  Stream.runForEach(handleEmission),
+  Effect.forkScoped({ startImmediately: true })
+)
+
+const ref = yield * prepared.start
+```
+
+`Machine.start(machine)` remains the one-step convenience for callers that do
+not observe startup emissions. Preparation does not retain or replay an
+emission: the observer is simply subscribed before initialization begins.
+
+Invalid event and emission constructions fail the machine with a typed
+`MachineSchemaDecodeError`; they do not throw from the constructor call.
+
+### Send explicitly between actors
+
+`raise` targets the current machine in the same macrostep. `sendTo` targets an
+actor mailbox and is processed later. A child declares the subset of parent
+inputs it may send with `parentEvents`:
+
+```ts
+const ParentEvents = Machine.events(ChildFinished)
+
+const child = Machine.make({
+  states: ChildStates.states,
+  events: ChildEvents,
+  parentEvents: ParentEvents,
+  initial: () => ChildStates.initial.Working.from()
+}).handle({
+  Working: {
+    on: {
+      Finish: ({ parent, target }, enqueue) => {
+        if (parent !== undefined) {
+          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+        }
+        return target.full.Done.from()
+      }
+    }
+  },
+  Done: {}
+})
+
+const Child = Machine.child("worker", child)
+const ParentInputs = Machine.events(Start, ParentEvents)
+```
+
+The same child remains isolated and may be started as a root, where `parent` is
+`undefined`. When `Child` is invoked, the parent definition must accept every
+event in `parentEvents`; otherwise `.handle(...)` is a compile-time error.
+Inside the child, the parent reference accepts only those declared events.
+`emit` never sends to the parent: it only publishes on the emitting actor's
+`emissions` stream.
+
+Every handler also receives `self`, which can be targeted with `sendTo` when a
+later mailbox turn is required. Use `raise` instead for same-macrostep work.
+Structural state values use distinct names: `containingState` is the immediate
+valued state in the same statechart, while `ancestors` maps valued ancestor
+paths. `parent` always means the owning actor reference.
 
 ### Choose the target by scope
 
 | Builder          | Use when                                 | Preserves                                         |
 | ---------------- | ---------------------------------------- | ------------------------------------------------- |
+| `target.none()`  | Handling without selecting a destination | The complete current configuration                |
 | `target.local`   | Moving inside the nearest compound scope | Ancestors and unrelated parallel regions          |
 | `target.branch`  | Moving elsewhere under the active root   | Omitted active ancestors and parallel regions     |
 | `target.full`    | Replacing or selecting a complete root   | Nothing implicit for a newly selected root        |
 | `target.history` | Restoring a declared history node        | The remembered configuration or its typed default |
 
-Builders describe the next logical configuration. Shared states exit and enter
-only when paths change; use `{ reenter: true, transition }` when the source must
-restart even if its path is unchanged.
+Every installed transition handler returns either a concrete target or
+`target.none()`. An absent handler ignores the trigger; `target.none()` handles
+it and retains queued commands, raised events, and emitted events without
+selecting a destination. Declared `targets` constrain only concrete
+destinations, so `target.none()` is always permitted. Builders describe the
+next logical configuration. Shared states exit and enter only when paths
+change; use `{ reenter: true, transition }` when the source must restart. With
+`target.none()`, reentry restarts the source while retaining its configuration.
 
 ## Statechart capabilities
 
@@ -233,6 +332,35 @@ invoke: Machine.invoke({
 })
 ```
 
+The standalone `Machine.invoke(...)` constructor does not know the owning
+definition, so its `self` and `parent` references are non-sendable. When an
+invocation callback sends through either reference, construct it through the
+owning definition so those references use its exact public input and
+`parentEvents` protocols:
+
+```ts
+const definition = Machine.make({
+  events: Commands,
+  internalEvents: InternalEvents,
+  parentEvents: ParentEvents
+  // ...
+})
+
+const machine = definition.handle({
+  Saving: {
+    invoke: definition.invoke({
+      id: "notify-parent",
+      effect: ({ parent }) =>
+        parent === undefined
+          ? Effect.void
+          : parent.send(ParentEvents.SaveStarted()),
+      onDone: ({ target }) => target.none(),
+      onFailure: ({ target }) => target.none()
+    })
+  }
+})
+```
+
 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
@@ -265,6 +393,17 @@ The bridge exposes `ref`, `snapshot`, `state`, fail-aware `result`, writable
 equality-aware derivations. React applications using `@effect/atom-react` need
 a `RegistryProvider`.
 
+Emissions stay streams rather than becoming retained atom state:
+
+```ts
+const rootEmissions = AtomMachine.emissions(counterAtom)
+const childEmissions = AtomMachine.childEmissions(counterAtom.child(Worker))
+```
+
+These streams require the same `AtomRegistry`, follow the currently mounted
+actor instance, and do not replay notifications from an earlier subscription
+or child instance.
+
 ## Persistence
 
 Logical snapshots can be validated for storage or transport:
@@ -296,8 +435,8 @@ import { MachineTest } from "@typeonce/effect-machine/testing"
 
 const trace = yield* MachineTest.run(Counter, {
   events: [
-    Machine.event(Counter, Event.cases.Start),
-    Machine.event(Counter, Event.cases.Increment)
+    { _tag: "Start" },
+    { _tag: "Increment" }
   ]
 })
 
@@ -305,9 +444,9 @@ yield* MachineTest.verify(Counter, trace)
 ```
 
 `MachineTest` scenarios retain decoded event values for model inspection, so
-this is the main case for the eager `Machine.event` API. Pure planner tests do
-not execute invokes or time. Use a started machine and a probe when those
-semantics matter.
+pass complete decoded objects when defining scenarios manually. Pure planner
+tests do not execute invokes or time. Use a started machine and a probe when
+those semantics matter.
 
 ## Entrypoints