@thi.ng/cache 2.1.105 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-07T20:40:47Z
+- **Last updated**: 2024-03-11T10:09:24Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,25 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/cache@2.2.0) (2024-03-11)
+
+#### 🚀 Features
+
+- add value update callback, update TLRUCache ([d2fed06](https://github.com/thi-ng/umbrella/commit/d2fed06))
+  - add CacheOpts.update
+  - update doSetEntry() in all impls
+  - refactor TLRUCache.getSet() as async fn
+  - update TLRUCache.prune() to return eviction count
+  - various other refactoring
+  - add tests
+  - add docs
+
+### [2.1.106](https://github.com/thi-ng/umbrella/tree/@thi.ng/cache@2.1.106) (2024-03-11)
+
+#### 🩹 Bug fixes
+
+- fix ICache.get() return type, add docs ([d9f98f7](https://github.com/thi-ng/umbrella/commit/d9f98f7))
+
 ### [2.1.89](https://github.com/thi-ng/umbrella/tree/@thi.ng/cache@2.1.89) (2024-01-26)
 
 #### 🩹 Bug fixes

package/README.md

@@ -47,7 +47,8 @@ strategies](https://en.wikipedia.org/wiki/Cache_replacement_policies).
 - Supports any types for both keys & values
 - Customizable cache limits (no. of items / actual size)
 - Customizable key equality checks (@thi.ng/equiv by default)
-- Optional item release callbacks (to clean up resources when value is expunged)
+- Optional item update & release callbacks (e.g. to clean up resources when
+  value is being updated or evicted)
 
 ## Status
 
@@ -79,7 +80,7 @@ For Node.js REPL:
 const cache = await import("@thi.ng/cache");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.08 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.06 KB
 
 ## Dependencies
 
@@ -119,6 +120,10 @@ interface CacheOpts<K, V> {
      * Eviction callback to clean up resources
      */
     release: (k: K, v: V) => void;
+    /**
+     * Update callback to clean up resources
+     */
+    update: (k: K, vold: V, vnew: V) => void;
     /**
      * Factory for ES6 Map compatible instance
      * to index cache entries
@@ -137,13 +142,14 @@ interface CacheOpts<K, V> {
 
 ### LRU
 
-Removes least recently used items if a new item is added, but would not satisfy cache limit. Every time a cached item is accessed, it's recency is updated.
+Removes least recently used items if a new item is added, but would not satisfy
+cache limit. Every time a cached item is accessed, it's recency is updated.
 
 ```ts
-import * as cache from "@thi.ng/cache";
+import { LRUCache } from "@thi.ng/cache";
 
-// caches can be configured with maxLen, maxSize and sizing functions (see below)
-const lru = new cache.LRUCache<string, number>(null, { maxlen: 3 });
+// caches can be configured with maxlen, maxsize and sizing functions (see below)
+const lru = new LRUCache<string, number>(null, { maxlen: 3 });
 lru.set("foo", 23);
 lru.set("bar", 42);
 lru.set("baz", 66);
@@ -155,7 +161,7 @@ lru.get("foo");
 // 23
 
 // caches are fully iterable
-// largely intended for inspection, does not update recency
+// largely intended for inspection only, does not update recency
 // btw. "foo" appears last since most recently accessed
 [...lru]
 // [ { k: 'bar', v: 42, s: 0 },
@@ -172,12 +178,12 @@ lru.delete("foo");
 
 // caches have a getSet() method to obtain & store a new value
 // if its key is not known. this process is asynchronous
-lru.getSet("boo", () => Promise.resolve(999)).then(console.log);
+lru.getSet("boo", async () => 999).then(console.log);
 // 999
 
 // the given retrieval fn is only called if there's a cache miss
 // (not the case here). `getSet()` always returns a promise
-lru.getSet("boo", () => Promise.resolve(123)).then(console.log);
+lru.getSet("boo", async () => 123).then(console.log);
 // 999
 
 // caches can be limited by size instead of (or in addition to)
@@ -187,13 +193,14 @@ lru.getSet("boo", () => Promise.resolve(123)).then(console.log);
 // we also provide a release hook for demo purposes
 
 // the first arg is an iterable of KV pairs to store (just as for Map)
-lru = new cache.LRUCache<string, number[]>(
+lru = new LRUCache<string, number[]>(
     [ ["a", [1.0, 2.0]], ["b", [3.0, 4.0, 5.0]] ],
     {
         maxsize: 32,
         ksize: (k) => k.length,
         vsize: (v) => v.length * 8,
-        release: (k, v) => console.log("release", k, v)
+        release: (k, v) => console.log("release", k, v),
+        update: (k, vold, vnew) => console.log("update", k, vold, "->", vnew)
     }
 );
 // release a [1, 2] ("a" is evicted due to maxsize constraint)
@@ -206,19 +213,18 @@ lru.size
 
 ### TLRU
 
-Time-aware LRU cache. 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.
+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.
 
 ```ts
 import { TLRUCache } from "@thi.ng/cache";
 
-// same opts as LRUCache, but here with custom TTL period (in ms)
+// same opts as LRUCache, but here with custom default TTL period (in ms)
 tlru = new TLRUCache(null, { ttl: 10000 });
 
 // with item specific TTL (500ms)
@@ -227,7 +233,8 @@ tlru.set("foo", 42, 500)
 
 ### MRU
 
-Similar to LRU, but removes most recently accessed items first. [Wikipedia](https://en.wikipedia.org/wiki/Cache_replacement_policies#Most_recently_used_(MRU))
+Similar to LRU, but removes most recently accessed items first.
+[Wikipedia](https://en.wikipedia.org/wiki/Cache_replacement_policies#Most_recently_used_(MRU))
 
 ```ts
 import { MRUCache } from "@thi.ng/cache";

package/api.d.ts

@@ -1,21 +1,94 @@
-import type { Fn, Fn0, Fn2, ICopy, IEmpty, ILength, IRelease } from "@thi.ng/api";
+import type { Fn, Fn0, Fn2, Fn3, ICopy, IEmpty, ILength, IRelease } from "@thi.ng/api";
 export interface ICache<K, V> extends Iterable<Readonly<[K, CacheEntry<K, V>]>>, ICopy<ICache<K, V>>, IEmpty<ICache<K, V>>, ILength, IRelease {
     readonly size: number;
+    /**
+     * Returns true if the given `key` is currently in the cache.
+     *
+     * @param key
+     */
     has(key: K): boolean;
-    get(key: K, notFound?: V): V;
+    /**
+     * Looks up value for given `key` and if cached returns it. For cache
+     * misses, returns the optional `notFound` value or else `undefined`.
+     *
+     * @param key
+     * @param notFound
+     */
+    get(key: K, notFound?: V): V | undefined;
+    /**
+     * Set or updates value for given `key` and updates cache internal
+     * statistics (depending on cache policy).
+     *
+     * @param key
+     * @param val
+     */
     set(key: K, val: V): V;
+    /**
+     * Combination of {@link ICache.get} and {@link ICache.set}. Looks up the
+     * value for given `key` and returns it. In case of a cache miss, calls
+     * given `fn` to provide a value for the `key` and then stores it in the
+     * cache before returning that value.
+     *
+     * @param key
+     * @param fn
+     */
     getSet(key: K, fn: Fn0<Promise<V>>): Promise<V>;
+    /**
+     * Evicts cache entry for given `key` and returns true if the `key` was
+     * still cached. If that's the case and if {@link CacheOpts.release} was
+     * given when the cache was created, also calls that user provided release
+     * handler to perform custom clean up tasks.
+     *
+     * @param key
+     */
     delete(key: K): boolean;
+    /**
+     * Returns an iterator of cache entries.
+     */
     entries(): IterableIterator<Readonly<[K, CacheEntry<K, V>]>>;
+    /**
+     * Returns an iterator of currently cached keys.
+     */
     keys(): IterableIterator<Readonly<K>>;
+    /**
+     * Returns an iterator of currently cached values.
+     */
     values(): IterableIterator<Readonly<V>>;
 }
 export interface CacheOpts<K, V> {
+    /**
+     * Function to compute the size of a given key in arbitrary user defined
+     * units (must be same unit as given to {@link CacheOpts.maxsize}).
+     */
     ksize: Fn<K, number>;
+    /**
+     * Function to compute the size of a given value in arbitrary user defined
+     * units (must be same unit as given to {@link CacheOpts.maxsize}).
+     */
     vsize: Fn<V, number>;
+    /**
+     * Callback function to perform custom tasks when an item gets evicted from
+     * the cache.
+     */
     release: Fn2<K, V, void>;
+    /**
+     * Callback function to perform custom tasks when an item gets updated in the cache.
+     * The function will be called with a key and its associated old and news values.
+     */
+    update: Fn3<K, V, V, void>;
+    /**
+     * Custom ES6 Map compatible implementation to use as the cache's backing
+     * store.
+     */
     map: Fn0<Map<K, any>>;
+    /**
+     * Max number of items in the cache.
+     */
     maxlen: number;
+    /**
+     * Cache max size in arbitrary user defined units (must be same unit as
+     * given to {@link CacheOpts.ksize} and/or {@link CacheOpts.vsize}).
+     */
     maxsize: number;
 }
 export interface CacheEntry<K, V> {

package/lru.d.ts

@@ -1,4 +1,4 @@
-import type { Fn0 } from "@thi.ng/api";
+import type { Fn0, Nullable } from "@thi.ng/api";
 import type { ConsCell } from "@thi.ng/dcons";
 import { DCons } from "@thi.ng/dcons/dcons";
 import type { CacheEntry, CacheOpts, ICache } from "./api.js";
@@ -7,7 +7,7 @@ export declare class LRUCache<K, V> implements ICache<K, V> {
     protected items: DCons<CacheEntry<K, V>>;
     protected opts: CacheOpts<K, V>;
     protected _size: number;
-    constructor(pairs?: Iterable<[K, V]> | null, opts?: Partial<CacheOpts<K, V>>);
+    constructor(pairs: Nullable<Iterable<[K, V]>>, opts?: Partial<CacheOpts<K, V>>);
     get length(): number;
     get size(): number;
     [Symbol.iterator](): IterableIterator<readonly [K, CacheEntry<K, V>]>;
@@ -18,7 +18,7 @@ export declare class LRUCache<K, V> implements ICache<K, V> {
     empty(): LRUCache<K, V>;
     release(): boolean;
     has(key: K): boolean;
-    get(key: K, notFound?: any): any;
+    get(key: K, notFound?: V): V | undefined;
     set(key: K, value: V): V;
     into(pairs: Iterable<[K, V]>): this;
     getSet(key: K, retrieve: Fn0<Promise<V>>): Promise<V>;

package/lru.js

@@ -6,16 +6,14 @@ class LRUCache {
   opts;
   _size;
   constructor(pairs, opts) {
-    const _opts = Object.assign(
-      {
-        maxlen: Infinity,
-        maxsize: Infinity,
-        map: () => /* @__PURE__ */ new Map(),
-        ksize: () => 0,
-        vsize: () => 0
-      },
-      opts
-    );
+    const _opts = {
+      maxlen: Infinity,
+      maxsize: Infinity,
+      map: () => /* @__PURE__ */ new Map(),
+      ksize: () => 0,
+      vsize: () => 0,
+      ...opts
+    };
     this.map = _opts.map();
     this.items = new DCons();
     this._size = 0;
@@ -73,10 +71,7 @@ class LRUCache {
   }
   get(key, notFound) {
     const e = this.map.get(key);
-    if (e) {
-      return this.resetEntry(e);
-    }
-    return notFound;
+    return e ? this.resetEntry(e) : notFound;
   }
   set(key, value) {
     const size = this.opts.ksize(key) + this.opts.vsize(value);
@@ -96,12 +91,9 @@ class LRUCache {
     }
     return this;
   }
-  getSet(key, retrieve) {
+  async getSet(key, retrieve) {
     const e = this.map.get(key);
-    if (e) {
-      return Promise.resolve(this.resetEntry(e));
-    }
-    return retrieve().then((v) => this.set(key, v));
+    return e ? this.resetEntry(e) : this.set(key, await retrieve());
   }
   delete(key) {
     const e = this.map.get(key);
@@ -116,16 +108,13 @@ class LRUCache {
     return e.value.v;
   }
   ensureSize() {
-    const release = this.opts.release;
-    const maxs = this.opts.maxsize;
-    const maxl = this.opts.maxlen;
-    while (this._size > maxs || this.length >= maxl) {
+    const { release, maxsize, maxlen } = this.opts;
+    while (this._size > maxsize || this.length >= maxlen) {
       const e = this.items.drop();
-      if (!e) {
+      if (!e)
         return false;
-      }
       this.map.delete(e.k);
-      release && release(e.k, e.v);
+      release?.(e.k, e.v);
       this._size -= e.s;
     }
     return true;
@@ -134,11 +123,12 @@ class LRUCache {
     const ee = e.value;
     this.map.delete(ee.k);
     this.items.remove(e);
-    this.opts.release && this.opts.release(ee.k, ee.v);
+    this.opts.release?.(ee.k, ee.v);
     this._size -= ee.s;
   }
   doSetEntry(e, k, v, s) {
     if (e) {
+      this.opts.update?.(k, e.value.v, v);
       e.value.v = v;
       e.value.s = s;
       this.items.asTail(e);

package/mru.d.ts

@@ -1,8 +1,7 @@
 import type { ConsCell } from "@thi.ng/dcons";
-import type { CacheEntry, CacheOpts } from "./api.js";
+import type { CacheEntry } from "./api.js";
 import { LRUCache } from "./lru.js";
 export declare class MRUCache<K, V> extends LRUCache<K, V> {
-    constructor(pairs?: Iterable<[K, V]> | null, opts?: Partial<CacheOpts<K, V>>);
     empty(): MRUCache<K, V>;
     protected resetEntry(e: ConsCell<CacheEntry<K, V>>): V;
     protected doSetEntry(e: ConsCell<CacheEntry<K, V>> | undefined, k: K, v: V, s: number): void;

package/mru.js

@@ -1,8 +1,5 @@
 import { LRUCache } from "./lru.js";
 class MRUCache extends LRUCache {
-  constructor(pairs, opts) {
-    super(pairs, opts);
-  }
   empty() {
     return new MRUCache(null, this.opts);
   }
@@ -12,6 +9,7 @@ class MRUCache extends LRUCache {
   }
   doSetEntry(e, k, v, s) {
     if (e) {
+      this.opts.update?.(k, e.value.v, v);
       e.value.v = v;
       e.value.s = s;
       this.items.asHead(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/cache",
-  "version": "2.1.105",
+  "version": "2.2.0",
   "description": "In-memory cache implementations with ES6 Map-like API and different eviction strategies",
   "type": "module",
   "module": "./index.js",
@@ -91,5 +91,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "69100942474942f7446ac645d59d91e7dfc352f9\n"
+  "gitHead": "8c206a7a1aa00822e5adedb67d922591648f7ced\n"
 }

package/tlru.d.ts

@@ -1,8 +1,14 @@
-import type { Fn0 } from "@thi.ng/api";
+import type { Fn0, Nullable } from "@thi.ng/api";
 import type { ConsCell, DCons } from "@thi.ng/dcons";
 import type { CacheEntry, CacheOpts } from "./api.js";
 import { LRUCache } from "./lru.js";
 export interface TLRUCacheOpts<K, V> extends CacheOpts<K, V> {
+    /**
+     * Default time-to-live (cache period in milliseconds) before an entry is
+     * considered expired.
+     *
+     * @defaultValue 3600000 (1 hour)
+     */
     ttl: number;
 }
 export interface TLRUCacheEntry<K, V> extends CacheEntry<K, V> {
@@ -26,14 +32,23 @@ export declare class TLRUCache<K, V> extends LRUCache<K, V> {
     protected opts: TLRUCacheOpts<K, V>;
     protected map: Map<K, ConsCell<TLRUCacheEntry<K, V>>>;
     protected items: DCons<TLRUCacheEntry<K, V>>;
-    constructor(pairs?: Iterable<[K, V]> | null, opts?: Partial<TLRUCacheOpts<K, V>>);
+    constructor(pairs: Nullable<Iterable<[K, V]>>, opts?: Partial<TLRUCacheOpts<K, V>>);
     empty(): TLRUCache<K, V>;
     has(key: K): boolean;
-    get(key: K, notFound?: any): any;
+    get(key: K, notFound?: V): V | undefined;
     set(key: K, value: V, ttl?: number): V;
     getSet(key: K, retrieve: Fn0<Promise<V>>, ttl?: number): Promise<V>;
-    prune(): void;
+    /**
+     * Scans all cached entries and evicts any which are expired by now (based
+     * on their TTL). Does **not** modify last-accessed time of remaining
+     * entries. Returns number of entries evicted.
+     *
+     * @remarks
+     * For very large caches, it's recommended to call this function in a
+     * cron-like manner...
+     */
+    prune(): number;
     protected ensureSize(): boolean;
-    protected doSetTlruEntry(e: ConsCell<TLRUCacheEntry<K, V>> | undefined, k: K, v: V, s: number, t: number): void;
+    protected doSetEntry(e: ConsCell<TLRUCacheEntry<K, V>> | undefined, k: K, v: V, s: number, ttl?: number): void;
 }
 //# sourceMappingURL=tlru.d.ts.map

package/tlru.js

@@ -1,8 +1,7 @@
 import { LRUCache } from "./lru.js";
 class TLRUCache extends LRUCache {
   constructor(pairs, opts) {
-    opts = Object.assign({ ttl: 60 * 60 * 1e3 }, opts);
-    super(pairs, opts);
+    super(pairs, { ttl: 60 * 60 * 1e3, ...opts });
   }
   empty() {
     return new TLRUCache(null, this.opts);
@@ -26,36 +25,43 @@ class TLRUCache extends LRUCache {
     const additionalSize = Math.max(0, size - (e ? e.value.s : 0));
     this._size += additionalSize;
     if (this.ensureSize()) {
-      const t = Date.now() + ttl;
-      this.doSetTlruEntry(e, key, value, size, t);
+      this.doSetEntry(e, key, value, size, ttl);
     } else {
       this._size -= additionalSize;
     }
     return value;
   }
-  getSet(key, retrieve, ttl = this.opts.ttl) {
+  async getSet(key, retrieve, ttl = this.opts.ttl) {
     const e = this.get(key);
-    if (e) {
-      return Promise.resolve(e);
-    }
-    return retrieve().then((v) => this.set(key, v, ttl));
+    return e !== void 0 ? e : this.set(key, await retrieve(), ttl);
   }
+  /**
+   * Scans all cached entries and evicts any which are expired by now (based
+   * on their TTL). Does **not** modify last-accessed time of remaining
+   * entries. Returns number of entries evicted.
+   *
+   * @remarks
+   * For very large caches, it's recommended to call this function in a
+   * cron-like manner...
+   */
   prune() {
     const now = Date.now();
     let cell = this.items.head;
+    let count = 0;
     while (cell) {
       if (cell.value.t < now) {
         this.removeEntry(cell);
+        count++;
       }
       cell = cell.next;
     }
+    return count;
   }
   ensureSize() {
-    const maxs = this.opts.maxsize;
-    const maxl = this.opts.maxlen;
+    const { maxlen, maxsize } = this.opts;
     const now = Date.now();
     let cell = this.items.head;
-    while (cell && (this._size > maxs || this.length >= maxl)) {
+    while (cell && (this._size > maxsize || this.length >= maxlen)) {
       if (cell.value.t < now) {
         this.removeEntry(cell);
       }
@@ -63,8 +69,10 @@ class TLRUCache extends LRUCache {
     }
     return super.ensureSize();
   }
-  doSetTlruEntry(e, k, v, s, t) {
+  doSetEntry(e, k, v, s, ttl = this.opts.ttl) {
+    const t = Date.now() + ttl;
     if (e) {
+      this.opts.update?.(k, e.value.v, v);
       e.value.v = v;
       e.value.s = s;
       e.value.t = t;