cachette 3.0.1 → 4.0.1

package/README.md

@@ -2,7 +2,8 @@
 
 Resilient cache library supporting concurrent requests through local cache or Redis.
 
-> **This repo is a work-in-progress and is not ready for general use.**
+> **This library is undocumented, and only meant for internal Unito use.**
+> **It remains licensed as MIT; TS source code is bundled in the npm tarball.**
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachette",
-  "version": "3.0.1",
+  "version": "4.0.1",
   "engines": {
     "node": ">=20",
     "npm": ">=10"
@@ -8,7 +8,6 @@
   "description": "Resilient cache library supporting concurrent requests through local cache or Redis.",
   "main": "dist/src/index.js",
   "typings": "dist/src/index.d.ts",
-  "repository": "https://github.com/unitoio/cachette",
   "author": {
     "name": "Unito",
     "email": "hello@unito.io"
@@ -31,7 +30,7 @@
     "test:ci": "npm run compile && mkdir -p ci_output/testresults && mocha --config test/mocharc-ci.js 'dist/test/**/*.js'",
     "relock": "rm -rf node_modules package-lock.json; npm install --package-lock; npm out; true",
     "postprepare": "npm run --silent githook-install",
-    "githook-install": "mkdir -p .git/hooks/ && echo '#!/usr/bin/env sh\necho \"⚠️ Reminder that cachette is a *public* repo! ⚠️\"\necho \"No private info in: branch name, commit message, PR title & description & comments!\"\necho \"Ctrl+C to abort git push, Enter to proceed.\"\nread REPLY < /dev/tty' > '.git/hooks/pre-push' && chmod +x '.git/hooks/pre-push'"
+    "githook-install": "mkdir -p .git/hooks/ && echo '#!/usr/bin/env sh\necho \"⚠️ Reminder that cachette is a *source-public* package! ⚠️\"\necho \"No private info in comments!!!\"\necho \"Ctrl+C to abort git push, Enter to proceed.\"\nread REPLY < /dev/tty' > '.git/hooks/pre-push' && chmod +x '.git/hooks/pre-push'"
   },
   "nyc": {
     "cache": false,

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './lib/CacheClient';
+export * from './lib/CacheInstance';
+export * from './lib/LocalCache';
+export * from './lib/RedisCache';
+export * from './lib/WriteThroughCache';

package/src/lib/CacheClient.ts

@@ -0,0 +1,145 @@
+import { CacheInstance, CachableValue } from './CacheInstance';
+
+export abstract class CacheClient {
+
+  protected cacheInstance: CacheInstance;
+  protected buildCacheKey(propertyKey: string, args: any[]): string {
+
+    const buildKeyArgs = (args: any[]) => args
+      .filter(x =>
+        typeof x !== 'object' ||
+        // If the arg is an object, we check that it's not an instance of a class
+        (typeof x === 'object' && (x?.constructor.name === 'Object' || x?.constructor.name === 'Array')) ||
+        // typeof null === object, then we need to have another condition to accept null as well
+        x === null
+      ).map(x => {
+        if (typeof x === 'object' && !Array.isArray(x) && x) {
+          // Check if we have a circular reference in the plain object
+          JSON.stringify(x);
+
+          return Object.entries(x).sort().map(([key, value]) => {
+            if (typeof value === 'object') {
+              const nestedObjectKeys = buildKeyArgs([value])
+              return `${key}-${nestedObjectKeys}`
+            }
+            return `${key}-${value}`
+          }).join('-');
+        }
+
+        if (Array.isArray(x)) {
+          const builtKey = buildKeyArgs(x.sort());
+          return builtKey.join('-');
+        }
+        return new String(x).valueOf();
+      });
+
+    const builtKey = [
+      propertyKey,
+      ...buildKeyArgs(args),
+    ].join('-');
+
+    const maxKeyLength = process.env.UNITO_CACHE_MAX_KEY_LENGTH && parseInt(process.env.UNITO_CACHE_MAX_KEY_LENGTH, 10) || 1000;
+    if (builtKey.length > maxKeyLength) {
+      throw new Error(`Built key is bigger than ${maxKeyLength} chars`);
+    }
+
+    return builtKey;
+  }
+
+  /**
+   * Decorator to cache the calls to a function.
+   *
+   * @param ttl How long the cache should last, in seconds
+   * @param shouldCacheError How the error-caching function (accessible by calling
+   *        `getErrorCachingFunction`) should decide which errors to cache.
+   *        Defaults to caching *all* errors. *Again, to insist*: this does not
+   *        mean the _decorated function_ will cache all errors, it means that
+   *        _the error-caching function_ will. They live apart and each honors
+   *        its behavior (decorated function *never* caches errors, the other does)
+   */
+  public static cached(
+    ttl = 0,
+    shouldCacheError = (err: Error) => true,
+  ): any {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
+      const origFunction = descriptor.value;
+
+      // don't use an => function here, or you lose access to 'this'
+      const functionCachingResults = function (...args): Promise<CachableValue> {
+        const key = this.buildCacheKey(propertyKey, args);
+        const fetchFunction = origFunction.bind(this, ...args);
+        return this.cacheInstance.getOrFetchValue(
+          key,
+          ttl,
+          fetchFunction,
+          undefined,
+        );
+      };
+      const functionCachingResultsAndErrors = function (...args): Promise<CachableValue> {
+        const key = this.buildCacheKey(propertyKey, args);
+        const fetchFunction = origFunction.bind(this, ...args);
+        return this.cacheInstance.getOrFetchValue(
+          key,
+          ttl,
+          fetchFunction,
+          undefined,
+          shouldCacheError,
+        );
+      };
+
+      target[`${propertyKey}NoCache`] = origFunction;
+      target[`${propertyKey}ErrorCaching`] = functionCachingResultsAndErrors;
+
+      descriptor.value = functionCachingResults;
+      return descriptor;
+    };
+  }
+
+  // We *do* want a loosely-typed `Function` here, by nature of the library
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  public getUncachedFunction(functionName: string): Function {
+    if (this[`${functionName}NoCache`]) {
+      return this[`${functionName}NoCache`].bind(this);
+    }
+    return this[functionName].bind(this);
+  }
+
+  public getErrorCachingFunction(functionName: string): (...args: any) => Promise<any> {
+    if (this[`${functionName}ErrorCaching`]) {
+      return this[`${functionName}ErrorCaching`].bind(this);
+    }
+    return this[functionName].bind(this);
+  }
+
+  /**
+   * Clears the valued returned from a cached function call,
+   * using the CacheClient.cached.
+   */
+  public async clearCachedFunctionCall(functionName: string, ...args: any[]): Promise<void> {
+    const key = this.buildCacheKey(functionName, args);
+    await this.cacheInstance.delValue(key);
+  }
+
+  /**
+   * Wait for the write commands to be acknowledged by the replicas.
+   * This is useful when you want to ensure data is freshness on all nodes of the cluster.
+   * We're defaulting to 5 replicas because it is the maximum number of read-only replica nodes
+   * that you can have for each shard in AWS-Elastic cache (https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Replication.Redis.Groups.html)
+   * 
+   * /!\ If the number of replicas asked for acknowledgment is greater than the number of replicas in the cluster, the function will always block
+   * /!\ until the timeout is reached. Make sure you know the number of replicas in your cluster when calling this function.
+   */
+  public async waitForReplication(replicas: number = 5, timeout: number = 50): Promise<number> {
+    return this.cacheInstance.waitForReplication(replicas, timeout);
+  }
+
+  /**
+   * Gets the valued returned from a cached function call,
+   * using the CacheClient.cached.
+   */
+  public async getCachedFunctionCall(functionName: string, ...args: any[]): Promise<CachableValue> {
+    const key = this.buildCacheKey(functionName, args);
+    return this.cacheInstance.getValue(key);
+  }
+
+}

package/src/lib/CacheInstance.ts

@@ -0,0 +1,222 @@
+import { EventEmitter } from 'node:events';
+
+export type CachableValue = any;
+export type FetchingFunction = () => Promise<CachableValue>;
+
+
+export abstract class CacheInstance extends EventEmitter {
+
+  /**
+   * Will resolve when the cache instance connection is ready.
+   */
+  public abstract isReady(): Promise<void>;
+
+  /**
+   * Get the number of items in the cache.
+   */
+  public abstract itemCount(): Promise<number>;
+
+  /**
+   * Get a value from the cache.
+   *
+   * @param key   The key of the value to get.
+   *
+   * @return      The value associated with the key, or undefined if
+   *              no such value exists.
+   *
+   */
+  public abstract getValue(key: string): Promise<CachableValue>;
+
+  /**
+   * Get the TTL of an entry, in ms
+   *
+   * @param key   The key of the entry whose ttl to retrieve
+   *
+   * @return      The remaining TTL on the entry, in ms.
+   *              undefined if the entry does not exist.
+   *              0 if the entry does not expire.
+   */
+  public abstract getTtl(key: string): Promise<number | undefined>;
+
+  /**
+   * Set a value in the cache.
+   *
+   * @param key        The key of the value to set.
+   * @param value      The value to set.
+   * @param ttl        The time to live of the value in seconds.
+   *                   By default, the value will not expire
+   *
+   * @return true if the value was stored, false otherwise.
+   */
+  public abstract setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean>;
+
+  /**
+   * Delete a value from the cache.
+   *
+   * @param key        The key of the value to set.
+   *
+   */
+  public abstract delValue(key: string): Promise<void>;
+
+  /**
+   * This command blocks the current client until all the previous write commands are
+   * successfully transferred and acknowledged by at least the specified number of replicas.
+   * 
+   * @param replicas The number of replicas that should acknowledge write operations.
+   * @param timeout The maximum amount of time to wait in milliseconds.
+   * 
+   */
+  public abstract waitForReplication(replicas: number, timeout: number): Promise<number>;
+
+
+  /**
+   * clear the whole cache
+   */
+  public abstract clear(): Promise<void>;
+
+  /**
+   * clear any in-memory cache item.
+   */
+  public abstract clearMemory(): Promise<void>;
+
+  /**
+   * Determines if locking is supported in the cache implementation
+   */
+  public isLockingSupported(): boolean {
+    return false;
+  }
+
+  /**
+   * Globally lock a named resource
+   *
+   * @param resource    The name of the resource to lock
+   * @param ttlMs       The time to live of the lock in ms
+   * @param retry       Whether or not to retry attempts to lock
+   *
+   * @returns           The lock, an opaque object that must be passed to unlock()
+   */
+  public lock(resource: string, ttlMs: number, retry?: boolean): Promise<any> {
+    throw new Error('unsupported');
+  }
+
+  /**
+   * Unlock a named resource aquired with lock()
+   *
+   * @param lock        The lock object
+   */
+  public unlock(lock: any): Promise<void> {
+    throw new Error('unsupported');
+  }
+
+  /**
+   * Determine whether *at least one non-expired lock* starts with the given pattern.
+   */
+  public hasLock(prefix: string): Promise<boolean> {
+    throw new Error('unsupported');
+  }
+
+  /**
+   * Terminate / exit / quit the instance
+   */
+  public quit(): Promise<void> {
+    return new Promise((resolve) => { resolve() });
+  }
+
+
+  /**
+   * Keep track of active fetches to prevent
+   * simultaneous requests to the same resource in parallel.
+   */
+  private activeFetches: { [key: string]: Promise<CachableValue> } = {};
+
+  /**
+   * Get or fetch a value
+   *
+   * @param key     The key of the value to get
+   * @param ttl     The time to live of the value in seconds.
+   * @param fetchFn The function that can retrieve the original value
+   * @param lockTtl Global distributed lock TTL (in seconds) protecting fetching.
+   *                If undefined, 0 or falsy, locking is not preformed
+   * @param shouldCacheError A callback being passed errors, controlling whether
+   *                         to cache or not errors. Defaults to never cache.
+   *
+   * @returns       The cached or fetched value
+   */
+  public async getOrFetchValue<F extends FetchingFunction = FetchingFunction>(
+    key: string,
+    ttl: number,
+    fetchFunction: F,
+    lockTtl?: number,
+    shouldCacheError?: (err: Error) => boolean,
+  ): Promise<ReturnType<F>> {
+
+    // already cached?
+    let cached = await this.getValue(key);
+    if (cached instanceof Error) {
+      if (shouldCacheError) {
+        throw cached;
+      } else {
+        cached = undefined;
+      }
+    }
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    // already fetching?
+    const currentFetch = this.activeFetches[key];
+    if (currentFetch) {
+      return currentFetch;
+    }
+
+    // I'm the one fetching.
+    let lock: any;
+    try {
+      // get the lock if needed
+      const lockName = `lock__${key}`;
+      if (lockTtl && this.isLockingSupported()) {
+        lock = await this.lock(lockName, lockTtl * 1000);
+        // check if the value has been populated while we were locking
+        let cachedValue = await this.getValue(key);
+        if (cachedValue instanceof Error) {
+          if (shouldCacheError) {
+            throw cachedValue;
+          } else {
+            cachedValue = undefined;
+          }
+        }
+        if (cachedValue !== undefined) {
+          return cachedValue;
+        }
+      }
+
+      // fetch!
+      let error: Error | undefined;
+      let result: any;
+      try {
+        const fetchPromise = this.activeFetches[key] = fetchFunction();
+        result = await fetchPromise;
+      } catch (err) {
+        error = err;
+      }
+
+      // cache! results: always, errors: only if satisfying user assertion
+      if (error && shouldCacheError && shouldCacheError(error)) {
+        await this.setValue(key, error, ttl);
+      } else if (result !== undefined) {
+        await this.setValue(key, result, ttl);
+      }
+
+      if (error) {
+        throw error;
+      }
+      return result;
+    } finally {
+      delete this.activeFetches[key];
+      if (lock) {
+        await this.unlock(lock);
+      }
+    }
+  }
+
+}

package/src/lib/LocalCache.ts

@@ -0,0 +1,178 @@
+import { LRUCache } from 'lru-cache';
+
+import { CachableValue, CacheInstance } from './CacheInstance';
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export class LocalCache extends CacheInstance {
+
+  public static DEFAULT_MAX_ITEMS = 5000;
+  // Default maximum age for the items, in MS.
+  public static DEFAULT_MAX_AGE: number = 30 * 60 * 1000;
+
+  public static LOCK_ACQUIRE_TIMEOUT = 2000;
+
+  // See https://github.com/isaacs/node-lru-cache#options
+  // for options.
+  private cache = new LRUCache<string, any>({
+    max: Number.parseInt(process.env.CACHETTE_LC_MAX_ITEMS as string, 10) || LocalCache.DEFAULT_MAX_ITEMS,
+    ttl: Number.parseInt(process.env.CACHETTE_LC_MAX_AGE as string, 10) || LocalCache.DEFAULT_MAX_AGE,
+  });
+
+  /**
+   * @inheritdoc
+   */
+  public async isReady(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async itemCount(): Promise<number> {
+    return this.cache.size;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async setValue(key: string, value: CachableValue, ttl = 0): Promise<boolean> {
+    this.emit('set', key, value);
+
+    if (value === undefined) {
+      this.emit('warn', `Cannot set ${key} to undefined!`);
+      return false;
+    }
+
+    // The lru cache interprets 0 as no expiration date.
+    if (ttl === 0) {
+      this.cache.set(key, value);
+    } else {
+      this.cache.set(key, value, { ttl: ttl * 1000 });
+    }
+    return true;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async getValue(key: string): Promise<any> {
+    const value = await this.cache.get(key);
+    this.emit('get', key, value);
+    return value;
+  }
+
+  /**
+   * @inheritdoc
+   * Return the number of ms left in the item's TTL.
+   * If item is not in cache, returns 0.
+   * Returns a very large number (e.g. 1799999.9158420563) if item is in cache without a defined TTL.
+   * Docs: https://github.com/isaacs/node-lru-cache#getremainingttlkey
+   */
+  public async getTtl(key: string): Promise<number | undefined> {
+    const remainingTtl = await this.cache.getRemainingTTL(key);
+    /** If entry is not cached, return undefined */
+    if (remainingTtl === 0) {
+      return undefined;
+    }
+    /** If entry does not expire, return 0 */
+    if (remainingTtl > 1799999) {
+      return 0;
+    }
+
+    return remainingTtl;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async delValue(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async waitForReplication(replicas: number, timeout: number): Promise<number> {
+    return 0;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clearMemory(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /**
+   * @inheritdoc
+   * Dumb locking is supported for local development work
+   */
+  public isLockingSupported(): boolean {
+    return true;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async lock(resource: string, ttlMs: number): Promise<any> {
+    let isLocked = true;
+    const startTimestamp = Date.now()
+    while(isLocked) {
+      if (Date.now() - startTimestamp > LocalCache.LOCK_ACQUIRE_TIMEOUT) {
+        throw new Error(`Abandoning locking ${resource} , as timed out while waiting for other lock to be released.`)
+      }
+      this.cache.purgeStale()
+      if (!this.cache.has(resource)) {
+        isLocked = false;
+      } else {
+        // LRU keeps its TTL information private, so we don't know how long to wait.
+        // Whatever, we just loop on waiting a bit and retrying.
+        await sleep(10);
+      }
+    }
+    this.cache.set(resource, 1, { ttl: ttlMs });
+    return new Promise(resolve => { resolve(resource) });
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async unlock(lock: any): Promise<void> {
+    this.cache.delete(lock);
+    return new Promise(resolve => { resolve() });
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * Note that this specific implementation in `LocalCache` is not very efficient.
+   * Use RedisCache for a performant implementation.
+   */
+  public async hasLock(prefix: string): Promise<boolean> {
+    const startsWithPattern = prefix.replace(/\*$/, '');
+    let found = false;
+    this.cache.purgeStale();
+    this.cache.forEach((value, key) => {
+      // Doing a full CPU-inefficient traversal because `lru-cache.LRU` doesn't
+      // provide a `some` function or a way to exit this `forEach`. An alternative
+      // would be to work on `keys()`, which then would be RAM-inefficient.
+      // Neither is a big deal, this cache is meant to be used for small local/dev
+      // If this needs fixing, TODO move away from LRU.lru-cache.
+      if (key.startsWith(startsWithPattern)) {
+        found = true;
+      }
+    });
+    return new Promise((resolve) => { resolve(found) });
+  }
+
+}