@typeonce/effect-machine 0.16.0 → 0.18.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())
     }
   }
 })
@@ -134,7 +122,10 @@ 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>`.
+complete tree. Type full-snapshot helpers as `Machine.Snapshot<typeof States>`
+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>`.
 
 ### Construct state through builders
 
@@ -153,13 +144,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 +166,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 +209,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 +311,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 +320,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 +339,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 +371,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
 
@@ -418,52 +440,35 @@ arbitrary asynchronous Effects do not run inside planning.
 State-scoped work starts on entry and is interrupted on exit:
 
 ```ts
-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) })
-    })
-  })
-}
-
-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" })
-    })
-  })
-}
+machine.handle({
+  Loading: {
+    invoke: (from) =>
+      from.effect("save-document", () => saveDocument)
+        .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) })))
+  },
+  Waiting: {
+    invoke: (from) =>
+      from.timer("save-timeout", "3 seconds")
+        .onDone((to) => to.full.Failed().resolve(({ target }) => target.from({ message: "Timed out" })))
+  }
+})
 ```
 
-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:
+The state-local `from` selector starts an `effect`, `stream`, `timer`, reusable
+`logic`, or complete `child` statechart. The selected source determines which
+lifecycle methods the chain requires and which methods are available. For
+example, an Effect with non-`never` output and error channels must handle both;
+the completed chain is the value returned by the callback:
 
 ```ts
-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 })
-  })
+machine.handle({
+  Loading: {
+    invoke: (from) =>
+      from.effect("load-document", ({ state }) => loadDocument(state.documentId))
+        .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 })))
+  }
 })
 ```
 
@@ -472,78 +477,80 @@ 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: {
-    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 })
-  })
+machine.handle({
+  Listening: {
+    invoke: (from) =>
+      from.stream("channel", () => 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 })))
+  }
 })
 ```
 
-`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.
+`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
-callbacks can send through `self` and `parent` while retaining the invoked
-Effect's output and error inference:
+Inside `.handle(...)`, `from` receives the owning machine's public input and
+declared parent protocol contextually. 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
+  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) => {
-          enqueue.sendTo(self, Commands.Save())
-          if (parent !== undefined) {
+    invoke: (from) =>
+      from.effect("notify-parent", () => saveDocument)
+        .onDone((to) =>
+          to.none.resolve(({ parent, self }, enqueue) => {
+            enqueue.sendTo(self, Commands.Save())
             enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
-          }
-          return undefined
-        }
-      }),
-      onFailure: Machine.transition({
-        target: (to) => to.none(),
-        resolve: () => undefined
-      })
-    })
+          })
+        )
+        .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.
+Return an array of completed chains to compose multiple state-owned activities.
+The source computation itself, process logic, or `Machine.child(id, machine)`
+descriptor can be named and reused; the invocation chain stays local so its
+transitions retain the exact owning state and machine protocols.
 
-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.
+```ts
+const refreshCache = Cache.refresh
+
+machine.handle({
+  Active: {
+    invoke: (from) => [
+      from.effect("refresh-cache", () => refreshCache).onDone((to) => to.none).onFailure((to) => to.none),
+      from.timer("expire-session", "5 minutes").onDone((to) => to.full.Expired())
+    ]
+  }
+})
+```
 
 `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 sources are always factories evaluated when their state is
-entered. Use `effect: () => Effect.sleep(...)` for a generic Effect, while
-`after` keeps timers explicit and makes static durations visible through
-activity inspection.
+non-`never` typed error. Streams additionally require `onElement` when their
+element channel is non-`never` and always require `onDone`; logic and child
+chains optionally expose `onSnapshot`. A handled method disappears from the
+next builder step, so every reachable lifecycle channel is handled exactly
+once. Defects, interruption, and source-construction failures terminate the
+owning runtime. Effect sources are factories evaluated when their state is
+entered. Use an Effect containing `Effect.sleep(...)` for generic work, while
+`from.timer(...)` keeps timer intent explicit and makes static durations visible
+through activity inspection.
 
 ## Reactivity