diff --git a/docs/docs/with-entity-resources.md b/docs/docs/with-entity-resources.md index 57d54e88..c1d30969 100644 --- a/docs/docs/with-entity-resources.md +++ b/docs/docs/with-entity-resources.md @@ -1,5 +1,5 @@ --- -title: withEntityResources() +## title: withEntityResources() --- ```typescript @@ -86,6 +86,35 @@ This exposes per-resource members with the resource name as a prefix: - **Resource members**: `todosValue()`, `todosStatus()`, `todosError()`, `todosIsLoading()`; `projectsValue()`, ... - **Entity members**: `todosIds()`, `todosEntityMap()`, `todosEntities()`; `projectsIds()`, `projectsEntityMap()`, `projectsEntities()` +## Error Handling + +The behavior of Angular's resources' error handling and the NgRx SignalStore's `getState/patchState` required `withEntityResource` to approach error handling +with a particular strategy unique to the intersection of resources and the Signal Store. +To prevent resource failures from blocking the store, the Toolkit provides some strategies to handle errors. + +```ts +withEntityResource( + () => ({ + id: resource({ + loader: () => Promise.resolve(1), + defaultValue: 0, + }), + }), + // Other values: 'native' and 'previous value' + { errorHandling: 'undefined value' }, // default if not specified +), +``` + +Options: + +1. `'undfined value'` (default). In the event of an error, the resource's value will be `undefined` +1. `'previous value'`. Provided the resource had a previous value, that previous value will be returned. If not, an error is thrown. +1. `'native'`. No special handling is provided, inline with default error behavior. + + + +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). + ## Component Usage ```typescript diff --git a/docs/docs/with-resource.md b/docs/docs/with-resource.md index 869ed59e..70b70af0 100644 --- a/docs/docs/with-resource.md +++ b/docs/docs/with-resource.md @@ -83,6 +83,35 @@ With named resources, each resource gets prefixed properties: - **Single resource:** use when your store works with just one data source. - **Named resources:** use when your store is larger and manages multiple entities or async operations. +## Error Handling + +The behavior of Angular's resources' error handling and the NgRx SignalStore's `getState/patchState` required `withResource` to approach error handling +with a particular strategy unique to the intersection of resources and the Signal Store. +To prevent resource failures from blocking the store, the Toolkit provides some strategies to handle errors. + +```ts +withResource( + () => ({ + id: resource({ + loader: () => Promise.resolve(1), + defaultValue: 0, + }), + }), + // Other values: 'native' and 'previous value' + { errorHandling: 'undefined value' }, // default if not specified +), +``` + +Options: + +1. `'undfined value'` (default). In the event of an error, the resource's value will be `undefined` +1. `'previous value'`. Provided the resource had a previous value, that previous value will be returned. If not, an error is thrown. +1. `'native'`. No special handling is provided, inline with default error behavior. + + + +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). + ## Component Usage ```typescript