docs(mutations): document mutations API #228

michael-small · 2025-09-05T04:17:03Z

No description provided.

michael-small · 2025-09-06T20:04:32Z

@manfredsteyer @rainerhahnekamp I have prefaced the who/why of the mutations part. Onto the actual API + examples.

michael-small · 2025-09-07T02:35:43Z

Update: I have fleshed out the details. I am going to rest and then refine this to a formal submission midday CST tomorrow.

It's particularly verbose and repetitive, but that's normal for a first rough draft for me. And in some ways it takes from the structure of withResource, but in other ways diverged when I overthought stuff.

If you have any feedback before I formally mark this ready then feel free.

apps/demo/src/app/counter-rx-mutation/counter-rx-mutation.ts

michael-small · 2025-09-07T20:38:18Z

docs/docs/mutations.md

+
+- Why we do not use [`withResource`](./with-resource), and the direction on mutations from the community
+- Key Features ([summary](#key-features-summary) and [in depth](#key-features-in-depth)):
+  <!-- TODO (discuss): I think it is important to know it is `HttpClient` under the hood for stuff like interceptors and global stuff -->


While it may be more of an implementation detail, it is important that people know global functions like interceptors will still work. While we can't hook into non-rjxs HttpClient API like Angular's source can do with httpResource and have to do this, I believe this detail is an important one.

Yes, yes, people should know that this not yet a replacement for the HttpClient. We should include that information.

michael-small · 2025-09-07T20:40:14Z

docs/docs/mutations.md

+  - `rx`'s `operation` is a function that defines the mutation logic. It returns an Observable,
+  - `http` takes parts of `HttpClient`'s method signature, or a `request` object which accepts those parts
+
+<!-- TODO - I was wrong on flattening part, re-write -->


@rainerhahnekamp after our discussion about my misunderstanding, I think you or @manfredsteyer would be better suited to write this part instead

I commented in detail on that topic above. Feel free to move it here.

michael-small · 2025-09-07T20:41:34Z

docs/docs/mutations.md

+  - Callbacks available (`onSuccess` and `onError`)
+  - Flattening operators (`concatOp, exhaustOp, mergeOp, switchOp`)
+  - Calling the mutations (optionally as promises)
+  <!-- TODO - narrowing not working like intended? -->


I made an issue for this: #235 Leaving this in for emphasis until the round of feedback changes.

michael-small · 2025-09-07T20:45:50Z

@manfredsteyer @rainerhahnekamp ready for review

rainerhahnekamp

Very good Michael, I left a few comments, which also include a longer explanation on the flattening operators. For me there are two big points, which we should address more:

httpMutation - Types, onSuccess and parse: As mentioned in some comments, we should't motivate users to do explicit typing. The problem is that we are hindering ourselfs to increase the number of generic types we can have. With type inference (so no explicit types), we could have as many types we want. In the request function you define the type of the first parameter. Then, if we have just onSuccessbut no parse, the type of the onSuccess parameter is taken. If we parse but no onSuccess it is going to be parse. If both parse and onSuccess are there (we have tests for that btw), then parse dictates the type and onSuccess has it already implicitely.
Why do we return a Promise and not something else, like an Observable or Signal? We were looking at the use case for showing a message, navigating to a different route or showing/hiding a loading indicator while the mutation is active or ends. If we use a Signal, then it could be that a former mutation already set the value successful on the status. If we would have an effect, waiting for the Signal to have successful, that one would run immediately...not good. Observable would have the same problem and it would also add be an API which exposes an Observable which means user have to do deal with RxJS once more. A Promise is perfect. It gurantees to return just a single value where Observable can emit one, none or multiple. it is always asynchronous and not like Observables both. The syntax with await makes it quite good for DX and it is very easy to go from a Promise to an Observable or even Signal.

rainerhahnekamp · 2025-09-09T19:53:23Z

docs/docs/mutations.md

+
+## Basic Usage
+
+The mutations feature (`withMutations`) and methods (`httpMutation` and `rxMutation`) seek to offer an appropriate equivalent to signal resources for sending data back to the backend. The methods can be used in `withMutations()` or on their own.


Do you think it is worht mentioning, that using them on their own means, outside the SignalStore?

Yeah, I could clarify that

rainerhahnekamp · 2025-09-09T19:54:05Z

docs/docs/mutations.md

+
+- Why we do not use [`withResource`](./with-resource), and the direction on mutations from the community
+- Key Features ([summary](#key-features-summary) and [in depth](#key-features-in-depth)):
+  <!-- TODO (discuss): I think it is important to know it is `HttpClient` under the hood for stuff like interceptors and global stuff -->


Yes, yes, people should know that this not yet a replacement for the HttpClient. We should include that information.

rainerhahnekamp · 2025-09-09T19:56:23Z

docs/docs/mutations.md

+
+### Path the toolkit is following for Mutations
+
+Libraries like Angular Query offer a [Mutation API](https://tanstack.com/query/latest/docs/framework/angular/guides/mutations) for such cases. Some time ago, Marko Stanimirović also [proposed a Mutation API for Angular](https://github.com/markostanimirovic/rx-resource-proto). These mutation functions and features are heavily inspired by Marko's work and adapts it as a custom feature/functions for the NgRx Signal Store.


Maybe one can also add that we had internal discussions with Alex Rickabaugh on our design. I think it adds value to our feature if users know that the Angular team was involved a little bit.

rainerhahnekamp · 2025-09-09T19:59:20Z

docs/docs/mutations.md

+
+Each mutation has the following:
+
+1. Parameters to pass to an RxJS stream (`rxMutation`) or RxJS agnostic `HttpClient` call (`httpMutation`)


I think it should be either bullet points or numbers (but then not just only 1 ;) )

Markdown automatically numbers it

1. test 1. test 1. test

becomes

test

test

test

rainerhahnekamp · 2025-09-09T20:00:25Z

docs/docs/mutations.md

+1. Parameters to pass to an RxJS stream (`rxMutation`) or RxJS agnostic `HttpClient` call (`httpMutation`)
+1. Callbacks: `onSuccess` and `onError` (optional)
+1. Flattening operators (optional, defaults to `concatOp`)
+1. Exposes a method of the same name as the mutation, returns a promise.


Is "Exposing" the right term here? Isn't it more like that rxMutation and httpMutation are factory functions returning the actual mutation function (which again returns a Promise)?

That's better, I knew there was better vocabulary

rainerhahnekamp · 2025-09-09T20:18:04Z

docs/docs/mutations.md

+For brevity, take `rx` as `rxMutation` and `http` for `httpMutation`
+
+- `rx` to utilize RxJS streams, `http` to make an `HttpClient` request
+  - `rx` could be any valid observable, even if it is not HTTP related.


Observable?

rainerhahnekamp · 2025-09-09T20:18:33Z

docs/docs/mutations.md

+  - `rx` could be any valid observable, even if it is not HTTP related.
+  - `http` has to be an HTTP request. The user's API is agnostic of RxJS. _Technically, HttpClient with observables is used under the hood_.
+- Primary property to pass parameters to:
+  - `rx`'s `operation` is a function that defines the mutation logic. It returns an Observable,


Observable

rainerhahnekamp · 2025-09-09T20:18:57Z

docs/docs/mutations.md

+  - `rx`'s `operation` is a function that defines the mutation logic. It returns an Observable,
+  - `http` takes parts of `HttpClient`'s method signature, or a `request` object which accepts those parts
+
+<!-- TODO - I was wrong on flattening part, re-write -->


I commented in detail on that topic above. Feel free to move it here.

rainerhahnekamp · 2025-09-09T20:21:33Z

docs/docs/mutations.md

+import { concatOp, exhaustOp, mergeOp, switchOp } from '@angular-architects/ngrx-toolkit';
+```
+
+## Basic Usage


Should we have a TLTR? It is quite long (but worth it) until you hit the actual example with withMutations.

That was my intent with the bullet points under this. What are you thinking to be more explicit/brief? A snippet, a couple sentences?

Added example

rainerhahnekamp · 2025-09-09T20:24:23Z

docs/docs/mutations.md

+      operation: (params: Params) => {
+        return calcSum(store.counter(), params.value);
+      },
+      operator: concatOp,


I wouldn't add concatMap because it is the default. In fact I think using operator is going to be an edge case.

michael-small · 2025-09-11T00:37:16Z

httpMutation - Types, onSuccess and parse: As mentioned in some comments, we should't motivate users to do explicit typing. The problem is that we are hindering ourselfs to increase the number of generic types we can have. With type inference (so no explicit types), we could have as many types we want. In the request function you define the type of the first parameter. Then, if we have just onSuccessbut no parse, the type of the onSuccess parameter is taken. If we parse but no onSuccess it is going to be parse. If both parse and onSuccess are there (we have tests for that btw), then parse dictates the type and onSuccess has it already implicitely.

Like this? I have to set the _: void since it isn't assumed

    saveToServer: httpMutation({
      request: (_: void) => ({ // I cannot get it to infer void implicitly
        url: `https://httpbin.org/post`,
        method: 'POST',
        body: { counter: store.counter() },
        headers: { 'Content-Type': 'application/json' },
      }),
      parse: (res) => res as CounterResponse,
      onSuccess: (response) => {
        console.log('Counter sent to server:', response);
        patchState(store, { lastResponse: response.json });
      },
      onError: (error) => {
        console.error('Failed to send counter:', error);
      },
    }),

michael-small · 2025-09-11T02:01:48Z

I have integrated all the changes, other than not being exactly sure how to refer to the state consistently.

edit: oops I was in an offshoot branch, merged that in

docs(mutations): create draft of mutations

5c3fb10

michael-small self-assigned this Sep 5, 2025

michael-small added the documentation Improvements or additions to documentation label Sep 5, 2025

michael-small linked an issue Sep 5, 2025 that may be closed by this pull request

docs: add httpMutate page #227

Closed

docs(mutations): write preface ("why" & "who")

ee60344

Michael added 6 commits September 6, 2025 17:46

docs(mutations): provide examples at top

29d1d56

docs(mutations): give example snippet + WIP usage

d55c440

docs(mutations): list differences between rx and http

98e15ce

docs(mutations): write in depth features (state/callbacks/methods)

0e216da

docs(mutations): show in vs out of store use

6c54c31

docs(mutations): re-order + flesh out misc points

3177b29

Michael added 10 commits September 7, 2025 10:47

docs(mutations): add imports for mutations flatteners

c5fe637

docs(mutations): re-order examples + background

0d7fa1c

docs(mutations): remove extra callback example

8d1e242

docs(mutations): remove our RFC copypasta + link to withResource

3420f9d

docs(mutations): add full example

aac5421

docs(mutations): misc feedback, emphasis on flattening operators

78d102e

docs(mutations): hyperlink to other sections, some ordering

15118c6

docs(mutations): fix typos

6d798c1

docs(mutations): mention resource non-GET edge case...

e990da5

docs(mutaitons): mention summary section on where to use

289d995

michael-small commented Sep 7, 2025

View reviewed changes

apps/demo/src/app/counter-rx-mutation/counter-rx-mutation.ts Show resolved Hide resolved

michael-small commented Sep 7, 2025

View reviewed changes

chore(mutations): remove TODO

d495c08

michael-small marked this pull request as ready for review September 7, 2025 20:45

michael-small requested review from manfredsteyer and rainerhahnekamp September 7, 2025 20:46

rainerhahnekamp mentioned this pull request Sep 8, 2025

RFC: Builder-linke Pattern for Creating Mutations #225

Closed

rainerhahnekamp requested changes Sep 9, 2025

View reviewed changes

Michael added 17 commits September 10, 2025 19:54

docs(mutations): use inference for httpMutation

9184273

docs(mutation): specify typing of value with parse

03290b1

docs(mutation): capitalize Promise

bd0eb16

docs(mutation): mention why Promise for methods

635c8c8

docs(mutation): signalStore/SignalStore

65c4388

docs(mutation): observable --> Observable

039d92b

docs(mutations): mention flattening operator nuances

19479c0

docs(mutations): specify use outside of store

3aea73d

docs(mutation): mention discussion w/team

e258350

docs(mutation): exposes --> factory function

7672959

docs(mutations): remove explicit json header

80e69e9

docs(mutation): show parse/callback inference

b7408f5

docs(mutations): add link from homepage

3ad0061

docs(mutation): remove numbering in values

2133463

docs(mutations): add preview example

83dfa3e

docs(mutations): use wording for signals !== signalstate

befa426

docs(mutation): resolve a TODO

32da9c8

michael-small added 2 commits September 11, 2025 05:00

Merge pull request #2 from michael-small/docs-mutations-wip

e8f01e0

Merge pull request #3 from michael-small/docs-mutations-2

fb79d59

rainerhahnekamp approved these changes Sep 11, 2025

View reviewed changes

rainerhahnekamp merged commit 15db547 into angular-architects:main Sep 11, 2025
1 check passed

michael-small deleted the docs-mutations branch October 7, 2025 23:07


		## Basic Usage

		The mutations feature (`withMutations`) and methods (`httpMutation` and `rxMutation`) seek to offer an appropriate equivalent to signal resources for sending data back to the backend. The methods can be used in `withMutations()` or on their own.


		### Path the toolkit is following for Mutations

		Libraries like Angular Query offer a [Mutation API](https://tanstack.com/query/latest/docs/framework/angular/guides/mutations) for such cases. Some time ago, Marko Stanimirović also [proposed a Mutation API for Angular](https://github.com/markostanimirovic/rx-resource-proto). These mutation functions and features are heavily inspired by Marko's work and adapts it as a custom feature/functions for the NgRx Signal Store.


		Each mutation has the following:

		1. Parameters to pass to an RxJS stream (`rxMutation`) or RxJS agnostic `HttpClient` call (`httpMutation`)

docs(mutations): document mutations API #228

docs(mutations): document mutations API #228

Uh oh!

Conversation

michael-small commented Sep 5, 2025

Uh oh!

michael-small commented Sep 6, 2025

Uh oh!

michael-small commented Sep 7, 2025

Uh oh!

Uh oh!

michael-small Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michael-small commented Sep 7, 2025

Uh oh!

rainerhahnekamp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michael-small commented Sep 11, 2025

Uh oh!

michael-small commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michael-small Sep 7, 2025 •

edited

Loading

michael-small commented Sep 11, 2025 •

edited

Loading