@webreflection/utils 0.2.10 → 0.2.11

package/README.md

@@ -7,6 +7,7 @@
 
 A [collection](./src/) of utility functions:
 
+  * **[all](https://github.com/WebReflection/utils/tree/main/src#all)** - `Promise.all` via object destructuring
   * **[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

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "type": "module",
   "types": {
+    "./all": "./types/all.d.ts",
     "./bound-once": "./types/bound-once.d.ts",
     "./bound": "./types/bound.d.ts",
     "./shared-array-buffer": "./types/shared-array-buffer.d.ts",
@@ -10,6 +11,10 @@
     "./with-resolvers": "./types/with-resolvers.d.ts"
   },
   "exports": {
+    "./all": {
+      "types": "./types/all.d.ts",
+      "import": "./src/all.js"
+    },
     "./bound-once": {
       "types": "./types/bound-once.d.ts",
       "import": "./src/bound-once.js"
@@ -33,6 +38,7 @@
     "./package.json": "./package.json"
   },
   "tests": [
+    "all",
     "bound-once",
     "bound",
     "shared-array-buffer",

package/src/README.md

@@ -6,6 +6,28 @@ Each utility can be loaded from a *CDN* via either `https://esm.run/@webreflecti
 This document describes each utility separately.
 
 
+## all
+
+A `Promise.all` companion with one extra convenience: when called with a
+single object literal, it resolves each value and returns an object with the
+same keys.
+
+```js
+import all from '@webreflection/all';
+
+const user = await all({
+  name: fetchName(),
+  age: fetchAge()
+});
+
+// { name: 'Ada', age: 36 }
+```
+
+This preserves the shape and names of object-literal work, avoiding the
+positional array juggling required by `Promise.all`. For arrays, or for two or
+more arguments, it behaves like `Promise.all` and resolves to an array.
+
+
 ## 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.

package/src/all.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+import bound from './bound.js';
+
+const { isArray } = Array;
+const { entries, fromEntries } = Object;
+
+const { all, resolve } = bound(Promise);
+
+/**
+ * @typedef {{
+ *   <T extends object>(obj: T): Promise<{ [K in keyof T]: Awaited<T[K]> }>;
+ *   <T extends unknown[]>(values: T): Promise<{ [K in keyof T]: Awaited<T[K]> }>;
+ *   <T extends [unknown, unknown, ...unknown[]]>(...values: T): Promise<{ [K in keyof T]: Awaited<T[K]> }>;
+ * }} All
+ */
+
+/**
+ * @param {unknown} obj
+ * @param {...unknown} rest
+ * @returns {Promise<unknown>}
+ */
+const values = (obj, ...rest) => {
+  // resolve all arguments passed along as array
+  if (rest.length)
+    return all([obj, ...rest]);
+
+  // resolve all entries in the array
+  if (isArray(obj))
+    return all(obj);
+
+  // resolve the object literal values re-mapping
+  // them as key-value pairs
+  for (const [k, v] of entries(/** @type {object} */ (obj)))
+    /** @type {Promise<[string, unknown]>[]} */(rest).push(resolve(v).then(v => [k, v]));
+
+  // return the object literal with the resolved values
+  return all(/** @type {Promise<[string, unknown]>[]} */(rest)).then(fromEntries);
+};
+
+export default /** @type {All} */(values);

package/types/all.d.ts

@@ -0,0 +1,7 @@
+declare const _default: All;
+export default _default;
+export type All = {
+    <T extends object>(obj: T): Promise<{ [K in keyof T]: Awaited<T[K]>; }>;
+    <T extends unknown[]>(values: T): Promise<{ [K in keyof T]: Awaited<T[K]>; }>;
+    <T extends [unknown, unknown, ...unknown[]]>(...values: T): Promise<{ [K in keyof T]: Awaited<T[K]>; }>;
+};