react-redux-cache 0.3.0 → 0.4.1

package/README.md

@@ -1,22 +1,23 @@
-### 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.
 
-Here is example of redux state, generated by cache reducer from `/example` project:
+Example of **normalized** redux state, generated by cache reducer from `/example` project:
 ```js
-const state = {
+{
   entities: {
     // each typename has its own map of entities, stored by id
     users: {
@@ -50,6 +51,38 @@ const state = {
 }
 ```
 
+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
 
@@ -80,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, QueryMutationState, 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,10 +6,11 @@ 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>;
+        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: {
@@ -36,7 +37,7 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         type: `@rrc/${N}/clearMutationState`;
         mutationKeys: (keyof MR)[];
     }) => {
-        entities: EntitiesMap<T>;
+        entities: import("./types").EntitiesMap<T>;
         queries: { [QK in keyof QR]: import("./types").Dict<QueryMutationState<QR[QK]>>; };
         mutations: { [MK in keyof MR]: QueryMutationState<MR[MK]>; };
     };
@@ -86,24 +87,34 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
                 mutationKeys: K_3[];
             };
             type: `@rrc/${N}/clearMutationState`;
-        };
+        }; /** Selects query latest result. */
     };
     selectors: {
+        /** 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;
-        /** 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 entity by id and typename. */
+        selectEntityById: <TN extends keyof T>(state: unknown, id: Key | null | undefined, typename: TN) => T[TN] | undefined;
+        /** 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_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: {
@@ -117,10 +128,12 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         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];
-        /** 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;
     };
     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,13 +29,6 @@ const createCache = (partialCache) => {
     partialCache.abortControllers = abortControllers;
     const cache = partialCache;
     // make selectors
-    const entitiesSelector = (state) => {
-        return cache.cacheStateSelector(state).entities;
-    };
-    const enitityMapSelectorByTypename = Object.keys(partialCache.typenames).reduce((result, x) => {
-        result[x] = (state) => cache.cacheStateSelector(state).entities[x];
-        return result;
-    }, {});
     const selectQueryState = (state, query, cacheKey) => {
         // @ts-expect-error fix later
         return cache.cacheStateSelector(state).queries[query][cacheKey];
@@ -46,43 +39,58 @@ const createCache = (partialCache) => {
     };
     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: {
+            /** 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;
             },
-            /** Select all entities from the state. */
-            entitiesSelector,
-            /** Select all entities of provided typename. */
-            entitiesByTypenameSelector: (typename) => {
-                return enitityMapSelectorByTypename[typename];
+            /** Selects entity by id and typename. */
+            selectEntityById: (state, id, typename) => {
+                return 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)(() => {
@@ -106,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,12 +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
-// add example without normalization
+// add not optimized not normalized example, and not normalized state example to readme
 // try use skip for refreshing strategy?
 // optimistic response
-// make query key / cache key difference more clear in the docs, or remove queryKey at all?
+// 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
@@ -42,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/types.d.ts

@@ -121,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/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.3.0",
+  "version": "0.4.1",
   "description": "Powerful data fetching and caching library that supports normalization, built on top of redux",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",