@webreflection/utils 0.2.8 → 0.2.9

package/README.md

@@ -5,40 +5,12 @@
 <sup>**Social Media Photo by [benjamin lehman](https://unsplash.com/@abject) on [Unsplash](https://unsplash.com/)**</sup>
 
 
-A [collection](./src/) of utility functions.
+A [collection](./src/) of utility functions:
 
-```js
-// example: a shim based on ArrayBuffer if native is `false`
-import { SharedArrayBuffer, native } from '@webreflection/utils/shared-array-buffer';
+  * **[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
+  * **[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
 
-// example: self bound Promise.withResolvers()
-import withResolvers from '@webreflection/utils/with-resolvers';
-
-const { promise, resolve, reject } = withResolvers();
-
-// example: any object bound method
-import bound from '@webreflection/utils/bound';
-
-const { all, resolve } = bound(Promise);
-all([1, 2, 3]);
-resolve(4);
-
-
-// example: any object bound method is identical
-//          particularly useful for listeners identity
-import boundOnce from '@webreflection/utils/bound-once';
-
-const { all, resolve } = boundOnce(Promise);
-all([1, 2, 3]);
-resolve(4);
-
-boundOnce(Promise).all === all;
-boundOnce(Promise).resolve === resolve;
-
-// example: always retrieve the first time data/module
-import sticky from '@webreflection/utils/sticky';
-
-const [module, known] = sticky('@module/name', { always: 'same' });
-
-export default module;
-```
+MIT style License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "type": "module",
   "types": {
     "./bound-once": "./types/bound-once.d.ts",

package/src/README.md

@@ -0,0 +1,79 @@
+# @webreflection/utils
+
+Each utility can be loaded from a *CDN* via either `https://esm.run/@webreflection/utils/{{UTILITY}}` or `https://cdn.jsdelivr.net/npm/@webreflection/utils/src/{{UTILITY}}.js`.
+
+
+This document describes each utility separately.
+
+## bound-once
+
+This is equivalent to **bound**, except each bound method is created only once. It is useful when bound method identity must be preserved across multiple calls.
+
+This variant uses **sticky** to ensure that weakly referenced targets always produce the same bound method within the same realm.
+
+## bound
+
+This utility provides an object-destructuring syntax shortcut for binding methods.
+
+```js
+import bound from '@webreflection/utils/bound';
+
+const { all, resolve } = bound(Promise);
+all([1, 2, 3]);
+resolve(4);
+```
+
+The **bound-once** variant ensures that repeated accesses, such as `boundOnce(Promise).all`, always return the same bound method.
+
+## shared-array-buffer
+
+This utility provides an unobtrusive *SAB* (*SharedArrayBuffer*) shim based on the default *ArrayBuffer*, with `grow(length)` and `growable` additions.
+
+This class can be used to simulate *SAB* capabilities.
+
+The module exports both `SharedArrayBuffer` and `native`. The `native` *boolean* indicates whether the returned constructor is the platform implementation or the shim.
+
+## sticky
+
+Based on `Symbol.for(name)`, this utility helps modules that might be embedded multiple times across projects avoid conflicts in their internal logic. It preserves the assumption that a module is imported only *once* per application.
+
+```js
+import sticky from '@webreflection/utils/sticky';
+
+// will be created and discarded ASAP
+// if embedded multiple times
+const computed = new WeakMap;
+
+// module will always point at the very first computed
+const [module, known] = sticky(
+  '@my-project/known-references',
+  ref => {
+    // ensure this reference is processed only once in this realm
+    if (computed.has(ref)) return computed.get(ref);
+
+    // compute the value once, then reuse it on future calls
+    const costlyComputation = somethingNeededOnce(ref);
+    computed.set(ref, costlyComputation);
+    return costlyComputation;
+  },
+);
+
+if (known) console.warn('embedded multiple times');
+
+export default module;
+```
+
+
+## with-resolvers
+
+This utility returns a self-bound `Promise.withResolvers()` implementation that also works on older Android WebView runtimes.
+
+```js
+import withResolvers from '@webreflection/utils/with-resolvers';
+
+const { promise, resolve, reject } = withResolvers();
+
+setTimeout(resolve, 0, 42);
+
+export default promise;
+```

package/src/bound-once.js

@@ -2,14 +2,9 @@
 
 import sticky from './sticky.js';
 
-const [methods] = sticky(
-  '@webreflection/utils/bound-once',
-  /** @type {WeakMap<object, Map<string | symbol, (...args: any[]) => unknown>>} */ (new WeakMap),
-);
+const methods = /** @type {WeakMap<object, Map<string | symbol, (...args: any[]) => unknown>>} */ (new WeakMap);
 
-/**
- * @type {ProxyHandler<any>}
- */
+/** @type {ProxyHandler<any>} */
 const handler = {
   get(target, prop) {
     const known = /** @type {Map<string | symbol, (...args: any[]) => unknown>} */ (methods.get(target));
@@ -19,12 +14,15 @@ const handler = {
   }
 };
 
-/**
- * @template {object} T
- * @param {T} target
- * @returns {import('./bound.js').Bound<T>}
- */
-export default target => {
-  if (!methods.has(target)) methods.set(target, new Map);
-  return new Proxy(target, handler);
-};
+export default sticky(
+  '@webreflection/utils/bound-once',
+  /**
+   * @template {object} T
+   * @param {T} target
+   * @returns {import('./bound.js').Bound<T>}
+   */
+  target => {
+    if (!methods.has(target)) methods.set(target, new Map);
+    return new Proxy(target, handler);
+  },
+)[0];

package/types/bound-once.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @template {object} T
+ * @param {T} target
+ * @returns {import('./bound.js').Bound<T>}
+ */
 declare function _default<T extends object>(target: T): import("./bound.js").Bound<T>;
 export default _default;