@webreflection/utils 0.1.2 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2025-today, Andrea Giammarchi, @WebReflection
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/README.md

@@ -9,10 +9,29 @@ A [collection](./src/) of utility functions.
 
 ```js
 // example: a shim based on ArrayBuffer if native is `false`
-import { SharedArrayBuffer, native } from 'https://esm.run/@webreflection/utils/shared-array-buffer';
+import { SharedArrayBuffer, native } from '@webreflection/utils/shared-array-buffer';
 
 // example: self bound Promise.withResolvers()
-import withResolvers from 'https://esm.run/@webreflection/utils/with-resolvers';
+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;
 ```

package/package.json

@@ -1,20 +1,44 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "type": "module",
   "exports": {
-    "./shared-array-buffer": "./src/shared-array-buffer.js",
-    "./with-resolvers": "./src/with-resolvers.js",
+    "./bound": {
+      "types": "./types/bound.d.ts",
+      "import": "./src/bound.js"
+    },
+    "./bound-once": {
+      "types": "./types/bound-once.d.ts",
+      "import": "./src/bound-once.js"
+    },
+    "./shared-array-buffer": {
+      "types": "./types/shared-array-buffer.d.ts",
+      "import": "./src/shared-array-buffer.js"
+    },
+    "./with-resolvers": {
+      "types": "./types/with-resolvers.d.ts",
+      "import": "./src/with-resolvers.js"
+    },
     "./package.json": "./package.json"
   },
   "tests": [
+    "bound",
+    "bound-once",
     "shared-array-buffer",
     "with-resolvers"
   ],
   "scripts": {
+    "build": "npm run build:types && npm run test",
+    "build:types": "tsc --allowJs --checkJs --declaration --emitDeclarationOnly --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`));'"
   },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
     "shared",
     "utility",
@@ -32,6 +56,7 @@
   },
   "homepage": "https://github.com/WebReflection/utils#readme",
   "devDependencies": {
-    "c8": "^10.1.3"
+    "c8": "^11.0.0",
+    "typescript": "^6.0.3"
   }
 }

package/src/bound-once.js

@@ -0,0 +1,29 @@
+//@ts-check
+
+/**
+ * @type {WeakMap<object, Map<string | symbol, (...args: any[]) => unknown>>}
+ */
+const methods = new WeakMap;
+
+/**
+ * @type {ProxyHandler<any>}
+ */
+const handler = {
+  get(target, prop) {
+    const known = /** @type {Map<string | symbol, (...args: any[]) => unknown>} */ (methods.get(target));
+    let method = known.get(prop);
+    if (!method) known.set(prop, (method = target[prop].bind(target)));
+    return method;
+  }
+};
+
+/**
+ * @template {object} T
+ * @param {T} target
+ * @returns {import('./bound.js').Bound<T>}
+ */
+export default target => {
+  let known = methods.get(target);
+  if (!known) methods.set(target, (known = new Map));
+  return new Proxy(target, handler);
+};

package/src/bound.js

@@ -0,0 +1,25 @@
+//@ts-check
+
+/**
+ * @template F
+ * @typedef {unknown extends ThisParameterType<F> ? F : F extends (this: any, ...args: infer A) => infer R ? (...args: A) => R : never} BoundMethod
+ */
+
+/**
+ * @template T
+ * @typedef {{[K in keyof T as T[K] extends Function ? K : never]: BoundMethod<T[K]>}} Bound
+ */
+
+/**
+ * @type {ProxyHandler<any>}
+ */
+const handler = {
+  get: (target, prop) => target[prop].bind(target),
+};
+
+/**
+ * @template {object} T
+ * @param {T} target
+ * @returns {Bound<T>}
+ */
+export default target => new Proxy(target, handler);

package/src/with-resolvers.js

@@ -2,21 +2,26 @@
 
 /**
  * @template T
- * @typedef {{promise: Promise<T>, resolve: (value: T) => void, reject: (reason?: any) => void}} Resolvers
+ * @typedef {{promise: Promise<T>, resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void}} Resolvers
  */
 
 // fallback for Android WebView
-//@ts-ignore
-const withResolvers = Promise.withResolvers || function withResolvers() {
+/**
+ * @template T
+ * @this {PromiseConstructor}
+ * @returns {Resolvers<T>}
+ */
+function withResolvers() {
   var a, b, c = new this((resolve, reject) => {
     a = resolve;
     b = reject;
   });
-  return {resolve: a, reject: b, promise: c};
-};
+  // @ts-ignore
+  return { resolve: a, reject: b, promise: c };
+}
 
-/**
- * @template T
- * @type {() => Resolvers<T>}
- */
-export default withResolvers.bind(Promise);
+
+export default /** @type {<T>() => Resolvers<T>} */((
+  /** @type {PromiseConstructor & {withResolvers?: <T>() => Resolvers<T>}} */ (Promise).withResolvers ||
+  withResolvers
+).bind(Promise));

package/types/bound-once.d.ts

@@ -0,0 +1,2 @@
+declare function _default<T extends object>(target: T): import("./bound.js").Bound<T>;
+export default _default;

package/types/bound.d.ts

@@ -0,0 +1,4 @@
+declare function _default<T extends object>(target: T): Bound<T>;
+export default _default;
+export type BoundMethod<F> = unknown extends ThisParameterType<F> ? F : F extends (this: any, ...args: infer A) => infer R ? (...args: A) => R : never;
+export type Bound<T_1> = { [K in keyof T_1 as T_1[K] extends Function ? K : never]: BoundMethod<T_1[K]>; };

package/types/shared-array-buffer.d.ts

@@ -0,0 +1,3 @@
+declare let SAB: SharedArrayBufferConstructor;
+export let native: boolean;
+export { SAB as SharedArrayBuffer };

package/types/with-resolvers.d.ts

@@ -0,0 +1,7 @@
+declare const _default: <T>() => Resolvers<T>;
+export default _default;
+export type Resolvers<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};

package/.github/dependabot.yml

@@ -1,13 +0,0 @@
-# Keep GitHub Actions up to date with GitHub's Dependabot...
-# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
-# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
-version: 2
-updates:
-  - package-ecosystem: github-actions
-    directory: /
-    groups:
-      github-actions:
-        patterns:
-          - "*"  # Group all Actions updates into a single larger pull request
-    schedule:
-      interval: weekly

package/.github/workflows/node.js.yml

@@ -1,31 +0,0 @@
-# This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: build
-
-on: [push, pull_request]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [22]
-
-    steps:
-    - uses: actions/checkout@v5
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm run test
-    - run: npm run coverage --if-present
-    - name: Coveralls
-      uses: coverallsapp/github-action@master
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}

package/test/shared-array-buffer.js

@@ -1,22 +0,0 @@
-const { SharedArrayBuffer: SAB } = globalThis;
-
-globalThis.SharedArrayBuffer = null;
-
-const { SharedArrayBuffer, native } = await import("../src/shared-array-buffer.js");
-
-globalThis.SharedArrayBuffer = SAB;
-
-console.assert(!native);
-
-const gsab = new SharedArrayBuffer(4, { maxByteLength: 8 });
-
-console.assert(gsab.byteLength === 4);
-console.assert(gsab.growable);
-
-gsab.grow(8);
-
-console.assert(gsab.byteLength === 8);
-
-const fsab = new SharedArrayBuffer(6);
-console.assert(fsab.byteLength === 6);
-console.assert(!fsab.growable);

package/test/with-resolvers.js

@@ -1,13 +0,0 @@
-Promise.withResolvers = undefined;
-
-const { default: withResolvers } = await import('../src/with-resolvers.js');
-
-const { promise, resolve, reject } = withResolvers();
-
-console.assert(typeof reject === 'function');
-console.assert(typeof resolve === 'function');
-console.assert(promise instanceof Promise);
-
-resolve('OK');
-
-console.log(await promise);