@webreflection/utils 0.2.16 → 0.2.17

package/README.md

@@ -2,19 +2,20 @@
 
 [![Coverage Status](https://coveralls.io/repos/github/WebReflection/utils/badge.svg?branch=main)](https://coveralls.io/github/WebReflection/utils?branch=main)
 
-<sup>**Social Media Photo by [benjamin lehman](https://unsplash.com/@abject) on [Unsplash](https://unsplash.com/)**</sup>
+<sup>**Social media photo by [Benjamin Lehman](https://unsplash.com/@abject) on [Unsplash](https://unsplash.com/)**</sup>
 
 
-A curated, *TypeScript* friendly, [collection](./src/) of utilities:
+A curated, *TypeScript*-friendly [collection](./src/) of utilities:
 
   * **[all](https://github.com/WebReflection/utils/tree/main/src#all)** - `Promise.all` via object destructuring
-  * **[ascii](https://github.com/WebReflection/utils/tree/main/src#ascii)** - basic string to buffer conversion (without validation)
-  * **[bound-once](https://github.com/WebReflection/utils/tree/main/src#bound-once)** - to retrieve unique bound methods per realm
-  * **[bound](https://github.com/WebReflection/utils/tree/main/src#bound)** - to retrieve one-off bound methods
-  * **[iterable](https://github.com/WebReflection/utils/tree/main/src#iterable)** - to make plain objects iterable as `Object.entries(object)` pairs, without touching objects that already are iterable
-  * **[json-storage](https://github.com/WebReflection/utils/tree/main/src#json-storage)** - to use `localStorage` or `sessionStorage` through a JSON-aware, iterable, *Map* friendly API
-  * **[shared-array-buffer](https://github.com/WebReflection/utils/tree/main/src#shared-array-buffer)** - to simulate *SAB* when not available
-  * **[sticky](https://github.com/WebReflection/utils/tree/main/src#sticky)** - to stick once per realm anything useful
-  * **[with-resolvers](https://github.com/WebReflection/utils/tree/main/src#with-resolvers)** - a self bound `Promise.withResolver()` for older runtimes
+  * **[ascii](https://github.com/WebReflection/utils/tree/main/src#ascii)** - basic string-to-buffer conversion without validation
+  * **[bound-once](https://github.com/WebReflection/utils/tree/main/src#bound-once)** - retrieve unique bound methods per realm
+  * **[bound](https://github.com/WebReflection/utils/tree/main/src#bound)** - retrieve one-off bound methods
+  * **[iterable](https://github.com/WebReflection/utils/tree/main/src#iterable)** - make plain objects iterable as `Object.entries(object)` pairs, without touching objects that are already iterable
+  * **[json-storage](https://github.com/WebReflection/utils/tree/main/src#json-storage)** - use `localStorage` or `sessionStorage` through a JSON-aware, iterable, *Map*-friendly API
+  * **[registry](https://github.com/WebReflection/utils/tree/main/src#registry)** - use a `Map`-like API with key/value validation and duplicate-key protection by default
+  * **[shared-array-buffer](https://github.com/WebReflection/utils/tree/main/src#shared-array-buffer)** - simulate *SAB* when not available
+  * **[sticky](https://github.com/WebReflection/utils/tree/main/src#sticky)** - keep useful values stable once per realm
+  * **[with-resolvers](https://github.com/WebReflection/utils/tree/main/src#with-resolvers)** - use a self-bound `Promise.withResolvers()` helper for older runtimes
 
-MIT style License.
+MIT-style license.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "type": "module",
   "types": {
     "./all": "./types/all.d.ts",
@@ -36,6 +36,10 @@
       "types": "./types/json-storage.d.ts",
       "import": "./src/json-storage.js"
     },
+    "./registry": {
+      "types": "./types/registry.d.ts",
+      "import": "./src/registry.js"
+    },
     "./shared-array-buffer": {
       "types": "./types/shared-array-buffer.d.ts",
       "import": "./src/shared-array-buffer.js"
@@ -57,6 +61,7 @@
     "bound",
     "iterable",
     "json-storage",
+    "registry",
     "shared-array-buffer",
     "sticky",
     "with-resolvers"

package/src/README.md

@@ -131,6 +131,52 @@ from the key. A second constructor argument can replace the native *JSON* API as
 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`.
+
+```js
+import Registry from '@webreflection/utils/registry';
+
+const registry = new Registry(null, {
+  key: value => typeof value === 'string',
+  value: value => typeof value === 'function'
+});
+
+registry.set('ready', () => true);
+
+console.log(registry.get('ready')());
+// true
+```
+
+Both validators receive the candidate value and should return whether it is
+allowed. In TypeScript-aware editors, type-predicate validators also define the
+resulting `Registry<Key, Value>` shape, so `key` controls the map key type and
+`value` controls the stored value type.
+
+```js
+const mutable = new Registry(
+  [
+    ['answer', 41],
+    ['answer', 42]
+  ],
+  {
+    key: value => value === 'answer',
+    value: value => Number.isInteger(value),
+    unique: false
+  }
+);
+
+console.log(mutable.get('answer'));
+// 42
+```
+
+Initial iterable entries are validated with the same rules used by `set()`, so
+invalid keys, invalid values, or duplicate keys fail during construction.
+
+
 ## shared-array-buffer
 
 This utility provides an unobtrusive *SAB* (*SharedArrayBuffer*) shim based on the default *ArrayBuffer*, with `grow(length)` and `growable` additions.

package/src/registry.js

@@ -0,0 +1,80 @@
+// @ts-check
+
+/**
+ * @template Type
+ * @typedef {((value: unknown) => value is Type) | ((value: unknown) => boolean)} RegistryValidator
+ */
+
+/**
+ * @template [Key=unknown]
+ * @template [Value=unknown]
+ * @typedef {{
+ *   key?: RegistryValidator<Key>,
+ *   value?: RegistryValidator<Value>,
+ *   unique?: boolean,
+ * }} RegistryOptions
+ */
+
+/**
+ * @param {unknown[]} parts
+ */
+const fail = (...parts) => {
+  throw new TypeError(parts.map(String).join(' '));
+};
+
+/** @type {RegistryOptions} */
+const defaultOptions = {
+  key: _ => true,
+  value: _ => true,
+  unique: true,
+};
+
+/**
+ * Map with optional key/value validation and duplicate-key protection.
+ *
+ * @template [Key=unknown]
+ * @template [Value=unknown]
+ * @extends {Map<Key, Value>}
+ */
+export default class Registry extends Map {
+  /** @type {RegistryValidator<Key>} */
+  #key;
+
+  /** @type {RegistryValidator<Value>} */
+  #value;
+
+  /** @type {boolean} */
+  #unique;
+
+  /**
+   * @param {Iterable<[Key, Value]> | null} [iterable]
+   * @param {RegistryOptions<Key, Value>} [options]
+   */
+  constructor(
+    iterable,
+    options = {}
+  ) {
+    super();
+    const {
+      key = /** @type {RegistryValidator<Key>} */ (defaultOptions.key),
+      value = /** @type {RegistryValidator<Value>} */ (defaultOptions.value),
+      unique = defaultOptions.unique
+    } = options;
+    this.#key = key;
+    this.#value = value;
+    this.#unique = !!unique;
+    for (const [key, value] of iterable ?? []) this.set(key, value);
+  }
+
+  /**
+   * @param {Key} key
+   * @param {Value} value
+   * @returns {this}
+   */
+  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);
+    return super.set(key, value);
+  }
+}

package/types/registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Map with optional key/value validation and duplicate-key protection.
+ *
+ * @template [Key=unknown]
+ * @template [Value=unknown]
+ * @extends {Map<Key, Value>}
+ */
+export default class Registry<Key = unknown, Value = unknown> extends Map<Key, Value> {
+    /**
+     * @param {Iterable<[Key, Value]> | null} [iterable]
+     * @param {RegistryOptions<Key, Value>} [options]
+     */
+    constructor(iterable?: Iterable<[Key, Value]> | null, options?: RegistryOptions<Key, Value>);
+    /**
+     * @param {Key} key
+     * @param {Value} value
+     * @returns {this}
+     */
+    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;
+};