@typeonce/effect-machine 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.28.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

@@ -557,6 +557,41 @@ const selectSnapshotByPath = <
 ): Option.Option<SnapshotByIdentifier<State, Path>> =>
   Topology.getSnapshotByPath(snapshot, path) as Option.Option<SnapshotByIdentifier<State, Path>>
 
+type SelectorKind =
+  | "matches"
+  | "matchesChild"
+  | "select"
+  | "selectChild"
+  | "selectSnapshot"
+  | "selectSnapshotChild"
+
+const selectorsByBridge = new WeakMap<object, Map<SelectorKind, Map<string, Atom.Atom<any>>>>()
+
+const cachedSelector = <A>(
+  bridge: object,
+  kind: SelectorKind,
+  path: string,
+  make: () => Atom.Atom<A>
+): Atom.Atom<A> => {
+  let selectorsByKind = selectorsByBridge.get(bridge)
+  if (selectorsByKind === undefined) {
+    selectorsByKind = new Map()
+    selectorsByBridge.set(bridge, selectorsByKind)
+  }
+  let selectorsByPath = selectorsByKind.get(kind)
+  if (selectorsByPath === undefined) {
+    selectorsByPath = new Map()
+    selectorsByKind.set(kind, selectorsByPath)
+  }
+  const cached = selectorsByPath.get(path)
+  if (cached !== undefined) {
+    return cached as Atom.Atom<A>
+  }
+  const selector = make()
+  selectorsByPath.set(path, selector)
+  return selector
+}
+
 export const select = <
   State extends Machine.Machine.AtomicSnapshot<string, unknown>,
   Event,
@@ -571,8 +606,14 @@ export const select = <
 ): Atom.Atom<
   AsyncResult.AsyncResult<Option.Option<SnapshotValueByIdentifier<State, Path>>, StartError | Error>
 > =>
-  Atom.mapResult(self.result, (snapshot) => selectValueByPath(snapshot, path)).pipe(
-    Atom.withEquality(Equal.equals)
+  cachedSelector(
+    self,
+    "select",
+    path,
+    () =>
+      Atom.mapResult(self.result, (snapshot) => selectValueByPath(snapshot, path)).pipe(
+        Atom.withEquality(Equal.equals)
+      )
   )
 
 export const selectSnapshot = <
@@ -589,8 +630,14 @@ export const selectSnapshot = <
 ): Atom.Atom<
   AsyncResult.AsyncResult<Option.Option<SnapshotByIdentifier<State, Path>>, StartError | Error>
 > =>
-  Atom.mapResult(self.result, (snapshot) => selectSnapshotByPath(snapshot, path)).pipe(
-    Atom.withEquality(Equal.equals)
+  cachedSelector(
+    self,
+    "selectSnapshot",
+    path,
+    () =>
+      Atom.mapResult(self.result, (snapshot) => selectSnapshotByPath(snapshot, path)).pipe(
+        Atom.withEquality(Equal.equals)
+      )
   )
 
 export const selectChild = <
@@ -606,10 +653,11 @@ export const selectChild = <
     StartError | RefError<Machine.ChildMachine.Ref<Child>>
   >
 > =>
-  Atom.mapResult(
-    self.result,
-    Option.flatMap((snapshot) => selectValueByPath(snapshot, path))
-  ).pipe(Atom.withEquality(Equal.equals))
+  cachedSelector(self, "selectChild", path, () =>
+    Atom.mapResult(
+      self.result,
+      Option.flatMap((snapshot) => selectValueByPath(snapshot, path))
+    ).pipe(Atom.withEquality(Equal.equals)))
 
 export const selectSnapshotChild = <
   Child extends Machine.ChildMachine.Any,
@@ -624,10 +672,11 @@ export const selectSnapshotChild = <
     StartError | RefError<Machine.ChildMachine.Ref<Child>>
   >
 > =>
-  Atom.mapResult(
-    self.result,
-    Option.flatMap((snapshot) => selectSnapshotByPath(snapshot, path))
-  ).pipe(Atom.withEquality(Equal.equals))
+  cachedSelector(self, "selectSnapshotChild", path, () =>
+    Atom.mapResult(
+      self.result,
+      Option.flatMap((snapshot) => selectSnapshotByPath(snapshot, path))
+    ).pipe(Atom.withEquality(Equal.equals)))
 
 export const matches = <
   State extends Machine.Machine.AtomicSnapshot<string, unknown>,
@@ -641,8 +690,14 @@ export const matches = <
   self: MachineAtom<State, Event, Error, Output, StartError, Emitted>,
   path: Path
 ): Atom.Atom<AsyncResult.AsyncResult<boolean, StartError | Error>> =>
-  Atom.mapResult(self.result, (snapshot) => Option.isSome(Topology.getSnapshotByPath(snapshot, path))).pipe(
-    Atom.withEquality(Equal.equals)
+  cachedSelector(
+    self,
+    "matches",
+    path,
+    () =>
+      Atom.mapResult(self.result, (snapshot) => Option.isSome(Topology.getSnapshotByPath(snapshot, path))).pipe(
+        Atom.withEquality(Equal.equals)
+      )
   )
 
 export const matchesChild = <
@@ -655,10 +710,11 @@ export const matchesChild = <
 ): Atom.Atom<
   AsyncResult.AsyncResult<boolean, StartError | RefError<Machine.ChildMachine.Ref<Child>>>
 > =>
-  Atom.mapResult(
-    self.result,
-    Option.exists((snapshot) => Option.isSome(Topology.getSnapshotByPath(snapshot, path)))
-  ).pipe(Atom.withEquality(Equal.equals))
+  cachedSelector(self, "matchesChild", path, () =>
+    Atom.mapResult(
+      self.result,
+      Option.exists((snapshot) => Option.isSome(Topology.getSnapshotByPath(snapshot, path)))
+    ).pipe(Atom.withEquality(Equal.equals)))
 
 type MachineResumeRequirementsOf<M extends Machine.Machine.Any> = MachineResumeRequirements<
   Machine.Machine.Services<M>,
@@ -745,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:
@@ -845,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

@@ -387,8 +387,8 @@ type EnsureValuedSelectorPath<State, Path extends string> = [Path] extends [Valu
  * Selects the typed value for an active state path.
  *
  * Valid paths and their selected value types are inferred from the bridge.
- * The derived atom suppresses structurally equal updates. Keep the returned
- * atom stable when constructing it inside a component.
+ * The derived atom suppresses structurally equal updates. Repeated calls with
+ * the same bridge and path return the same atom.
  *
  * **Example**
  *
@@ -465,8 +465,8 @@ export const select: {
  * Selects the typed logical snapshot for an active state path.
  *
  * Unlike {@link select}, the selected value retains its child snapshot
- * topology. The derived atom suppresses structurally equal updates. Keep the
- * returned atom stable when constructing it inside a component.
+ * topology. The derived atom suppresses structurally equal updates. Repeated
+ * calls with the same bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.7.0
@@ -519,8 +519,8 @@ export const selectSnapshot: {
  * Selects the typed value for an active state path in a directly owned child.
  *
  * Valid paths and their selected value types are inferred from the child
- * bridge. An inactive child produces `Option.none()`. Keep the returned atom
- * stable when constructing it inside a component.
+ * bridge. An inactive child produces `Option.none()`. Repeated calls with the
+ * same child bridge and path return the same atom.
  *
  * **Example**
  *
@@ -578,7 +578,8 @@ export const selectChild: {
  *
  * An inactive child or state path produces `Option.none()`. Unlike
  * {@link selectChild}, the selected value retains its child snapshot topology.
- * The derived atom suppresses structurally equal updates.
+ * The derived atom suppresses structurally equal updates. Repeated calls with
+ * the same child bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.7.0
@@ -625,8 +626,9 @@ export const selectSnapshotChild: {
  * Returns whether a state path is active.
  *
  * Valid paths are inferred from the bridge snapshot.
- * The derived atom suppresses equal updates. Runtime failures remain in the
- * typed failure channel.
+ * The derived atom suppresses equal updates. Repeated calls with the same
+ * bridge and path return the same atom. Runtime failures remain in the typed
+ * failure channel.
  *
  * **Example**
  *
@@ -697,8 +699,8 @@ export const matches: {
  * Returns whether a state path is active in a directly owned child.
  *
  * Valid paths are inferred from the child bridge snapshot.
- * An inactive child produces `false`. Keep the returned atom stable when
- * constructing it inside a component.
+ * An inactive child produces `false`. Repeated calls with the same child
+ * bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.4.0
@@ -904,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
@@ -927,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:
@@ -1138,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.
  *
@@ -1160,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