Declare always and onDone targets

Author: SandroMaglione

.changeset/quiet-spiders-inspect.md

@@ -2,4 +2,4 @@
 "@typeonce/effect-machine": minor
 ---
 
-Add public getters for inspecting compiled state nodes, registered transition handlers, declared transition targets, and the active state configuration of a snapshot. Event handlers may declare an upper bound of target paths that is checked against inferred and runtime results.
+Add public getters for inspecting compiled state nodes, registered transition handlers, declared transition targets, and the active state configuration of a snapshot. Event, eventless, and completion handlers may declare an upper bound of target paths that is checked against inferred and runtime results.

src/Machine.ts

@@ -2055,10 +2055,10 @@ export declare namespace Machine {
    *
    * **Details**
    *
-   * Event handlers may declare an upper bound of possible target paths. A
-   * handler without that declaration is explicitly reported as dynamic. The
-   * source, trigger, and reentry behavior are available without executing the
-   * handler.
+   * Event, eventless, and completion handlers may declare an upper bound of
+   * possible target paths. A handler without that declaration is explicitly
+   * reported as dynamic. The source, trigger, and reentry behavior are
+   * available without executing the handler.
    *
    * @category models
    * @since 4.0.0
@@ -3417,7 +3417,7 @@ export declare namespace Machine {
    * @since 4.0.0
    */
   export type AlwaysReturn<Config> = Config extends { readonly always?: infer Always }
-    ? NonNullable<Always> extends (...args: any) => infer Ret ? Ret : never
+    ? EventTransitionReturn<NonNullable<Always>>
     : never
   /**
    * Extracts the return value from a state completion transition.
@@ -3426,7 +3426,7 @@ export declare namespace Machine {
    * @since 4.0.0
    */
   export type DoneReturn<Config> = Config extends { readonly onDone?: infer OnDone }
-    ? NonNullable<OnDone> extends (...args: any) => infer Ret ? Ret : never
+    ? EventTransitionReturn<NonNullable<OnDone>>
     : never
   /**
    * Extracts the return value from a final state output function.
@@ -3596,8 +3596,24 @@ export declare namespace Machine {
     readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>
     readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>
     readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>
-    readonly always?: (context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>
-    readonly onDone?: (context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>
+    readonly always?:
+      | ((context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>)
+      | {
+        /** Statically declared upper bound of possible target paths. */
+        readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>
+        readonly transition: (
+          context: AlwaysContext<States, Events, Emits, StateId>
+        ) => HandlerResult<States, any, any>
+      }
+    readonly onDone?:
+      | ((context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, any, any>)
+      | {
+        /** Statically declared upper bound of possible target paths. */
+        readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>
+        readonly transition: (
+          context: DoneContext<States, Events, Emits, StateId>
+        ) => HandlerResult<States, any, any>
+      }
     readonly on?: {
       readonly [EventTag in TagOf<Events[number]>]?:
         | ((
@@ -3935,6 +3951,22 @@ export declare namespace Machine {
     : unknown
     : unknown
 
+  type HandlerDirectTargetValidation<
+    StateId extends string,
+    Config,
+    Trigger extends "always" | "onDone",
+    Transition = Config extends { readonly [Key in Trigger]?: infer Value } ? NonNullable<Value> : never,
+    Undeclared extends string = UndeclaredTransitionTarget<Transition>
+  > = Trigger extends keyof Config ? [Undeclared] extends [never] ? unknown
+    : {
+      readonly [Key in Trigger]: HandlerValidationError<
+        "Transition returns a target not listed in targets",
+        StateId,
+        readonly [trigger: Trigger, target: Undeclared]
+      >
+    }
+    : unknown
+
   type HandlerDepth = readonly [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown]
 
   type HandlerNextDepth<Depth extends ReadonlyArray<unknown>> = Depth extends
@@ -4024,6 +4056,8 @@ export declare namespace Machine {
     & HandlerUnknownConfigKeyValidation<StateId, Config>
     & HandlerOnKeyValidation<Events, StateId, Config>
     & HandlerOnTargetValidation<StateId, Config>
+    & HandlerDirectTargetValidation<StateId, Config, "always">
+    & HandlerDirectTargetValidation<StateId, Config, "onDone">
     & HandlerInvokeOutputValidation<Events, StateId, Config>
     & HandlerInvokeEmitsValidation<Events, StateId, Config>
     & HandlerInvokeSnapshotValidation<Events, StateId, Config>
@@ -4494,8 +4528,22 @@ export declare namespace Machine {
     readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>
     readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>
     readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>
-    readonly always?: (context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>
-    readonly onDone?: (context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>
+    readonly always?:
+      | ((context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>)
+      | {
+        readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>
+        readonly transition: (
+          context: AlwaysContext<States, Events, Emits, StateId>
+        ) => HandlerResult<States, E, R>
+      }
+    readonly onDone?:
+      | ((context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>)
+      | {
+        readonly targets?: ReadonlyArray<StateNodeIdentifier<States>>
+        readonly transition: (
+          context: DoneContext<States, Events, Emits, StateId>
+        ) => HandlerResult<States, E, R>
+      }
     readonly output?:
       | ((context: FinalOutputContext<States, Events, StateId>) => unknown)
       | ((context: ParallelOutputContext<States, Events, StateId>) => unknown)
@@ -4550,6 +4598,29 @@ const cloneWithHandlers = (
   return machine
 }
 
+const validateTransitionTargets = (
+  stateNodes: Machine.StateNodes,
+  path: string,
+  trigger: PropertyKey,
+  transition: unknown
+): void => {
+  if (typeof transition !== "object" || transition === null || !hasProperty(transition, "targets")) {
+    return
+  }
+  if (!Array.isArray(transition.targets)) {
+    throw new Error(
+      `Machine expected transition targets for state "${path}" on "${String(trigger)}" to be an array`
+    )
+  }
+  for (const target of transition.targets) {
+    if (typeof target !== "string" || !stateNodes.byPath.has(target)) {
+      throw new Error(
+        `Machine transition for state "${path}" on "${String(trigger)}" declares unknown target "${String(target)}"`
+      )
+    }
+  }
+}
+
 const flattenHandlers = (
   handlers: Record<PropertyKey, Machine.AnyStateConfig>,
   stateNodes: Machine.StateNodes,
@@ -4570,24 +4641,11 @@ const flattenHandlers = (
     const on = stateConfig.on
     if (typeof on === "object" && on !== null) {
       for (const event of Reflect.ownKeys(on)) {
-        const transition = (on as Record<PropertyKey, unknown>)[event]
-        if (typeof transition !== "object" || transition === null || !hasProperty(transition, "targets")) {
-          continue
-        }
-        if (!Array.isArray(transition.targets)) {
-          throw new Error(
-            `Machine expected transition targets for state "${path}" on "${String(event)}" to be an array`
-          )
-        }
-        for (const target of transition.targets) {
-          if (typeof target !== "string" || !stateNodes.byPath.has(target)) {
-            throw new Error(
-              `Machine transition for state "${path}" on "${String(event)}" declares unknown target "${String(target)}"`
-            )
-          }
-        }
+        validateTransitionTargets(stateNodes, path, event, (on as Record<PropertyKey, unknown>)[event])
       }
     }
+    validateTransitionTargets(stateNodes, path, "always", stateConfig.always)
+    validateTransitionTargets(stateNodes, path, "done", stateConfig.onDone)
     handlers[path] = stateConfig as Machine.AnyStateConfig
     if (childConfig !== undefined) {
       const node = Model.getStateNodeDefinition(path, states[key])
@@ -5978,8 +6036,9 @@ export const stateNodes = <M extends Machine.Any>(
  *
  * Event handlers retain their handler-key order within each source state and
  * are followed by eventless and completion handlers. This function does not
- * execute handlers. Event handlers with a `targets` declaration expose those
- * possible paths; handlers without one remain dynamic.
+ * execute handlers. Object-form event, eventless, and completion handlers with
+ * a `targets` declaration expose those possible paths; handlers without one
+ * remain dynamic.
  *
  * @category getters
  * @since 4.0.0

src/internal/machineModel.ts

@@ -358,6 +358,11 @@ export const compileStateNodes = (states: Machine.StateSchemas): Machine.StateNo
 
 const dynamicTransitionTargets = { type: "dynamic" } as const
 
+const transitionTargets = (handler: unknown): Machine.TransitionTargets =>
+  typeof handler === "object" && handler !== null && "targets" in handler && handler.targets !== undefined
+    ? { type: "declared", paths: Array.from(handler.targets as ReadonlyArray<string>) }
+    : dynamicTransitionTargets
+
 export const transitionDefinitions = (
   machine: Machine.Any
 ): ReadonlyArray<Machine.TransitionDefinition> => {
@@ -373,25 +378,23 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "event", event },
         reenter: typeof handler === "object" && handler !== null && handler.reenter === true,
-        targets: typeof handler === "object" && handler !== null && handler.targets !== undefined
-          ? { type: "declared", paths: Array.from(handler.targets) }
-          : dynamicTransitionTargets
+        targets: transitionTargets(handler)
       })
     }
     if (config.always !== undefined) {
       definitions.push({
         source: node.path,
         trigger: { type: "always" },
         reenter: false,
-        targets: dynamicTransitionTargets
+        targets: transitionTargets(config.always)
       })
     }
     if (config.onDone !== undefined) {
       definitions.push({
         source: node.path,
         trigger: { type: "done" },
         reenter: false,
-        targets: dynamicTransitionTargets
+        targets: transitionTargets(config.onDone)
       })
     }
   }

src/internal/machinePlanner.ts

@@ -239,7 +239,7 @@ type MicrostepTransition<States extends Machine.StateSchemas, E, R, Context> = {
   readonly transition: TransitionHandler<States, E, R, Context>
 }
 
-const normalizeEventTransition = <States extends Machine.StateSchemas, E, R, Context>(
+const normalizeTransition = <States extends Machine.StateSchemas, E, R, Context>(
   transition: EventTransition<States, E, R, Context> | undefined
 ): MicrostepTransition<States, E, R, Context> | undefined => {
   if (transition === undefined) {
@@ -481,6 +481,7 @@ const resolveHistoryTarget = Effect.fnUntraced(function*(
 type SelectedTransition<States extends Machine.StateSchemas, E, R, Context> = {
   readonly sourcePath: string
   readonly leafPath: string
+  readonly trigger: Machine.TransitionTrigger
   readonly transition: MicrostepTransition<States, E, R, Context>
   readonly context: Context
 }
@@ -703,14 +704,15 @@ const selectAlwaysTransitions = <
   const selectedSources = new Set<string>()
   for (const leaf of getActiveLeafPaths(machine, configuration)) {
     for (const path of getLeafCandidatePaths(machine, leaf)) {
-      const always = machine.handlers[path]?.always
+      const always = normalizeTransition(machine.handlers[path]?.always)
       if (always !== undefined) {
         if (!selectedSources.has(path)) {
           selectedSources.add(path)
           selected.push({
             sourcePath: path,
             leafPath: leaf,
-            transition: { reenter: false, targets: undefined, transition: always } as MicrostepTransition<
+            trigger: { type: "always" },
+            transition: always as unknown as MicrostepTransition<
               States,
               E,
               R,
@@ -771,13 +773,14 @@ const selectDoneTransitions = <
   > = []
   const selectedSources = new Set<string>()
   for (const completion of completions) {
-    const onDone = machine.handlers[completion.path]?.onDone
+    const onDone = normalizeTransition(machine.handlers[completion.path]?.onDone)
     if (onDone !== undefined && !selectedSources.has(completion.path)) {
       selectedSources.add(completion.path)
       selected.push({
         sourcePath: completion.path,
         leafPath: getActiveLeafPathFrom(machine, configuration, completion.path),
-        transition: { reenter: false, targets: undefined, transition: onDone } as MicrostepTransition<
+        trigger: { type: "done" },
+        transition: onDone as unknown as MicrostepTransition<
           States,
           E,
           R,
@@ -833,13 +836,14 @@ const selectEventTransitions = <
   const selectedSources = new Set<string>()
   for (const leaf of getActiveLeafPaths(machine, configuration)) {
     for (const path of getLeafCandidatePaths(machine, leaf)) {
-      const transition = normalizeEventTransition(machine.handlers[path]?.on?.[event._tag])
+      const transition = normalizeTransition(machine.handlers[path]?.on?.[event._tag])
       if (transition !== undefined) {
         if (!selectedSources.has(path)) {
           selectedSources.add(path)
           selected.push({
             sourcePath: path,
             leafPath: leaf,
+            trigger: { type: "event", event: event._tag },
             transition: transition as unknown as MicrostepTransition<
               States,
               E,
@@ -884,7 +888,7 @@ const getTargetNodePath = <const States extends Machine.StateSchemas>(
 
 const validateDeclaredTransitionTarget = (
   sourcePath: string,
-  event: unknown,
+  trigger: Machine.TransitionTrigger,
   declaredTargets: ReadonlyArray<string> | undefined,
   target: unknown
 ): void => {
@@ -895,10 +899,9 @@ const validateDeclaredTransitionTarget = (
     ? String(target.path)
     : "<unknown>"
   if (!declaredTargets.some((path) => actual === path || actual.startsWith(`${path}.`))) {
+    const triggerLabel = trigger.type === "event" ? String(trigger.event) : trigger.type
     throw new Error(
-      `Machine transition from "${sourcePath}" on "${
-        String(event)
-      }" returned target "${actual}" outside declared targets: ${
+      `Machine transition from "${sourcePath}" on "${triggerLabel}" returned target "${actual}" outside declared targets: ${
         declaredTargets.length === 0 ? "none" : declaredTargets.map((path) => `"${path}"`).join(", ")
       }`
     )
@@ -1002,7 +1005,7 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
       | Machine.Target<States, Machine.StateIdentifier<States>>
   validateDeclaredTransitionTarget(
     selection.sourcePath,
-    (selection.context as { readonly event: { readonly _tag: unknown } }).event._tag,
+    selection.trigger,
     selection.transition.targets,
     unresolvedTarget
   )