@onrails/result 0.1.4 → 0.3.0

package/dist/index.d.ts

@@ -1,10 +1,204 @@
-export { R as ResultAsync, e as errAsync, f as fromPromise, a as fromSafePromise, o as okAsync, p as parallelTupleAsync, s as sequenceTupleAsync, t as tryAsync } from './async-DKISqIBc.js';
-export { InferErr, InferOk, asyncAfter, fromAsync, fromResult } from './interop.js';
+import { R as ResultAsync, I as InferErr, a as InferOk } from './async-SZ7BEl0g.js';
+import { R as Result, U as UnexpectedError, E as Err, O as Ok } from './types-BQ9vv0nD.js';
 export { flow } from './pipe.js';
-import { R as Result, E as Err, O as Ok } from './types-C2Dp1d5J.js';
-export { U as UnexpectedError } from './types-C2Dp1d5J.js';
 export { $, tryGen, yieldResult } from './try-gen.js';
 
+/**
+ * @onrails/result — THE lift module. Every "value → {@link ResultAsync}"
+ * entry point is defined exactly once, here: `okAsync`, `errAsync`,
+ * `fromPromise`, `fromSafePromise`, `fromResult`, `fromAsync`, `asyncAfter`,
+ * `tryAsync`.
+ */
+
+/**
+ * Lifts a value into an `Ok` async result.
+ *
+ * @example
+ * ```ts
+ * const r = okAsync(42);                  // ResultAsync<number, never>
+ * ```
+ */
+declare const okAsync: typeof ResultAsync.ok;
+/**
+ * Lifts a value into an `Err` async result.
+ *
+ * @example
+ * ```ts
+ * const r = errAsync({ kind: "not_found" as const });
+ * ```
+ */
+declare const errAsync: typeof ResultAsync.err;
+/**
+ * Wraps a `PromiseLike<T>` into a {@link ResultAsync}. Reject reasons go
+ * through `onReject` to become typed `Err`s; success becomes `Ok<T>`.
+ *
+ * @example
+ * ```ts
+ * const body = fromPromise(
+ *   fetch(url).then((r) => r.text()),
+ *   (e): NetworkError => ({ kind: "network", cause: String(e) }),
+ * );
+ * ```
+ */
+declare const fromPromise: typeof ResultAsync.fromPromise;
+/**
+ * Wraps a `PromiseLike<T>` that **never rejects** into {@link ResultAsync}.
+ * Skips the `onReject` mapper. Use only when the promise is provably safe.
+ */
+declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
+/**
+ * Lifts an already-settled sync {@link Result} into a {@link ResultAsync}, so
+ * it can be chained alongside async steps in a railway.
+ *
+ * @example
+ * ```ts
+ * const ra = fromResult(ok(1));            // ResultAsync<number, never>
+ * await fromResult(err(error)).resolve();  // Err(error)
+ * ```
+ */
+declare const fromResult: typeof ResultAsync.fromResult;
+/**
+ * Bind a sync {@link Result} into an async step without widening defects.
+ * Dual-form: data-first for one-shots, data-last (curried) for `pipe`/`flow`.
+ *
+ * @example
+ * ```ts
+ * asyncAfter(result, (u) => tryAsync(db.insert(u), toErr)); // data-first
+ * asyncAfter((u) => tryAsync(db.insert(u), toErr));         // data-last
+ * ```
+ */
+declare const asyncAfter: {
+    <T, U, E, F>(result: Result<T, E>, fn: (value: T) => ResultAsync<U, F>): ResultAsync<U, E | F>;
+    <T, U, F>(fn: (value: T) => ResultAsync<U, F>): <E>(result: Result<T, E>) => ResultAsync<U, E | F>;
+};
+type AnyResult = Result<unknown, unknown>;
+/**
+ * Lifts a `(...args) => Promise<Result<T, E>>` function (typical of interop or
+ * boundary code) into one returning `(...args) => ResultAsync<T, E>`. Expected
+ * `Err`s pass through; an unexpected promise rejection (a defect) is routed via
+ * `onDefect`, defaulting to {@link UnexpectedError} and widening the error union.
+ *
+ * @param fn - a function returning a promise that already yields a `Result`
+ * @param onDefect - maps an unexpected rejection to the `Err` channel
+ *
+ * @example
+ * ```ts
+ * const loadUser = fromAsync(
+ *   (id: string): Promise<Result<User, NotFound>> => api.getUser(id),
+ * );
+ * const ra = loadUser("u1");   // ResultAsync<User, NotFound | UnexpectedError>
+ * ```
+ */
+declare const fromAsync: <A extends readonly unknown[], R extends AnyResult>(fn: (...args: A) => Promise<R>, onDefect?: (error: unknown) => InferErr<R> | UnexpectedError) => ((...args: A) => ResultAsync<InferOk<R>, InferErr<R> | UnexpectedError>);
+/**
+ * Convenience wrapper over {@link fromPromise} with default `Error`
+ * normalization. Call without `onReject` to get `ResultAsync<T, Error>`,
+ * or pass a custom mapper for a typed error.
+ *
+ * @example
+ * ```ts
+ * // Default: rejection → Err(Error)
+ * const a = tryAsync(db.users.insert(row));
+ *
+ * // Custom: typed error
+ * const b = tryAsync(db.users.insert(row), (e): DbError => ({
+ *   kind: "db",
+ *   cause: e,
+ * }));
+ * ```
+ */
+declare function tryAsync<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
+declare function tryAsync<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
+
+/**
+ * @onrails/result — sync aggregation, one module, two axes:
+ *
+ *   short-circuit (first `Err` wins)      — {@link combine} / {@link combineTuple}
+ *   accumulate expected failures          — {@link validateAll} / {@link validateTuple}
+ *
+ * The accumulate pair collects every failure into a readonly array by
+ * default, or folds them with an explicit `combineErrors` when given one.
+ */
+
+/**
+ * Combines a homogeneous array of results into a single result holding an
+ * array of the `Ok` values, in input order. Short-circuits on the first `Err`
+ * (first failure wins). For heterogeneous tuples that preserve per-index
+ * types, use {@link combineTuple}.
+ *
+ * @example
+ * ```ts
+ * combine([ok(1), ok(2)]);        // Ok([1, 2])
+ * combine([ok(1), err("e")]);     // Err("e")
+ * ```
+ */
+declare const combine: <T, E>(results: readonly Result<T, E>[]) => Result<T[], E>;
+type CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<{
+    [K in keyof R]: InferOk<R[K]>;
+}, {
+    [K in keyof R]: InferErr<R[K]>;
+}[number]>;
+/**
+ * Heterogeneous tuple combine — like {@link combine} but preserves each
+ * branch's `Ok` type by position, so the result destructures type-safely.
+ * Short-circuits on the first `Err` in input order (neverthrow-style).
+ *
+ * @example
+ * ```ts
+ * const r = combineTuple([ok(1), ok("x")] as const);
+ * // Result<readonly [number, string], never>
+ * if (isOk(r)) {
+ *   const [n, s] = r.value;   // typed per position
+ * }
+ * ```
+ */
+declare const combineTuple: <const R extends readonly Result<unknown, unknown>[]>(results: R) => CombineTuple<R>;
+/**
+ * Accumulate independent validation failures. Returns `Ok<T[]>` only when
+ * every input is `Ok`. Without a combiner, failures are collected into a
+ * readonly array; with `combineErrors` they are folded into a single `E`.
+ *
+ * Unlike {@link combine}, this does **not** short-circuit on first failure —
+ * use for independent checks where you want to report all problems at once.
+ *
+ * @example
+ * ```ts
+ * const checks: Result<string, string[]>[] = [ok("Ada"), err(["age required"])];
+ *
+ * validateAll(checks);
+ * // Result<string[], readonly string[][]>
+ *
+ * validateAll(checks, (left, right) => [...left, ...right]);
+ * // Result<string[], string[]>
+ * ```
+ */
+declare function validateAll<T, E>(results: readonly Result<T, E>[]): Result<T[], readonly E[]>;
+declare function validateAll<T, E>(results: readonly Result<T, E>[], combineErrors: (left: E, right: E) => E): Result<T[], E>;
+/**
+ * Tuple-preserving variant of {@link validateAll}. Heterogeneous input tuple
+ * → preserved `Ok` tuple shape. Without a combiner, the error union is
+ * collected into a readonly array; with `combineErrors`, all inputs must
+ * share the error type `E` and failures fold into a single `E`.
+ *
+ * @example
+ * ```ts
+ * const name: Result<string, string[]> = ok("Ada");
+ * const age: Result<number, string[]> = ok(36);
+ *
+ * validateTuple([name, age] as const);
+ * // Result<readonly [string, number], readonly string[][]>
+ *
+ * validateTuple([name, age] as const, (l, r) => [...l, ...r]);
+ * // Result<readonly [string, number], string[]>
+ * ```
+ */
+declare function validateTuple<const R extends readonly Result<unknown, unknown>[]>(results: R): Result<{
+    [K in keyof R]: InferOk<R[K]>;
+}, readonly InferErr<R[number]>[]>;
+declare function validateTuple<const R extends readonly Result<unknown, unknown>[], E = InferErr<R[number]>>(results: R & readonly Result<unknown, E>[], combineErrors: (left: E, right: E) => E): Result<{
+    [K in keyof R]: InferOk<R[K]>;
+}, E>;
+
 /**
  * Lifts a value into the success track.
  *
@@ -47,11 +241,6 @@ declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T, E>;
  * ```
  */
 declare const isErr: <T, E>(result: Result<T, E>) => result is Err<T, E>;
-/**
- * Fantasy Land `of` — alias of {@link ok}.
- * @deprecated Use {@link ok} instead.
- */
-declare const of: <T, E = never>(value: T) => Result<T, E>;
 /**
  * Transform the `Ok` value, passing `Err` through unchanged. Dual-form:
  * call data-first or curried (for use with {@link pipe}).
@@ -62,8 +251,10 @@ declare const of: <T, E = never>(value: T) => Result<T, E>;
  * pipe(ok("x"), map((s) => s.length));// Ok 1 — curried
  * ```
  */
-declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
-declare function map<T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Result<U, E>;
+declare const map: {
+    <T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+    <T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Result<U, E>;
+};
 /**
  * Transform the `Err` value, passing `Ok` through unchanged. Useful for
  * unifying heterogeneous failure types into one app-level union.
@@ -77,8 +268,10 @@ declare function map<T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Re
  * );
  * ```
  */
-declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
-declare function mapErr<E, F>(fn: (error: E) => F): <T>(result: Result<T, E>) => Result<T, F>;
+declare const mapErr: {
+    <T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+    <E, F>(fn: (error: E) => F): <T>(result: Result<T, E>) => Result<T, F>;
+};
 /**
  * Transform both tracks at once — `Ok` via `onOk`, `Err` via `onErr`.
  * Equivalent to `mapErr(onErr)(map(onOk)(result))` but in one pass.
@@ -88,8 +281,10 @@ declare function mapErr<E, F>(fn: (error: E) => F): <T>(result: Result<T, E>) =>
  * bimap(parsed, (cfg) => cfg.name, (e) => ({ kind: "input", cause: e }));
  * ```
  */
-declare function bimap<T, U, E, F>(result: Result<T, E>, onOk: (value: T) => U, onErr: (error: E) => F): Result<U, F>;
-declare function bimap<T, U, E, F>(onOk: (value: T) => U, onErr: (error: E) => F): (result: Result<T, E>) => Result<U, F>;
+declare const bimap: {
+    <T, U, E, F>(result: Result<T, E>, onOk: (value: T) => U, onErr: (error: E) => F): Result<U, F>;
+    <T, U, E, F>(onOk: (value: T) => U, onErr: (error: E) => F): (result: Result<T, E>) => Result<U, F>;
+};
 /**
  * Canonical bind (Fantasy Land `chain`). Chains a Result-returning step,
  * widening the error union to `E | F`. Short-circuits on `Err`.
@@ -102,8 +297,10 @@ declare function bimap<T, U, E, F>(onOk: (value: T) => U, onErr: (error: E) => F
  * // Result<Data, ParseError | { kind: "missing_id" }>
  * ```
  */
-declare function flatMap<T, U, E, F>(result: Result<T, E>, fn: (value: T) => Result<U, F>): Result<U, E | F>;
-declare function flatMap<T, U, F>(fn: (value: T) => Result<U, F>): <E>(result: Result<T, E>) => Result<U, E | F>;
+declare const flatMap: {
+    <T, U, E, F>(result: Result<T, E>, fn: (value: T) => Result<U, F>): Result<U, E | F>;
+    <T, U, F>(fn: (value: T) => Result<U, F>): <E>(result: Result<T, E>) => Result<U, E | F>;
+};
 /**
  * Error-track bind — runs `fn` only when the result is `Err`, allowing
  * a failed workflow to recover to `Ok` or remap the failure. Mirror of
@@ -116,8 +313,10 @@ declare function flatMap<T, U, F>(fn: (value: T) => Result<U, F>): <E>(result: R
  * );
  * ```
  */
-declare function recover<T, E, F>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
-declare function recover<T, E, F>(fn: (error: E) => Result<T, F>): (result: Result<T, E>) => Result<T, F>;
+declare const recover: {
+    <T, E, F>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+    <T, E, F>(fn: (error: E) => Result<T, F>): (result: Result<T, E>) => Result<T, F>;
+};
 /**
  * Observe the `Ok` value for side effects (logging, metrics) without
  * changing the carried value. Passes `Err` through untouched.
@@ -131,8 +330,10 @@ declare function recover<T, E, F>(fn: (error: E) => Result<T, F>): (result: Resu
  * );
  * ```
  */
-declare function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
-declare function tap<T>(fn: (value: T) => void): <E>(result: Result<T, E>) => Result<T, E>;
+declare const tap: {
+    <T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
+    <T>(fn: (value: T) => void): <E>(result: Result<T, E>) => Result<T, E>;
+};
 /**
  * Observe the `Err` value for side effects (logging, metrics) without
  * changing the carried error. Passes `Ok` through untouched.
@@ -145,38 +346,28 @@ declare function tap<T>(fn: (value: T) => void): <E>(result: Result<T, E>) => Re
  * );
  * ```
  */
-declare function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
-declare function tapErr<E>(fn: (error: E) => void): <T>(result: Result<T, E>) => Result<T, E>;
+declare const tapErr: {
+    <T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
+    <E>(fn: (error: E) => void): <T>(result: Result<T, E>) => Result<T, E>;
+};
 /**
  * Terminal collapse — fold both tracks into a single value. Dual-form:
  * 3-args data-first, 2-args curried for {@link pipe}. Returns whatever
  * the handlers return.
  *
- * For files that also import `match` from `ts-pattern`, the
- * collision-free alias {@link matchResult} is identical.
+ * For files that also import `match` from `ts-pattern`, use a namespace
+ * import (`import * as R from "@onrails/result"` → `R.match`) to dissolve
+ * the collision.
  *
  * @example
  * ```ts
  * const html = match(parsed, (cfg) => render(cfg), (e) => renderError(e));
  * ```
  */
-declare function match<T, E, U>(result: Result<T, E>, onOk: (value: T) => U, onErr: (error: E) => U): U;
-declare function match<T, E, U>(onOk: (value: T) => U, onErr: (error: E) => U): (result: Result<T, E>) => U;
-/**
- * Collision-free alias for files that also import `match` from ts-pattern.
- * @deprecated Namespace import carriers (e.g., `import * as R from "@onrails/result"`) and use canonical {@link match} instead.
- */
-declare const matchResult: typeof match;
-/**
- * Curried collapse with named slots — escape valve when positional `match`
- * order is unclear at the call site (e.g. when both handlers return the same
- * type and a transposed `match(r, onErr, onOk)` would silently compile).
- * @deprecated Use curried {@link match}(onOk, onErr)(result) instead.
- */
-declare const fold: <T, E, U>(handlers: {
-    readonly ok: (value: T) => U;
-    readonly err: (error: E) => U;
-}) => (result: Result<T, E>) => U;
+declare const match: {
+    <T, E, U>(result: Result<T, E>, onOk: (value: T) => U, onErr: (error: E) => U): U;
+    <T, E, U>(onOk: (value: T) => U, onErr: (error: E) => U): (result: Result<T, E>) => U;
+};
 /**
  * Returns the `Ok` value, or `defaultValue` when the result is `Err`.
  *
@@ -185,48 +376,82 @@ declare const fold: <T, E, U>(handlers: {
  * unwrapOr(parsedSetting, "default-value");
  * ```
  */
-declare const unwrapOr: <T, E>(result: Result<T, E>, defaultValue: T) => T;
+declare const unwrapOr: {
+    <T, E>(result: Result<T, E>, defaultValue: T): T;
+    <T>(defaultValue: T): <E>(result: Result<T, E>) => T;
+};
 /**
- * Test/assert helper — throws the original Err value when called on Err.
+ * Test/assert helper — returns the `Ok` value, or **throws the original `Err`
+ * value** when called on an `Err`. This is the assertion tier (RFC 0001 §4):
+ * intended for `*.spec.ts` / `*.test.ts`, where throwing fails the test loudly.
+ * In business logic prefer {@link match} or {@link unwrapOr}; the lint plugins
+ * flag `unwrapOk` outside test files.
  *
- * @throws when the result is Err — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.
- * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ * @returns the unwrapped `Ok` value
+ * @throws the carried `Err` value when the result is `Err`
+ *
+ * @example
+ * ```ts
+ * // in a *.spec.ts
+ * expect(unwrapOk(ok(5))).toBe(5);
+ * expect(() => unwrapOk(err(error))).toThrow(error);
+ * ```
  */
 declare function unwrapOk<T, E>(result: Result<T, E>): T;
+/** Alias of {@link unwrapOk} for syntax cohesion with `@onrails/maybe`. */
+declare const unwrap: typeof unwrapOk;
 /**
- * Test/assert helper — throws TypeError when called on Ok.
+ * Test/assert helper — returns the `Err` value, or **throws a `TypeError`**
+ * when called on an `Ok`. Mirror of {@link unwrapOk} on the error track and
+ * part of the same assertion tier (RFC 0001 §4): intended for `*.spec.ts` /
+ * `*.test.ts`. Prefer {@link match} / {@link unwrapOr} in business logic; the
+ * lint plugins flag `unwrapErr` outside test files.
  *
- * @throws when the result is Ok — assertion-tier; allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ * @returns the unwrapped `Err` value
+ * @throws `TypeError` when the result is `Ok`
+ *
+ * @example
+ * ```ts
+ * // in a *.spec.ts
+ * expect(unwrapErr(err("x"))).toBe("x");
+ * expect(() => unwrapErr(ok(5))).toThrow(TypeError);
+ * ```
  */
 declare function unwrapErr<T, E>(result: Result<T, E>): E;
-/** Wrap a throwing sync function — neverthrow `Result.fromThrowable` */
+/**
+ * Wraps a throwing sync function, returning a function that produces a
+ * {@link Result} instead of throwing. Thrown errors pass through `onThrow` to
+ * become a typed `Err`; a normal return becomes `Ok`. The neverthrow analogue
+ * is `Result.fromThrowable`.
+ *
+ * @param fn - the throwing function to wrap
+ * @param onThrow - maps a thrown value to the `Err` channel
+ * @returns a function with `fn`'s parameters that returns `Result<ReturnType, E>`
+ *
+ * @example
+ * ```ts
+ * type ParseError = { kind: "parse"; message: string };
+ * const parse = trySync(
+ *   JSON.parse,
+ *   (e): ParseError => ({ kind: "parse", message: String(e) }),
+ * );
+ * parse("{}");      // Ok({})
+ * parse("nope");    // Err({ kind: "parse", … })
+ * ```
+ */
 declare function trySync<A extends readonly unknown[], T, E>(fn: (...args: A) => T, onThrow: (error: unknown) => E): (...args: A) => Result<T, E>;
 declare function trySync<F extends (...args: never) => unknown, E>(fn: F, onThrow: (error: unknown) => E): (...args: Parameters<F>) => Result<ReturnType<F>, E>;
-/** First failure wins; otherwise collects values in order */
-declare const combine: <T, E>(results: readonly Result<T, E>[]) => Result<T[], E>;
-/** Tuple-preserving combine (neverthrow-style) */
-declare const combineTuple: <const R extends readonly Result<unknown, unknown>[]>(results: R) => CombineTuple<R>;
-type _OkValue<R> = R extends {
-    _tag: "Ok";
-    readonly value: infer T;
-} ? T : never;
-type _ErrValue<R> = R extends {
-    _tag: "Err";
-    readonly error: infer E;
-} ? E : never;
-type CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<{
-    [K in keyof R]: _OkValue<R[K]>;
-}, {
-    [K in keyof R]: _ErrValue<R[K]>;
-}[number]>;
 /**
- * Variadic value-first pipe — threads `value` through up to nine unary fns.
+ * Variadic value-first pipe — threads `value` through up to nine unary fns,
+ * left-to-right. Use {@link pipe} when you already have a starting value;
+ * use {@link flow} to define a reusable composed function with no value yet.
  *
+ * @example
  * ```ts
  * pipe(
  *   parseConfig(raw),
  *   map((cfg) => cfg.name),
- *   flatMap((name) => name ? ok(name) : err({ kind: "empty" })),
+ *   flatMap((name) => (name ? ok(name) : err({ kind: "empty" as const }))),
  *   tap(log),
  * );
  * ```
@@ -241,4 +466,4 @@ declare function pipe<A, B, C, D, E, F, G>(value: A, ab: (a: A) => B, bc: (b: B)
 declare function pipe<A, B, C, D, E, F, G, H>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): H;
 declare function pipe<A, B, C, D, E, F, G, H, I>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): I;
 
-export { Err, Ok, Result, bimap, combine, combineTuple, err, flatMap, fold, isErr, isOk, map, mapErr, match, matchResult, of, ok, pipe, recover, tap, tapErr, trySync, unwrapErr, unwrapOk, unwrapOr };
+export { Err, InferErr, InferOk, Ok, Result, ResultAsync, UnexpectedError, asyncAfter, bimap, combine, combineTuple, err, errAsync, flatMap, fromAsync, fromPromise, fromResult, fromSafePromise, isErr, isOk, map, mapErr, match, ok, okAsync, pipe, recover, tap, tapErr, tryAsync, trySync, unwrap, unwrapErr, unwrapOk, unwrapOr, validateAll, validateTuple };