非同期リアクティビティとリソース

すべてのシグナルAPIは同期的です（signal、computed、inputなど）。しかし、アプリケーションは多くの場合、非同期的に利用可能なデータを処理する必要があります。Resourceを使用すると、非同期データをアプリケーションのシグナルベースのコードに組み込み、そのデータに同期的にアクセスできるようになります。

Resourceを使用してあらゆる種類の非同期処理を実行できますが、Resourceの最も一般的なユースケースはサーバーからデータを取得することです。以下は、ユーザーデータを取得するためのリソースを作成する例です。

Resourceを作成する最も簡単な方法は、resource関数を使用することです。

import {computed, resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // 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 `params` value changes.
  loader: ({params}) => fetchUser(params),
});

// Create a computed signal based on the result of the resource's loader function.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` serves 2 purposes:
    // - It acts as type guard to strip `undefined` from the type
    // - It protects against reading a throwing `value` when the resource is in error state
    return userResource.value().firstName;
  }

  // fallback in case the resource value is `undefined` or if the resource is in error state
  return undefined;
});

resource関数は、2つの主なプロパティであるparamsとloaderを持つResourceOptionsオブジェクトを受け入れます。

paramsプロパティは、パラメータ値を生成するリアクティブな計算を定義します。この計算で読み取られるシグナルが変更されるたびに、リソースは新しいパラメータ値を生成します。これはcomputedと同様です。

loaderプロパティはResourceLoaderを定義します。これは、状態を取得する非同期関数です。リソースは、params計算が新しい値を生成するたびにローダーを呼び出し、その値をローダーに渡します。詳細は下記のResourceローダーを参照してください。

Resourceには、ローダーの結果を含むvalueシグナルがあります。

リソースローダー

リソースを作成する際には、ResourceLoaderを指定します。このローダーは、単一のパラメーター（ResourceLoaderParamsオブジェクト）を受け入れ、値を返す非同期関数です。

ResourceLoaderParamsオブジェクトには、params、previous、abortSignalの3つのプロパティが含まれています。

paramsの計算がundefinedを返す場合、ローダー関数は実行されず、リソースの状態はIdleになります。

Streaming resources

Some asynchronous data sources produce multiple values over time instead of returning a single result. Examples include WebSockets, Server-Sent Events (SSE), and Firestore onSnapshot listeners.

Use stream for these continuously updating data sources. Unlike loader, which resolves once for each request, stream returns a signal whose value can continue to update as new data becomes available.

Use loader for one-time asynchronous operations, such as fetching data from an HTTP endpoint.

const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// Later, when new data arrives:
userUpdates.set({value: 'Bob'});

リクエストの中断

リソースが読み込み中の場合にparams計算が変更されると、リソースは未処理の読み込み処理を中断します。

ResourceLoaderParams内のabortSignalを使用して、中断されたリクエストに応答できます。例えば、ネイティブのfetch関数はAbortSignalを受け入れます。

const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // 与えられた`AbortSignal`がリクエストの中断を示している場合、
    // fetchは未処理のHTTPリクエストをキャンセルします。
    return fetch(`users/${params.id}`, {signal: abortSignal});
  },
});

AbortSignalによるリクエストのキャンセルについては、AbortSignal on MDNを参照してください。

再読み込み

reloadメソッドを呼び出すことで、プログラム的にリソースのloaderをトリガーできます。

const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();

リソースの状態

リソースオブジェクトには、非同期ローダーの状態を読み取るためのいくつかのシグナルプロパティがあります。

status シグナルは、文字列定数を使用してリソースの状態を説明する特定の ResourceStatus を提供します。

この状態情報を使用して、ローディングインジケーターやエラーメッセージなどのユーザーインターフェース要素を条件付きで表示できます。

Caching resource data with SSR

When an application renders on the server, a resource loader runs once to produce the initial HTML. During hydration, the browser normally runs the same loader again.

To reuse the server result, provide an id for the resource. Angular stores the resolved value in TransferState on the server and uses it on the client to initialize the resource in a 'resolved' state.

const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});

The id value must be unique within your application and identical on the server and the client so that Angular can match the cached entry to the resource that requested it.

Chaining resources

Sometimes one resource depends on the result of another. You can express this dependency using the chain function available in the params context object.

import {resource} from '@angular/core';

const userResource = resource({
  params: () => ({id: getUserId()}),
  loader: ({params}) => fetchUser(params),
});

const companyResource = resource({
  params: ({chain}) => chain(userResource)?.companyId,
  loader: ({params: companyId}) => fetchCompany(companyId),
});

Here companyResource depends on the user's companyId, which is only known once userResource has loaded. chain(userResource) reads the value of userResource and automatically propagates its status to companyResource:

• If userResource is idle, companyResource also becomes idle.
• If userResource is loading or reloading, companyResource enters the loading state and its loader does not run. Note that during reloading, chain does not return the previously resolved value.
• If userResource is in an error state, companyResource also enters the error state.
• If userResource is resolved or local, chain returns its current value, which companyResource then uses as its params.

When chain propagates a status from userResource (idle, loading, reloading, or error), the params function does not continue. When userResource is resolved or local, chain returns its value, which can itself be undefined. The example handles this with chain(userResource)?.companyId, so an undefined value results in undefined params and companyResource becomes idle.

Chaining vs. reading resource values directly

You might be tempted to read a resource's value directly inside params:

const companyResource = resource({
  params: () => {
    const user = userResource.value(); // may be undefined
    return user ? {companyId: user.companyId} : undefined;
  },
  loader: ({params}) => fetchCompany(params.companyId),
});

While this works, returning undefined from params makes the resource go idle rather than reflecting the actual state of the upstream resource. Using chain is preferred because it correctly mirrors loading and error states.

Reach for chain only when the downstream resource performs its own async work that depends on the upstream value. If you only need to derive a value synchronously from a resource, use computed instead.

httpResource を使用したリアクティブデータ取得

httpResource は HttpClient のラッパーで、リクエストの状態とレスポンスをシグナルとして提供します。これはインターセプターを含むAngular HTTPスタックを通してHTTPリクエストを行います。

Resource composition with snapshots

A ResourceSnapshot is a structured representation of a resource's current state. Every resource has a snapshot property that provides a signal of its current state.

const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;

Each snapshot contains a status and either a value or an error.

Composing resources with snapshots

You can create new resources from snapshots using resourceFromSnapshots. This enables composition with signal APIs like computed and linkedSignal to transform resource behavior.

import {linkedSignal, resourceFromSnapshots, Resource, ResourceSnapshot} from '@angular/core';

function withPreviousValue<T>(input: Resource<T>): Resource<T> {
  const derived = linkedSignal<ResourceSnapshot<T>, ResourceSnapshot<T>>({
    source: input.snapshot,
    computation: (snap, previous) => {
      if (snap.status === 'loading' && previous && previous.value.status !== 'error') {
        // When the input resource enters loading state, we keep the value
        // from its previous state, if any.
        return {status: 'loading' as const, value: previous.value.value};
      }

      // Otherwise we simply forward the state of the input resource.
      return snap;
    },
  });

  return resourceFromSnapshots(derived);
}

@Component({
  /*... */
})
export class AwesomeProfile {
  userId = input.required<number>();
  user = withPreviousValue(httpResource(() => `/user/${this.userId()}`));
  // When userId changes, user.value() keeps the old user data until the new one loads
}