Algolia を TypeScript プロジェクトに導入する際、検索結果の hits プロパティへのアクセスで型エラーが発生することがあります。本記事では、このような問題への対処法と、型安全な実装パターンについて解説します。

発生した型エラー

Algolia の JavaScript/TypeScript SDK（algoliasearch）を使用して検索を実装する際、以下のようなコードで型エラーが発生することがありました。

const response = await client.search(queries);
const hits = response.results.flatMap(result => result.hits); // 型エラー！

Algolia SDK で client.search や index.search を使用した場合、返却値の型はSearchResponse や SearchResult を期待しがちです。しかしこのメソッドは、複数インデックスに対して検索を行うケースなどを想定した Union 型が定義されています。

type SearchResponseType = SearchResponse | SearchForFacetValuesResponse;

そのため、TypeScriptから見ると results 配列の各要素に必ず hits プロパティが存在することを保証できなくなります。実際の動作では hits が返ることが多いものの、型定義上は必須プロパティとして扱われていないため、型エラーが発生します。

Type Guardで型エラーを解決する

この問題を解決するシンプルな方法は、いわゆる Type Guardです。以下のような実装により、型安全性を保ちながら hits プロパティにアクセスできます。

const response = await client.search(queries);
const allHits = response.results.flatMap(result => {
  if ('hits' in result) {
    return result.hits;
  }
  return [];
});

'hits' in result という型ガードを使用することで、TypeScript コンパイラに「このブロック内では result に hits プロパティが存在する」ことを明示的に伝えています。これにより、型エラーを回避しながら安全にプロパティにアクセスできるようになります。

まとめ

複数インデックス検索をあまり使用することがないため、この型エラーがなぜ発生したかを特定することに少し時間がかかりました。ですが、背景さえ理解すれば、Union型をどう処理するかという実装の問題に変わリマス。

慌てで as anyを設定したりせず、なぜその型推論になるかを生成 AI なども活用しながら調査を進めましょう。

参考資料

Algolia Search API ドキュメント

algoliasearch-client-javascript GitHub

TypeScript Handbook – Type Guards

Tag: 型エラー

Algolia で search を TypeScript 実装する際の Tips