react-redux-cache 0.16.1-rc.0 → 0.17.0

package/README.md

@@ -9,11 +9,13 @@
 
 # react-redux-cache (RRC)
 
-**Powerful**, **performant** 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 **doesn't use Immer** ([perf issue](https://github.com/reduxjs/redux-toolkit/issues/4793)). Built on top of `Redux`, covered with tests, fully typed and written on Typescript.
+### Supports both `Redux` and `Zustand` (check /example)
+
+**Powerful**, **performant** 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 **doesn't use Immer** ([perf issue](https://github.com/reduxjs/redux-toolkit/issues/4793)). 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**.
 
-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.
+Can be considered as `ApolloClient` for protocols other than `GraphQL`, but with **full control** over its storage - redux or zustand store, with ability to write custom selectors, actions and reducers to manage cached state.
 
 Examples of states, generated by cache reducer from `/example` project:
 <details>
@@ -46,7 +48,7 @@ Examples of states, generated by cache reducer from `/example` project:
       },
       getUsers: {
         // example of paginated state under custom cache key
-        "all-pages": {
+        "feed": {
           result: {items: [0,1,2], page: 1},
           params: {page: 1}
         }
@@ -84,7 +86,7 @@ Examples of states, generated by cache reducer from `/example` project:
       },
       getUsers: {
         // example of paginated state under custom cache key
-        "all-pages": {
+        "feed": {
           result: {
             items: [
               {id: 0, bank: {id: "0", name: "Bank 0"}, name: "User 0 *"},
@@ -130,23 +132,28 @@ Examples of states, generated by cache reducer from `/example` project:
 `react` is a peer dependency.
 
 `react-redux` and `fast-deep-equal` are optional peer dependencies:
-  - `react-redux` required when `storeHooks` is not provided when creating cache.
+  - `react-redux` required when `storeHooks` is not provided when creating cache. Not needed for Zustand.
   - `fast-deep-equal` required if `deepComparisonEnabled` cache option is enabled (default is true).
 
 ```sh
 # required
-npm add react-redux-cache react
+npm i react-redux-cache react
 
 # without react-redux
-npm add react-redux-cache react fast-deep-equal
+npm i react-redux-cache react fast-deep-equal
 
 # all required and optional peers
-npm add react-redux-cache react react-redux fast-deep-equal
+npm i react-redux-cache react react-redux fast-deep-equal
 ```
+
 ### Initialization
 The only function that needs to be imported is either `withTypenames`, which is needed for normalization, or directly `createCache` if it is not needed. `createCache` creates fully typed reducer, hooks, actions, selectors and utils to be used in the app. You can create as many caches as needed, but keep in mind that normalization is not shared between them.
 All queries and mutations should be passed while initializing the cache for proper typing.
+
 #### cache.ts
+
+> Zustand requires additional option - `storeHooks`.
+
 ```typescript
 // Mapping of all typenames to their entity types, which is needed for proper normalization typing.
 // Not needed if normalization is not used.
@@ -177,6 +184,10 @@ export const {
     updateUser: { mutation: updateUser },
     removeUser: { mutation: removeUser },
   },
+
+  // Required for Zustand. Just an empty object can be passed during initialization, and hooks can be set later (see `store.ts` section).
+  // Can be also used for Redux if working with multiple stores.
+  storeHooks: {},
 })
 ```
 
@@ -194,6 +205,8 @@ type EntityChanges<T extends Typenames> = {
 ```
 
 #### store.ts
+
+Redux:
 ```typescript
 // Create store as usual, passing the new cache reducer under the name of the cache.
 // If some other redux structure is needed, provide custom cacheStateSelector when creating cache.
@@ -204,6 +217,24 @@ const store = configureStore({
   }
 })
 ```
+
+Zustand:
+```typescript
+type State = {[cache.name]: ReturnType<typeof reducer>}
+type Actions = {dispatch: (action: Parameters<typeof reducer>[1]) => void}
+
+const initialState = getInitialState()
+
+export const useStore = create<State & Actions>((set, get) => ({
+  ...initialState,
+  dispatch: (action) => set({[cache.name]: reducer(get()[cache.name], action)}),
+}))
+
+const store = {dispatch: useStore.getState().dispatch, getState: useStore.getState}
+cache.storeHooks.useStore = () => store
+cache.storeHooks.useSelector = useStore
+```
+
 #### api.ts
 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.
@@ -239,7 +270,7 @@ export const removeUser = (async (id, _, abortSignal) => {
 
 ### Usage
 
-Please check `example/` folder (`npm run example` to run).
+Please check `example/` folder (`npm run example` to run). There are examples for both Redux and Zustand.
 
 #### UserScreen.tsx
 ```typescript
@@ -400,7 +431,7 @@ Here is an example of `getUsers` query configuration with pagination support. Yo
   queries: {
     getUsers: {
       query: getUsers,
-      getCacheKey: () => 'all-pages', // 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
@@ -408,7 +439,7 @@ Here is an example of `getUsers` query configuration with pagination support. Yo
         if (newResult.page === oldResult.page + 1) {
           return {
             ...newResult,
-            items: [...oldResult.items, ...newResult.items],
+            items: oldResult.items.concat(newResult.items),
           }
         }
         return oldResult

package/dist/createCache.d.ts

@@ -175,6 +175,8 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
             useSelectEntityById: <TN extends keyof T>(id: Key | null | undefined, typename: TN) => T[TN] | undefined;
         };
         utils: {
+            /** Generates the initial state by calling a reducer. Not needed for redux — it already generates it the same way when creating the store. */
+            getInitialState: () => import("./types").CacheState<T, QP, QR, MP, MR>;
             /** Apply changes to the entities map.
              * @returns `undefined` if nothing to change, otherwise new `EntitiesMap<T>` with applied changes. */
             applyEntityChanges: (entities: Parameters<typeof applyEntityChanges<T>>[0], changes: Parameters<typeof applyEntityChanges<T>>[1]) => import("./types").EntitiesMap<T> | undefined;
@@ -357,6 +359,8 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(partialCach
         useSelectEntityById: <TN extends string>(id: Key | null | undefined, typename: TN) => object | undefined;
     };
     utils: {
+        /** Generates the initial state by calling a reducer. Not needed for redux — it already generates it the same way when creating the store. */
+        getInitialState: () => import("./types").CacheState<Typenames, QP, QR, MP, MR>;
         /** Apply changes to the entities map.
          * @returns `undefined` if nothing to change, otherwise new `EntitiesMap<T>` with applied changes. */
         applyEntityChanges: (entities: import("./types").EntitiesMap<Typenames>, changes: import("./types").EntityChanges<Typenames>) => import("./types").EntitiesMap<Typenames> | undefined;

package/dist/createCache.js

@@ -58,11 +58,13 @@ const withTypenames = () => {
             // actions
             const actions = (0, createActions_1.createActions)(cache.name);
             const { updateQueryStateAndEntities, updateMutationStateAndEntities, mergeEntityChanges, invalidateQuery, clearQueryState, clearMutationState, clearCache, } = actions;
+            // reducer
+            const reducer = (0, createCacheReducer_1.createCacheReducer)(actions, Object.keys(cache.queries), cache.options);
             return {
                 /** Keeps all options, passed while creating the cache. */
                 cache,
                 /** Reducer of the cache, should be added to redux store. */
-                reducer: (0, createCacheReducer_1.createCacheReducer)(actions, Object.keys(cache.queries), cache.options),
+                reducer,
                 actions: {
                     /** Updates query state, and optionally merges entity changes in a single action. */
                     updateQueryStateAndEntities,
@@ -147,6 +149,11 @@ const withTypenames = () => {
                     },
                 },
                 utils: {
+                    /** Generates the initial state by calling a reducer. Not needed for redux — it already generates it the same way when creating the store. */
+                    getInitialState: () => {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        return reducer(undefined, utilsAndConstants_1.EMPTY_OBJECT);
+                    },
                     /** Apply changes to the entities map.
                      * @returns `undefined` if nothing to change, otherwise new `EntitiesMap<T>` with applied changes. */
                     applyEntityChanges: (entities, changes) => {

package/dist/types.d.ts

@@ -119,6 +119,11 @@ params: P,
 store: Store) => Promise<QueryResponse<R>>;
 export type NormalizedQuery<T extends Typenames = Typenames, P = unknown, R = unknown> = (...args: Parameters<Query<P, R>>) => Promise<NormalizedQueryResponse<T, R>>;
 export type QueryState<P, R> = MutationState<P, R> & {
+    /**
+     * Timestamp in milliseconds, after which state is considered expired.
+     * Hooks may refetch the query again when component mounts, cache key or skip option change, depending on the fetch policy.
+     * Client query calls also start making fetch if onlyIfExpired argument is truthy.
+     * */
     expiresAt?: number;
 };
 export type UseQueryOptions<N extends string, T extends Typenames, QK extends keyof (QP & QR), QP, QR, MP, MR> = {

package/package.json

@@ -2,14 +2,15 @@
   "name": "react-redux-cache",
   "author": "Alexander Danilov",
   "license": "MIT",
-  "version": "0.16.1-rc.0",
-  "description": "Powerful data fetching and caching library that supports normalization, built on top of redux",
+  "version": "0.17.0",
+  "description": "Powerful data fetching and caching library for Redux and Zustand that supports normalization.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "example": "(cd example && yarn && yarn start)",
+    "example": "(cd example && yarn && yarn dev)",
     "clean": "rm -rf dist",
     "lint": "yarn eslint src",
+    "lint-fix": "yarn eslint --fix src",
     "build": "yarn clean && yarn lint && tsc && rm -rf dist/testing && rm -rf dist/__tests__",
     "test": "node node_modules/jest/bin/jest.js",
     "preminor-rc": "yarn build && npm version preminor --preid rc",
@@ -65,6 +66,7 @@
   "keywords": [
     "react",
     "redux",
+    "zustand",
     "cache",
     "query",
     "normalization"