@ambarltd/core 0.1.17

package/dist/maybe.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A type which represents the existence or absence of a value in a
+ * robust and unambiguous manner.
+ *
+ * Values can be extracted using `instanceof` tests.
+ *
+ * ```ts
+ * switch (true) {
+ *   case x instanceof Just:
+ *     // use x.value here
+ *     break;
+ *   case x instanceof Nothing:
+ *     break;
+ *   default:
+ *     x satisfies never;
+ * }
+ * ```
+ */
+type Maybe<T> = Just<T> | Nothing<T>;
+type Nullable<T> = T | null;
+/** Infer the type from a Maybe definition. */
+type Infer<A extends Maybe<unknown>> = A extends Maybe<infer B> ? B : never;
+export interface IMaybe<T> {
+    isJust(): boolean;
+    isNothing(): boolean;
+    map<W>(f: (t: T) => W): Maybe<W>;
+    withDefault(def: T): T;
+    expect(msg: string): T;
+    maybe<W>(def: W, f: (t: T) => W): W;
+    unwrap<W>(f: () => W, g: (t: T) => W): W;
+    chain<W>(f: (t: T) => Maybe<W>): Maybe<W>;
+    alt(other: Maybe<T>): Maybe<T>;
+    asNullable(): Nullable<T>;
+}
+/** Wrap a present value. Use at system boundaries or to lift a value into a `Maybe<T>`. */
+declare class Just<T> implements IMaybe<T> {
+    static new<W>(v: W): Just<W>;
+    readonly value: T;
+    constructor(v: T);
+    toString(): string;
+    /** Returns true if this is a `Just`. Prefer `instanceof Just` — booleans don't narrow the type. */
+    isJust(): boolean;
+    /** Returns true if this is a `Nothing`. Prefer `instanceof Nothing` — booleans don't narrow the type. */
+    isNothing(): boolean;
+    /** Transform the contained value if present; `Nothing` passes through unchanged. */
+    map<W>(f: (t: T) => W): Maybe<W>;
+    /** Unwrap the value, returning `def` if this is a `Nothing`. */
+    withDefault(_: T): T;
+    /**
+     * Unwrap the value or throw `new Error(msg)`. Only use for catastrophic
+     * programmer bugs — use `withDefault` or `maybe` for recoverable absence.
+     */
+    expect(_: string): T;
+    /** Fold into a `W`: return `def` for `Nothing`, else apply `f` to the value. */
+    maybe<W>(_: W, f: (t: T) => W): W;
+    /** Exhaustive two-branch fold: `f()` on `Nothing`, `g(value)` on `Just`. */
+    unwrap<W>(_: () => W, g: (t: T) => W): W;
+    /** Monadic bind. Use when `f` returns `Maybe<W>` — avoids `Maybe<Maybe<W>>`. */
+    chain<W>(f: (t: T) => Maybe<W>): Maybe<W>;
+    /** Fallback to `other` if this is a `Nothing`. Chainable: `primary.alt(secondary).alt(fallback)`. */
+    alt(_: Maybe<T>): Maybe<T>;
+    /** Convert to `T | null` at a system boundary. */
+    asNullable(): T;
+}
+/** Represent absence. Use instead of returning `null`/`undefined` from domain code. */
+declare class Nothing<T> implements IMaybe<T> {
+    static new<T>(): Nothing<T>;
+    constructor();
+    toString(): string;
+    /** Returns true if this is a `Just`. Prefer `instanceof Just` — booleans don't narrow the type. */
+    isJust(): boolean;
+    /** Returns true if this is a `Nothing`. Prefer `instanceof Nothing` — booleans don't narrow the type. */
+    isNothing(): boolean;
+    /** Transform the contained value if present; `Nothing` passes through unchanged. */
+    map<W>(_: (t: T) => W): Maybe<W>;
+    /** Unwrap the value, returning `def` if this is a `Nothing`. */
+    withDefault(d: T): T;
+    /**
+     * Unwrap the value or throw `new Error(msg)`. Only use for catastrophic
+     * programmer bugs — use `withDefault` or `maybe` for recoverable absence.
+     */
+    expect(msg: string): T;
+    /** Fold into a `W`: return `def` for `Nothing`, else apply `f` to the value. */
+    maybe<W>(def: W, _: (t: T) => W): W;
+    /** Exhaustive two-branch fold: `f()` on `Nothing`, `g(value)` on `Just`. */
+    unwrap<W>(f: () => W, _: (t: T) => W): W;
+    /** Monadic bind. Use when `f` returns `Maybe<W>` — avoids `Maybe<Maybe<W>>`. */
+    chain<W>(_: (t: T) => Maybe<W>): Maybe<W>;
+    /** Fallback to `other` if this is a `Nothing`. Chainable: `primary.alt(secondary).alt(fallback)`. */
+    alt(other: Maybe<T>): Maybe<T>;
+    /** Convert to `T | null` at a system boundary. */
+    asNullable(): Nullable<T>;
+}
+/** Boundary helper: `undefined` becomes `Nothing`, any other value becomes `Just`. Don't mix with `fromNullable`. */
+declare function fromOptional<T>(v: undefined | T): Maybe<T>;
+/** Boundary helper: `null` becomes `Nothing`, any other value becomes `Just`. Don't mix with `fromOptional`. */
+declare function fromNullable<T>(v: NonNullable<T> | null): Maybe<T>;
+/** Remove Nothings from an array. */
+declare function catMaybes<T>(xs: Array<Maybe<T>>): Array<T>;
+/** Map and filter using maybes. */
+declare function mapMaybe<T, W>(xs: Array<T>, f: (v: T) => Maybe<W>): Array<W>;
+declare var CallableJust: typeof Just & typeof Just.new;
+declare var CallableNothing: typeof Nothing & typeof Nothing.new;
+export { type Maybe, type Nullable, type Infer, CallableJust as Just, CallableNothing as Nothing, fromOptional, fromNullable, catMaybes, mapMaybe, };

package/dist/maybe.js

@@ -0,0 +1,106 @@
+import Callable from "./callable";
+/** Wrap a present value. Use at system boundaries or to lift a value into a `Maybe<T>`. */
+// prettier-ignore
+class Just {
+    static new(v) { return new Just(v); }
+    value;
+    constructor(v) { this.value = v; }
+    toString() {
+        return `Just(${this.value})`;
+    }
+    /** Returns true if this is a `Just`. Prefer `instanceof Just` — booleans don't narrow the type. */
+    isJust() { return true; }
+    /** Returns true if this is a `Nothing`. Prefer `instanceof Nothing` — booleans don't narrow the type. */
+    isNothing() { return false; }
+    /** Transform the contained value if present; `Nothing` passes through unchanged. */
+    map(f) { return new Just(f(this.value)); }
+    /** Unwrap the value, returning `def` if this is a `Nothing`. */
+    withDefault(_) { return this.value; }
+    /**
+     * Unwrap the value or throw `new Error(msg)`. Only use for catastrophic
+     * programmer bugs — use `withDefault` or `maybe` for recoverable absence.
+     */
+    expect(_) { return this.value; }
+    /** Fold into a `W`: return `def` for `Nothing`, else apply `f` to the value. */
+    maybe(_, f) { return f(this.value); }
+    /** Exhaustive two-branch fold: `f()` on `Nothing`, `g(value)` on `Just`. */
+    unwrap(_, g) { return g(this.value); }
+    /** Monadic bind. Use when `f` returns `Maybe<W>` — avoids `Maybe<Maybe<W>>`. */
+    chain(f) { return f(this.value); }
+    /** Fallback to `other` if this is a `Nothing`. Chainable: `primary.alt(secondary).alt(fallback)`. */
+    alt(_) { return this; }
+    /** Convert to `T | null` at a system boundary. */
+    asNullable() { return this.value; }
+}
+/** Represent absence. Use instead of returning `null`/`undefined` from domain code. */
+// prettier-ignore
+class Nothing {
+    static new() { return new Nothing(); }
+    constructor() { }
+    toString() {
+        return "Nothing()";
+    }
+    /** Returns true if this is a `Just`. Prefer `instanceof Just` — booleans don't narrow the type. */
+    isJust() { return false; }
+    /** Returns true if this is a `Nothing`. Prefer `instanceof Nothing` — booleans don't narrow the type. */
+    isNothing() { return true; }
+    /** Transform the contained value if present; `Nothing` passes through unchanged. */
+    map(_) { return new Nothing(); }
+    /** Unwrap the value, returning `def` if this is a `Nothing`. */
+    withDefault(d) { return d; }
+    /**
+     * Unwrap the value or throw `new Error(msg)`. Only use for catastrophic
+     * programmer bugs — use `withDefault` or `maybe` for recoverable absence.
+     */
+    expect(msg) { throw new Error(msg); }
+    /** Fold into a `W`: return `def` for `Nothing`, else apply `f` to the value. */
+    maybe(def, _) { return def; }
+    /** Exhaustive two-branch fold: `f()` on `Nothing`, `g(value)` on `Just`. */
+    unwrap(f, _) { return f(); }
+    /** Monadic bind. Use when `f` returns `Maybe<W>` — avoids `Maybe<Maybe<W>>`. */
+    chain(_) {
+        return new Nothing();
+    }
+    /** Fallback to `other` if this is a `Nothing`. Chainable: `primary.alt(secondary).alt(fallback)`. */
+    alt(other) { return other; }
+    /** Convert to `T | null` at a system boundary. */
+    asNullable() { return null; }
+}
+/** Boundary helper: `undefined` becomes `Nothing`, any other value becomes `Just`. Don't mix with `fromNullable`. */
+function fromOptional(v) {
+    if (typeof v === "undefined") {
+        return new Nothing();
+    }
+    else {
+        return new Just(v);
+    }
+}
+/** Boundary helper: `null` becomes `Nothing`, any other value becomes `Just`. Don't mix with `fromOptional`. */
+function fromNullable(v) {
+    if (v === null) {
+        return new Nothing();
+    }
+    else {
+        return new Just(v);
+    }
+}
+/** Remove Nothings from an array. */
+function catMaybes(xs) {
+    const r = [];
+    for (const x of xs) {
+        x.map(v => r.push(v));
+    }
+    return r;
+}
+/** Map and filter using maybes. */
+function mapMaybe(xs, f) {
+    const r = [];
+    for (const x of xs) {
+        f(x).map(v => r.push(v));
+    }
+    return r;
+}
+/* eslint-disable no-var */
+var CallableJust = Callable(Just);
+var CallableNothing = Callable(Nothing);
+export { CallableJust as Just, CallableNothing as Nothing, fromOptional, fromNullable, catMaybes, mapMaybe, };

package/dist/remote-data.d.ts

@@ -0,0 +1,117 @@
+import { Nullable, Maybe } from "./maybe";
+/**
+ * Represents the state of data that is fetched from a remote source.
+ *
+ * A value is either not yet requested, loading, failed with an error, or
+ * successfully loaded (`Ready`).
+ */
+type RemoteData<E, T> = NotAsked<E, T> | Loading<E, T> | Failed<E, T> | Ready<E, T>;
+interface IRemoteData<E, T> {
+    map<W>(f: (t: T) => W): RemoteData<E, W>;
+    chain<W>(f: (t: T) => RemoteData<E, W>): RemoteData<E, W>;
+    unwrapFailure<W>(def: W, f: (e: E) => W): W;
+    toMaybe(): Maybe<T>;
+    readonly isLoading: boolean;
+    readonly isReady: boolean;
+    readonly isFailed: boolean;
+}
+/**
+ * Initial state: the request hasn't been made yet. For "asked but empty",
+ * use `Ready([])` instead — `NotAsked` is not a generic "no data" state.
+ */
+declare class NotAsked<E, T> implements IRemoteData<E, T> {
+    private readonly _tag;
+    static new<E, T>(): NotAsked<E, T>;
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map<W>(_: (t: T) => W): RemoteData<E, W>;
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain<W>(_: (t: T) => RemoteData<E, W>): NotAsked<E, W>;
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure<W>(def: W, _: (e: E) => W): W;
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe(): Maybe<T>;
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    readonly isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    readonly isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    readonly isFailed = false;
+}
+type Bytes = number;
+type LoadingDetails = {
+    uploaded: Bytes;
+    uploadSize: Nullable<Bytes>;
+    downloaded: Bytes;
+    downloadSize: Nullable<Bytes>;
+};
+/** In-flight state. Optionally carries upload/download progress via `details`. */
+declare class Loading<E, T> implements IRemoteData<E, T> {
+    private readonly _tag;
+    readonly uploaded: Bytes;
+    readonly uploadSize: Nullable<Bytes>;
+    readonly downloaded: Bytes;
+    readonly downloadSize: Nullable<Bytes>;
+    constructor(details?: Nullable<LoadingDetails>);
+    static new<E, T>(details?: Nullable<LoadingDetails>): Loading<E, T>;
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map<W>(_: (t: T) => W): RemoteData<E, W>;
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain<W>(_: (t: T) => RemoteData<E, W>): Loading<E, W>;
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure<W>(def: W, _: (e: E) => W): W;
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe(): Maybe<T>;
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    readonly isLoading = true;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    readonly isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    readonly isFailed = false;
+}
+/** Terminal failure state carrying the error payload. */
+declare class Failed<E, T> implements IRemoteData<E, T> {
+    private readonly _tag;
+    readonly error: E;
+    static new<E, T>(e: E): Failed<E, T>;
+    constructor(e: E);
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map<W>(_: (t: T) => W): RemoteData<E, W>;
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain<W>(_: (t: T) => RemoteData<E, W>): Failed<E, W>;
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure<W>(_: W, f: (e: E) => W): W;
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe(): Maybe<T>;
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    readonly isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    readonly isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    readonly isFailed = true;
+}
+/** Terminal success state carrying the loaded value. */
+declare class Ready<E, T> implements IRemoteData<E, T> {
+    private readonly _tag;
+    static new<E, T>(v: T): Ready<E, T>;
+    readonly value: T;
+    constructor(v: T);
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map<W>(f: (t: T) => W): RemoteData<E, W>;
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain<W>(f: (t: T) => RemoteData<E, W>): RemoteData<E, W>;
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure<W>(def: W, _: (e: E) => W): W;
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe(): Maybe<T>;
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    readonly isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    readonly isReady = true;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    readonly isFailed = false;
+}
+declare var CallableNotAsked: typeof NotAsked & typeof NotAsked.new;
+declare var CallableLoading: typeof Loading & typeof Loading.new;
+declare var CallableFailure: typeof Failed & typeof Failed.new;
+declare var CallableSuccess: typeof Ready & typeof Ready.new;
+export { type RemoteData, CallableSuccess as Ready, CallableFailure as Failed, CallableNotAsked as NotAsked, CallableLoading as Loading, };

package/dist/remote-data.js

@@ -0,0 +1,148 @@
+import { Nothing, Just } from "./maybe";
+import Callable from "./callable";
+/**
+ * Initial state: the request hasn't been made yet. For "asked but empty",
+ * use `Ready([])` instead — `NotAsked` is not a generic "no data" state.
+ */
+class NotAsked {
+    // @ts-expect-error Unused _tag's existence prevents structural comparison
+    _tag = null;
+    static new() {
+        return new NotAsked();
+    }
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map(_) {
+        return new NotAsked();
+    }
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain(_) {
+        return new NotAsked();
+    }
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure(def, _) {
+        return def;
+    }
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe() {
+        return Nothing();
+    }
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    isFailed = false;
+}
+/** In-flight state. Optionally carries upload/download progress via `details`. */
+class Loading {
+    // @ts-expect-errorUnused_tag's existence prevents structural comparison
+    _tag = null;
+    uploaded;
+    uploadSize;
+    downloaded;
+    downloadSize;
+    constructor(details = null) {
+        this.uploaded = details?.uploaded ?? 0;
+        this.uploadSize = details?.uploadSize ?? null;
+        this.downloaded = details?.downloaded ?? 0;
+        this.downloadSize = details?.downloadSize ?? null;
+    }
+    static new(details = null) {
+        return new Loading(details);
+    }
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map(_) {
+        return new Loading();
+    }
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain(_) {
+        return new Loading();
+    }
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure(def, _) {
+        return def;
+    }
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe() {
+        return Nothing();
+    }
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    isLoading = true;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    isFailed = false;
+}
+/** Terminal failure state carrying the error payload. */
+class Failed {
+    // @ts-expect-error Unused _tag's existence prevents structural comparison
+    _tag = null;
+    error;
+    static new(e) {
+        return new Failed(e);
+    }
+    constructor(e) {
+        this.error = e;
+    }
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map(_) {
+        return new Failed(this.error);
+    }
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain(_) {
+        return new Failed(this.error);
+    }
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure(_, f) {
+        return f(this.error);
+    }
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe() {
+        return Nothing();
+    }
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    isReady = false;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    isFailed = true;
+}
+/** Terminal success state carrying the loaded value. */
+class Ready {
+    // @ts-expect-error Unused _tag's existence prevents structural comparison
+    _tag = null;
+    static new(v) {
+        return new Ready(v);
+    }
+    value;
+    constructor(v) {
+        this.value = v;
+    }
+    /** Transform only if `Ready`; `Loading`/`Failed`/`NotAsked` pass through unchanged. */
+    map(f) {
+        return new Ready(f(this.value));
+    }
+    /** Chain a `RemoteData`-returning fn without double-wrapping. */
+    chain(f) {
+        return f(this.value);
+    }
+    /** Return `f(error)` on `Failed`, otherwise return `def`. */
+    unwrapFailure(def, _) {
+        return def;
+    }
+    /** Collapse to `Just(value)` on `Ready`, otherwise `Nothing`. */
+    toMaybe() {
+        return Just(this.value);
+    }
+    /** `true` only in `Loading`. Prefer `instanceof Loading` + `satisfies never` for exhaustive narrowing. */
+    isLoading = false;
+    /** `true` only in `Ready`. Prefer `instanceof Ready` + `satisfies never` for exhaustive narrowing. */
+    isReady = true;
+    /** `true` only in `Failed`. Prefer `instanceof Failed` + `satisfies never` for exhaustive narrowing. */
+    isFailed = false;
+}
+var CallableNotAsked = Callable(NotAsked);
+var CallableLoading = Callable(Loading);
+var CallableFailure = Callable(Failed);
+var CallableSuccess = Callable(Ready);
+export { CallableSuccess as Ready, CallableFailure as Failed, CallableNotAsked as NotAsked, CallableLoading as Loading, };

package/dist/result.d.ts

@@ -0,0 +1,75 @@
+import { List } from "./list";
+/**
+ * Represents the result of a computation that may fail.
+ *
+ * Either `Success<E, T>` wrapping a successful value, or `Failure<E, T>`
+ * wrapping an error value.
+ */
+type Result<E, T> = Success<E, T> | Failure<E, T>;
+export interface IResult<E, T> {
+    isSuccess(): boolean;
+    isFailure(): boolean;
+    map<W>(f: (t: T) => W): Result<E, W>;
+    mapFailure<W>(f: (t: E) => W): Result<W, T>;
+    either<W>(f: (e: E) => W, g: (s: T) => W): W;
+    chain<W>(f: (t: T) => Result<E, W>): Result<E, W>;
+    unwrap(f: (e: E) => string): T;
+    withDefault(f: (e: E) => T): T;
+}
+/** Wrap a computed value. Use to return from a fallible operation that succeeded. */
+declare class Success<E, T> implements IResult<E, T> {
+    readonly value: T;
+    static new<E, T>(v: T): Success<E, T>;
+    constructor(v: T);
+    /** Returns true if this is a `Success`. Prefer `instanceof Success` for narrowing. */
+    isSuccess(): boolean;
+    /** Returns true if this is a `Failure`. Prefer `instanceof Failure` for narrowing. */
+    isFailure(): boolean;
+    /** Transform the success value; `Failure` passes through unchanged. */
+    map<W>(f: (t: T) => W): Result<E, W>;
+    /** Transform the error value; `Success` passes through unchanged. */
+    mapFailure<W>(_: (t: E) => W): Result<W, T>;
+    /** Exhaustive fold: `f(error)` on `Failure`, `g(value)` on `Success`. */
+    either<W>(_: (e: E) => W, g: (s: T) => W): W;
+    /** Monadic sequencing. Short-circuits on the first `Failure`. */
+    chain<W>(f: (t: T) => Result<E, W>): Result<E, W>;
+    /**
+     * Unwrap the value or throw an `Error` built from `f(error)`. Boundary-only —
+     * don't mix with try/catch; use `either` or `withDefault` in business logic.
+     */
+    unwrap(_: (e: E) => string): T;
+    /** Recover from `Failure` by mapping the error to a default value. */
+    withDefault(_: (e: E) => T): T;
+}
+/** Wrap an error value. Return from a fallible operation instead of throwing — reserve `throw` for catastrophic bugs. */
+declare class Failure<E, T> implements IResult<E, T> {
+    readonly error: E;
+    static new<E, T>(v: E): Failure<E, T>;
+    constructor(v: E);
+    /** Returns true if this is a `Success`. Prefer `instanceof Success` for narrowing. */
+    isSuccess(): boolean;
+    /** Returns true if this is a `Failure`. Prefer `instanceof Failure` for narrowing. */
+    isFailure(): boolean;
+    /** Transform the success value; `Failure` passes through unchanged. */
+    map<W>(_: (t: T) => W): Result<E, W>;
+    /** Transform the error value; `Success` passes through unchanged. */
+    mapFailure<W>(f: (t: E) => W): Result<W, T>;
+    /** Exhaustive fold: `f(error)` on `Failure`, `g(value)` on `Success`. */
+    either<W>(f: (e: E) => W, _: (s: T) => W): W;
+    /** Monadic sequencing. Short-circuits on the first `Failure`. */
+    chain<W>(_: (t: T) => Result<E, W>): Result<E, W>;
+    /**
+     * Unwrap the value or throw an `Error` built from `f(error)`. Boundary-only —
+     * don't mix with try/catch; use `either` or `withDefault` in business logic.
+     */
+    unwrap(f: (error: E) => string): T;
+    /** Recover from `Failure` by mapping the error to a default value. */
+    withDefault(f: (e: E) => T): T;
+}
+/** Traverse a `List<A>` with a fallible fn. Short-circuits on the first `Failure`. */
+declare function traverse<T, A, E>(xs: List<A>, f: (v: A) => Result<E, T>): Result<E, List<T>>;
+/** Array version of `traverse`. Short-circuits on the first `Failure`. */
+declare function traverse_<T, A, E>(xs: Array<A>, f: (v: A) => Result<E, T>): Result<E, Array<T>>;
+declare var CallableSuccess: typeof Success & typeof Success.new;
+declare var CallableFailure: typeof Failure & typeof Failure.new;
+export { type Result, CallableSuccess as Success, CallableFailure as Failure, traverse, traverse_ };

package/dist/result.js

@@ -0,0 +1,126 @@
+import { end, tailRecursive } from "./trampoline";
+import { List } from "./list";
+import Callable from "./callable";
+/** Wrap a computed value. Use to return from a fallible operation that succeeded. */
+class Success {
+    value;
+    static new(v) {
+        return new Success(v);
+    }
+    constructor(v) {
+        this.value = v;
+    }
+    /** Returns true if this is a `Success`. Prefer `instanceof Success` for narrowing. */
+    isSuccess() {
+        return true;
+    }
+    /** Returns true if this is a `Failure`. Prefer `instanceof Failure` for narrowing. */
+    isFailure() {
+        return false;
+    }
+    /** Transform the success value; `Failure` passes through unchanged. */
+    map(f) {
+        return new Success(f(this.value));
+    }
+    /** Transform the error value; `Success` passes through unchanged. */
+    mapFailure(_) {
+        return new Success(this.value);
+    }
+    /** Exhaustive fold: `f(error)` on `Failure`, `g(value)` on `Success`. */
+    either(_, g) {
+        return g(this.value);
+    }
+    /** Monadic sequencing. Short-circuits on the first `Failure`. */
+    chain(f) {
+        return f(this.value);
+    }
+    /**
+     * Unwrap the value or throw an `Error` built from `f(error)`. Boundary-only —
+     * don't mix with try/catch; use `either` or `withDefault` in business logic.
+     */
+    unwrap(_) {
+        return this.value;
+    }
+    /** Recover from `Failure` by mapping the error to a default value. */
+    withDefault(_) {
+        return this.value;
+    }
+}
+/** Wrap an error value. Return from a fallible operation instead of throwing — reserve `throw` for catastrophic bugs. */
+class Failure {
+    error;
+    static new(v) {
+        return new Failure(v);
+    }
+    constructor(v) {
+        this.error = v;
+    }
+    /** Returns true if this is a `Success`. Prefer `instanceof Success` for narrowing. */
+    isSuccess() {
+        return false;
+    }
+    /** Returns true if this is a `Failure`. Prefer `instanceof Failure` for narrowing. */
+    isFailure() {
+        return true;
+    }
+    /** Transform the success value; `Failure` passes through unchanged. */
+    map(_) {
+        return new Failure(this.error);
+    }
+    /** Transform the error value; `Success` passes through unchanged. */
+    mapFailure(f) {
+        return new Failure(f(this.error));
+    }
+    /** Exhaustive fold: `f(error)` on `Failure`, `g(value)` on `Success`. */
+    either(f, _) {
+        return f(this.error);
+    }
+    /** Monadic sequencing. Short-circuits on the first `Failure`. */
+    chain(_) {
+        return new Failure(this.error);
+    }
+    /**
+     * Unwrap the value or throw an `Error` built from `f(error)`. Boundary-only —
+     * don't mix with try/catch; use `either` or `withDefault` in business logic.
+     */
+    unwrap(f) {
+        throw new Error(f(this.error));
+    }
+    /** Recover from `Failure` by mapping the error to a default value. */
+    withDefault(f) {
+        return f(this.error);
+    }
+}
+/** Traverse a `List<A>` with a fallible fn. Short-circuits on the first `Failure`. */
+function traverse(xs, f) {
+    const go = tailRecursive((done, todo) => {
+        switch (true) {
+            case "head" in todo.value: {
+                const { head, tail } = todo.value;
+                const r = f(head);
+                switch (true) {
+                    case r instanceof Success: {
+                        const value = r.value;
+                        return go(List.cons(value, done), tail);
+                    }
+                    case r instanceof Failure:
+                        return end(new Failure(r.error));
+                    default:
+                        return r;
+                }
+            }
+            case "empty" in todo.value:
+                return end(new Success(done.reverse()));
+            default:
+                return todo.value;
+        }
+    });
+    return go(List.empty(), xs).run();
+}
+/** Array version of `traverse`. Short-circuits on the first `Failure`. */
+function traverse_(xs, f) {
+    return traverse(List.from(xs), f).map(r => r.toArray());
+}
+var CallableSuccess = Callable(Success);
+var CallableFailure = Callable(Failure);
+export { CallableSuccess as Success, CallableFailure as Failure, traverse, traverse_ };