react-redux-cache 0.22.1 → 0.22.3

package/README.md

@@ -46,7 +46,7 @@ Can be considered as `ApolloClient` for protocols other than `GraphQL`, but with
   ```js
   {
     entities: {
-      // each typename has its own map of entities, stored by id
+      // Each typename has its own map of entities, stored by id.
       users: {
         "0": {id: 0, bankId: "0", name: "User 0 *"},
         "1": {id: 1, bankId: "1", name: "User 1 *"},
@@ -61,13 +61,13 @@ Can be considered as `ApolloClient` for protocols other than `GraphQL`, but with
       }
     },
     queries: {
-      // each query has its own map of query states, stored by cache key, which is generated from query params
+      // Each query has its own map of query states, stored by cache key, which is generated from query params.
       getUser: {
         "2": {result: 2, params: 2, expiresAt: 1727217298025},
         "3": {loading: Promise<...>, params: 3}
       },
       getUsers: {
-        // example of paginated state under custom cache key
+        // Example of paginated state under custom cache key.
         "feed": {
           result: {items: [0,1,2], page: 1},
           params: {page: 1}
@@ -192,7 +192,7 @@ export const {
   reducer,
   hooks: {useClient, useMutation, useQuery},
 } = withTypenames<CacheTypenames>().createCache({
-  name: 'cache', // Used as prefix for actions and in default cacheStateSelector for selecting cache state from redux state.
+  name: 'cache', // Used as prefix for actions and in default cacheStateSelector for selecting cache state from the store.
   queries: {
     getUsers: { query: getUsers },
     getUser: {
@@ -273,15 +273,15 @@ export const getUser = (async (id) => {
   return normalize(response, getUserSchema)
 }) satisfies NormalizedQuery<CacheTypenames, number>
 
-// Example of query without normalization (not recommended), with selecting access token from the store
+// Example of query without normalization (not recommended), with selecting access token from the store.
 
 export const getBank = (async (id, {getState}) => {
   const token = tokenSelector(getState())
   const result: Bank = ...
-  return {result} // result is bank object, no entities passed
+  return {result} // result is bank object, no entities passed.
 }) satisfies Query<string>
 
-// Example of mutation with normalization
+// Example of mutation with normalization.
 
 export const removeUser = (async (id, _, abortSignal) => {
   await ...
@@ -300,18 +300,19 @@ Please check `example/` folder (`npm run example` to run). There are examples fo
 export const UserScreen = () => {
   const {id} = useParams()
 
-  // useQuery connects to redux state and if user with that id is already cached, fetch won't happen (with default FetchPolicy.NoCacheOrExpired).
-  // Infers all types from created cache, telling here that params and result are of type `number`.
-  const [{result: userId, loading, error}] = useQuery({
+  // useQuery fetches data if query not cached already (with default FetchPolicy.NoCacheOrExpired).
+  // Infers all types from created cache so expects params of type `number`.
+  const [{result: user, loading, error}] = useQuery({
     query: 'getUser',
     params: Number(id),
   })
 
+  // Globally tracks loading state for mutation.
   const [updateUser, {loading: updatingUser}] = useMutation({
     mutation: 'updateUser',
   })
 
-  // This selector returns entities with proper types - User and Bank
+  // This selector used only with normalization and returns entities with proper types - User and Bank.
   const user = useSelectEntityById(userId, 'users')
   const bank = useSelectEntityById(user?.bankId, 'banks')
 
@@ -329,12 +330,12 @@ export const UserScreen = () => {
 
 For huge collections (> 1000 items, see benchmark) immutable approach may be a bottleneck - every merge of entity, query or mutation state is O(n). There is an option `mutableCollections` that makes it O(1) by using mutable approach when working with collections, while still keeping separate entities, query and mutation states immutable.
 
-[Benchmark](https://github.com/gentlee/react-redux-cache/blob/main/benchmark.ts) results of adding item to collection depending on collection size, in microseconds (less is better):
+[Benchmark](https://github.com/gentlee/react-redux-cache/blob/main/scripts/benchmark.mjs) results of adding item to collection depending on collection size, in microseconds (Macbook M1, less is better):
     
 | Collection size | 0 | 1000 | 10000 | 100000 | 1000000 |
 |-|-|-|-|-|-|
-| immutable | 1.78 | 1.69 | 5.64 | 117.4 | 1284.6 |
-| mutable | 1.68 | 0.92 | 0.98 | 0.98 | 0.99 |
+| immutable | 1.57 | 1.81 | 7.62 | 103.82 | 1457.89 |
+| mutable | 1.4 | 1.15 | 0.65 | 1.03 | 0.76 |
 
 Well written code should not subcribe to whole collections, so just enabling this options most of the times should not break anything. But if it is still needed, you should subscribe to both collection (it may still change e.g. when clearing state) and to its `_changeKey`.
 
@@ -342,7 +343,7 @@ Well written code should not subcribe to whole collections, so just enabling thi
 const Component = () => {
   // It is usually a bad idea to subscribe to whole collections, consider using order of ids and subscribe to a single entity in each cell.
   const allUsers = useSelector((state) => selectEntitiesByTypename(state, 'users'))
-  const allUsersChangeKey = useSelector((state) => selectEntitiesByTypename(state, 'users')._changeKey) // <-- Add this line while subscribing to collections
+  const allUsersChangeKey = useSelector((state) => selectEntitiesByTypename(state, 'users')._changeKey) // <-- Add this line while subscribing to collections.
 
   // For memoized components you should also pass it as extra prop to cause its re-render.
   return <List data={allUsers} extra={allUsersChangeKey}/>
@@ -366,8 +367,8 @@ export const updateBank = (async (bank) => {
   const {httpError, response} = ...
   return {
     result: {
-      httpError,            // Error is a part of the result, containing e.g. map of not valid fields and threir error messages
-      bank: response?.bank  // Bank still can be returned from the backend with error e.g. when only some of fields were udpated
+      httpError,            // Error is a part of the result, containing e.g. map of not valid fields and threir error messages.
+      bank: response?.bank  // Bank still can be returned from the backend with error e.g. when only some of fields were udpated.
     }
   }
 }) satisfies Mutation<Partial<Bank>>
@@ -402,7 +403,7 @@ export const cache = createCache({
     updateUser: {
       mutation: updateUser,
       onSuccess(_, __, {dispatch}, {invalidateQuery}) {
-        // Invalidate getUsers after a single user update (can be done better by updating getUsers state with updateQueryStateAndEntities)
+        // Invalidate getUsers after a single user update (can be done better by updating getUsers state with updateQueryStateAndEntities).
         dispatch(invalidateQuery([{query: 'getUsers'}]))
       },
     },
@@ -425,7 +426,7 @@ export const UserScreen = () => {
   const [{loading, error}] = useQuery({
     query: 'getUser',
     params: userId,
-    skipFetch: !!user // Disable fetches if we already have user cached by some other query, e.g. getUsers
+    skipFetch: !!user // Disable fetches if we already have user cached by some other query, e.g. getUsers.
   })
 
   ...
@@ -440,10 +441,10 @@ But if more control is needed, e.g. checking if entity is full, custom fetch pol
     query: getUser,
     fetchPolicy(expired, id, _, {getState}, {selectEntityById}) {
       if (expired) {
-        return true // fetch if expired
+        return true // Fetch if expired.
       }
 
-      // fetch if user is not full
+      // Fetch if user is not full.
       const user = selectEntityById(getState(), id, 'users')
       return !user || !('name' in user) || !('bankId' in user)
     },
@@ -465,7 +466,9 @@ export const UserScreen = () => {
 
   useEffect(() => {
     if (screenIsVisible) {
-      fetchUser({ onlyIfExpired: true }) // expiration happens if expiresAt was set before e.g. by secondsToLive option or invalidateQuery action. If result is not cached yet, it is also considered as expired.
+      // Expiration happens if expiresAt was set before e.g. by secondsToLive option or invalidateQuery action.
+      // If result is not cached yet, it is also considered as expired.
+      fetchUser({ onlyIfExpired: true })
     }
   }, [screenIsVisible])
 
@@ -486,7 +489,7 @@ Here is an example of `getUsers` query configuration with pagination support. Yo
   queries: {
     getUsers: {
       query: getUsers,
-      getCacheKey: () => 'feed', // single cache key is used for all pages
+      getCacheKey: () => 'feed', // Single cache key is used for all pages.
       mergeResults: (oldResult, {result: newResult}) => {
         if (!oldResult || newResult.page === 1) {
           return newResult
@@ -549,16 +552,17 @@ export const GetUsersScreen = () => {
 Here is a simple `redux-persist` configuration:
 
 ```typescript
-// removes `loading` and `error` from persisted state
+// Removes `loading` and `error` from persisted state.
+// '_changeKey' is needed only when `mutuableCollections` enabled.
 function stringifyReplacer(key: string, value: unknown) {
-  return key === 'loading' || key === 'error' ? undefined : value
+  return key === 'loading' || key === 'error' || key === '_changeKey' ? undefined : value
 }
 
 const persistedReducer = persistReducer(
   {
     key: 'cache',
     storage,
-    whitelist: ['entities', 'queries'], // mutations are ignored
+    whitelist: ['entities', 'queries'], // Mutation states are ignored.
     throttle: 1000, // ms
     serialize: (value: unknown) => JSON.stringify(value, stringifyReplacer),
   },
@@ -593,6 +597,6 @@ As example, can be overridden when implementing pagination.
 
 #### How race conditions are handled?
 
-**Queries:** Queries are throttled: query with the same cache key (generated from params by default) is cancelled if already running.
+**Queries:** Queries are deduplicated: queries with the same cache key (generated from params by default) use existing fetch promise if already fetching.
 
-**Mutations:** Mutations are debounced: previous similar mutation is aborted if it was running when the new one started. Third argument in mutations is `AbortSignal`, which can be used e.g. for cancelling http requests.
+**Mutations:** Mutations are cancelled: previous similar mutation is aborted if it was running when the new one started. Third argument in mutations is `AbortSignal`, which can be used e.g. for cancelling http requests.

package/dist/cjs/createActions.js

@@ -1,64 +1,64 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createActions = void 0;
-const utilsAndConstants_1 = require("./utilsAndConstants");
+'use strict'
+Object.defineProperty(exports, '__esModule', {value: true})
+exports.createActions = void 0
+const utilsAndConstants_1 = require('./utilsAndConstants')
 const createActions = (name) => {
-    const actionPrefix = `@${utilsAndConstants_1.PACKAGE_SHORT_NAME}/${name}/`;
-    const updateQueryStateAndEntitiesType = `${actionPrefix}updateQueryStateAndEntities`;
-    const updateQueryStateAndEntities = (queryKey, queryCacheKey, state, entityChanges) => ({
-        type: updateQueryStateAndEntitiesType,
-        queryKey,
-        queryCacheKey,
-        state,
-        entityChanges,
-    });
-    updateQueryStateAndEntities.type = updateQueryStateAndEntitiesType;
-    const updateMutationStateAndEntitiesType = `${actionPrefix}updateMutationStateAndEntities`;
-    const updateMutationStateAndEntities = (mutationKey, state, entityChanges) => ({
-        type: updateMutationStateAndEntitiesType,
-        mutationKey,
-        state,
-        entityChanges,
-    });
-    updateMutationStateAndEntities.type = updateMutationStateAndEntitiesType;
-    const mergeEntityChangesType = `${actionPrefix}mergeEntityChanges`;
-    const mergeEntityChanges = (changes) => ({
-        type: mergeEntityChangesType,
-        changes,
-    });
-    mergeEntityChanges.type = mergeEntityChangesType;
-    const invalidateQueryType = `${actionPrefix}invalidateQuery`;
-    const invalidateQuery = (queries) => ({
-        type: invalidateQueryType,
-        queries,
-    });
-    invalidateQuery.type = invalidateQueryType;
-    const clearQueryStateType = `${actionPrefix}clearQueryState`;
-    const clearQueryState = (queries) => ({
-        type: clearQueryStateType,
-        queries,
-    });
-    clearQueryState.type = clearQueryStateType;
-    const clearMutationStateType = `${actionPrefix}clearMutationState`;
-    const clearMutationState = (mutationKeys) => ({
-        type: clearMutationStateType,
-        mutationKeys,
-    });
-    clearMutationState.type = clearMutationStateType;
-    const clearCacheType = `${actionPrefix}clearCache`;
-    const clearCache = (stateToKeep) => ({
-        type: clearCacheType,
-        stateToKeep,
-    });
-    clearCache.type = clearCacheType;
-    return {
-        updateQueryStateAndEntities,
-        updateMutationStateAndEntities,
-        mergeEntityChanges,
-        invalidateQuery,
-        clearQueryState,
-        clearMutationState,
-        clearCache,
-    };
-};
-exports.createActions = createActions;
+  const actionPrefix = `@${utilsAndConstants_1.PACKAGE_SHORT_NAME}/${name}/`
+  const updateQueryStateAndEntitiesType = `${actionPrefix}updateQueryStateAndEntities`
+  const updateQueryStateAndEntities = (queryKey, queryCacheKey, state, entityChanges) => ({
+    type: updateQueryStateAndEntitiesType,
+    queryKey,
+    queryCacheKey,
+    state,
+    entityChanges,
+  })
+  updateQueryStateAndEntities.type = updateQueryStateAndEntitiesType
+  const updateMutationStateAndEntitiesType = `${actionPrefix}updateMutationStateAndEntities`
+  const updateMutationStateAndEntities = (mutationKey, state, entityChanges) => ({
+    type: updateMutationStateAndEntitiesType,
+    mutationKey,
+    state,
+    entityChanges,
+  })
+  updateMutationStateAndEntities.type = updateMutationStateAndEntitiesType
+  const mergeEntityChangesType = `${actionPrefix}mergeEntityChanges`
+  const mergeEntityChanges = (changes) => ({
+    type: mergeEntityChangesType,
+    changes,
+  })
+  mergeEntityChanges.type = mergeEntityChangesType
+  const invalidateQueryType = `${actionPrefix}invalidateQuery`
+  const invalidateQuery = (queries) => ({
+    type: invalidateQueryType,
+    queries,
+  })
+  invalidateQuery.type = invalidateQueryType
+  const clearQueryStateType = `${actionPrefix}clearQueryState`
+  const clearQueryState = (queries) => ({
+    type: clearQueryStateType,
+    queries,
+  })
+  clearQueryState.type = clearQueryStateType
+  const clearMutationStateType = `${actionPrefix}clearMutationState`
+  const clearMutationState = (mutationKeys) => ({
+    type: clearMutationStateType,
+    mutationKeys,
+  })
+  clearMutationState.type = clearMutationStateType
+  const clearCacheType = `${actionPrefix}clearCache`
+  const clearCache = (stateToKeep) => ({
+    type: clearCacheType,
+    stateToKeep,
+  })
+  clearCache.type = clearCacheType
+  return {
+    updateQueryStateAndEntities,
+    updateMutationStateAndEntities,
+    mergeEntityChanges,
+    invalidateQuery,
+    clearQueryState,
+    clearMutationState,
+    clearCache,
+  }
+}
+exports.createActions = createActions