@webreflection/utils 0.2.10 → 0.2.12

package/README.md

@@ -7,6 +7,8 @@
 
 A [collection](./src/) of utility functions:
 
+  * **[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
   * **[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,10 @@
 {
   "name": "@webreflection/utils",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "type": "module",
   "types": {
+    "./all": "./types/all.d.ts",
+    "./ascii": "./types/ascii.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 +12,14 @@
     "./with-resolvers": "./types/with-resolvers.d.ts"
   },
   "exports": {
+    "./all": {
+      "types": "./types/all.d.ts",
+      "import": "./src/all.js"
+    },
+    "./ascii": {
+      "types": "./types/ascii.d.ts",
+      "import": "./src/ascii.js"
+    },
     "./bound-once": {
       "types": "./types/bound-once.d.ts",
       "import": "./src/bound-once.js"
@@ -33,6 +43,8 @@
     "./package.json": "./package.json"
   },
   "tests": [
+    "all",
+    "ascii",
     "bound-once",
     "bound",
     "shared-array-buffer",

package/src/README.md

@@ -6,6 +6,49 @@ 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/utils/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.
+
+
+## ascii
+
+An extremely small string to `Uint8Array` converter for known ASCII-compatible
+content. It does not validate or encode Unicode code points; it simply stores
+each string unit as its `0-255` char code.
+
+This is meant for niche cases where the input is already constrained, such as
+ISO date strings, plain-English global names or method names, and other small
+ad-hoc values.
+
+```js
+import { encode, decode } from '@webreflection/utils/ascii';
+
+console.log(decode(encode('ASCII')));
+// ASCII
+```
+
+Please note that decoding also fails for inputs bigger than about 64K bytes, or
+whatever argument limit your runtime has for `String.fromCharCode`.
+
+
 ## 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/src/ascii.js

@@ -0,0 +1,14 @@
+const { fromCharCode } = String;
+const toCharCode = Uint8Array.from.bind(Uint8Array);
+
+/**
+ * @param {string} str
+ * @returns
+ */
+export const encode = str => toCharCode(str, c => c.charCodeAt(0));
+
+/**
+ * @param {Uint8Array} view
+ * @returns {string}
+ */
+export const decode = view => fromCharCode(...view);

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

package/types/ascii.d.ts

@@ -0,0 +1,2 @@
+export function encode(str: string): Uint8Array<ArrayBuffer>;
+export function decode(view: Uint8Array): string;