IBLCATALOG-616: quick draft for a new refresh method

README.md

@@ -77,6 +77,18 @@ Returns a wrapped function that implements caching.
 
 Invalidates the current cache entry for the given function and args combination. The function passed should be the unwrapped, initial function.
 
+#### `ceych.set()`
+
+Use this to manually sets the cache entry for the given function and args combination. You can use this to overrwrite an existing cache entry to a newer one.
+
+The new cache key will have a TTL set randomly between this.defaultTtl/2 and this.defaultTtl. This is to ensure that when manually setting a lot of cache keys at the same time, they don't end up all expiring at the same time and causing lots of caches misses.
+
+##### Parameters
+
+* `funcOrOpts` - Either a function or a set of options of the format `{ func: yourFunction, suffix: 'yourSuffix' }` if you wish to include a suffix.
+* `args` - An array of args that you passed to the wrapped function call which initially stored the cache entry.
+* `updatedValue` - The new value to store in the cache.
+
 ##### Parameters
 
 * `funcOrOpts` - Either a function or a set of options of the format `{ func: yourFunction, suffix: 'yourSuffix' }` if you wish to include a suffix.

lib/ceych.js

@@ -32,9 +32,9 @@ function validateClientOpts(opts) {
   return opts;
 }
 
-function validateInvalidateOpts(opts) {
+function getOptions(opts) {
   if (!opts) {
-    throw new Error('Incorrect invalidate opts received, you must pass a function or options object to invalidate.');
+    throw new Error('Incorrect opts received, you must pass a function or options object to invalidate.');
   }
 
   if (typeof opts === 'function') {
@@ -45,13 +45,13 @@ function validateInvalidateOpts(opts) {
   }
 
   if (!opts.func || typeof opts.func !== 'function') {
-    throw new Error('Incorrect invalidate opts received, opts.func must be a function.');
+    throw new Error('Incorrect opts received, opts.func must be a function.');
   }
 
   if (opts.suffix && typeof opts.suffix !== 'string') {
-    throw new Error('Incorrect invalidate opts received, opts.suffix must be a string.');
+    throw new Error('Incorrect opts received, opts.suffix must be a string.');
   }
-  
+
   if (!opts.suffix) opts.suffix = '';
 
   return opts;
@@ -110,16 +110,41 @@ class Ceych {
    * @param  {...any} args The args that you passed to the wrapped function call which initially stored the cache entry.
    */
   invalidate(funcOrOpts, ...args) {
-    const opts = validateInvalidateOpts(funcOrOpts);
+    const opts = getOptions(funcOrOpts);
 
     const cacheKey = createCacheKey(opts.func, args, opts.suffix);
 
     if (this.stats) {
       this.stats.increment('ceych.invalidate');
     }
+
     return this.cache.drop(cacheKey);
   }
 
+  /**
+   * Manually sets the cache entry for the given function and args combination.
+   * This is an advanced escape hatch for cases where you know a cached value has changed
+   * and would prefer to manually store the new value instead of simply calling invalidate().
+   *
+   * The new cache key will have a TTL set randomly between this.defaultTTL/2 and this.defaultTTL.
+   * This is to ensure that when manually setting a lot of cache keys at the same time, they don't end
+   * up all expiring at the same time and causing lots of caches misses.
+   * @param {function | {func: function, suffix: string}} funcOrOpts Either a function or options including `func` and optional `suffix`.
+   * @param  {args[]} functionArgs The args that identify the target cache key.
+   * @param {*} updatedValue The value to store in cache.
+   */
+  set(funcOrOpts, functionArgs, updatedValue) {
+    const opts = getOptions(funcOrOpts);
+    const cacheKey = createCacheKey(opts.func, functionArgs, opts.suffix);
+    const randomTtl = Math.floor(Math.random() * this.defaultTTL / 2);
+
+    if (this.stats) {
+      this.stats.increment('ceych.set');
+    }
+
+    return this.cache.set(cacheKey, updatedValue, (this.defaultTTL - randomTtl) * 1000);
+  }
+
   /**
    * Disables the use of the cache. This can be useful if you want to toggle usage of the cache for operational purposes - e.g. for operational purposes, or unit tests.
    */

package.json

@@ -41,5 +41,6 @@
     "mocha": "^10.2.0",
     "nyc": "^17.1.0",
     "sinon": "^15.0.3"
-  }
-}
+  },
+  "packageManager": "pnpm@11.5.1+sha512.93f7b57422ea7068257235b4c16eb60762eb68e1dc23723199cc739043ea9be2c4143274a399d8c6defa2b1176226d9ca1c4b63482d6200c1a8fbaa78c1d1485"
+}