`httpResource`について

httpResourceは、AngularのHttpClientを内部で用いて動作するAPIである。Angular標準のHTTPスタックを利用するため、インターセプターなどの既存の仕組みやテスト手法をそのまま活用できる。
たとえば、以下のようにhttpResourceを定義し、currentUserIdというSignalを用いてリクエストURLを動的に変更できる。

currentUserId = getCurrentUserId(); // currentUserIdはSignal
// Signalを含むリアクティブな関数を引数に取っている
user = httpResource(() => `/api/user/${currentUserId()}`);

デフォルトでは、httpResourceはGETリクエストを行い、JSONとしてレスポンスをパースして返す。通常のHttpClientと異なるのは、購読（subscribe）を待たずにリクエストが即時に発行される点だ。ソースとなるSignalの値が変化すれば、自動的に新たなHTTPリクエストが送られる。
また、次のようにリクエストオブジェクトを用いて詳細な設定を加えることも可能である。

user = httpResource(() => ({
  url: `/api/user/${currentUserId()}`,
  method: 'GET',
  headers: {
    'X-Special': 'true',
  },
  params: {
    'fast': 'yes',
  },
  reportProgress: true,
  withCredentials: true,
  transferCache: true,
}));

httpResourceは基本的に非同期データの取得を目的として設計されており、サーバーへのデータ更新のような用途には推奨されない。フォーム送信などを行いたい場合は、これまで通りHttpClientのメソッドを使うべきだ。

また、以下のように返却されるデータ型をJSON以外にすることも可能であり、専用のメソッドが用意されている。

httpResource.text(() => ({ … }));       // value()でテキストを返す
httpResource.blob(() => ({ … }));       // value()でBlobを返す
httpResource.arrayBuffer(() => ({ … })); // value()でArrayBufferを返す

`httpResource`の構造

httpResourceが返すオブジェクトは、次のようなSignalを持っている。

value() — HTTPリクエストの結果（成功時）を保持する。プログラム的に上書きも可能
status() — リソースの状態（idle、loading、errorなど）を表す
error() — リクエストエラーやパースエラーなどを保持する
isLoading() — リクエストが進行中かどうかを示す真偽値

さらに、レスポンスに関する追加情報を得るためのSignalとして、以下が用意されている。

headers() — レスポンスヘッダー
statusCode() — HTTPステータスコード
progress() — リクエストの進捗状況（リクエストオブジェクトで指定されている場合）

HttpClientの場合、レスポンスヘッダーやステータスコードを取得するには明示的な指定が必要だが、httpResourceではこれらの値を専用のSignalで取得できるため、コードの見通しが良くなる。

型安全性の追求

HTTPリクエストのレスポンスが期待する型かどうかを検証する「スキーマバリデーション」は、ZodやValibotなどがよく利用されている。httpResourceはこれらのライブラリと直接連携できる仕組みを備えており、parseパラメータにバリデーション関数を指定すると、その戻り値の型を自動的に推論してくれる。

次の例では、外部のAPI（StarWars API）を呼び出してレスポンスをZodでパースしている。パース結果の型がhttpResourceの型として反映されるため、型安全性が保たれる。

export class AppComponent {
  id = signal(1);
  swPersonResource = httpResource(
    () => `https://swapi.dev/api/people/${this.id()}`,
    { parse: starWarsPersonSchema.parse }
  );
}

const starWarsPersonSchema = z.object({
  name: z.string(),
  height: z.number({ coerce: true }),
  edited: z.string().datetime(),
  films: z.array(z.string()),
});

実験的APIについて

httpResourceはAngular v19.2リリースに含まれる実験的機能であり、まだ本番環境での使用は推奨されない。将来的にAPIの仕様が変わる可能性があるが、開発チームは幅広いフィードバックを求めているため、興味がある開発者は積極的に試してみるとよい。詳細については、GitHub上のRFCにも情報が公開されている。

詳細はSeamless data fetching with httpResourceを参照していただきたい。

httpResourceについて

httpResourceの構造

型安全性の追求

実験的APIについて

`httpResource`について

`httpResource`の構造