@typeonce/effect-machine 0.7.0 → 0.9.0

package/README.md

@@ -40,12 +40,14 @@ const Event = Schema.TaggedUnion({
 
 const States = Machine.defineStates(State.cases)
 
-const Counter = Machine.make({
+const CounterDefinition = Machine.make({
   id: "Counter",
   states: States.states,
   events: [Event],
   initial: () => States.initial.Idle.from()
-}).handle({
+})
+
+const Counter = CounterDefinition.handle({
   Idle: {
     on: {
       Start: ({ target }) => target.full.Running.from({ count: 0 })
@@ -59,10 +61,12 @@ const Counter = Machine.make({
   }
 })
 
+const CounterEvent = Machine.events(Counter)
+
 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())
 })
 ```
 
@@ -94,6 +98,27 @@ 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`.
 
+Omit `schema` when a state represents control flow but owns no data:
+
+```ts
+const States = Machine.defineStates({
+  Form: {
+    initial: "Editing",
+    states: {
+      Editing: {},
+      Saving
+    }
+  }
+})
+
+States.initial.Form.from((form) => form.Editing.from())
+```
+
+Schema-less states remain active, targetable, matchable, and visible through
+`getSnapshot`, but have no value to read. Their builders expose only `.from`,
+their handler `state` is `undefined`, and `get` / `getWithParents` accept only
+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.
 
@@ -109,20 +134,32 @@ const Internal = Schema.TaggedUnion({
   SaveFailed: { message: Schema.String }
 })
 
-const machine = Machine.make({
+const definition = Machine.make({
   states: States.states,
   events: [Command],
   internalEvents: [Internal],
   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.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.
+Use `Machine.events(machine)` and `Machine.internalEvents(machine)` as the
+standard constructors for their respective protocols:
+
+```ts
+ref.send(CommandEvent.Save())
+enqueue.raise(InternalEvent.Saved({ 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.
 
 ### Choose the target by scope
 
@@ -164,29 +201,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:
+
+```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.
 
-Expected failures should become internal events. An unrecovered invoke or child
-failure terminates the owning runtime.
+`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
 
@@ -239,14 +295,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: [
+    Machine.event(Counter, Event.cases.Start),
+    Machine.event(Counter, Event.cases.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
+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.
 
 ## Entrypoints