V5: Providing more specific types within implementation.

[chaulkie]

Here's my situation: I want a base machine that contains the bulk of my logic, e.g.

const baseMachine = createMachine({
  types: {} as BaseSchema,
  context: ({input}) => {
    ...input,
    data: {},
  },
  on: {
    UPDATE: { actions: "evaluate" }
  }
  states: {
    // Some state logic
  }
})

Then I want to provide the evaluate action. In fact, I want many different implementations, with different evaluate actions, and each might take a different set of parameters. I want to get these parameters from context.params, which is to be supplied as input when creating actors.

const rangeMachine = baseMachine.provide({
  actions: {
    evaluate: raise(({ context: {params, data} }) => {
      if (data.value > params.maxValue) {
        return { type: "ALARM" };
      } else if (data.value < params.minValue) {
        return { type: "ALARM" };
      }
      return { type: "RETURN" };
    }),
  },
});

And this is trivial of course, but I want some nice typings for params both within the evaluate implementation, and in the input argument when I createActor(rangeMachine, { ... }).

The obvious potential solution is to instead use setup instead, something like

const rangeMachine = setup({
  types: SlightlyMoreWellDefinedSchema
  actions: { ... } // Gives me well-typed arguments to implement with
}).createMachine(baseMachine.config);

But I get type-conflicts (even without defining any types). The lazy fix is to use .createMachine(baseMachine.config as any), but I would like to avoid such bad practice if possible, and besides this way seems a little intuitively backwards for my use-case; I want rangeMachine to proceed from baseMachine, not to be vaguely coupled with it.

What I really want to have is an allowable types field in .provide({ ... }), where the schema is checked against that of the parent machine to ensure that it is more specific and not more general.

[chaulkie]

After some more development I have found the .createMachine(baseMachine.config as any) more unsatisfactory, as it doesn't allow default implementations. For example I want some delays that will be common to all machines. I can't inline them since they need to be calculated, but if I put them in the implementation parameter of createMachine they won't be present in the setuped machine. I don't particularly want to repeat the delays in every setup call.

[chaulkie]

It now seems that .createMachine(baseMachine.config) (without the as any) now works! I'm unsure whether this is because I changed something, or it was fixed by a new release.

But my overall feeling of the approach still stands, and especially the part about default implementations in the last comment. I have worked around the issue with a factory function, but am still looking for a more elegant solution.

To reiterate, my intuitive feeling is that I would like to provide the types. But of course I'm open to any existing solutions that I've overlooked. As I've been working with xstate more I've found there are often many ways to achieve the same thing, and it's hard to know the best way forward.

[davidkpiano]

Here is how I would do it, with strong typings:

const baseMachine = setup({
  types: {
    context: {} as { data: { value: number } }
  },
  actions: {
    evaluate: raise((_, params: { data: { value: number }; minValue: number; maxValue: number }) => {
      if (params.data.value > params.maxValue) {
        return { type: "ALARM" };
      } else if (params.data.value < params.minValue) {
        return { type: "ALARM" };
      }
      return { type: "RETURN" };
    })
  }
}).createMachine({
  context: ({input}) => ({
    // ...
    data: {
      value: 5
    }
  }),
  on: {
    UPDATE: { actions: {
      type: 'evaluate',
      params: ({ context }) => ({
        data: context.data,
        minValue: 0,
        maxValue: 100
      })
    } }
  },
  states: {
    // Some state logic
  }
})

[chaulkie]

That doesn't quite do it, because in my case the config can't know for sure what parameters the evaluate function will take, (minValue, maxValue was just one example, it could be, say, setpoint, margin). Basically I think the config has to be unchanging, and there are multiple implementations which are built on that config.

These are my issues with the standard setup(implementation).createMachine(config) approach for my use-case.

• The ordering is unintuitive and inconvenient because I want multiple implementations of one config, not multiple configs of one implementation.
• I can't provide common config elements in createMachine(); I have to repeat them in each .setup().
• I have a slightly different schema for each implementation, and I want some assurance that these schemas are compatible with the base schema I have defined.

I have solved each of these issues by implementing a factory function, but what I'm looking for is a solution that doesn't require a factory function.

A solution that would solve most of my problems would be to allow the user to .provide() additional typings, along with the rest of the implementation. I did have this thread originally marked under "Ideas", but moved it to this board because I didn't have enough confidence that my problem wasn't solvable with existing features. But perhaps i should put it back?

[Andarist]

A solution that would solve most of my problems would be to allow the user to .provide() additional typings, along with the rest of the implementation.

Could you expand on that with some PoC examples? The problem of setup-less scenario is that this is allowed:

const machine = createMachine({
  invoke: [{ src: 'a' }, { src: 'b' }]
}).provide({
  actors: {
    a: fromPromise(async () => 'foo')
  }
})

createActor(machine).start()

As we can see here, we were able to instantiate a machine even though an implementation for b was not provided. In almost all situations, this is a problem and a gotcha for people. setup eliminates this risk since you are forced to provide all of the implementations upfront (even if they are just stubs for the real implementations that you later on plan to .provide)

[chaulkie]

I want to do something like this:

// The base machine logic that I want to fork off into multiple inheriting machines
const baseAlarmMachine = createMachine({
  types: {
    input: {} as {
      params: Record<string, unknown>,
      name: string,
    },
    context: {} as {
      params: Record<string, unknown>,
      data: Record<string, unknown>,
      updatedAt: Date,
    }
  },
  context: ({input}) => ({
    name: input.name,
    params: input.params,
    updatedAt: new Date(Date.now()),
    data: {},
  }),
  on: {
    UPDATE: { actions: "evaluate" }
  },
  states: {
    // Some state logic
  }
})


// A machine implementation that has some unique parameters
type RangeParams = {
  minValue: number,
  maxValue: number,
}

const rangeMachine = baseAlarmMachine.provide({
  types: {
    input: {} as {
      params: RangeParams,
      name: string,
    },
    context: {} as {
      params: RangeParams,
      data: {
        value: number,
      },
      updatedAt: Date,
    }
  },
  actions: {
    evaluate: raise(({ context: {params, data} }) => {
      if (data.value > params.maxValue) {
        return { type: "ALARM" };
      } else if (data.value < params.minValue) {
        return { type: "ALARM" };
      }
      return { type: "RETURN" };
    }),
  },
});


// Another machine with different parameters
type SetpointParams = {
  setpoint: number,
  margin: number,
}

const setpointMachine = baseAlarmMachine.provide({
  types: {
    input: {} as {
      params: SetpointParams,
      name: string,
    },
    context: {} as {
      params: SetpointParams
      data: {
        value: number,
      },
      updatedAt: Date,
    }
  },
  actions: {
    evaluate: raise(({ context: {params, data} }) => {
      if (data.value > params.setpoint + params.margin) {
        return { type: "ALARM" };
      } else if (data.value < params.setpoint - params.margin) {
        return { type: "ALARM" };
      }
      return { type: "RETURN" };
    }),
  },
});

You can see that the different implementations for evaluate have different parameter requirements. Like I said I realise this is achievable with setup, and have done so, but its a little bit finicky and required a factory function. It doesn't seem I can give default implementations in the base machine config, and I end up with some unsightly type-manipulation magic. In itself its not a huge deal, but it compounds with other complexities in my use case, and I'm just looking for elegance where I can.

In the meantime, another solution I thought up is to implement evaluate not as an action but as a callback actor. Each type of evaluation actor would have a factory function. You would have:

baseMachine.provide({
  actors: {
    evaluator: {
      src: rangeEvaluator(minValue, maxValue)
    }
  }
})

The actor will initialize by validating parameters (another piece of this puzzle I didn't mention), then injecting them into the context (purely so they are visible at runtime), then will communicate back and forwards with the machine. This could fit well; it lends itself to a composition-style architecture, and I already have another actor which is constructed similarly.

P.S. You talk about the createMachine().provide() pattern like its considered harmful and is marked to be deprecated. Is that the case? or does it just remain as a possible approach that is nonetheless discouraged unless absolutely necessary?

[Andarist]

Given the example above, how do we make sure that is correct and that it does use all of the required params (with correct types)?:

  on: {
    UPDATE: { actions: "evaluate" }
  },

I think this "call site" of the evaluate just stays unsound unless you configure the params types beforehand (in setup) or at the same time (in createMachine). TS just can't typecheck this based on the information that is provided later (in provide). If you want this kind of generic-ness then factory functions are the only way since it's the only way to make it work in TypeScript.

I see now that your example is using context.params (and not params that belong to an action). However, that doesn't change that much here since the dependency (context) still has to have some known type for it to flow into your evaluate.

You talk about the createMachine().provide() pattern like its considered harmful and is marked to be deprecated. Is that the case? or does it just remain as a possible approach that is nonetheless discouraged unless absolutely necessary?

There are no plans to deprecate this right now.

[chaulkie]

OK that makes sense. I'm thinking I might try approaching this using callback actors unless you have another suggestion. Thanks a lot for your help!

[tnortman]

@chaulkie can you share your solution, or factory function? I am running into a similar situation