@typeonce/effect-machine 0.14.1 → 0.16.0

package/README.md

@@ -53,14 +53,14 @@ const State = Schema.TaggedUnion({
   Running: { count: Schema.Number }
 })
 
-const Event = Schema.TaggedUnion({
-  Start: {},
-  Increment: {},
-  Stop: {}
-})
-
-const States = Machine.defineStates(State.cases)
-const CounterEvent = Machine.events(Event)
+const States = Machine.states(State.cases)
+const CounterEvent = Machine.events(
+  Schema.TaggedUnion({
+    Start: {},
+    Increment: {},
+    Stop: {}
+  })
+)
 
 const CounterDefinition = Machine.make({
   id: "Counter",
@@ -102,6 +102,16 @@ const program = Effect.gen(function*() {
 })
 ```
 
+`handle` creates a complete implementation boundary. Its result does not
+expose `handle`, so all behavior for one machine belongs in the same handler
+tree. Reuse the definition when multiple independent implementations are
+useful, such as production and testing variants:
+
+```ts
+const ProductionCounter = CounterDefinition.handle(productionHandlers)
+const TestingCounter = CounterDefinition.handle(testingHandlers)
+```
+
 `Machine.start` returns a `MachineRef` with `send`, `state`, `snapshot`,
 `changes`, `emissions`, `join`, and `stop`. Sending enqueues an event; observe
 `changes` or use the testing probe when work must be causally acknowledged.
@@ -110,13 +120,21 @@ const program = Effect.gen(function*() {
 
 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 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.
+1. Define domain schemas used by state and by shared event fields.
+2. Declare topology with `Machine.states`, naming a tagged state union
+   when its `.cases` are reused.
+3. Create event descriptors with `Machine.events`, `Machine.internalEvents`,
+   and `Machine.emittedEvents`, passing tagged unions or tagged classes directly.
+4. Create the machine and implement every active state with
+   `Machine.make({...}).handle({...})`.
+5. Add child descriptors, then runtime, Atom, testing, or cluster adapters at
+   the application boundary.
+
+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>`.
 
 ### Construct state through builders
 
@@ -147,7 +165,7 @@ Submit: Machine.transition({
 Omit `schema` when a state represents control flow but owns no data:
 
 ```ts
-const States = Machine.defineStates({
+const States = Machine.states({
   Form: {
     initial: "Editing",
     states: {
@@ -178,19 +196,21 @@ belong in `internalEvents`. Ephemeral outward notifications have their own
 `emittedEvents` protocol:
 
 ```ts
-const Command = Schema.TaggedUnion({ Save: {} })
-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 const CommandEvent = Machine.events(
+  Schema.TaggedUnion({ Save: {} })
+)
 export type PublicCommandEvent = Machine.EventOf<typeof CommandEvent>
-const InternalEvent = Machine.internalEvents(Internal)
-const Emissions = Machine.emittedEvents(Emitted)
+const InternalEvent = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
+const Emissions = Machine.emittedEvents(
+  Schema.TaggedUnion({
+    SaveObserved: { id: Schema.String }
+  })
+)
 
 const definition = Machine.make({
   states: States.states,
@@ -374,7 +394,7 @@ change; use `{ reenter: true, transition }` when the source must restart. With
 
 ## Statechart capabilities
 
-`Machine.defineStates` supports:
+`Machine.states` supports:
 
 - atomic states;
 - compound states with one active child;
@@ -384,7 +404,7 @@ change; use `{ reenter: true, transition }` when the source must restart. With
 - shallow and deep history states.
 
 Declare topology—including finality, output schemas, choices, and history—only
-in `defineStates`. Handlers implement behavior and output computation without
+in `states`. Handlers implement behavior and output computation without
 repeating structural metadata. Final children complete their parent, so
 `onDone` belongs on that compound or parallel parent.
 
@@ -393,7 +413,7 @@ synchronous. Conditions use ordinary TypeScript control flow. Callbacks may
 select state and enqueue explicit `raise`, `emit`, `sendTo`, or `stop` commands;
 arbitrary asynchronous Effects do not run inside planning.
 
-## Effects, timers, and child machines
+## Effects, Streams, timers, and child machines
 
 State-scoped work starts on entry and is interrupted on exit:
 
@@ -425,8 +445,9 @@ Waiting: {
 }
 ```
 
-Use `effect` for one Effect, `after` for a cancellable delay, `logic` for a
-reusable process, and `child` for a complete child statechart—all through
+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:
@@ -446,31 +467,58 @@ 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:
+A Stream source remains independent of the parent event protocol. Each element
+is mapped by `onElement`, and the next element is not pulled until that parent
+macrostep commits:
 
 ```ts
-const definition = Machine.make({
+invoke: Machine.invoke({
+  id: "channel",
+  stream: () => channelMessages,
+  onElement: {
+    target: Machine.targetless,
+    resolve: ({ element }, enqueue) => {
+      enqueue.raise(Events.MessageReceived({ message: element }))
+    }
+  },
+  onDone: { target: Machine.targetless },
+  onFailure: Machine.transition({
+    target: (to) => to.full.Failed(),
+    resolve: ({ error, target }) => target.from({ error })
+  })
+})
+```
+
+`target: Machine.targetless` is the direct shorthand for a non-reentering
+transition that keeps the current configuration. Its optional `resolve`
+callback may enqueue commands and must return `undefined`. Use
+`Machine.transition(...)` for transitions that select state or reenter.
+
+Inside `.handle(...)`, `Machine.invoke(...)` receives the owning machine's
+public input and `parentEvents` protocols contextually. Its 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({
   events: Commands,
   internalEvents: InternalEvents,
   parentEvents: ParentEvents
   // ...
-})
-
-const machine = definition.handle({
+}).handle({
   Saving: {
-    invoke: definition.invoke({
+    invoke: Machine.invoke({
       id: "notify-parent",
-      effect: ({ parent }) =>
-        parent === undefined
-          ? Effect.void
-          : parent.send(ParentEvents.SaveStarted()),
+      effect: () => saveDocument,
       onDone: Machine.transition({
         target: (to) => to.none(),
-        resolve: () => undefined
+        resolve: ({ parent, self }, enqueue) => {
+          enqueue.sendTo(self, Commands.Save())
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          }
+          return undefined
+        }
       }),
       onFailure: Machine.transition({
         target: (to) => to.none(),
@@ -481,6 +529,9 @@ const machine = definition.handle({
 })
 ```
 
+The machine-bound `definition.invoke(...)` form remains equivalent when a
+definition is already named; it is not required for `self` or `parent` typing.
+
 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