@webreflection/utils 0.2.18 → 0.2.20

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.18",
+  "version": "0.2.20",
   "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
@@ -134,8 +163,10 @@ long as it provides compatible `parse(source)` and `stringify(value)` methods.
 ## registry
 
 A `Map` subclass that validates keys and values before storing them. By default,
-keys must be unique, so setting the same key twice throws a `TypeError`; pass
-`unique: false` when replacement should behave like a regular `Map`.
+keys are permanent: setting the same key twice throws a `TypeError`, and
+deleting an existing key also throws so it cannot be re-appended later. Pass
+`unique: false` when replacement and deletion should behave like a regular
+`Map`.
 
 ```js
 import Registry from '@webreflection/utils/registry';
@@ -171,10 +202,15 @@ const mutable = new Registry(
 
 console.log(mutable.get('answer'));
 // 42
+
+console.log(mutable.delete('answer'));
+// true
 ```
 
 Initial iterable entries are validated with the same rules used by `set()`, so
-invalid keys, invalid values, or duplicate keys fail during construction.
+invalid keys, invalid values, or duplicate keys fail during construction. With
+the default `unique: true` behavior, only missing keys can be passed to
+`delete()` without throwing, in which case it returns `false` like `Map`.
 
 
 ## shared-array-buffer

package/src/cache.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+/**
+ * @template K,V
+ * @type {(self: Cache<K,V>) => void}
+ */
+let cleanup;
+
+/**
+ * @template K,V
+ * @extends Map<K,V>
+ */
+export default class Cache extends Map {
+  static {
+    cleanup = self => {
+      self.#run = true;
+      self.#queue.splice(0).forEach(self.delete, self);
+    };
+  }
+
+  /** @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(() => cleanup(this));
+      }
+      else {
+        // @ts-ignore
+        setTimeout(cleanup, this.#delay, this);
+      }
+    }
+  }
+
+  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) {
+    return this.has(key) ? this.get(key) : this.put(key, value);
+  }
+
+  /**
+   * @param {K} key
+   * @param {(key: K) => V} callback
+   * @returns
+   */
+  getOrInsertComputed(key, callback) {
+    return this.has(key) ? this.get(key) : this.put(key, callback(key));
+  }
+
+  /**
+   * 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

@@ -8,11 +8,10 @@
 /**
  * @template [Key=unknown]
  * @template [Value=unknown]
- * @typedef {{
- *   key?: RegistryValidator<Key>,
- *   value?: RegistryValidator<Value>,
- *   unique?: boolean,
- * }} RegistryOptions
+ * @typedef {object} RegistryOptions
+ * @property {RegistryValidator<Key>} [key] Accepts or rejects candidate keys.
+ * @property {RegistryValidator<Value>} [value] Accepts or rejects candidate values.
+ * @property {boolean} [unique] When true, stored keys cannot be replaced or removed.
  */
 
 /**
@@ -30,7 +29,9 @@ const defaultOptions = {
 };
 
 /**
- * Map with optional key/value validation and duplicate-key protection.
+ * Map with optional key/value validation and permanent-key protection.
+ *
+ * When unique keys are enabled, stored keys cannot be replaced or deleted.
  *
  * @template [Key=unknown]
  * @template [Value=unknown]
@@ -49,6 +50,7 @@ export default class Registry extends Map {
   /**
    * @param {Iterable<[Key, Value]> | null} [iterable]
    * @param {RegistryOptions<Key, Value>} [options]
+   * @throws {TypeError} If an initial entry violates validation or uniqueness.
    */
   constructor(
     iterable,
@@ -66,10 +68,23 @@ export default class Registry extends Map {
     for (const [key, value] of iterable ?? []) this.set(key, value);
   }
 
+  /**
+   * Remove a key when unique-key protection is disabled.
+   *
+   * @param {Key} key
+   * @returns {boolean}
+   * @throws {TypeError} If the key exists and unique-key protection is enabled.
+   */
+  delete(key) {
+    if (this.#unique && super.has(key)) fail('Unable to remove key:', key);
+    return super.delete(key);
+  }
+
   /**
    * @param {Key} key
    * @param {Value} value
    * @returns {this}
+   * @throws {TypeError} If the key, value, or uniqueness check fails.
    */
   set(key, value) {
     if (!this.#key(key)) fail('Invalid key:', key);

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;
+}

package/types/registry.d.ts

@@ -1,5 +1,7 @@
 /**
- * Map with optional key/value validation and duplicate-key protection.
+ * Map with optional key/value validation and permanent-key protection.
+ *
+ * When unique keys are enabled, stored keys cannot be replaced or deleted.
  *
  * @template [Key=unknown]
  * @template [Value=unknown]
@@ -9,19 +11,30 @@ export default class Registry<Key = unknown, Value = unknown> extends Map<Key, V
     /**
      * @param {Iterable<[Key, Value]> | null} [iterable]
      * @param {RegistryOptions<Key, Value>} [options]
+     * @throws {TypeError} If an initial entry violates validation or uniqueness.
      */
     constructor(iterable?: Iterable<[Key, Value]> | null, options?: RegistryOptions<Key, Value>);
     /**
      * @param {Key} key
      * @param {Value} value
      * @returns {this}
+     * @throws {TypeError} If the key, value, or uniqueness check fails.
      */
     set(key: Key, value: Value): this;
     #private;
 }
 export type RegistryValidator<Type> = ((value: unknown) => value is Type) | ((value: unknown) => boolean);
 export type RegistryOptions<Key = unknown, Value = unknown> = {
-    key?: RegistryValidator<Key>;
-    value?: RegistryValidator<Value>;
-    unique?: boolean;
+    /**
+     * Accepts or rejects candidate keys.
+     */
+    key?: RegistryValidator<Key> | undefined;
+    /**
+     * Accepts or rejects candidate values.
+     */
+    value?: RegistryValidator<Value> | undefined;
+    /**
+     * When true, stored keys cannot be replaced or removed.
+     */
+    unique?: boolean | undefined;
 };