@reykjavik/webtools 0.1.30 → 0.1.31

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.31
+
+_2024-09-23_
+
+- `@reykjavik/webtools/async`:
+  - feat: `maxWait` returns full `PromiseSettledResult` objects
+  - fix: `maxWait` result objects should remain stable
+  - fix: `maxWait` should distinguish between unresolved and rejected promises
+
 ## 0.1.30
 
 _2024-09-15_

package/README.md

@@ -265,23 +265,21 @@ const { user, posts } = await promiseAllObject({
 
 **Syntax:** `maxWait(timeout: number, promises: Array<any>): Promise<void>`  
 **Syntax:**
-`maxWait<T extends PlainObj>(timeout: number, promises: T): Promise<{ [K in keyof T]: { value: Awaited<T[K]> } | undefined }>`
+`maxWait<T extends PlainObj>(timeout: number, promises: T): Promise<{ [K in keyof T]: PromiseSettledResult<T[K]> } | undefined }>`
 
-This somewhat esoteric helper resolves soon as all of the passed `promises`
-have resolved, or after `timeout` milliseconds — whichever comes first.
+This somewhat esoteric helper resolves soon when all of the passed `promises`
+have settled (resolved or rejected), OR after `timeout` milliseconds —
+whichever comes first.
 
 If an object is passed, the resolved value will be an object with the same
-keys, with undefined values for any promises that didn't resolve in time, and
-the resolved values in a `value` container object.
-
-If any of the promises reject, their values become undefined in the returned
-object.
+keys, and any settled values in a `PromiseSettledResult` object, and
+`undefined` for any promises that didn't settle in time.
 
 ```ts
 import { maxWait } from '@reykjavik/webtools/async';
 
-const user = fetchUser();
-const posts = fetchPosts();
+const user = fetchUser(); // Promise<User>
+const posts = fetchPosts(); // Promise<Array<Post>>
 
 // Array of promises resolves to void
 await maxWait(500, [user, posts]);
@@ -291,6 +289,8 @@ const { user, posts } = await maxWait(500, { user, posts });
 
 console.log(user?.value); // undefined | User
 console.log(posts?.value); // undefined | Array<Post>
+console.log(posts?.status); // 'fulfilled' | 'rejected'
+console.log(posts?.reason); // undefined | unknown
 ```
 
 ---
@@ -333,11 +333,10 @@ detection test.)
 
 **`Intl.Collator` and `localeCompare`:**
 
-- It incorrectly treats `ð` and `d` as the same letter (most of the time), and
-  the acute-accented characters `á`, `é`, `í`, `ó`, `ú` and `ý` get lumped in
-  with their non-accented counterparts (unless the compared).  
-  We fix this only for the first letter in the string, but not for the rest of
-  it.
+- It sorts initial letters correctly but in the rest of the string, it
+  incorrectly treats `ð` and `d` as the same letter (most of the time), and
+  lumps the acute-accented characters `á`, `é`, `í`, `ó`, `ú` and `ý` in with
+  their non-accented counterparts.
 
 **`Intl.NumberFormat` and `toLocaleString`:**
 

package/async.d.ts

@@ -1,3 +1,4 @@
+import { EitherObj } from '@reykjavik/hanna-utils';
 type PlainObj = Record<string, unknown>;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -5,16 +6,19 @@ type PlainObj = Record<string, unknown>;
  */
 export declare const sleep: (length: number) => Promise<void>;
 /**
- * Resolves soon as all of the passed `promises` have resolved, or after
- * `timeout` milliseconds — whichever comes first.
+ * Returns a function that adds lag/delay to a promise chain,
+ * passing the promise payload through.
+ */
+export declare const addLag: (length: number) => <T>(res: T) => Promise<T>;
+/**
+ * Resolves as soon as all of the passed `promises` have resolved/settled,
+ * or after `timeout` milliseconds — whichever comes first.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#maxwait
  */
 export declare function maxWait(timeout: number, promises: Array<unknown>): Promise<void>;
 export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, promises: PromiseMap): Promise<{
-    -readonly [K in keyof PromiseMap]: {
-        value: Awaited<PromiseMap[K]>;
-    } | undefined;
+    -readonly [K in keyof PromiseMap]: EitherObj<PromiseFulfilledResult<Awaited<PromiseMap[K]>>, PromiseRejectedResult> | undefined;
 }>;
 /**
  * A variation of `Promise.all()` that accepts an object with named promises

package/async.js

@@ -1,12 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promiseAllObject = exports.maxWait = exports.sleep = void 0;
+exports.promiseAllObject = exports.maxWait = exports.addLag = exports.sleep = void 0;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
  * milliseconds.
  */
 const sleep = (length) => new Promise((resolve) => setTimeout(resolve, length));
 exports.sleep = sleep;
+/**
+ * Returns a function that adds lag/delay to a promise chain,
+ * passing the promise payload through.
+ */
+const addLag = (length) => (res) => (0, exports.sleep)(length).then(() => res);
+exports.addLag = addLag;
 function maxWait(timeout, promises) {
     if (Array.isArray(promises)) {
         return Promise.race([
@@ -19,17 +25,17 @@ function maxWait(timeout, promises) {
         Object.entries(promises).forEach(([key, value]) => {
             if (value instanceof Promise) {
                 retObj[key] = undefined;
-                value
-                    .then((value) => {
-                    retObj[key] = { value };
-                })
-                    .catch(() => undefined);
+                value.then((value) => {
+                    retObj[key] = { status: 'fulfilled', value };
+                }, (reason) => {
+                    retObj[key] = { status: 'rejected', reason };
+                });
             }
             else {
-                retObj[key] = { value };
+                retObj[key] = { status: 'fulfilled', value };
             }
         });
-        return (0, exports.sleep)(0).then(() => retObj);
+        return Promise.resolve().then(() => ({ ...retObj }));
     });
 }
 exports.maxWait = maxWait;

package/esm/async.d.ts

@@ -1,3 +1,4 @@
+import { EitherObj } from '@reykjavik/hanna-utils';
 type PlainObj = Record<string, unknown>;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -5,16 +6,19 @@ type PlainObj = Record<string, unknown>;
  */
 export declare const sleep: (length: number) => Promise<void>;
 /**
- * Resolves soon as all of the passed `promises` have resolved, or after
- * `timeout` milliseconds — whichever comes first.
+ * Returns a function that adds lag/delay to a promise chain,
+ * passing the promise payload through.
+ */
+export declare const addLag: (length: number) => <T>(res: T) => Promise<T>;
+/**
+ * Resolves as soon as all of the passed `promises` have resolved/settled,
+ * or after `timeout` milliseconds — whichever comes first.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#maxwait
  */
 export declare function maxWait(timeout: number, promises: Array<unknown>): Promise<void>;
 export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, promises: PromiseMap): Promise<{
-    -readonly [K in keyof PromiseMap]: {
-        value: Awaited<PromiseMap[K]>;
-    } | undefined;
+    -readonly [K in keyof PromiseMap]: EitherObj<PromiseFulfilledResult<Awaited<PromiseMap[K]>>, PromiseRejectedResult> | undefined;
 }>;
 /**
  * A variation of `Promise.all()` that accepts an object with named promises

package/esm/async.js

@@ -3,6 +3,11 @@
  * milliseconds.
  */
 export const sleep = (length) => new Promise((resolve) => setTimeout(resolve, length));
+/**
+ * Returns a function that adds lag/delay to a promise chain,
+ * passing the promise payload through.
+ */
+export const addLag = (length) => (res) => sleep(length).then(() => res);
 export function maxWait(timeout, promises) {
     if (Array.isArray(promises)) {
         return Promise.race([
@@ -15,17 +20,17 @@ export function maxWait(timeout, promises) {
         Object.entries(promises).forEach(([key, value]) => {
             if (value instanceof Promise) {
                 retObj[key] = undefined;
-                value
-                    .then((value) => {
-                    retObj[key] = { value };
-                })
-                    .catch(() => undefined);
+                value.then((value) => {
+                    retObj[key] = { status: 'fulfilled', value };
+                }, (reason) => {
+                    retObj[key] = { status: 'rejected', reason };
+                });
             }
             else {
-                retObj[key] = { value };
+                retObj[key] = { status: 'fulfilled', value };
             }
         });
-        return sleep(0).then(() => retObj);
+        return Promise.resolve().then(() => ({ ...retObj }));
     });
 }
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.30",
+	"version": "0.1.31",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",