react-redux-cache 0.2.0 → 0.4.0

package/README.md

@@ -1,18 +1,88 @@
-### Donations 🙌
-
-**BTC:** bc1qs0sq7agz5j30qnqz9m60xj4tt8th6aazgw7kxr \
-**ETH:** 0x1D834755b5e889703930AC9b784CB625B3cd833E \
-**USDT(Tron):** TPrCq8LxGykQ4as3o1oB8V7x1w2YPU2o5n \
-**TON:** EQAtBuFWI3H_LpHfEToil4iYemtfmyzlaJpahM3tFSoxojvV \
-**DOGE:** D7GMQdKhKC9ymbT9PtcetSFTQjyPRRfkwT
+<details>
+  <summary>Donations 🙌</summary>
+  <b>BTC:</b> bc1qs0sq7agz5j30qnqz9m60xj4tt8th6aazgw7kxr <br>
+  <b>ETH:</b> 0x1D834755b5e889703930AC9b784CB625B3cd833E <br>
+  <b>USDT(Tron):</b> TPrCq8LxGykQ4as3o1oB8V7x1w2YPU2o5n <br>
+  <b>TON:</b> EQAtBuFWI3H_LpHfEToil4iYemtfmyzlaJpahM3tFSoxojvV <br>
+  <b>DOGE:</b> D7GMQdKhKC9ymbT9PtcetSFTQjyPRRfkwT <br>
+</details>
 
 # react-redux-cache
 
-**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`, fully typed and written on Typescript. Can be considered as `ApolloClient` for protocols other than `GraphQL`.
+**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.
 
 **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**.
 
-Remains **full control** of redux state with ability to write custom selectors, actions and reducers to manage cached state.
+Can be considered as `ApolloClient` for protocols other than `GraphQL`, but with **full control** over its storage - redux store, with ability to write custom selectors, actions and reducers to manage cached state.
+
+Example of **normalized** redux state, generated by cache reducer from `/example` project:
+```js
+{
+  entities: {
+    // 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 *"},
+      "2": {id: 2, bankId: "2", name: "User 2"},
+      "3": {id: 3, bankId: "3", name: "User 3"}
+    },
+    banks: {
+      "0": {id: "0", name: "Bank 0"},
+      "1": {id: "1", name: "Bank 1"},
+      "2": {id: "2", name: "Bank 2"},
+      "3": {id: "3", name: "Bank 3"}
+    }
+  },
+  queries: {
+    // each query has its own map of query states, stored by cache key, which is generated from query params
+    getUser: {
+      "2": {loading: false, error: undefined, result: 2},
+      "3": {loading: true}
+    },
+    getUsers: {
+      // example of paginated state under custom cache key
+      "all-pages": {loading: false, result: {items: [0,1,2], page: 1}}
+    }
+  },
+  mutations: {
+    // each mutation has its own state as well
+    updateUser: {loading: false, result: 1} 
+  }
+}
+```
+
+Example of **not normalized** redux state, generated by cache reducer from `/example` project:
+```js
+{
+  // entities map is used for normalization and is empty here
+  entities: {},
+  queries: {
+    // each query has its own map of query states, stored by cache key, which is generated from query params
+    getUser: {
+      "2": {loading: false, error: undefined, result: {id: 2, bank: {id: "2", name: "Bank 2"}, name: "User 2"}},
+      "3": {loading: true}
+    },
+    getUsers: {
+      // example of paginated state under custom cache key
+      "all-pages": {
+        loading: false,
+        result: {
+          items: [
+            {id: 0, bank: {id: "0", name: "Bank 0"}, name: "User 0 *"},
+            {id: 1, bank: {id: "1", name: "Bank 1"}, name: "User 1 *"},
+            {id: 2, bank: {id: "2", name: "Bank 2"}, name: "User 2"}
+          ],
+          page: 1
+        }
+      }
+    }
+  },
+  mutations: {
+    // each mutation has its own state as well
+    updateUser: {loading: false, result: {id: 1, bank: {id: "1", name: "Bank 1"}, name: "User 1 *"}} 
+  }
+}
+```
     
 ### Table of contents
 
@@ -43,17 +113,7 @@ All typenames, queries and mutations should be passed while initializing the cac
 export const {
   cache,
   reducer,
-  hooks: {useClient, useMutation, useQuery, useSelectEntityById},
-  // Actions, selectors and utils may be not used at all
-  selectors: {entitiesSelector, entitiesByTypenameSelector},
-  actions: {
-    updateQueryStateAndEntities,
-    updateMutationStateAndEntities,
-    mergeEntityChanges,
-    clearQueryState,
-    clearMutationState,
-  },
-  utils: {applyEntityChanges},
+  hooks: {useClient, useMutation, useQuery},
 } = createCache({
   // Used as prefix for actions and in default cacheStateSelector for selecting cache state from redux state.
   name: 'cache',

package/dist/createActions.d.ts

@@ -1,6 +1,7 @@
 import type { EntityChanges, Key, QueryMutationState, Typenames } from './types';
 export type ActionMap<N extends string, T extends Typenames, QR, MR> = ReturnType<typeof createActions<N, T, QR, MR>>;
 export declare const createActions: <N extends string, T extends Typenames, QR, MR>(name: N) => {
+    /** Updates query state, and optionally merges entity changes in a single action. */
     updateQueryStateAndEntities: {
         <K extends keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryMutationState<QR[K]>> | undefined, entityChagnes?: EntityChanges<T> | undefined): {
             type: `@rrc/${N}/updateQueryStateAndEntities`;
@@ -11,6 +12,7 @@ export declare const createActions: <N extends string, T extends Typenames, QR,
         };
         type: `@rrc/${N}/updateQueryStateAndEntities`;
     };
+    /** Updates mutation state, and optionally merges entity changes in a single action. */
     updateMutationStateAndEntities: {
         <K_1 extends keyof MR>(mutationKey: K_1, state?: Partial<QueryMutationState<MR[K_1]>> | undefined, entityChagnes?: EntityChanges<T> | undefined): {
             type: `@rrc/${N}/updateMutationStateAndEntities`;
@@ -20,6 +22,7 @@ export declare const createActions: <N extends string, T extends Typenames, QR,
         };
         type: `@rrc/${N}/updateMutationStateAndEntities`;
     };
+    /** Merge EntityChanges to the state. */
     mergeEntityChanges: {
         (changes: EntityChanges<T>): {
             type: `@rrc/${N}/mergeEntityChanges`;
@@ -27,6 +30,8 @@ export declare const createActions: <N extends string, T extends Typenames, QR,
         };
         type: `@rrc/${N}/mergeEntityChanges`;
     };
+    /** Clear 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_2 extends keyof QR>(queryKeys: {
             key: K_2;
@@ -40,6 +45,7 @@ export declare const createActions: <N extends string, T extends Typenames, QR,
         };
         type: `@rrc/${N}/clearQueryState`;
     };
+    /** Clear states for provided mutation keys. */
     clearMutationState: {
         <K_3 extends keyof MR>(mutationKeys: K_3[]): {
             type: `@rrc/${N}/clearMutationState`;

package/dist/createActions.js

@@ -5,7 +5,6 @@ const utilsAndConstants_1 = require("./utilsAndConstants");
 const createActions = (name) => {
     const actionPrefix = `@${utilsAndConstants_1.PACKAGE_SHORT_NAME}/${name}/`;
     const updateQueryStateAndEntitiesType = `${actionPrefix}updateQueryStateAndEntities`;
-    /** Updates query state, and optionally merges entity changes in a single action. */
     const updateQueryStateAndEntities = (queryKey, queryCacheKey, state, entityChagnes) => ({
         type: updateQueryStateAndEntitiesType,
         queryKey,
@@ -15,7 +14,6 @@ const createActions = (name) => {
     });
     updateQueryStateAndEntities.type = updateQueryStateAndEntitiesType;
     const updateMutationStateAndEntitiesType = `${actionPrefix}updateMutationStateAndEntities`;
-    /** Updates mutation state, and optionally merges entity changes in a single action. */
     const updateMutationStateAndEntities = (mutationKey, state, entityChagnes) => ({
         type: updateMutationStateAndEntitiesType,
         mutationKey,
@@ -24,32 +22,34 @@ const createActions = (name) => {
     });
     updateMutationStateAndEntities.type = updateMutationStateAndEntitiesType;
     const mergeEntityChangesType = `${actionPrefix}mergeEntityChanges`;
-    /** Merge EntityChanges to the state. */
     const mergeEntityChanges = (changes) => ({
         type: mergeEntityChangesType,
         changes,
     });
     mergeEntityChanges.type = mergeEntityChangesType;
     const clearQueryStateType = `${actionPrefix}clearQueryState`;
-    /** Clear 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. */
     const clearQueryState = (queryKeys) => ({
         type: clearQueryStateType,
         queryKeys,
     });
     clearQueryState.type = clearQueryStateType;
     const clearMutationStateType = `${actionPrefix}clearMutationState`;
-    /** Clear states for provided mutation keys. */
     const clearMutationState = (mutationKeys) => ({
         type: clearMutationStateType,
         mutationKeys,
     });
     clearMutationState.type = clearMutationStateType;
     return {
+        /** Updates query state, and optionally merges entity changes in a single action. */
         updateQueryStateAndEntities,
+        /** Updates mutation state, and optionally merges entity changes in a single action. */
         updateMutationStateAndEntities,
+        /** Merge EntityChanges to the state. */
         mergeEntityChanges,
+        /** Clear 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. */
         clearMutationState,
     };
 };

package/dist/createCache.d.ts

@@ -1,4 +1,4 @@
-import type { Cache, EntitiesMap, Key, MutationResult, OptionalPartial, QueryOptions, QueryResult, Typenames } from './types';
+import type { Cache, Key, MutationResult, OptionalPartial, QueryMutationState, QueryOptions, QueryResult, Typenames } from './types';
 import { useMutation } from './useMutation';
 import { useQuery } from './useQuery';
 import { applyEntityChanges } from './utilsAndConstants';
@@ -6,22 +6,23 @@ import { applyEntityChanges } from './utilsAndConstants';
  * Creates reducer, actions and hooks for managing queries and mutations through redux cache.
  */
 export declare const createCache: <N extends string, T extends Typenames, QP, QR, MP, MR>(partialCache: OptionalPartial<Cache<N, T, QP, QR, MP, MR>, "options" | "queries" | "mutations" | "cacheStateSelector">) => {
+    /** 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: EntitiesMap<T>;
-        queries: { [QK in keyof QR]: import("./types").Dict<import("./types").QueryMutationState<QR[QK]>>; };
-        mutations: { [MK in keyof MR]: import("./types").QueryMutationState<MR[MK]>; };
+        entities: import("./types").EntitiesMap<T>;
+        queries: { [QK in keyof QR]: import("./types").Dict<QueryMutationState<QR[QK]>>; };
+        mutations: { [MK in keyof MR]: QueryMutationState<MR[MK]>; };
     } | undefined, action: {
         type: `@rrc/${N}/updateQueryStateAndEntities`;
         queryKey: keyof QR;
         queryCacheKey: Key;
-        state: Partial<import("./types").QueryMutationState<QR[keyof QR]>> | undefined;
+        state: Partial<QueryMutationState<QR[keyof QR]>> | undefined;
         entityChagnes: import("./types").EntityChanges<T> | undefined;
     } | {
         type: `@rrc/${N}/updateMutationStateAndEntities`;
         mutationKey: keyof MR;
-        state: Partial<import("./types").QueryMutationState<MR[keyof MR]>> | undefined;
+        state: Partial<QueryMutationState<MR[keyof MR]>> | undefined;
         entityChagnes: import("./types").EntityChanges<T> | undefined;
     } | {
         type: `@rrc/${N}/mergeEntityChanges`;
@@ -34,28 +35,28 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         }[];
     } | {
         type: `@rrc/${N}/clearMutationState`;
-        mutationKeys: (keyof MR)[]; /** Select all entities of provided typename. */
+        mutationKeys: (keyof MR)[];
     }) => {
-        entities: EntitiesMap<T>;
-        queries: { [QK in keyof QR]: import("./types").Dict<import("./types").QueryMutationState<QR[QK]>>; };
-        mutations: { [MK in keyof MR]: import("./types").QueryMutationState<MR[MK]>; };
+        entities: import("./types").EntitiesMap<T>;
+        queries: { [QK in keyof QR]: import("./types").Dict<QueryMutationState<QR[QK]>>; };
+        mutations: { [MK in keyof MR]: QueryMutationState<MR[MK]>; };
     };
     actions: {
         updateQueryStateAndEntities: {
-            <K extends keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<import("./types").QueryMutationState<QR[K]>> | undefined, entityChagnes?: import("./types").EntityChanges<T> | undefined): {
+            <K extends keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryMutationState<QR[K]>> | undefined, entityChagnes?: import("./types").EntityChanges<T> | undefined): {
                 type: `@rrc/${N}/updateQueryStateAndEntities`;
                 queryKey: K;
                 queryCacheKey: Key;
-                state: Partial<import("./types").QueryMutationState<QR[K]>> | undefined;
+                state: Partial<QueryMutationState<QR[K]>> | undefined;
                 entityChagnes: import("./types").EntityChanges<T> | undefined;
             };
             type: `@rrc/${N}/updateQueryStateAndEntities`;
         };
         updateMutationStateAndEntities: {
-            <K_1 extends keyof MR>(mutationKey: K_1, state?: Partial<import("./types").QueryMutationState<MR[K_1]>> | undefined, entityChagnes?: import("./types").EntityChanges<T> | undefined): {
+            <K_1 extends keyof MR>(mutationKey: K_1, state?: Partial<QueryMutationState<MR[K_1]>> | undefined, entityChagnes?: import("./types").EntityChanges<T> | undefined): {
                 type: `@rrc/${N}/updateMutationStateAndEntities`;
                 mutationKey: K_1;
-                state: Partial<import("./types").QueryMutationState<MR[K_1]>> | undefined;
+                state: Partial<QueryMutationState<MR[K_1]>> | undefined;
                 entityChagnes: import("./types").EntityChanges<T> | undefined;
             };
             type: `@rrc/${N}/updateMutationStateAndEntities`;
@@ -83,36 +84,56 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         clearMutationState: {
             <K_3 extends keyof MR>(mutationKeys: K_3[]): {
                 type: `@rrc/${N}/clearMutationState`;
-                mutationKeys: K_3[]; /** Select all entities of provided typename. */
+                mutationKeys: K_3[];
             };
             type: `@rrc/${N}/clearMutationState`;
-        };
+        }; /** Selects query latest result. */
     };
     selectors: {
-        /** Select all entities from the state. */
-        entitiesSelector: (state: unknown) => EntitiesMap<T>;
-        /** Select all entities of provided typename. */
-        entitiesByTypenameSelector: <TN extends keyof T>(typename: TN) => { [K_4 in keyof T]: (state: unknown) => EntitiesMap<T>[K_4]; }[TN];
+        /** Selects query state. */
+        selectQueryState: <QK_1 extends keyof QR | keyof QP>(state: unknown, query: QK_1, cacheKey: Key) => QueryMutationState<QK_1 extends keyof QP & keyof QR ? QR[QK_1] : never> | undefined;
+        /** Selects query latest result. */
+        selectQueryResult: <QK_2 extends keyof QR | keyof QP>(state: unknown, query: QK_2, cacheKey: Key) => (QK_2 extends keyof QP & keyof QR ? QR[QK_2] : never) | undefined;
+        /** Selects query loading state. */
+        selectQueryLoading: <QK_3 extends keyof QR | keyof QP>(state: unknown, query: QK_3, cacheKey: Key) => boolean | undefined;
+        /** Selects query latest error. */
+        selectQueryError: <QK_4 extends keyof QR | keyof QP>(state: unknown, query: QK_4, cacheKey: Key) => Error | undefined;
+        /** Selects mutation state. */
+        selectMutationState: <MK_1 extends keyof MP | keyof MR>(state: unknown, mutation: MK_1) => QueryMutationState<MK_1 extends keyof MP & keyof MR ? MR[MK_1] : never>;
+        /** Selects mutation latest result. */
+        selectMutationResult: <MK_2 extends keyof MP | keyof MR>(state: unknown, mutation: MK_2) => (MK_2 extends keyof MP & keyof MR ? MR[MK_2] : never) | undefined;
+        /** Selects mutation loading state. */
+        selectMutationLoading: <MK_3 extends keyof MP | keyof MR>(state: unknown, mutation: MK_3) => boolean;
+        /** Selects mutation latest error. */
+        selectMutationError: <MK_4 extends keyof MP | keyof MR>(state: unknown, mutation: MK_4) => Error | undefined;
+        /** Selects entity by id and typename. */
+        selectEntityById: <TN extends keyof T>(state: unknown, id: Key | null | undefined, typename: TN) => void;
+        /** Selects all entities. */
+        selectEntities: (state: unknown) => import("./types").EntitiesMap<T>;
+        /** Selects all entities of provided typename. */
+        selectEntitiesByTypename: <TN_1 extends keyof T>(state: unknown, typename: TN_1) => import("./types").EntitiesMap<T>[TN_1];
     };
     hooks: {
-        /** Returns client object with query function */
+        /** Returns client object with query and mutate functions. */
         useClient: () => {
-            query: <QK_1 extends keyof QR | keyof QP>(options: QueryOptions<T, QP, QR, MR, QK_1>) => Promise<QueryResult<QK_1 extends keyof QP & keyof QR ? QR[QK_1] : never>>;
-            mutate: <MK_1 extends keyof MP | keyof MR>(options: {
-                mutation: MK_1;
-                params: MK_1 extends keyof MP & keyof MR ? MP[MK_1] : never;
-            }) => Promise<MutationResult<MK_1 extends keyof MP & keyof MR ? MR[MK_1] : never>>;
+            query: <QK_5 extends keyof QR | keyof QP>(options: Omit<QueryOptions<T, QP, QR, MR, QK_5>, "cachePolicy">) => Promise<QueryResult<QK_5 extends keyof QP & keyof QR ? QR[QK_5] : never>>;
+            mutate: <MK_5 extends keyof MP | keyof MR>(options: {
+                mutation: MK_5;
+                params: MK_5 extends keyof MP & keyof MR ? MP[MK_5] : never;
+            }) => Promise<MutationResult<MK_5 extends keyof MP & keyof MR ? MR[MK_5] : never>>;
         };
         /** Fetches query when params change and subscribes to query state. */
-        useQuery: <QK_2 extends keyof QR | keyof QP>(options: import("./types").UseQueryOptions<T, QP, QR, MR, QK_2>) => readonly [import("./types").QueryMutationState<QK_2 extends keyof QP & keyof QR ? QR[QK_2] : never>, () => Promise<void>];
+        useQuery: <QK_6 extends keyof QR | keyof QP>(options: import("./types").UseQueryOptions<T, QP, QR, MR, QK_6>) => readonly [QueryMutationState<QK_6 extends keyof QP & keyof QR ? QR[QK_6] : never>, () => Promise<QueryResult<QK_6 extends infer T_1 ? T_1 extends QK_6 ? T_1 extends keyof QP & keyof QR ? QR[T_1] : never : never : never>>];
         /** Subscribes to provided mutation state and provides mutate function. */
-        useMutation: <MK_2 extends keyof MP | keyof MR>(options: {
-            mutation: MK_2;
-        }) => readonly [(params: MK_2 extends keyof MP & keyof MR ? MP[MK_2] : never) => Promise<void>, import("./types").QueryMutationState<MK_2 extends keyof MP & keyof MR ? MP[MK_2] : never>, () => boolean];
-        /** Selects entity by id and subscribes to the changes. */
-        useSelectEntityById: <TN_1 extends keyof T>(id: Key | null | undefined, typename: TN_1) => T[TN_1] | undefined;
+        useMutation: <MK_6 extends keyof MP | keyof MR>(options: {
+            mutation: MK_6;
+        }) => readonly [(params: MK_6 extends keyof MP & keyof MR ? MP[MK_6] : never) => Promise<MutationResult<MK_6 extends infer T_2 ? T_2 extends MK_6 ? T_2 extends keyof MP & keyof MR ? MR[T_2] : never : never : never>>, QueryMutationState<MK_6 extends keyof MP & keyof MR ? MP[MK_6] : never>, () => boolean];
     };
     utils: {
-        applyEntityChanges: (entities: EntitiesMap<T>, changes: import("./types").EntityChanges<T>) => EntitiesMap<T> | undefined;
+        /**
+         * Apply changes to the entities map.
+         * @return `undefined` if nothing to change, otherwise new entities map with applied changes.
+         */
+        applyEntityChanges: (entities: import("./types").EntitiesMap<T>, changes: import("./types").EntityChanges<T>) => import("./types").EntitiesMap<T> | undefined;
     };
 };

package/dist/createCache.js

@@ -29,29 +29,68 @@ const createCache = (partialCache) => {
     partialCache.abortControllers = abortControllers;
     const cache = partialCache;
     // make selectors
-    const entitiesSelector = (state) => {
-        return cache.cacheStateSelector(state).entities;
+    const selectQueryState = (state, query, cacheKey) => {
+        // @ts-expect-error fix later
+        return cache.cacheStateSelector(state).queries[query][cacheKey];
+    };
+    const selectMutationState = (state, mutation) => {
+        // @ts-expect-error fix later
+        return cache.cacheStateSelector(state).mutations[mutation];
     };
-    const enitityMapSelectorByTypename = Object.keys(partialCache.typenames).reduce((result, x) => {
-        result[x] = (state) => cache.cacheStateSelector(state).entities[x];
-        return result;
-    }, {});
     const actions = (0, createActions_1.createActions)(cache.name);
     return {
+        /** Keeps all options, passed while creating the cache. */
         cache,
         /** Reducer of the cache, should be added to redux store. */
         reducer: (0, reducer_1.createCacheReducer)(actions, cache.typenames, Object.keys(cache.queries), cache.options),
         actions,
         selectors: {
-            /** Select all entities from the state. */
-            entitiesSelector,
-            /** Select all entities of provided typename. */
-            entitiesByTypenameSelector: (typename) => {
-                return enitityMapSelectorByTypename[typename];
+            /** Selects query state. */
+            selectQueryState,
+            /** Selects query latest result. */
+            selectQueryResult: (state, query, cacheKey) => {
+                var _a;
+                return (_a = selectQueryState(state, query, cacheKey)) === null || _a === void 0 ? void 0 : _a.result;
+            },
+            /** Selects query loading state. */
+            selectQueryLoading: (state, query, cacheKey) => {
+                var _a;
+                return (_a = selectQueryState(state, query, cacheKey)) === null || _a === void 0 ? void 0 : _a.loading;
+            },
+            /** Selects query latest error. */
+            selectQueryError: (state, query, cacheKey) => {
+                var _a;
+                return (_a = selectQueryState(state, query, cacheKey)) === null || _a === void 0 ? void 0 : _a.error;
+            },
+            /** Selects mutation state. */
+            selectMutationState,
+            /** Selects mutation latest result. */
+            selectMutationResult: (state, mutation) => {
+                return selectMutationState(state, mutation).result;
+            },
+            /** Selects mutation loading state. */
+            selectMutationLoading: (state, mutation) => {
+                return selectMutationState(state, mutation).loading;
+            },
+            /** Selects mutation latest error. */
+            selectMutationError: (state, mutation) => {
+                return selectMutationState(state, mutation).error;
+            },
+            /** Selects entity by id and typename. */
+            selectEntityById: (state, id, typename) => {
+                id == null ? undefined : cache.cacheStateSelector(state).entities[typename][id];
+            },
+            /** Selects all entities. */
+            selectEntities: (state) => {
+                return cache.cacheStateSelector(state).entities;
+            },
+            /** Selects all entities of provided typename. */
+            selectEntitiesByTypename: (state, typename) => {
+                return cache.cacheStateSelector(state).entities[typename];
             },
         },
         hooks: {
-            /** Returns client object with query function */
+            /** Returns client object with query and mutate functions. */
             useClient: () => {
                 const store = (0, react_redux_1.useStore)();
                 return (0, react_1.useMemo)(() => {
@@ -62,10 +101,10 @@ const createCache = (partialCache) => {
                             const getCacheKey = (_a = cache.queries[queryKey].getCacheKey) !== null && _a !== void 0 ? _a : (utilsAndConstants_1.defaultGetCacheKey);
                             // @ts-expect-error fix later
                             const cacheKey = getCacheKey(params);
-                            return (0, query_1.query)('query', true, store, cache, actions, queryKey, cacheKey, params);
+                            return (0, query_1.query)('query', store, cache, actions, queryKey, cacheKey, params);
                         },
                         mutate: (options) => {
-                            return (0, mutate_1.mutate)('mutate', true, store, cache, actions, options.mutation, options.params, abortControllers);
+                            return (0, mutate_1.mutate)('mutate', store, cache, actions, options.mutation, options.params, abortControllers);
                         },
                     };
                     return client;
@@ -75,14 +114,12 @@ const createCache = (partialCache) => {
             useQuery: (options) => (0, useQuery_1.useQuery)(cache, actions, options),
             /** Subscribes to provided mutation state and provides mutate function. */
             useMutation: (options) => (0, useMutation_1.useMutation)(cache, actions, options, abortControllers),
-            /** Selects entity by id and subscribes to the changes. */
-            useSelectEntityById: (id, typename) => {
-                return (0, react_redux_1.useSelector)((state) => 
-                // TODO move to selectors?
-                id == null ? undefined : cache.cacheStateSelector(state).entities[typename][id]);
-            },
         },
         utils: {
+            /**
+             * Apply changes to the entities map.
+             * @return `undefined` if nothing to change, otherwise new entities map with applied changes.
+             */
             applyEntityChanges: (entities, changes) => {
                 return (0, utilsAndConstants_1.applyEntityChanges)(entities, changes, cache.options);
             },

package/dist/index.js

@@ -23,15 +23,11 @@ Object.defineProperty(exports, "defaultGetCacheKey", { enumerable: true, get: fu
 Object.defineProperty(exports, "defaultQueryMutationState", { enumerable: true, get: function () { return utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE; } });
 // Backlog
 // ! high
-// screenshot of redux state to README
-// optimistic response
-// cover with tests
+// add not optimized not normalized example, and not normalized state example to readme
 // try use skip for refreshing strategy?
-// add example without normalization
-// make query key / cache key difference more clear in the docs
-// support multiple caches = reducers
+// optimistic response
+// make query key / cache key difference more clear in the docs, and/or rename queryKey -> query
 // ! medium
-// make named caches to produce named hooks, actions etc (same as slices in RTK)?
 // allow multiple mutation with same keys?
 // type extractors from cache
 // custom useStore
@@ -45,6 +41,7 @@ Object.defineProperty(exports, "defaultQueryMutationState", { enumerable: true,
 // make error type generic
 // don't cache result if resultSelector set? throw error if mergeResult set with resultSelector?
 // ! low
+// access to currently loading queries and mutations?
 // add params to the state?
 // cancellation to queries
 // if mutation & query alrady loading - make options: last, throttle, debounce, parallel?

package/dist/mutate.d.ts

@@ -1,4 +1,4 @@
 import { Store } from 'redux';
 import type { ActionMap } from './createActions';
 import type { Cache, Key, MutationResult, Typenames } from './types';
-export declare const mutate: <N extends string, T extends Typenames, QP, QR, MP, MR, MK extends keyof MP | keyof MR>(logTag: string, returnResult: boolean, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateMutationStateAndEntities }: Pick<ActionMap<N, T, QR, MR>, "updateMutationStateAndEntities">, mutationKey: MK, params: MK extends keyof MP & keyof MR ? MP[MK] : never, abortControllers: WeakMap<Store, Record<Key, AbortController>>) => Promise<void | MutationResult<MK extends keyof MP & keyof MR ? MR[MK] : never>>;
+export declare const mutate: <N extends string, T extends Typenames, QP, QR, MP, MR, MK extends keyof MP | keyof MR>(logTag: string, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateMutationStateAndEntities }: Pick<ActionMap<N, T, QR, MR>, "updateMutationStateAndEntities">, mutationKey: MK, params: MK extends keyof MP & keyof MR ? MP[MK] : never, abortControllers: WeakMap<Store, Record<Key, AbortController>>) => Promise<MutationResult<MK extends keyof MP & keyof MR ? MR[MK] : never>>;

package/dist/mutate.js

@@ -11,7 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mutate = void 0;
 const utilsAndConstants_1 = require("./utilsAndConstants");
-const mutate = (logTag, returnResult, store, cache, { updateMutationStateAndEntities }, mutationKey, params, abortControllers) => __awaiter(void 0, void 0, void 0, function* () {
+const mutate = (logTag, store, cache, { updateMutationStateAndEntities }, mutationKey, params, abortControllers) => __awaiter(void 0, void 0, void 0, function* () {
     let abortControllersOfStore = abortControllers.get(store);
     if (abortControllersOfStore === undefined) {
         abortControllersOfStore = {};
@@ -55,7 +55,7 @@ const mutate = (logTag, returnResult, store, cache, { updateMutationStateAndEnti
             aborted: abortController.signal.aborted,
         });
     if (abortController.signal.aborted) {
-        return returnResult ? { aborted: true } : undefined;
+        return ABORTED_RESULT;
     }
     delete abortControllersOfStore[mutationKey];
     if (error) {
@@ -73,8 +73,9 @@ const mutate = (logTag, returnResult, store, cache, { updateMutationStateAndEnti
             result: response.result,
         }, response));
         // @ts-expect-error fix later
-        return returnResult ? { result: response.result } : undefined;
+        return { result: response.result };
     }
     throw new Error(`${logTag}: both error and response are not defined`);
 });
 exports.mutate = mutate;
+const ABORTED_RESULT = Object.freeze({ aborted: true });

package/dist/query.d.ts

@@ -1,4 +1,4 @@
 import { Store } from 'redux';
 import type { ActionMap } from './createActions';
 import type { Cache, Key, QueryResult, Typenames } from './types';
-export declare const query: <N extends string, T extends Typenames, QP, QR, MP, MR, QK extends keyof QP | keyof QR>(logTag: string, returnResult: boolean, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateQueryStateAndEntities }: Pick<ActionMap<N, T, QR, MR>, "updateQueryStateAndEntities">, queryKey: QK, cacheKey: Key, params: QK extends keyof QP & keyof QR ? QP[QK] : never) => Promise<void | QueryResult<QK extends keyof QP & keyof QR ? QR[QK] : never>>;
+export declare const query: <N extends string, T extends Typenames, QP, QR, MP, MR, QK extends keyof QP | keyof QR>(logTag: string, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateQueryStateAndEntities }: Pick<ActionMap<N, T, QR, MR>, "updateQueryStateAndEntities">, queryKey: QK, cacheKey: Key, params: QK extends keyof QP & keyof QR ? QP[QK] : never) => Promise<QueryResult<QK extends keyof QP & keyof QR ? QR[QK] : never>>;

package/dist/query.js

@@ -11,7 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.query = void 0;
 const utilsAndConstants_1 = require("./utilsAndConstants");
-const query = (logTag, returnResult, store, cache, { updateQueryStateAndEntities }, queryKey, cacheKey, params) => __awaiter(void 0, void 0, void 0, function* () {
+const query = (logTag, store, cache, { updateQueryStateAndEntities }, queryKey, cacheKey, params) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const logsEnabled = cache.options.logsEnabled;
     const cacheStateSelector = cache.cacheStateSelector;
@@ -25,7 +25,7 @@ const query = (logTag, returnResult, store, cache, { updateQueryStateAndEntities
                 params,
                 cacheKey,
             });
-        return returnResult ? { cancelled: true } : undefined;
+        return CANCELLED_RESULT;
     }
     store.dispatch(updateQueryStateAndEntities(queryKey, cacheKey, {
         loading: true,
@@ -43,7 +43,7 @@ const query = (logTag, returnResult, store, cache, { updateQueryStateAndEntities
             error: error,
             loading: false,
         }));
-        return returnResult ? { error } : undefined;
+        return { error };
     }
     const newState = {
         error: undefined,
@@ -53,19 +53,18 @@ const query = (logTag, returnResult, store, cache, { updateQueryStateAndEntities
             : mergeResults
                 ? mergeResults(
                 // @ts-expect-error fix later
-                (_a = cacheStateSelector(store.getState()).queries[queryKey][cacheKey]) === null || _a === void 0 ? void 0 : _a.result, response, params)
+                (_a = cacheStateSelector(store.getState()).queries[queryKey][cacheKey]) === null || _a === void 0 ? void 0 : _a.result, response, params, store)
                 : response.result,
     };
     store.dispatch(updateQueryStateAndEntities(queryKey, cacheKey, newState, response));
-    // @ts-expect-error fix types
-    return returnResult
-        ? {
-            result: cacheResultSelector
-                ? cacheResultSelector(cacheStateSelector(store.getState()), 
-                // @ts-expect-error fix types
-                params)
-                : newState === null || newState === void 0 ? void 0 : newState.result,
-        }
-        : undefined;
+    return {
+        // @ts-expect-error fix types
+        result: cacheResultSelector
+            ? cacheResultSelector(cacheStateSelector(store.getState()), 
+            // @ts-expect-error fix types
+            params)
+            : newState === null || newState === void 0 ? void 0 : newState.result,
+    };
 });
 exports.query = query;
+const CANCELLED_RESULT = Object.freeze({ cancelled: true });

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { Store } from 'redux';
 import type { ReduxCacheState } from './reducer';
 export type Key = string | number | symbol;
 export type Dict<T> = Record<Key, T>;
@@ -73,8 +74,8 @@ export type QueryInfo<T extends Typenames, P, R, S> = {
      * Needed when query result may already be in the cache, e.g. for single entity query by id.
      * */
     resultSelector?: (state: S, params: P) => R | undefined;
-    /** Merges results before saving to the store. */
-    mergeResults?: (oldResult: R | undefined, response: QueryResponse<T, R>, params: P | undefined) => R;
+    /** Merges results before saving to the store. Default implementation is using the latest result. */
+    mergeResults?: (oldResult: R | undefined, response: QueryResponse<T, R>, params: P | undefined, store: Store) => R;
     /**
      * Cache key is used for storing the query state and for performing a fetch when it changes. Queries with the same cache key share their state.
      * Default implementation uses `JSON.stringify` or `String()` depending on type.
@@ -86,7 +87,7 @@ export type UseQueryOptions<T extends Typenames, QP, QR, MR, QK extends keyof (Q
     query: QK;
     params: QK extends keyof (QP | QR) ? QP[QK] : never;
     skip?: boolean;
-} & Pick<QK extends keyof (QP | QR) ? QueryInfo<T, QP[QK], QR[QK], ReduxCacheState<T, QR, MR>> : never, 'cachePolicy' | 'mergeResults' | 'getCacheKey'>;
+} & Pick<QK extends keyof (QP | QR) ? QueryInfo<T, QP[QK], QR[QK], ReduxCacheState<T, QR, MR>> : never, 'cachePolicy'>;
 /**
  * @param cache-first for each params key fetch is not called if cache exists.
  * @param cache-and-fetch for each params key result is taken from cache and fetch is called.
@@ -120,7 +121,7 @@ export type MutationResult<R> = {
 export type QueryMutationState<R> = {
     /** `true` when query or mutation is currently in progress. */
     loading: boolean;
-    /** Result of the latest successfull query response. */
+    /** Result of the latest successfull response. */
     result?: R;
     /** Error of the latest response. */
     error?: Error;

package/dist/useMutation.d.ts

@@ -3,4 +3,4 @@ import { ActionMap } from './createActions';
 import { Cache, Key, QueryMutationState, Typenames } from './types';
 export declare const useMutation: <N extends string, T extends Typenames, MP, MR, MK extends keyof MP | keyof MR>(cache: Cache<N, T, unknown, unknown, MP, MR>, actions: Pick<ActionMap<N, T, unknown, MR>, "updateMutationStateAndEntities">, options: {
     mutation: MK;
-}, abortControllers: WeakMap<Store, Record<Key, AbortController>>) => readonly [(params: MK extends keyof MP & keyof MR ? MP[MK] : never) => Promise<void>, QueryMutationState<MK extends keyof MP & keyof MR ? MP[MK] : never>, () => boolean];
+}, abortControllers: WeakMap<Store, Record<Key, AbortController>>) => readonly [(params: MK extends keyof MP & keyof MR ? MP[MK] : never) => Promise<import("./types").MutationResult<MK extends infer T_1 ? T_1 extends MK ? T_1 extends keyof MP & keyof MR ? MR[T_1] : never : never : never>>, QueryMutationState<MK extends keyof MP & keyof MR ? MP[MK] : never>, () => boolean];

package/dist/useMutation.js

@@ -32,7 +32,7 @@ const useMutation = (cache, actions, options, abortControllers) => {
             },
             // mutate
             (params) => __awaiter(void 0, void 0, void 0, function* () {
-                yield (0, mutate_1.mutate)('useMutation.mutate', false, store, cache, actions, mutationKey, params, abortControllers);
+                return yield (0, mutate_1.mutate)('useMutation.mutate', store, cache, actions, mutationKey, params, abortControllers);
             }),
             // abort
             () => {

package/dist/useQuery.d.ts

@@ -1,3 +1,3 @@
 import { ActionMap } from './createActions';
 import { Cache, QueryMutationState, Typenames, UseQueryOptions } from './types';
-export declare const useQuery: <N extends string, T extends Typenames, QP, QR, MP, MR, QK extends keyof QP | keyof QR>(cache: Cache<N, T, QP, QR, MP, MR>, actions: Pick<ActionMap<N, T, QR, MR>, "updateQueryStateAndEntities">, options: UseQueryOptions<T, QP, QR, MR, QK>) => readonly [QueryMutationState<QK extends keyof QP & keyof QR ? QR[QK] : never>, () => Promise<void>];
+export declare const useQuery: <N extends string, T extends Typenames, QP, QR, MP, MR, QK extends keyof QP | keyof QR>(cache: Cache<N, T, QP, QR, MP, MR>, actions: Pick<ActionMap<N, T, QR, MR>, "updateQueryStateAndEntities">, options: UseQueryOptions<T, QP, QR, MR, QK>) => readonly [QueryMutationState<QK extends keyof QP & keyof QR ? QR[QK] : never>, () => Promise<import("./types").QueryResult<QK extends infer T_1 ? T_1 extends QK ? T_1 extends keyof QP & keyof QR ? QR[T_1] : never : never : never>>];

package/dist/useQuery.js

@@ -16,8 +16,9 @@ const query_1 = require("./query");
 const utilsAndConstants_1 = require("./utilsAndConstants");
 const useQuery = (cache, actions, options) => {
     var _a, _b, _c;
-    const { query: queryKey, skip, params, cachePolicy = (_a = cache.queries[queryKey].cachePolicy) !== null && _a !== void 0 ? _a : 'cache-first', getCacheKey = (_b = cache.queries[queryKey].getCacheKey) !== null && _b !== void 0 ? _b : (utilsAndConstants_1.defaultGetCacheKey), } = options;
+    const { query: queryKey, skip, params, cachePolicy = (_a = cache.queries[queryKey].cachePolicy) !== null && _a !== void 0 ? _a : 'cache-first', } = options;
     const logsEnabled = cache.options.logsEnabled;
+    const getCacheKey = (_b = cache.queries[queryKey].getCacheKey) !== null && _b !== void 0 ? _b : (utilsAndConstants_1.defaultGetCacheKey);
     const cacheResultSelector = cache.queries[queryKey].resultSelector;
     const cacheStateSelector = cache.cacheStateSelector;
     const store = (0, react_redux_1.useStore)();
@@ -34,7 +35,7 @@ const useQuery = (cache, actions, options) => {
     const resultFromSelector = (resultSelector && (0, react_redux_1.useSelector)(resultSelector));
     const hasResultFromSelector = resultFromSelector !== undefined;
     const fetch = (0, react_1.useCallback)(() => __awaiter(void 0, void 0, void 0, function* () {
-        yield (0, query_1.query)('useQuery.fetch', false, store, cache, actions, queryKey, cacheKey, params);
+        return yield (0, query_1.query)('useQuery.fetch', store, cache, actions, queryKey, cacheKey, params);
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }), [store, queryKey, cacheKey]);
     const queryStateFromSelector = (_c = (0, react_redux_1.useSelector)((state) => {

package/dist/utilsAndConstants.d.ts

@@ -7,8 +7,4 @@ export declare const DEFAULT_QUERY_MUTATION_STATE: {
 };
 export declare const defaultGetCacheKey: <P = unknown>(params: P) => Key;
 export declare const log: (tag: string, data?: unknown) => void;
-/**
- * Apply changes to the entities map.
- * @return `undefined` if nothing to change, otherwise new entities map with applied changes.
- */
 export declare const applyEntityChanges: <T extends Typenames>(entities: EntitiesMap<T>, changes: EntityChanges<T>, options: CacheOptions) => EntitiesMap<T> | undefined;

package/dist/utilsAndConstants.js

@@ -28,10 +28,6 @@ const log = (tag, data) => {
     console.debug(`@${exports.PACKAGE_SHORT_NAME} [${tag}]`, data);
 };
 exports.log = log;
-/**
- * Apply changes to the entities map.
- * @return `undefined` if nothing to change, otherwise new entities map with applied changes.
- */
 const applyEntityChanges = (entities, changes, options) => {
     var _a, _b, _c;
     if (options.validateFunctionArguments) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "react-redux-cache",
   "author": "Alexander Danilov",
   "license": "MIT",
-  "version": "0.2.0",
+  "version": "0.4.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",