@typeonce/effect-machine 0.29.0 → 0.30.0

package/docs/machine-review.md

@@ -71,7 +71,8 @@ Use `useMachineAtom` when one React subtree owns the workflow, including a
 machine with startup input:
 
 ```tsx
-const machine = useMachineAtom(() => machineAtoms.make(processMachine, input))
+const makeProcessMachine = machineAtoms.factory(processMachine)
+const machine = useMachineAtom(() => makeProcessMachine(input))
 ```
 
 Pass the stable machine through props or Context. Startup input is captured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {

package/src/Machine.ts

@@ -9301,6 +9301,120 @@ export const enabled: <
   state: Machine.Snapshot<States>
 ) => ReadonlyArray<Machine.TagOf<Events[number]>> = internal.enabled as any
 
+/**
+ * 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 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>
+} = internal.can as any
+
 /**
  * Plans the next state snapshot synchronously.
  *

package/src/internal/machine/atom.ts

@@ -801,6 +801,9 @@ export const make: {
   return result
 }) as any
 
+export const factory =
+  ((machine: Machine.Machine.Any) => (...args: ReadonlyArray<unknown>) => (make as any)(machine, ...args)) as any
+
 export const resume: {
   <M extends Machine.Machine.Any>(
     machine:
@@ -901,19 +904,25 @@ export const familyChild = (
 
 export const bind = <Services, RuntimeError>(
   runtime: Atom.AtomRuntime<Services, RuntimeError>
-): Bound<Services, RuntimeError> => ({
-  make:
+): Bound<Services, RuntimeError> => {
+  const makeBound =
     ((machine: Machine.Machine.Any, ...args: ReadonlyArray<unknown>) =>
       makeWithRuntime(runtime, machine, args)) as Bound<
         Services,
         RuntimeError
-      >["make"],
-  resume:
-    ((machine: Machine.Machine.Any, snapshot: Machine.Machine.Snapshot<any>) =>
-      resumeWithRuntime(runtime, machine, snapshot)) as Bound<Services, RuntimeError>["resume"],
-  family: ((machine: Machine.Machine.Any, options: FamilyOptions) =>
-    makeFamily(
-      (input) => makeWithRuntime(runtime, machine, [input]),
-      options
-    )) as Bound<Services, RuntimeError>["family"]
-})
+      >["make"]
+  return {
+    make: makeBound,
+    factory:
+      ((machine: Machine.Machine.Any) => (...args: ReadonlyArray<unknown>) =>
+        (makeBound as any)(machine, ...args)) as Bound<Services, RuntimeError>["factory"],
+    resume:
+      ((machine: Machine.Machine.Any, snapshot: Machine.Machine.Snapshot<any>) =>
+        resumeWithRuntime(runtime, machine, snapshot)) as Bound<Services, RuntimeError>["resume"],
+    family: ((machine: Machine.Machine.Any, options: FamilyOptions) =>
+      makeFamily(
+        (input) => makeWithRuntime(runtime, machine, [input]),
+        options
+      )) as Bound<Services, RuntimeError>["family"]
+  }
+}

package/src/internal/machine/machine.ts

@@ -2176,6 +2176,8 @@ export const enabled = <
   state: Machine.Snapshot<States>
 ): ReadonlyArray<Machine.TagOf<Events[number]>> => internalPlanner.enabled(machine as any, state)
 
+export const can = internalPlanner.can
+
 export const plan: <
   const States extends Machine.StateSchemas,
   const Events extends ReadonlyArray<Machine.TaggedSchema>,

package/src/internal/machine/planner.ts

@@ -1876,6 +1876,17 @@ export const enabled = <
   return tags
 }
 
+const canSync = (
+  machine: Machine.Any,
+  state: Machine.Snapshot<any>,
+  event: unknown
+): boolean => {
+  const decodedEvent = decodeEventSync(machine, event)
+  if (isFinalState(machine, state)) return false
+  const configuration = normalizeConfigurationSync(machine, state)
+  return selectEventTransitions(machine, configuration, decodedEvent as any).length > 0
+}
+
 const microstep = <
   const States extends Machine.StateSchemas,
   const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -2300,6 +2311,20 @@ const planningEffect = <A>(thunk: () => A): Effect.Effect<A, InfiniteTransitionE
     }
   })
 
+const schemaEffect = <A>(thunk: () => A): Effect.Effect<A, MachineSchemaDecodeError> =>
+  Effect.suspend(() => {
+    try {
+      return Effect.succeed(thunk())
+    } catch (error) {
+      return error instanceof MachineSchemaDecodeError ? Effect.fail(error) : Effect.die(error)
+    }
+  })
+
+export const can = (...args: readonly [Machine.Any] | readonly [Machine.Any, Machine.Snapshot<any>, unknown]) => {
+  const query = (state: Machine.Snapshot<any>, event: unknown) => schemaEffect(() => canSync(args[0], state, event))
+  return args.length === 1 ? query : query(args[1], args[2])
+}
+
 export const plan = (machine: Machine.Any, state: Machine.Snapshot<any>, event: unknown) =>
   planningEffect(() => planSync(machine as any, state, event as any))
 

package/src/unstable/reactivity/AtomMachine.ts

@@ -906,7 +906,7 @@ type ResumedMachineAtomOf<M extends Machine.Machine.Any, RuntimeError> = Machine
 >
 
 /**
- * An `AtomMachine` factory with one owned Effect runtime.
+ * `AtomMachine` constructors bound to one owned Effect runtime.
  *
  * @category models
  * @since 0.4.0
@@ -929,6 +929,22 @@ export interface Bound<Services, RuntimeError = never> {
     ...args: MachineInputArgsOf<M>
   ) => MachineAtomOf<M, RuntimeError>
 
+  /**
+   * Specializes a machine definition into a reusable bridge constructor.
+   *
+   * Every call creates an independent machine bridge. Startup remains lazy
+   * and begins only when an `AtomRegistry` reads or mounts the bridge.
+   *
+   * @since 0.30.0
+   */
+  readonly factory: <M extends Machine.Machine.Any>(
+    machine:
+      & M
+      & EnsureBoundRequirements<Services, NoInfer<M>>
+      & EnsureMachineExecutable<NoInfer<M>>
+      & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<NoInfer<M>>>
+  ) => (...args: MachineInputArgsOf<M>) => MachineAtomOf<M, RuntimeError>
+
   /** Creates a lazy bridge from a decoded logical snapshot. */
   readonly resume: <M extends Machine.Machine.Any>(
     machine:
@@ -1140,6 +1156,33 @@ export const make: {
   >
 } = internal.make
 
+/**
+ * Specializes a machine definition into a reusable bridge constructor.
+ *
+ * The returned function preserves the machine's startup input arity and exact
+ * bridge type. Every call creates a fresh `MachineAtom`; it does not cache by
+ * input or start the machine before an `AtomRegistry` reads or mounts it.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const makeSearchMachine = AtomMachine.factory(searchMachine)
+ * const search = makeSearchMachine({ query: "effect" })
+ *
+ * type SearchMachineAtom = ReturnType<typeof makeSearchMachine>
+ * ```
+ *
+ * @category constructors
+ * @since 0.30.0
+ */
+export const factory: <M extends Machine.Machine.Any>(
+  machine:
+    & M
+    & EnsureNoExternalRequirements<MachineRequirementsOf<NoInfer<M>>>
+    & EnsureMachineExecutable<NoInfer<M>>
+    & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<NoInfer<M>>>
+) => (...args: MachineInputArgsOf<M>) => MachineAtomOf<M, never> = internal.factory
+
 /**
  * Creates a lazy atom bridge from a decoded logical snapshot.
  *
@@ -1162,11 +1205,12 @@ export const resume: {
 } = internal.resume
 
 /**
- * Creates an `AtomMachine` factory that owns a shared Effect runtime.
+ * Binds `AtomMachine` constructors to a shared Effect runtime.
  *
  * Use this when an application runs many machines from the same service layer.
- * The returned factory keeps runtime provisioning at the composition boundary,
- * while every call to `make` still creates an independent machine bridge.
+ * The returned interface keeps runtime provisioning at the composition seam,
+ * while every call to `make` or a specialized `factory` still creates an
+ * independent machine bridge.
  *
  * @category constructors
  * @since 0.4.0