Require input in integration packages when defined inside types (#…

…5055) * `useActor` required input when defined * `useMachine` required input when defined * required input in svelte and vue * `useActorRef` input required (but optional `options`) * `useActionRef` options type * rename type to `RequiredActorInstanceOptions` * type tests for required/not required input * required input in `xstate-solid` * added changeset * move machines inside tests * rename type and split changeset --------- Co-authored-by: Mateusz Burzyński <[email protected]>
statelyai · Sep 6, 2024 · ad38c35 · ad38c35
1 parent ec156a3
commit ad38c35
Show file tree

Hide file tree

Showing 19 changed files with 360 additions and 55 deletions.
diff --git a/.changeset/smooth-ravens-exist.md b/.changeset/smooth-ravens-exist.md
@@ -0,0 +1,5 @@
+---
+'xstate': patch
+---
+
+Exported `RequiredActorOptionsKeys` type meant to be used by integration packages like `@xstate/react`
diff --git a/.changeset/smooth-ravens-vanish.md b/.changeset/smooth-ravens-vanish.md
@@ -0,0 +1,43 @@
+---
+'@xstate/svelte': patch
+'@xstate/react': patch
+'@xstate/solid': patch
+'@xstate/vue': patch
+---
+
+Updated types of `useActor`, `useMachine`, and `useActorRef` to require `input` when defined inside `types/input`.
+
+Previously even when `input` was defined inside `types`, `useActor`, `useMachine`, and `useActorRef` would **not** make the input required:
+
+```tsx
+const machine = setup({
+  types: {
+    input: {} as { value: number }
+  }
+}).createMachine({});
+
+function App() {
+  // Event if `input` is not defined, `useMachine` works at compile time, but risks crashing at runtime
+  const _ = useMachine(machine);
+  return <></>;
+}
+```
+
+With this change the above code will show a type error, since `input` is now required:
+
+```tsx
+const machine = setup({
+  types: {
+    input: {} as { value: number }
+  }
+}).createMachine({});
+
+function App() {
+  const _ = useMachine(machine, {
+    input: { value: 1 } // Now input is required at compile time!
+  });
+  return <></>;
+}
+```
+
+This avoids runtime errors when forgetting to pass `input` when defined inside `types`.
diff --git a/packages/core/src/createActor.ts b/packages/core/src/createActor.ts
@@ -746,7 +746,7 @@ export class Actor<TLogic extends AnyActorLogic>
   }
 }
 
-type RequiredOptions<TLogic extends AnyActorLogic> =
+export type RequiredActorOptionsKeys<TLogic extends AnyActorLogic> =
   undefined extends InputFrom<TLogic> ? never : 'input';
 
 /**
@@ -792,10 +792,10 @@ export function createActor<TLogic extends AnyActorLogic>(
   ...[options]: ConditionalRequired<
     [
       options?: ActorOptions<TLogic> & {
-        [K in RequiredOptions<TLogic>]: unknown;
+        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
       }
     ],
-    IsNotNever<RequiredOptions<TLogic>>
+    IsNotNever<RequiredActorOptionsKeys<TLogic>>
   >
 ): Actor<TLogic> {
   return new Actor(logic, options);

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -1,15 +1,12 @@
-export { SimulatedClock } from './SimulatedClock.ts';
-export { isMachineSnapshot, type MachineSnapshot } from './State.ts';
-export { StateMachine } from './StateMachine.ts';
-export { StateNode } from './StateNode.ts';
 export * from './actions.ts';
 export * from './actors/index.ts';
 export { assertEvent } from './assert.ts';
 export {
   Actor,
   createActor,
   interpret,
-  type Interpreter
+  type Interpreter,
+  type RequiredActorOptionsKeys as RequiredActorOptionsKeys
 } from './createActor.ts';
 export { createMachine } from './createMachine.ts';
 export { getInitialSnapshot, getNextSnapshot } from './getNextSnapshot.ts';
@@ -21,7 +18,11 @@ export type {
   InspectionEvent
 } from './inspection.ts';
 export { setup } from './setup.ts';
+export { SimulatedClock } from './SimulatedClock.ts';
 export { type Spawner } from './spawn.ts';
+export { isMachineSnapshot, type MachineSnapshot } from './State.ts';
+export { StateMachine } from './StateMachine.ts';
+export { StateNode } from './StateNode.ts';
 export { getStateNodes } from './stateUtils.ts';
 export type { ActorSystem } from './system.ts';
 export { toPromise } from './toPromise.ts';

diff --git a/packages/core/test/types.test.ts b/packages/core/test/types.test.ts
@@ -10,28 +10,23 @@ import {
 } from '../src/actors';
 import {
   ActorRefFrom,
-  InputFrom,
+  ActorRefFromLogic,
+  AnyActorLogic,
   MachineContext,
   ProvidedActor,
   Spawner,
   StateMachine,
+  UnknownActorRef,
   assign,
   createActor,
   createMachine,
   enqueueActions,
   not,
   sendTo,
+  setup,
   spawnChild,
   stateIn,
-  setup,
-  toPromise,
-  UnknownActorRef,
-  AnyActorLogic,
-  ActorRef,
-  SnapshotFrom,
-  EmittedFrom,
-  EventFrom,
-  ActorRefFromLogic
+  toPromise
 } from '../src/index';
 
 function noop(_x: unknown) {
@@ -3526,6 +3521,27 @@ describe('input', () => {
       }
     });
   });
+
+  it('should require input to be specified when defined', () => {
+    const machine = createMachine({
+      types: {
+        input: {} as {
+          count: number;
+        }
+      }
+    });
+
+    // @ts-expect-error
+    createActor(machine);
+  });
+
+  it('should not require input when not defined', () => {
+    const machine = createMachine({
+      types: {}
+    });
+
+    createActor(machine);
+  });
 });
 
 describe('guards', () => {

diff --git a/packages/xstate-react/src/useActor.ts b/packages/xstate-react/src/useActor.ts
@@ -1,13 +1,28 @@
 import isDevelopment from '#is-development';
 import { useCallback, useEffect } from 'react';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
-import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom } from 'xstate';
+import {
+  Actor,
+  ActorOptions,
+  AnyActorLogic,
+  SnapshotFrom,
+  type ConditionalRequired,
+  type IsNotNever,
+  type RequiredActorOptionsKeys
+} from 'xstate';
 import { stopRootWithRehydration } from './stopRootWithRehydration.ts';
 import { useIdleActorRef } from './useActorRef.ts';
 
 export function useActor<TLogic extends AnyActorLogic>(
   logic: TLogic,
-  options: ActorOptions<TLogic> = {}
+  ...[options]: ConditionalRequired<
+    [
+      options?: ActorOptions<TLogic> & {
+        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
+      }
+    ],
+    IsNotNever<RequiredActorOptionsKeys<TLogic>>
+  >
 ): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>] {
   if (
     isDevelopment &&

diff --git a/packages/xstate-react/src/useActorRef.ts b/packages/xstate-react/src/useActorRef.ts
@@ -8,13 +8,23 @@ import {
   Observer,
   SnapshotFrom,
   createActor,
-  toObserver
+  toObserver,
+  type ConditionalRequired,
+  type IsNotNever,
+  type RequiredActorOptionsKeys
 } from 'xstate';
 import { stopRootWithRehydration } from './stopRootWithRehydration';
 
 export function useIdleActorRef<TLogic extends AnyActorLogic>(
   logic: TLogic,
-  options: Partial<ActorOptions<TLogic>>
+  ...[options]: ConditionalRequired<
+    [
+      options?: ActorOptions<TLogic> & {
+        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
+      }
+    ],
+    IsNotNever<RequiredActorOptionsKeys<TLogic>>
+  >
 ): Actor<TLogic> {
   let [[currentConfig, actorRef], setCurrent] = useState(() => {
     const actorRef = createActor(logic, options);
@@ -44,10 +54,23 @@ export function useIdleActorRef<TLogic extends AnyActorLogic>(
 
 export function useActorRef<TLogic extends AnyActorLogic>(
   machine: TLogic,
-  options: ActorOptions<TLogic> = {},
-  observerOrListener?:
-    | Observer<SnapshotFrom<TLogic>>
-    | ((value: SnapshotFrom<TLogic>) => void)
+  ...[options, observerOrListener]: IsNotNever<
+    RequiredActorOptionsKeys<TLogic>
+  > extends true
+    ? [
+        options: ActorOptions<TLogic> & {
+          [K in RequiredActorOptionsKeys<TLogic>]: unknown;
+        },
+        observerOrListener?:
+          | Observer<SnapshotFrom<TLogic>>
+          | ((value: SnapshotFrom<TLogic>) => void)
+      ]
+    : [
+        options?: ActorOptions<TLogic>,
+        observerOrListener?:
+          | Observer<SnapshotFrom<TLogic>>
+          | ((value: SnapshotFrom<TLogic>) => void)
+      ]
 ): Actor<TLogic> {
   const actorRef = useIdleActorRef(machine, options);
 

diff --git a/packages/xstate-react/src/useMachine.ts b/packages/xstate-react/src/useMachine.ts
@@ -1,10 +1,25 @@
-import { Actor, ActorOptions, AnyStateMachine, StateFrom } from 'xstate';
+import {
+  Actor,
+  ActorOptions,
+  AnyStateMachine,
+  StateFrom,
+  type ConditionalRequired,
+  type IsNotNever,
+  type RequiredActorOptionsKeys
+} from 'xstate';
 import { useActor } from './useActor.ts';
 
 /** @alias useActor */
 export function useMachine<TMachine extends AnyStateMachine>(
   machine: TMachine,
-  options: ActorOptions<TMachine> = {}
+  ...[options]: ConditionalRequired<
+    [
+      options?: ActorOptions<TMachine> & {
+        [K in RequiredActorOptionsKeys<TMachine>]: unknown;
+      }
+    ],
+    IsNotNever<RequiredActorOptionsKeys<TMachine>>
+  >
 ): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>] {
   return useActor(machine, options);
 }
diff --git a/packages/xstate-react/test/types.test.tsx b/packages/xstate-react/test/types.test.tsx
@@ -1,7 +1,11 @@
 import { render } from '@testing-library/react';
 import { ActorRefFrom, assign, createMachine, setup } from 'xstate';
-import { useMachine, useSelector } from '../src/index.ts';
-import { useEffect, useMemo } from 'react';
+import {
+  useActor,
+  useActorRef,
+  useMachine,
+  useSelector
+} from '../src/index.ts';
 
 describe('useMachine', () => {
   interface YesNoContext {
@@ -121,6 +125,79 @@ describe('useMachine', () => {
   });
 });
 
+describe('useActor', () => {
+  it('should require input to be specified when defined', () => {
+    const withInputMachine = createMachine({
+      types: {} as { input: { value: number } },
+      initial: 'idle',
+      states: {
+        idle: {}
+      }
+    });
+
+    const Component = () => {
+      // @ts-expect-error
+      const _ = useActor(withInputMachine);
+      return <></>;
+    };
+
+    render(<Component />);
+  });
+
+  it('should not require input when not defined', () => {
+    const noInputMachine = createMachine({
+      types: {} as {},
+      initial: 'idle',
+      states: {
+        idle: {}
+      }
+    });
+    const Component = () => {
+      const _ = useActor(noInputMachine);
+      return <></>;
+    };
+
+    render(<Component />);
+  });
+});
+
+describe('useActorRef', () => {
+  it('should require input to be specified when defined', () => {
+    const withInputMachine = createMachine({
+      types: {} as { input: { value: number } },
+      initial: 'idle',
+      states: {
+        idle: {}
+      }
+    });
+
+    const Component = () => {
+      // @ts-expect-error
+      const _ = useActorRef(withInputMachine);
+      return <></>;
+    };
+
+    render(<Component />);
+  });
+
+  it('should not require input when not defined', () => {
+    const noInputMachine = createMachine({
+      types: {} as {},
+      initial: 'idle',
+      states: {
+        idle: {}
+      }
+    });
+
+    const Component = () => {
+      const _ = useActorRef(noInputMachine);
+      return <></>;
+    };
+
+    render(<Component />);
+  });
+});
+
 it('useMachine types work for machines with a specified id and state with an after property #5008', () => {
   // https://github.com/statelyai/xstate/issues/5008
   const cheatCodeMachine = setup({}).createMachine({

diff --git a/packages/xstate-react/test/useActorRef.test.tsx b/packages/xstate-react/test/useActorRef.test.tsx
@@ -1,3 +1,8 @@
+import {
+  fireEvent,
+  screen,
+  waitFor as testWaitFor
+} from '@testing-library/react';
 import * as React from 'react';
 import {
   ActorRefFrom,
@@ -9,11 +14,6 @@ import {
   sendParent,
   sendTo
 } from 'xstate';
-import {
-  fireEvent,
-  screen,
-  waitFor as testWaitFor
-} from '@testing-library/react';
 import { useActorRef, useMachine, useSelector } from '../src/index.ts';
 import { describeEachReactMode } from './utils.tsx';