@thi.ng/cache 2.2.21 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-07-22T13:15:57Z
+- **Last updated**: 2024-07-28T10:53:10Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/cache@2.3.0) (2024-07-28)
+
+#### 🚀 Features
+
+- add `TLRUCacheOpts.autoExtend` option ([9fbda4c](https://github.com/thi-ng/umbrella/commit/9fbda4c))
+  - add support to auto-extend TTL of cached values upon cache hit
+  - add tests
+  - add/update docs
+  - update readme
+
 ### [2.2.11](https://github.com/thi-ng/umbrella/tree/@thi.ng/cache@2.2.11) (2024-04-20)
 
 #### ♻️ Refactoring

package/README.md

@@ -86,7 +86,7 @@ For Node.js REPL:
 const cache = await import("@thi.ng/cache");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.05 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.09 KB
 
 ## Dependencies
 
@@ -221,18 +221,24 @@ lru.size
 ### TLRU
 
 Time-aware [LRU cache](#lru). Extends LRU strategy with TTL (time-to-live)
-values associated with each entry. `has()` will only return `true` and `get()`
-only returns a cached value if its TTL hasn't yet expired. When adding a new
-value to the cache, first removes expired entries and if there's still not
-sufficient space removes entries in LRU order. `set()` takes an optional entry
-specific `ttl` arg. If not given, uses the cache instance's default (provided
-via ctor option arg). If no instance TTL is given, TTL defaults to 1 hour.
+values associated with each entry, which has an impact on:
+
+- `has()` only returns `true` if a cached value's TTL hasn't yet expired
+- `get()` only returns a cached value if its TTL hasn't yet expired. Using the
+  `autoExtend` option given via the cache constructor options, the cache can be
+  configured such that a successful cache hit will update/extend the expiry time
+  of that respective entry.
+- `set()` takes an optional entry specific `ttl` arg. If not given, uses the
+  cache's default (provided via ctor option arg). Default TTL is 1 hour.
+
+When adding a new value to the cache, first removes expired entries and if
+there's still not sufficient space removes entries in LRU order.
 
 ```ts
 import { TLRUCache } from "@thi.ng/cache";
 
-// same opts as LRUCache, but here with custom default TTL period (in ms)
-tlru = new TLRUCache(null, { ttl: 10000 });
+// same opts as LRUCache, but here with additional custom TTL period (in ms)
+tlru = new TLRUCache(null, { ttl: 10000, autoExtend: true });
 
 // with item specific TTL (500ms)
 tlru.set("foo", 42, 500)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/cache",
-  "version": "2.2.21",
+  "version": "2.3.0",
   "description": "In-memory cache implementations with ES6 Map-like API and different eviction strategies",
   "type": "module",
   "module": "./index.js",
@@ -89,5 +89,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "bd22b0826134b79064169371665b4d6caa9b6066\n"
+  "gitHead": "c8461a678e3c0d496dfde24b8c494845d7514cc0\n"
 }

package/tlru.d.ts

@@ -10,9 +10,26 @@ export interface TLRUCacheOpts<K, V> extends CacheOpts<K, V> {
      * @defaultValue 3600000 (1 hour)
      */
     ttl: number;
+    /**
+     * If true, a cache hit (i.e. reading a cached value via
+     * {@link TLRUCache.get}) will auto-extend the expiry time for that cache
+     * entry.
+     *
+     * @defaultValue false
+     */
+    autoExtend: boolean;
 }
 export interface TLRUCacheEntry<K, V> extends CacheEntry<K, V> {
+    /**
+     * Expiry timestamp
+     */
     t: number;
+    /**
+     * TTL for this entry (defaults to {@link TLRUCacheOpts.ttl}, but can be
+     * customized per key via {@link TLRUCache.set} or
+     * {@link TLRUCache.getSet}).
+     */
+    ttl: number;
 }
 /**
  * Time-aware LRU cache. Extends LRU strategy with TTL (time-to-live)
@@ -35,7 +52,28 @@ export declare class TLRUCache<K, V> extends LRUCache<K, V> {
     constructor(pairs?: Nullable<Iterable<[K, V]>>, opts?: Partial<TLRUCacheOpts<K, V>>);
     empty(): TLRUCache<K, V>;
     has(key: K): boolean;
+    /**
+     * Attempts to retrieve & return cached value for `key`. If found, also
+     * resets the cache entry's configured TTL. If cache miss, returns
+     * `notFound`.
+     *
+     * @param key
+     * @param notFound
+     */
     get(key: K, notFound?: V): V | undefined;
+    /**
+     * Stores given `value` under `key` in the cache, optionally with custom
+     * `ttl` (in milliseconds). Returns `value`.
+     *
+     * @remarks
+     * Also see {@link TLRUCache.getSet} for alternative, and
+     * {@link CacheOpts.update} for user callback when updating an existing
+     * `key` in the cache.
+     *
+     * @param key
+     * @param value
+     * @param ttl
+     */
     set(key: K, value: V, ttl?: number): V;
     getSet(key: K, retrieve: Fn0<Promise<V>>, ttl?: number): Promise<V>;
     /**
@@ -50,5 +88,6 @@ export declare class TLRUCache<K, V> extends LRUCache<K, V> {
     prune(): number;
     protected ensureSize(): boolean;
     protected doSetEntry(e: Maybe<ConsCell<TLRUCacheEntry<K, V>>>, k: K, v: V, s: number, ttl?: number): void;
+    protected resetEntry(e: ConsCell<TLRUCacheEntry<K, V>>): V;
 }
 //# sourceMappingURL=tlru.d.ts.map

package/tlru.js

@@ -1,7 +1,7 @@
 import { LRUCache } from "./lru.js";
 class TLRUCache extends LRUCache {
   constructor(pairs, opts) {
-    super(pairs, { ttl: 60 * 60 * 1e3, ...opts });
+    super(pairs, { ttl: 60 * 60 * 1e3, autoExtend: false, ...opts });
   }
   empty() {
     return new TLRUCache(null, this.opts);
@@ -9,6 +9,14 @@ class TLRUCache extends LRUCache {
   has(key) {
     return this.get(key) !== void 0;
   }
+  /**
+   * Attempts to retrieve & return cached value for `key`. If found, also
+   * resets the cache entry's configured TTL. If cache miss, returns
+   * `notFound`.
+   *
+   * @param key
+   * @param notFound
+   */
   get(key, notFound) {
     const e = this.map.get(key);
     if (e) {
@@ -19,6 +27,19 @@ class TLRUCache extends LRUCache {
     }
     return notFound;
   }
+  /**
+   * Stores given `value` under `key` in the cache, optionally with custom
+   * `ttl` (in milliseconds). Returns `value`.
+   *
+   * @remarks
+   * Also see {@link TLRUCache.getSet} for alternative, and
+   * {@link CacheOpts.update} for user callback when updating an existing
+   * `key` in the cache.
+   *
+   * @param key
+   * @param value
+   * @param ttl
+   */
   set(key, value, ttl = this.opts.ttl) {
     const size = this.opts.ksize(key) + this.opts.vsize(value);
     const e = this.map.get(key);
@@ -78,10 +99,16 @@ class TLRUCache extends LRUCache {
       e.value.t = t;
       this.items.asTail(e);
     } else {
-      this.items.push({ k, v, s, t });
+      this.items.push({ k, v, s, t, ttl });
       this.map.set(k, this.items.tail);
     }
   }
+  resetEntry(e) {
+    if (this.opts.autoExtend) {
+      e.value.t = Date.now() + e.value.ttl;
+    }
+    return super.resetEntry(e);
+  }
 }
 export {
   TLRUCache