Add TagsFrom helper type (#3835)

* add TagsFrom helper type

* simplify TagsFrom helper

* move TagsFrom tests to typegenTypes

* remove unused import

* Apply suggestions from code review

---------

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

.changeset/mean-oranges-dress.md

@@ -0,0 +1,31 @@
+---
+'xstate': minor
+---
+
+The new `TagsFrom` helper type extracts the type of `tags` from a state machine when typegen is enabled:
+
+```ts
+const machine = createMachine({
+  // `tags` attached to machine via typegen
+  tsTypes: {} as import('./machine.typegen').Typegen0,
+  tags: ['a', 'b'],
+  states: {
+    idle: { tags: 'c' }
+  },
+});
+
+type Tags = TagsFrom<typeof machine>; // 'a' | 'b' | 'c'
+```
+
+If typegen is not enabled, `TagsFrom` returns `string`:
+
+```ts
+const machine = createMachine({
+  tags: ['a', 'b'],
+  states: {
+    idle: { tags: 'c' }
+  }
+});
+
+type Tags = TagsFrom<typeof machine>; // string
+```

packages/core/src/types.ts

@@ -155,8 +155,9 @@ type SimpleActionsOf<T extends BaseActionObject> = ActionObject<
 /**
  * Events that do not require payload
  */
-export type SimpleEventsOf<TEvent extends EventObject> =
-  ExtractWithSimpleSupport<TEvent>;
+export type SimpleEventsOf<
+  TEvent extends EventObject
+> = ExtractWithSimpleSupport<TEvent>;
 
 export type BaseAction<
   TContext,
@@ -1984,18 +1985,23 @@ type Matches<TypegenEnabledArg, TypegenDisabledArg> = {
   (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;
+export type StateValueFrom<
+  TMachine extends AnyStateMachine
+> = StateFrom<TMachine>['matches'] extends Matches<
+  infer TypegenEnabledArg,
+  infer TypegenDisabledArg
+>
+  ? TMachine['__TResolvedTypesMeta'] extends TypegenEnabled
+    ? TypegenEnabledArg
+    : TypegenDisabledArg
+  : never;
 
 export type PredictableActionArgumentsExec = (
   action: ActionObject<unknown, EventObject>,
   context: unknown,
   _event: SCXML.Event<EventObject>
 ) => void;
+
+export type TagsFrom<TMachine extends AnyStateMachine> = Parameters<
+  StateFrom<TMachine>['hasTag']
+>[0];

packages/core/test/typeHelpers.test.ts

@@ -6,7 +6,8 @@ import {
   EventFrom,
   interpret,
   MachineOptionsFrom,
-  StateValueFrom
+  StateValueFrom,
+  TagsFrom
 } from '../src';
 import { createModel } from '../src/model';
 import { TypegenMeta } from '../src/typegenTypes';
@@ -428,3 +429,38 @@ describe('EmittedFrom', () => {
     acceptState("isn't any");
   });
 });
+
+describe('tags', () => {
+  it('derives tags from StateMachine when typegen is enabled', () => {
+    interface TypesMeta extends TypegenMeta {
+      tags: 'a' | 'b' | 'c';
+    }
+    const machine = createMachine({
+      tsTypes: {} as TypesMeta
+    });
+
+    type Tags = TagsFrom<typeof machine>;
+
+    const acceptTag = (_tag: Tags) => {};
+
+    acceptTag('a');
+    acceptTag('b');
+    acceptTag('c');
+    // @ts-expect-error d is not a valid tag
+    acceptTag('d');
+  });
+
+  it('derives string from StateMachine without typegen', () => {
+    const machine = createMachine({});
+
+    type Tags = TagsFrom<typeof machine>;
+
+    const acceptTag = (_tag: Tags) => {};
+
+    acceptTag('a');
+    acceptTag('b');
+    acceptTag('c');
+    // d is a valid tag, as is any string
+    acceptTag('d');
+  });
+});