react-redux-cache 0.20.0 → 0.22.0

package/dist/esm/utilsAndConstants.js

@@ -45,7 +45,7 @@ export const defaultGetCacheKey = (params) => {
 }
 
 export const applyEntityChanges = (entities, changes, options) => {
-  var _a, _b, _c, _d
+  var _a, _b, _c
   if (changes.merge && changes.entities) {
     logWarn('applyEntityChanges', 'merge and entities should not be both set')
   }
@@ -53,6 +53,7 @@ export const applyEntityChanges = (entities, changes, options) => {
   if (!merge && !replace && !remove) {
     return undefined
   }
+  const mutable = options.mutableCollections
   const deepEqual = options.deepComparisonEnabled ? optionalUtils.deepEqual : undefined
   let result
   const objectWithAllTypenames = Object.assign(
@@ -95,37 +96,48 @@ export const applyEntityChanges = (entities, changes, options) => {
         logWarn('applyEntityChanges', 'merge, replace and remove changes have intersections for: ' + typename)
       }
     }
-    const oldEntities = (_d = entities[typename]) !== null && _d !== void 0 ? _d : EMPTY_OBJECT
+    const oldEntities = entities[typename]
     let newEntities
     entitiesToRemove === null || entitiesToRemove === void 0
       ? void 0
       : entitiesToRemove.forEach((id) => {
-          if (oldEntities[id]) {
+          if (oldEntities === null || oldEntities === void 0 ? void 0 : oldEntities[id]) {
             newEntities !== null && newEntities !== void 0
               ? newEntities
-              : (newEntities = Object.assign({}, oldEntities))
+              : (newEntities = mutable ? oldEntities : Object.assign({}, oldEntities))
             delete newEntities[id]
           }
         })
     if (entitiesToReplace) {
       for (const id in entitiesToReplace) {
         const newEntity = entitiesToReplace[id]
-        if (!(deepEqual === null || deepEqual === void 0 ? void 0 : deepEqual(oldEntities[id], newEntity))) {
+        if (
+          oldEntities === undefined ||
+          !(deepEqual === null || deepEqual === void 0 ? void 0 : deepEqual(oldEntities[id], newEntity))
+        ) {
           newEntities !== null && newEntities !== void 0
             ? newEntities
-            : (newEntities = Object.assign({}, oldEntities))
+            : (newEntities = mutable
+                ? oldEntities !== null && oldEntities !== void 0
+                  ? oldEntities
+                  : {}
+                : Object.assign({}, oldEntities))
           newEntities[id] = newEntity
         }
       }
     }
     if (entitiesToMerge) {
       for (const id in entitiesToMerge) {
-        const oldEntity = oldEntities[id]
+        const oldEntity = oldEntities === null || oldEntities === void 0 ? void 0 : oldEntities[id]
         const newEntity = Object.assign(Object.assign({}, oldEntity), entitiesToMerge[id])
         if (!(deepEqual === null || deepEqual === void 0 ? void 0 : deepEqual(oldEntity, newEntity))) {
           newEntities !== null && newEntities !== void 0
             ? newEntities
-            : (newEntities = Object.assign({}, oldEntities))
+            : (newEntities = mutable
+                ? oldEntities !== null && oldEntities !== void 0
+                  ? oldEntities
+                  : {}
+                : Object.assign({}, oldEntities))
           newEntities[id] = newEntity
         }
       }
@@ -133,7 +145,15 @@ export const applyEntityChanges = (entities, changes, options) => {
     if (!newEntities) {
       continue
     }
-    result !== null && result !== void 0 ? result : (result = Object.assign({}, entities))
+    if (mutable) {
+      incrementChangeKey(newEntities)
+      if (result === undefined) {
+        incrementChangeKey(entities)
+        result = entities
+      }
+    } else {
+      result !== null && result !== void 0 ? result : (result = Object.assign({}, entities))
+    }
     result[typename] = newEntities
   }
   options.logsEnabled &&
@@ -146,8 +166,8 @@ export const applyEntityChanges = (entities, changes, options) => {
   return result
 }
 
-export const isEmptyObject = (o) => {
-  for (const _ in o) {
+export const isEmptyObject = (obj) => {
+  for (const _ in obj) {
     return false
   }
   return true
@@ -177,3 +197,11 @@ export const FetchPolicy = {
   },
   Always: () => true,
 }
+
+export const incrementChangeKey = (mutable) => {
+  if (mutable._changeKey === undefined) {
+    mutable._changeKey = 0
+  } else {
+    mutable._changeKey += 1
+  }
+}

package/dist/types/createCache.d.ts

@@ -2,7 +2,6 @@ import type {
   Cache,
   CacheOptions,
   CacheState,
-  Dict,
   EntitiesMap,
   EntityChanges,
   Globals,
@@ -32,7 +31,7 @@ import {applyEntityChanges} from './utilsAndConstants'
  * `const cache = withTypenames<MyTypenames>().createCache({...})`
  */
 export declare const withTypenames: <T extends Typenames = Typenames>() => {
-  /** Creates reducer, actions and hooks for managing queries and mutations through redux cache. */
+  /** Creates reducer, actions and hooks for managing queries and mutations. */
   createCache: <N extends string, QP, QR, MP, MR>(
     partialCache: OptionalPartial<
       Omit<Cache<N, T, QP, QR, MP, MR>, 'globals'>,
@@ -43,7 +42,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
   ) => {
     /** Keeps all options, passed while creating the cache. */
     cache: Cache<N, T, QP, QR, MP, MR>
-    /** Reducer of the cache, should be added to redux store. */
+    /** Reducer of the cache, should be added to redux/zustand store. */
     reducer: (
       state: CacheState<T, QP, QR, MP, MR> | undefined,
       action:
@@ -127,7 +126,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
         }
         type: `@rrc/${N}/mergeEntityChanges`
       }
-      /** Invalidates query states. */
+      /** Sets expiresAt to Date.now(). */
       invalidateQuery: {
         <K extends keyof QP & keyof QR>(
           queries: {
@@ -170,7 +169,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
         }
         type: `@rrc/${N}/clearMutationState`
       }
-      /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and shoult be used with caution. */
+      /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and should be used with caution. */
       clearCache: {
         (stateToKeep?: Partial<CacheState<T, QP, QR, MP, MR>> | undefined): {
           type: `@rrc/${N}/clearCache`
@@ -255,9 +254,12 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
         typename: TN
       ) => T[TN] | undefined
       /** Selects all entities. */
-      selectEntities: (state: unknown) => EntitiesMap<T>
+      selectEntities: (state: unknown) => EntitiesMap<T> & import('./types').Mutable
       /** Selects all entities of provided typename. */
-      selectEntitiesByTypename: <TN extends keyof T>(state: unknown, typename: TN) => EntitiesMap<T>[TN]
+      selectEntitiesByTypename: <TN extends keyof T>(
+        state: unknown,
+        typename: TN
+      ) => (EntitiesMap<T> & import('./types').Mutable)[TN]
     }
     hooks: {
       /** Returns memoized object with query and mutate functions. Memoization dependency is the store. */
@@ -331,6 +333,13 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
       ]
       /** useSelector + selectEntityById. */
       useSelectEntityById: <TN extends keyof T>(id: Key | null | undefined, typename: TN) => T[TN] | undefined
+      /**
+       * useSelector + selectEntitiesByTypename. Also subscribes to collection's change key if `mutableCollections` enabled.
+       * @warning Subscribing to collections should be avoided.
+       * */
+      useEntitiesByTypename: <TN extends keyof T>(
+        typename: TN
+      ) => (EntitiesMap<T> & import('./types').Mutable)[TN]
     }
     utils: {
       /** Creates client by providing the store. Can be used when the store is a singleton - to not use a useClient hook for getting the client, but import it directly. */
@@ -352,8 +361,12 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
       }
       /** Generates the initial state by calling a reducer. Not needed for redux — it already generates it the same way when creating the store. */
       getInitialState: () => 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. */
+      /**
+       * Apply changes to the entities map.
+       * Returns `undefined` if nothing to change, otherwise new `EntitiesMap<T>` with applied changes.
+       * Uses deep comparison if `deepComparisonEnabled` option is `true`.
+       * Performs additional checks for intersections if `additionalValidation` option is `true`, and prints warnings if finds any issues.
+       */
       applyEntityChanges: (
         entities: Parameters<typeof applyEntityChanges<T>>[0],
         changes: Parameters<typeof applyEntityChanges<T>>[1]
@@ -362,9 +375,7 @@ export declare const withTypenames: <T extends Typenames = Typenames>() => {
   }
 }
 
-/**
- * Creates reducer, actions and hooks for managing queries and mutations through redux cache.
- */
+/** Creates reducer, actions and hooks for managing queries and mutations. */
 export declare const createCache: <N extends string, QP, QR, MP, MR>(
   partialCache: Partial<{
     queries: Partial<{
@@ -393,7 +404,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
 ) => {
   /** Keeps all options, passed while creating the cache. */
   cache: Cache<N, Typenames, QP, QR, MP, MR>
-  /** Reducer of the cache, should be added to redux store. */
+  /** Reducer of the cache, should be added to redux/zustand store. */
   reducer: (
     state: CacheState<Typenames, QP, QR, MP, MR> | undefined,
     action:
@@ -479,7 +490,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
       }
       type: `@rrc/${N}/mergeEntityChanges`
     }
-    /** Invalidates query states. */
+    /** Sets expiresAt to Date.now(). */
     invalidateQuery: {
       <K extends keyof QP & keyof QR>(
         queries: {
@@ -522,7 +533,7 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
       }
       type: `@rrc/${N}/clearMutationState`
     }
-    /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and shoult be used with caution. */
+    /** Replaces cache state with initial, optionally merging with provided state. Doesn't cancel running fetches and should be used with caution. */
     clearCache: {
       (stateToKeep?: Partial<CacheState<Typenames, QP, QR, MP, MR>> | undefined): {
         type: `@rrc/${N}/clearCache`
@@ -614,9 +625,12 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
       typename: TN
     ) => object | undefined
     /** Selects all entities. */
-    selectEntities: (state: unknown) => EntitiesMap<Typenames>
+    selectEntities: (state: unknown) => EntitiesMap<Typenames> & import('./types').Mutable
     /** Selects all entities of provided typename. */
-    selectEntitiesByTypename: <TN extends string>(state: unknown, typename: TN) => Dict<object> | undefined
+    selectEntitiesByTypename: <TN extends string>(
+      state: unknown,
+      typename: TN
+    ) => (EntitiesMap<Typenames> & import('./types').Mutable)[TN]
   }
   hooks: {
     /** Returns memoized object with query and mutate functions. Memoization dependency is the store. */
@@ -690,6 +704,13 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
     ]
     /** useSelector + selectEntityById. */
     useSelectEntityById: <TN extends string>(id: Key | null | undefined, typename: TN) => object | undefined
+    /**
+     * useSelector + selectEntitiesByTypename. Also subscribes to collection's change key if `mutableCollections` enabled.
+     * @warning Subscribing to collections should be avoided.
+     * */
+    useEntitiesByTypename: <TN extends string>(
+      typename: TN
+    ) => (EntitiesMap<Typenames> & import('./types').Mutable)[TN]
   }
   utils: {
     /** Creates client by providing the store. Can be used when the store is a singleton - to not use a useClient hook for getting the client, but import it directly. */
@@ -711,10 +732,14 @@ export declare const createCache: <N extends string, QP, QR, MP, MR>(
     }
     /** Generates the initial state by calling a reducer. Not needed for redux — it already generates it the same way when creating the store. */
     getInitialState: () => 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. */
+    /**
+     * Apply changes to the entities map.
+     * Returns `undefined` if nothing to change, otherwise new `EntitiesMap<T>` with applied changes.
+     * Uses deep comparison if `deepComparisonEnabled` option is `true`.
+     * Performs additional checks for intersections if `additionalValidation` option is `true`, and prints warnings if finds any issues.
+     */
     applyEntityChanges: (
-      entities: EntitiesMap<Typenames>,
+      entities: EntitiesMap<Typenames> & import('./types').Mutable,
       changes: EntityChanges<Typenames>
     ) => EntitiesMap<Typenames> | undefined
   }

package/dist/types/createSelectors.d.ts

@@ -12,6 +12,11 @@ export type Selectors<
 export declare const createSelectors: <N extends string, T extends Typenames, QP, QR, MP, MR>(
   cache: Cache<N, T, QP, QR, MP, MR>
 ) => {
+  selectEntityById: <TN extends keyof T>(
+    state: unknown,
+    id: Key | null | undefined,
+    typename: TN
+  ) => T[TN] | undefined
   selectQueryState: <QK extends keyof (QP & QR)>(
     state: unknown,
     query: QK,
@@ -67,14 +72,9 @@ export declare const createSelectors: <N extends string, T extends Typenames, QP
     state: unknown,
     mutation: MK
   ) => (MK extends keyof MP & keyof MR ? MP[MK] : never) | undefined
-  selectEntityById: <TN extends keyof T>(
-    state: unknown,
-    id: Key | null | undefined,
-    typename: TN
-  ) => T[TN] | undefined
-  selectEntities: (state: unknown) => import('./types').EntitiesMap<T>
+  selectEntities: (state: unknown) => import('./types').EntitiesMap<T> & import('./types').Mutable
   selectEntitiesByTypename: <TN extends keyof T>(
     state: unknown,
     typename: TN
-  ) => import('./types').EntitiesMap<T>[TN]
+  ) => (import('./types').EntitiesMap<T> & import('./types').Mutable)[TN]
 }

package/dist/types/types.d.ts

@@ -3,7 +3,15 @@ import type {Selectors} from './createSelectors'
 
 export type Key = string | number | symbol
 
-export type Dict<T> = Record<Key, T>
+export type Mutable = {
+  /**
+   * Used only when mutable cache enabled. Always incremented when collection changed by reducer to allow subscribe on changes.
+   * Should not be used for comparing different collections as supposed to be compared only with previously saved changeKey of the same collection.
+   */
+  _changeKey?: number
+}
+
+export type Dict<T> = Record<Key, T> & Mutable
 
 export type OptionalPartial<T, K extends keyof T> = Partial<{
   [A in K]: Partial<T[A]>
@@ -95,7 +103,14 @@ export type Globals<N extends string, T extends Typenames, QP, QR, MP, MR> = {
 }
 
 export type CacheOptions = {
-  /** Enables additional validation with logging to console.warn. Recommened to enable in dev/testing mode. @Default true in dev mode. */
+  /**
+   * BETA: Optimization that makes state collections mutable.
+   * Subscription to mutable collecitons will work only when subscribed to both collection and its change key - collections
+   * still can be replaced with the new ones instead of mutating e.g. when clearing state.
+   * @Default false
+   * */
+  mutableCollections: boolean
+  /** Enables additional validation with logging to console.warn. Recommended to enable in dev/testing mode. @Default true in dev mode. */
   additionalValidation: boolean
   /** Enables debug logs. @Default false */
   logsEnabled: boolean
@@ -121,13 +136,13 @@ export type EntityIds<T extends Typenames> = {
 }
 
 export type CacheState<T extends Typenames, QP, QR, MP, MR> = {
-  entities: EntitiesMap<T>
+  entities: EntitiesMap<T> & Mutable
   queries: {
     [QK in keyof (QP | QR)]: Dict<QueryState<T, QP[QK], QR[QK]> | undefined>
-  }
+  } & Mutable
   mutations: {
     [MK in keyof (MP | MR)]: MutationState<T, MP[MK], MR[MK]>
-  }
+  } & Mutable
 }
 
 export type QueryInfo<
@@ -165,7 +180,7 @@ export type QueryInfo<
    * Default implementation uses `String()` or `JSON.stringify` depending on type.
    * 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
+  getCacheKey?: (params: P) => Key
   /** Called after fetch completed either successfully or not. */
   onCompleted?: (
     response: NormalizedQueryResponse<T, R> | undefined,
@@ -272,17 +287,21 @@ export type QueryOptions<
 
 export type QueryResponse<R = unknown> = {
   result: R
-  /** If defined, overrides this value for query state, ignoring `secondsToLive`. */
+  /** If defined, overrides this value in the query state, ignoring `secondsToLive` option. */
   expiresAt?: number
 }
 
 export type NormalizedQueryResponse<T extends Typenames = Typenames, R = unknown> = EntityChanges<T> &
   QueryResponse<R>
 
-/** Current result is always returned, even if cancelled or finished with error. */
+/** Result is always returned, even if cancelled or finished with error. */
 export type QueryResult<R = unknown> = {
   error?: unknown
-  /** Fetch cancelled reason. */
+  /**
+   * Fetch cancelled reason.
+   * @value loading - already loading. Result of current fetch is returned.
+   * @value not-expired - not expired yet. Current state result is returned.
+   */
   cancelled?: 'loading' | 'not-expired'
   result?: R
 }

package/dist/types/utilsAndConstants.d.ts

@@ -3,6 +3,7 @@ import type {
   EntitiesMap,
   EntityChanges,
   Key,
+  Mutable,
   QueryState,
   QueryStateComparer,
   Typenames,
@@ -31,13 +32,13 @@ export declare const noop: () => void
 export declare const defaultGetCacheKey: <P = unknown>(params: P) => Key
 
 export declare const applyEntityChanges: <T extends Typenames>(
-  entities: EntitiesMap<T>,
+  entities: EntitiesMap<T> & Mutable,
   changes: EntityChanges<T>,
   options: CacheOptions
 ) => EntitiesMap<T> | undefined
 
 /** Returns true if object has no keys. */
-export declare const isEmptyObject: (o: object) => boolean
+export declare const isEmptyObject: (obj: object) => boolean
 
 /** Returns query state comparer that compares only provided fields. Used in implementation of `selectorComparer` option. */
 export declare const createStateComparer: <T extends Typenames = Typenames, Q = unknown, P = unknown>(
@@ -45,7 +46,10 @@ export declare const createStateComparer: <T extends Typenames = Typenames, Q =
 ) => QueryStateComparer<T, Q, P>
 
 export declare const FetchPolicy: {
-  /** Only if cache does not exist (result is undefined) or expired. @Default */
+  /**
+   * Only if cache does not exist (result is undefined) or expired. Default.
+   * @param expired `true` when `expiresAt` is defined and lower than `Date.now()`
+   */
   NoCacheOrExpired: <T extends Typenames = Typenames, P = unknown, R = unknown>(
     expired: boolean,
     _params: P,
@@ -54,3 +58,5 @@ export declare const FetchPolicy: {
   /** Every fetch trigger. */
   Always: () => boolean
 }
+
+export declare const incrementChangeKey: (mutable: Mutable) => void

package/package.json

@@ -2,7 +2,7 @@
   "name": "react-redux-cache",
   "author": "Alexander Danilov",
   "license": "MIT",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Powerful data fetching and caching library for Redux and Zustand that supports normalization.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -17,8 +17,8 @@
   "scripts": {
     "example": "(cd example && yarn --production && yarn dev)",
     "clean": "rm -rf dist",
-    "lint": "yarn eslint",
-    "lint-fix": "yarn eslint --fix",
+    "lint": "yarn eslint ./src",
+    "lint-fix": "yarn eslint --fix ./src",
     "lint-fix-dist": "yarn eslint --quiet --fix dist/ > /dev/null 2>&1 || true",
     "build-cjs": "tsc -p tsconfig.cjs.json && rm -rf dist/cjs/testing && rm -rf dist/cjs/__tests__",
     "build-esm": "tsc -p tsconfig.esm.json > /dev/null ; rm -rf dist/esm/testing && rm -rf dist/esm/__tests__",
@@ -31,7 +31,8 @@
     "publish-rc": "npm publish --tag rc",
     "remove-rc": "npm version <same-version-without-rc>",
     "prepublishOnly": "yarn build && yarn test",
-    "generate-docs": "node --experimental-strip-types scripts/generate-docs.ts"
+    "generate-docs": "node --experimental-strip-types scripts/generate-docs.ts",
+    "benchmark": "NODE_ENV=production node -r ts-node/register --expose-gc benchmark.ts"
   },
   "peerDependencies": {
     "fast-deep-equal": "*",
@@ -72,6 +73,7 @@
     "redux": "4.2.1",
     "redux-logger": "3.0.6",
     "ts-jest": "29.1.0",
+    "ts-node": "10.9.2",
     "typescript": "5.6.3"
   },
   "files": [