@aedge-io/grugway 0.0.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![codecov](https://codecov.io/github/aedge-io/grugway/graph/badge.svg?token=9WTDQ8WOKW)](https://codecov.io/github/aedge-io/grugway)
 
-> Safe abstractions for fallible flows — for humans and clankers alike.
+> Safe abstractions for fallible flows — for humans, their clankers and foes.
 
 This is a ~~fork~~ rework of an old, personal project
 [eitherway](https://github.com/realpha/eitherway).

package/esm/async/task.js

@@ -1,12 +1,13 @@
 import { asInfallible, Err, Ok } from "../core/result.js";
-import { andEnsureTask, chainTaskFailure, chainTaskSuccess, cloneTask, inspectTaskFailure, inspectTaskSuccess, iterTask, mapTaskFailure, mapTaskSuccess, mapTaskSuccessOr, mapTaskSuccessOrElse, orEnsureTask, tapTask, unwrapTask, unwrapTaskOr, unwrapTaskOrElse, zipTask, } from "./_internal.js";
 /**
  * # Task<T, E>
  *
- * `Task<T, E>` is a composeable extension of `Promise<Result<T, E>>`
+ * `Task<T, E>` is a composeable equivalent of `Promise<Result<T, E>>`
  *
- * It is a `Promise` sub-class, which never rejects, but always resolves.
- * Either with an `Ok<T>` or an `Err<E>`
+ * It never rejects, but always resolves. Either with an `Ok<T>` or an `Err<E>`
+ *
+ * It implements the full interface of `Promise<Result<T, E>>` and can be used
+ * as a drop-in replacement if desired.
  *
  * It supports almost the same API as {@linkcode Result} and allows for
  * the same composition patterns as {@linkcode Result}
@@ -16,33 +17,35 @@ import { andEnsureTask, chainTaskFailure, chainTaskSuccess, cloneTask, inspectTa
  *
  * @category Task#Basic
  */
-export class Task extends Promise {
-    constructor(executor) {
-        super(executor);
+export class Task {
+    #promise;
+    constructor(promise) {
+        this.#promise = promise;
     }
     /**
-     * =======================
-     *    TASK CONSTRUCTORS
-     * =======================
+     * This is done to provide drop-in parity with native Promises, as some libraries
+     * are (IMO needlessly) invariant over `PromiseLike` types and test for `thenability`
+     * via `value instanceof Promise`
      */
+    static {
+        Object.setPrototypeOf(Task.prototype, Promise.prototype);
+    }
     /**
-     * Use this to create a task from a `Result<T, E>` value
-     *
-     * @category Task#Basic
-     *
-     * @example
-     * ```typescript
-     * import { Ok, Result, Task } from "../mod.ts";
-     *
-     * async function produceRes(): Promise<Result<number, TypeError>> {
-     *  return Ok(42);
-     * }
-     *
-     * const task = Task.of(produceRes());
-     * ```
+     * =======================
+     *   PROMISE INTERFACE
+     * =======================
      */
+    then(onfulfilled, onrejected) {
+        return this.#promise.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.#promise.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.#promise.finally(onfinally);
+    }
     static of(value) {
-        return new Task((resolve) => resolve(value));
+        return new Task(Promise.resolve(value));
     }
     /**
      * Use this to create a `Task` which always succeeds with a value `<T>`
@@ -51,13 +54,13 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * const task: Task<number, never> = Task.succeed(42);
      * ```
      */
     static succeed(value) {
-        return new Task((resolve) => resolve(Ok(value)));
+        return new Task(Promise.resolve(Ok(value)));
     }
     /**
      * Use this to create a `Task` which always fails with a value `<E>`
@@ -66,13 +69,13 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * const task: Task<never, number> = Task.fail(1);
      * ```
      */
     static fail(error) {
-        return new Task((resolve) => resolve(Err(error)));
+        return new Task(Promise.resolve(Err(error)));
     }
     /**
      * Use this to create a deferred `Task<T, E>` which will either succeed with
@@ -87,7 +90,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * class TimeoutError extends Error {}
      *
@@ -106,9 +109,10 @@ export class Task extends Promise {
      */
     static deferred() {
         let resolveBinding;
-        const task = new Task((resolve) => {
+        const promise = new Promise((resolve) => {
             resolveBinding = resolve;
         });
+        const task = new Task(promise);
         const succeed = (value) => resolveBinding(Ok(value));
         const fail = (error) => resolveBinding(Err(error));
         return { task, succeed, fail };
@@ -125,7 +129,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Ok, Result, Task } from "../mod.ts";
+     * import { Ok, Result, Task } from "@aedge-io/grugway";
      *
      * async function produceRes(): Promise<Result<number, TypeError>> {
      *  return Ok(42);
@@ -137,7 +141,7 @@ export class Task extends Promise {
     static from(fn) {
         const p = new Promise((resolve) => resolve(fn()))
             .catch(asInfallible);
-        return new Task((resolve) => resolve(p));
+        return new Task(p);
     }
     /**
      * Use this to create a `Task<T, E>` from a `Promise<T>`.
@@ -152,7 +156,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { asInfallible, Task } from "../mod.ts";
+     * import { asInfallible, Task } from "@aedge-io/grugway";
      *
      * const willBeString = Promise.resolve("42");
      *
@@ -165,7 +169,7 @@ export class Task extends Promise {
      * ```
      */
     static fromPromise(promise, errorMapFn) {
-        return Task.fromFallible(() => promise, errorMapFn);
+        return new Task(promise.then((v) => Ok(v), (e) => Err(errorMapFn(e))));
     }
     /**
      * Use this to construct a `Task<T, E>` from the return value of a fallible
@@ -175,7 +179,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * async function rand(): Promise<number> {
      *   throw new TypeError("Oops");
@@ -195,7 +199,7 @@ export class Task extends Promise {
     static fromFallible(fn, errorMapFn) {
         const p = new Promise((resolve) => resolve(fn()))
             .then((v) => Ok(v), (e) => Err(errorMapFn(e)));
-        return new Task((resolve) => resolve(p));
+        return new Task(p);
     }
     /**
      * Use this lift a function into a `Task` context, by composing the wrapped
@@ -210,7 +214,7 @@ export class Task extends Promise {
      *
      * @example
      * ```
-     * import { Err, Ok, Result, Task } from "../mod.ts";
+     * import { Err, Ok, Result, Task } from "@aedge-io/grugway";
      *
      * async function toSpecialString(s: string): Promise<string> {
      *   if (s.length % 3 === 0) return s;
@@ -231,7 +235,7 @@ export class Task extends Promise {
         return function (...args) {
             const p = new Promise((resolve) => resolve(fn(...args)))
                 .then((v) => ctor(v), (e) => Err(errorMapFn(e)));
-            return new Task((resolve) => resolve(p));
+            return new Task(p);
         };
     }
     /**
@@ -251,26 +255,175 @@ export class Task extends Promise {
     id() {
         return this;
     }
+    /**
+     * Use this to obtain a deep clone of `Task<T, E>`
+     *
+     * Under the hood, this uses the `structuredClone` algorithm
+     *
+     * @category Task#Basic
+     *
+     * @example
+     * ```typescript
+     * import { assert } from "@std/assert";
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.succeed({ a: 1 });
+     * const cloned = task.clone();
+     *
+     * const res = await task;
+     * const clonedRes = await cloned;
+     *
+     * assert(res.unwrap() !== clonedRes.unwrap())
+     * ```
+     */
     clone() {
-        return Task.of(cloneTask(this));
+        return new Task(this.#promise.then((res) => res.clone()));
     }
+    /**
+     * Use this to asynchronously map the encapsulated value `<T>` to `<T2>`
+     *
+     * In case of `Err<E>`, this method short-circuits.
+     * See {@linkcode Task#mapErr} for the opposite case.
+     *
+     * @category Task#Basic
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.succeed(21).map((n) => n * 2);
+     * const res = await task; // Ok(42)
+     * ```
+     */
     map(mapFn) {
-        return Task.of(mapTaskSuccess(this, mapFn));
+        return new Task(this.#promise.then(async (res) => {
+            if (res.isErr())
+                return res;
+            return Ok(await mapFn(res.unwrap()));
+        }));
     }
+    /**
+     * Same as {@linkcode Task#map} but returns the provided `orValue` asynchronously
+     * as a fallback in case of `Err<E>`
+     *
+     * @category Task#Intermediate
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const t1 = Task.succeed(5).mapOr((n) => n * 2, 0); // Task<number, never>
+     * const t2 = Task.fail("x").mapOr((n) => n * 2, 0);  // Task<number, never>
+     * ```
+     */
     mapOr(mapFn, orValue) {
-        return Task.of(mapTaskSuccessOr(this, mapFn, orValue));
+        return new Task(this.#promise.then(async (res) => {
+            const mapped = res.isErr() ? await orValue : await mapFn(res.unwrap());
+            return Ok(mapped);
+        }));
     }
+    /**
+     * Same as {@linkcode Task#map} but applies `orFn` asynchronously to the
+     * error value in case of `Err<E>`
+     *
+     * Use this if the fallback value is expensive to produce.
+     *
+     * @category Task#Intermediate
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const t1 = Task.succeed(5).mapOrElse((n) => n * 2, (e) => -1);  // Ok(10)
+     * const t2 = Task.fail("x").mapOrElse((n) => n * 2, (e) => -1);   // Ok(-1)
+     * ```
+     */
     mapOrElse(mapFn, orFn) {
-        return Task.of(mapTaskSuccessOrElse(this, mapFn, orFn));
+        return new Task(this.#promise.then(async (res) => {
+            const mapped = res.isErr()
+                ? await orFn(res.unwrap())
+                : await mapFn(res.unwrap());
+            return Ok(mapped);
+        }));
     }
+    /**
+     * Use this to asynchronously map the encapsulated error `<E>` to `<E2>`
+     *
+     * In case of `Ok<T>`, this method short-circuits.
+     * See {@linkcode Task#map} for the opposite case.
+     *
+     * @category Task#Basic
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.fail(Error("oops"))
+     *   .mapErr((e) => TypeError(e.message));
+     *
+     * const res = await task; // Err<TypeError>
+     * ```
+     */
     mapErr(mapFn) {
-        return Task.of(mapTaskFailure(this, mapFn));
+        return new Task(this.#promise.then(async (res) => {
+            if (res.isOk())
+                return res;
+            return Err(await mapFn(res.unwrap()));
+        }));
     }
+    /**
+     * Use this to produce a new `Task<T2, E2>` from the encapsulated
+     * value `<T>`. Canonical `.flatMap()` or `.chain()` method.
+     *
+     * In case of `Err<E>`, this method short-circuits.
+     * See {@linkcode Task#orElse} for the opposite case.
+     *
+     * @category Task#Intermediate
+     *
+     * @example
+     * ```typescript
+     * import { Err, Ok, Task } from "@aedge-io/grugway";
+     *
+     * const safeParse = async (s: string) => {
+     *   const n = Number(s);
+     *   return Number.isNaN(n) ? Err(TypeError("NaN")) : Ok(n);
+     * };
+     *
+     * const t = Task.succeed("42").andThen(safeParse); // Task<number, TypeError>
+     * ```
+     */
     andThen(thenFn) {
-        return Task.of(chainTaskSuccess(this, thenFn));
+        return new Task(this.#promise.then((res) => {
+            if (res.isErr())
+                return res;
+            return thenFn(res.unwrap());
+        }));
     }
+    /**
+     * Use this to produce a new `Task<T2, E2>` from the encapsulated
+     * error `<E>`. Useful for recovery or error transformation.
+     *
+     * In case of `Ok<T>`, this method short-circuits.
+     * See {@linkcode Task#andThen} for the opposite case.
+     *
+     * @category Task#Intermediate
+     *
+     * @example
+     * ```typescript
+     * import { Ok, Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.fail(Error("oops"))
+     *   .orElse((e) => Ok(e.message));
+     *
+     * const res = await task; // Ok<string>
+     * ```
+     */
     orElse(elseFn) {
-        return Task.of(chainTaskFailure(this, elseFn));
+        return new Task(this.#promise.then((res) => {
+            if (res.isOk())
+                return res;
+            return elseFn(res.unwrap());
+        }));
     }
     /**
      * Use this to conditionally pass-through the encapsulated value `<T>`
@@ -297,7 +450,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * function getPath(): Task<string, Error> { return Task.succeed("/home")};
      * function isReadableDir(path: string): Task<void, TypeError> { return Task.succeed(undefined) };
@@ -311,7 +464,12 @@ export class Task extends Promise {
      * ```
      */
     andEnsure(ensureFn) {
-        return Task.of(andEnsureTask(this, ensureFn));
+        return new Task(this.#promise.then(async (original) => {
+            if (original.isErr())
+                return original;
+            const res = await ensureFn(original.unwrap());
+            return res.and(original);
+        }));
     }
     /**
      * Use this to conditionally pass-through the encapsulated value `<E>`
@@ -338,7 +496,7 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { Task } from "./task.ts";
+     * import { Task } from "@aedge-io/grugway";
      *
      * function getConfig(): Task<string, RangeError> { return Task.succeed("secret")};
      * function getFallback(err: RangeError): Task<string, Error> { return Task.succeed("default")};
@@ -352,31 +510,110 @@ export class Task extends Promise {
      * ```
      */
     orEnsure(ensureFn) {
-        return Task.of(orEnsureTask(this, ensureFn));
+        return new Task(this.#promise.then(async (original) => {
+            if (original.isOk())
+                return original;
+            const res = await ensureFn(original.unwrap());
+            return res.or(original);
+        }));
     }
+    /**
+     * Use this to asynchronously zip the encapsulated values of two `Ok`
+     * instances into a new `Task`
+     *
+     * If either side is `Err`, the respective `Err` is returned.
+     *
+     * |**LHS zip RHS** |**RHS: Ok<T2>**|**RHS: Err<E2>**|
+     * |:--------------:|:-------------:|:--------------:|
+     * | **LHS: Ok<T>** |  Ok<[T, T2]>  |     Err<E2>    |
+     * | **LHS: Err<E>**|     Err<E>    |     Err<E>     |
+     *
+     * @category Task#Advanced
+     *
+     * @example
+     * ```typescript
+     * import { Ok, Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.succeed(1).zip(Task.of(Ok("two")));
+     * const res = await task; // Ok([1, "two"])
+     * ```
+     */
     zip(rhs) {
-        return Task.of(zipTask(this, rhs));
+        return new Task(this.#promise.then(async (res) => {
+            return res.zip(await rhs);
+        }));
     }
+    /**
+     * Use this to perform asynchronous side-effects transparently.
+     *
+     * The `tapFn` receives a deep clone of the `Result<T, E>` to ensure
+     * the original value cannot be mutated.
+     *
+     * @category Task#Intermediate
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.succeed(42)
+     *   .tap((res) => console.log("got:", res.unwrap()));
+     * ```
+     */
     tap(tapFn) {
-        return Task.of(tapTask(this, tapFn));
-    }
-    inspect(inspectFn) {
-        return Task.of(inspectTaskSuccess(this, inspectFn));
-    }
-    inspectErr(inspectFn) {
-        return Task.of(inspectTaskFailure(this, inspectFn));
+        return new Task(this.#promise.then(async (res) => {
+            await tapFn(res.clone());
+            return res;
+        }));
     }
     /**
-     * @deprecated (will be removed in 1.0.0) use {@linkcode Task#andEnsure} instead
+     * Use this to asynchronously inspect the encapsulated value `<T>`.
+     *
+     * Mainly used for debugging and logging.
+     *
+     * In case of `Err<E>`, this method short-circuits.
+     * See {@linkcode Task#inspectErr} for the opposite case.
+     *
+     * @category Task#Basic
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.succeed(42)
+     *   .inspect((n) => console.log("value:", n));
+     * ```
      */
-    trip(tripFn) {
-        return Task.of(andEnsureTask(this, tripFn));
+    inspect(inspectFn) {
+        return new Task(this.#promise.then(async (res) => {
+            if (res.isOk())
+                await inspectFn(res.unwrap());
+            return res;
+        }));
     }
     /**
-     * @deprecated (will be removed in 1.0.0) use {@linkcode Task#orEnsure} instead
+     * Use this to asynchronously inspect the encapsulated error `<E>`.
+     *
+     * Mainly used for debugging and logging.
+     *
+     * In case of `Ok<T>`, this method short-circuits.
+     * See {@linkcode Task#inspect} for the opposite case.
+     *
+     * @category Task#Basic
+     *
+     * @example
+     * ```typescript
+     * import { Task } from "@aedge-io/grugway";
+     *
+     * const task = Task.fail(Error("oops"))
+     *   .inspectErr((e) => console.error("error:", e.message));
+     * ```
      */
-    rise(riseFn) {
-        return Task.of(orEnsureTask(this, riseFn));
+    inspectErr(inspectFn) {
+        return new Task(this.#promise.then(async (res) => {
+            if (res.isErr())
+                await inspectFn(res.unwrap());
+            return res;
+        }));
     }
     /**
      * Use this to get the wrapped value out of an `Task<T, E>` instance
@@ -391,9 +628,8 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts";
-     * import { Result } from "../core/result.ts";
-     * import { Task } from "./task.ts";
+     * import { assert } from "@std/assert";
+     * import { Result, Task } from "@aedge-io/grugway";
      *
      * const ok = Result(42) as Result<number, string>;
      * const task = Task.of(ok);
@@ -403,8 +639,8 @@ export class Task extends Promise {
      * assert(union === 42);
      * ```
      */
-    unwrap() {
-        return unwrapTask(this);
+    async unwrap() {
+        return (await this.#promise).unwrap();
     }
     /**
      * Same as {@linkcode Task#unwrap} but returns a default value in case the
@@ -414,9 +650,8 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts";
-     * import { Result } from "../core/result.ts";
-     * import { Task } from "./task.ts";
+     * import { assert } from "@std/assert";
+     * import { Result, Task } from "@aedge-io/grugway";
      *
      * const err = Result(Error()) as Result<number, Error>;
      * const task = Task.of(err);
@@ -426,8 +661,11 @@ export class Task extends Promise {
      * assert(union === "foo");
      * ```
      */
-    unwrapOr(orValue) {
-        return unwrapTaskOr(this, orValue);
+    async unwrapOr(orValue) {
+        const res = await this.#promise;
+        if (res.isOk())
+            return res.unwrap();
+        return await orValue;
     }
     /**
      * Same as {@linkcode Task#unwrap} but returns a fallback value, which can based
@@ -437,9 +675,8 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts";
-     * import { Result } from "../core/result.ts";
-     * import { Task } from "./task.ts";
+     * import { assert } from "@std/assert";
+     * import { Result, Task } from "@aedge-io/grugway";
      *
      * const err = Result(Error("foo")) as Result<number, Error>;
      * const task = Task.of(err);
@@ -451,8 +688,11 @@ export class Task extends Promise {
      * assert(union === "foo");
      * ```
      */
-    unwrapOrElse(orFn) {
-        return unwrapTaskOrElse(this, orFn);
+    async unwrapOrElse(orFn) {
+        const res = await this.#promise;
+        if (res.isOk())
+            return res.unwrap();
+        return await orFn(res.unwrap());
     }
     /**
      * Use this to obtain an async iterator of the encapsulated value `<T>`
@@ -463,8 +703,8 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts"
-     * import { Err, Ok, Result, Task } from "../mod.ts";
+     * import { assert } from "@std/assert"
+     * import { Err, Ok, Result, Task } from "@aedge-io/grugway";
      *
      * const success = Task.succeed(42);
      * const failure = Task.fail(Error());
@@ -498,8 +738,11 @@ export class Task extends Promise {
      * main().then(() => console.log("Done"));
      * ```
      */
-    iter() {
-        return iterTask(this);
+    async *iter() {
+        const res = await this.#promise;
+        if (res.isErr())
+            return;
+        yield res.unwrap();
     }
     /**
      * ============================
@@ -516,12 +759,12 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts";
-     * import { Task } from "./task.ts"
+     * import { assert } from "@std/assert";
+     * import { Task } from "@aedge-io/grugway"
      *
      * const tag = Task.succeed(42).toString();
      *
-     * assert(tag === "[object aetherway.Task]");
+     * assert(tag === "[object grugway.Task]");
      * ```
      */
     toString() {
@@ -541,22 +784,19 @@ export class Task extends Promise {
      *
      * @example
      * ```typescript
-     * import { assert } from "../core/assert.ts";
-     * import { Task } from "./task.ts"
+     * import { assert } from "@std/assert";
+     * import { Task } from "@aedge-io/grugway"
      *
      * const task = Task.succeed({ a: 1, b: 2 });
      *
      * const toString = Object.prototype.toString;
      *
-     * assert(toString.call(task) === "[object aetherway.Task]");
-     * assert(toString.call(Task) === "[object aetherway.Task]");
+     * assert(toString.call(task) === "[object grugway.Task]");
+     * assert(toString.call(Task) === "[object grugway.Task]");
      * ```
      */
     get [Symbol.toStringTag]() {
-        return "aetherway.Task";
-    }
-    static get [Symbol.toStringTag]() {
-        return "aetherway.Task";
+        return "grugway.Task";
     }
     /**
      * In case of success AND that the encapsulated value `<T>` implements the