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

TypeScriptでAlgoliaの検索結果を扱う際に発生する型エラーの原因と、Type Guardを使った安全な実装方法について解説します。複数インデックス検索に対応した型定義の理解がカギです。

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 プロパティが存在する」ことを明示的に伝えています。これにより、型エラーを回避しながら安全にプロパティにアクセスできるようになります。