react-redux-cache 0.6.1 → 0.7.0-rc.1

package/README.md

@@ -41,7 +41,7 @@ Examples of states, generated by cache reducer from `/example` project:
     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, params: 2},
+        "2": {loading: false, result: 2, params: 2, expiresAt: 1727217298025},
         "3": {loading: true, params: 3}
       },
       getUsers: {
@@ -79,9 +79,9 @@ Examples of states, generated by cache reducer from `/example` project:
       getUser: {
         "2": {
           loading: false,
-          error: undefined,
           result: {id: 2, bank: {id: "2", name: "Bank 2"}, name: "User 2"},
-          params: 2
+          params: 2,
+          expiresAt: 1727217298025
         },
         "3": {loading: true, params: 3}
       },
@@ -122,6 +122,8 @@ Examples of states, generated by cache reducer from `/example` project:
    - [api.ts](https://github.com/gentlee/react-redux-cache#apits) 
  - [Usage](https://github.com/gentlee/react-redux-cache#usage)
  - [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 cache policy](https://github.com/gentlee/react-redux-cache#extended-cache-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)
@@ -134,7 +136,7 @@ Examples of states, generated by cache reducer from `/example` project:
 
 `fast-deep-equal` is an optional peer dependency if `deepComparisonEnabled` cache option is enabled (default is true).
 ```sh
-npm add react-redux-cache react redux react-redux
+npm add react-redux-cache react redux react-redux fast-deep-equal
 ```
 ### Initialization
 The only function that needs to be imported is `createCache`, which 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.
@@ -156,7 +158,12 @@ export const {
   },
   queries: {
     getUsers: { query: getUsers },
-    getUser: { query: getUser },
+    getUser: {
+      query: getUser,
+      // For each query `secondsToLive` option can be set, which is used to set expiration date of a cached result when query response is received.
+      // After expiration query result is considered invalidated and will be refetched on the next useQuery mount.
+      secondsToLive: 5 * 60 // Here cached result is valid for 5 minutes.
+    },
   },
   mutations: {
     updateUser: { mutation: updateUser },
@@ -201,37 +208,32 @@ Perfect implementation is when the backend already returns normalized data.
 
 // Example of query with normalization (recommended)
 
-export const getUser = async (id: number) => {
-  const result = await ...
-  
-  const normalizedResult: {
-     // result is id of the user
-    result: number
-    // entities contain all normalized objects 
-    entities: {
-      users: Record<number, User>
-      banks: Record<string, Bank>
-    }
-  } = normalize(result, getUserSchema)
+export const getUser = async (id) => {
+  // Result can be get by any way - fetch, axios etc, even with database connection.
+  // There is no limitation here.
+  const response = await ...
 
-  return normalizedResult
-}
+  // In this example normalizr package is used, but it is not necessary.
+  return normalize(response, getUserSchema)
+  // satisfies keyword is used here for proper typing of params and returned value.
+} satisfies Query<number, CacheTypenames>
 
-// Example of query without normalization (not recommended)
+// Example of query without normalization (not recommended), with selecting access token from the store
 
-export const getBank = (id: string) => {
+export const getBank = (id, {getState}) => {
+  const token = tokenSelector(getState())
   const result: Bank = ...
   return {result} // result is bank object, no entities passed
-}
+} satisfies Query<string>
 
 // Example of mutation with normalization
 
-export const removeUser = async (id: number) => {
+export const removeUser = async (id, _, abortSignal) => {
   await ...
   return {
     remove: { users: [id] },
   }
-}
+} satisfies Query<number, CacheTypenames>
 ```
 
 ### Usage
@@ -243,7 +245,7 @@ Please check `example/` folder (`npm run example` to run).
 export const UserScreen = () => {
   const {id} = useParams()
 
-  // useQuery connects to redux state and if user with that id is already cached, fetch won't happen (with default cachePolicy 'cache-first')
+  // useQuery connects to redux state and if user with that id is already cached, fetch won't happen (with default cachePolicy 'cache-first').
   // Infers all types from created cache, telling here that params and result are of type `number`.
   const [{result: userId, loading, error}] = useQuery({
     query: 'getUser',
@@ -254,7 +256,7 @@ export const UserScreen = () => {
     mutation: 'updateUser',
   })
 
-  // This selector is used for denormalization and returns entities with proper types - User and Bank
+  // This selector returns entities with proper types - User and Bank
   const user = useSelectEntityById(userId, 'users')
   const bank = useSelectEntityById(user?.bankId, 'banks')
 
@@ -268,9 +270,43 @@ export const UserScreen = () => {
 
 ### Advanced
 
+#### Error handling
+
+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) => {
+  const {httpError, response} = ...
+  return {
+    result: {
+      // Error is a part of the result, containing e.g. map of not valid fields and threir error messages
+      httpError,
+      // Bank still can be returned from the backend with error e.g. when only some of fields were udpated
+      bank: response?.bank
+    }
+  }
+} satisfies Mutation<Partial<Bank>>
+
+```
+
+#### Invalidation
+
+`cache-first` cache policy (default) skips fetching on component mount if result is already cached, but we can invalidate cached query results using `invalidateQuery` action to make it run again on a next mount. Also, we can return this action as a part of query or mutation response, to perform it in one batch update.
+
+```typescript
+const updateUser = (user: Partial<User>) => {
+  const response = ...
+  return {
+    result: response.result,
+    expiresAt: Date.now() + 10000, // optional, expiration time of current response
+    actions: [invalidateQuery([{ key: 'getUsers' }])] // optional, this action sets `expiresAt` field of `getUsers` states to Date.now()
+  }
+}
+```
+
 #### Extended cache policy
 
-`cache-first` cache policy skips fetching if result is already cached, but sometimes it can't determine that we already have result in some other's query result or in normalized entities cache. In that case we can use `skip` parameter of a query:
+`cache-first` cache policy (default) skips fetching on component mount if result is already cached, but sometimes it can't determine that we already have result in some other's query result or in normalized entities cache. In that case we can use `skip` parameter of a query:
 
 ```typescript
 export const UserScreen = () => {
@@ -294,7 +330,7 @@ We can additionally check that entity is full or "fresh" enough:
 skip: !!user && isFullUser(user)
 ```
 
-Another approach is to set `skip: true` and manually run `fetch` when needed:
+Another approach is to set `skip: true` and manually run `fetch`. `onlyIfExpired` option can be also used:
 
 ```typescript
 export const UserScreen = () => {
@@ -308,7 +344,7 @@ export const UserScreen = () => {
 
   useEffect(() => {
     if (screenIsVisible) {
-      fetchUser()
+      fetchUser({ onlyIfExpired: true }) // expiration happens if expiresAt was set before e.g. by secondsToLive option or invalidateQuery action. If result is not cached yet, it is also considered as expired.
     }
   }, [screenIsVisible])
 
@@ -439,4 +475,4 @@ As example, can be overriden when implementing pagination.
 
 **Queries:** Queries are throttled: query with the same cache key (generated from params by default) is cancelled if already running.
 
-**Mutations:** Mutations are debounced: previous similar mutation is aborted if it was running when the new one started. Second argument in mutations is `AbortSignal`, which can be used e.g. for cancelling http requests.
+**Mutations:** Mutations are debounced: previous similar mutation is aborted if it was running when the new one started. Third argument in mutations is `AbortSignal`, which can be used e.g. for cancelling http requests.

package/dist/createActions.d.ts

@@ -1,23 +1,23 @@
-import type { EntityChanges, Key, QueryMutationState, Typenames } from './types';
+import type { EntityChanges, Key, MutationState, QueryState, Typenames } from './types';
 export type ActionMap<N extends string, T extends Typenames, QP, QR, MP, MR> = 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) => {
     /** Updates query state, and optionally merges entity changes in a single action. */
     updateQueryStateAndEntities: {
-        <K extends keyof QP & keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryMutationState<QP[K], QR[K]>> | undefined, entityChanges?: EntityChanges<T> | undefined): {
+        <K extends keyof QP & keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryState<QP[K], QR[K]>> | undefined, entityChanges?: EntityChanges<T> | undefined): {
             type: `@rrc/${N}/updateQueryStateAndEntities`;
             queryKey: K;
             queryCacheKey: Key;
-            state: Partial<QueryMutationState<QP[K], QR[K]>> | undefined;
+            state: Partial<QueryState<QP[K], QR[K]>> | undefined;
             entityChanges: EntityChanges<T> | undefined;
         };
         type: `@rrc/${N}/updateQueryStateAndEntities`;
     };
     /** Updates mutation state, and optionally merges entity changes in a single action. */
     updateMutationStateAndEntities: {
-        <K_1 extends keyof MP & keyof MR>(mutationKey: K_1, state?: Partial<QueryMutationState<MP[K_1], MR[K_1]>> | undefined, entityChanges?: EntityChanges<T> | undefined): {
+        <K_1 extends keyof MP & keyof MR>(mutationKey: K_1, state?: Partial<MutationState<MP[K_1], MR[K_1]>> | undefined, entityChanges?: EntityChanges<T> | undefined): {
             type: `@rrc/${N}/updateMutationStateAndEntities`;
             mutationKey: K_1;
-            state: Partial<QueryMutationState<MP[K_1], MR[K_1]>> | undefined;
+            state: Partial<MutationState<MP[K_1], MR[K_1]>> | undefined;
             entityChanges: EntityChanges<T> | undefined;
         };
         type: `@rrc/${N}/updateMutationStateAndEntities`;
@@ -30,16 +30,42 @@ export declare const createActions: <N extends string, T extends Typenames, QP,
         };
         type: `@rrc/${N}/mergeEntityChanges`;
     };
+    /** Invalidates query states. */
+    invalidateQuery: {
+        <K_2 extends keyof QP & keyof QR>(queries: {
+            /** Query key */
+            key: K_2;
+            /** Query cache key */
+            cacheKey?: Key | undefined;
+            /** Unix timestamp at which query expires. Is set to the query state. @default Date.now() */
+            expiresAt?: number | undefined;
+        }[]): {
+            type: `@rrc/${N}/invalidateQuery`;
+            queries: {
+                /** Query key */
+                key: K_2;
+                /** Query cache key */
+                cacheKey?: Key | undefined;
+                /** Unix timestamp at which query expires. Is set to the query state. @default Date.now() */
+                expiresAt?: number | undefined;
+            }[];
+        };
+        type: `@rrc/${N}/invalidateQuery`;
+    };
     /** 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 QP & keyof QR>(queryKeys: {
-            key: K_2;
+        <K_3 extends keyof QP & keyof QR>(queries: {
+            /** Query key */
+            key: K_3;
+            /** Query cache key */
             cacheKey?: Key | undefined;
         }[]): {
             type: `@rrc/${N}/clearQueryState`;
-            queryKeys: {
-                key: K_2;
+            queries: {
+                /** Query key */
+                key: K_3;
+                /** Query cache key */
                 cacheKey?: Key | undefined;
             }[];
         };
@@ -47,9 +73,9 @@ export declare const createActions: <N extends string, T extends Typenames, QP,
     };
     /** Clear states for provided mutation keys. */
     clearMutationState: {
-        <K_3 extends keyof MP & keyof MR>(mutationKeys: K_3[]): {
+        <K_4 extends keyof MP & keyof MR>(mutationKeys: K_4[]): {
             type: `@rrc/${N}/clearMutationState`;
-            mutationKeys: K_3[];
+            mutationKeys: K_4[];
         };
         type: `@rrc/${N}/clearMutationState`;
     };

package/dist/createActions.js

@@ -27,10 +27,16 @@ const createActions = (name) => {
         changes,
     });
     mergeEntityChanges.type = mergeEntityChangesType;
+    const invalidateQueryType = `${actionPrefix}invalidateQuery`;
+    const invalidateQuery = (queries) => ({
+        type: invalidateQueryType,
+        queries,
+    });
+    invalidateQuery.type = invalidateQueryType;
     const clearQueryStateType = `${actionPrefix}clearQueryState`;
-    const clearQueryState = (queryKeys) => ({
+    const clearQueryState = (queries) => ({
         type: clearQueryStateType,
-        queryKeys,
+        queries,
     });
     clearQueryState.type = clearQueryStateType;
     const clearMutationStateType = `${actionPrefix}clearMutationState`;
@@ -46,6 +52,8 @@ const createActions = (name) => {
         updateMutationStateAndEntities,
         /** Merge EntityChanges to the state. */
         mergeEntityChanges,
+        /** Invalidates query states. */
+        invalidateQuery,
         /** 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,

package/dist/createCache.d.ts

@@ -1,35 +1,42 @@
-import type { Cache, Key, MutationResult, OptionalPartial, QueryMutationState, QueryOptions, QueryResult, Typenames } from './types';
+import type { Cache, Key, MutateOptions, MutationResult, MutationState, OptionalPartial, QueryOptions, QueryResult, QueryState, Typenames } from './types';
 import { useMutation } from './useMutation';
 import { useQuery } from './useQuery';
 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">) => {
+export declare const createCache: <N extends string, T extends Typenames, QP, QR, MP, MR>(partialCache: OptionalPartial<Cache<N, T, QP, QR, MP, MR>, "queries" | "options" | "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: import("./types").EntitiesMap<T>;
-        queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: import("./types").Dict<QueryMutationState<QP[QK], QR[QK]>>; } : never;
-        mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: QueryMutationState<MP[MK], MR[MK]>; } : never;
+        queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: import("./types").Dict<QueryState<QP[QK], QR[QK]> | undefined>; } : never;
+        mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: MutationState<MP[MK], MR[MK]>; } : never;
     } | undefined, action: {
         type: `@rrc/${N}/updateQueryStateAndEntities`;
         queryKey: keyof QP & keyof QR;
         queryCacheKey: Key;
-        state: Partial<QueryMutationState<QP[keyof QP & keyof QR], QR[keyof QP & keyof QR]>> | undefined;
+        state: Partial<QueryState<QP[keyof QP & keyof QR], QR[keyof QP & keyof QR]>> | undefined;
         entityChanges: import("./types").EntityChanges<T> | undefined;
     } | {
         type: `@rrc/${N}/updateMutationStateAndEntities`;
         mutationKey: keyof MP & keyof MR;
-        state: Partial<QueryMutationState<MP[keyof MP & keyof MR], MR[keyof MP & keyof MR]>> | undefined;
+        state: Partial<MutationState<MP[keyof MP & keyof MR], MR[keyof MP & keyof MR]>> | undefined;
         entityChanges: import("./types").EntityChanges<T> | undefined;
     } | {
         type: `@rrc/${N}/mergeEntityChanges`;
         changes: import("./types").EntityChanges<T>;
+    } | {
+        type: `@rrc/${N}/invalidateQuery`;
+        queries: {
+            key: keyof QP & keyof QR;
+            cacheKey?: Key | undefined;
+            expiresAt?: number | undefined;
+        }[];
     } | {
         type: `@rrc/${N}/clearQueryState`;
-        queryKeys: {
+        queries: {
             key: keyof QP & keyof QR;
             cacheKey?: Key | undefined;
         }[];
@@ -38,25 +45,25 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         mutationKeys: (keyof MP & keyof MR)[];
     }) => {
         entities: import("./types").EntitiesMap<T>;
-        queries: QP | QR extends infer T_3 ? { [QK in keyof T_3]: import("./types").Dict<QueryMutationState<QP[QK], QR[QK]>>; } : never;
-        mutations: MP | MR extends infer T_4 ? { [MK in keyof T_4]: QueryMutationState<MP[MK], MR[MK]>; } : never;
+        queries: QP | QR extends infer T_3 ? { [QK in keyof T_3]: import("./types").Dict<QueryState<QP[QK], QR[QK]> | undefined>; } : never;
+        mutations: MP | MR extends infer T_4 ? { [MK in keyof T_4]: MutationState<MP[MK], MR[MK]>; } : never;
     };
     actions: {
         updateQueryStateAndEntities: {
-            <K extends keyof QP & keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryMutationState<QP[K], QR[K]>> | undefined, entityChanges?: import("./types").EntityChanges<T> | undefined): {
+            <K extends keyof QP & keyof QR>(queryKey: K, queryCacheKey: Key, state?: Partial<QueryState<QP[K], QR[K]>> | undefined, entityChanges?: import("./types").EntityChanges<T> | undefined): {
                 type: `@rrc/${N}/updateQueryStateAndEntities`;
                 queryKey: K;
                 queryCacheKey: Key;
-                state: Partial<QueryMutationState<QP[K], QR[K]>> | undefined;
+                state: Partial<QueryState<QP[K], QR[K]>> | undefined;
                 entityChanges: import("./types").EntityChanges<T> | undefined;
             };
             type: `@rrc/${N}/updateQueryStateAndEntities`;
         };
         updateMutationStateAndEntities: {
-            <K_1 extends keyof MP & keyof MR>(mutationKey: K_1, state?: Partial<QueryMutationState<MP[K_1], MR[K_1]>> | undefined, entityChanges?: import("./types").EntityChanges<T> | undefined): {
+            <K_1 extends keyof MP & keyof MR>(mutationKey: K_1, state?: Partial<MutationState<MP[K_1], MR[K_1]>> | undefined, entityChanges?: import("./types").EntityChanges<T> | undefined): {
                 type: `@rrc/${N}/updateMutationStateAndEntities`;
                 mutationKey: K_1;
-                state: Partial<QueryMutationState<MP[K_1], MR[K_1]>> | undefined;
+                state: Partial<MutationState<MP[K_1], MR[K_1]>> | undefined;
                 entityChanges: import("./types").EntityChanges<T> | undefined;
             };
             type: `@rrc/${N}/updateMutationStateAndEntities`;
@@ -68,30 +75,45 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
             };
             type: `@rrc/${N}/mergeEntityChanges`;
         };
-        clearQueryState: {
-            <K_2 extends keyof QP & keyof QR>(queryKeys: {
+        invalidateQuery: {
+            <K_2 extends keyof QP & keyof QR>(queries: {
                 key: K_2;
                 cacheKey?: Key | undefined;
+                expiresAt?: number | undefined;
             }[]): {
-                type: `@rrc/${N}/clearQueryState`;
-                queryKeys: {
+                type: `@rrc/${N}/invalidateQuery`;
+                queries: {
                     key: K_2;
                     cacheKey?: Key | undefined;
+                    expiresAt?: number | undefined;
+                }[];
+            };
+            type: `@rrc/${N}/invalidateQuery`;
+        };
+        clearQueryState: {
+            <K_3 extends keyof QP & keyof QR>(queries: {
+                key: K_3;
+                cacheKey?: Key | undefined;
+            }[]): {
+                type: `@rrc/${N}/clearQueryState`;
+                queries: {
+                    key: K_3;
+                    cacheKey?: Key | undefined;
                 }[];
             };
             type: `@rrc/${N}/clearQueryState`;
         };
         clearMutationState: {
-            <K_3 extends keyof MP & keyof MR>(mutationKeys: K_3[]): {
+            <K_4 extends keyof MP & keyof MR>(mutationKeys: K_4[]): {
                 type: `@rrc/${N}/clearMutationState`;
-                mutationKeys: K_3[];
+                mutationKeys: K_4[];
             };
             type: `@rrc/${N}/clearMutationState`;
         };
     };
     selectors: {
         /** Selects query state. */
-        selectQueryState: <QK_1 extends keyof QP | keyof QR>(state: unknown, query: QK_1, cacheKey: Key) => QueryMutationState<QK_1 extends keyof QP & keyof QR ? QP[QK_1] : never, QK_1 extends keyof QP & keyof QR ? QR[QK_1] : never>;
+        selectQueryState: <QK_1 extends keyof QP | keyof QR>(state: unknown, query: QK_1, cacheKey: Key) => 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. */
         selectQueryResult: <QK_2 extends keyof QP | keyof QR>(state: unknown, query: QK_2, cacheKey: Key) => (QK_2 extends keyof QP & keyof QR ? QR[QK_2] : never) | undefined;
         /** Selects query loading state. */
@@ -100,8 +122,10 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
         selectQueryError: <QK_4 extends keyof QP | keyof QR>(state: unknown, query: QK_4, cacheKey: Key) => Error | undefined;
         /** Selects query latest params. */
         selectQueryParams: <QK_5 extends keyof QP | keyof QR>(state: unknown, query: QK_5, cacheKey: Key) => (QK_5 extends keyof QP & keyof QR ? QP[QK_5] : never) | undefined;
+        /** Selects query expiresAt value. */
+        selectQueryExpiresAt: <QK_6 extends keyof QP | keyof QR>(state: unknown, query: QK_6, cacheKey: Key) => number | 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 ? MP[MK_1] : never, MK_1 extends keyof MP & keyof MR ? MR[MK_1] : never>;
+        selectMutationState: <MK_1 extends keyof MP | keyof MR>(state: unknown, mutation: MK_1) => MutationState<MK_1 extends keyof MP & keyof MR ? MP[MK_1] : never, 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. */
@@ -120,20 +144,13 @@ export declare const createCache: <N extends string, T extends Typenames, QP, QR
     hooks: {
         /** Returns client object with query and mutate functions. */
         useClient: () => {
-            query: <QK_6 extends keyof QP | keyof QR>(options: Omit<QueryOptions<T, QP, QR, QK_6>, "cachePolicy">) => Promise<QueryResult<QK_6 extends keyof QP & keyof QR ? QR[QK_6] : never>>;
-            mutate: <MK_6 extends keyof MP | keyof MR>(options: {
-                mutation: MK_6;
-                params: MK_6 extends keyof MP & keyof MR ? MP[MK_6] : never;
-            }) => Promise<MutationResult<MK_6 extends keyof MP & keyof MR ? MR[MK_6] : never>>;
+            query: <QK_7 extends keyof QP | keyof QR>(options: QueryOptions<T, QP, QR, QK_7>) => Promise<QueryResult<QK_7 extends keyof QP & keyof QR ? QR[QK_7] : never>>;
+            mutate: <MK_6 extends keyof MP | keyof MR>(options: MutateOptions<T, MP, MR, MK_6>) => Promise<MutationResult<MK_6 extends keyof MP & keyof MR ? MR[MK_6] : never>>;
         };
-        /** Fetches query when params change and subscribes to query state. */
-        useQuery: <QK_7 extends keyof QP | keyof QR>(options: import("./types").UseQueryOptions<T, QP, QR, QK_7>) => readonly [QueryMutationState<QK_7 extends keyof QP & keyof QR ? QP[QK_7] : never, QK_7 extends keyof QP & keyof QR ? QR[QK_7] : never>, (options?: {
-            params: QK_7 extends keyof QP & keyof QR ? QP[QK_7] : never;
-        } | undefined) => Promise<QueryResult<QK_7 extends infer T_5 ? T_5 extends QK_7 ? T_5 extends keyof QP & keyof QR ? QR[T_5] : never : never : never>>];
+        /** Fetches query when params change and subscribes to query state changes (except `expiresAt` field). */
+        useQuery: <QK_8 extends keyof QP | keyof QR>(options: import("./types").UseQueryOptions<T, QP, QR, QK_8>) => readonly [Omit<QueryState<QK_8 extends keyof QP & keyof QR ? QP[QK_8] : never, QK_8 extends keyof QP & keyof QR ? QR[QK_8] : never>, "expiresAt">, (options?: Partial<Pick<QueryOptions<T, QP, QR, QK_8>, "params" | "onlyIfExpired">> | undefined) => Promise<QueryResult<QK_8 extends infer T_5 ? T_5 extends QK_8 ? T_5 extends keyof QP & keyof QR ? QR[T_5] : never : never : never>>];
         /** Subscribes to provided mutation state and provides mutate function. */
-        useMutation: <MK_7 extends keyof MP | keyof MR>(options: {
-            mutation: MK_7;
-        }) => readonly [(params: MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never) => Promise<MutationResult<MK_7 extends infer T_6 ? T_6 extends MK_7 ? T_6 extends keyof MP & keyof MR ? MR[T_6] : never : never : never>>, QueryMutationState<MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never, MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never>, () => boolean];
+        useMutation: <MK_7 extends keyof MP | keyof MR>(options: Omit<MutateOptions<T, MP, MR, MK_7>, "params">) => readonly [(params: MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never) => Promise<MutationResult<MK_7 extends infer T_6 ? T_6 extends MK_7 ? T_6 extends keyof MP & keyof MR ? MR[T_6] : never : never : never>>, MutationState<MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never, MK_7 extends keyof MP & keyof MR ? MP[MK_7] : never>, () => boolean];
         /** useSelector + selectEntityById. */
         useSelectEntityById: <TN_2 extends keyof T>(id: Key | null | undefined, typename: TN_2) => T[TN_2] | undefined;
     };

package/dist/createCache.js

@@ -4,9 +4,9 @@ exports.createCache = void 0;
 const react_1 = require("react");
 const react_redux_1 = require("react-redux");
 const createActions_1 = require("./createActions");
+const createCacheReducer_1 = require("./createCacheReducer");
 const mutate_1 = require("./mutate");
 const query_1 = require("./query");
-const reducer_1 = require("./reducer");
 const useMutation_1 = require("./useMutation");
 const useQuery_1 = require("./useQuery");
 const utilsAndConstants_1 = require("./utilsAndConstants");
@@ -48,7 +48,7 @@ const createCache = (partialCache) => {
         /** 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),
+        reducer: (0, createCacheReducer_1.createCacheReducer)(actions, cache.typenames, Object.keys(cache.queries), cache.options),
         actions,
         selectors: {
             /** Selects query state. */
@@ -69,6 +69,10 @@ const createCache = (partialCache) => {
             selectQueryParams: (state, query, cacheKey) => {
                 return selectQueryState(state, query, cacheKey).params;
             },
+            /** Selects query expiresAt value. */
+            selectQueryExpiresAt: (state, query, cacheKey) => {
+                return selectQueryState(state, query, cacheKey).expiresAt;
+            },
             /** Selects mutation state. */
             selectMutationState,
             /** Selects mutation latest result. */
@@ -110,16 +114,20 @@ 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', store, cache, actions, queryKey, cacheKey, params);
+                            return (0, query_1.query)('query', store, cache, actions, queryKey, cacheKey, params, options.secondsToLive, options.onlyIfExpired, 
+                            // @ts-expect-error fix later
+                            options.mergeResults, options.onCompleted, options.onSuccess, options.onError);
                         },
                         mutate: (options) => {
-                            return (0, mutate_1.mutate)('mutate', store, cache, actions, options.mutation, options.params, abortControllers);
+                            return (0, mutate_1.mutate)('mutate', store, cache, actions, options.mutation, options.params, abortControllers, 
+                            // @ts-expect-error fix later
+                            options.onCompleted, options.onSuccess, options.onError);
                         },
                     };
                     return client;
                 }, [store]);
             },
-            /** Fetches query when params change and subscribes to query state. */
+            /** Fetches query when params change and subscribes to query state changes (except `expiresAt` field). */
             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),

package/dist/{reducer.d.ts → createCacheReducer.d.ts}

@@ -1,27 +1,34 @@
 import type { ActionMap } from './createActions';
-import type { CacheOptions, Dict, EntitiesMap, QueryMutationState, Typenames } from './types';
+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: ActionMap<N, T, QP, QR, MP, MR>, typenames: T, queryKeys: (keyof QP & keyof QR)[], cacheOptions: CacheOptions) => (state: {
     entities: EntitiesMap<T>;
-    queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: Dict<QueryMutationState<QP[QK], QR[QK]>>; } : never;
-    mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: QueryMutationState<MP[MK], MR[MK]>; } : never;
+    queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: Dict<QueryState<QP[QK], QR[QK]> | undefined>; } : never;
+    mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: MutationState<MP[MK], MR[MK]>; } : never;
 } | undefined, action: {
     type: `@rrc/${N}/updateQueryStateAndEntities`;
     queryKey: keyof QP & keyof QR;
     queryCacheKey: import("./types").Key;
-    state: Partial<QueryMutationState<QP[keyof QP & keyof QR], QR[keyof QP & keyof QR]>> | undefined;
+    state: Partial<QueryState<QP[keyof QP & keyof QR], QR[keyof QP & keyof QR]>> | undefined;
     entityChanges: import("./types").EntityChanges<T> | undefined;
 } | {
     type: `@rrc/${N}/updateMutationStateAndEntities`;
     mutationKey: keyof MP & keyof MR;
-    state: Partial<QueryMutationState<MP[keyof MP & keyof MR], MR[keyof MP & keyof MR]>> | undefined;
+    state: Partial<MutationState<MP[keyof MP & keyof MR], MR[keyof MP & keyof MR]>> | undefined;
     entityChanges: import("./types").EntityChanges<T> | undefined;
 } | {
     type: `@rrc/${N}/mergeEntityChanges`;
     changes: import("./types").EntityChanges<T>;
+} | {
+    type: `@rrc/${N}/invalidateQuery`;
+    queries: {
+        key: keyof QP & keyof QR;
+        cacheKey?: import("./types").Key | undefined;
+        expiresAt?: number | undefined;
+    }[];
 } | {
     type: `@rrc/${N}/clearQueryState`;
-    queryKeys: {
+    queries: {
         key: keyof QP & keyof QR;
         cacheKey?: import("./types").Key | undefined;
     }[];
@@ -30,6 +37,6 @@ export declare const createCacheReducer: <N extends string, T extends Typenames,
     mutationKeys: (keyof MP & keyof MR)[];
 }) => {
     entities: EntitiesMap<T>;
-    queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: Dict<QueryMutationState<QP[QK], QR[QK]>>; } : never;
-    mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: QueryMutationState<MP[MK], MR[MK]>; } : never;
+    queries: QP | QR extends infer T_1 ? { [QK in keyof T_1]: Dict<QueryState<QP[QK], QR[QK]> | undefined>; } : never;
+    mutations: MP | MR extends infer T_2 ? { [MK in keyof T_2]: MutationState<MP[MK], MR[MK]>; } : never;
 };

package/dist/{reducer.js → createCacheReducer.js}

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCacheReducer = void 0;
 const utilsAndConstants_1 = require("./utilsAndConstants");
 const EMPTY_QUERY_STATE = Object.freeze({});
+const optionalQueryKeys = ['error', 'expiresAt', 'result', 'params'];
+const optionalMutationKeys = ['error', 'result', 'params'];
 const createCacheReducer = (actions, typenames, queryKeys, cacheOptions) => {
     const entitiesMap = {};
     for (const key in typenames) {
@@ -32,6 +34,14 @@ const createCacheReducer = (actions, typenames, queryKeys, cacheOptions) => {
                 const { queryKey, queryCacheKey, state: queryState, entityChanges, } = action;
                 const oldQueryState = (_a = state.queries[queryKey][queryCacheKey]) !== null && _a !== void 0 ? _a : utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE;
                 let newQueryState = queryState && Object.assign(Object.assign({}, oldQueryState), queryState);
+                // remove undefined optional fields
+                if (newQueryState) {
+                    for (const key of optionalQueryKeys) {
+                        if (key in newQueryState && newQueryState[key] === undefined) {
+                            delete newQueryState[key];
+                        }
+                    }
+                }
                 if (deepEqual === null || deepEqual === void 0 ? void 0 : deepEqual(oldQueryState, newQueryState)) {
                     newQueryState = undefined;
                 }
@@ -51,6 +61,14 @@ const createCacheReducer = (actions, typenames, queryKeys, cacheOptions) => {
                 const { mutationKey, state: mutationState, entityChanges, } = action;
                 const oldMutationState = (_b = state.mutations[mutationKey]) !== null && _b !== void 0 ? _b : utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE;
                 let newMutationState = mutationState && Object.assign(Object.assign({}, oldMutationState), mutationState);
+                // remove undefined optional fields
+                if (newMutationState) {
+                    for (const key of optionalMutationKeys) {
+                        if (key in newMutationState && newMutationState[key] === undefined) {
+                            delete newMutationState[key];
+                        }
+                    }
+                }
                 if (deepEqual === null || deepEqual === void 0 ? void 0 : deepEqual(oldMutationState, newMutationState)) {
                     newMutationState = undefined;
                 }
@@ -71,26 +89,71 @@ const createCacheReducer = (actions, typenames, queryKeys, cacheOptions) => {
                 const newEntities = (0, utilsAndConstants_1.applyEntityChanges)(state.entities, changes, cacheOptions);
                 return newEntities ? Object.assign(Object.assign({}, state), { entities: newEntities }) : state;
             }
+            case actions.invalidateQuery.type: {
+                const { queries: queriesToInvalidate } = action;
+                if (!queriesToInvalidate.length) {
+                    return state;
+                }
+                const now = Date.now();
+                let newQueries = undefined;
+                for (const { key, cacheKey, expiresAt = now } of queriesToInvalidate) {
+                    const queryStates = (newQueries !== null && newQueries !== void 0 ? newQueries : state.queries)[key];
+                    if (cacheKey != null) {
+                        if (queryStates[cacheKey]) {
+                            const queryState = queryStates[cacheKey];
+                            if (queryState && queryState.expiresAt !== expiresAt) {
+                                newQueries !== null && newQueries !== void 0 ? newQueries : (newQueries = Object.assign({}, state.queries));
+                                if (state.queries[key] === newQueries[key]) {
+                                    newQueries[key] = Object.assign({}, newQueries[key]);
+                                }
+                                // @ts-expect-error fix type later
+                                newQueries[key][cacheKey] = Object.assign(Object.assign({}, queryState), { expiresAt });
+                                if (expiresAt === undefined) {
+                                    delete newQueries[key][cacheKey].expiresAt;
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        for (const cacheKey in queryStates) {
+                            const queryState = queryStates[cacheKey];
+                            if (queryState && queryState.expiresAt !== expiresAt) {
+                                newQueries !== null && newQueries !== void 0 ? newQueries : (newQueries = Object.assign({}, state.queries));
+                                if (state.queries[key] === newQueries[key]) {
+                                    newQueries[key] = Object.assign({}, newQueries[key]);
+                                }
+                                newQueries[key][cacheKey] = Object.assign(Object.assign({}, queryState), { expiresAt });
+                                if (expiresAt === undefined) {
+                                    delete newQueries[key][cacheKey].expiresAt;
+                                }
+                            }
+                        }
+                    }
+                }
+                return !newQueries
+                    ? state
+                    : Object.assign(Object.assign({}, state), { queries: newQueries });
+            }
             case actions.clearQueryState.type: {
-                const { queryKeys: queryKeysToClear } = action;
-                if (!queryKeysToClear.length) {
+                const { queries: queriesToClear } = action;
+                if (!queriesToClear.length) {
                     return state;
                 }
                 let newQueries = undefined;
-                for (const query of queryKeysToClear) {
-                    const queryState = (newQueries !== null && newQueries !== void 0 ? newQueries : state.queries)[query.key];
-                    if (query.cacheKey != null) {
-                        if (queryState[query.cacheKey]) {
+                for (const { key, cacheKey } of queriesToClear) {
+                    const queryStates = (newQueries !== null && newQueries !== void 0 ? newQueries : state.queries)[key];
+                    if (cacheKey != null) {
+                        if (queryStates[cacheKey]) {
                             newQueries !== null && newQueries !== void 0 ? newQueries : (newQueries = Object.assign({}, state.queries));
-                            if (state.queries[query.key] === newQueries[query.key]) {
-                                newQueries[query.key] = Object.assign({}, newQueries[query.key]);
+                            if (state.queries[key] === newQueries[key]) {
+                                newQueries[key] = Object.assign({}, newQueries[key]);
                             }
-                            delete newQueries[query.key][query.cacheKey];
+                            delete newQueries[key][cacheKey];
                         }
                     }
-                    else if (queryState !== EMPTY_QUERY_STATE) {
+                    else if (queryStates !== EMPTY_QUERY_STATE) {
                         newQueries !== null && newQueries !== void 0 ? newQueries : (newQueries = Object.assign({}, state.queries));
-                        newQueries[query.key] = EMPTY_QUERY_STATE;
+                        newQueries[key] = EMPTY_QUERY_STATE;
                     }
                 }
                 return !newQueries

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createCache } from './createCache';
-export type { ReduxCacheState } from './reducer';
+export type { ReduxCacheState } from './createCacheReducer';
 export * from './types';
 export { defaultGetCacheKey, DEFAULT_QUERY_MUTATION_STATE as defaultQueryMutationState, } from './utilsAndConstants';

package/dist/index.js

@@ -22,18 +22,20 @@ var utilsAndConstants_1 = require("./utilsAndConstants");
 Object.defineProperty(exports, "defaultGetCacheKey", { enumerable: true, get: function () { return utilsAndConstants_1.defaultGetCacheKey; } });
 Object.defineProperty(exports, "defaultQueryMutationState", { enumerable: true, get: function () { return utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE; } });
 // Backlog
-// ! high
-// optimistic response
-// type extractors?
-// skip -> enabled?
-// add full api docs
-// update readme with how to use mergeResults for invalidating / updating caches?
-// make query key / cache key difference more clear in the docs, and/or rename queryKey -> query?
+// ! high (1.0.0)
+// key -> query
+// rca -> vite
+// defaults
+// remove cachePolicy? make skip/enabled a function? skip -> enabled/shouldFetch?
+// optional typenames: {} as Typenames
+// remove mergeResults? bcs store is passed to queries/mutations
+// remove undefined optional fields & emtpy states
+// generate full api docs
 // ! medium
+// optimistic response
+// make query key / cache key difference more clear in the docs
 // check type of function arguments in dev
 // allow multiple mutation with same keys?
-// type extractors from cache
-// custom useStore
 // return back deserialize selector?
 // selector for entities by typename
 // callback option on error / success?
@@ -42,6 +44,7 @@ Object.defineProperty(exports, "defaultQueryMutationState", { enumerable: true,
 // deep equal entities while merging state
 // make error type generic
 // ! low
+// custom useStore & useSelector to support multiple stores?
 // access to currently loading queries and mutations?
 // add params to the state?
 // cancellation to queries

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, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateMutationStateAndEntities, }: Pick<ActionMap<N, T, unknown, unknown, MP, 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>>;
+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, unknown, unknown, MP, MR>, "updateMutationStateAndEntities">, mutationKey: MK, params: MK extends keyof MP & keyof MR ? MP[MK] : never, abortControllers: WeakMap<Store, Record<Key, AbortController>>, onCompleted?: ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & string]> | undefined, error: unknown, params: MP[keyof MP & keyof MR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & number]> | undefined, error: unknown, params: MP[keyof MP & keyof MR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & symbol]> | undefined, error: unknown, params: MP[keyof MP & keyof MR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined, onSuccess?: ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & string]>, params: MP[keyof MP & keyof MR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & number]>, params: MP[keyof MP & keyof MR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, MR[keyof MP & keyof MR & symbol]>, params: MP[keyof MP & keyof MR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined, onError?: ((error: unknown, params: MP[keyof MP & keyof MR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((error: unknown, params: MP[keyof MP & keyof MR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((error: unknown, params: MP[keyof MP & keyof MR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined) => 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, store, cache, { updateMutationStateAndEntities, }, mutationKey, params, abortControllers) => __awaiter(void 0, void 0, void 0, function* () {
+const mutate = (logTag, store, cache, { updateMutationStateAndEntities, }, mutationKey, params, abortControllers, onCompleted = cache.mutations[mutationKey].onCompleted, onSuccess = cache.mutations[mutationKey].onSuccess, onError = cache.mutations[mutationKey].onError) => __awaiter(void 0, void 0, void 0, function* () {
     let abortControllersOfStore = abortControllers.get(store);
     if (abortControllersOfStore === undefined) {
         abortControllersOfStore = {};
@@ -44,7 +44,7 @@ const mutate = (logTag, store, cache, { updateMutationStateAndEntities, }, mutat
     try {
         response = yield fetchFn(
         // @ts-expect-error fix later
-        params, abortController.signal);
+        params, store, abortController.signal);
     }
     catch (e) {
         error = e;
@@ -64,15 +64,23 @@ const mutate = (logTag, store, cache, { updateMutationStateAndEntities, }, mutat
             error: error,
             loading: false,
         }));
+        // @ts-expect-error params
+        onError === null || onError === void 0 ? void 0 : onError(error, params, store);
+        // @ts-expect-error response
+        onCompleted === null || onCompleted === void 0 ? void 0 : onCompleted(response, error, params, store);
         return { error };
     }
     if (response) {
-        store.dispatch(updateMutationStateAndEntities(mutationKey, {
+        const newState = {
             error: undefined,
             loading: false,
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             result: response.result,
-        }, response));
+        };
+        store.dispatch(updateMutationStateAndEntities(mutationKey, newState, response));
+        // @ts-expect-error params
+        onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess(response, params, store);
+        // @ts-expect-error response
+        onCompleted === null || onCompleted === void 0 ? void 0 : onCompleted(response, error, params, store);
         // @ts-expect-error fix later
         return { result: response.result };
     }

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, store: Store, cache: Cache<N, T, QP, QR, MP, MR>, { updateQueryStateAndEntities, }: Pick<ActionMap<N, T, QP, QR, unknown, unknown>, "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>>;
+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, QP, QR, unknown, unknown>, "updateQueryStateAndEntities">, queryKey: QK, cacheKey: Key, params: QK extends keyof QP & keyof QR ? QP[QK] : never, secondsToLive: number | undefined, onlyIfExpired: boolean | undefined, mergeResults?: ((oldResult: QR[keyof QP & keyof QR & string] | undefined, response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & string]>, params: QP[keyof QP & keyof QR & string] | undefined, store: Store<any, import("redux").AnyAction>) => QR[keyof QP & keyof QR & string]) | ((oldResult: QR[keyof QP & keyof QR & number] | undefined, response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & number]>, params: QP[keyof QP & keyof QR & number] | undefined, store: Store<any, import("redux").AnyAction>) => QR[keyof QP & keyof QR & number]) | ((oldResult: QR[keyof QP & keyof QR & symbol] | undefined, response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & symbol]>, params: QP[keyof QP & keyof QR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => QR[keyof QP & keyof QR & symbol]) | undefined, onCompleted?: ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & string]> | undefined, error: unknown, params: QP[keyof QP & keyof QR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & number]> | undefined, error: unknown, params: QP[keyof QP & keyof QR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & symbol]> | undefined, error: unknown, params: QP[keyof QP & keyof QR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined, onSuccess?: ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & string]>, params: QP[keyof QP & keyof QR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & number]>, params: QP[keyof QP & keyof QR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((response: import("./types").QueryResponse<T, QR[keyof QP & keyof QR & symbol]>, params: QP[keyof QP & keyof QR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined, onError?: ((error: unknown, params: QP[keyof QP & keyof QR & string] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((error: unknown, params: QP[keyof QP & keyof QR & number] | undefined, store: Store<any, import("redux").AnyAction>) => void) | ((error: unknown, params: QP[keyof QP & keyof QR & symbol] | undefined, store: Store<any, import("redux").AnyAction>) => void) | undefined) => Promise<QueryResult<QK extends keyof QP & keyof QR ? QR[QK] : never>>;

package/dist/query.js

@@ -11,11 +11,10 @@ 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, store, cache, { updateQueryStateAndEntities, }, queryKey, cacheKey, params) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
+const query = (logTag, store, cache, { updateQueryStateAndEntities, }, queryKey, cacheKey, params, secondsToLive = cache.queries[queryKey].secondsToLive, onlyIfExpired, mergeResults = cache.queries[queryKey].mergeResults, onCompleted = cache.queries[queryKey].onCompleted, onSuccess = cache.queries[queryKey].onSuccess, onError = cache.queries[queryKey].onError) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
     const logsEnabled = cache.options.logsEnabled;
     const cacheStateSelector = cache.cacheStateSelector;
-    const mergeResults = cache.queries[queryKey].mergeResults;
     const queryStateOnStart = cacheStateSelector(store.getState()).queries[queryKey][cacheKey];
     if (queryStateOnStart === null || queryStateOnStart === void 0 ? void 0 : queryStateOnStart.loading) {
         logsEnabled &&
@@ -26,35 +25,54 @@ const query = (logTag, store, cache, { updateQueryStateAndEntities, }, queryKey,
             });
         return CANCELLED_RESULT;
     }
+    if (onlyIfExpired && (queryStateOnStart === null || queryStateOnStart === void 0 ? void 0 : queryStateOnStart.expiresAt) != null && queryStateOnStart.expiresAt > Date.now()) {
+        logsEnabled &&
+            (0, utilsAndConstants_1.log)(`${logTag} cancelled: not expired yet`, {
+                queryStateOnStart,
+                params,
+                cacheKey,
+                onlyIfExpired,
+            });
+        return CANCELLED_RESULT;
+    }
     store.dispatch(updateQueryStateAndEntities(queryKey, cacheKey, {
         loading: true,
         params,
     }));
-    logsEnabled && (0, utilsAndConstants_1.log)(`${logTag} started`, { queryStateOnStart, params, cacheKey });
+    logsEnabled && (0, utilsAndConstants_1.log)(`${logTag} started`, { queryKey, params, cacheKey, queryStateOnStart, onlyIfExpired });
     let response;
     const fetchFn = cache.queries[queryKey].query;
     try {
         response = yield fetchFn(
         // @ts-expect-error fix later
-        params);
+        params, store);
     }
     catch (error) {
         store.dispatch(updateQueryStateAndEntities(queryKey, cacheKey, {
             error: error,
             loading: false,
         }));
+        // @ts-expect-error params
+        onError === null || onError === void 0 ? void 0 : onError(error, params, store);
+        // @ts-expect-error params
+        onCompleted === null || onCompleted === void 0 ? void 0 : onCompleted(undefined, error, params, store);
         return { error };
     }
     const newState = {
         error: undefined,
         loading: false,
+        expiresAt: (_a = response.expiresAt) !== null && _a !== void 0 ? _a : (secondsToLive != null ? Date.now() + secondsToLive * 1000 : undefined),
         result: mergeResults
             ? mergeResults(
             // @ts-expect-error fix later
-            (_a = cacheStateSelector(store.getState()).queries[queryKey][cacheKey]) === null || _a === void 0 ? void 0 : _a.result, response, params, store)
+            (_b = cacheStateSelector(store.getState()).queries[queryKey][cacheKey]) === null || _b === void 0 ? void 0 : _b.result, response, params, store)
             : response.result,
     };
     store.dispatch(updateQueryStateAndEntities(queryKey, cacheKey, newState, response));
+    // @ts-expect-error response
+    onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess(response, params, store);
+    // @ts-expect-error response
+    onCompleted === null || onCompleted === void 0 ? void 0 : onCompleted(response, undefined, params, store);
     return {
         // @ts-expect-error fix types
         result: newState === null || newState === void 0 ? void 0 : newState.result,

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { Store } from 'redux';
-import type { ReduxCacheState } from './reducer';
+import type { ReduxCacheState } from './createCacheReducer';
 export type Key = string | number | symbol;
 export type Dict<T> = Record<Key, T>;
 export type OptionalPartial<T, K extends keyof T> = Partial<{
@@ -69,14 +69,20 @@ export type EntitiesMap<T extends Typenames> = {
 export type EntityIds<T extends Typenames> = {
     [K in keyof T]?: Key[];
 };
-export type Query<T extends Typenames, P, R> = (params: P) => Promise<QueryResponse<T, R>>;
+export type Query<P, T extends Typenames = Typenames, R = unknown> = (
+/** Query parameters */
+params: P, 
+/** Redux store */
+store: Store) => Promise<QueryResponse<T, R>>;
 export type QueryInfo<T extends Typenames, P, R> = {
-    query: Query<T, P, R>;
+    query: Query<P, T, R>;
     /**
      * Cache policy.
      * @default cache-first
      */
     cachePolicy?: QueryCachePolicy;
+    /** If set, this value updates expiresAt value of query state when query resut is received. */
+    secondsToLive?: number;
     /** 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;
     /**
@@ -85,35 +91,56 @@ export type QueryInfo<T extends Typenames, P, R> = {
      * It is recommended to override it when default implementation is not optimal or when keys in params object can be sorted in random order etc.
      * */
     getCacheKey?: (params?: P) => Key;
+    /** Called after fetch finished either successfully or not. */
+    onCompleted?: (response: QueryResponse<T, R> | undefined, error: unknown | undefined, params: P | undefined, store: Store) => void;
+    /** Called after fetch finished without error. */
+    onSuccess?: (response: QueryResponse<T, R>, params: P | undefined, store: Store) => void;
+    /** Called after fetch finished with error. */
+    onError?: (error: unknown, params: P | undefined, store: Store) => void;
+};
+export type QueryState<P, R> = MutationState<P, R> & {
+    expiresAt?: number;
 };
 export type UseQueryOptions<T extends Typenames, QP, QR, QK extends keyof (QP & QR)> = {
     query: QK;
     params: QK extends keyof (QP | QR) ? QP[QK] : never;
+    /** When true fetch is not performed. When switches to false fetch is performed depending on cache policy. */
     skip?: boolean;
-} & Pick<QueryInfo<T, unknown, unknown>, 'cachePolicy'>;
+} & Pick<QueryInfo<T, QK extends keyof (QP | QR) ? QP[QK] : never, QK extends keyof (QP | QR) ? QR[QK] : never>, 'cachePolicy' | 'secondsToLive' | 'mergeResults' | 'onCompleted' | 'onSuccess' | 'onError'>;
+export type QueryOptions<T extends Typenames, QP, QR, QK extends keyof (QP & QR)> = Omit<UseQueryOptions<T, QP, QR, QK>, 'skip' | 'cachePolicy'> & {
+    /** If set to true, query will run only if it is expired or result not yet cached. */
+    onlyIfExpired?: boolean;
+};
 /**
  * @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.
  */
 export type QueryCachePolicy = 'cache-first' | 'cache-and-fetch';
 export type QueryResponse<T extends Typenames, R> = EntityChanges<T> & {
-    /** Normalized result of a query. */
     result: R;
+    /** If defined, overrides this value for query state, ignoring `secondsToLive`. */
+    expiresAt?: number;
 };
 export type QueryResult<R> = {
     error?: unknown;
     cancelled?: true;
     result?: R;
 };
-export type QueryOptions<T extends Typenames, QP, QR, QK extends keyof (QP & QR)> = Omit<UseQueryOptions<T, QP, QR, QK>, 'skip'>;
-export type Mutation<T extends Typenames, P, R> = (params: P, 
+export type Mutation<P, T extends Typenames = Typenames, R = unknown> = (
+/** Mutation parameters */
+params: P, 
+/** Redux store */
+store: Store, 
 /** Signal is aborted for current mutation when the same mutation was called once again. */
 abortSignal: AbortSignal) => Promise<MutationResponse<T, R>>;
-export type MutationInfo<T extends Typenames, P, R> = {
-    mutation: Mutation<T, P, R>;
+export type MutationInfo<T extends Typenames, P, R> = Pick<QueryInfo<T, P, R>, 'onCompleted' | 'onSuccess' | 'onError'> & {
+    mutation: Mutation<P, T, R>;
+};
+export type MutateOptions<T extends Typenames, MP, MR, MK extends keyof (MP & MR)> = Pick<MutationInfo<T, MK extends keyof (MP | MR) ? MP[MK] : never, MK extends keyof (MP | MR) ? MR[MK] : never>, 'onCompleted' | 'onSuccess' | 'onError'> & {
+    mutation: MK;
+    params: MK extends keyof (MP | MR) ? MP[MK] : never;
 };
 export type MutationResponse<T extends Typenames, R> = EntityChanges<T> & {
-    /** Normalized result of a mutation. */
     result?: R;
 };
 export type MutationResult<R> = {
@@ -121,7 +148,7 @@ export type MutationResult<R> = {
     aborted?: true;
     result?: R;
 };
-export type QueryMutationState<P, R> = {
+export type MutationState<P, R> = {
     /** `true` when query or mutation is currently in progress. */
     loading: boolean;
     /** Result of the latest successfull response. */

package/dist/useMutation.d.ts

@@ -1,6 +1,4 @@
 import { Store } from 'redux';
 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, unknown, MP, MR>, "updateMutationStateAndEntities">, options: {
-    mutation: MK;
-}, 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, MK extends keyof MP & keyof MR ? MP[MK] : never>, () => boolean];
+import { Cache, Key, MutateOptions, MutationState, 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, unknown, MP, MR>, "updateMutationStateAndEntities">, options: Omit<MutateOptions<T, MP, MR, MK>, "params">, 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>>, MutationState<MK extends keyof MP & keyof MR ? MP[MK] : never, MK extends keyof MP & keyof MR ? MP[MK] : never>, () => boolean];

package/dist/useMutation.js

@@ -16,7 +16,7 @@ const mutate_1 = require("./mutate");
 const utilsAndConstants_1 = require("./utilsAndConstants");
 const useMutation = (cache, actions, options, abortControllers) => {
     var _a;
-    const { mutation: mutationKey } = options;
+    const { mutation: mutationKey, onCompleted, onSuccess, onError } = options;
     const store = (0, react_redux_1.useStore)();
     // Using single useMemo for performance reasons
     const [mutationStateSelector, mutate, abort] = (0, react_1.useMemo)(() => {
@@ -32,7 +32,9 @@ const useMutation = (cache, actions, options, abortControllers) => {
             },
             // mutate
             (params) => __awaiter(void 0, void 0, void 0, function* () {
-                return yield (0, mutate_1.mutate)('useMutation.mutate', store, cache, actions, mutationKey, params, abortControllers);
+                return yield (0, mutate_1.mutate)('useMutation.mutate', store, cache, actions, mutationKey, params, abortControllers, 
+                // @ts-expect-error fix later
+                onCompleted, onSuccess, onError);
             }),
             // abort
             () => {

package/dist/useQuery.d.ts

@@ -1,5 +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, QP, QR, MP, MR>, "updateQueryStateAndEntities">, options: UseQueryOptions<T, QP, QR, QK>) => readonly [QueryMutationState<QK extends keyof QP & keyof QR ? QP[QK] : never, QK extends keyof QP & keyof QR ? QR[QK] : never>, (options?: {
-    params: QK extends keyof QP & keyof QR ? QP[QK] : never;
-} | undefined) => 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>>];
+import { Cache, QueryOptions, QueryState, 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, QP, QR, MP, MR>, "updateQueryStateAndEntities">, options: UseQueryOptions<T, QP, QR, QK>) => readonly [Omit<QueryState<QK extends keyof QP & keyof QR ? QP[QK] : never, QK extends keyof QP & keyof QR ? QR[QK] : never>, "expiresAt">, (options?: Partial<Pick<QueryOptions<T, QP, QR, QK>, "params" | "onlyIfExpired">> | undefined) => 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,7 +16,7 @@ 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', } = options;
+    const { query: queryKey, skip, params, secondsToLive, cachePolicy = (_a = cache.queries[queryKey].cachePolicy) !== null && _a !== void 0 ? _a : 'cache-first', mergeResults, onCompleted, onSuccess, onError, } = options;
     const logsEnabled = cache.options.logsEnabled;
     const getCacheKey = (_b = cache.queries[queryKey].getCacheKey) !== null && _b !== void 0 ? _b : (utilsAndConstants_1.defaultGetCacheKey);
     const cacheStateSelector = cache.cacheStateSelector;
@@ -25,9 +25,13 @@ const useQuery = (cache, actions, options) => {
     const cacheKey = getCacheKey(params);
     /** Fetch query with the new parameters, or refetch with the same if parameters not provided. */
     const fetch = (0, react_1.useCallback)((options) => __awaiter(void 0, void 0, void 0, function* () {
+        const paramsPassed = options && 'params' in options;
         return yield (0, query_1.query)('useQuery.fetch', store, cache, actions, queryKey, 
         // @ts-expect-error fix later
-        options ? getCacheKey(options.params) : cacheKey, options ? options.params : params);
+        paramsPassed ? getCacheKey(options.params) : cacheKey, paramsPassed ? options.params : params, // params type can also have null | undefined, thats why we don't check for it here
+        secondsToLive, options === null || options === void 0 ? void 0 : options.onlyIfExpired, 
+        // @ts-expect-error fix later
+        mergeResults, onCompleted, onSuccess, onError);
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [store, queryKey, cacheKey]);
@@ -35,16 +39,20 @@ const useQuery = (cache, actions, options) => {
     const queryState = (_c = (0, react_redux_1.useSelector)((state) => {
         const queryState = cacheStateSelector(state).queries[queryKey][cacheKey];
         return queryState; // TODO proper type
-    })) !== null && _c !== void 0 ? _c : utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE;
+    }, (useQueryStateComparer))) !== null && _c !== void 0 ? _c : utilsAndConstants_1.DEFAULT_QUERY_MUTATION_STATE;
     (0, react_1.useEffect)(() => {
         if (skip) {
             logsEnabled && (0, utilsAndConstants_1.log)('useQuery.useEffect skip fetch', { skip, cacheKey });
             return;
         }
-        if (queryState.result != null && cachePolicy === 'cache-first') {
+        if (queryState.result != null &&
+            cachePolicy === 'cache-first' &&
+            (queryState.expiresAt == null || queryState.expiresAt > Date.now())) {
             logsEnabled &&
-                (0, utilsAndConstants_1.log)('useQuery.useEffect don`t fetch due to cache policy', {
+                (0, utilsAndConstants_1.log)('useQuery.useEffect no fetch due to cache policy', {
                     result: queryState.result,
+                    expiresAt: queryState.expiresAt,
+                    now: Date.now(),
                     cachePolicy,
                 });
             return;
@@ -61,3 +69,16 @@ const useQuery = (cache, actions, options) => {
     return [queryState, fetch];
 };
 exports.useQuery = useQuery;
+/** Omit `expiresAt` from comparison */
+const useQueryStateComparer = (state1, state2) => {
+    if (state1 === state2) {
+        return true;
+    }
+    if (state1 === undefined || state2 === undefined) {
+        return false;
+    }
+    return (state1.error === state2.error &&
+        state1.loading === state2.loading &&
+        state1.params === state2.params &&
+        state1.result === state2.result);
+};

package/dist/utilsAndConstants.d.ts

@@ -4,9 +4,9 @@ export declare const optionalUtils: {
     deepEqual?: (a: any, b: any) => boolean;
 };
 export declare const IS_DEV: boolean;
-export declare const DEFAULT_QUERY_MUTATION_STATE: {
-    readonly loading: false;
-};
+export declare const DEFAULT_QUERY_MUTATION_STATE: Readonly<{
+    loading: false;
+}>;
 export declare const defaultGetCacheKey: <P = unknown>(params: P) => Key;
 export declare const log: (tag: string, data?: unknown) => void;
 export declare const applyEntityChanges: <T extends Typenames>(entities: EntitiesMap<T>, changes: EntityChanges<T>, options: CacheOptions) => EntitiesMap<T> | undefined;

package/dist/utilsAndConstants.js

@@ -20,7 +20,7 @@ exports.IS_DEV = (() => {
         return process.env.NODE_ENV === 'development';
     }
 })();
-exports.DEFAULT_QUERY_MUTATION_STATE = { loading: false };
+exports.DEFAULT_QUERY_MUTATION_STATE = Object.freeze({ loading: false });
 const defaultGetCacheKey = (params) => {
     switch (typeof params) {
         case 'string':

package/package.json

@@ -2,7 +2,7 @@
   "name": "react-redux-cache",
   "author": "Alexander Danilov",
   "license": "MIT",
-  "version": "0.6.1",
+  "version": "0.7.0-rc.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",
@@ -12,6 +12,8 @@
     "lint": "yarn eslint src",
     "build": "yarn clean && yarn lint && tsc",
     "test": "node node_modules/jest/bin/jest.js",
+    "preminor-rc": "yarn build && npm version preminor --preid rc",
+    "publish-rc": "npm publish --tag rc",
     "prepublishOnly": "yarn build && yarn test"
   },
   "peerDependencies": {