Require input on transitions targeting states with an input schema

.changeset/require-input-on-transitions.md

@@ -0,0 +1,26 @@
+---
+'xstate': minor
+---
+
+Transitions that target a state declaring `schemas.input` now **require** an `input` property, enforced at the type level. This applies to `on`, `always`, `after`, `onTimeout`, `onDone`, `onError`, invoke handlers, and the object form of `initial`.
+
+```ts
+const machine = setup({
+  states: {
+    loading: {
+      schemas: { input: z.object({ userId: z.string() }) }
+    }
+  }
+}).createMachine({
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        // Before: LOAD: { target: 'loading' }  — now a type error
+        LOAD: { target: 'loading', input: { userId: 'user-1' } }
+      }
+    },
+    loading: {}
+  }
+});
+```

packages/core/src/setup.ts

@@ -27,6 +27,7 @@ import {
   DoneActorEvent,
   DoneStateEvent,
   ErrorActorEvent,
+  ErrorEvent,
   SystemRegistry,
   RegistryKeyForLogic,
   ActorOptions,
@@ -894,7 +895,14 @@ type StateNodeConfigWithNestedInput<
       Record<string, unknown>,
       TSystemRegistry
     >,
-    'on' | 'always' | 'initial' | 'invoke' | 'onDone'
+    | 'on'
+    | 'always'
+    | 'initial'
+    | 'invoke'
+    | 'onDone'
+    | 'after'
+    | 'onError'
+    | 'onTimeout'
   > & {
     initial?: TStateSchema['states'] extends Record<string, SetupStateSchema>
       ?
@@ -974,6 +982,56 @@ type StateNodeConfigWithNestedInput<
       TSystemRegistry,
       StateInput<TStateSchema>
     >;
+    onError?: StateTransitionConfigOrTarget<
+      TSiblingStateSchemas,
+      StateContext<TStateSchema, TContext>,
+      StateContextShape<TStateSchema, TContextShape>,
+      ErrorEvent,
+      TEvent,
+      TEmitted,
+      TChildren,
+      TMeta,
+      TActionMap,
+      TActorMap,
+      TGuardMap,
+      TDelayMap,
+      TSystemRegistry,
+      StateInput<TStateSchema>
+    >;
+    onTimeout?: StateTransitionConfigOrTarget<
+      TSiblingStateSchemas,
+      StateContext<TStateSchema, TContext>,
+      StateContextShape<TStateSchema, TContextShape>,
+      TEvent,
+      TEvent,
+      TEmitted,
+      TChildren,
+      TMeta,
+      TActionMap,
+      TActorMap,
+      TGuardMap,
+      TDelayMap,
+      TSystemRegistry,
+      StateInput<TStateSchema>
+    >;
+    after?: {
+      [K in NoInfer<TDelays> | number]?: StateTransitionConfigOrTarget<
+        TSiblingStateSchemas,
+        StateContext<TStateSchema, TContext>,
+        StateContextShape<TStateSchema, TContextShape>,
+        TEvent,
+        TEvent,
+        TEmitted,
+        TChildren,
+        TMeta,
+        TActionMap,
+        TActorMap,
+        TGuardMap,
+        TDelayMap,
+        TSystemRegistry,
+        StateInput<TStateSchema>
+      >;
+    };
   },
   TStateSchema['states'] extends Record<string, SetupStateSchema>
     ? StatesWithInput<
@@ -1108,7 +1166,8 @@ type SetupInvokeConfig<
             TActorMap,
             TGuardMap,
             TDelayMap,
-            TSystemRegistry
+            TSystemRegistry,
+            undefined
           >;
           onError?: StateTransitionConfigOrTarget<
             TStateSchemas,
@@ -1123,7 +1182,8 @@ type SetupInvokeConfig<
             TActorMap,
             TGuardMap,
             TDelayMap,
-            TSystemRegistry
+            TSystemRegistry,
+            undefined
           >;
           onSnapshot?: StateTransitionConfigOrTarget<
             TStateSchemas,
@@ -1138,7 +1198,8 @@ type SetupInvokeConfig<
             TActorMap,
             TGuardMap,
             TDelayMap,
-            TSystemRegistry
+            TSystemRegistry,
+            undefined
           >;
           onTimeout?: StateTransitionConfigOrTarget<
             TStateSchemas,
@@ -1153,7 +1214,8 @@ type SetupInvokeConfig<
             TActorMap,
             TGuardMap,
             TDelayMap,
-            TSystemRegistry
+            TSystemRegistry,
+            undefined
           >;
         }
       : never
@@ -1395,6 +1457,26 @@ type StateTransitionFunction<
   false
 > | void;
 
+type TransitionInputFn<
+  TSchema extends SetupStateSchema,
+  TContext extends MachineContext
+> = (
+  args: { context: TContext; event: EventObject } & OutputArg<EventObject>
+) => StateInput<TSchema>;
+
+type TransitionInputRequirement<
+  TSchema extends SetupStateSchema,
+  TContext extends MachineContext
+> = [StateInput<TSchema>] extends [undefined]
+  ? {
+      reenter?: boolean;
+      input?: StateInput<TSchema> | TransitionInputFn<TSchema, TContext>;
+    }
+  : {
+      reenter?: boolean;
+      input: StateInput<TSchema> | TransitionInputFn<TSchema, TContext>;
+    };
+
 type StateTransitionResult<
   TStateSchemas extends Record<string, SetupStateSchema>,
   TContext extends MachineContext,
@@ -1431,51 +1513,43 @@ type StateTransitionResult<
   | {
       [K in keyof TStateSchemas & string]: {
         target: K;
-        reenter?: boolean;
         meta?: TMeta;
-        input?:
-          | StateInput<TStateSchemas[K]>
-          | ((
-              args: {
-                context: TContext;
-                event: EventObject;
-              } & OutputArg<EventObject>
-            ) => StateInput<TStateSchemas[K]>);
-      } & ([TContextShape] extends [
-        StateContextShape<TStateSchemas[K], TContextShape>
-      ]
-        ? {
-            context?: StateTransitionContext<
-              TAllowContextMapper,
-              TContext,
-              TContextShape,
-              StateContextShape<TStateSchemas[K], TContextShape>,
-              StateContext<TStateSchemas[K], TContext>,
-              TExpressionEvent,
-              TChildren,
-              TActionMap,
-              TActorMap,
-              TGuardMap,
-              TDelayMap,
-              TSystemRegistry
-            >;
-          }
-        : {
-            context: StateTransitionContext<
-              TAllowContextMapper,
-              TContext,
-              TContextShape,
-              StateContextShape<TStateSchemas[K], TContextShape>,
-              StateContext<TStateSchemas[K], TContext>,
-              TExpressionEvent,
-              TChildren,
-              TActionMap,
-              TActorMap,
-              TGuardMap,
-              TDelayMap,
-              TSystemRegistry
-            >;
-          });
+      } & TransitionInputRequirement<TStateSchemas[K], TContext> &
+        ([TContextShape] extends [
+          StateContextShape<TStateSchemas[K], TContextShape>
+        ]
+          ? {
+              context?: StateTransitionContext<
+                TAllowContextMapper,
+                TContext,
+                TContextShape,
+                StateContextShape<TStateSchemas[K], TContextShape>,
+                StateContext<TStateSchemas[K], TContext>,
+                TExpressionEvent,
+                TChildren,
+                TActionMap,
+                TActorMap,
+                TGuardMap,
+                TDelayMap,
+                TSystemRegistry
+              >;
+            }
+          : {
+              context: StateTransitionContext<
+                TAllowContextMapper,
+                TContext,
+                TContextShape,
+                StateContextShape<TStateSchemas[K], TContextShape>,
+                StateContext<TStateSchemas[K], TContext>,
+                TExpressionEvent,
+                TChildren,
+                TActionMap,
+                TActorMap,
+                TGuardMap,
+                TDelayMap,
+                TSystemRegistry
+              >;
+            });
     }[keyof TStateSchemas & string]
   | {
       target: Exclude<
@@ -1524,6 +1598,12 @@ type RequiredContextKeys<TCurrentContext, TTargetContext> = {
     : K;
 }[keyof TTargetContext];
 
+type InitialInputFn<
+  TSchema extends SetupStateSchema,
+  TContext extends MachineContext,
+  TEvent extends EventObject
+> = (args: { context: TContext; event: TEvent }) => StateInput<TSchema>;
+
 /** Initial transition with typed input based on target state */
 type InitialTransitionWithInput<
   TStateSchemas extends Record<string, SetupStateSchema>,
@@ -1532,13 +1612,17 @@ type InitialTransitionWithInput<
 > = {
   [K in keyof TStateSchemas & string]: {
     target: K;
-    input?:
-      | StateInput<TStateSchemas[K]>
-      | ((args: {
-          context: TContext;
-          event: TEvent;
-        }) => StateInput<TStateSchemas[K]>);
-  };
+  } & ([StateInput<TStateSchemas[K]>] extends [undefined]
+    ? {
+        input?:
+          | StateInput<TStateSchemas[K]>
+          | InitialInputFn<TStateSchemas[K], TContext, TEvent>;
+      }
+    : {
+        input:
+          | StateInput<TStateSchemas[K]>
+          | InitialInputFn<TStateSchemas[K], TContext, TEvent>;
+      });
 }[keyof TStateSchemas & string];
 
 /** Return type of setup() */

packages/core/src/stateUtils.ts

@@ -1445,7 +1445,8 @@ function microstep(
           { resolveActions: false }
         );
         if (input && targets) {
-          for (const targetNode of targets) {
+          const enteredTargets = targets.filter((t) => statesToEnter.has(t));
+          for (const targetNode of enteredTargets) {
             stateInputMap[targetNode.id] = input;
             stateInputsChanged = true;
           }