Add ActorRef

.changeset/great-toes-vanish.md

@@ -0,0 +1,5 @@
+---
+'xstate': patch
+---
+
+Fixed an issue with invoked service not being correctly started if other service got stopped in a subsequent microstep (in response to raised or null event).

.changeset/rotten-rivers-wonder.md

@@ -0,0 +1,105 @@
+---
+'xstate': major
+---
+
+**Breaking:** Activities are no longer a separate concept. Instead, activities are invoked. Internally, this is how activities worked. The API is consolidated so that `activities` are no longer a property of the state node or machine options:
+
+```diff
+import { createMachine } from 'xstate';
++import { invokeActivity } from 'xstate/invoke';
+
+const machine = createMachine(
+  {
+    // ...
+-   activities: 'someActivity',
++   invoke: {
++     src: 'someActivity'
++   }
+  },
+  {
+-   activities: {
++   behaviors: {
+-     someActivity: ((context, event) => {
++     someActivity: invokeActivity((context, event) => {
+        // ... some continuous activity
+
+        return () => {
+          // dispose activity
+        }
+      })
+    }
+  }
+);
+```
+
+**Breaking:** The `services` option passed as the second argument to `createMachine(config, options)` is renamed to `behaviors`. Each value in `behaviors`should be a function that takes in `context` and `event` and returns a [behavior](TODO: link). The provided invoke creators are:
+
+- `invokeActivity`
+- `invokePromise`
+- `invokeCallback`
+- `invokeObservable`
+- `invokeMachine`
+
+```diff
+import { createMachine } from 'xstate';
++import { invokePromise } from 'xstate/invoke';
+
+const machine = createMachine(
+  {
+    // ...
+    invoke: {
+      src: 'fetchFromAPI'
+    }
+  },
+  {
+-   services: {
++   behaviors: {
+-     fetchFromAPI: ((context, event) => {
++     fetchFromAPI: invokePromise((context, event) => {
+        // ... (return a promise)
+      })
+    }
+  }
+);
+```
+
+**Breaking:** The `state.children` property is now a mapping of invoked actor IDs to their `ActorRef` instances.
+
+**Breaking:** The way that you interface with invoked/spawned actors is now through `ActorRef` instances. An `ActorRef` is an opaque reference to an `Actor`, which should be never referenced directly.
+
+**Breaking:** The `spawn` function is no longer imported globally. Spawning actors is now done inside of `assign(...)`, as seen below:
+
+```diff
+-import { createMachine, spawn } from 'xstate';
++import { createMachine } from 'xstate';
+
+const machine = createMachine({
+  // ...
+  entry: assign({
+-   someRef: (context, event) => {
++   someRef: (context, event, { spawn }) => {
+-     return spawn(somePromise);
++     return spawn.from(somePromise);
+    }
+  })
+});
+
+```
+
+**Breaking:** The `src` of an `invoke` config is now either a string that references the machine's `options.behaviors`, or a `BehaviorCreator`, which is a function that takes in `context` and `event` and returns a `Behavior`:
+
+```diff
+import { createMachine } from 'xstate';
++import { invokePromise } from 'xstate/invoke';
+
+const machine = createMachine({
+  // ...
+  invoke: {
+-   src: (context, event) => somePromise
++   src: invokePromise((context, event) => somePromise)
+  }
+  // ...
+});
+```
+
+**Breaking:** The `origin` of an `SCXML.Event` is no longer a string, but an `ActorRef` instance.

.changeset/wet-swans-deny.md

@@ -0,0 +1,5 @@
+---
+'xstate': minor
+---
+
+Actions from a restored state provided as a custom initial state to `interpret(machine).start(initialState)` are now executed properly. See #1174 for more information.

README.md

@@ -27,6 +27,17 @@ JavaScript and TypeScript [finite state machines](https://en.wikipedia.org/wiki/
 - [💚 `@xstate/vue`](https://github.com/davidkpiano/xstate/tree/master/packages/xstate-vue) - Vue composition functions and utilities for using XState in Vue applications
 - [✅ `@xstate/test`](https://github.com/davidkpiano/xstate/tree/master/packages/xstate-test) - Model-based testing utilities for XState
 
+## Templates
+
+Get started by forking one of these templates on CodeSandbox:
+
+- [XState Template](https://codesandbox.io/s/xstate-example-template-m4ckv) - no framework
+- [XState + TypeScript Template](https://codesandbox.io/s/xstate-typescript-template-s9kz8) - no framework
+- [XState + React Template](https://codesandbox.io/s/xstate-react-template-3t2tg)
+- [XState + React + TypeScript Template](https://codesandbox.io/s/xstate-react-typescript-template-wjdvn)
+- [XState + Vue Template](https://codesandbox.io/s/xstate-vue-template-composition-api-1n23l)
+- [XState + Svelte Template](https://codesandbox.io/s/xstate-svelte-template-jflv1)
+
 ## Super quick start
 
 ```bash

docs/packages/xstate-react/index.md

@@ -49,7 +49,7 @@ A [React hook](https://reactjs.org/hooks) that interprets the given `machine` an
 **Arguments**
 
 - `machine` - An [XState machine](https://xstate.js.org/docs/guides/machines.html).
-- `options` (optional) - [Interpreter options](https://xstate.js.org/docs/guides/interpretation.html#options) OR one of the following Machine Config options: `guards`, `actions`, `activities`, `services`, `delays`, `immediate`, `context`, or `state`.
+- `options` (optional) - [Interpreter options](https://xstate.js.org/docs/guides/interpretation.html#options) OR one of the following Machine Config options: `guards`, `actions`, `activities`, `behaviors`, `delays`, `immediate`, `context`, or `state`.
 
 **Returns** a tuple of `[state, send, service]`:
 
@@ -148,13 +148,16 @@ const Fetcher = ({ onFetch = () => new Promise(res => res('some data')) }) => {
 };
 ```
 
-## Configuring Machines <Badge text="0.7+"/>
+## Configuring Machines
 
 Existing machines can be configured by passing the machine options as the 2nd argument of `useMachine(machine, options)`.
 
 Example: the `'fetchData'` service and `'notifySuccess'` action are both configurable:
 
 ```js
+import { createMachine } from 'xstate';
+import { invokePromise } from 'xstate/invoke';
+
 const fetchMachine = Machine({
   id: 'fetch',
   initial: 'idle',
@@ -200,9 +203,10 @@ const Fetcher = ({ onResolve }) => {
     actions: {
       notifySuccess: (ctx) => onResolve(ctx.data)
     },
-    services: {
-      fetchData: (_, e) =>
-        fetch(`some/api/${e.query}`).then((res) => res.json())
+    behaviors: {
+      fetchData: invokePromise((_, event) =>
+        fetch(`some/api/${event.query}`).then((res) => res.json())
+      )
     }
   });
 

docs/packages/xstate-test/index.md

@@ -3,6 +3,7 @@
 This package contains utilities for facilitating [model-based testing](https://en.wikipedia.org/wiki/Model-based_testing) for any software.
 
 - **Talk**: [Write Fewer Tests! From Automation to Autogeneration](https://slides.com/davidkhourshid/mbt) at React Rally 2019 ([🎥 Video](https://www.youtube.com/watch?v=tpNmPKjPSFQ))
+- [Model-Based Testing in React with State Machines](https://css-tricks.com/model-based-testing-in-react-with-state-machines/)
 
 ## Quick Start
 
@@ -49,7 +50,7 @@ const toggleMachine = Machine({
         /* ... */
       },
       meta: {
-        test: async page => {
+        test: async (page) => {
           await page.waitFor('input:checked');
         }
       }
@@ -59,7 +60,7 @@ const toggleMachine = Machine({
         /* ... */
       },
       meta: {
-        test: async page => {
+        test: async (page) => {
           await page.waitFor('input:not(:checked)');
         }
       }
@@ -78,7 +79,7 @@ const toggleMachine = Machine(/* ... */);
 
 const toggleModel = createModel(toggleMachine).withEvents({
   TOGGLE: {
-    exec: async page => {
+    exec: async (page) => {
       await page.click('input');
     }
   }
@@ -93,9 +94,9 @@ const toggleModel = createModel(toggleMachine).withEvents({
 describe('toggle', () => {
   const testPlans = toggleModel.getShortestPathPlans();
 
-  testPlans.forEach(plan => {
+  testPlans.forEach((plan) => {
     describe(plan.description, () => {
-      plan.paths.forEach(path => {
+      plan.paths.forEach((path) => {
         it(path.description, async () => {
           // do any setup, then...
 
@@ -142,7 +143,7 @@ Provides testing details for each event. Each key in `eventsMap` is an object wh
 ```js
 const toggleModel = createModel(toggleMachine).withEvents({
   TOGGLE: {
-    exec: async page => {
+    exec: async (page) => {
       await page.click('input');
     }
   }
@@ -167,7 +168,7 @@ const todosModel = createModel(todosMachine).withEvents({
 const plans = todosModel.getShortestPathPlans({
   // Tell the algorithm to limit state/event adjacency map to states
   // that have less than 5 todos
-  filter: state => state.context.todos.length < 5
+  filter: (state) => state.context.todos.length < 5
 });
 ```
 
@@ -195,7 +196,7 @@ Tests that all state nodes were covered (traversed) in the exected tests.
 // Only test coverage for state nodes with a `.meta` property defined:
 
 testModel.testCoverage({
-  filter: stateNode => !!stateNode.meta
+  filter: (stateNode) => !!stateNode.meta
 });
 ```
 

docs/packages/xstate-vue/index.md

@@ -75,7 +75,7 @@ A [Vue composition function](https://vue-composition-api-rfc.netlify.com/) that
 **Arguments**
 
 - `machine` - An [XState machine](https://xstate.js.org/docs/guides/machines.html).
-- `options` (optional) - [Interpreter options](https://xstate.js.org/docs/guides/interpretation.html#options) OR one of the following Machine Config options: `guards`, `actions`, `activities`, `services`, `delays`, `immediate`, `context`, or `state`.
+- `options` (optional) - [Interpreter options](https://xstate.js.org/docs/guides/interpretation.html#options) OR one of the following Machine Config options: `guards`, `actions`, `activities`, `behaviors`, `delays`, `immediate`, `context`, or `state`.
 
 **Returns** `{ state, send, service}`:
 

docs/tutorials/reddit.md

@@ -94,8 +94,8 @@ function invokeFetchSubreddit(context) {
   const { subreddit } = context;
 
   return fetch(`https://www.reddit.com/r/${subreddit}.json`)
-    .then(response => response.json())
-    .then(json => json.data.children.map(child => child.data));
+    .then((response) => response.json())
+    .then((json) => json.data.children.map((child) => child.data));
 }
 
 const redditMachine = Machine({
@@ -207,9 +207,9 @@ import { assert } from 'chai';
 import { redditMachine } from '../path/to/redditMachine';
 
 describe('reddit machine (live)', () => {
-  it('should load posts of a selected subreddit', done => {
+  it('should load posts of a selected subreddit', (done) => {
     const redditService = interpret(redditMachine)
-      .onTransition(state => {
+      .onTransition((state) => {
         // when the state finally reaches 'selected.loaded',
         // the test has succeeded.
 
@@ -249,11 +249,11 @@ const App = () => {
     <main>
       <header>
         <select
-          onChange={e => {
+          onChange={(e) => {
             send('SELECT', { name: e.target.value });
           }}
         >
-          {subreddits.map(subreddit => {
+          {subreddits.map((subreddit) => {
             return <option key={subreddit}>{subreddit}</option>;
           })}
         </select>
@@ -263,7 +263,7 @@ const App = () => {
         {current.matches({ selected: 'loading' }) && <div>Loading...</div>}
         {current.matches({ selected: 'loaded' }) && (
           <ul>
-            {posts.map(post => (
+            {posts.map((post) => (
               <li key={post.title}>{post.title}</li>
             ))}
           </ul>
@@ -284,7 +284,7 @@ Consider two machines:
 - A `subredditMachine`, which is the machine responsible for loading and displaying its specified subreddit
 
 ```js
-const createSubredditMachine = subreddit => {
+const createSubredditMachine = (subreddit) => {
   return Machine({
     id: 'subreddit',
     initial: 'loading',
@@ -362,7 +362,7 @@ const Subreddit = ({ name }) => {
     return (
       <div>
         Failed to load posts.{' '}
-        <button onClick={_ => send('RETRY')}>Retry?</button>
+        <button onClick={(_) => send('RETRY')}>Retry?</button>
       </div>
     );
   }
@@ -381,11 +381,11 @@ const Subreddit = ({ name }) => {
             <h2>{subreddit}</h2>
             <small>
               Last updated: {lastUpdated}{' '}
-              <button onClick={_ => send('REFRESH')}>Refresh</button>
+              <button onClick={(_) => send('REFRESH')}>Refresh</button>
             </small>
           </header>
           <ul>
-            {posts.map(post => {
+            {posts.map((post) => {
               return <li key={post.id}>{post.title}</li>;
             })}
           </ul>
@@ -468,7 +468,7 @@ const redditMachine = Machine({
     SELECT: {
       target: '.selected',
       actions: assign((context, event) => {
-        // Use the existing subreddit actor if one doesn't exist
+        // Use the existing subreddit actor if one already exists
         let subreddit = context.subreddits[event.name];
 
         if (subreddit) {

packages/core/actor/package.json

@@ -0,0 +1,7 @@
+{
+  "main": "dist/xstate.cjs.js",
+  "module": "dist/xstate.esm.js",
+  "preconstruct": {
+    "source": "../src/Actor"
+  }
+}

packages/core/behavior/package.json

@@ -0,0 +1,7 @@
+{
+  "main": "dist/xstate.cjs.js",
+  "module": "dist/xstate.esm.js",
+  "preconstruct": {
+    "source": "../src/behavior"
+  }
+}

packages/core/package.json

@@ -12,7 +12,8 @@
   "files": [
     "dist",
     "actions",
-    "invoke"
+    "invoke",
+    "behavior"
   ],
   "keywords": [
     "statechart",
@@ -49,7 +50,8 @@
     "entrypoints": [
       ".",
       "actions",
-      "invoke"
+      "invoke",
+      "behavior"
     ]
   }
 }