Reddit API

Adapted from the Redux Docs: Advanced Tutorial

Suppose we wanted to create an app that displays a selected subreddit’s posts. The app should be able to:

  • Have a predefined list of subreddits that the user can select from
  • Load the selected subreddit
  • Display the last time the selected subreddit was loaded
  • Reload the selected subreddit
  • Select a different subreddit at any time

The app logic and state can be modeled with a single app-level machine, as well as invoked child machines for modeling the logic of each individual subreddit. For now, let’s start with a single machine.

Modeling the App

The Reddit app we’re creating can be modeled with two top-level states:

  • 'idle' - no subreddit selected yet (the initial state)
  • 'selected' - a subreddit is selected

```js {6-9} import { createMachine, assign } from ‘xstate’;

const redditMachine = createMachine({ id: ‘reddit’, initial: ‘idle’, states: { idle: {}, selected: {} } });

  2. We also need somewhere to store the selected `subreddit`, so let's put that in [`context`](../guides/context.md):
  4. ```js {6-8}
  5. // ...
  7. const redditMachine = createMachine({
  8.   id: 'reddit',
  9.   initial: 'idle',
  10.   context: {
  11.     subreddit: null // none selected
  12.   },
  13.   states: {
  14.     /* ... */
  15.   }
  16. });

Since a subreddit can be selected at any time, we can create a top-level transition for a 'SELECT' event, which signals that a subreddit was selected by the user. This event will have a payload that has the selected subreddit name in .name:

  1. // sample SELECT event
  2. const selectEvent = {
  3.   type: 'SELECT', // event type
  4.   name: 'reactjs' // subreddit name
  5. };

This event will be handled at the top-level, so that whenever the 'SELECT' event occurs, the machine will:

```js {10-17} const redditMachine = createMachine({ id: ‘reddit’, initial: ‘idle’, context: { subreddit: null // none selected }, states: { / … / }, on: { SELECT: { target: ‘.selected’, actions: assign({ subreddit: (context, event) => event.name }) } } });

  2. ## Async Flow
  4. When a subreddit is selected (that is, when the machine is in the `'selected'` state due to a `'SELECT'` event), the machine should start loading the subreddit data. To do this, we [invoke a Promise](../guides/communication.html#invoking-promises) that will resolve with the selected subreddit data:
  6. ```js {1-7,14-17}
  7. function invokeFetchSubreddit(context) {
  8.   const { subreddit } = context;
  10.   return fetch(`https://www.reddit.com/r/${subreddit}.json`)
  11.     .then((response) => response.json())
  12.     .then((json) => json.data.children.map((child) => child.data));
  13. }
  15. const redditMachine = createMachine({
  16.   /* ... */
  17.   states: {
  18.     idle: {},
  19.     selected: {
  20.       invoke: {
  21.         id: 'fetch-subreddit',
  22.         src: invokeFetchSubreddit
  23.       }
  24.     }
  25.   },
  26.   on: {
  27.     /* ... */
  28.   }
  29. });
Why specify the invoke ID? Specifying an id on the invoke config object allows clearer debugging and visualization, as well as the ability to send events directly to an invoked entity by its id.

When the 'selected' state is entered, invokeFetchSubreddit(...) will be called with the current context and event (not used here) and start fetching subreddit data from the Reddit API. The promise can then take two special transitions:

  • onDone - taken when the invoked promise resolves
  • onError - taken when the invoked promise rejects

This is where it’s helpful to have nested (hierarchical) states. We can make 3 child states that represent when the subreddit is 'loading', 'loaded' or 'failed' (pick names appropriate to your use-cases):

```js {8-17} const redditMachine = createMachine({ / … / states: { idle: {}, selected: { initial: ‘loading’, states: { loading: { invoke: { id: ‘fetch-subreddit’, src: invokeFetchSubreddit, onDone: ‘loaded’, onError: ‘failed’ } }, loaded: {}, failed: {} } } }, on: { / … / } });

  2. Notice how we moved the `invoke` config to the `'loading'` state. This is useful because if we want to change the app logic in the future to have some sort of `'paused'` or `'canceled'` child state, the invoked promise will automatically be "canceled" since it's no longer in the `'loading'` state where it was invoked.
  4. When the promise resolves, a special `'done.invoke.<invoke ID>'` event will be sent to the machine, containing the resolved data as `event.data`. For convenience, XState maps the `onDone` property within the `invoke` object to this special event. You can assign the resolved data to `context.posts`:
  6. ```js {18-20}
  7. const redditMachine = createMachine({
  8.   /* ... */
  9.   context: {
  10.     subreddit: null,
  11.     posts: null
  12.   },
  13.   states: {
  14.     idle: {},
  15.     selected: {
  16.       initial: 'loading',
  17.       states: {
  18.         loading: {
  19.           invoke: {
  20.             id: 'fetch-subreddit',
  21.             src: invokeFetchSubreddit,
  22.             onDone: {
  23.               target: 'loaded',
  24.               actions: assign({
  25.                 posts: (context, event) => event.data
  26.               })
  27.             },
  28.             onError: 'failed'
  29.           }
  30.         },
  31.         loaded: {},
  32.         failed: {}
  33.       }
  34.     }
  35.   },
  36.   on: {
  37.     /* ... */
  38.   }
  39. });

Testing It Out

It’s a good idea to test that your machine’s logic matches the app logic you intended. The most straightforward way to confidently test your app logic is by writing integration tests. You can test against a real or mock implementation of your app logic (e.g., using real services, making API calls, etc.), you can run the logic in an interpreter via interpret(...) and write an async test that finishes when the state machine reaches a certain state:

  1. import { interpret } from 'xstate';
  2. import { assert } from 'chai';
  4. import { redditMachine } from '../path/to/redditMachine';
  6. describe('reddit machine (live)', () => {
  7.   it('should load posts of a selected subreddit', (done) => {
  8.     const redditService = interpret(redditMachine)
  9.       .onTransition((state) => {
  10.         // when the state finally reaches 'selected.loaded',
  11.         // the test has succeeded.
  13.         if (state.matches({ selected: 'loaded' })) {
  14.           assert.isNotEmpty(state.context.posts);
  16.           done();
  17.         }
  18.       })
  19.       .start(); // remember to start the service!
  21.     // Test that when the 'SELECT' event is sent, the machine eventually
  22.     // reaches the { selected: 'loaded' } state with posts
  23.     redditService.send('SELECT', { name: 'reactjs' });
  24.   });
  25. });

Implementing the UI

From here, your app logic is self-contained in the redditMachine and can be used however you want, in any front-end framework, such as React, Vue, Angular, Svelte, etc.

Here’s an example of how it would be used in React with @xstate/react:

  1. import React from 'react';
  2. import { useMachine } from '@xstate/react';
  3. import { redditMachine } from '../path/to/redditMachine';
  5. const subreddits = ['frontend', 'reactjs', 'vuejs'];
  7. const App = () => {
  8.   const [current, send] = useMachine(redditMachine);
  9.   const { subreddit, posts } = current.context;
  11.   return (
  12.     <main>
  13.       <header>
  14.         <select
  15.           onChange={(e) => {
  16.             send('SELECT', { name: e.target.value });
  17.           }}
  18.         >
  19.           {subreddits.map((subreddit) => {
  20.             return <option key={subreddit}>{subreddit}</option>;
  21.           })}
  22.         </select>
  23.       </header>
  24.       <section>
  25.         <h1>{current.matches('idle') ? 'Select a subreddit' : subreddit}</h1>
  26.         {current.matches({ selected: 'loading' }) && <div>Loading...</div>}
  27.         {current.matches({ selected: 'loaded' }) && (
  28.           <ul>
  29.             {posts.map((post) => (
  30.               <li key={post.title}>{post.title}</li>
  31.             ))}
  32.           </ul>
  33.         )}
  34.       </section>
  35.     </main>
  36.   );
  37. };

Splitting Machines

Within the chosen UI framework, components provide natural isolation and encapsulation of logic. We can take advantage of that to organize logic and make smaller, more manageable machines.

Consider two machines:

  • A redditMachine, which is the app-level machine, responsible for rendering the selected subreddit component
  • A subredditMachine, which is the machine responsible for loading and displaying its specified subreddit
  1. const createSubredditMachine = (subreddit) => {
  2.   return createMachine({
  3.     id: 'subreddit',
  4.     initial: 'loading',
  5.     context: {
  6.       subreddit, // subreddit name passed in
  7.       posts: null,
  8.       lastUpdated: null
  9.     },
  10.     states: {
  11.       loading: {
  12.         invoke: {
  13.           id: 'fetch-subreddit',
  14.           src: invokeFetchSubreddit,
  15.           onDone: {
  16.             target: 'loaded',
  17.             actions: assign({
  18.               posts: (_, event) => event.data,
  19.               lastUpdated: () => Date.now()
  20.             })
  21.           },
  22.           onError: 'failure'
  23.         }
  24.       },
  25.       loaded: {
  26.         on: {
  27.           REFRESH: 'loading'
  28.         }
  29.       },
  30.       failure: {
  31.         on: {
  32.           RETRY: 'loading'
  33.         }
  34.       }
  35.     }
  36.   });
  37. };

Notice how a lot of the logic in the original redditMachine was moved to the subredditMachine. That allows us to isolate logic to their specific domains and make the redditMachine more general, without being concerned with subreddit loading logic:

```js {9} const redditMachine = createMachine({ id: ‘reddit’, initial: ‘idle’, context: { subreddit: null }, states: { idle: {}, selected: {} // no invocations! }, on: { SELECT: { target: ‘.selected’, actions: assign({ subreddit: (context, event) => event.name }) } } });

  2. Then, in the UI framework (React, in this case), a `<Subreddit>` component can be responsible for displaying the subreddit, using the logic from the created `subredditMachine`:
  4. ```jsx
  5. const Subreddit = ({ name }) => {
  6.   // Only create the machine based on the subreddit name once
  7.   const subredditMachine = useMemo(() => {
  8.     return createSubredditMachine(name);
  9.   }, [name]);
  11.   const [current, send] = useMachine(subredditMachine);
  13.   if (current.matches('failure')) {
  14.     return (
  15.       <div>
  16.         Failed to load posts.{' '}
  17.         <button onClick={(_) => send('RETRY')}>Retry?</button>
  18.       </div>
  19.     );
  20.   }
  22.   const { subreddit, posts, lastUpdated } = current.context;
  24.   return (
  25.     <section
  26.       data-machine={subredditMachine.id}
  27.       data-state={current.toStrings().join(' ')}
  28.     >
  29.       {current.matches('loading') && <div>Loading posts...</div>}
  30.       {posts && (
  31.         <>
  32.           <header>
  33.             <h2>{subreddit}</h2>
  34.             <small>
  35.               Last updated: {lastUpdated}{' '}
  36.               <button onClick={(_) => send('REFRESH')}>Refresh</button>
  37.             </small>
  38.           </header>
  39.           <ul>
  40.             {posts.map((post) => {
  41.               return <li key={post.id}>{post.title}</li>;
  42.             })}
  43.           </ul>
  44.         </>
  45.       )}
  46.     </section>
  47.   );
  48. };

And the overall app can use that <Subreddit> component:

```jsx {8} const App = () => { const [current, send] = useMachine(redditMachine); const { subreddit } = current.context;

return (

{/ … /}
{subreddit && }
); };

  2. ## Using Actors
  4. The machines we've created work, and fit our basic use-cases. However, suppose we want to support the following use-cases:
  6. - When a subreddit is selected, it should load fully, even if a different one is selected (basic "caching")
  7. - The user should see when a subreddit was last updated, and have the ability to refresh the subreddit.
  9. A good mental model for this is the [Actor model](../guides/actors.md), where each individual subreddit is its own "actor" that controls its own logic based on events, whether internal or external.
  11. ## Spawning Subreddit Actors
  13. Recall that an actor is an entity that has its own logic/behavior, and it can receive and send events to other actors.
  15. <mermaid>
  16.   graph TD;
  17.   A("subreddit (reactjs)")
  18.   B("subreddit (vuejs)")
  19.   C("subreddit (frontend)")
  20.   reddit-.->A;
  21.   reddit-.->B;
  22.   reddit-.->C;
  23. </mermaid>
  25. The `context` of the `redditMachine` needs to be modeled to:
  27. - maintain a mapping of subreddits to their spawned actors
  28. - keep track of which subreddit is currently visible
  30. ```js {4,5}
  31. const redditMachine = createMachine({
  32.   // ...
  33.   context: {
  34.     subreddits: {},
  35.     subreddit: null
  36.   }
  37.   // ...
  38. });

When a subreddit is selected, one of two things can happen:

  1. If that subreddit actor already exists in the context.subreddits object, assign() it as the current context.subreddit.
  2. Otherwise, spawn() a new subreddit actor with subreddit machine behavior from createSubredditMachine, assign it as the current context.subreddit, and save it in the context.subreddits object.
  1. const redditMachine = createMachine({
  2.   // ...
  3.   context: {
  4.     subreddits: {},
  5.     subreddit: null
  6.   },
  7.   // ...
  8.   on: {
  9.     SELECT: {
  10.       target: '.selected',
  11.       actions: assign((context, event) => {
  12.         // Use the existing subreddit actor if one already exists
  13.         let subreddit = context.subreddits[event.name];
  15.         if (subreddit) {
  16.           return {
  17.             ...context,
  18.             subreddit
  19.           };
  20.         }
  22.         // Otherwise, spawn a new subreddit actor and
  23.         // save it in the subreddits object
  24.         subreddit = spawn(createSubredditMachine(event.name));
  26.         return {
  27.           subreddits: {
  28.             ...context.subreddits,
  29.             [event.name]: subreddit
  30.           },
  31.           subreddit
  32.         };
  33.       })
  34.     }
  35.   }
  36. });

Putting It All Together

Now that we have each subreddit encapsulated in its own “live” actor with its own logic and behavior, we can pass these actor references (or “refs”) around as data. These actors created from machines are called “services” in XState. Just like any actor, events can be sent to these services, but these services can also be subscribed to. The subscriber will receive the most current state of the service whenever it’s updated.

::: tip In React, change detection is done by reference, and changes to props/state cause rerenders. An actor’s reference never changes, but its internal state may change. This makes actors ideal for when top-level state needs to maintain references to spawned actors, but should not rerender when a spawned actor changes (unless explicitly told to do so via an event sent to the parent).

In other words, spawned child actors updating will not cause unnecessary rerenders. 🎉 :::

  1. // ./Subreddit.jsx
  3. const Subreddit = ({ service }) => {
  4.   const [current, send] = useService(service);
  6.   // ... same code as previous Subreddit component
  7. };
  1. // ./App.jsx
  3. const App = () => {
  4.   const [current, send] = useMachine(redditMachine);
  5.   const { subreddit } = current.context;
  7.   return (
  8.     <main>
  9.       {/* ... */}
  10.       {subreddit && <Subreddit service={subreddit} key={subreddit.id} />}
  11.     </main>
  12.   );
  13. };

The differences between using the actor model above and just using machines with a component hierarchy (e.g., with React) are:

  • The data flow and logic hierarchy live in the XState services, not in the components. This is important when the subreddit needs to continue loading, even when its <Subreddit> component may be unmounted.
  • The UI framework layer (e.g., React) becomes a plain view layer; logic and side-effects are not tied directly to the UI, except where it is appropriate.
  • The redditMachine → subredditMachine actor hierarchy is “self-sustaining”, and allows for the logic to be transferred to any UI framework, or even no framework at all!

React Demo

Vue Demo

Unsurprisingly, the same machines can be used in a Vue app that exhibits the exact same behavior (thanks to Chris Hannaby):