@thi.ng/cache 2.1.104 → 2.1.106

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-07T20:40:47Z
+- **Last updated**: 2024-03-11T08:41:23Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.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/api.d.ts

@@ -1,21 +1,89 @@
 import type { Fn, Fn0, Fn2, 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> {
+    /**
+     * Key size in arbitrary user defined units (must be same unit as given to
+     * {@link CacheOpts.maxSize}).
+     */
     ksize: Fn<K, number>;
+    /**
+     * Value size in arbitrary user defined units (must be same unit as given to
+     * {@link CacheOpts.maxSize}).
+     */
     vsize: Fn<V, number>;
+    /**
+     * Function to perform custom cleanup tasks when an item gets evicted from
+     * the cache.
+     */
     release: Fn2<K, 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

@@ -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

@@ -96,12 +96,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/cache",
-  "version": "2.1.104",
+  "version": "2.1.106",
   "description": "In-memory cache implementations with ES6 Map-like API and different eviction strategies",
   "type": "module",
   "module": "./index.js",
@@ -36,9 +36,9 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.28",
-    "@thi.ng/dcons": "^3.2.99",
-    "@thi.ng/transducers": "^8.9.10"
+    "@thi.ng/api": "^8.9.29",
+    "@thi.ng/dcons": "^3.2.100",
+    "@thi.ng/transducers": "^8.9.11"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
@@ -91,5 +91,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "a421058a65ba76608d94129ac29451bfedaf201c\n"
+  "gitHead": "aadddd399541d69266672a5815a3f28359a71425\n"
 }

package/tlru.d.ts

@@ -29,7 +29,7 @@ export declare class TLRUCache<K, V> extends LRUCache<K, V> {
     constructor(pairs?: Iterable<[K, V]> | null, 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;