Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/docs/with-entity-resources.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The complete withEntityResource is based on the undefined value strategy. I think we just need to here a quick note on that and link to withResource for further details.

Users cannot change the error handling here, since withEntityResource uses the resource internally. It is an implementation detail so to say.


Starting in NgRx Toolkit v20.6.0, error handling now has more resilient options.

The behavior of Angular's resources' error handling and the NgRx SignalStore's `getState/patchState` required `withEntityResource` to approach error handling
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO - I phrased this so weird. Once the v21 blog post is more fleshed out, take what was written there and replace some of this awkwardness.

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://github.com/angular-architects/ngrx-toolkit/blob/main/libs/ngrx-toolkit/src/lib/with-resource.ts#L402).

## Component Usage

```typescript
Expand Down
29 changes: 29 additions & 0 deletions docs/docs/with-resource.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Starting in NgRx Toolkit v20.6.0, error handling now has more resilient options.

The behavior of Angular's resources' error handling and the NgRx SignalStore's `getState/patchState` required `withResource` to approach error handling
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't be that specific. I would just say sometihng like

that the error throwing behavior of the native resource causes a deadlock in the error case. That's why withResource comes with a different error handling, which doesn't throw.

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`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. `'undfined value'` (default). In the event of an error, the resource's value will be `undefined`
1. `'undefined 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't mention the condition that it only returns if a previous value exists. It just returns the previous value.

A resource always has a value in its initial state. The implementation needs to consider a "non-realsitic" scenario because of TypeScript.

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://github.com/angular-architects/ngrx-toolkit/blob/main/libs/ngrx-toolkit/src/lib/with-resource.ts#L402).

## Component Usage

```typescript
Expand Down