@webreflection/utils 0.2.13 → 0.2.15

package/README.md

@@ -11,6 +11,8 @@ A [collection](./src/) of utility functions:
   * **[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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "types": {
     "./all": "./types/all.d.ts",
@@ -28,6 +28,14 @@
       "types": "./types/bound.d.ts",
       "import": "./src/bound.js"
     },
+    "./iterable": {
+      "types": "./types/iterable.d.ts",
+      "import": "./src/iterable.js"
+    },
+    "./json-storage": {
+      "types": "./types/json-storage.d.ts",
+      "import": "./src/json-storage.js"
+    },
     "./shared-array-buffer": {
       "types": "./types/shared-array-buffer.d.ts",
       "import": "./src/shared-array-buffer.js"
@@ -47,6 +55,8 @@
     "ascii",
     "bound-once",
     "bound",
+    "iterable",
+    "json-storage",
     "shared-array-buffer",
     "sticky",
     "with-resolvers"
@@ -79,6 +89,11 @@
     "url": "https://github.com/WebReflection/utils/issues"
   },
   "homepage": "https://github.com/WebReflection/utils#readme",
+  "overrides": {
+    "c8": {
+      "yargs": "^18.0.0"
+    }
+  },
   "devDependencies": {
     "c8": "^11.0.0",
     "typescript": "^6.0.3"

package/src/README.md

@@ -70,6 +70,67 @@ resolve(4);
 
 The **bound-once** variant ensures that repeated accesses, such as `boundOnce(Promise).all`, always return the same bound method.
 
+
+## iterable
+
+Ensures an object can be consumed by `for...of`, spread, `Array.from`, and
+other iterable-aware APIs.
+
+```js
+import iterable from '@webreflection/utils/iterable';
+
+const query = iterable({ page: 1, perPage: 20 });
+
+console.log([...query]);
+// [['page', 1], ['perPage', 20]]
+```
+
+If the object already defines or inherits `Symbol.iterator`, it is returned
+unchanged. Otherwise, the same object receives a configurable own
+`Symbol.iterator` method that yields `Object.entries(ref)`.
+
+
+## json-storage
+
+A small *Map* like facade over `localStorage` by default, or `sessionStorage`
+when requested. Values are serialized with `JSON.stringify` on write and parsed
+with `JSON.parse` on read, so callers can store structured data without
+manually converting every value.
+
+```js
+import JSONStorage from '@webreflection/utils/json-storage';
+
+const preferences = new JSONStorage;
+
+preferences.set('theme', { dark: true });
+
+console.log(preferences.get('theme').dark);
+// true
+```
+
+The API follows familiar `Map` names where they make sense: `get`, `set`,
+`has`, `delete`, `clear`, `entries`, `keys`, `values`, and default iteration.
+Missing keys return `undefined`, while `delete(key)` reports whether the key was
+present.
+
+```js
+const cart = new JSONStorage(JSONStorage.SESSION);
+
+const items = cart.getOrInsert('items', []);
+items.push('book');
+cart.set('items', items);
+
+for (const [key, value] of cart) {
+  console.log(key, value);
+}
+```
+
+Use `getOrInsert(key, value)` to create a value only when the key is absent, or
+`getOrInsertComputed(key, callback)` when the initial value should be computed
+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.
+
+
 ## shared-array-buffer
 
 This utility provides an unobtrusive *SAB* (*SharedArrayBuffer*) shim based on the default *ArrayBuffer*, with `grow(length)` and `growable` additions.

package/src/iterable.js

@@ -0,0 +1,37 @@
+// @ts-check
+
+/** @type {typeof Symbol.iterator} */
+const iterator = Symbol.iterator;
+
+const { defineProperty: dp, entries } = Object;
+
+/**
+ * @this {object}
+ * @returns {Generator<[string, any], void, unknown>}
+ */
+function* value() {
+  yield* entries(this);
+}
+
+const configurable = true;
+
+/**
+ * Ensures an object is iterable.
+ *
+ * If `ref` already defines or inherits `Symbol.iterator`, it is returned
+ * unchanged. Otherwise, the same object is augmented with `Symbol.iterator`
+ * yielding the entries produced by `Object.entries(ref)`.
+ *
+ * @typedef {{
+ *   <T extends Iterable<unknown>>(ref: T): T;
+ *   <T extends object>(ref: T): T & Iterable<[string, T[keyof T]]>;
+ * }} EnsureIterable
+ */
+
+/**
+ * @param {object} ref
+ * @returns {object}
+ */
+const iterable = ref => iterator in ref ? ref : dp(ref, iterator, { configurable, value });
+
+export default /** @type {EnsureIterable} */(iterable);

package/src/json-storage.js

@@ -0,0 +1,167 @@
+// @ts-check
+
+const { entries, keys, values } = Object;
+
+/** @type {typeof Symbol.iterator} */
+const iterator = Symbol.iterator;
+
+const LOCAL = 'local';
+const SESSION = 'session';
+
+/**
+ * @typedef {typeof LOCAL | typeof SESSION} JSONStorageKind
+ */
+
+/**
+ * @template Value
+ * @typedef {{
+ *   parse(source: string): Value,
+ *   stringify(value: Value): string
+ * }} JSONStorageAPI
+ */
+
+/**
+ * @typedef {{
+ *   clear(): void,
+ *   getItem(key: string): string | null,
+ *   removeItem(key: string): void,
+ *   setItem(key: string, value: string): void,
+ *   [Symbol.iterator](): Generator<[string, string], void, unknown>,
+ * }} StorageAPI
+ */
+
+/**
+ * @template Value
+ * @param {JSONStorage<Value>} self
+ * @param {string} key
+ * @param {Value} value
+ * @returns {Value}
+ */
+const add = (self, key, value) => {
+  self.set(key, value);
+  return value;
+};
+
+/**
+ * Map-like facade over `localStorage` or `sessionStorage` that stores values
+ * through a JSON-compatible `parse`/`stringify` pair.
+ *
+ * @template [Value=unknown]
+ * @implements {Iterable<[string, Value]>}
+ */
+export default class JSONStorage {
+  /** @type {typeof LOCAL} */
+  static LOCAL = LOCAL;
+
+  /** @type {typeof SESSION} */
+  static SESSION = SESSION;
+
+  /** @type {StorageAPI} */
+  #storage;
+
+  /** @type {(value: Value) => string} */
+  #stringify;
+
+  /** @type {(source: string) => Value} */
+  #parse;
+
+  /**
+   * @param {JSONStorageKind} [storage=LOCAL]
+   * @param {JSONStorageAPI<Value>} [json=JSON]
+   */
+  constructor(storage = LOCAL, { parse, stringify } = /** @type {JSONStorageAPI<Value>} */ (JSON)) {
+    // @ts-ignore
+    this.#storage = storage === LOCAL ? localStorage : sessionStorage;
+    this.#stringify = stringify;
+    this.#parse = parse;
+  }
+
+  /** @returns {void} */
+  clear() {
+    this.#storage.clear();
+  }
+
+  /**
+   * @param {string} key
+   * @returns {boolean}
+   */
+  delete(key) {
+    const had = this.has(key);
+    if (had) this.#storage.removeItem(key);
+    return had;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Value | undefined}
+   */
+  get(key) {
+    const value = this.#storage.getItem(key);
+    return typeof value === 'string' ? this.#parse(value) : void 0;
+  }
+
+  /**
+   * @param {string} key
+   * @param {Value} value
+   * @returns {Value}
+   */
+  getOrInsert(key, value) {
+    const current = this.get(key);
+    return current !== void 0 ? current : add(this, key, value);
+  }
+
+  /**
+   * @template {string} Key
+   * @param {Key} key
+   * @param {(key: Key) => Value} callback
+   * @returns {Value}
+   */
+  getOrInsertComputed(key, callback) {
+    const current = this.get(key);
+    return current !== void 0 ? current : add(this, key, callback(key));
+  }
+
+  /**
+   * @param {string} key
+   * @returns {boolean}
+   */
+  has(key) {
+    return this.#storage.getItem(key) != null;
+  }
+
+  /**
+   * @param {string} key
+   * @param {Value} value
+   * @returns {this}
+   */
+  set(key, value) {
+    this.#storage.setItem(key, this.#stringify(value));
+    return this;
+  }
+
+  /** @returns {Generator<[string, Value], void, unknown>} */
+  *entries() {
+    yield* this[iterator]();
+  }
+
+  /** @returns {Generator<string, void, unknown>} */
+  *keys() {
+    yield* keys(this.#storage);
+  }
+
+  /** @returns {Generator<Value, void, unknown>} */
+  *values() {
+    for (const value of values(this.#storage)) {
+      // @ts-ignore
+      yield this.#parse(value);
+    }
+  }
+
+  /** @returns {Generator<[string, Value], void, unknown>} */
+  *[iterator]() {
+    for (const [key, value] of entries(this.#storage)) {
+      // @ts-ignore
+      yield [key, this.#parse(value)];
+    }
+  }
+}

package/types/iterable.d.ts

@@ -0,0 +1,13 @@
+declare const _default: EnsureIterable;
+export default _default;
+/**
+ * Ensures an object is iterable.
+ *
+ * If `ref` already defines or inherits `Symbol.iterator`, it is returned
+ * unchanged. Otherwise, the same object is augmented with `Symbol.iterator`
+ * yielding the entries produced by `Object.entries(ref)`.
+ */
+export type EnsureIterable = {
+    <T extends Iterable<unknown>>(ref: T): T;
+    <T extends object>(ref: T): T & Iterable<[string, T[keyof T]]>;
+};

package/types/json-storage.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Map-like facade over `localStorage` or `sessionStorage` that stores values
+ * through a JSON-compatible `parse`/`stringify` pair.
+ *
+ * @template [Value=unknown]
+ * @implements {Iterable<[string, Value]>}
+ */
+export default class JSONStorage<Value = unknown> implements Iterable<[string, Value]> {
+    /** @type {typeof LOCAL} */
+    static LOCAL: typeof LOCAL;
+    /** @type {typeof SESSION} */
+    static SESSION: typeof SESSION;
+    /**
+     * @param {JSONStorageKind} [storage=LOCAL]
+     * @param {JSONStorageAPI<Value>} [json=JSON]
+     */
+    constructor(storage?: JSONStorageKind, { parse, stringify }?: JSONStorageAPI<Value>);
+    /** @returns {void} */
+    clear(): void;
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
+    delete(key: string): boolean;
+    /**
+     * @param {string} key
+     * @returns {Value | undefined}
+     */
+    get(key: string): Value | undefined;
+    /**
+     * @param {string} key
+     * @param {Value} value
+     * @returns {Value}
+     */
+    getOrInsert(key: string, value: Value): Value;
+    /**
+     * @template {string} Key
+     * @param {Key} key
+     * @param {(key: Key) => Value} callback
+     * @returns {Value}
+     */
+    getOrInsertComputed<Key extends string>(key: Key, callback: (key: Key) => Value): Value;
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
+    has(key: string): boolean;
+    /**
+     * @param {string} key
+     * @param {Value} value
+     * @returns {this}
+     */
+    set(key: string, value: Value): this;
+    /** @returns {Generator<[string, Value], void, unknown>} */
+    entries(): Generator<[string, Value], void, unknown>;
+    /** @returns {Generator<string, void, unknown>} */
+    keys(): Generator<string, void, unknown>;
+    /** @returns {Generator<Value, void, unknown>} */
+    values(): Generator<Value, void, unknown>;
+    /** @returns {Generator<[string, Value], void, unknown>} */
+    [Symbol.iterator](): Generator<[string, Value], void, unknown>;
+    #private;
+}
+export type JSONStorageKind = typeof LOCAL | typeof SESSION;
+export type JSONStorageAPI<Value> = {
+    parse(source: string): Value;
+    stringify(value: Value): string;
+};
+export type StorageAPI = {
+    clear(): void;
+    getItem(key: string): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+    [Symbol.iterator](): Generator<[string, string], void, unknown>;
+};
+declare const LOCAL: "local";
+declare const SESSION: "session";
+export {};