@reykjavik/webtools 0.1.30 → 0.1.32

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.32
+
+_2024-10-02_
+
+- feat: Add module `@reykjavik/webtools/errorhandling` with `asError` and
+  `Result.*` helpers for safe, structured error handling with discriminated
+  `[error, result]` tuples.
+
+## 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

@@ -24,11 +24,21 @@ bun add @reykjavik/webtools
     - [Type `TTLConfig`](#type-ttlconfig)
   - [`toSec` TTL helper](#tosec-ttl-helper)
   - [`toMs` duration helper](#toms-duration-helper)
+- [`@reykjavik/webtools/fixIcelandicLocale`](#reykjavikwebtoolsfixicelandiclocale)
+  - [Limitations](#limitations)
 - [`@reykjavik/webtools/async`](#reykjavikwebtoolsasync)
   - [`promiseAllObject`](#promiseallobject)
   - [`maxWait`](#maxwait)
-- [`@reykjavik/webtools/fixIcelandicLocale`](#reykjavikwebtoolsfixicelandiclocale)
-  - [Limitations](#limitations)
+- [`@reykjavik/webtools/errorhandling`](#reykjavikwebtoolserrorhandling)
+  - [`asError`](#aserror)
+  - [`Result` Singleton](#result-singleton)
+  - [Type `ResultTuple`](#type-resulttuple)
+  - [Type `ResultTupleObj`](#type-resulttupleobj)
+  - [`Result.catch`](#resultcatch)
+  - [`Result.map`](#resultmap)
+  - [`Result.Success`](#resultsuccess)
+  - [`Result.Fail`](#resultfail)
+  - [`Result.throw`](#resultthrow)
 - [`@reykjavik/webtools/SiteImprove`](#reykjavikwebtoolssiteimprove)
   - [`SiteImprove` component](#siteimprove-component)
   - [`pingSiteImprove` helper](#pingsiteimprove-helper)
@@ -236,6 +246,70 @@ const ttlSec = toMs(ttl);
 
 ---
 
+## `@reykjavik/webtools/fixIcelandicLocale`
+
+As of early 2024, Google Chrome still does not support the Icelandic locale
+`is`/`is-IS` in any way. Meanwhile other browsers have supported it for over a
+decade.
+
+This module patches the following methods/classes by substituting the `is`
+locale with `da` (Danish) and apply a few post-hoc fixes to their return
+values.
+
+- `Intl.Collator` and `String.prototype.localeCompare` (\*)
+- `Intl.NumberFormat` and `Number.prototype.toLocaleString` (\*)
+- `Intl.DateTimeFormat` and `Date.prototype.toLocaleString`,
+  `.toLocaleDateString`, and `.toLocaleTimeString` (\*)
+- `Intl.RelativeDateFormat`
+- `Intl.PluralRules`
+- `Intl.ListFormat`
+
+(\*) The results are quite usable, but not entirely perfect. The
+limitations/caveats are listed below.
+
+To apply the patch, simply "side-effect import" this module at the top of your
+app's entry point:
+
+```ts
+import '@reykjavik/webtools/fixIcelandicLocale';
+
+// Then continue with your day and use `localeCompare` and other Intl.* methods
+// as you normally would. (See "limitations" below.)
+```
+
+(**NOTE** The patch is only applied in engines that fail a simple feature
+detection test.)
+
+### Limitations
+
+**`Intl.Collator` and `localeCompare`:**
+
+- 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`:**
+
+- The `style: "unit"` option is not supported and prints units in Danish. (Soo
+  many units and unit-variants…)
+- The `currencyDisplay: "name"` option is not supported and prints the
+  currency's full name in Danish.
+
+**`Intl.DateTimeFormat` and `toLocaleDateString`:**
+
+- The `month: 'narrow'` and `weekday: 'narrow'` options are not supported, and
+  print the corresponding Danish initials.
+- For `timeZoneName` the values `"long"`, `"shortGeneric"` and `"longGeneric"`
+  will appear in Danish.
+- The `timeStyle: 'full'` option prints the timezone names in Danish
+- The `dayPeriod` option has a couple of slight mismatches, at 5 am and 12
+  noon.
+
+We eagerly accept bugfixes, additions, etc. to this module!
+
+---
+
 ## `@reykjavik/webtools/async`
 
 Contains a few small helpers for working with async functions and promises.
@@ -265,23 +339,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,72 +363,237 @@ 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
 ```
 
 ---
 
-## `@reykjavik/webtools/fixIcelandicLocale`
+## `@reykjavik/webtools/errorhandling`
 
-As of early 2024, Google Chrome still does not support the Icelandic locale
-`is`/`is-IS` in any way. Meanwhile other browsers have supported it for over a
-decade.
+A small set of lightweight tools for handling errors and promises in a safer,
+more structured, FP-style way.
 
-This module patches the following methods/classes by substituting the `is`
-locale with `da` (Danish) and apply a few post-hoc fixes to their return
-values.
+Errors are always the first return value to promote early, explicit error
+handling.
 
-- `Intl.Collator` and `String.prototype.localeCompare` (\*)
-- `Intl.NumberFormat` and `Number.prototype.toLocaleString` (\*)
-- `Intl.DateTimeFormat` and `Date.prototype.toLocaleString`,
-  `.toLocaleDateString`, and `.toLocaleTimeString` (\*)
-- `Intl.RelativeDateFormat`
-- `Intl.PluralRules`
-- `Intl.ListFormat`
+### `asError`
 
-(\*) The results are quite usable, but not entirely perfect. The
-limitations/caveats are listed below.
+**Syntax:** `asError(maybeError: unknown): ErrorFromPayload`
 
-To apply the patch, simply "side-effect import" this module at the top of your
-app's entry point:
+Guarantees that a caught (`catch (e)`) value of `unknown` type, is indeed an
+`Error` instance.
+
+If the input is an `Error` instance, it is returned as-is. If the input is
+something else it is wrapped in a new `ErrorFromPayload` instance, and the
+original value is stored in a `payload`
 
 ```ts
-import '@reykjavik/webtools/fixIcelandicLocale';
+import { asError, type ErrorFromPayload } from '@reykjavik/webtools/errorhandling';
+
+const theError = new Error('Something went wrong');
+try {
+  throw theError;
+} catch (err) {
+  const error = asError(theError);
+  console.error(error === theError); // true
+  console.error('patload' in error); // false
+}
 
-// Then continue with your day and use `localeCompare` and other Intl.* methods
-// as you normally would. (See "limitations" below.)
+const someObject = ['Something went wrong'];
+try {
+  throw someObject;
+} catch (err) {
+  const error = asError(someObject);
+  console.error(error === someObject); // false
+  console.error(error.message === someObject.join(',')); // false
+  console.error(error instanceOf ErrorFromPayload); // true
+  console.error(error.payload === someObject); // true
+}
 ```
 
-(**NOTE** The patch is only applied in engines that fail a simple feature
-detection test.)
+### `Result` Singleton
 
-### Limitations
+Singleton object with the following small methods for creating, mapping or
+handling `ResultTupleObj` instances:
 
-**`Intl.Collator` and `localeCompare`:**
+- `Result.Success`
+- `Result.Fail`
+- `Result.catch`
+- `Result.map`
+- `Result.throw`
 
-- 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.
+### Type `ResultTuple`
 
-**`Intl.NumberFormat` and `toLocaleString`:**
+**Syntax:** `ResultTuple<ResultType, OptionalErrorType>`
 
-- The `style: "unit"` option is not supported and prints units in Danish. (Soo
-  many units and unit-variants…)
-- The `currencyDisplay: "name"` option is not supported and prints the
-  currency's full name in Danish.
+(Also aliased as `Result.Tuple`)
 
-**`Intl.DateTimeFormat` and `toLocaleDateString`:**
+Simple bare-bones discriminated tuple type for a `[error, result]` pair.
 
-- The `month: 'narrow'` and `weekday: 'narrow'` options are not supported, and
-  print the corresponding Danish initials.
-- For `timeZoneName` the values `"long"`, `"shortGeneric"` and `"longGeneric"`
-  will appear in Danish.
-- The `timeStyle: 'full'` option prints the timezone names in Danish
-- The `dayPeriod` option has a couple of slight mismatches, at 5 am and 12
-  noon.
+```ts
+import { type ResultTuple } from '@reykjavik/webtools/errorhandling';
 
-We eagerly accept bugfixes, additions, etc. to this module!
+declare const myResult: ResultTuple<string, Error>;
+
+const [error, result] = myResult;
+// Either `error` or `result` will be `undefined`
+
+if (error) {
+  // Here `error` is an Error instance
+  console.error(error.message);
+} else {
+  // Here `result` is guaranteed to be a string
+  console.log(result);
+}
+```
+
+### Type `ResultTupleObj`
+
+**Syntax:** `ResultTupleObj<ResultType, OptionalErrorType>`
+
+(Also aliased as `Result.TupleObj`)
+
+Discriminated tuple type for a `[error, result]` pair (same as `ResultTuple`)
+but with named properties `error` and `result` attached for dev convenience.
+
+```ts
+import { type ResultTuple } from '@reykjavik/webtools/errorhandling';
+
+declare const myResult: ResultTuple<string, Error>;
+
+const [error, result] = myResult;
+// Either `error` or `result` will be `undefined`
+
+if (error) {
+  // Here `error` is an Error instance
+  console.error(error.message);
+} else {
+  // Here `result` is guaranteed to be a string
+  console.log(result);
+}
+
+// But `myResults` also has named properties, for convenience
+if (myResult.error) {
+  // Here `myResult.error` is an Error instance
+  console.error(myResult.error.message);
+} else {
+  // Here `myResult.result` is a string
+  console.log(myResult.result);
+}
+```
+
+### `Result.catch`
+
+**Syntax:** `Result.catch<T, Err>(callback: () => T): ResultTupleObj<T, Err>`
+**Syntax:**
+`Result.catch<T, Err>(promise: Promise<T>): Promise<ResultTupleObj<T, Err>>`
+
+Error handling utility that wraps a promise or a callback function.
+
+Catches errors and returns a `ResultTupleObj` — a nice discriminated
+`[error, results]` tuple with the `result` and `error` also attached as named
+properties.
+
+Works on both promises and sync callback functions.
+
+```ts
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+// Callback:
+const [error, fooObject] = Result.catch(() => getFooSyncMayThrow());
+// Promise:
+const [error, fooObject] = await Result.catch(getFooPromiseMayThrow());
+
+// Example of object property access:
+const fooQuery = await Result.catch(getFooPromiseMayThrow());
+if (fooQuery.error) {
+  console.log(fooQuery.error === fooQuery[0]); // true
+  throw fooQuery.error;
+}
+console.log(fooQuery.result === fooQuery[1]); // true
+fooQuery.result; // Guaranteed to be defined
+```
+
+This function acts as the inverse of [`Result.throw()`](#resultthrow).
+
+### `Result.map`
+
+**Syntax:**
+`Result.map<T, T2, E>(result: ResultTuple<T, E>, mapResult: (resultValue: T) => T2): ResultTuple<T2, E>`
+
+Helper to map a `ResultTuple`-like object to a new `ResultTupleObj` object,
+applying a transformation function to the result, but retaining the error
+as-is.
+
+```ts
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+const getStrLength = (str: string) => str.length;
+
+const resultTuple =
+  Math.random() < 0.5 ? [new Error('Fail')] : [undefined, 'Hello!'];
+
+const [error, mappedResult] = Result.map(resultTuple, getStrLength);
+
+if (result) {
+  console.log(result); // 6
+}
+```
+
+### `Result.Success`
+
+**Syntax:** `Result.Success<T>(result: T): ResultTuple<T>`
+
+Factory for creating a successful `ResultTupleObj`.
+
+```ts
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+const happyResult: Result.SuccessObj<string> =
+  Result.Success('My result value');
+
+console.log(happyResult.error); // undefined
+console.log(happyResult[0]); // undefined
+console.log(happyResult.result); // 'My result value'
+console.log(happyResult[1]); // 'My result value'
+```
+
+### `Result.Fail`
+
+**Syntax:** `Result.Fail<E extends Error>(err: T): ResultTuple<unknown, Err>`
+
+Factory for creating a failed `ResultTupleObj`.
+
+```ts
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+const happyResult: Result.FailObj<string> = Result.Fail(new Error('Oh no!'));
+
+console.log(happyResult.error.message); // 'Oh no!'
+console.log(happyResult[0].message); // 'Oh no!'
+console.log(happyResult.result); // undefined
+console.log(happyResult[1]); // undefined
+```
+
+### `Result.throw`
+
+**Syntax:** `Result.throw<T>(result: ResultTuple<T>): T`
+
+Unwraps a discriminated `ResultTuple`-like `[error, result]` tuple and throws
+if there's an error, but returns the result otherwise.
+
+```ts
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+try {
+  const fooResults = Result.throw(await getFooResultsTuple());
+} catch (fooError) {
+  // error is
+}
+```
+
+This function acts as the inverse of [`Result.catch()`](#resultcatch).
 
 ---
 

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/errorhandling.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare class ErrorFromPayload extends Error {
+    payload?: unknown;
+    constructor(payload: unknown);
+    name: string;
+}
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare const asError: (maybeError: unknown) => ErrorFromPayload;
+type SuccessResult<T> = [error: undefined, result: T] & {
+    error?: undefined;
+    result: T;
+};
+type FailResult<E extends Error> = [error: E] & {
+    error: E;
+    result?: undefined;
+};
+/**
+ * Simple bare-bones discriminated tuple type for a [error, result] pair.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttuple
+ */
+export type ResultTuple<T, E extends Error = Error> = [error: undefined, result: T] | [error: E];
+/**
+ * Discriminated tuple type for a `[error, result]` pair (same as `ResultTuple`)
+ * but with named properties `error` and `result` attached for dev convenience.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttupleobj
+ */
+export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | FailResult<E>;
+/**
+ * Error handling utility that wraps a promise or a callback function.
+ *
+ * Catches errors and returns a `ResultTupleObj` — a nice discriminated
+ * `[error, results]` tuple with the `result` and `error` also attached as
+ * named properties.
+ *
+ * Works on both promises and sync callback functions.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultcatch
+ */
+declare function catch_<T, E extends Error = ErrorFromPayload>(promise: Promise<T>): Promise<ResultTupleObj<T, E>>;
+declare function catch_<T, E extends Error = ErrorFromPayload>(callback: () => T): ResultTupleObj<T, E>;
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+export declare const Result: {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success: <T>(result: T) => SuccessResult<T>;
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail: <E extends Error = Error>(e: unknown) => FailResult<E>;
+    catch: typeof catch_;
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: <T_1, T2, E_1 extends Error>(result: ResultTuple<T_1, E_1>, mapFn: (resultValue: T_1) => T2) => ResultTupleObj<T2, E_1>;
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: <T_2>(result: ResultTuple<T_2, Error>) => T_2;
+};
+export declare namespace Result {
+    type Tuple<T, E extends Error = Error> = ResultTuple<T, E>;
+    type TupleObj<T, E extends Error = Error> = ResultTupleObj<T, E>;
+    type SuccessObj<T> = SuccessResult<T>;
+    type FailObj<E extends Error> = FailResult<E>;
+}
+export {};

package/errorhandling.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = exports.asError = exports.ErrorFromPayload = void 0;
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+class ErrorFromPayload extends Error {
+    constructor(payload) {
+        if (process.env.NODE_ENV !== 'production' && payload instanceof Error) {
+            throw new Error('Do not pass an Error instance as payload, just use it directly');
+        }
+        const message = (payload != null ? String(payload) : '') || 'Threw a falsy/empty value';
+        super(message);
+        this.name = 'ErrorFromPayload';
+        this.payload = payload;
+    }
+}
+exports.ErrorFromPayload = ErrorFromPayload;
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+const asError = (maybeError) => {
+    if (maybeError instanceof Error) {
+        return maybeError;
+    }
+    return new ErrorFromPayload(maybeError);
+};
+exports.asError = asError;
+const Success = (result) => {
+    const tuple = [undefined, result];
+    tuple.result = result;
+    return tuple;
+};
+const Fail = (e) => {
+    const tuple = [(0, exports.asError)(e)];
+    tuple.error = tuple[0];
+    return tuple;
+};
+function catch_(something) {
+    if (something instanceof Promise) {
+        return something.then((result) => Success(result), (e) => Fail(e));
+    }
+    try {
+        return Success(something());
+    }
+    catch (e) {
+        return Fail(e);
+    }
+}
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+exports.Result = {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success,
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail,
+    // NOTE: The JSDoc must be placed above the `catch_` function above.
+    catch: catch_,
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: (result, mapFn) => {
+        const [error, resultValue] = result;
+        if (error) {
+            return Fail(error);
+        }
+        return Success(mapFn(resultValue));
+    },
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: (result) => {
+        if (result[0]) {
+            throw result[0];
+        }
+        return result[1];
+    },
+};

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/esm/errorhandling.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare class ErrorFromPayload extends Error {
+    payload?: unknown;
+    constructor(payload: unknown);
+    name: string;
+}
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare const asError: (maybeError: unknown) => ErrorFromPayload;
+type SuccessResult<T> = [error: undefined, result: T] & {
+    error?: undefined;
+    result: T;
+};
+type FailResult<E extends Error> = [error: E] & {
+    error: E;
+    result?: undefined;
+};
+/**
+ * Simple bare-bones discriminated tuple type for a [error, result] pair.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttuple
+ */
+export type ResultTuple<T, E extends Error = Error> = [error: undefined, result: T] | [error: E];
+/**
+ * Discriminated tuple type for a `[error, result]` pair (same as `ResultTuple`)
+ * but with named properties `error` and `result` attached for dev convenience.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttupleobj
+ */
+export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | FailResult<E>;
+/**
+ * Error handling utility that wraps a promise or a callback function.
+ *
+ * Catches errors and returns a `ResultTupleObj` — a nice discriminated
+ * `[error, results]` tuple with the `result` and `error` also attached as
+ * named properties.
+ *
+ * Works on both promises and sync callback functions.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultcatch
+ */
+declare function catch_<T, E extends Error = ErrorFromPayload>(promise: Promise<T>): Promise<ResultTupleObj<T, E>>;
+declare function catch_<T, E extends Error = ErrorFromPayload>(callback: () => T): ResultTupleObj<T, E>;
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+export declare const Result: {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success: <T>(result: T) => SuccessResult<T>;
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail: <E extends Error = Error>(e: unknown) => FailResult<E>;
+    catch: typeof catch_;
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: <T_1, T2, E_1 extends Error>(result: ResultTuple<T_1, E_1>, mapFn: (resultValue: T_1) => T2) => ResultTupleObj<T2, E_1>;
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: <T_2>(result: ResultTuple<T_2, Error>) => T_2;
+};
+export declare namespace Result {
+    type Tuple<T, E extends Error = Error> = ResultTuple<T, E>;
+    type TupleObj<T, E extends Error = Error> = ResultTupleObj<T, E>;
+    type SuccessObj<T> = SuccessResult<T>;
+    type FailObj<E extends Error> = FailResult<E>;
+}
+export {};

package/esm/errorhandling.js

@@ -0,0 +1,102 @@
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export class ErrorFromPayload extends Error {
+    constructor(payload) {
+        if (process.env.NODE_ENV !== 'production' && payload instanceof Error) {
+            throw new Error('Do not pass an Error instance as payload, just use it directly');
+        }
+        const message = (payload != null ? String(payload) : '') || 'Threw a falsy/empty value';
+        super(message);
+        this.name = 'ErrorFromPayload';
+        this.payload = payload;
+    }
+}
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export const asError = (maybeError) => {
+    if (maybeError instanceof Error) {
+        return maybeError;
+    }
+    return new ErrorFromPayload(maybeError);
+};
+const Success = (result) => {
+    const tuple = [undefined, result];
+    tuple.result = result;
+    return tuple;
+};
+const Fail = (e) => {
+    const tuple = [asError(e)];
+    tuple.error = tuple[0];
+    return tuple;
+};
+function catch_(something) {
+    if (something instanceof Promise) {
+        return something.then((result) => Success(result), (e) => Fail(e));
+    }
+    try {
+        return Success(something());
+    }
+    catch (e) {
+        return Fail(e);
+    }
+}
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+export const Result = {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success,
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail,
+    // NOTE: The JSDoc must be placed above the `catch_` function above.
+    catch: catch_,
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: (result, mapFn) => {
+        const [error, resultValue] = result;
+        if (error) {
+            return Fail(error);
+        }
+        return Success(mapFn(resultValue));
+    },
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: (result) => {
+        if (result[0]) {
+            throw result[0];
+        }
+        return result[1];
+    },
+};

package/esm/index.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />
 /// <reference path="./fixIcelandicLocale.d.ts" />
+/// <reference path="./errorhandling.d.ts" />
 /// <reference path="./remix/http.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />

package/index.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />
 /// <reference path="./fixIcelandicLocale.d.ts" />
+/// <reference path="./errorhandling.d.ts" />
 /// <reference path="./remix/http.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.30",
+	"version": "0.1.32",
 	"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",
@@ -64,6 +64,10 @@
 			"import": "./esm/fixIcelandicLocale.js",
 			"require": "./fixIcelandicLocale.js"
 		},
+		"./errorhandling": {
+			"import": "./esm/errorhandling.js",
+			"require": "./errorhandling.js"
+		},
 		"./remix/http": {
 			"import": "./esm/remix/http.js",
 			"require": "./remix/http.js"