@typeonce/effect-machine 0.29.0 → 0.31.0

package/README.md

@@ -249,8 +249,9 @@ const definition = 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.
+Handlers see both protocols. Typed `send`, `Machine.can`, and `Machine.plan`
+accept only public events. Event tags must be unique and public/internal tags
+must be disjoint.
 
 Export the descriptor returned by `Machine.events` instead of exporting its
 schemas. This keeps the deferred constructors as the standard way to create
@@ -554,6 +555,23 @@ 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.
 
+Use `Machine.can` when a caller needs to test a concrete event against a
+snapshot. The direct and machine-specialized forms have the same semantics:
+
+```ts
+const canSubmit = yield * Machine.can(machine, snapshot, Submit({ draft }))
+
+const canMachine = Machine.can(machine)
+const canCancel = yield * canMachine(snapshot, Cancel())
+```
+
+`can` returns `true` when at least one required or non-declined handler accepts
+the event. Targetless transitions count as accepted. Invalid event input fails
+with `MachineSchemaDecodeError`; a valid unhandled event returns `false`.
+Declinable resolvers run to decide acceptance, but collected commands,
+emissions, and raised events are discarded. Required resolvers and transition
+lifecycle do not run.
+
 ## Statechart capabilities
 
 `Machine.states` supports:
@@ -746,6 +764,19 @@ const counterAtom = AtomMachine.bind(runtime).make(Counter)
 
 Binding a shared runtime once is the canonical form for service-backed
 applications. Service-free machines can use `AtomMachine.make(Counter)`.
+Use `factory` when the same definition constructs several independent bridges:
+
+```ts
+const MachineAtoms = AtomMachine.bind(runtime)
+const makeProcessMachine = MachineAtoms.factory(ProcessMachine)
+
+const first = makeProcessMachine({ processId: "first" })
+const second = makeProcessMachine({ processId: "second" })
+type ProcessMachineAtom = ReturnType<typeof makeProcessMachine>
+```
+
+Each call creates a fresh lazy bridge. `factory` does not cache by input;
+`AtomMachine.family` remains the keyed shared-identity interface.
 
 The bridge exposes `ref`, `snapshot`, `state`, fail-aware `result`, writable
 `send` and `stop` atoms, and `child(descriptor)`. Use `AtomMachine.select`,
@@ -753,6 +784,19 @@ The bridge exposes `ref`, `snapshot`, `state`, fail-aware `result`, writable
 equality-aware derivations. Repeating one of these calls with the same bridge
 and state path returns the same atom.
 
+Use `AtomMachine.can` to project concrete event acceptance. Declare the
+projection once and apply it to compatible bridges:
+
+```ts
+const submitAllowed = AtomMachine.can(Events.Submit({ draft }))
+const canSubmitAtom = submitAllowed(machineAtom)
+```
+
+Pass an `Atom<EventInput>` instead when the event payload changes reactively.
+Each projection returns the same derived atom for repeated applications to one
+bridge. Startup and runtime failures remain typed, while done and stopped
+machines return `false`.
+
 Use `useMachineAtom` from `@typeonce/effect-machine-react` when one React
 subtree owns the machine. It mounts the machine without subscribing the owner
 to state. Pass the returned machine atom through props or Context, then call
@@ -769,6 +813,7 @@ preserving lazy registry startup and disposal:
 ```ts
 const processAtoms = AtomMachine.bind(runtime).family(processMachine, {
   atoms: {
+    canStart: AtomMachine.can(ProcessEvents.Start()),
     details: AtomMachine.select("Processing"),
     ready: AtomMachine.matches("Ready"),
     send: (machine) => machine.send

package/dist/Machine.d.ts

@@ -5104,6 +5104,44 @@ export declare const configuration: <M extends Machine.Any>(machine: M, state: M
  * @since 0.4.0
  */
 export declare const enabled: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events, ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents, ParentEvents>, state: Machine.Snapshot<States>) => ReadonlyArray<Machine.TagOf<Events[number]>>;
+/**
+ * Tests whether a concrete event would select at least one transition from a
+ * decoded snapshot.
+ *
+ * **Details**
+ *
+ * Required handlers are accepted from their structural eligibility.
+ * Declinable handlers run their resolver only far enough to decide whether
+ * they accept the event. Any commands, emissions, or raised events collected
+ * during that check are discarded.
+ *
+ * Event input is decoded through the machine's public event protocol. Invalid
+ * input fails with `MachineSchemaDecodeError`. Final snapshots and valid events
+ * with no accepting handler return `false`.
+ *
+ * **Gotchas**
+ *
+ * This query does not execute transitions or stabilize the resulting machine.
+ * It does not run entry, exit, always, completion, child lifecycle, or command
+ * effects. A `true` result therefore describes event acceptance only.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const canCheckout = Machine.can(checkoutMachine)
+ *
+ * const canSubmit = yield* canCheckout(snapshot, {
+ *   _tag: "SubmitOrder"
+ * })
+ * ```
+ *
+ * @category getters
+ * @since 0.30.0
+ */
+export declare const can: {
+    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events, ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents, ParentEvents> & EnsureExecutable<States, UnhandledStates, OutputStates> & Machine.RootCompatible<ParentEvents>): (state: Machine.Snapshot<States>, event: Machine.EventInputOf<InputEvents>) => Effect.Effect<boolean, MachineSchemaDecodeError>;
+    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events, ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents, ParentEvents> & EnsureExecutable<States, UnhandledStates, OutputStates> & Machine.RootCompatible<ParentEvents>, state: Machine.Snapshot<States>, event: Machine.EventInputOf<InputEvents>): Effect.Effect<boolean, MachineSchemaDecodeError>;
+};
 /**
  * Plans the next state snapshot synchronously.
  *