RFC: Builder-linke Pattern for Creating Mutations

[manfredsteyer]

Usually, we don't want to define details of the underlying HTTP call in the store. It's more usual to move this into a service:

readonly save() {
  return httpMutation<Flight, Flight>( (flight) => ({
      url: 'https://...',
      method: 'POST',
      body: flight,
  }));
}

However, the store needs to be able to specify the success and error handlers, as well as the flattening operator to use. To streamline this task, this RFC proposes a builder-like style for specifying these details via setters in the store:

withMutations((store) => ({
  save: store._flightService.save()
    .withOnSuccess: (result: Flight) => {
      patchState(store, { flightValue: result });
      store._snackBar.open('Flight saved!', 'OK');
    }
    .withOnError: (error: any) => {
      console.error('Error saving flight:', error);
      store._snackBar.open('Error saving flight', 'OK');
    },
    .withOperator(mergeOp),
  }),
),

Alternative

Providing types that expose all mutation options but the operation (rxMutation) or request (httpMutation) so that the caller can pass these options to the service:

export type MutationSettings<Params, Result> = Omit<
  HttpMutationOptions<Params, Result>,
  'request'
>;

In this case, the service method can be configured by the caller:

createSaveMutation(options: MutationSettings<Flight, Flight>) {
  return httpMutation({
    ...options,
    request: (flight) => ({
      url: 'https://demo.angulararchitects.io/api/flight',
      method: 'POST',
      body: flight,
    }),
  });
}

In the store, such a method could be called as follows:

withMutations((store) => ({
  save: store._flightService.createSaveMutation({
    onSuccess: (result: Flight) => {
      patchState(store, { flightValue: result });
      store._snackBar.open('Flight saved!', 'OK');
    },
    onError: (error: any) => {
      console.error('Error saving flight:', error);
      store._snackBar.open('Error saving flight', 'OK');
    },
  }),
})),

One disadvantage of this solution is that it adds one more level of nesting when calling the service method.

[rainerhahnekamp]

Good evening, if I have a service like the flight service in your example… what speaks against using rxMutation and let the operation call the service?

[manfredsteyer]

This is also an option: Putting the request or operation into the service. However, in this case, the Store needs to know whether it's an rxMutation, an httpMutation, or some other type of mutation we might add eventually.

When using resources, this is not the case -- here, we can entirely create the resource inside of the service method. Hence, withResource does not know about the concrete type of the resource.

[rainerhahnekamp]

Got it. Let me think about an option that would also work for withResource. We obviously have the same problem twice and a single solution should be good

[GregOnNet]

Hi,

the API slightly goes in the direction that tanstack/query provides (see reference).

Maybe, it is worth to borrow a few ideas from there...

withMutations(store => ({
  save: { // could be configure with Observables
    mutation$: /* ... */,
    onSuccess: () => /* ... */,
    onError: err => /* ... */,
    retry: /* ... /*,
    resubsribeOnError: true // 😉
  },
  update: { // could be configured with signals
    mutation: store._flightService.save(),
    onSuccess: () => /* ... */,
    onError: err => /* ... */,
    retry: /* ... /*
    executionBehavior: 'cancelPendingOpertaion' | 'ignoreIfPendingOperation |'runAfterPendingOperation' // mimic behavior of rxjs operators (exhaustMap, switchMap, concatMap), executionBehavior could also accept a function with a custom behavior (strategy)
  }
})

[rainerhahnekamp]

@GregOnNet in case you haven't seen it, but we landed a mutation feature yesterday: #219 and #202. And we don't have an automatic resubscription but I hope that the solid error handling doesn't require it.

[GregOnNet]

Hey @rainerhahnekamp,

thanks for pointing out, that rxMutation made its way to the lib.
I did not notice it.

I do not want to hinder or disturb your vision on providing extensions to the signal store. 🤗
Furthermore, I was just thinking on how I would shape the API.

Topic

In my code-snippet, I wanted to show, that the alternative to a fluent-API would be a configuration.
Before coding and maintaining withOnSuccess etc. the configurational approach is worth looking at.
It can be enhanced and typed in an easier way.
Goodies like retry or caching can be added later on if the developers are in need. :-)

For resources, that do not origin from RxJS-streams the behavior of switch-, merge-, exhaust- and concatMap is still relevant and might be implemented with or without RxJS operators.
That's why I added (executionBehavior - could be named differently of cause).

Of topic

resubscribeOnError

In the team, we saw just some confusion here.
A lot of NgRx-veterans tend to imply that rxMethod mimics createEffect so the were confused, why it stops working once the stream broke. Especially when a global error handler was installed, but the error was not caught there.
I can provide an example, if you like.

This being said, rxMutation could inherit the same expectations developer have. :-)

[rainerhahnekamp]

A lot of NgRx-veterans tend to imply that rxMethod mimics createEffect so the were confused, why it stops working once the stream broke. Especially when a global error handler was installed, but the error was not caught there.
I can provide an example, if you like.

No need for an example, I can actually tell you why it doesn't resubscribe automatically. This was a design decision based on removing "magic" which might make things working differently. In that case the magic would be that a resubscription happens, whereas this is never the case with a normal Observable.

Next to that, mapResponse and tapResponse were introduced to enforce proper error handling by the developers.

---

About the mutations. We were a little bit in a hurry for the Webinar today but we plan to bring out a full documentation about it. The current way is quite close to your version. Manfred's proposed builder pattern might be a solution to a problem which I hope I can find a solution via the type system internally...we'lll see

[GregOnNet]

No need for an example, I can actually tell you why it doesn't resubscribe automatically. This was a design decision based on removing "magic" which might make things working differently.

Yeah, the “expectations” are not related to the API. I fall over this “trap” myself, but it actually isn't.
This is also where documentation can help.

[rainerhahnekamp]

Alright, I see now that I misunderstood the issue and had something else in mind.

For the current case, I see your suggested factory approach is the best option since it doesn’t introduce another level. We should definitely document this in #228.

If users start to raise concerns, we can always revisit the topic.

Another possible path could be for SignalStore to provide a tighter integration out of the box — for example, offering an adapter with dedicated onSuccess/onError handlers and internally relying on a Promise.

For now though, and if we decide to go in that direction later, I’d still consider the builder approach more elegant (guess we both can’t hide our backend background 😉).

---

@manfredsteyer if you agree on this, could you close that issue?