docs(core): document resource chaining with chain() in params context#69348
docs(core): document resource chaining with chain() in params context#69348sausi-7 wants to merge 5 commits into
Conversation
Adds a new 'Chaining resources' section to the resource guide covering: - Basic usage of chain() to depend one resource on another - Automatic status propagation (loading/idle/error) - Chaining vs reading .value() directly - Synchronous value transformation via chained resource Closes angular#69329
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
|
I have signed the CLA. |
Pass the chained value directly as params so when chain() returns undefined the downstream resource becomes idle rather than throwing. Addresses review feedback from @JeanMeche on PR angular#69348.
|
Good catch, thank you! Updated the example to pass the chained value directly as params ( |
The example used an async resource to do synchronous string mapping then recommended computed instead, which was confusing. Replaced with a concise note clarifying when to reach for chain vs computed. Addresses review feedback from @JeanMeche on PR angular#69348.
|
You're right, that section was misleading. It used an async resource to do synchronous string mapping and then said to use computed instead, so it was basically showing an anti pattern as if it was a feature. I removed it and added a short note instead clarifying that chain is for when the downstream resource does its own async work, and computed is the right tool when you just need to derive a value synchronously. |
Reword the description so it matches chain(userResource)?.id being passed directly as params, and explain why returning the value directly (instead of wrapping it in an object) keeps the idle behaviour. Addresses review feedback from @JeanMeche on PR angular#69348.
|
Updated the wording so it matches the new example. It now says chain reads the value (which can be undefined) instead of saying it returns the resolved value, and the bullet for the resolved case reflects that the value is used as params. I also rephrased the note to explain why passing chain(userResource)?.id directly matters: if you wrap it in an object like {userId: undefined} the params are still defined so the loader would run with an undefined id, whereas passing the value directly lets the resource go idle when there is no upstream value. |
| - If `userResource` is in an **error** state, `userPostsResource` also enters the `error` state. | ||
| - If `userResource` is **resolved**, `chain` returns its value, which `userPostsResource` then uses as its params. | ||
|
|
||
| A resource's value can be `undefined`, so `chain` can return `undefined` too. The example passes `chain(userResource)?.id` directly as the params value, so when there is no upstream value the params are `undefined` and `userPostsResource` becomes `idle`. Returning the value directly is important here: a params value like `{userId: undefined}` is still defined, so it would run the loader with an `undefined` id instead. |
There was a problem hiding this comment.
I'm not sure that sentence makes a lot of sense.
A resource's value can be
undefined, sochaincan returnundefinedtoo.
This is indeed true but I'm not sure this is worth calling out.
The example passes
chain(userResource)?.iddirectly as the params value, so when there is no upstream value the params areundefinedanduserPostsResourcebecomesidle.
But if a resource is idle or loading, chain() will actually throw a specific error do the loader won't run because of the said error.
Returning the value directly is important here: a params value like
{userId: undefined}is still defined, so it would run the loader with anundefinedid instead.
This might be worth a callout on its own with NOTE:
…to callout Clarify that chain throws to propagate status when the upstream resource is not resolved, and only returns undefined when the resolved value is undefined. Move the direct-value vs object params guidance into its own NOTE callout. Addresses review feedback from @JeanMeche on PR angular#69348.
|
Both good points, fixed. You're right that chain throws when the resource is idle or loading, it does not return undefined in those cases. I reworded it so it now says chain throws to propagate the status when the upstream is not resolved, and that it only returns undefined when the resolved value itself is undefined. I also moved the bit about passing the value directly instead of wrapping it in an object into its own NOTE callout. |
Which issue does this PR close?
Closes #69329
Description
Angular 22 introduced resource chaining via the
chainfunction inResourceParamsContext. This feature had no documentation in the signals resource guide.This PR adds a "Chaining resources" section to
adev/src/content/guide/signals/resource.mdcovering:chain(resource)insideparamsto make one resource depend on anotherloading/idle/error, the downstream mirrors that status so the loader never runs with missing data.value()directly — explains whychainis preferred: reading.value()collapses any non-resolved state toidle, whereaschaincorrectly propagatesloadinganderrorcomputedis a better fitType of change
Checklist