Merge pull request reduxjs#1085 from reduxjs/docs/rtkq-overview

query-old/docs/introduction/comparison.md → docs/rtk-query/comparison.md

@@ -1,20 +1,55 @@
 ---
 id: comparison
-title: Comparison
-sidebar_label: Comparison
+title: Comparison with Other Tools
+sidebar_label: Comparison with Other Tools
 hide_title: true
-hide_table_of_contents: true
 ---
 
-# Comparison
+# Comparison with Other Tools
 
-RTK Query takes inspiration from many other data fetching libraries in the ecosystem. Much like [the Redux core library was inspired by tools like Flux and Elm](https://redux.js.org/understanding/history-and-design/prior-art), RTK Query builds on API design patterns and feature concepts popularized by libraries like React Query, SWR, Apollo, and Urql. RTK Query has been written from scratch, but tries to use the best concepts from those libraries and other data fetching tools, with an eye towards leveraging the unique strengths and capabilities of Redux.
+**RTK Query takes inspiration from many other data fetching libraries in the ecosystem**. Much like [the Redux core library was inspired by tools like Flux and Elm](https://redux.js.org/understanding/history-and-design/prior-art), RTK Query builds on API design patterns and feature concepts popularized by libraries like React Query, SWR, Apollo, and Urql. RTK Query has been written from scratch, but tries to use the best concepts from those libraries and other data fetching tools, with an eye towards leveraging the unique strengths and capabilities of Redux.
+
+We think that all of those tools are great! If you're using one of them, you're happy with it, and it solves the problems you are facing in your app, keep using that tool. The information on this page is meant to help show **where there are differences in features, implementation approaches, and API design**. The goal is to help you **make informed decisions and understand tradeoffs**, rather than argue that tool X is better than tool Y.
+
+## When Should You Use RTK Query?
+
+In general, the main reasons to use RTK Query are:
+
+- You already have a Redux app and you want to simplify your existing data fetching logic
+- You want to be able to use the Redux DevTools to see the history of changes to your state over time
+- You want to be able to integrate the RTK Query behavior with the rest of the Redux ecosystem
+- Your app logic needs to work outside of React
+
+### Unique Capabilities
+
+RTK Query has some unique API design aspects and capabilities that are worth considering.
+
+- With React Query and SWR, you usually define your hooks yourself, and you can do that all over the place and on the fly. With RTK Query, you do so in one central place by defining an "API slice" with multiple endpoints ahead of time. This allows for a more tightly integrated model of mutations automatically invalidating/refetching queries on trigger.
+- With the endpoint [matcher functionality](./api/created-api/endpoints#matchers): Every request is automatically is visible to your Redux reducers and can easily update the global application state if necessary ([see example](https://github.com/reduxjs/redux-toolkit/issues/958#issuecomment-809570419)).
+- You can easily invalidate entities or patch existing query data (via `util.updateQueryData`) from middleware.
+- RTK Query enables [streaming cache updates](./usage/streaming-updates.mdx), such as updating the initial fetched data as messages are received over a websocket, and has built in support for [optimistic updates](./usage/optimistic-updates.mdx) as well.
+- Like Redux itself, the main RTK Query functionality is UI-agnostic and can be used with any UI layer
+- RTK Query ships a very tiny and flexible fetch wrapper: [`fetchBaseQuery`](./api/fetchBaseQuery.mdx). It's also very easy to [swap our client with your own](./usage/customizing-queries.mdx), such as using `axios`, `redaxios`, or something custom.
+- RTK Query has [a (currently experimental) code-gen tool](https://github.com/rtk-incubator/rtk-query-codegen) that will take an OpenAPI spec and give you a typed API client, as well as provide methods for enhancing the generated client after the fact.
+
+## Tradeoffs
+
+### No Normalized or Deduplicated Cache
+
+RTK Query deliberately **does _not_ implement a cache that would deduplicate identical items across multiple requests**. There are several reasons for this:
+
+- A fully normalized shared-across-queries cache is a _hard_ problem to solve
+- We don't have the time, resources, or interest in trying to solve that right now
+- In many cases, simply refetching data when it's invalidated works well and is easier to understand
+- At a minimum, RTKQ can help solve the general use case of "fetch some data", which is a big pain point for a lot of people
+
+## Comparing Feature Sets
 
 It's worth comparing the feature sets of all these tools to get a sense of their similarities and differences.
 
 :::info
 
-This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be improved, feel free to suggest changes (with notes or evidence of claims) by [opening an issue](https://github.com/rtk-incubator/rtk-query/issues/new).
+This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be improved, feel free to suggest changes (with notes or evidence of claims) by [opening an issue](https://github.com/reduxjs/redux-toolkit/issues/new).
 
 :::
 
@@ -37,3 +72,9 @@ This comparison table strives to be as accurate and as unbiased as possible. If
 | **Optimistic updates**                 | can update cache by hand                | can update cache by hand | `optimisticResponse`                                                                | ?                                                                                                           |
 | **Manual cache manipulation**          | yes                                     | yes                      | yes                                                                                 | yes                                                                                                         |
 | **Platforms**                          | hooks for React, everywhere Redux works | hooks for React          | various                                                                             | various                                                                                                     |
+
+## Further Information
+
+- The [React Query "Comparison" page](https://react-query.tanstack.com/comparison) has an additional detailed feature set comparison table and discussion of capabilities
+- Urql maintainer Phil Pluckthun wrote [an excellent explanation of what a "normalized cache" is and how Urql's cache works](https://kitten.sh/graphql-normalized-caching)
+- The [RTK Query "Cached Data" page](./usage/cached-data.mdx#tradeoffs) has further details on why RTK Query does not implement a normalized cache

docs/rtk-query/overview.md

@@ -0,0 +1,60 @@
+---
+id: overview
+title: RTK Query Overview
+sidebar_label: RTK Query Overview
+hide_title: true
+---
+
+# RTK Query Overview
+
+**RTK Query** is a powerful data fetching and caching tool. It is designed to simplify common cases for loading data in a web application, **eliminating the need to hand-write data fetching & caching logic yourself**.
+
+RTK Query is **an optional addon included in the Redux Toolkit package**, and its functionality is built on top of the other APIs in Redux Toolkit.
+
+### Motivation
+
+Web applications normally need to fetch data from a server in order to display it. They also usually need to make updates to that data, send those updates to the server, and keep the cached data on the client in sync with the data on the server. This is made more complicated by the need to implement other behaviors used in today's applications:
+
+- Tracking loading state in order to show UI spinners
+- Avoiding duplicate requests for the same data
+- Optimistic updates to make the UI feel faster
+- Managing cache lifetimes as the user interacts with the UI
+
+The Redux core has always been very minimal - it's up to developers to write all the actual logic. That means that Redux has never included anything built in to help solve these use cases. The Redux docs have taught [some common patterns for dispatching actions around the request lifecycle to track loading state and request results](https://redux.js.org/tutorials/fundamentals/part-7-standard-patterns#async-request-status), and [Redux Toolkit's `createAsyncThunk` API](../api/createAsyncThunk.mdx) was designed to abstract that typical pattern. However, users still have to write significant amounts of reducer logic to manage the loading state and the cached data.
+
+Over the last couple years, the React community has come to realize that **"data fetching and caching" is really a different set of concerns than "state management"**. While you can use a state management library like Redux to cache data, the use cases are different enough that it's worth using tools that are purpose-built for the data fetching use case.
+
+RTK Query takes inspiration from other tools that have pioneered solutions for data fetching, like Apollo Client, React Query, Urql, and SWR, but adds a unique approach to its API design:
+
+- The data fetching and caching logic is built on top of Redux Toolkit's `createSlice` and `createAsyncThunk` APIs
+- Because Redux Toolkit is UI-agnostic, RTK Query's functionality can be used with any UI layer
+- API endpoints are defined ahead of time, including how to generate query parameters from arguments and transform responses for caching
+- RTK Query can also generate React hooks that encapsulate the entire data fetching process, provide `data` and `isFetching` fields to components, and manage the lifetime of cached data as components mount and unmount
+- Finally, RTK Query is completely written in TypeScript, and is designed to provide an excellent TS usage experience
+
+### What's included
+
+RTK Query is included within the installation of the core Redux Toolkit package. It is available via either of the two entry points below:
+
+```ts no-transpile
+import { createApi } from '@reduxjs/toolkit/query'
+
+/* React-specific entry point that automatically generates
+   hooks corresponding to the defined endpoints */
+import { createApi } from '@reduxjs/toolkit/query/react'
+```
+
+RTK Query includes these APIs:
+
+- [`createApi()`](./api/createApi.mdx): The core of RTK Query's functionality. It allows you to define a set of endpoints describe how to retrieve data from a series of endpoints, including configuration of how to fetch and transform that data.
+- [`fetchBaseQuery()`](./api/fetchBaseQuery.mdx): A small wrapper around [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) that aims to simply requests. Intended as the recommended `baseQuery` to be used in `createApi` for the majority of users.
+- [`<ApiProvider />`](./api/ApiProvider.mdx): Can be used as a `Provider` if you **do not already have a Redux store**.
+- [`setupListeners()`](./api/setupListeners.mdx): A utility used to enable `refetchOnMount` and `refetchOnReconnect` behaviors.
+
+## Further Information
+
+See the [RTK Query Quick Start tutorial](../tutorials/rtk-query.mdx/) for examples of how to add RTK Query to a project that uses Redux Toolkit, set up an "API slice" with endpoint definitions, and how to use the auto-generated React hooks in your components.
+
+The [RTK Query usage guide section](./usage/queries.mdx) has information on topics like [querying data](./usage/queries.mdx), [using mutations to send updates to the server](./usage/mutations.mdx), [streaming cache updates](./usage/streaming-updates.mdx), and much more.
+
+The [Examples page](./usage/examples.mdx) has runnable CodeSandboxes that demonstrate topics like [making queries with GraphQL](./usage/examples.mdx#react-with-graphql), [authentication](./usage/examples.mdx#authentication), and even [using RTK Query with other UI libraries like Svelte](./usage/examples.mdx#svelte).

docs/rtk-query/usage/cached-data.mdx

@@ -984,3 +984,35 @@ const api = createApi({
 ```
 
 An example of various abstractions for tag providing/invalidating designed for common rest data formats can be seen in the following gist, including typescript support, and factoring both ['LIST' style advanced tag invalidation](#advanced-invalidation-with-abstract-tag-ids) and ['error' style tag invalidation](#providing-errors-to-the-cache): **[RTK Query cache utils](https://gist.github.com/Shrugsy/6b6af02aef1f783df9d636526c1e05fa)**.
+
+## Tradeoffs
+
+### No Normalized or Deduplicated Cache
+
+RTK Query deliberately **does _not_ implement a cache that would deduplicate identical items across multiple requests**. There are several reasons for this:
+
+- A fully normalized shared-across-queries cache is a _hard_ problem to solve
+- We don't have the time, resources, or interest in trying to solve that right now
+- In many cases, simply refetching data when it's invalidated works well and is easier to understand
+- At a minimum, RTKQ can help solve the general use case of "fetch some data", which is a big pain point for a lot of people
+
+As an example, say that we have an API slice with `getTodos` and `getTodo` endpoints, and our components make the following queries:
+
+- `getTodos()`
+- `getTodos({filter: 'odd'})`
+- `getTodo({id: 1})`
+
+Each of these query results would include a Todo object that looks like `{id: 1}`.
+
+In a fully normalized deduplicating cache, only a single copy of this Todo object would be stored. However, RTK Query saves each query result independently in the cache. So, this would result in three separate copies of this Todo being cached in the Redux store. However, if all the endpoints are consistently providing the same tags (such as `{type: 'Todo', id: 1}`), then invalidating that tag will force all the matching endpoints to refetch their data for consistency.
+
+The Redux docs have always recommended [keeping data in a normalized lookup table](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape) to enable easily finding items by ID and updating them in the store, and [RTK's `createEntityAdapter`](../../api/createEntityAdapter.mdx) was designed to help manage normalized state. Those concepts are still valuable and don't go away. However, if you're using RTK Query to manage caching data, there's less need to manipulate the data that way yourself.
+
+There are a couple additional points that can help here:
+
+- The generated query hooks have [a `selectFromResult` option](../api/created-api/hooks.mdx) that allow components to read individual pieces of data from a query result. As an example, a `<TodoList>` component might call `useTodosQuery()`, and each individual `<TodoListItem>` could use the same query hook but select from the result to get the right todo object.
+- You can use the [`transformResponse` endpoint option](../api/createApi.mdx) to modify the fetched data so that it's stored in a different shape, such as using `createEntityAdapter` to normalize the data _for this one response_ before it's inserted into the cache.
+
+## Further information
+
+- [Reddit: discussion of why RTKQ doesn't have a normalized cache, and tradeoffs](https://www.reddit.com/r/reactjs/comments/my9vrq/redux_toolkit_v16_alpha1_rtk_query_apis/gvxi5t7/)

website/sidebars.json

@@ -30,6 +30,7 @@
     {
       "type": "category",
       "label": "API Reference",
+      "collapsed": true,
       "items": [
         {
           "type": "category",
@@ -69,10 +70,14 @@
     {
       "type": "category",
       "label": "RTK Query",
+      "collapsed": false,
       "items": [
+        "rtk-query/overview",
+        "rtk-query/comparison",
         {
           "type": "category",
           "label": "Using RTK Query",
+          "collapsed": true,
           "items": [
             "rtk-query/usage/queries",
             "rtk-query/usage/mutations",
@@ -95,7 +100,7 @@
         {
           "type": "category",
           "label": "API Reference",
-          "collapsed": false,
+          "collapsed": true,
           "items": [
             "rtk-query/api/createApi",
             "rtk-query/api/fetchBaseQuery",