Skip to content
This repository has been archived by the owner on Jun 8, 2021. It is now read-only.

Beta 0.3

Latest
Latest
Compare
Choose a tag to compare
@markerikson markerikson released this 19 Apr 13:44
· 4 commits to main since this release
v0.3.0
1ae1538

This beta release of RTK Query adds new APIs for working with external service classes in endpoints, adds lazy queries, splits the React-specific functionality into a new /react entry point, renames the "entity" concept to "tags", and makes a variety of tweaks and fixes for fetching behavior and our TypeScript types.

This is the final planned pre-release for RTK Query as a standalone library. The APIs are effectively finalized at this point, and we're now ready to merge the RTK Query source code and documentation back into the main Redux Toolkit repo. The plan is to release RTK Query as a new pair of entry points ( /query and /query/react ) in the upcoming Redux Toolkit 1.6 package release. We'll lock this repo once we're ready to switch where issues should be filed.

The APIs are stable enough that you can consider using them in production. We may make a few final tweaks as we merge this back into RTK or get feedback based on this release, but most likely the only migration steps needed from this release to RTK 1.6 would be changing the import paths.

Changelog

New queryFn Option for Endpoints

The typical approach for making actual API requests is to use the fetchBaseQuery wrapper included in RTKQ. However, there are times you may want to use a custom function for making the request. This is especially true if you are working with some kind of external API client like a Google API or Firebase wrapper.

We now support supplying a queryFn option inside of an endpoint definition, in which case that specific endpoint will use the function you provided for fetching data.

If you want to enforce that all endpoints in a given API slice must supply a queryFn, you can set the API slice to use the fakeBaseQuery instance instead of fetchBaseQuery. This will throw an error if actually used to make a request, and also allows you to define a common TS error type for all the queryFn usages as a generic type arg:

const api = createApi({
  baseQuery: fakeBaseQuery<CustomErrorType>(),
  endpoints: (build) => ({
    withAsyncQueryFn: build.query<string, string>({
      async queryFn(arg: string) {
        return { data: `resultFrom(${arg})` };
      },
    }),
  })
});

Lazy Queries

We now have a useLazyQuery hook, which lets you delay actually fetching data until you call the trigger function supplied by the hook:

const [fetchThing, { data, isLoading, ...rest }] = api.endpoints.getPosts.useLazyQuery({
  refetchOnFocus, 
  refetchOnReconnect, 
  pollingInterval
});

<button onClick={() => fetchThing({ with: 'variable', another: 'one' })}>Do a fetch</button>

New Utility Functions

RTK Query typically manages invalidation of data and clearing out internal state, but there are times you may wish to trigger that functionality yourself. API slices now include an additional pair of thunk functions under the utils key, invalidateTags and resetApiState. You can manually dispatch those thunks yourself if needed.

selectFromResult for Mutations

The useMutation hook now accepts a selectFromResult option similar to useQuery. This allows a user to 'optimize renders' by only rerendering when the selected values change. There will always be 1 rerender when the mutation is called as it creates a new requestId. An example of optimizing this behavior might look like yourEndpoint.useMutation(undefined, { selectFromResult: () => ({}) }).

Breaking Changes

New React-Specific Entry Point

Redux Toolkit has always been UI-agnostic, and the majority of RTK Query is UI-agnostic as well. In order to keep that core UI-agnostic, we've moved the React-specific functionality into a new /react entry point. That entry point exports everything from the root entry point, but the React-specific version of createApi will also auto-generate React hooks for the endpoints.

If you are using RTK Query with React, you'll need to change your imports to:

import { createApi } from "@rtk-incubator/rtk-query/react";

Note that when we move RTK Query over into Redux Toolkit itself, we expect the final entry points to be:

import { createSlice} from "@reduxjs/toolkit";
import { createApi as genericCreateApi } from "@reduxjs/toolkit/query";
import { createApi as reactCreateApi } from "@reduxjs/toolkit/query/react";

We recognize that the entry point paths are a bit lengthy, but we expect that most applications will only need to have these imports in a handful of API slice definition files.

API and Type Renaming

We've gone through the API definitions and done a (hopefully final) round of renaming and cleanup. In particular, we've renamed the "entity" concept that is used for cache invalidation to "tags" instead, which also applies to several specific field names:

  • entity -> tag
  • entityTypes -> tagTypes
  • provides -> providesTags
  • invalidates -> invalidatesTags

We've also renamed the utils.prefetchThunk function in API slice objects to utils.prefetch for consistency, renamed the endpoint field in hook status objects to endpointName, and removed the internalQueryArgs field.

If you are using any of these fields and want some help renaming your code to match, we have an initial v2-v3 codemod available at https://github.com/rtk-incubator/rtk-query-codemods . We've also inserted some temporary dev-only warnings if you attempt to use any of the old field names like provides.

Tag Invalidation Signatures

The signature of providesTags and invalidatesTags has changed from (result, arg) => Tags to (result?, error?, arg) => Tags, which allows providing and invalidating tags even when a query has errored.

Other Improvements

fetchBaseQuery now supports FormData as a body, clears undefined headers, and has better handling for JSON content vs non-JSON Content like FormData or ArrayBuffer.

useQueryHooks now go straight to isLoading on the first render instead of isUninitialized to simplify loading state logic, unless the hook is being skipped as it starts.

We've fixed issues related to SSR and React Fast Refresh.

It was possible for selectFromResult to return a primitive like a number, but that breaks with how the query state results are merged together to form the hook return value. The TS types now enforce that selectFromResult must return an object, which will be shallow-merged into the hook result value.

Docs Improvements

We've restructured the docs to better document what is part of createApi, vs what is in the API slice objects generated by createApi. We've also done a bunch of cleanup and fleshing out of content.

Note that as of right now, not all of the new functionality in this release has been fully documented. We're working on filling out the missing docs content now, and will have a complete set of documentation when RTK 1.6 is ready.

Changes

New APIs

  • Add queryFn as alternative to query to endpoint definitions (#158) @phryneas
    enables use with external libraries that provide a service class, such as the spotify api, google apis, firebase or grpc services - as well as chaining multiple requests in one combined "endpoint"
    also adds fakeBaseQuery for apis without any baseQuery
  • Add utils.invalidateEntities (#190) @msutkowski
  • Add utils.resetApiState (#189) @msutkowski
  • Add useLazyQuery (#177) @msutkowski, @phryneas
  • Add selectFromResult for mutations ( #206 ) @msutkowski

Potentially Breaking

  • extra /react entrypoint (#141) @phryneas
  • [minor breaking] remove internalQueryArgs, pass endpointDefinition into serializeQueryArgs, rename endpoint to endpointName or endpointDefinition everywhere (#156)
  • Call providesTags/invalidatesTags when a query has an isError state (#201) @phryneas
  • last minute renames (#213) @phryneas

Tweaks and Fixes

v0.2.0...v0.3.0

Assets 2