I think that the following API would make things much simpler and more explicit:

const actionDirector = inject(ActionDirector);
// somewhere appropriate in the code
actionDirector.attachAction(
  CountriesState, 
  AddCountry, 
  (ctx: StateContext<string[]>, action: AddCountry) => {
    ctx.setState(countries => [...countries, action.country]);
  }
);

and to build on this example with more a complex usage and side effects:

const actionDirector = inject(ActionDirector);
const countryRepo = inject(CountryRepo);
// somewhere appropriate in the code
const detachMe = actionDirector.attachAction(
  CountriesState, 
  AddCountry, 
  async (ctx: StateContext<string[]>, action: AddCountry) => {
    // Note: this is not run inside an injection context, just like in the states
    ctx.setState(countries => [...countries, action.country]);
    await countryRepo.Add(action.country);
  }
);
const destroyRef = inject(DestroyRef);
destroyRef.onDestroy(() => detachMe());

We could also provide another function (effect) that is only for side effects that don't influence state:

const actionDirector = inject(ActionDirector);
const countryRepo = inject(CountryRepo);
// somewhere appropriate in the code
const stopEffect = actionDirector.effect(
  AddCountry, 
  async (action: AddCountry) => {
    // Note: this is not run inside an injection context, just like in the states
    await countryRepo.Add(action.country);
  }
);
const destroyRef = inject(DestroyRef);
destroyRef.onDestroy(() => stopEffect());

With respect to the naming of these functions, I have thought of a few options:

1. attachAction, effect
2. onAction, effect
3. reaction, effect

What do you think?

Good points. I think I'm leaning towards attachAction because it gives the conceptual model of an action that is connected to a state, and therefore can update that state. effect is for side effects, and has nothing to do with a state, so that name is good.

I also think that the signature for the function should require the state model type information (to be able to provide to the StateContext), and, with that in mind, maybe requiring a StateToken as opposed to a state class as the first parameter would push towards the more type safe API.

I have made some changes and added documentation for this feature.
@joaqcid and @profanis please could you have a read through the docs I created for this and give me your feedback?

The explanation is easy to follow 💯

I have made some changes and added documentation for this feature. @joaqcid and @profanis please could you have a read through the docs I created for this and give me your feedback?

i added a couple of comments, but overall looks great!

thanks!!