[v5] Restrict context to object

.changeset/cold-steaks-drop.md

@@ -0,0 +1,24 @@
+---
+'xstate': major
+---
+
+The machine's `context` is now restricted to an `object`. This was the most common usage, but now the typings prevent `context` from being anything but an object:
+
+```ts
+const machine = createMachine({
+  // This will produce the TS error:
+  // "Type 'string' is not assignable to type 'object | undefined'"
+  context: 'some string'
+});
+```
+
+If `context` is `undefined`, it will now default to an empty object `{}`:
+
+```ts
+const machine = createMachine({
+  // No context
+});
+
+machine.initialState.context;
+// => {}
+```

packages/core/src/Actor.ts

@@ -6,7 +6,8 @@ import {
   InterpreterOptions,
   ActorRef,
   Lazy,
-  BaseActorRef
+  BaseActorRef,
+  MachineContext
 } from './types';
 import { StateMachine } from './StateMachine';
 import { State } from './State';
@@ -68,7 +69,10 @@ export function fromCallback<TEvent extends EventObject>(
   );
 }
 
-export function fromMachine<TContext, TEvent extends EventObject>(
+export function fromMachine<
+  TContext extends MachineContext,
+  TEvent extends EventObject
+>(
   machine: StateMachine<TContext, TEvent>,
   name: string,
   options?: Partial<InterpreterOptions>

packages/core/src/Machine.ts

@@ -3,30 +3,31 @@ import {
   MachineConfig,
   EventObject,
   AnyEventObject,
-  Typestate
+  Typestate,
+  MachineContext
 } from './types';
 import { StateMachine } from './StateMachine';
 import { Model, ModelContextFrom, ModelEventsFrom } from './model';
 
 export function createMachine<
   TModel extends Model<any, any, any>,
-  TContext = ModelContextFrom<TModel>,
+  TContext extends MachineContext = ModelContextFrom<TModel>,
   TEvent extends EventObject = ModelEventsFrom<TModel>,
   TTypestate extends Typestate<TContext> = { value: any; context: TContext }
 >(
   config: MachineConfig<TContext, TEvent>,
   options?: Partial<MachineImplementations<TContext, TEvent>>
 ): StateMachine<TContext, TEvent, TTypestate>;
 export function createMachine<
-  TContext,
+  TContext extends MachineContext,
   TEvent extends EventObject = AnyEventObject,
   TTypestate extends Typestate<TContext> = { value: any; context: TContext }
 >(
   config: MachineConfig<TContext, TEvent>,
   options?: Partial<MachineImplementations<TContext, TEvent>>
 ): StateMachine<TContext, TEvent, TTypestate>;
 export function createMachine<
-  TContext,
+  TContext extends MachineContext,
   TEvent extends EventObject = AnyEventObject,
   TTypestate extends Typestate<TContext> = { value: any; context: TContext }
 >(

packages/core/src/State.ts

@@ -9,15 +9,16 @@ import {
   Typestate,
   HistoryValue,
   NullEvent,
-  ActorRef
+  ActorRef,
+  MachineContext
 } from './types';
 import { matchesState, keys, isString } from './utils';
 import { StateNode } from './StateNode';
 import { isInFinalState, nextEvents, getMeta } from './stateUtils';
 import { initEvent } from './actions';
 
 export function isState<
-  TContext,
+  TContext extends MachineContext,
   TEvent extends EventObject,
   TTypestate extends Typestate<TContext> = { value: any; context: TContext }
 >(state: object | string): state is State<TContext, TEvent, TTypestate> {
@@ -27,17 +28,20 @@ export function isState<
 
   return 'value' in state && 'history' in state;
 }
-export function bindActionToState<TC, TE extends EventObject>(
-  action: ActionObject<TC, TE>,
-  state: State<TC, TE, any>
-): ActionObject<TC, TE> {
+export function bindActionToState<
+  TContext extends MachineContext,
+  TEvent extends EventObject
+>(
+  action: ActionObject<TContext, TEvent>,
+  state: State<TContext, TEvent, any>
+): ActionObject<TContext, TEvent> {
   const { exec } = action;
-  const boundAction: ActionObject<TC, TE> = {
+  const boundAction: ActionObject<TContext, TEvent> = {
     ...action,
     exec:
       exec !== undefined
         ? () =>
-            exec(state.context, state.event as TE, {
+            exec(state.context, state.event as TEvent, {
               action,
               state,
               _event: state._event
@@ -49,7 +53,7 @@ export function bindActionToState<TC, TE extends EventObject>(
 }
 
 export class State<
-  TContext,
+  TContext extends MachineContext,
   TEvent extends EventObject = EventObject,
   TTypestate extends Typestate<TContext> = { value: any; context: TContext }
 > {
@@ -95,15 +99,18 @@ export class State<
    * @param stateValue
    * @param context
    */
-  public static from<TC, TE extends EventObject = EventObject>(
-    stateValue: State<TC, TE, any> | StateValue,
-    context?: TC | undefined
-  ): State<TC, TE, any> {
+  public static from<
+    TContext extends MachineContext,
+    TEvent extends EventObject = EventObject
+  >(
+    stateValue: State<TContext, TEvent, any> | StateValue,
+    context: TContext = {} as TContext
+  ): State<TContext, TEvent, any> {
     if (stateValue instanceof State) {
       if (stateValue.context !== context) {
-        return new State<TC, TE>({
+        return new State<TContext, TEvent>({
           value: stateValue.value,
-          context: context as TC,
+          context: context as TContext,
           _event: stateValue._event,
           _sessionid: null,
           history: stateValue.history,
@@ -118,11 +125,11 @@ export class State<
       return stateValue;
     }
 
-    const _event = initEvent as SCXML.Event<TE>;
+    const _event = initEvent as SCXML.Event<TEvent>;
 
-    return new State<TC, TE>({
+    return new State<TContext, TEvent>({
       value: stateValue,
-      context: context as TC,
+      context: context as TContext,
       _event,
       _sessionid: null,
       history: undefined,
@@ -137,9 +144,10 @@ export class State<
    * Creates a new State instance for the given `config`.
    * @param config The state config
    */
-  public static create<TC, TE extends EventObject = EventObject>(
-    config: StateConfig<TC, TE>
-  ): State<TC, TE, any> {
+  public static create<
+    TContext extends MachineContext,
+    TEvent extends EventObject = EventObject
+  >(config: StateConfig<TContext, TEvent>): State<TContext, TEvent, any> {
     return new State(config);
   }
   /**
@@ -151,10 +159,10 @@ export class State<
     state: TState,
     context: any
   ): TState;
-  public static inert<TC, TE extends EventObject = EventObject>(
-    stateValue: StateValue,
-    context: TC
-  ): State<TC, TE>;
+  public static inert<
+    TContext extends MachineContext,
+    TEvent extends EventObject = EventObject
+  >(stateValue: StateValue, context: TContext): State<TContext, TEvent>;
   public static inert(
     stateValue: State<any, any> | StateValue,
     context: any

packages/core/src/StateMachine.ts

@@ -9,7 +9,8 @@ import {
   Typestate,
   Transitions,
   MachineSchema,
-  StateNodeDefinition
+  StateNodeDefinition,
+  MachineContext
 } from './types';
 import { State } from './State';
 
@@ -30,7 +31,7 @@ export const NULL_EVENT = '';
 export const STATE_IDENTIFIER = '#';
 export const WILDCARD = '*';
 
-const createDefaultOptions = <TContext>(
+const createDefaultOptions = <TContext extends MachineContext>(
   context: TContext
 ): MachineImplementations<TContext, any> => ({
   actions: {},
@@ -44,18 +45,14 @@ function resolveContext<TContext>(
   context: TContext,
   partialContext?: Partial<TContext>
 ): TContext {
-  if (context === undefined) {
-    return context;
-  }
-
   return {
     ...context,
     ...partialContext
   };
 }
 
 export class StateMachine<
-  TContext = any,
+  TContext extends MachineContext = any,
   TEvent extends EventObject = EventObject,
   TTypestate extends Typestate<TContext> = any
 > {
@@ -100,10 +97,7 @@ export class StateMachine<
       createDefaultOptions(config.context!),
       options
     );
-    this.context = resolveContext<TContext>(
-      config.context as TContext,
-      this.options.context
-    );
+    this.context = resolveContext(config.context, options?.context) as TContext;
     this.delimiter = this.config.delimiter || STATE_DELIMITER;
     this.version = this.config.version;
     this.schema = this.config.schema ?? (({} as any) as this['schema']);

packages/core/src/StateNode.ts

@@ -28,7 +28,8 @@ import {
   NullEvent,
   SCXML,
   TransitionDefinitionMap,
-  InitialTransitionDefinition
+  InitialTransitionDefinition,
+  MachineContext
 } from './types';
 import { State } from './State';
 import * as actionTypes from './actionTypes';
@@ -44,14 +45,17 @@ import { StateMachine } from './StateMachine';
 
 const EMPTY_OBJECT = {};
 
-interface StateNodeOptions<TContext, TEvent extends EventObject> {
+interface StateNodeOptions<
+  TContext extends MachineContext,
+  TEvent extends EventObject
+> {
   _key: string;
   _parent?: StateNode<TContext, TEvent>;
   _machine: StateMachine<TContext, TEvent>;
 }
 
 export class StateNode<
-  TContext = any,
+  TContext extends MachineContext = MachineContext,
   TEvent extends EventObject = EventObject
 > {
   /**