@typeonce/effect-machine 0.15.0 → 0.17.0

package/README.md

@@ -66,31 +66,19 @@ const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
   events: CounterEvent,
-  initial: {
-    target: (to) => to.Idle(),
-    resolve: ({ target }) => target.from()
-  }
+  initial: (to) => to.Idle().resolve(({ target }) => target.from())
 })
 
 const Counter = CounterDefinition.handle({
   Idle: {
     on: {
-      Start: Machine.transition({
-        target: (to) => to.full.Running(),
-        resolve: ({ target }) => target.from({ count: 0 })
-      })
+      Start: (to) => to.full.Running().resolve(({ target }) => target.from({ count: 0 }))
     }
   },
   Running: {
     on: {
-      Increment: Machine.transition({
-        target: (to) => to.full.Running(),
-        resolve: ({ state, target }) => target.from({ count: state.count + 1 })
-      }),
-      Stop: Machine.transition({
-        target: (to) => to.full.Idle(),
-        resolve: ({ target }) => target.from()
-      })
+      Increment: (to) => to.full.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
+      Stop: (to) => to.full.Idle().resolve(({ target }) => target.from())
     }
   }
 })
@@ -153,13 +141,13 @@ When sibling states share fields, remove the source discriminator and pass the
 remaining fields through the target schema:
 
 ```ts
-Submit: Machine.transition({
-  target: (to) => to.local.Saving(),
-  resolve: ({ state, target }) => {
-    const { _tag: _, ...fields } = state
-    return target.from({ ...fields, attempt: 1 })
-  }
-})
+const handlers = {
+  Submit: (to) =>
+    to.local.Saving().resolve(({ state, target }) => {
+      const { _tag: _, ...fields } = state
+      return target.from({ ...fields, attempt: 1 })
+    })
+}
 ```
 
 Omit `schema` when a state represents control flow but owns no data:
@@ -175,10 +163,11 @@ const States = Machine.states({
   }
 })
 
-initial: {
-  target: (to) => to.Form.initial(),
-  resolve: ({ target }) => target((form) => form.Editing.from())
-}
+const definition = Machine.make({
+  states: States.states,
+  events: Machine.events(),
+  initial: (to) => to.Form.initial.resolve(({ target }) => target((form) => form.Editing.from()))
+})
 ```
 
 Schema-less states remain active, targetable, matchable, and visible through
@@ -217,10 +206,7 @@ const definition = Machine.make({
   events: CommandEvent,
   internalEvents: InternalEvent,
   emittedEvents: Emissions,
-  initial: {
-    target: (to) => to.Idle(),
-    resolve: ({ target }) => target.from()
-  }
+  initial: (to) => to.Idle().resolve(({ target }) => target.from())
 })
 ```
 
@@ -322,8 +308,8 @@ Invalid event and emission constructions fail the machine with a typed
 ### Send explicitly between machines
 
 `raise` targets the current machine in the same macrostep. `sendTo` targets a
-machine mailbox and is processed later. A child declares the subset of parent
-inputs it may send with `parentEvents`:
+machine mailbox and is processed later. A machine that requires an owner
+declares the subset of parent inputs it may send with `Machine.parent`:
 
 ```ts
 const ParentEvents = Machine.events(ChildFinished)
@@ -331,23 +317,16 @@ const ParentEvents = Machine.events(ChildFinished)
 const child = Machine.make({
   states: ChildStates.states,
   events: ChildEvents,
-  parentEvents: ParentEvents,
-  initial: {
-    target: (to) => to.Working(),
-    resolve: ({ target }) => target.from()
-  }
+  parent: Machine.parent(ParentEvents),
+  initial: (to) => to.Working().resolve(({ target }) => target.from())
 }).handle({
   Working: {
     on: {
-      Finish: Machine.transition({
-        target: (to) => to.full.Done(),
-        resolve: ({ parent, target }, enqueue) => {
-          if (parent !== undefined) {
-            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-          }
+      Finish: (to) =>
+        to.full.Done().resolve(({ parent, target }, enqueue) => {
+          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
           return target.from()
-        }
-      })
+        })
     }
   },
   Done: {}
@@ -357,10 +336,16 @@ 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.
+`parent` is statically present in every child callback, and root APIs such as
+`Machine.start`, `Machine.planInitial`, Atom machines, and Cluster machines
+reject this machine. When `Child` is invoked, the parent definition must accept
+every declared parent event; otherwise `.handle(...)` is a compile-time error.
 Inside the child, the parent target accepts only those declared events.
+
+Use `parent: Machine.optionalParent(ParentEvents)` when the same machine is
+intentionally valid both as a root and as a child. In that case `parent` is
+`MachineTarget<...> | undefined` and must be narrowed before sending. When no
+parent declaration is present, callbacks do not expose a `parent` property.
 `emit` never sends to the parent: it only publishes on the emitting machine's
 `emissions` stream.
 
@@ -383,14 +368,48 @@ paths. `parent` always means the owning machine target.
 | `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 |
 
-Every installed transition handler returns either a concrete target or
-`target.none()`. An absent handler ignores the trigger; `target.none()` handles
+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
 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
+selecting a destination. Concrete destinations stay narrowed inside their
+resolver, and `to.branches({...})` gives the resolver only the declared named
+`select` builders. 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.
+change; call `.reenter()` for resolver-free reentry or pass `{ reenter: true }`
+to `.resolve(...)` when the source must restart. With `to.none`, reentry
+restarts the source while retaining its configuration.
+
+Topology-only definition instructions are values: `to.none`, declared
+`.initial` and history selections, and `to.local.with`. Concrete state and
+choice destinations remain calls such as `to.full.Running()`. Runtime named
+branch builders remain callable, including `select.unchanged()`, because their
+result carries the selected branch evidence.
+
+Use `declinable: true` when a resolver may decide that its transition is not
+enabled. Only that resolver receives `decline()`, and its return type expands to
+accept the opaque declined result:
+
+```ts
+const handlers = {
+  Submit: (to) =>
+    to.local.Saving().resolve(
+      ({ event, target, decline }) => accepts(event) ? target.from({ draft: event.draft }) : decline(),
+      { declinable: true }
+    )
+}
+```
+
+Declining discards work enqueued by that resolver. Event and eventless dispatch
+continues with the next eligible ancestor; if no candidate accepts, no
+transition is selected. This differs from `target.none()`, which consumes the
+trigger and prevents an ancestor from handling it. `transitionDefinitions`
+reports each handler's `acceptance` as `"required"` or `"declinable"` while
+preserving the exact declared target branches. Choices and initial routing must
+remain total and cannot use declinable transitions. Completion and invocation
+outcomes have no ancestor candidate: declining one ignores that lifecycle
+occurrence and leaves the current configuration active.
 
 ## Statechart capabilities
 
@@ -413,7 +432,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:
 
@@ -422,14 +441,8 @@ Loading: {
   invoke: Machine.invoke({
     id: "save-document",
     effect: () => saveDocument,
-    onDone: Machine.transition({
-      target: (to) => to.full.Saved(),
-      resolve: ({ output, target }) => target.from({ id: output.id })
-    }),
-    onFailure: Machine.transition({
-      target: (to) => to.full.Failed(),
-      resolve: ({ error, target }) => target.from({ message: String(error) })
-    })
+    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) }))
   })
 }
 
@@ -437,16 +450,14 @@ Waiting: {
   invoke: Machine.invoke({
     id: "save-timeout",
     after: "3 seconds",
-    onDone: Machine.transition({
-      target: (to) => to.full.Failed(),
-      resolve: ({ target }) => target.from({ message: "Timed out" })
-    })
+    onDone: (to) => to.full.Failed().resolve(({ target }) => target.from({ message: "Timed out" }))
   })
 }
 ```
 
-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:
@@ -455,19 +466,35 @@ for state-dependent Effects:
 invoke: Machine.invoke({
   id: "load-document",
   effect: ({ state }) => loadDocument(state.documentId),
-  onDone: Machine.transition({
-    target: (to) => to.full.Ready(),
-    resolve: ({ output, target }) => target.from({ document: output })
-  }),
-  onFailure: Machine.transition({
-    target: (to) => to.full.Failed(),
-    resolve: ({ error, target }) => target.from({ message: error.message })
-  })
+  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 }))
 })
 ```
 
+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
+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 }))
+})
+```
+
+`to.none` is the targetless transition value. Return it directly to keep the
+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 `parentEvents` protocols contextually. Its source and lifecycle
+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:
 
@@ -475,34 +502,27 @@ Effect's output and error inference:
 const machine = Machine.make({
   events: Commands,
   internalEvents: InternalEvents,
-  parentEvents: ParentEvents
+  parent: Machine.parent(ParentEvents)
   // ...
 }).handle({
   Saving: {
     invoke: Machine.invoke({
       id: "notify-parent",
       effect: () => saveDocument,
-      onDone: Machine.transition({
-        target: (to) => to.none(),
-        resolve: ({ parent, self }, enqueue) => {
+      onDone: (to) =>
+        to.none.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(),
-        resolve: () => undefined
-      })
+          enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+        }),
+      onFailure: (to) => to.none
     })
   }
 })
 ```
 
-The machine-bound `definition.invoke(...)` form remains equivalent when a
-definition is already named; it is not required for `self` or `parent` typing.
+The standard `Machine.invoke(...)` form retains exact `self` and `parent`
+typing even when the definition is named separately; no intermediate
+definition method is required.
 
 A direct `invoke: { ... }` object is also supported when its lifecycle handlers
 do not need source-derived context. Reuse one exported