[core] Add .createStateConfig(…) to machine setup (#5364)

* Add createStateConfig method to setup for strongly typed state configuration

* Add changeset

* add tests

* make it generic

---------

Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com>

Author: davidkpiano

.changeset/four-horses-shine.md

@@ -0,0 +1,32 @@
+---
+'xstate': minor
+---
+
+Added `.createStateConfig(…)` to the setup API. This makes it possible to create state configs that are strongly typed and modular.
+
+```ts
+const lightMachineSetup = setup({
+  // ...
+});
+
+const green = lightMachineSetup.createStateConfig({
+  //...
+});
+
+const yellow = lightMachineSetup.createStateConfig({
+  //...
+});
+
+const red = lightMachineSetup.createStateConfig({
+  //...
+});
+
+const machine = lightMachineSetup.createMachine({
+  initial: 'green',
+  states: {
+    green,
+    yellow,
+    red
+  }
+});
+```

packages/core/src/setup.ts

@@ -17,6 +17,7 @@ import {
   NonReducibleUnknown,
   ParameterizedObject,
   SetupTypes,
+  StateNodeConfig,
   ToChildren,
   ToStateValue,
   UnknownActorLogic,
@@ -145,6 +146,51 @@ export function setup<
 } & {
   [K in RequiredSetupKeys<TChildrenMap>]: unknown;
 }): {
+  /**
+   * Creates a state config that is strongly typed. This state config can be
+   * used to create a machine.
+   *
+   * @example
+   *
+   * ```ts
+   * const lightMachineSetup = setup({
+   *   // ...
+   * });
+   *
+   * const green = lightMachineSetup.createStateConfig({
+   *   on: {
+   *     timer: {
+   *       actions: 'doSomething'
+   *     }
+   *   }
+   * });
+   *
+   * const machine = lightMachineSetup.createMachine({
+   *   initial: 'green',
+   *   states: {
+   *     green,
+   *     yellow,
+   *     red
+   *   }
+   * });
+   * ```
+   */
+  createStateConfig: <
+    TStateConfig extends StateNodeConfig<
+      TContext,
+      TEvent,
+      ToProvidedActor<TChildrenMap, TActors>,
+      ToParameterizedObject<TActions>,
+      ToParameterizedObject<TGuards>,
+      TDelay,
+      TTag,
+      unknown,
+      TEmitted,
+      TMeta
+    >
+  >(
+    config: TStateConfig
+  ) => TStateConfig;
   createMachine: <
     const TConfig extends MachineConfig<
       TContext,
@@ -182,6 +228,7 @@ export function setup<
   >;
 } {
   return {
+    createStateConfig: (config) => config,
     createMachine: (config) =>
       (createMachine as any)(
         { ...config, schemas },

packages/core/test/setup.types.test.ts

@@ -2398,3 +2398,253 @@ describe('setup()', () => {
     ((_accept: ContextFrom<typeof machine>) => {})({ myVar: 'whatever' });
   });
 });
+
+describe('createStateConfig', () => {
+  it('should be able to create a state config with a custom action', () => {
+    const machineSetup = setup({
+      types: {
+        context: {} as {
+          count: number;
+        },
+        events: {} as {
+          type: 'timer';
+          by: number;
+        }
+      },
+      actions: {
+        doSomething: () => {}
+      },
+      guards: {
+        isLightActive: () => true
+      }
+    });
+
+    const green = machineSetup.createStateConfig({
+      on: {
+        timer: {
+          actions: 'doSomething',
+          guard: 'isLightActive'
+        }
+      }
+    });
+
+    const yellow = machineSetup.createStateConfig({
+      on: {
+        timer: {
+          actions: 'doSomething',
+          guard: 'isLightActive'
+        }
+      }
+    });
+
+    const red = machineSetup.createStateConfig({
+      on: {
+        timer: {
+          actions: 'doSomething',
+          guard: 'isLightActive'
+        }
+      }
+    });
+
+    const invalidEvent = machineSetup.createStateConfig({
+      on: {
+        // @ts-expect-error
+        nonsense: {}
+      }
+    });
+
+    const invalidAction = machineSetup.createStateConfig({
+      on: {
+        // @ts-expect-error
+        timer: {
+          // TODO: why is the error not here?
+          actions: 'nonexistent'
+        }
+      }
+    });
+
+    const invalidGuard = machineSetup.createStateConfig({
+      on: {
+        // @ts-expect-error
+        timer: {
+          // TODO: why is the error not here?
+          guard: 'nonexistent'
+        }
+      }
+    });
+
+    machineSetup.createMachine({
+      context: {
+        count: 0
+      },
+      initial: 'green',
+      states: {
+        green,
+        yellow,
+        red,
+        invalidEvent,
+        invalidAction,
+        invalidGuard
+      }
+    });
+  });
+
+  it('should allow matching against valid top state keys of a statechart with nested compound states', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {},
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches('green');
+    snapshot.matches('yellow');
+    snapshot.matches('red');
+  });
+
+  it('should not allow matching against an invalid top state key of a statechart with nested compound states', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {},
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches(
+      // @ts-expect-error
+      'orange'
+    );
+  });
+
+  it('should allow matching against a valid full object value of a statechart with nested compound states', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {},
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches({
+      green: 'wait'
+    });
+  });
+
+  it('should allow matching against a valid non-full object value of a statechart with nested compound states', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {
+          initial: 'steady',
+          states: {
+            steady: {},
+            slowingDown: {}
+          }
+        },
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches({
+      green: 'wait'
+    });
+  });
+
+  it('should not allow matching against a invalid object value of a statechart with nested compound states', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {},
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches({
+      // @ts-expect-error
+      green: 'invalid'
+    });
+  });
+
+  it('should not allow matching against a invalid object value with self-key at value position', () => {
+    const machineSetup = setup({});
+    const green = machineSetup.createStateConfig({
+      initial: 'walk',
+      states: {
+        walk: {},
+        wait: {}
+      }
+    });
+    const machine = machineSetup.createMachine({
+      initial: 'green',
+      states: {
+        green,
+        yellow: {},
+        red: {}
+      }
+    });
+
+    const snapshot = createActor(machine).start().getSnapshot();
+
+    snapshot.matches({
+      // @ts-expect-error
+      green: 'green'
+    });
+  });
+});