Added a StateValueFrom helper that can be used to extract valid sta…

…te values from a machine (#3234)

.changeset/stupid-plums-smile.md

@@ -0,0 +1,5 @@
+---
+'xstate': minor
+---
+
+Added a `StateValueFrom` helper that can be used to extract valid state values from a machine. This might specifically be useful with typegen because typegenless `state.matches` accepts `any` anyway.

packages/core/src/types.ts

@@ -7,7 +7,8 @@ import {
   TypegenDisabled,
   ResolveTypegenMeta,
   TypegenConstraint,
-  AreAllImplementationsAssumedToBeProvided
+  AreAllImplementationsAssumedToBeProvided,
+  TypegenEnabled
 } from './typegenTypes';
 
 export type AnyFunction = (...args: any[]) => any;
@@ -1865,3 +1866,19 @@ export type ContextFrom<T> = ReturnTypeOrValue<T> extends infer R
     ? TContext
     : never
   : never;
+
+type Matches<TypegenEnabledArg, TypegenDisabledArg> = {
+  (stateValue: TypegenEnabledArg): any;
+  (stateValue: TypegenDisabledArg): any;
+};
+
+export type StateValueFrom<
+  TMachine extends AnyStateMachine
+> = StateFrom<TMachine>['matches'] extends Matches<
+  infer TypegenEnabledArg,
+  infer TypegenDisabledArg
+>
+  ? TMachine['__TResolvedTypesMeta'] extends TypegenEnabled
+    ? TypegenEnabledArg
+    : TypegenDisabledArg
+  : never;

packages/core/test/typeHelpers.test.ts

@@ -4,7 +4,8 @@ import {
   createMachine,
   EventFrom,
   interpret,
-  MachineOptionsFrom
+  MachineOptionsFrom,
+  StateValueFrom
 } from '../src';
 import { createModel } from '../src/model';
 import { TypegenMeta } from '../src/typegenTypes';
@@ -326,3 +327,30 @@ describe('MachineOptionsFrom', () => {
     acceptMachineOptions(100);
   });
 });
+
+describe('StateValueFrom', () => {
+  it('should return possible state values from a typegened machine', () => {
+    interface TypesMeta extends TypegenMeta {
+      matchesStates: 'a' | 'b' | 'c';
+    }
+
+    const machine = createMachine({
+      tsTypes: {} as TypesMeta
+    });
+
+    function matches(_value: StateValueFrom<typeof machine>) {}
+
+    matches('a');
+    matches('b');
+    // @ts-expect-error
+    matches('unknown');
+  });
+
+  it('should return any from a typegenless machine', () => {
+    const machine = createMachine({});
+
+    function matches(_value: StateValueFrom<typeof machine>) {}
+
+    matches('just anything');
+  });
+});