RTK Query Release Planning notes

[markerikson]

The maintainers (@phryneas , @msutkowski , and myself) are hoping to nail down plans within the next few days for finalizing and releasing the "RTK Query" APIs officially.

This will presumably involve migrating the source code for createApi over into the Redux Toolkit codebase itself, and moving the documentation from https://rtk-query-docs.netlify.app into the actual Redux Toolkit docs at https://redux-toolkit.js.org . This would be followed by releasing a new Redux Toolkit version with that functionality, likely a v1.6 release.

Key things for us to figure out:

• What final tweaks to the APIs and functionality are needed to consider this "done" and ready for initial stable release?
• How much of the Git development history from this repo do we want to preserve as we migrate it over into the RTK repo?
• How should the "RTK Query" docs content be structured inside of the RTK docs? Should there be some kind of an "RTK Query" category, just put this content under "Usage Guides", or something else?

[ajcwebdev]

In regards the last question, I think the level of separation from the rest of the docs will be dependent on how it is integrated into the larger RTK library.

• If dropping in rtk-query is as simple as importing a hook then it can just be one section among many within the docs.
• If it's going to be akin to installing a separate dependency then it will need to have a larger and more comprehensive section within the docs.

[markerikson]

At the moment, the rough plan is that the createApi function currently in this "RTK Query" package will be just another API exported from RTK directly, like configureStore and createSlice. So, the intent is that there's one single @reduxjs/toolkit package, and you get everything at once - it's just a question of which APIs you import and use in your app.

There will be a new "@reduxjs/toolkit/react" entry point of some kind, which will specifically have the functionality that handles generating React hooks from the API endpoint definitions. (I'm actually still not entirely sure how that logic is organized in this package right now.)

As far as docs organization, I assume there'll be two aspects:

• A createApi API reference page, in the same overall section as https://redux-toolkit.js.org/api/createSlice , but possibly nested under a different subcategory like "Data Fetching" instead of "Reducers and Actions"
• The pages from the current RTK Query "Concepts" section ( like https://rtk-query-docs.netlify.app/concepts/queries ) need to go somewhere in the RTK docs. So, what I was referring to in the original comment was that those pages either ought to get their own dedicated "RTK Query" top-level category in Docusaurus, or a subcategory under the "Using Redux Toolkit" category.

[ajcwebdev]

Makes sense, for the second point I'd lean toward putting it as its own category within "Using Redux Toolkit," instead of its own top-level category, as it'll be a decent sized chunk of docs but still comparable to the length of other content in that category. And it wouldn't make as much sense to have it separated because you would be recreating an API Reference section and a Using Redux Toolkit section within the new top level section.

[msutkowski]

From twitter:

Jakob Heuser @jakobo · 1m Tweet sized fast feedback:

• Less animated checks
• “invalidates: ['Posts']” isn’t hyped up enough. Cache invalidation is a PITA & having a “good enough” pattern is Hundred points symbol
• I’d prefer the feature list be in terms of benefits, as some of the terms like “lagged queries” are jargon

[msutkowski]

@gfortaine Just wanted to give you a quick ping as you've contributed quite a few things - if you have any additional feedback, please let us know! We have a few more features pending right now that we're aiming to roll out soon. If we're missing anything you've come across, let us know!

@kahirokunn Your input would also be valuable here, thanks!

[tobybaratta]

What final tweaks to the APIs and functionality are needed to consider this "done" and ready for initial stable release?

I can think of three things that would be useful, but I don't think absolutely necessary; in my experience, pagination is frequently done using a skip token rather than just incrementing the page number. I think overall just having another explicit example of changing a query based on the response of a previous query to the same endpoint. I could see pagination using a skip token as an example, or having the polling time set by the retry-after header.

I think overall documentation could be easier to have some more explicit walkthroughs - though perhaps some of that could be done through an updated example to use rtk-query for RTK core's examples.

How should the "RTK Query" docs content be structured inside of the RTK docs? Should there be some kind of an "RTK Query" category, just put this content under "Usage Guides", or something else?

I think it should be its own header, but can also see it being fine as a subheader under "Using Redux Toolkit" as mentioned above.

I feel like the rest of RTK can be seen as a more clean drop-in substitute for Redux for new projects, where rtk-query is more of an additional feature that RTK has that is wonderful integration, but not a default thing that people would think of (the way createSlice/Action/Reducer are). You could maybe make the argument that it should go alongside createAsyncThunk, but even then the use case is related but not really a drop-in.

I think with the amount of documentation and examples you have already on the rtk-query documentation site, it makes the most sense to keep it as a separate header.

[msutkowski]

Adding some notes from our call:

RTKQ

• Merge PRs/issues to be feature complete for 0.3.0
  • https://github.com/rtk-incubator/rtk-query/issues/176
  • https://github.com/rtk-incubator/rtk-query/issues/170
  • https://github.com/rtk-incubator/rtk-query/issues/139
  • Requires an example - consider Firebase or a google api that could be cached.
  • https://github.com/rtk-incubator/rtk-query/pull/177
• Review test coverage and docs, update where appropriate
• Release
• Update RTKQ repo to point to RTKQ
• 301 rtk-query-docs site -> RTK site/query (or wherever the new permalink is)

RTK

• Will need to have the RTKQ build infra applied to RTK
• Will need to have an examples folder added specifically for RTKQ examples.
  • All of the existing codesandboxes shown in RTKQ docs should be versioned in here and the docs should link to them. - Requires research on best path forward
• Will need a minor release to 1.6
  • Add .unwrap() from RTKQ to regular cAT

RTK Misc:

• Review listeners PR and consider packaging an implementation under @rtk-incubator

RTK Docs:

• Move RTKQ docs into RTK
• Restructure: Treat 'Query' as a subcategory under API reference
• Add info about entry points:
  • @reduxjs/toolkit/query/react
  • @reduxjs/toolkit/query
  • @reduxjs/toolkit/react
  • @reduxjs/toolkit
• Should show an updated example using Query
  • Include specific examples of extraReducers and matchers in a 'real-world' usage scenario
  • Note: an authSlice could be a great place for this

[phryneas]

adding from memory:

• deprecate ApiWithInjectedEndpoints type

[gfortaine]

@msutkowski It looks like that we don't have any additional comments on our side 😀 For your kind reference, we have successfully moved from a homemade fetcher to RTK query like a breeze in our production project. Now, we are eagerly waiting for the 0.3.0 to move forward 👍 Thank you for the great work guys 🎉 @phryneas @msutkowski

[phryneas]

So, another TODO would be a rename for:

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

[markerikson]

Also prefetchThunk -> prefetch

[phryneas]

see https://github.com/rtk-incubator/rtk-query/pull/213

[phryneas]

So, stuff that happened since the last release:

"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.invalidateTags (#190) @msutkowski
  • A utility that gives you the ability to invalidate Tags (previously Entities) in any place that you have access to dispatch. This could be useful for invalidating parts of the cache based on various actions that pass through middleware.
• Add utils.resetApiState (#189) @msutkowski
  • Allows you to hard reset the api state in any place that you have access to dispatch. In addition, this will clean up any existing polling intervals that run in the api middleware.
• Add useLazyQuery (#177) @msutkowski, @phryneas
  • An alternative to useQuery for the cases where you don't immediately want to make a request for data.
• Add selectFromResult for mutations ( #206 ) @msutkowski
  • A 'render optimized' selector for mutations that only rerenders when the selected fields change. The common use case would be to prevent the extra renders that are caused by subscribing to updates for isLoading or data when you do not care about the result. (ex: const [update] = useUpdateUser(1, { selectFromResult: () => ({}) }))

potentially breaking

• Add extra /react entrypoint @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 this changes the signature of providesTags and invalidatesTags from (result, arg) => Tags to (result?, error?, arg) => Tags, which allows to provide & invalidate tags even in erroring queries
• entity -> tag
• entityTypes -> tagTypes
• provides -> providesTags
• invalidates -> invalidatesTags
• prefetchThunk -> prefetch

tweaks & fixes

• Support FormData in fetchBaseQuery (#140) @msutkowski
• Clear undefined values from headers (#146) @kahirokunn
• Export FetchBaseQueryArgs (#145) @kahirokunn
• SSR Support: delete substate.error property (#152) @gfortaine instead of setting it to undefined, which does not stringify (important for Next.js getServerSideProps)
• TypeScript: Loosen dispatch types (#150) @kahirokunn
• fetchBaseQuery: Fix: JSON.stringify body when it isJsonifiable and content-type is 'application/json' (#168) @gfortaine will prevent stuff like FormData, ArrayBuffer, Blob etc from being wrongly serialized
• Reset promiseRef on useQuery/Mutation hooks on unmount (#173) @msutkowski this fixes fast refresh reinitialization
• useQuery: skip uninitialized status (#197) @phryneas useQuery hooks will now be isLoading on first render instead of isUninitialized (except for skipped queries), to simplify the logic the library users have to write
• Enforce an object return from selectFromResult (#216) @markerikson

And of course Docs docs docs by @Shrugsy, @markerikson but also quite a lot of smaller tweaks in master and next. I'm not gonna name all of them here now to avoid a mass ping though.

[markerikson]

The primary RTKQ migration work is now done, and I've just published https://github.com/reduxjs/redux-toolkit/releases/tag/v1.6.0-alpha.1 containing the RTKQ APIs as part of the RTK package!

This is basically rtkq@0.3, but moved over to be under @reduxjs/toolkit/query and @reduxjs/toolkit/query/react.

[phryneas]

I'm closing everything here now. If there's any need for further discussion, that should take place in a new issue over at https://github.com/reduxjs/redux-toolkit/