メインコンテンツにスキップ

API スライス: ユーティリティ

API スライスオブジェクトには、楽観的更新の実装や、サーバーサイドレンダリングの実装など、キャッシュ管理に使用できるさまざまなユーティリティが含まれています。

これらは、API オブジェクト内に api.util として含まれています。

情報

このページの一部の TS タイプは、実際の内部タイプはかなり複雑であるため、意図を説明するための擬似コードです。

updateQueryData​

シグネチャ​

const updateQueryData = (
  endpointName: string,
  args: any,
  updateRecipe: (draft: Draft<CachedState>) => void,
  updateProvided?: boolean,
) => ThunkAction<PatchCollection, PartialState, any, AnyAction>

interface PatchCollection {
  patches: Patch[]
  inversePatches: Patch[]
  undo: () => void
}
  • パラメータ
    • endpointName: 既存のエンドポイント名と一致する文字列
    • args: 更新する必要があるキャッシュされたデータセットを決定するために使用される、以前のクエリ呼び出しで使用されたものと一致する引数
    • updateRecipe: キャッシュされた状態に変更を適用できる Immer produce コールバック
    • updateProvided: エンドポイントの提供されたタグを更新されたキャッシュに基づいて再計算する必要があるかどうかを示すブール値。デフォルトは false です。

説明​

ディスパッチされると、JSON diff/patch オブジェクトのセットを作成して現在の状態に適用する Redux thunk アクションクリエーター。これは、Redux の状態をこれらの変更で即座に更新します。

thunk アクションクリエーターは、3 つの引数を受け入れます。更新しているエンドポイントの名前 ('getPost' など)、関連するクエリ引数、コールバック関数です。コールバックは、現在の状態の Immer でラップされた draft を受け取り、ミューテーションが正常に完了した後の予期される結果と一致するようにドラフトを変更できます。

thunk は {patches: Patch[], inversePatches: Patch[], undo: () => void} を含むオブジェクトを返します。 patches と inversePatches は、Immer の produceWithPatches メソッド を使用して生成されます。

これは通常、楽観的更新を実装する最初のステップとして使用されます。生成された inversePatches は、dispatch(patchQueryData(endpointName, args, inversePatches)) を呼び出すことで更新を元に戻すために使用できます。または、undo メソッドを直接呼び出して同じ効果を得ることができます。

最初の 2 つの引数 (endpointName と args) は、どの既存のキャッシュエントリを更新するかを決定するために使用されることに注意してください。既存のキャッシュエントリが見つからない場合、updateRecipe コールバックは実行されません。

例 1​

const patchCollection = dispatch(
  api.util.updateQueryData('getPosts', undefined, (draftPosts) => {
    draftPosts.push({ id: 1, name: 'Teddy' })
  }),
)

上記の例では、endpointName に 'getPosts' が提供され、args に undefined が提供されています。これは、'getPosts(undefined)' のクエリキャッシュキーと一致します。

つまり、次のいずれかの呼び出しによって作成された可能性のあるキャッシュエントリと一致します

api.endpoints.getPosts.useQuery()

useGetPostsQuery()

useGetPostsQuery(undefined, { ...options })

dispatch(api.endpoints.getPosts.initiate())

dispatch(api.endpoints.getPosts.initiate(undefined, { ...options }))

例 2​

const patchCollection = dispatch(
  api.util.updateQueryData('getPostById', 1, (draftPost) => {
    draftPost.name = 'Lilly'
  }),
)

上記の例では、endpointName に 'getPostById' が提供され、args に 1 が提供されています。これは、'getPostById(1)' のクエリキャッシュキーと一致します。

つまり、次のいずれかの呼び出しによって作成された可能性のあるキャッシュエントリと一致します

api.endpoints.getPostById.useQuery(1)

useGetPostByIdQuery(1)

useGetPostByIdQuery(1, { ...options })

dispatch(api.endpoints.getPostById.initiate(1))

dispatch(api.endpoints.getPostById.initiate(1, { ...options }))

upsertQueryData​

シグネチャ​

const upsertQueryData = <T>(endpointName: string, args: any, newEntryData: T) =>
  ThunkAction<Promise<CacheEntry<T>>, PartialState, any, UnknownAction>
  • パラメータ
    • endpointName: 既存のエンドポイント名と一致する文字列
    • args: 更新する必要があるキャッシュされたデータセットを決定するために使用される、以前のクエリ呼び出しで使用されたものと一致する引数
    • newEntryValue: 対応するキャッシュエントリの data フィールドに書き込まれる値

説明​

ディスパッチされると、キャッシュに値を更新するための擬似 API リクエストとして機能する Redux thunk アクションクリエーター。

thunk アクションクリエーターは、3 つの引数を受け入れます。更新しているエンドポイントの名前 ('getPost' など)、目的のキャッシュキーを構築するための適切なクエリ引数値、および更新するデータです。

そのキャッシュキーのキャッシュエントリが存在しない場合、キャッシュエントリが作成され、データが追加されます。キャッシュエントリが既に存在する場合、これは既存のキャッシュエントリデータを_上書き_します。

thunk は_非同期_に実行され、ストアが更新されたときに解決される promise を返します。

実際のリクエストが進行中にディスパッチされた場合、更新とリクエストの両方が解決されるとすぐに処理され、「最後の結果が優先される」更新動作になります。

例​

await dispatch(
  api.util.upsertQueryData('getPost', { id: 1 }, { id: 1, text: 'Hello!' }),
)

patchQueryData​

シグネチャ​

const patchQueryData = (
  endpointName: string,
  args: any
  patches: Patch[],
  updateProvided?: boolean
) => ThunkAction<void, PartialState, any, UnknownAction>;
  • パラメータ
    • endpointName: 既存のエンドポイント名と一致する文字列
    • args: 更新する必要があるキャッシュされたデータセットを決定するために使用されるキャッシュキー
    • patches: キャッシュされた状態に適用するパッチ (または逆パッチ) の配列。これらは通常、updateQueryData のディスパッチ結果から取得されます
    • updateProvided: エンドポイントの提供されたタグを更新されたキャッシュに基づいて再計算する必要があるかどうかを示すブール値。デフォルトは false です。

説明​

ディスパッチされると、JSON diff/patch 配列を指定されたクエリ結果のキャッシュデータに適用する Redux thunk アクションクリエーター。これは、Redux の状態をこれらの変更で即座に更新します。

thunk アクションクリエーターは、3 つの引数を受け入れます。更新しているエンドポイントの名前 ('getPost' など)、目的のキャッシュキーを構築するための適切なクエリ引数値、および Immer の produceWithPatches によって生成された JSON diff/patch 配列です。

これは通常、楽観的更新を実装する 2 番目のステップとして使用されます。リクエストが失敗した場合、楽観的に適用された変更は、updateQueryData によって以前に生成された inversePatches で patchQueryData をディスパッチすることによって元に戻すことができます。

単に以前の変更を元に戻したい場合は、代わりに updateQueryData のディスパッチから返された undo メソッドを呼び出す方が望ましい場合があります。

例​

const patchCollection = dispatch(
  api.util.updateQueryData('getPosts', undefined, (draftPosts) => {
    draftPosts.push({ id: 1, name: 'Teddy' })
  }),
)

// later
dispatch(
  api.util.patchQueryData(
    'getPosts',
    undefined,
    patchCollection.inversePatches,
  ),
)

// or
patchCollection.undo()

prefetch​

シグネチャ​

type PrefetchOptions = { ifOlderThan?: false | number } | { force?: boolean }

const prefetch = (endpointName: string, arg: any, options: PrefetchOptions) =>
  ThunkAction<void, any, any, UnknownAction>

  • パラメータ

    • endpointName: 既存のエンドポイント名と一致する文字列
    • args: 更新する必要があるキャッシュされたデータセットを決定するために使用されるキャッシュキー
    • options: 特定の状況でリクエストを送信する必要があるかどうかを決定するオプション
      • ifOlderThan: 指定されている場合、new Date() と最後の fulfilledTimeStamp の差が指定された値 (秒単位) より大きい場合にのみクエリを実行します
      • force: true の場合、ifOlderThan 値が設定されていても無視され、キャッシュに存在する場合でもクエリが実行されます。

説明​

データのプリフェッチを手動でトリガーするために使用できる Redux thunk アクションクリエーター。

thunk アクションクリエーターは、3 つの引数を受け入れます。更新しているエンドポイントの名前 ('getPost' など)、関連するクエリ引数、およびキャッシュの鮮度に基づいてデータを実際に再フェッチする必要があるかどうかを決定するために使用されるオプションのセットです.

React Hooks ユーザーは、usePrefetch フックがフックによって提供されるプリフェッチ関数を呼び出すと必要に応じて内部的に thunk アクションクリエーターの結果をディスパッチするため、これを直接使用する必要はほとんどありません。

例​

dispatch(api.util.prefetch('getPosts', undefined, { force: true }))

selectInvalidatedBy​

シグネチャ​

function selectInvalidatedBy(
  state: RootState,
  tags: ReadonlyArray<TagDescription<string>>,
): Array<{
  endpointName: string
  originalArgs: any
  queryCacheKey: QueryCacheKey
}>
  • パラメータ
    • state: ルート状態
    • tags: 無効化されたタグの読み取り専用配列。ここで、提供された TagDescription は、API の tagTypes プロパティに提供された文字列の 1 つです。例:
      • [TagType]
      • [{ type: TagType }]
      • [{ type: TagType, id: number | string }]

説明​

無効化するクエリパラメータを選択できる関数です.

関数は 2 つの引数を受け取ります

  • ルート状態と
  • 無効化するキャッシュタグ。

次のものを含む配列を返します

  • エンドポイント名、
  • 元の引数と
  • queryCacheKey。

例​

const entries = api.util.selectInvalidatedBy(state, ['Post'])
const entries = api.util.selectInvalidatedBy(state, [{ type: 'Post', id: 1 }])
const entries = api.util.selectInvalidatedBy(state, [
  { type: 'Post', id: 1 },
  { type: 'Post', id: 4 },
])

`invalidateTags`​

シグネチャ​

const invalidateTags = (
  tags: Array<TagTypes | FullTagDescription<TagTypes>>,
) => ({
  type: string,
  payload: tags,
})
  • パラメータ
    • `tags`: 無効化するタグの配列。ここで、提供された `TagType` は、API の `tagTypes` プロパティに提供された文字列の 1 つです。例:
      • [TagType]
      • [{ type: TagType }]
      • [{ type: TagType, id: number | string }]

説明​

自動再フェッチのためにキャッシュタグを手動で無効化するために使用できる Redux アクションクリエーター。

アクションクリエーターは 1 つの引数を受け入れます。無効化するキャッシュタグです。これらのタグをペイロードとして、API の対応する `invalidateTags` アクションタイプを持つアクションを返します。

このアクションクリエーターの結果をディスパッチすると、指定されたタグが無効化され、提供するキャッシュデータにサブスクライブされている場合、クエリが自動的に再フェッチされます。対応するタグ。

例​

dispatch(api.util.invalidateTags(['Post']))
dispatch(api.util.invalidateTags([{ type: 'Post', id: 1 }]))
dispatch(
  api.util.invalidateTags([
    { type: 'Post', id: 1 },
    { type: 'Post', id: 'LIST' },
  ]),
)

`selectCachedArgsForQuery`​

シグネチャ​

function selectCachedArgsForQuery(
  state: RootState,
  queryName: QueryName,
): Array<QueryArg>
  • パラメータ
    • state: ルート状態
    • `queryName`: 既存のクエリエンドポイント名と一致する文字列

説明​

現在キャッシュされているクエリに対する引数を選択できる関数です。

関数は 2 つの引数を受け取ります

  • ルート状態と

  • クエリの名称

各エントリで使用されている引数を含む配列を返します。

例​

const args = api.util.selectCachedArgsForQuery(state, 'getPosts')

resetApiState​

シグネチャ​

const resetApiState = () => ({
  type: string,
  payload: undefined,
})

説明​

APIの状態を完全に手動でリセットするためにディスパッチできるReduxアクションクリエーターです。これにより、既存のすべてのキャッシュエントリがすぐに削除され、すべてのクエリは「初期化されていない」と見なされます。

フックもローカルコンポーネントの状態を追跡するため、resetApiStateによって完全にリセットされない場合があることに注意してください。

例​

dispatch(api.util.resetApiState())

getRunningQueriesThunk と getRunningMutationsThunk​

シグネチャ​

getRunningQueriesThunk(): ThunkWithReturnValue<Array<QueryActionCreatorResult<any>>>
getRunningMutationsThunk(): ThunkWithReturnValue<Array<MutationActionCreatorResult<any>>>

説明​

（ディスパッチされた場合）実行中のすべてのクエリまたはミューテーションを返すThunkです。これらの戻り値は、Promiseのように待機できます。

これは、フック呼び出しやinitiateアクションの手動ディスパッチなど、あらゆる方法でトリガーされたすべてのクエリ（またはミューテーション）を待機するSSRシナリオに役立ちます。

現在実行中のすべてのクエリを待機する例
await Promise.all(dispatch(api.util.getRunningQueriesThunk()))

getRunningQueryThunk と getRunningMutationThunk​

シグネチャ​

getRunningQueryThunk<EndpointName extends QueryKeys<Definitions>>(
  endpointName: EndpointName,
  args: QueryArgFrom<Definitions[EndpointName]>
): ThunkWithReturnValue<
  | QueryActionCreatorResult<
      Definitions[EndpointName] & { type: 'query' }
    >
  | undefined
>

getRunningMutationThunk<EndpointName extends MutationKeys<Definitions>>(
  endpointName: EndpointName,
  fixedCacheKeyOrRequestId: string
): ThunkWithReturnValue<
  | MutationActionCreatorResult<
      Definitions[EndpointName] & { type: 'mutation' }
    >
  | undefined
>

説明​

（ディスパッチされた場合）指定されたエンドポイント名と引数（またはrequestId/fixedCacheKey）の組み合わせに対して、現在実行中の単一の実行クエリ（またはミューテーション）を返します。現在実行されていない場合、関数はundefinedを返します。

これらのThunkは、主に将来のサスペンスの実験的なサポートを追加するために追加されました。RTK Queryが特定のエンドポイント/引数の組み合わせに対して既に実行中のクエリ/ミューテーションを持っているかどうかを検索し、それを取得してPromiseとしてthrowするカスタムフックの作成を可能にします。

最終更新日