refactor(core): rename resource's request to params (angular#60919)

As decided in the resource RFC, this commit renames the `request` option of
a resource to `params`, including the subsequent argument passed to the
loader. It also corrects the type in the process to properly allow narrowing
of the `undefined` value.

Fixes angular#58871

PR Close angular#60919

Author: alxhub

adev/shared-docs/services/search.service.ts

@@ -55,8 +55,8 @@ export class Search {
   private readonly client = inject(ALGOLIA_CLIENT);
 
   searchResults = resource({
-    request: () => this.searchQuery() || undefined, // coerces empty string to undefined
-    loader: async ({request: query, abortSignal}) => {
+    params: () => this.searchQuery() || undefined, // coerces empty string to undefined
+    loader: async ({params: query, abortSignal}) => {
       // Until we have a better alternative we debounce by awaiting for a short delay.
       await wait(SEARCH_DELAY, abortSignal);
 

adev/src/content/guide/signals/resource.md

@@ -14,52 +14,52 @@ import {resource, Signal} from '@angular/core';
 const userId: Signal<string> = getUserId();
 
 const userResource = resource({
-  // Define a reactive request computation.
-  // The request value recomputes whenever any read signals change.
-  request: () => ({id: userId()}),
+  // Define a reactive computation.
+  // The params value recomputes whenever any read signals change.
+  params: () => ({id: userId()}),
 
   // Define an async loader that retrieves data.
-  // The resource calls this function every time the `request` value changes.
-  loader: ({request}) => fetchUser(request),
+  // The resource calls this function every time the `params` value changes.
+  loader: ({params}) => fetchUser(params),
 });
 
 // Create a computed signal based on the result of the resource's loader function.
 const firstName = computed(() => userResource.value().firstName);
 ```
 
-The `resource` function accepts a `ResourceOptions` object with two main properties: `request` and `loader`.
+The `resource` function accepts a `ResourceOptions` object with two main properties: `params` and `loader`.
 
-The `request` property defines a reactive computation that produce a request value. Whenever signals read in this computation change, the resource produces a new request value, similar to `computed`.
+The `params` property defines a reactive computation that produces a parameter value. Whenever signals read in this computation change, the resource produces a new parameter value, similar to `computed`.
 
-The `loader` property defines a `ResourceLoader`— an async function that retrieves some state. The resource calls the loader every time the `request` computation produces a new value, passing that value to the loader. See [Resource loaders](#resource-loaders) below for more details.
+The `loader` property defines a `ResourceLoader`— an async function that retrieves some state. The resource calls the loader every time the `params` computation produces a new value, passing that value to the loader. See [Resource loaders](#resource-loaders) below for more details.
 
 `Resource` has a `value` signal that contains the results of the loader.
 
 ## Resource loaders
 
 When creating a resource, you specify a `ResourceLoader`. This loader is an async function that accepts a single parameter— a `ResourceLoaderParams` object— and returns a value.
 
-The `ResourceLoaderParams` object contains three properties: `request`, `previous`, and `abortSignal`.
+The `ResourceLoaderParams` object contains three properties: `params`, `previous`, and `abortSignal`.
 
 | Property      | Description                                                                                                                                      |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`     | The value of the resource's `request` computation.                                                                                               |
+| `params`      | The value of the resource's `params` computation.                                                                                                |
 | `previous`    | An object with a `status` property, containing the previous `ResourceStatus`.                                                                    |
 | `abortSignal` | An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). See [Aborting requests](#aborting-requests) below for details. |
 
-If the `request` computation returns `undefined`, the loader function does not run and the resource status becomes `'idle'`.
+If the `params` computation returns `undefined`, the loader function does not run and the resource status becomes `'idle'`.
 
 ### Aborting requests
 
-A resource aborts an outstanding request if the `request` computation changes while the resource is loading.
+A resource aborts an outstanding loading operation if the `params` computation changes while the resource is loading.
 
 You can use the `abortSignal` in `ResourceLoaderParams` to respond to aborted requests. For example, the native `fetch` function accepts an `AbortSignal`:
 
 ```typescript
 const userId: Signal<string> = getUserId();
 
 const userResource = resource({
-  request: () => ({id: userId()}),
+  params: () => ({id: userId()}),
   loader: ({request, abortSignal}): Promise<User> => {
     // fetch cancels any outstanding HTTP requests when the given `AbortSignal`
     // indicates that the request has been aborted.
@@ -78,8 +78,8 @@ You can programmatically trigger a resource's `loader` by calling the `reload` m
 const userId: Signal<string> = getUserId();
 
 const userResource = resource({
-  request: () => ({id: userId()}),
-  loader: ({request}) => fetchUser(request),
+  params: () => ({id: userId()}),
+  loader: ({params}) => fetchUser(params),
 });
 
 // ...

goldens/public-api/core/index.api.md

@@ -179,7 +179,7 @@ export interface BaseResourceOptions<T, R> {
     defaultValue?: NoInfer<T>;
     equal?: ValueEqualityFn<T>;
     injector?: Injector;
-    request?: () => R;
+    params?: () => R;
 }
 
 // @public
@@ -1620,11 +1620,11 @@ export interface ResourceLoaderParams<R> {
     // (undocumented)
     abortSignal: AbortSignal;
     // (undocumented)
+    params: NoInfer<Exclude<R, undefined>>;
+    // (undocumented)
     previous: {
         status: ResourceStatus;
     };
-    // (undocumented)
-    request: Exclude<NoInfer<R>, undefined>;
 }
 
 // @public (undocumented)

packages/common/http/src/resource.ts

@@ -315,7 +315,7 @@ class HttpResourceImpl<T>
   ) {
     super(
       request,
-      ({request, abortSignal}) => {
+      ({params: request, abortSignal}) => {
         let sub: Subscription;
 
         // Track the abort listener so it can be removed if the Observable completes (as a memory

packages/core/rxjs-interop/test/rx_resource_spec.ts

@@ -30,8 +30,8 @@ describe('rxResource()', () => {
     let unsub = false;
     let lastSeenRequest: number = 0;
     rxResource({
-      request,
-      loader: ({request}) => {
+      params: request,
+      loader: ({params: request}) => {
         lastSeenRequest = request;
         return new Observable((sub) => {
           if (request === 2) {

packages/core/src/resource/api.ts

@@ -128,7 +128,7 @@ export interface ResourceRef<T> extends WritableResource<T> {
  * @experimental
  */
 export interface ResourceLoaderParams<R> {
-  request: Exclude<NoInfer<R>, undefined>;
+  params: NoInfer<Exclude<R, undefined>>;
   abortSignal: AbortSignal;
   previous: {
     status: ResourceStatus;
@@ -163,7 +163,7 @@ export interface BaseResourceOptions<T, R> {
    *
    * If a request function isn't provided, the loader won't rerun unless the resource is reloaded.
    */
-  request?: () => R;
+  params?: () => R;
 
   /**
    * The value which will be returned from the resource when a server value is unavailable, such as

packages/core/src/resource/resource.ts

@@ -20,6 +20,7 @@ import {
   ResourceStreamingLoader,
   StreamingResourceOptions,
   ResourceStreamItem,
+  ResourceLoaderParams,
 } from './api';
 
 import {ValueEqualityFn} from '../../primitives/signals';
@@ -58,9 +59,12 @@ export function resource<T, R>(
 export function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined>;
 export function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined> {
   options?.injector || assertInInjectionContext(resource);
-  const request = (options.request ?? (() => null)) as () => R;
+  const oldNameForParams = (
+    options as ResourceOptions<T, R> & {request: ResourceOptions<T, R>['params']}
+  ).request;
+  const params = (options.params ?? oldNameForParams ?? (() => null)) as () => R;
   return new ResourceImpl<T | undefined, R>(
-    request,
+    params,
     getLoader(options),
     options.defaultValue,
     options.equal ? wrapEqualityFn(options.equal) : undefined,
@@ -308,12 +312,14 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
       // which side of the `await` they are.
       const stream = await untracked(() => {
         return this.loaderFn({
+          params: extRequest.request as Exclude<R, undefined>,
+          // TODO(alxhub): cleanup after g3 removal of `request` alias.
           request: extRequest.request as Exclude<R, undefined>,
           abortSignal,
           previous: {
             status: previousStatus,
           },
-        });
+        } as ResourceLoaderParams<R>);
       });
 
       // If this request has been aborted, or the current request no longer