react-redux-cache 0.13.0-rc.0 → 0.14.0

package/README.md

@@ -9,7 +9,7 @@
 
 # react-redux-cache (RRC)
 
-**Powerful** yet **lightweight** data fetching and caching library that supports **normalization** unlike `react-query` and `rtk-query`, while having similar but very simple interface. Built on top of `redux`, covered with tests, fully typed and written on Typescript.
+**Powerful** yet **lightweight** data fetching and caching library that supports **normalization** unlike `React Query` and `RTK-Query`, while having similar but not over-engineered, simple interface. Another advantage over `RTK-Query` is that it easily supports `Infinite Scroll`. Built on top of `Redux`, covered with tests, fully typed and written on Typescript.
 
 **Normalization** is the best way to keep the state of the app **consistent** between different views, reduces the number of fetches and allows to show cached data when navigating, which greatly improves **user experience**.
 
@@ -119,7 +119,7 @@ Examples of states, generated by cache reducer from `/example` project:
  - [Advanced](https://github.com/gentlee/react-redux-cache#advanced)
    - [Error handling](https://github.com/gentlee/react-redux-cache#error-handling)
    - [Invalidation](https://github.com/gentlee/react-redux-cache#invalidation)
-   - [Extended fetch policy](https://github.com/gentlee/react-redux-cache#extended-cache-policy)
+   - [Extended & custom fetch policy](https://github.com/gentlee/react-redux-cache#extended--custom-fetch-policy)
    - [Infinite scroll pagination](https://github.com/gentlee/react-redux-cache#infinite-scroll-pagination)
    - [redux-persist](https://github.com/gentlee/react-redux-cache#redux-persist)
  - [FAQ](https://github.com/gentlee/react-redux-cache#faq)
@@ -200,7 +200,6 @@ const store = configureStore({
 })
 ```
 #### api.ts
-Query result should be of type `QueryResponse`, mutation result should be of type `MutationResponse`.
 For normalization `normalizr` package is used in this example, but any other tool can be used if query result is of proper type.
 Perfect implementation is when the backend already returns normalized data.
 ```typescript
@@ -274,7 +273,7 @@ export const UserScreen = () => {
 Queries and mutations are wrapped in try/catch, so any error will lead to cancelling of any updates to the state except `loading: false` and the caught error. If you still want to make some state updates, or just want to use thrown errors only for unexpected cases, consider returning expected errors as a part of the result:
 
 ```typescript
-export const updateBank = (bank) => {
+export const updateBank = (async (bank) => {
   const {httpError, response} = ...
   return {
     result: {
@@ -284,7 +283,7 @@ export const updateBank = (bank) => {
       bank: response?.bank
     }
   }
-} satisfies Mutation<Partial<Bank>>
+}) satisfies Mutation<Partial<Bank>>
 ```
 
 If global error handling is needed for errors, not handled by query / mutation `onError` callback, global `onError` can be used:
@@ -432,7 +431,6 @@ export const GetUsersScreen = () => {
   const onLoadNextPage = () => {
     const lastLoadedPage = usersResult?.page ?? 0
     fetchUsers({
-      query: 'getUsers',
       params: lastLoadedPage + 1,
     })
   }

package/dist/createActions.d.ts

@@ -1,4 +1,5 @@
 import type { EntityChanges, Key, MutationState, QueryState, Typenames } from './types';
+import { ReduxCacheState } from './types';
 export type Actions<N extends string = string, T extends Typenames = Typenames, QP = unknown, QR = unknown, MP = unknown, MR = unknown> = ReturnType<typeof createActions<N, T, QP, QR, MP, MR>>;
 export declare const createActions: <N extends string, T extends Typenames, QP, QR, MP, MR>(name: N) => {
     updateQueryStateAndEntities: {
@@ -72,4 +73,11 @@ export declare const createActions: <N extends string, T extends Typenames, QP,
         };
         type: `@rrc/${N}/clearMutationState`;
     };
+    clearCache: {
+        (stateToKeep?: Partial<ReduxCacheState<T, QP, QR, MP, MR>>): {
+            type: `@rrc/${N}/clearCache`;
+            stateToKeep: Partial<ReduxCacheState<T, QP, QR, MP, MR>> | undefined;
+        };
+        type: `@rrc/${N}/clearCache`;
+    };
 };

package/dist/createActions.js

@@ -45,6 +45,12 @@ const createActions = (name) => {
         mutationKeys,
     });
     clearMutationState.type = clearMutationStateType;
+    const clearCacheType = `${actionPrefix}clearCache`;
+    const clearCache = (stateToKeep) => ({
+        type: clearCacheType,
+        stateToKeep,
+    });
+    clearCache.type = clearCacheType;
     return {
         updateQueryStateAndEntities,
         updateMutationStateAndEntities,
@@ -52,6 +58,7 @@ const createActions = (name) => {
         invalidateQuery,
         clearQueryState,
         clearMutationState,
+        clearCache,
     };
 };
 exports.createActions = createActions;

package/dist/createCache.d.ts

@@ -17,11 +17,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
         /** Keeps all options, passed while creating the cache. */
         cache: Cache<N, T, QP, QR, MP, MR>;
         /** Reducer of the cache, should be added to redux store. */
-        reducer: (state: {
-            entities: import("./types").EntitiesMap<T>;
-            queries: { [QK in keyof (QP | QR)]: import("./types").Dict<import("./types").QueryState<QP[QK], QR[QK]> | undefined>; };
-            mutations: { [MK in keyof (MP | MR)]: import("./types").MutationState<MP[MK], MR[MK]>; };
-        } | undefined, action: {
+        reducer: (state: import("./types").ReduxCacheState<T, QP, QR, MP, MR> | undefined, action: {
             type: `@rrc/${N}/updateQueryStateAndEntities`;
             queryKey: keyof QP & keyof QR;
             queryCacheKey: Key;
@@ -51,11 +47,10 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
         } | {
             type: `@rrc/${N}/clearMutationState`;
             mutationKeys: (keyof MP & keyof MR)[];
-        }) => {
-            entities: import("./types").EntitiesMap<T>;
-            queries: { [QK in keyof (QP | QR)]: import("./types").Dict<import("./types").QueryState<QP[QK], QR[QK]> | undefined>; };
-            mutations: { [MK in keyof (MP | MR)]: import("./types").MutationState<MP[MK], MR[MK]>; };
-        };
+        } | {
+            type: `@rrc/${N}/clearCache`;
+            stateToKeep: Partial<import("./types").ReduxCacheState<T, QP, QR, MP, MR>> | undefined;
+        }) => import("./types").ReduxCacheState<T, QP, QR, MP, MR>;
         actions: {
             /** Updates query state, and optionally merges entity changes in a single action. */
             updateQueryStateAndEntities: {
@@ -78,7 +73,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
                 };
                 type: `@rrc/${N}/updateMutationStateAndEntities`;
             };
-            /** Merge EntityChanges to the state. */
+            /** Merges EntityChanges to the state. */
             mergeEntityChanges: {
                 (changes: import("./types").EntityChanges<T>): {
                     type: `@rrc/${N}/mergeEntityChanges`;
@@ -102,7 +97,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
                 };
                 type: `@rrc/${N}/invalidateQuery`;
             };
-            /** Clear states for provided query keys and cache keys.
+            /** Clears states for provided query keys and cache keys.
              * If cache key for query key is not provided, the whole state for query key is cleared. */
             clearQueryState: {
                 <K extends keyof QP & keyof QR>(queries: {
@@ -117,7 +112,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
                 };
                 type: `@rrc/${N}/clearQueryState`;
             };
-            /** Clear states for provided mutation keys. */
+            /** Clears states for provided mutation keys. */
             clearMutationState: {
                 <K extends keyof MP & keyof MR>(mutationKeys: K[]): {
                     type: `@rrc/${N}/clearMutationState`;
@@ -125,8 +120,18 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
                 };
                 type: `@rrc/${N}/clearMutationState`;
             };
+            /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and shoult be used with caution. */
+            clearCache: {
+                (stateToKeep?: Partial<import("./types").ReduxCacheState<T, QP, QR, MP, MR>> | undefined): {
+                    type: `@rrc/${N}/clearCache`;
+                    stateToKeep: Partial<import("./types").ReduxCacheState<T, QP, QR, MP, MR>> | undefined;
+                };
+                type: `@rrc/${N}/clearCache`;
+            };
         };
         selectors: {
+            /** This is a cacheStateSelector from createCache options, or default one if was not provided. */
+            selectCacheState: (state: any) => import("./types").ReduxCacheState<T, QP, QR, MP, MR>;
             /** Selects query state. */
             selectQueryState: <QK extends keyof QP | keyof QR>(state: unknown, query: QK, cacheKey: Key) => import("./types").QueryState<QK extends keyof QP & keyof QR ? QP[QK] : never, QK extends keyof QP & keyof QR ? QR[QK] : never>;
             /** Selects query latest result. */
@@ -183,18 +188,14 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
     queries: Partial<{ [QK in keyof (QP & QR)]: QK extends keyof QP & keyof QR ? import("./types").QueryInfo<N, Typenames, QP[QK], QR[QK], QP, QR, MP, MR> : never; }>;
     mutations: Partial<{ [MK in keyof (MP & MR)]: MK extends keyof MP & keyof MR ? import("./types").MutationInfo<N, Typenames, MP[MK], MR[MK], QP, QR, MP, MR> : never; }>;
     options: Partial<CacheOptions>;
-    cacheStateSelector: Partial<(state: any) => import("./createCacheReducer").ReduxCacheState<Typenames, QP, QR, MP, MR>>;
+    cacheStateSelector: Partial<(state: any) => import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>>;
 }> & Omit<Omit<Cache<N, Typenames, QP, QR, MP, MR>, "globals">, "queries" | "mutations" | "options" | "cacheStateSelector"> & {
     globals?: OptionalPartial<Globals<N, Typenames, QP, QR, MP, MR>, "queries"> | undefined;
 }) => {
     /** Keeps all options, passed while creating the cache. */
     cache: Cache<N, Typenames, QP, QR, MP, MR>;
     /** Reducer of the cache, should be added to redux store. */
-    reducer: (state: {
-        entities: import("./types").EntitiesMap<Typenames>;
-        queries: { [QK_1 in keyof (QP | QR)]: import("./types").Dict<import("./types").QueryState<QP[QK_1], QR[QK_1]> | undefined>; };
-        mutations: { [MK_1 in keyof (MP | MR)]: import("./types").MutationState<MP[MK_1], MR[MK_1]>; };
-    } | undefined, action: {
+    reducer: (state: import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR> | undefined, action: {
         type: `@rrc/${N}/updateQueryStateAndEntities`;
         queryKey: keyof QP & keyof QR;
         queryCacheKey: Key;
@@ -224,11 +225,10 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
     } | {
         type: `@rrc/${N}/clearMutationState`;
         mutationKeys: (keyof MP & keyof MR)[];
-    }) => {
-        entities: import("./types").EntitiesMap<Typenames>;
-        queries: { [QK_1 in keyof (QP | QR)]: import("./types").Dict<import("./types").QueryState<QP[QK_1], QR[QK_1]> | undefined>; };
-        mutations: { [MK_1 in keyof (MP | MR)]: import("./types").MutationState<MP[MK_1], MR[MK_1]>; };
-    };
+    } | {
+        type: `@rrc/${N}/clearCache`;
+        stateToKeep: Partial<import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>> | undefined;
+    }) => import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>;
     actions: {
         /** Updates query state, and optionally merges entity changes in a single action. */
         updateQueryStateAndEntities: {
@@ -251,7 +251,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
             };
             type: `@rrc/${N}/updateMutationStateAndEntities`;
         };
-        /** Merge EntityChanges to the state. */
+        /** Merges EntityChanges to the state. */
         mergeEntityChanges: {
             (changes: import("./types").EntityChanges<Typenames>): {
                 type: `@rrc/${N}/mergeEntityChanges`;
@@ -275,7 +275,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
             };
             type: `@rrc/${N}/invalidateQuery`;
         };
-        /** Clear states for provided query keys and cache keys.
+        /** Clears states for provided query keys and cache keys.
          * If cache key for query key is not provided, the whole state for query key is cleared. */
         clearQueryState: {
             <K extends keyof QP & keyof QR>(queries: {
@@ -290,7 +290,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
             };
             type: `@rrc/${N}/clearQueryState`;
         };
-        /** Clear states for provided mutation keys. */
+        /** Clears states for provided mutation keys. */
         clearMutationState: {
             <K extends keyof MP & keyof MR>(mutationKeys: K[]): {
                 type: `@rrc/${N}/clearMutationState`;
@@ -298,8 +298,18 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
             };
             type: `@rrc/${N}/clearMutationState`;
         };
+        /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and shoult be used with caution. */
+        clearCache: {
+            (stateToKeep?: Partial<import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>> | undefined): {
+                type: `@rrc/${N}/clearCache`;
+                stateToKeep: Partial<import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>> | undefined;
+            };
+            type: `@rrc/${N}/clearCache`;
+        };
     };
     selectors: {
+        /** This is a cacheStateSelector from createCache options, or default one if was not provided. */
+        selectCacheState: (state: any) => import("./types").ReduxCacheState<Typenames, QP, QR, MP, MR>;
         /** Selects query state. */
         selectQueryState: <QK_1 extends keyof QP | keyof QR>(state: unknown, query: QK_1, cacheKey: Key) => import("./types").QueryState<QK_1 extends keyof QP & keyof QR ? QP[QK_1] : never, QK_1 extends keyof QP & keyof QR ? QR[QK_1] : never>;
         /** Selects query latest result. */

package/dist/createCache.js

@@ -53,7 +53,7 @@ const withTypenames = () => {
             const { selectQueryState, selectQueryResult, selectQueryLoading, selectQueryError, selectQueryParams, selectQueryExpiresAt, selectMutationState, selectMutationResult, selectMutationLoading, selectMutationError, selectMutationParams, selectEntityById, selectEntities, selectEntitiesByTypename, } = selectors;
             // actions
             const actions = (0, createActions_1.createActions)(cache.name);
-            const { updateQueryStateAndEntities, updateMutationStateAndEntities, mergeEntityChanges, invalidateQuery, clearQueryState, clearMutationState, } = actions;
+            const { updateQueryStateAndEntities, updateMutationStateAndEntities, mergeEntityChanges, invalidateQuery, clearQueryState, clearMutationState, clearCache, } = actions;
             return {
                 /** Keeps all options, passed while creating the cache. */
                 cache,
@@ -64,17 +64,21 @@ const withTypenames = () => {
                     updateQueryStateAndEntities,
                     /** Updates mutation state, and optionally merges entity changes in a single action. */
                     updateMutationStateAndEntities,
-                    /** Merge EntityChanges to the state. */
+                    /** Merges EntityChanges to the state. */
                     mergeEntityChanges,
                     /** Invalidates query states. */
                     invalidateQuery,
-                    /** Clear states for provided query keys and cache keys.
+                    /** Clears states for provided query keys and cache keys.
                      * If cache key for query key is not provided, the whole state for query key is cleared. */
                     clearQueryState,
-                    /** Clear states for provided mutation keys. */
+                    /** Clears states for provided mutation keys. */
                     clearMutationState,
+                    /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and shoult be used with caution. */
+                    clearCache,
                 },
                 selectors: {
+                    /** This is a cacheStateSelector from createCache options, or default one if was not provided. */
+                    selectCacheState: cache.cacheStateSelector,
                     /** Selects query state. */
                     selectQueryState,
                     /** Selects query latest result. */

package/dist/createCacheReducer.d.ts

@@ -1,12 +1,3 @@
 import type { Actions } from './createActions';
-import type { CacheOptions, Dict, EntitiesMap, MutationState, QueryState, Typenames } from './types';
-export type ReduxCacheState<T extends Typenames, QP, QR, MP, MR> = ReturnType<ReturnType<typeof createCacheReducer<string, T, QP, QR, MP, MR>>>;
-export declare const createCacheReducer: <N extends string, T extends Typenames, QP, QR, MP, MR>(actions: Actions<N, T, QP, QR, MP, MR>, queryKeys: (keyof (QP | QR))[], cacheOptions: CacheOptions) => (state: {
-    entities: EntitiesMap<T>;
-    queries: { [QK in keyof (QP | QR)]: Dict<QueryState<QP[QK], QR[QK]> | undefined>; };
-    mutations: { [MK in keyof (MP | MR)]: MutationState<MP[MK], MR[MK]>; };
-} | undefined, action: ReturnType<(typeof actions)[keyof typeof actions]>) => {
-    entities: EntitiesMap<T>;
-    queries: { [QK in keyof (QP | QR)]: Dict<QueryState<QP[QK], QR[QK]> | undefined>; };
-    mutations: { [MK in keyof (MP | MR)]: MutationState<MP[MK], MR[MK]>; };
-};
+import type { CacheOptions, ReduxCacheState, Typenames } from './types';
+export declare const createCacheReducer: <N extends string, T extends Typenames, QP, QR, MP, MR>(actions: Actions<N, T, QP, QR, MP, MR>, queryKeys: (keyof (QP | QR))[], cacheOptions: CacheOptions) => (state: ReduxCacheState<T, QP, QR, MP, MR> | undefined, action: ReturnType<(typeof actions)[keyof typeof actions]>) => ReduxCacheState<T, QP, QR, MP, MR>;

package/dist/createCacheReducer.js

@@ -16,17 +16,14 @@ const utilsAndConstants_1 = require("./utilsAndConstants");
 const optionalQueryKeys = ['error', 'expiresAt', 'result', 'params'];
 const optionalMutationKeys = ['error', 'result', 'params'];
 const createCacheReducer = (actions, queryKeys, cacheOptions) => {
-    const entitiesMap = {};
-    const queryStateMap = {};
-    for (const key of queryKeys) {
-        queryStateMap[key] = {};
-    }
-    const mutationStateMap = {};
-    const initialState = {
-        entities: entitiesMap,
-        queries: queryStateMap,
-        mutations: mutationStateMap,
-    };
+    const initialState = Object.freeze({
+        entities: Object.freeze({}),
+        queries: Object.freeze(queryKeys.reduce((result, x) => {
+            result[x] = Object.freeze({});
+            return result;
+        }, {})),
+        mutations: Object.freeze({}),
+    });
     cacheOptions.logsEnabled &&
         (0, utilsAndConstants_1.log)('createCacheReducer', {
             queryKeys,
@@ -205,6 +202,11 @@ const createCacheReducer = (actions, queryKeys, cacheOptions) => {
                     ? state
                     : Object.assign(Object.assign({}, state), { mutations: newMutations });
             }
+            case actions.clearCache.type: {
+                const { stateToKeep } = action;
+                return stateToKeep
+                    ? Object.assign(Object.assign({}, initialState), stateToKeep) : initialState;
+            }
         }
         return state;
     };

package/dist/index.js

@@ -27,12 +27,12 @@ Object.defineProperty(exports, "FetchPolicy", { enumerable: true, get: function
 Object.defineProperty(exports, "isEmptyObject", { enumerable: true, get: function () { return utilsAndConstants_1.isEmptyObject; } });
 // Backlog
 // ! high (1.0.0-rc.0)
+// reset [whole] cache to initial / to provided state
+// optimistic response
 // generate full api docs
 // ! medium
-// optimistic response
 // onCancel & onAbort
 // remove empty entities and queries from state
-// reset [whole] cache to initial / to provided state
 // globals for success, completions and loading states?
 // make query key / cache key difference more clear in the docs
 // check type of function arguments in dev

package/dist/types.d.ts

@@ -1,6 +1,5 @@
 import type { Store } from 'redux';
 import type { Actions } from './createActions';
-import type { ReduxCacheState } from './createCacheReducer';
 import type { Selectors } from './createSelectors';
 export type Key = string | number | symbol;
 export type Dict<T> = Record<Key, T>;
@@ -72,6 +71,15 @@ export type EntitiesMap<T extends Typenames> = {
 export type EntityIds<T extends Typenames> = {
     [K in keyof T]?: Key[];
 };
+export type ReduxCacheState<T extends Typenames, QP, QR, MP, MR> = {
+    entities: EntitiesMap<T>;
+    queries: {
+        [QK in keyof (QP | QR)]: Dict<QueryState<QP[QK], QR[QK]> | undefined>;
+    };
+    mutations: {
+        [MK in keyof (MP | MR)]: MutationState<MP[MK], MR[MK]>;
+    };
+};
 export type QueryInfo<N extends string, T extends Typenames = Typenames, P = unknown, R = unknown, QP = unknown, QR = unknown, MP = unknown, MR = unknown> = Partial<Pick<Globals<N, T, QP, QR, MP, MR>['queries'], 'skipFetch' | 'secondsToLive'>> & {
     query: NormalizedQuery<T, P, R>;
     /** Determines when useQuery fetch triggers should start fetching. Fetch is performed if function returns true.

package/package.json

@@ -2,7 +2,7 @@
   "name": "react-redux-cache",
   "author": "Alexander Danilov",
   "license": "MIT",
-  "version": "0.13.0-rc.0",
+  "version": "0.14.0",
   "description": "Powerful data fetching and caching library that supports normalization, built on top of redux",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",