feat(3.0.0-rc.5): implement tagged error type in err.ts

This commit primarily implements the Err type in err.ts. It is intended
to standardize error types such that errors from different computations
can be type unioned instead of deconstructed into application errors.
The secondary tag allows for some intelligent mapping at the end of the
pipeline, ideally useful for perhaps turning different tagged errors
into http status codes, etc. Originally I had implemented Combinable for
Err as a Free combinable, but I found that this would complicate the
structure of errors. Instead I am opting to allow the user to either
wrap the Err type in their own structure or to embed errors in the typed
context field. If I find that this was the wrong direction I hope to fix
it before the 3.0.0 release.

Author: baetheus

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@baetheus/fun",
-  "version": "3.0.0-rc.4",
+  "version": "3.0.0-rc.5",
   "exports": {
     "./applicable": "./applicable.ts",
     "./array": "./array.ts",
@@ -17,6 +17,7 @@
     "./decoder": "./decoder.ts",
     "./effect": "./effect.ts",
     "./either": "./either.ts",
+    "./err": "./err.ts",
     "./failable": "./failable.ts",
     "./filterable": "./filterable.ts",
     "./flatmappable": "./flatmappable.ts",

err.ts

@@ -0,0 +1,104 @@
+/**
+ * This file contains the Err algebraic data type and related utilities for
+ * creating and matching typed errors with optional context.
+ *
+ * @module Err
+ * @since 3.0.0-rc.5
+ */
+
+/**
+ * The Err type represents a typed error with a name, message, and optional context.
+ *
+ * @example
+ * ```ts
+ * import { err } from "./err.ts";
+ *
+ * const ValidationError = err("ValidationError");
+ * const error = ValidationError("Invalid input", { field: "email" });
+ *
+ * // error is of type Err<"ValidationError", { field: string }>
+ * console.log(error.name); // "ValidationError"
+ * console.log(error.message); // "Invalid input"
+ * console.log(error.context); // { field: "email" }
+ * ```
+ *
+ * @since 3.0.0-rc.5
+ */
+export type Err<T extends string, A> = {
+  readonly tag: "Error";
+  readonly name: T;
+  readonly message: string;
+  readonly context?: A;
+};
+
+/**
+ * A type alias for any Err type, useful for type constraints.
+ *
+ * @example
+ * ```ts
+ * import type { AnyErr } from "./err.ts";
+ *
+ * function handleError(error: AnyErr) {
+ *   console.log(error.name, error.message);
+ * }
+ * ```
+ *
+ * @since 3.0.0-rc.5
+ */
+// deno-lint-ignore no-explicit-any
+export type AnyErr = Err<string, any>;
+
+/**
+ * Create a constructor function for a specific error type.
+ *
+ * @example
+ * ```ts
+ * import { err } from "./err.ts";
+ *
+ * const NotFoundError = err("NotFoundError");
+ * const error = NotFoundError("Resource not found", { id: 123 });
+ *
+ * // error.name === "NotFoundError"
+ * // error.message === "Resource not found"
+ * // error.context === { id: 123 }
+ * ```
+ *
+ * @since 3.0.0-rc.5
+ */
+export function err<T extends string>(
+  name: T,
+): <A>(message: string, context?: A) => Err<T, A> {
+  return (message, context) => ({
+    tag: "Error",
+    name,
+    message,
+    context,
+  });
+}
+
+// deno-lint-ignore no-explicit-any
+type ExtractTags<T> = T extends Err<infer Tag, any> ? Tag : never;
+
+type MatchTag<Tag, Errors> = Tag extends string
+  ? Errors extends Err<Tag, infer A> ? Err<Tag, A> : never
+  : never;
+
+type MapFunc<T, B> = T extends Err<string, infer A>
+  ? (message: string, context: A) => B
+  : never;
+
+type ToRecord<T, B> = { [K in ExtractTags<T>]: MapFunc<MatchTag<K, T>, B> };
+
+/**
+ * Pattern match on an error value, dispatching to the appropriate handler
+ * based on the error's name.
+ *
+ * @since 3.0.0-rc.5
+ */
+export function match<T extends AnyErr, B>(
+  fns: ToRecord<T, B>,
+): (ta: T) => B {
+  return (ta) => (fns[ta.name as keyof ToRecord<T, B>])(ta.message, ta.context);
+}
+
+

examples/tagged_error.ts

@@ -1,3 +1,7 @@
+/**
+ * A talkback is the method for backpressure in our interpretation of the
+ * callbag specification. Specifically, we
+ */
 export type Talkback = (count: number) => void;
 
 export type Talk<A> = {
@@ -23,8 +27,6 @@ export type TypeOf<S> = S extends Stream<infer A, infer _> ? A : never;
 
 export type EnvOf<S> = S extends Stream<infer _, infer E> ? E : never;
 
-export const Disposed = Symbol("fun/stream/disposed");
-
 export function disposable(dispose: (reason?: unknown) => void): Disposable {
   return { [Symbol.dispose]: dispose };
 }
@@ -33,26 +35,14 @@ export function disposable(dispose: (reason?: unknown) => void): Disposable {
  * @todo: Consider how "safe" a sink needs to work.
  */
 export function sink<A>(snk: Sink<A>): Sink<A> {
-  return snk;
-  // return function safeSink(tlkbk) {
-  //   let open = true;
-  //   const talk = snk(tlkbk);
-  //   return {
-  //     event: (value) => {
-  //       if (open) {
-  //         return talk.event(value);
-  //       }
-  //       throw new Error("Talk event called after close.");
-  //     },
-  //     end: (reason) => {
-  //       if (open) {
-  //         open = false;
-  //         return talk.end(reason);
-  //       }
-  //       throw new Error("Talk end called after close.");
-  //     },
-  //   };
-  // };
+  return function safeSink(tlkbk) {
+    let open = true;
+    const talk = snk(tlkbk);
+    return {
+      event: (value) => open && talk.event(value),
+      end: (reason) => open && !(open = false) && talk.end(reason),
+    };
+  };
 }
 
 export function stream<A, R = unknown>(strm: Stream<A, R>): Stream<A, R> {
@@ -245,17 +235,20 @@ export function loop<A, B, S>(
 ): <E>(ua: Stream<A, E>) => Stream<B, E> {
   return (ua) => (snk, env) => {
     let state = seed;
-    return ua((tlkbk) => {
-      const talk = snk(tlkbk);
-      return {
-        event: (a) => {
-          const [next, b] = stepper(state, a);
-          state = next;
-          talk.event(b);
-        },
-        end: talk.end,
-      };
-    }, env);
+    return ua(
+      sink((tlkbk) => {
+        const talk = snk(tlkbk);
+        return {
+          event: (a) => {
+            const [next, b] = stepper(state, a);
+            state = next;
+            talk.event(b);
+          },
+          end: talk.end,
+        };
+      }),
+      env,
+    );
   };
 }
 

ideas/callbag.ts

@@ -0,0 +1,20 @@
+/**
+ * I think it's time to extend Decoder to be a full codec. The basic idea is
+ * that a Codec can decode from I to A and encode from A to O. Most of the time
+ * I will be unknown and O will be the same as A. But there is room for cases
+ * such as Option<A> encoding to and decoding from A or null or undefined. This
+ * will allow for cleaner mapping to and from internal representations. In
+ * tandem with this I would like to update Schemable to allow for some of the
+ * more useful filters on strings, numbers, record domain as well as range, and
+ * anything else that might be useful in general.
+ */
+import type * as Either from "../either.ts";
+
+import * as Err from "../err.ts";
+
+export const leaf = Err.err("DecodeErrorLeaf");
+
+export type Codec<I, A, O> = {
+  decode: (input: I) => Either.Either<Err.AnyErr, A>;
+  encode: (value: A) => O;
+};