@webreflection/utils 0.2.19 → 0.2.21

package/README.md

@@ -11,6 +11,7 @@ A curated, *TypeScript*-friendly [collection](./src/) of utilities:
   * **[ascii](./src#ascii)** - basic string-to-buffer conversion without validation
   * **[bound-once](./src#bound-once)** - retrieve unique bound methods per realm
   * **[bound](./src#bound)** - retrieve one-off bound methods
+  * **[cache](./src#cache)** - use a temporal `Map` to reuse repeated key lookups within the same tick, or for a short timed window
   * **[iterable](./src#iterable)** - make plain objects iterable as `Object.entries(object)` pairs, without touching objects that are already iterable
   * **[json-storage](./src#json-storage)** - use `localStorage` or `sessionStorage` through a JSON-aware, iterable, *Map*-friendly API
   * **[registry](./src#registry)** - use a `Map`-like API with key/value validation and duplicate-key protection by default

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "type": "module",
   "types": {
     "./all": "./types/all.d.ts",
     "./ascii": "./types/ascii.d.ts",
     "./bound-once": "./types/bound-once.d.ts",
     "./bound": "./types/bound.d.ts",
+    "./cache": "./types/cache.d.ts",
     "./iterable": "./types/iterable.d.ts",
     "./json-storage": "./types/json-storage.d.ts",
     "./registry": "./types/registry.d.ts",
@@ -31,6 +32,10 @@
       "types": "./types/bound.d.ts",
       "import": "./src/bound.js"
     },
+    "./cache": {
+      "types": "./types/cache.d.ts",
+      "import": "./src/cache.js"
+    },
     "./iterable": {
       "types": "./types/iterable.d.ts",
       "import": "./src/iterable.js"
@@ -62,6 +67,7 @@
     "ascii",
     "bound-once",
     "bound",
+    "cache",
     "iterable",
     "json-storage",
     "registry",
@@ -96,7 +102,7 @@
   "bugs": {
     "url": "https://github.com/WebReflection/utils/issues"
   },
-  "homepage": "https://github.com/WebReflection/utils#readme",
+  "homepage": "https://webreflection.github.io/utils/",
   "overrides": {
     "c8": {
       "yargs": "^18.0.0"

package/src/README.md

@@ -1,6 +1,6 @@
 # @webreflection/utils
 
-Each utility can be loaded from a *CDN* via either `https://esm.run/@webreflection/utils/{{UTILITY}}` or `https://cdn.jsdelivr.net/npm/@webreflection/utils/src/{{UTILITY}}.js`.
+Each utility can be loaded from a *CDN* via either `https://esm.run/@webreflection/utils/UTILITY` or `https://cdn.jsdelivr.net/npm/@webreflection/utils/src/UTILITY.js`.
 
 
 This document describes each utility separately.
@@ -53,7 +53,7 @@ whatever argument limit your runtime has for `String.fromCharCode`.
 
 This is equivalent to **bound**, except each bound method is created only once. It is useful when bound method identity must be preserved across multiple calls.
 
-This variant uses **sticky** to ensure that weakly referenced targets always produce the same bound method within the same realm.
+This variant uses [sticky](#sticky) to ensure that weakly referenced targets always produce the same bound method within the same realm.
 
 
 ## bound
@@ -71,6 +71,35 @@ resolve(4);
 The **bound-once** variant ensures that repeated accesses, such as `boundOnce(Promise).all`, always return the same bound method.
 
 
+## cache
+
+A temporal `Map` subclass for short-lived memoization. It keeps newly added
+entries only until its scheduled cleanup runs, making it useful to reuse
+expensive work for repeated access to the same key without keeping the value
+around as a long-term cache.
+
+```js
+import Cache from '@webreflection/utils/cache';
+
+const users = new Cache;
+
+const loadUser = id => users.getOrInsertComputed(
+  id,
+  id => fetch(`/users/${id}`).then(response => response.json())
+);
+```
+
+When the constructor `delay` is omitted, `0`, or less than `0`, cleanup is
+queued as a microtask, so same-tick lookups can share the stored value and the
+map clears itself before the next task. Pass a positive delay, such as
+`new Cache(100)`, to keep entries until a timer removes them instead.
+
+Use `getOrInsert(key, value)` or `getOrInsertComputed(key, callback)` when the
+value should only be stored if missing. Use `put(key, value)` for the faster
+`cache.get(key) ?? cache.put(key, value)` pattern when duplicate queue entries
+are acceptable.
+
+
 ## iterable
 
 Ensures an object can be consumed by `for...of`, spread, `Array.from`, and

package/src/cache.js

@@ -0,0 +1,101 @@
+// @ts-check
+
+/**
+ * @template K,V
+ * @extends Map<K,V>
+ */
+export default class Cache extends Map {
+  /**
+   * @template K,V
+   * @type {(self: Cache<K,V>) => void}
+   */
+  #cleanup = () => {
+    this.#run = true;
+    this.#queue.splice(0).forEach(this.delete, this);
+  };
+
+  /** @type {number} */
+  #delay;
+
+  /** @type {K[]} */
+  #queue = [];
+
+  /** @type {boolean} */
+  #run = true;
+
+  /**
+   * @param {K} key
+   */
+  #push(key) {
+    this.#queue.push(key);
+    if (this.#run) {
+      this.#run = false;
+      if (this.#delay < 1) {
+        // @ts-ignore
+        queueMicrotask(this.#cleanup);
+      }
+      else {
+        // @ts-ignore
+        setTimeout(this.#cleanup, this.#delay);
+      }
+    }
+  }
+
+  clear() {
+    this.#queue.splice(0);
+    super.clear();
+  }
+
+  /**
+   * @param {number} [delay]
+   */
+  constructor(delay = 0) {
+    super();
+    this.#delay = delay;
+  }
+
+  /**
+   * @param {K} key
+   * @param {V} value
+   * @returns
+   */
+  getOrInsert(key, value) {
+    const known = this.get(key);
+    return known === void 0 && !this.has(key) ? this.put(key, value) : known;
+  }
+
+  /**
+   * @param {K} key
+   * @param {(key: K) => V} callback
+   * @returns
+   */
+  getOrInsertComputed(key, callback) {
+    const known = this.get(key);
+    return known === void 0 && !this.has(key) ? this.put(key, callback(key)) : known;
+  }
+
+  /**
+   * This method is slightly faster than `getOrInsert` or `getOrInsertComputed`
+   * but it does not check if the key already exists, possibly pushing it twice.
+   * However, doing `ref.get(key) ?? ref.put(key, value)` provides same functionality as
+   * `ref.getOrInsert(key, value)` or `ref.getOrInsertComputed(key, callback)`.
+   * @param {K} key
+   * @param {V} value
+   * @returns
+   */
+  put(key, value) {
+    this.#push(key);
+    super.set(key, value);
+    return value;
+  }
+
+  /**
+   * @param {K} key
+   * @param {V} value
+   * @returns
+   */
+  set(key, value) {
+    if (!this.has(key)) this.#push(key);
+    return super.set(key, value);
+  }
+}

package/src/index.md

@@ -0,0 +1,6 @@
+---
+title: Utilities
+permalink: /src/
+---
+
+{% include_relative README.md %}

package/src/registry.js

@@ -68,6 +68,11 @@ export default class Registry extends Map {
     for (const [key, value] of iterable ?? []) this.set(key, value);
   }
 
+  clear() {
+    if (this.#unique) fail('Unable to clear registry with unique keys');
+    super.clear();
+  }
+
   /**
    * Remove a key when unique-key protection is disabled.
    *
@@ -88,8 +93,8 @@ export default class Registry extends Map {
    */
   set(key, value) {
     if (!this.#key(key)) fail('Invalid key:', key);
-    if (this.#unique && super.has(key)) fail('Duplicate key:', key);
     if (!this.#value(value)) fail('Invalid value:', value);
+    if (this.#unique && super.has(key)) fail('Duplicate key:', key);
     return super.set(key, value);
   }
 }

package/types/cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @template K,V
+ * @extends Map<K,V>
+ */
+export default class Cache<K, V> extends Map<K, V> {
+    /**
+     * @param {number} [delay]
+     */
+    constructor(delay?: number);
+    /**
+     * @param {K} key
+     * @param {V} value
+     * @returns
+     */
+    getOrInsert(key: K, value: V): V | undefined;
+    /**
+     * @param {K} key
+     * @param {(key: K) => V} callback
+     * @returns
+     */
+    getOrInsertComputed(key: K, callback: (key: K) => V): V | undefined;
+    /**
+     * This method is slightly faster than `getOrInsert` or `getOrInsertComputed`
+     * but it does not check if the key already exists, possibly pushing it twice.
+     * However, doing `ref.get(key) ?? ref.put(key, value)` provides same functionality as
+     * `ref.getOrInsert(key, value)` or `ref.getOrInsertComputed(key, callback)`.
+     * @param {K} key
+     * @param {V} value
+     * @returns
+     */
+    put(key: K, value: V): V;
+    /**
+     * @param {K} key
+     * @param {V} value
+     * @returns
+     */
+    set(key: K, value: V): this;
+    #private;
+}