@reykjavik/webtools 0.1.31 → 0.1.32

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 - ... <!-- 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_

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.
@@ -295,67 +369,231 @@ 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 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.
+### 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/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/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.31",
+	"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"