@webreflection/utils 0.2.14 → 0.2.16

package/README.md

@@ -5,13 +5,14 @@
 <sup>**Social Media Photo by [benjamin lehman](https://unsplash.com/@abject) on [Unsplash](https://unsplash.com/)**</sup>
 
 
-A [collection](./src/) of utility functions:
+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
-  * **[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
+  * **[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.14",
+  "version": "0.2.16",
   "type": "module",
   "types": {
     "./all": "./types/all.d.ts",
@@ -28,6 +28,10 @@
       "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"
@@ -51,6 +55,7 @@
     "ascii",
     "bound-once",
     "bound",
+    "iterable",
     "json-storage",
     "shared-array-buffer",
     "sticky",
@@ -60,7 +65,7 @@
     "build": "npm run build:types && npm run test",
     "build:types": "tsc --allowJs --checkJs --declaration --emitDeclarationOnly --stripInternal --outDir types --target es2022 --lib es2024 --module nodenext --moduleResolution nodenext src/*.js",
     "coverage": "mkdir -p ./coverage; c8 report --reporter=text-lcov > ./coverage/lcov.info",
-    "test": "c8 node -e 'let q=Promise.resolve();for(const t of require(`./package.json`).tests)q=q.then(()=>import(`./test/${t}.js`));'"
+    "test": "c8 node --localstorage-file './test/.storage' -e 'let q=Promise.resolve();for(const t of require(`./package.json`).tests)q=q.then(()=>import(`./test/${t}.js`));'"
   },
   "files": [
     "src",

package/src/README.md

@@ -71,23 +71,64 @@ 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 *Map* like API that is compatible out of the box with *JSON API*.
+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 localJSONStorage = new JSONStorage;
+const preferences = new JSONStorage;
 
-// insert if not present an object and returns it
-localJSONStorage.getOrInsert('key', { complex: true }).complex;
+preferences.set('theme', { dark: true });
 
-localJSONStorage.get('key').complex; // true
+console.log(preferences.get('theme').dark);
+// 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.
+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

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