Enhance service returned by default interpreter with custom event creators

[serhiipalash]

Hi! When our app starts we want to invoke multiple services as singletons (auth, user, theme, etc) and then use and compose them in different ways during user session. There is one minor problem, as the services are global they will be used in many files in various ways and in a big team people can make mistakes. To avoid additional complexity I suggest to have a code like this

// authService.js

import { createMachine, interpret } from '@xstate/fsm';

const authMachine = createMachine({
  /* ... */
});

const authService = interpret(
  authMachine,
  {
    logOut: () => ({ type: 'AUTH__LOG_OUT' }),
    logIn: (email, password) => ({ type: 'AUTH__LOG_IN', data: { email, password } })
  }
);

authService.start();

export default authService

// Login screen

import authService from './services/authService'

/* ... */

<Button 
  label="Log in" 
  onClick={() => authService.logIn(email, password)} 
/>

This should be more reliable code then next one, imho

// Login screen

import authService from './services/authService'

/* ... */

<Button 
  label="Log in" 
  onClick={() => authService.send({ type: 'AUTH__LOG_IN', data: { email, password })} 
/>

Note: I think it's a common practice for services in general. For example, react-navigation service has goBack, setParams methods alongside dispatch method.

https://reactnavigation.org/docs/navigation-actions/#setparams

[davidkpiano]

This is similar to the ideas in Comlink; it's sort of a proxy for sending events.

You can definitely do this in user-land, and perhaps XState can provide (opt-in) helper functions to help you do this:

function createProxy(service) {
  const handler = {
    get(target, propKey, receiver) {
      return (payload) => {
        service.send(propKey, payload);
      };
    }
  };

  return new Proxy(service, handler);
}

const serviceProxy = createProxy(someService);

serviceProxy.TOGGLE()
// ... etc.

Example: https://codesandbox.io/s/xstate-proxy-example-62w2i?file=/src/index.js

---

There are a couple of issues with this approach, though:

• Methods (which are conceptually the same as sending messages) are now on the same level as other methods, so it can be difficult to distinguish between e.g., proxy.doThis() and proxy.subscribe() at best; and might be a naming collision at worst.
• Mitigating this, you can probably push the "send" proxy methods down a level:

  someProxy.send.TOGGLE(somePayload)

  But then there's little difference between that and this:

  someProxy.send('TOGGLE', somePayload)

  Which... you can already do.
• Overall, it obscures having a common interface for most entities in your application (a simple { send, subscribe } interface) by replacing that with custom interfaces, and the only benefit is (arguably) developer experience... which might not be a benefit if the developer is not familiar with the custom methods that can be called (IMO).

[serhiipalash]

Thanks for replaying and for the link on sandbox @davidkpiano !

I agree almost with everything you said. Having custom event creators on the same level with send or dispatch is not good. Having them under send path also looks strange. Sorry, but I am not agree with last argument about convenience of common interface for most entities :)

I see this in the way that there are two general use cases. First is UI events processing, second - subordinate service.

UI events are various, they can compete, overlap each other. They can produce event stream, which can produce their own events (higher level events like debouncing, throttling or anything you can imagine to create with RxJS). Because of this handling complex UI state might be hard just to imagine, not saying about to do it. Everything changes when XState with declarative state definitions takes the stage. Now you don't have to look through the long HTML to find all possible UI events attached in different places, you don't have to memoize them, picture how they affect each other, etc. Only thing you need to do to understand the UI state is to open XState statechart. That's why this code

const { send } = useMachine(uiMachine)

<Input onChange={value => send({ type: 'NAME__CHANGE', data: value )} />

is much better than this one

[name, setName] = useState('')

<Input onChange={value => {
  // real state handling goes here, it's a part of View code :(
  setName(value)
}) />

So, what I'm trying to say is that, when you work with UI, you HAVE to think in terms of events and their composition, you HAVE to visualise it in your head in something like statechart even if you don't use XState. That's why next code is not good

const { service }= useMachine(uiMachine)

<Input onChange={value => service.updateName(value)} />

It only hides essential part of UI state handling - events.

Let's now think about not UI, but subordinate service state handling. Examples from React Native

Keyboard.dismiss()
StatusBar.setBarStyle('light-content')
StatusBar.setHidden(false)
navigation.goBack()

and let's try to write it in common interface

Keyboard.send({ type: 'DISMISS' })
StatusBar.send({ type: 'STYLE__CHANGE', data: 'light-content' })
StatusBar.send({ type: 'VISIBILITY__CHANGE', data: false })
navigation.send({ type: 'GO_BACK' })

The problem is not even that the second variant is more verbose, but that I have to know twice more entities to be able to work with service: events and their actions, in opposite to just methods in first variant.

As a user from service I just want the work to be done, I don't want to know how exactly it works in the nutshell. I don't want to think of what event to send to trigger action which triggers native method hides the keyboard. Just writing Keyboard.dismiss() gives enough and minimum understanding to be able to use it.

From your good points and everything I said, I would say the auth service should look like this

// authService.js

import { createMachine, interpret } from '@xstate/fsm';

const authMachine = createMachine({
  /* ... */
});

const authService = interpret(authMachine);

authService.start();

export default {
  logOut: () => authService.send({ type: 'AUTH__LOG_OUT' }),
  logIn: (email, password) => authService.send({ type: 'AUTH__LOG_IN', data: { email, password } })
  get state() {
    return authService.state.value
  },
  subscribe: (cb) => authService.subscribe(cb)
}

Even that I think that every state should be handled with state machines, exposing stte complexity in outer world has sense only for UI or similar use cases.

Note: everything above is only my personal opinion

[davidkpiano]

Right; and it's completely your choice to do what you did in the last example (export default { ... }) - it looks quite nice! But it should be up to the developer(s) to implement that, and XState should remain unopinionated about it.

Let me explain one of the reasons I prefer service.send({ type: 'UPDATE_NAME' }) versus service.updateName(). Can you tell the difference between these two lines of code?

service.updateName();

service.updateName();

Do you see a difference? There might not be a difference at first sight, but these two method calls might have completely different behavior depending on when they are called. As a developer, when you see service.updateName(), you would expect, on the very next line, for the name to be updated. But, for example, that might not be the case if you are in a state where you are forbidden from updating the name. In that case, there's no way of knowing whether your updateName() imperative call succeeded or failed without checking the state.

On the other hand, service.send({ type: 'UPDATE_NAME' }) makes it very clear that you are sending an intent to update the name, and you know it 1) might not be immediate, and 2) might not succeed. That second part is very important - sending a message feels different than making an imperative method call, because all you're doing is sending a message. You are not directly manipulating an entity.

As a real-life analogy, consider these two different calls:

human.sleep();

human.send('GO_TO_SLEEP');

In the first one, you expect the method call to succeed; it feels like you're directly manipulating the human. But in the second one, you're merely telling the human to go to sleep. It doesn't feel direct, which is good - there is the understanding that sending a message doesn't mean that the desired outcome will occur, and that's okay.

[serhiipalash]

Okey, you've convinced me :)

Still, not everyone is convinced to follow Actor Model, and most of subordinate services have imperative APIs today. I would say, the more you have Actor Model in your code, the more your app is composable based on Event entity, but when you have only UI and 2-5 your own services driven by events and all external services are driven by imperative methods, in this case you just create a "friction" and rivalry. So, I am wondering if you ever saw an app in fully implemented Actor Model. It seems to me so rare and so interesting that I can't even imagine it :)

[davidkpiano]

That's true (re: needing to interact with lots of imperative APIs), but that's why actions and invocations exist in SCXML, to be able to integrate those imperative APIs in a robust and flexible way.

With XState, you can work with imperative APIs through actions:

on: {
  GO_TO_SLEEP: {
    actions: () => { human.sleep(); }
  }
}

And then you have the best of both worlds!

Re: fully implemented actor model, I'd say lots of Erlang/Elixir apps, anything built on Akka framework, and microservice architectures are very similar to (but not exactly like) the actor model, which represents a lot of software.

[serhiipalash]

Great! Thanks for sharing!