Skip to content

Commit f051f12

Browse files
docs: draft of v21 changes section
1 parent a8cd59a commit f051f12

1 file changed

Lines changed: 59 additions & 1 deletion

File tree

v21-blog-post.md

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ As easy as `withStorageSync('storeNameHere')`. IndexedDB was added last year by
2626
- `withFeature` of the SignalStore started out in the Toolkit as `withFeatureFactory`
2727
- Other features can be found in the documentation: https://ngrx-toolkit.angulararchitects.io/docs/extensions
2828

29+
// TODO - some snippets? Screenshot(s)?
30+
2931
## But first: v20 minor features: `withResource`/`withEntityResources`/Mutations
3032

3133
Before talking about v21, there were two new features from v20 Toolkit minor versions: `withResource()` and its
@@ -39,11 +41,65 @@ The Mutations API came in a later minor, providing the other pieces of the REST
3941
standalone functions (`httpMutation`/`rxMutation`), as well as in a `withMutation` feature. The API was inspired by Angular Query and Marko Stanimirović's
4042
proposed mutations API for Angular. We also had internal discussions with Alex Rickabaugh on our design.
4143

44+
// TODO - snippets?
45+
4246
## TODO: v21
4347

48+
Finally, actual Toolkit v21 notes. Future posts that are not our debut blogpost for the library won't always have a three act structure with a detailed backstory, we promise.
49+
50+
The two major items for v21 tie into topics we already discussed:
51+
52+
- Better error handling for `withResource()` and `withEntityResources()`
53+
- Events integration into the devtools
54+
55+
### Upgraded `withResource()` and `withEntityResources()` error handling
56+
57+
The error throwing behavior of Angular's resources proved tricky for the signal store. Deadlock scenario: once a resource is in an
58+
error state and we update a signal in `params`, the update calls `patchState`, which will again access the value of the state.
59+
60+
After a lot of experiemtnation, as well as discussion with various members of the Angular community, we arrived on an error handling
61+
strategy that gives Toolkit users a few options:
62+
63+
```ts
64+
// TODO - reduce indent
65+
type ErrorHandling = 'native' | 'undefined value' | 'previous value';
66+
67+
withResource(
68+
(store) => {
69+
const resolver = inject(AddressResolver);
70+
return {
71+
address: resource({
72+
params: store.id,
73+
loader: ({ params: id }) => resolver.resolve(id),
74+
}),
75+
};
76+
},
77+
// Other values: 'native' and 'previous value'
78+
{ errorHandling: 'undefined value' }, // default if not specified
79+
),
80+
```
81+
82+
Options:
83+
84+
1. `'undfined value'` (default). In the event of an error, the resource's value will be `undefined`
85+
1. `'previous value'`. Provided the resource had a previous value, that previous value will be returned. If not, an error is thrown.
86+
1. `'native'`. No special handling is provided, inline with default error behavior.
87+
88+
<!-- TODO - update link when the code is merged -->
89+
90+
Under the hood, `'previous value'` and `'undefined value'` proxy the value. For a detailed explanation for why this is done and what a more longterm solution may be with some framework enhancements, check out the [JSDoc for the error handling strategy](https://google.com).
91+
4492
### Events integration into devtools
4593

46-
### Upgraded `withResource`
94+
There is some irony with this. The NgRx Toolkit brought events to the SignalStore before there was an official plugin, and the Toolkit
95+
provides Redux Devtools integration, with or without redux used. However, the now official NgRx events feature as it shaped up
96+
did not translate directly to working with the Toolkit's `withDevtools`.
97+
98+
In NgRx Toolkit v21, we are fixing this with `withTrackedReducer()`, an alternative approach to tracking reducer-based state changes in Redux DevTools.
99+
100+
```ts
101+
// TODO - snippet with imports
102+
```
47103

48104
## TODO (also decide location) - where to mention Murat's OpenAPI library based on the toolkit
49105

@@ -59,3 +115,5 @@ An OpenAPI generator that creates:
59115
On top of that, the generated code is genuinely beautiful – which is not something you usually
60116
see with code generators. [Check it out on npm](https://www.npmjs.com/package/ngrx-toolkit-openapi-gen),
61117
as well as [its documentation](https://coderabbit-gmbh.github.io/ngrx-toolkit-openapi-gen/).
118+
119+
## TODO - where to put this and what to say - our strategy to release a compatible minor with the next major in the future in a more timely manor

0 commit comments

Comments
 (0)