xstate 4.15.4 → 4.16.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # xstate
 
+## 4.16.0
+
+### Minor Changes
+
+- [`d2e328f8`](https://github.com/davidkpiano/xstate/commit/d2e328f8efad7e8d3500d39976d1153a26e835a3) [#1439](https://github.com/davidkpiano/xstate/pull/1439) Thanks [@davidkpiano](https://github.com/davidkpiano)! - An opt-in `createModel()` helper has been introduced to make it easier to work with typed `context` and events.
+
+  - `createModel(initialContext)` creates a `model` object
+  - `model.initialContext` returns the `initialContext`
+  - `model.assign(assigner, event?)` creates an `assign` action that is properly scoped to the `event` in TypeScript
+
+  See https://github.com/davidkpiano/xstate/pull/1439 for more details.
+
+  ```js
+  import { createMachine } from 'xstate';
+  import { createModel } from 'xstate/lib/model'; // opt-in, not part of main build
+
+  interface UserContext {
+    name: string;
+    age: number;
+  }
+
+  type UserEvents =
+    | { type: 'updateName'; value: string }
+    | { type: 'updateAge'; value: number }
+
+  const userModel = createModel<UserContext, UserEvents>({
+    name: 'David',
+    age: 30
+  });
+
+  const assignName = userModel.assign({
+    name: (_, e) => e.value // correctly typed to `string`
+  }, 'updateName'); // restrict to 'updateName' event
+
+  const machine = createMachine<UserContext, UserEvents>({
+    context: userModel.context,
+    initial: 'active',
+    states: {
+      active: {
+        on: {
+          updateName: {
+            actions: assignName
+          }
+        }
+      }
+    }
+  });
+  ```
+
 ## 4.15.4
 
 ### Patch Changes

package/es/model.d.ts

@@ -0,0 +1,8 @@
+import type { AssignAction, Assigner, PropertyAssigner, ExtractEvent, EventObject } from './types';
+export interface ContextModel<TContext, TEvent extends EventObject> {
+    initialContext: TContext;
+    assign: <TEventType extends TEvent['type'] = TEvent['type']>(assigner: Assigner<TContext, ExtractEvent<TEvent, TEventType>> | PropertyAssigner<TContext, ExtractEvent<TEvent, TEventType>>, eventType?: TEventType) => AssignAction<TContext, ExtractEvent<TEvent, TEventType>>;
+    reset: () => AssignAction<TContext, any>;
+}
+export declare function createModel<TContext, TEvent extends EventObject>(initialContext: TContext): ContextModel<TContext, TEvent>;
+//# sourceMappingURL=model.d.ts.map

package/es/types.d.ts

@@ -201,7 +201,7 @@ export declare type StatesDefinition<TContext, TStateSchema extends StateSchema,
 };
 export declare type TransitionConfigTarget<TContext, TEvent extends EventObject> = string | undefined | StateNode<TContext, any, TEvent>;
 export declare type TransitionConfigOrTarget<TContext, TEvent extends EventObject> = SingleOrArray<TransitionConfigTarget<TContext, TEvent> | TransitionConfig<TContext, TEvent>>;
-declare type TransitionsConfigMap<TContext, TEvent extends EventObject> = {
+export declare type TransitionsConfigMap<TContext, TEvent extends EventObject> = {
     [K in TEvent['type']]?: TransitionConfigOrTarget<TContext, TEvent extends {
         type: K;
     } ? TEvent : never>;
@@ -616,8 +616,9 @@ export interface CancelAction extends ActionObject<any, any> {
     sendId: string | number;
 }
 export declare type Assigner<TContext, TEvent extends EventObject> = (context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => Partial<TContext>;
+export declare type PartialAssigner<TContext, TEvent extends EventObject, TKey extends keyof TContext> = (context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => TContext[TKey];
 export declare type PropertyAssigner<TContext, TEvent extends EventObject> = {
-    [K in keyof TContext]?: ((context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => TContext[K]) | TContext[K];
+    [K in keyof TContext]?: PartialAssigner<TContext, TEvent, K> | TContext[K];
 };
 export declare type Mapper<TContext, TEvent extends EventObject, TParams extends {}> = (context: TContext, event: TEvent) => TParams;
 export declare type PropertyMapper<TContext, TEvent extends EventObject, TParams extends {}> = {
@@ -854,6 +855,9 @@ export interface Subscribable<T> {
     subscribe(next: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription;
 }
 export declare type Spawnable = StateMachine<any, any, any> | Promise<any> | InvokeCallback | Subscribable<any>;
+export declare type ExtractEvent<TEvent extends EventObject, TEventType extends TEvent['type']> = TEvent extends {
+    type: TEventType;
+} ? TEvent : never;
 export interface ActorRef<TEvent extends EventObject, TEmitted = any> extends Subscribable<TEmitted> {
     send: Sender<TEvent>;
 }

package/es/utils.d.ts

@@ -10,12 +10,10 @@ export declare function toStatePath(stateId: string | string[], delimiter: strin
 export declare function isStateLike(state: any): state is StateLike<any>;
 export declare function toStateValue(stateValue: StateLike<any> | StateValue | string[], delimiter: string): StateValue;
 export declare function pathToStateValue(statePath: string[]): StateValue;
-export declare function mapValues<T, P>(collection: {
+export declare function mapValues<T, P, O extends {
     [key: string]: T;
-}, iteratee: (item: T, key: string, collection: {
-    [key: string]: T;
-}, i: number) => P): {
-    [key: string]: P;
+}>(collection: O, iteratee: (item: O[keyof O], key: keyof O, collection: O, i: number) => P): {
+    [key in keyof O]: P;
 };
 export declare function mapFilterValues<T, P>(collection: {
     [key: string]: T;

package/lib/model.d.ts

@@ -0,0 +1,8 @@
+import type { AssignAction, Assigner, PropertyAssigner, ExtractEvent, EventObject } from './types';
+export interface ContextModel<TContext, TEvent extends EventObject> {
+    initialContext: TContext;
+    assign: <TEventType extends TEvent['type'] = TEvent['type']>(assigner: Assigner<TContext, ExtractEvent<TEvent, TEventType>> | PropertyAssigner<TContext, ExtractEvent<TEvent, TEventType>>, eventType?: TEventType) => AssignAction<TContext, ExtractEvent<TEvent, TEventType>>;
+    reset: () => AssignAction<TContext, any>;
+}
+export declare function createModel<TContext, TEvent extends EventObject>(initialContext: TContext): ContextModel<TContext, TEvent>;
+//# sourceMappingURL=model.d.ts.map

package/lib/model.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModel = void 0;
+var actions_1 = require("./actions");
+function createModel(initialContext) {
+    var model = {
+        initialContext: initialContext,
+        assign: actions_1.assign,
+        reset: function () { return actions_1.assign(initialContext); }
+    };
+    return model;
+}
+exports.createModel = createModel;

package/lib/types.d.ts

@@ -201,7 +201,7 @@ export declare type StatesDefinition<TContext, TStateSchema extends StateSchema,
 };
 export declare type TransitionConfigTarget<TContext, TEvent extends EventObject> = string | undefined | StateNode<TContext, any, TEvent>;
 export declare type TransitionConfigOrTarget<TContext, TEvent extends EventObject> = SingleOrArray<TransitionConfigTarget<TContext, TEvent> | TransitionConfig<TContext, TEvent>>;
-declare type TransitionsConfigMap<TContext, TEvent extends EventObject> = {
+export declare type TransitionsConfigMap<TContext, TEvent extends EventObject> = {
     [K in TEvent['type']]?: TransitionConfigOrTarget<TContext, TEvent extends {
         type: K;
     } ? TEvent : never>;
@@ -616,8 +616,9 @@ export interface CancelAction extends ActionObject<any, any> {
     sendId: string | number;
 }
 export declare type Assigner<TContext, TEvent extends EventObject> = (context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => Partial<TContext>;
+export declare type PartialAssigner<TContext, TEvent extends EventObject, TKey extends keyof TContext> = (context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => TContext[TKey];
 export declare type PropertyAssigner<TContext, TEvent extends EventObject> = {
-    [K in keyof TContext]?: ((context: TContext, event: TEvent, meta: AssignMeta<TContext, TEvent>) => TContext[K]) | TContext[K];
+    [K in keyof TContext]?: PartialAssigner<TContext, TEvent, K> | TContext[K];
 };
 export declare type Mapper<TContext, TEvent extends EventObject, TParams extends {}> = (context: TContext, event: TEvent) => TParams;
 export declare type PropertyMapper<TContext, TEvent extends EventObject, TParams extends {}> = {
@@ -854,6 +855,9 @@ export interface Subscribable<T> {
     subscribe(next: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription;
 }
 export declare type Spawnable = StateMachine<any, any, any> | Promise<any> | InvokeCallback | Subscribable<any>;
+export declare type ExtractEvent<TEvent extends EventObject, TEventType extends TEvent['type']> = TEvent extends {
+    type: TEventType;
+} ? TEvent : never;
 export interface ActorRef<TEvent extends EventObject, TEmitted = any> extends Subscribable<TEmitted> {
     send: Sender<TEvent>;
 }

package/lib/utils.d.ts

@@ -10,12 +10,10 @@ export declare function toStatePath(stateId: string | string[], delimiter: strin
 export declare function isStateLike(state: any): state is StateLike<any>;
 export declare function toStateValue(stateValue: StateLike<any> | StateValue | string[], delimiter: string): StateValue;
 export declare function pathToStateValue(statePath: string[]): StateValue;
-export declare function mapValues<T, P>(collection: {
+export declare function mapValues<T, P, O extends {
     [key: string]: T;
-}, iteratee: (item: T, key: string, collection: {
-    [key: string]: T;
-}, i: number) => P): {
-    [key: string]: P;
+}>(collection: O, iteratee: (item: O[keyof O], key: keyof O, collection: O, i: number) => P): {
+    [key in keyof O]: P;
 };
 export declare function mapFilterValues<T, P>(collection: {
     [key: string]: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xstate",
-  "version": "4.15.4",
+  "version": "4.16.0",
   "description": "Finite State Machines and Statecharts for the Modern Web.",
   "main": "lib/index.js",
   "module": "es/index.js",