@webreflection/utils 0.2.13 → 0.2.14

package/README.md

@@ -11,6 +11,7 @@ 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
+  * **[json-storage](https://github.com/WebReflection/utils/tree/main/src#json-storage)** - to handle with ease both `localStorage` and `sessionStorage` via a *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.14",
   "type": "module",
   "types": {
     "./all": "./types/all.d.ts",
@@ -28,6 +28,10 @@
       "types": "./types/bound.d.ts",
       "import": "./src/bound.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 +51,7 @@
     "ascii",
     "bound-once",
     "bound",
+    "json-storage",
     "shared-array-buffer",
     "sticky",
     "with-resolvers"
@@ -79,6 +84,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,26 @@ resolve(4);
 
 The **bound-once** variant ensures that repeated accesses, such as `boundOnce(Promise).all`, always return the same bound method.
 
+
+## json-storage
+
+A *Map* like API that is compatible out of the box with *JSON API*.
+
+```js
+import JSONStorage from '@webreflection/utils/json-storage';
+
+const localJSONStorage = new JSONStorage;
+
+// insert if not present an object and returns it
+localJSONStorage.getOrInsert('key', { complex: true }).complex;
+
+localJSONStorage.get('key').complex; // true
+```
+
+The storage can be a session one via `new JSONStorage(JSONStorage.SESSION)` and it can optionally accept a different api from native *JSON* as long as both `parse` and `stringify` are implemented.
+
+
+
 ## shared-array-buffer
 
 This utility provides an unobtrusive *SAB* (*SharedArrayBuffer*) shim based on the default *ArrayBuffer*, with `grow(length)` and `growable` additions.

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/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 {};