✨ expose Result<T> as public API

lib/action.ts

@@ -63,7 +63,7 @@ export function action<T>(executor: Executor<T>, desc?: string): Operation<T> {
               discard();
               discarded(Ok());
             } catch (error) {
-              discarded(Err(error as Error));
+              discarded(Err(error));
             }
           };
         },

lib/box.ts

@@ -5,6 +5,6 @@ export function* box<T>(op: () => Operation<T>): Operation<Result<T>> {
   try {
     return Ok(yield* op());
   } catch (error) {
-    return Err(error as Error);
+    return Err(error);
   }
 }

lib/delimiter.ts

@@ -86,7 +86,7 @@ export class Delimiter<T>
       }
     } catch (error) {
       this.computed = true;
-      this.outcome = Just(Err(error as Error));
+      this.outcome = Just(Err(error));
     } finally {
       this.finalized = true;
       this.outcome = this.outcome ?? Nothing();

lib/race.ts

@@ -45,7 +45,7 @@ export function* race<T extends Operation<unknown>>(
             let value = yield* operation;
             winner.resolve(Ok(value as Yielded<T>));
           } catch (error) {
-            winner.resolve(Err(error as Error));
+            winner.resolve(Err(error));
           }
         }),
       );

lib/reducer.ts

@@ -48,7 +48,7 @@ export class Reducer {
             throw result.error;
           }
         } catch (error) {
-          routine.next(Err(error as Error));
+          routine.next(Err(error));
         }
         item = queue.dequeue();
       }

lib/result.ts

@@ -1,5 +1,14 @@
 /**
- * @ignore
+ * A value representing either a successful outcome or an error.
+ *
+ * `Result<T>` is used in APIs when you want to make explicit flow control
+ * decisions about success/failure rather than allowing them to
+ * automatically percolate.
+ *
+ * A successful result has the shape `{ ok: true, value }` and a failed result
+ * has the shape `{ ok: false, error }`.
+ *
+ * @since 4.1
  */
 export type Result<T> = {
   readonly ok: true;
@@ -10,7 +19,18 @@ export type Result<T> = {
 };
 
 /**
- * @ignore
+ * Construct a successful {@link Result}.
+ *
+ * ### Example
+ *
+ * ```javascript
+ * import { Ok } from 'effection';
+ *
+ * let result = Ok("hello");
+ * // { ok: true, value: "hello" }
+ * ```
+ *
+ * @since 4.1
  */
 export function Ok(): Result<void>;
 export function Ok<T>(value: T): Result<T>;
@@ -22,9 +42,34 @@ export function Ok<T>(value?: T): Result<T | undefined> {
 }
 
 /**
- * @ignore
+ * Construct a failed {@link Result}.
+ *
+ * ### Example
+ *
+ * ```javascript
+ * import { Err } from 'effection';
+ *
+ * let result = Err(new Error("oh no"));
+ * // { ok: false, error: Error("oh no") }
+ * ```
+ *
+ * @since 4.1
  */
-export const Err = <T>(error: Error): Result<T> => ({ ok: false, error });
+export function Err<T>(cause: unknown): Result<T> {
+  return {
+    ok: false,
+    error: cause instanceof Error
+      ? cause
+      : new ThrownValueError(String(cause), { cause }),
+  };
+}
+
+class ThrownValueError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ThrownValueError";
+  }
+}
 
 /**
  * @ignore

lib/scope-internal.ts

@@ -79,7 +79,7 @@ export function createScopeInternal(
           destructors.delete(destructor);
           yield* destructor();
         } catch (error) {
-          outcome = Err(error as Error);
+          outcome = Err(error);
         }
       }
     } finally {

test/result.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "./suite.ts";
+
+import { Err, Ok } from "../mod.ts";
+
+describe("Result", () => {
+  it("constructs successful results with Ok()", () => {
+    expect(Ok("hello")).toEqual({ ok: true, value: "hello" });
+  });
+
+  it("preserves Error instances passed to Err()", () => {
+    let error = new Error("oh no");
+
+    expect(Err(error)).toEqual({ ok: false, error });
+  });
+
+  it("wraps non-Error causes passed to Err()", () => {
+    let result = Err("oh no");
+
+    if (result.ok) {
+      throw new Error("expected Err() to produce a failed result");
+    }
+
+    expect(result.error).toBeInstanceOf(Error);
+    expect(result.error.name).toEqual("ThrownValueError");
+    expect(result.error.message).toEqual("oh no");
+    expect(result.error.cause).toEqual("oh no");
+  });
+});

test/until.test.ts

@@ -9,13 +9,15 @@ describe("until", () => {
       expect(yield* until(Promise.resolve(42))).toEqual(42);
     });
   });
-  it("throws on error", async () => {
-    expect.assertions(1);
+  it("wraps non-Error promise rejections", async () => {
+    expect.assertions(3);
     await run(function* () {
       try {
         yield* until(Promise.reject("error"));
       } catch (error) {
-        expect(error).toBe("error");
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe("error");
+        expect((error as Error).cause).toBe("error");
       }
     });
   });