@typeonce/effect-machine 0.8.0 → 0.10.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,13 +39,16 @@ const Event = Schema.TaggedUnion({
 })
 
 const States = Machine.defineStates(State.cases)
+const CounterEvent = Machine.events(Event)
 
-const Counter = Machine.make({
+const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
-  events: [Event],
+  events: CounterEvent,
   initial: () => States.initial.Idle.from()
-}).handle({
+})
+
+const Counter = CounterDefinition.handle({
   Idle: {
     on: {
       Start: ({ target }) => target.full.Running.from({ count: 0 })
@@ -61,14 +64,14 @@ const Counter = Machine.make({
 
 const program = Effect.gen(function*() {
   const ref = yield* Machine.start(Counter)
-  yield* ref.send(Machine.event(Counter, Event.cases.Start))
-  yield* ref.send(Machine.event(Counter, Event.cases.Increment))
+  yield* ref.send(CounterEvent.Start())
+  yield* ref.send(CounterEvent.Increment())
 })
 ```
 
 `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
 
@@ -76,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
 
@@ -92,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:
 
@@ -118,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: {} })
@@ -129,11 +146,20 @@ const Internal = Schema.TaggedUnion({
   Saved: { id: Schema.String },
   SaveFailed: { message: Schema.String }
 })
+const Emitted = Schema.TaggedUnion({
+  SaveObserved: { id: Schema.String }
+})
 
-const machine = Machine.make({
+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()
 })
 ```
@@ -141,22 +167,101 @@ const machine = Machine.make({
 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.event(machine, schema, fields?)` for reusable machine-owned event
-values. Ordinary objects and schema-constructed values are also accepted and
-decoded at the machine boundary.
+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. Because `Machine.start`
+returns only after initialization, startup emissions are not observable from
+the returned ref; represent startup facts in state when they must be retained.
+
+```ts
+const next = ref.emissions.pipe(Stream.take(1), Stream.runHead)
+```
+
+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
 
@@ -185,29 +290,48 @@ State-scoped work starts on entry and is interrupted on exit:
 
 ```ts
 Loading: {
-  invoke: Machine.invokeEffect({
+  invoke: Machine.invoke({
     id: "save-document",
     effect: saveDocument,
-    onSuccess: (entry) => Internal.cases.Saved.make({ id: entry.id }),
-    onFailure: (error) => Internal.cases.SaveFailed.make({ message: String(error) })
+    onDone: ({ output, target }) => target.full.Saved({ id: output.id }),
+    onFailure: ({ error, target }) => target.full.Failed({ message: String(error) })
   })
 }
 
 Waiting: {
-  invoke: Machine.after(
-    "3 seconds",
-    Internal.cases.SaveFailed.make({ message: "Timed out" })
-  )
+  invoke: Machine.invoke({
+    id: "save-timeout",
+    after: "3 seconds",
+    onDone: ({ target }) => target.full.Failed({ message: "Timed out" })
+  })
 }
 ```
 
-Use `Machine.invokeEffect` for one Effect, `Machine.after` for a cancellable
-delay, and lower-level `Machine.invoke` only for custom process behavior or
-snapshot mapping. Use one exported `Machine.child(id, machine)` descriptor for
-`invokeMachine`, `sendTo`, and child lookup.
+Use `effect` for one Effect, `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:
 
-Expected failures should become internal events. An unrecovered invoke or child
-failure terminates the owning runtime.
+```ts
+invoke: Machine.invoke({
+  id: "load-document",
+  effect: ({ state }) => loadDocument(state.documentId),
+  onDone: ({ output, target }) => target.full.Ready({ document: output }),
+  onFailure: ({ error, target }) => target.full.Failed({ message: error.message })
+})
+```
+
+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.
+
+`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: Effect.sleep(...)` is valid, but `after` keeps timers explicit
+and makes static durations visible through activity inspection.
 
 ## Reactivity
 
@@ -230,6 +354,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:
@@ -260,14 +395,19 @@ The testing entrypoint provides complementary layers:
 import { MachineTest } from "@typeonce/effect-machine/testing"
 
 const trace = yield* MachineTest.run(Counter, {
-  events: [Event.cases.Start.make({}), Event.cases.Increment.make({})]
+  events: [
+    { _tag: "Start" },
+    { _tag: "Increment" }
+  ]
 })
 
 yield* MachineTest.verify(Counter, trace)
 ```
 
-Pure planner tests do not execute invokes or time. Use a started machine and a
-probe when those semantics matter.
+`MachineTest` scenarios retain decoded event values for model inspection, so
+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