fix(types): expose an explicit type for the output of logic wrapped with extendable caching

Author: uladkasach

src/index.ts

@@ -1,2 +1,2 @@
 export { withSimpleCaching, SimpleCache, KeySerializationMethod, SimpleCacheResolutionMethod, WithSimpleCachingOptions } from './withSimpleCaching';
-export { withExtendableCaching } from './withExtendableCaching';
+export { withExtendableCaching, LogicWithExtendableCaching } from './withExtendableCaching';

src/withExtendableCaching.ts

@@ -1,50 +1,30 @@
 import { withSimpleCaching } from '.';
+import { isAFunction } from './isAFunction';
 import {
   defaultKeySerializationMethod,
   defaultValueSerializationMethod,
   getCacheFromCacheOption,
   WithSimpleCachingOptions,
 } from './withSimpleCaching';
 
-/**
- * exposes the cache-wrapped method along with some primitives which enable extending the caching logic
- *
- * specifically
- * - exposes a way to `invalidate` the cache, for a given input (e.g., to support external triggers for invalidation)
- * - exposes a way to `update` the cache, for a given input (e.g., to support write-through caching and optimistic caching)
- *
- * relevance
- * - when wrapping logic to cache the user is able to specify several caching options (e.g., key serialization method, value serialization method, etc)
- * - in order to define their own `invalidation` and `update` methods, without this function, the user would need to access these caching options per function elsewhere
- * - this function makes it easy to utilize and extend cache invalidation + update commands for the wrapped logic, by managing the references to the caching options on behalf of the user
- */
-export const withExtendableCaching = <LR extends any, CR extends any, L extends (...args: any[]) => LR>(
-  logic: L,
-  options: WithSimpleCachingOptions<LR, CR, L>,
-) => {
+export interface LogicWithExtendableCaching<LR extends any, CR extends any, L extends (...args: any[]) => LR> {
   /**
    * execute the logic with caching
    */
-  const execute = withSimpleCaching(logic, options);
+  execute: L;
 
   /**
    * invalidate the cached value for a given input
    *
    * note
    * - applies key serialization on the key input, just like execute
    */
-  const invalidate = async ({
-    forInput,
-  }: {
+  invalidate: (args: {
     /**
      * invalidate the cache for this input
      */
     forInput: Parameters<L>;
-  }) => {
-    const serializeKey = options.serialize?.key ?? defaultKeySerializationMethod;
-    const cache = getCacheFromCacheOption({ forInput, cacheOption: options.cache });
-    await cache.set(serializeKey(forInput), undefined as CR);
-  };
+  }) => Promise<void>;
 
   /**
    * update the cached value for a given input
@@ -53,10 +33,7 @@ export const withExtendableCaching = <LR extends any, CR extends any, L extends
    * - applies key serialization on the key input, just like execute
    * - applies value serialization on the value output, just like execute
    */
-  const update = async ({
-    forInput,
-    toValue,
-  }: {
+  update: (args: {
     /**
      * update the cache for this input
      */
@@ -65,16 +42,41 @@ export const withExtendableCaching = <LR extends any, CR extends any, L extends
     /**
      * update the cache to this value
      */
-    toValue: ReturnType<L>;
-  }) => {
+    toValue: ReturnType<L> | ((args: { cachedValue: CR | undefined }) => ReturnType<L>);
+  }) => Promise<void>;
+}
+
+/**
+ * exposes the cache-wrapped method along with some primitives which enable extending the caching logic
+ *
+ * specifically
+ * - exposes a way to `invalidate` the cache, for a given input (e.g., to support external triggers for invalidation)
+ * - exposes a way to `update` the cache, for a given input (e.g., to support write-through caching and optimistic caching)
+ *
+ * relevance
+ * - when wrapping logic to cache the user is able to specify several caching options (e.g., key serialization method, value serialization method, etc)
+ * - in order to define their own `invalidation` and `update` methods, without this function, the user would need to access these caching options per function elsewhere
+ * - this function makes it easy to utilize and extend cache invalidation + update commands for the wrapped logic, by managing the references to the caching options on behalf of the user
+ */
+export const withExtendableCaching = <LR extends any, CR extends any, L extends (...args: any[]) => LR>(
+  logic: L,
+  options: WithSimpleCachingOptions<LR, CR, L>,
+): LogicWithExtendableCaching<LR, CR, L> => {
+  const execute: LogicWithExtendableCaching<LR, CR, L>['execute'] = withSimpleCaching(logic, options);
+
+  const invalidate: LogicWithExtendableCaching<LR, CR, L>['invalidate'] = async ({ forInput }) => {
+    const serializeKey = options.serialize?.key ?? defaultKeySerializationMethod;
+    const cache = getCacheFromCacheOption({ forInput, cacheOption: options.cache });
+    await cache.set(serializeKey(forInput), undefined as CR);
+  };
+
+  const update: LogicWithExtendableCaching<LR, CR, L>['update'] = async ({ forInput, toValue }) => {
     const serializeKey = options.serialize?.key ?? defaultKeySerializationMethod;
     const serializeValue = options.serialize?.value ?? defaultValueSerializationMethod;
     const cache = getCacheFromCacheOption({ forInput, cacheOption: options.cache });
-    await cache.set(serializeKey(forInput), serializeValue(toValue), { secondsUntilExpiration: options.secondsUntilExpiration });
+    const newValue = isAFunction(toValue) ? toValue({ cachedValue: await cache.get(serializeKey(forInput)) }) : toValue;
+    await cache.set(serializeKey(forInput), serializeValue(newValue), { secondsUntilExpiration: options.secondsUntilExpiration });
   };
 
-  /**
-   * return the extendable cache-wrapped logic methods
-   */
   return { execute, invalidate, update };
 };