@webreflection/utils 0.2.17 → 0.2.19

package/README.md

@@ -7,15 +7,15 @@
 
 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)** - 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
+  * **[all](./src/#all)** - `Promise.all` via object destructuring
+  * **[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
+  * **[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
+  * **[shared-array-buffer](./src#shared-array-buffer)** - simulate *SAB* when not available
+  * **[sticky](./src#sticky)** - keep useful values stable once per realm
+  * **[with-resolvers](./src#with-resolvers)** - use a self-bound `Promise.withResolvers()` helper for older runtimes
 
 MIT-style license.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "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",
+    "./iterable": "./types/iterable.d.ts",
+    "./json-storage": "./types/json-storage.d.ts",
+    "./registry": "./types/registry.d.ts",
     "./shared-array-buffer": "./types/shared-array-buffer.d.ts",
     "./sticky": "./types/sticky.d.ts",
     "./with-resolvers": "./types/with-resolvers.d.ts"

package/src/README.md

@@ -134,8 +134,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 +173,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/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/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;
 };