@backendkit-labs/result 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,281 @@
+import { R as Result, a as RichResult, T as TrackOptions } from './types-b-fNbJBy.cjs';
+
+/** Creates a successful Result. */
+declare const ok: <T, E = never>(value: T) => Result<T, E>;
+/** Creates a failed Result. */
+declare const fail: <T = never, E = Error>(error: E) => Result<T, E>;
+/**
+ * Wraps a synchronous throwable function. Catches any thrown value and
+ * passes it through `errorTransform` (defaults to identity cast).
+ *
+ * @example
+ * const result = fromThrowable(() => JSON.parse(raw), (e) => new ParseError(e));
+ */
+declare function fromThrowable<T, E = Error>(fn: () => T, errorTransform?: (caught: unknown) => E): Result<T, E>;
+/**
+ * Converts a Promise to a `Promise<Result<T, E>>`, catching rejections.
+ *
+ * @example
+ * const result = await fromPromise(fetch(url), (e) => new NetworkError(e));
+ */
+declare function fromPromise<T, E = Error>(promise: Promise<T>, errorTransform?: (caught: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Converts a nullable value to a Result.
+ * Returns `ok(value)` if non-null/undefined, `fail(error)` otherwise.
+ *
+ * @example
+ * const result = fromNullable(user, new NotFoundError('user'));
+ */
+declare function fromNullable<T, E>(value: T | null | undefined, error: E): Result<T, E>;
+
+type OkResult<T, E> = Extract<Result<T, E>, {
+    ok: true;
+}>;
+type FailResult<T, E> = Extract<Result<T, E>, {
+    ok: false;
+}>;
+/** Narrows a `Result<T, E>` to its success branch. */
+declare function isOk<T, E>(result: Result<T, E>): result is OkResult<T, E>;
+/** Narrows a `Result<T, E>` to its failure branch. */
+declare function isFail<T, E>(result: Result<T, E>): result is FailResult<T, E>;
+/** Returns `true` if the result carries observability metadata (`track()` output). */
+declare function isRich<T, E>(result: Result<T, E>): result is RichResult<T, E>;
+
+/** Maps the success value. Passes failures through unchanged. */
+declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/** Maps the error value. Passes successes through unchanged. */
+declare function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/** Monadic bind — chains a Result-returning function on success. */
+declare function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/** Async variant of `flatMap`. */
+declare function flatMapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+/** Async variant of `map`. */
+declare function mapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<U>): Promise<Result<U, E>>;
+/**
+ * Exhaustive pattern match over both branches.
+ *
+ * @example
+ * const msg = match(result, {
+ *   ok:   (user)  => `Welcome, ${user.name}`,
+ *   fail: (error) => `Error: ${error.message}`,
+ * });
+ */
+declare function match<T, E, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    fail: (error: E) => R;
+}): R;
+/** Alias for `match` — familiar to fp-ts / Scala users. */
+declare const fold: typeof match;
+/** Runs a side effect on the success value; returns the result unchanged. */
+declare function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
+/** Runs a side effect on the error value; returns the result unchanged. */
+declare function tapError<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
+/** Extracts the value or throws the error (re-thrown as-is if it's an Error, wrapped otherwise). */
+declare function unwrap<T, E>(result: Result<T, E>): T;
+/** Extracts the error or throws if the result is Ok. */
+declare function unwrapError<T, E>(result: Result<T, E>): E;
+/** Extracts the value or returns `defaultValue` on failure. */
+declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/** Extracts the value or computes a fallback from the error. */
+declare function unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+/** Extracts the value or throws with a custom `message`. */
+declare function expect<T, E>(result: Result<T, E>, message: string): T;
+/** Converts to a Promise — resolves on Ok, rejects on Fail. */
+declare function toPromise<T, E>(result: Result<T, E>): Promise<T>;
+/** Returns the value or `null` on failure. */
+declare function toNullable<T, E>(result: Result<T, E>): T | null;
+/** Returns the value or `undefined` on failure. */
+declare function toUndefined<T, E>(result: Result<T, E>): T | undefined;
+
+/**
+ * Executes an async (or sync) function and captures any thrown exception,
+ * returning a `Result<T, E>` instead of propagating the error.
+ *
+ * @example
+ * const result = await run(() => fetchUser(id));
+ * const result = await run(() => fetchUser(id), (e) => new UserError(e));
+ */
+declare function run<T, E = Error>(fn: () => T | Promise<T>, errorTransform?: (caught: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Like `run()` but also captures timing and metadata, returning a `RichResult<T, E>`.
+ *
+ * @example
+ * const result = await track(() => fetchUser(id), { operation: 'user.fetch', tags: ['db'] });
+ */
+declare function track<T, E = Error>(fn: () => T | Promise<T>, options?: TrackOptions & {
+    errorTransform?: (caught: unknown) => E;
+}): Promise<RichResult<T, E>>;
+/**
+ * Promotes a plain `Result<T, E>` to a `RichResult<T, E>` with a zero-duration snapshot.
+ * Useful when you already have a Result and want to attach metadata.
+ */
+declare function enrich<T, E>(result: Result<T, E>, options?: TrackOptions): RichResult<T, E>;
+/**
+ * Strips observability metadata from a `RichResult`, returning a plain `Result<T, E>`.
+ */
+declare function simplify<T, E>(rich: RichResult<T, E>): Result<T, E>;
+
+interface RetryOptions<E> {
+    /** Maximum number of attempts (including the first). */
+    attempts: number;
+    /** Fixed delay in ms between attempts. Default: 0 */
+    delayMs?: number;
+    /** Return false to stop retrying early based on the error. */
+    shouldRetry?: (error: E, attempt: number) => boolean;
+    /** Called before each retry with the previous error and attempt number. */
+    onRetry?: (error: E, attempt: number) => void;
+}
+interface BackoffOptions<E> extends RetryOptions<E> {
+    /** Cap for the computed backoff delay. Default: 30_000 */
+    maxDelayMs?: number;
+}
+/**
+ * Retries a Result-returning function up to `options.attempts` times with
+ * an optional fixed delay between attempts.
+ *
+ * @example
+ * const result = await retry(() => run(() => callApi()), {
+ *   attempts: 3,
+ *   delayMs:  500,
+ *   shouldRetry: (err) => err.code === 'ECONNRESET',
+ * });
+ */
+declare function retry<T, E = Error>(fn: () => Promise<Result<T, E>>, options: RetryOptions<E>): Promise<Result<T, E>>;
+/**
+ * Like `retry()` but uses exponential backoff: delay doubles on each attempt,
+ * capped at `maxDelayMs`.
+ *
+ * @example
+ * const result = await retryWithBackoff(() => run(() => callApi()), {
+ *   attempts:   4,
+ *   delayMs:    100,    // 100ms → 200ms → 400ms
+ *   maxDelayMs: 1_000,
+ * });
+ */
+declare function retryWithBackoff<T, E = Error>(fn: () => Promise<Result<T, E>>, options: BackoffOptions<E>): Promise<Result<T, E>>;
+/**
+ * Races a Result-returning function against a timeout.
+ * Returns `fail(timeoutError)` if `ms` elapses before the function resolves.
+ *
+ * @example
+ * const result = await withTimeout(
+ *   () => run(() => fetchData()),
+ *   5_000,
+ *   new TimeoutError('fetchData timed out'),
+ * );
+ */
+declare function withTimeout<T, E>(fn: () => Promise<Result<T, E>>, ms: number, timeoutError: E): Promise<Result<T, E>>;
+
+/**
+ * Returns `ok([...values])` if every result succeeds, or the first `fail` encountered.
+ *
+ * @example
+ * const result = all([findUser(id), findAccount(id)]);
+ * // Result<[User, Account], Error>
+ */
+declare function all<T, E>(results: Result<T, E>[]): Result<T[], E>;
+/**
+ * Returns the first successful result from a list of async operations,
+ * tried sequentially. Returns the last failure if all fail.
+ *
+ * @example
+ * const result = await any([
+ *   () => run(() => primaryCache.get(key)),
+ *   () => run(() => database.find(key)),
+ * ]);
+ */
+declare function any<T, E>(operations: (() => Promise<Result<T, E>>)[]): Promise<Result<T, E>>;
+interface ParallelOptions {
+    /** Max number of operations running concurrently. Default: all at once. */
+    concurrency?: number;
+}
+/**
+ * Runs operations concurrently (optionally throttled by `concurrency`).
+ * Returns `ok([...values])` if all succeed, or the first failure.
+ *
+ * @example
+ * const result = await parallel(
+ *   userIds.map(id => () => run(() => fetchUser(id))),
+ *   { concurrency: 5 },
+ * );
+ */
+declare function parallel<T, E>(operations: (() => Promise<Result<T, E>>)[], options?: ParallelOptions): Promise<Result<T[], E>>;
+/**
+ * Splits an array of Results into `[successValues, errorValues]`.
+ *
+ * @example
+ * const [users, errors] = partition(results);
+ */
+declare function partition<T, E>(results: Result<T, E>[]): [T[], E[]];
+/**
+ * Extracts only the success values, silently discarding failures.
+ *
+ * @example
+ * const users = collect(results); // User[]
+ */
+declare function collect<T, E>(results: Result<T, E>[]): T[];
+/**
+ * Maps each item through a Result-returning function, collecting all successes
+ * into an array or short-circuiting on the first failure.
+ *
+ * @example
+ * const result = traverse(ids, id => fromNullable(cache.get(id), 'not-found'));
+ */
+declare function traverse<T, U, E>(items: T[], fn: (item: T) => Result<U, E>): Result<U[], E>;
+/** Combines two Results into a tuple. Short-circuits on first failure. */
+declare function combine2<A, B, E>(r1: Result<A, E>, r2: Result<B, E>): Result<[A, B], E>;
+/** Combines three Results into a typed tuple. Short-circuits on first failure. */
+declare function combine3<A, B, C, E>(r1: Result<A, E>, r2: Result<B, E>, r3: Result<C, E>): Result<[A, B, C], E>;
+
+/**
+ * Fluent pipeline wrapper around `Result<T, E>`.
+ * Operations short-circuit on failure — subsequent transforms are skipped.
+ *
+ * @example
+ * const price = Flow.from(findProduct(id))
+ *   .map(p => p.price)
+ *   .filter(price => price > 0, new Error('Price must be positive'))
+ *   .map(price => price * taxRate)
+ *   .getResult();
+ */
+declare class Flow<T, E = Error> {
+    private readonly _result;
+    private constructor();
+    /** Start a pipeline from an existing Result. */
+    static from<T, E>(result: Result<T, E>): Flow<T, E>;
+    /** Start an empty pipeline (value is `undefined`). */
+    static start(): Flow<void, never>;
+    /** Maps the success value. Skipped on failure. */
+    map<U>(fn: (value: T) => U): Flow<U, E>;
+    /** Maps the error value. Skipped on success. */
+    mapError<F>(fn: (error: E) => F): Flow<T, F>;
+    /** Chains a Result-returning function. Skipped on failure. */
+    flatMap<U>(fn: (value: T) => Result<U, E>): Flow<U, E>;
+    /** Filters the success value. Becomes `fail(error)` if predicate is false. */
+    filter(pred: (value: T) => boolean, error: E): Flow<T, E>;
+    /** Runs a side effect on success; returns `this` unchanged. */
+    tap(fn: (value: T) => void): this;
+    /** Runs a side effect on failure; returns `this` unchanged. */
+    tapError(fn: (error: E) => void): this;
+    /**
+     * Recovers from a failure by computing a new success value.
+     * Skipped if already Ok.
+     */
+    recover(fn: (error: E) => T): Flow<T, never>;
+    /** Exhaustive pattern match — always produces a value. */
+    match<R>(handlers: {
+        ok: (value: T) => R;
+        fail: (error: E) => R;
+    }): R;
+    /** Returns the underlying `Result<T, E>`. */
+    getResult(): Result<T, E>;
+    /**
+     * Returns the underlying result as `RichResult<T, E>` if it was created by `track()`.
+     * Throws if the result has no observability metadata.
+     */
+    getRichResult(): RichResult<T, E>;
+    isOk(): boolean;
+    isFail(): boolean;
+}
+
+export { type BackoffOptions, Flow, type ParallelOptions, Result, type RetryOptions, RichResult, TrackOptions, all, any, collect, combine2, combine3, enrich, expect, fail, flatMap, flatMapAsync, fold, fromNullable, fromPromise, fromThrowable, isFail, isOk, isRich, map, mapAsync, mapError, match, ok, parallel, partition, retry, retryWithBackoff, run, simplify, tap, tapError, toNullable, toPromise, toUndefined, track, traverse, unwrap, unwrapError, unwrapOr, unwrapOrElse, withTimeout };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { R as Result, a as RichResult, T as TrackOptions } from './types-b-fNbJBy.js';
+
+/** Creates a successful Result. */
+declare const ok: <T, E = never>(value: T) => Result<T, E>;
+/** Creates a failed Result. */
+declare const fail: <T = never, E = Error>(error: E) => Result<T, E>;
+/**
+ * Wraps a synchronous throwable function. Catches any thrown value and
+ * passes it through `errorTransform` (defaults to identity cast).
+ *
+ * @example
+ * const result = fromThrowable(() => JSON.parse(raw), (e) => new ParseError(e));
+ */
+declare function fromThrowable<T, E = Error>(fn: () => T, errorTransform?: (caught: unknown) => E): Result<T, E>;
+/**
+ * Converts a Promise to a `Promise<Result<T, E>>`, catching rejections.
+ *
+ * @example
+ * const result = await fromPromise(fetch(url), (e) => new NetworkError(e));
+ */
+declare function fromPromise<T, E = Error>(promise: Promise<T>, errorTransform?: (caught: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Converts a nullable value to a Result.
+ * Returns `ok(value)` if non-null/undefined, `fail(error)` otherwise.
+ *
+ * @example
+ * const result = fromNullable(user, new NotFoundError('user'));
+ */
+declare function fromNullable<T, E>(value: T | null | undefined, error: E): Result<T, E>;
+
+type OkResult<T, E> = Extract<Result<T, E>, {
+    ok: true;
+}>;
+type FailResult<T, E> = Extract<Result<T, E>, {
+    ok: false;
+}>;
+/** Narrows a `Result<T, E>` to its success branch. */
+declare function isOk<T, E>(result: Result<T, E>): result is OkResult<T, E>;
+/** Narrows a `Result<T, E>` to its failure branch. */
+declare function isFail<T, E>(result: Result<T, E>): result is FailResult<T, E>;
+/** Returns `true` if the result carries observability metadata (`track()` output). */
+declare function isRich<T, E>(result: Result<T, E>): result is RichResult<T, E>;
+
+/** Maps the success value. Passes failures through unchanged. */
+declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/** Maps the error value. Passes successes through unchanged. */
+declare function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/** Monadic bind — chains a Result-returning function on success. */
+declare function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/** Async variant of `flatMap`. */
+declare function flatMapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+/** Async variant of `map`. */
+declare function mapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<U>): Promise<Result<U, E>>;
+/**
+ * Exhaustive pattern match over both branches.
+ *
+ * @example
+ * const msg = match(result, {
+ *   ok:   (user)  => `Welcome, ${user.name}`,
+ *   fail: (error) => `Error: ${error.message}`,
+ * });
+ */
+declare function match<T, E, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    fail: (error: E) => R;
+}): R;
+/** Alias for `match` — familiar to fp-ts / Scala users. */
+declare const fold: typeof match;
+/** Runs a side effect on the success value; returns the result unchanged. */
+declare function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
+/** Runs a side effect on the error value; returns the result unchanged. */
+declare function tapError<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
+/** Extracts the value or throws the error (re-thrown as-is if it's an Error, wrapped otherwise). */
+declare function unwrap<T, E>(result: Result<T, E>): T;
+/** Extracts the error or throws if the result is Ok. */
+declare function unwrapError<T, E>(result: Result<T, E>): E;
+/** Extracts the value or returns `defaultValue` on failure. */
+declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/** Extracts the value or computes a fallback from the error. */
+declare function unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+/** Extracts the value or throws with a custom `message`. */
+declare function expect<T, E>(result: Result<T, E>, message: string): T;
+/** Converts to a Promise — resolves on Ok, rejects on Fail. */
+declare function toPromise<T, E>(result: Result<T, E>): Promise<T>;
+/** Returns the value or `null` on failure. */
+declare function toNullable<T, E>(result: Result<T, E>): T | null;
+/** Returns the value or `undefined` on failure. */
+declare function toUndefined<T, E>(result: Result<T, E>): T | undefined;
+
+/**
+ * Executes an async (or sync) function and captures any thrown exception,
+ * returning a `Result<T, E>` instead of propagating the error.
+ *
+ * @example
+ * const result = await run(() => fetchUser(id));
+ * const result = await run(() => fetchUser(id), (e) => new UserError(e));
+ */
+declare function run<T, E = Error>(fn: () => T | Promise<T>, errorTransform?: (caught: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Like `run()` but also captures timing and metadata, returning a `RichResult<T, E>`.
+ *
+ * @example
+ * const result = await track(() => fetchUser(id), { operation: 'user.fetch', tags: ['db'] });
+ */
+declare function track<T, E = Error>(fn: () => T | Promise<T>, options?: TrackOptions & {
+    errorTransform?: (caught: unknown) => E;
+}): Promise<RichResult<T, E>>;
+/**
+ * Promotes a plain `Result<T, E>` to a `RichResult<T, E>` with a zero-duration snapshot.
+ * Useful when you already have a Result and want to attach metadata.
+ */
+declare function enrich<T, E>(result: Result<T, E>, options?: TrackOptions): RichResult<T, E>;
+/**
+ * Strips observability metadata from a `RichResult`, returning a plain `Result<T, E>`.
+ */
+declare function simplify<T, E>(rich: RichResult<T, E>): Result<T, E>;
+
+interface RetryOptions<E> {
+    /** Maximum number of attempts (including the first). */
+    attempts: number;
+    /** Fixed delay in ms between attempts. Default: 0 */
+    delayMs?: number;
+    /** Return false to stop retrying early based on the error. */
+    shouldRetry?: (error: E, attempt: number) => boolean;
+    /** Called before each retry with the previous error and attempt number. */
+    onRetry?: (error: E, attempt: number) => void;
+}
+interface BackoffOptions<E> extends RetryOptions<E> {
+    /** Cap for the computed backoff delay. Default: 30_000 */
+    maxDelayMs?: number;
+}
+/**
+ * Retries a Result-returning function up to `options.attempts` times with
+ * an optional fixed delay between attempts.
+ *
+ * @example
+ * const result = await retry(() => run(() => callApi()), {
+ *   attempts: 3,
+ *   delayMs:  500,
+ *   shouldRetry: (err) => err.code === 'ECONNRESET',
+ * });
+ */
+declare function retry<T, E = Error>(fn: () => Promise<Result<T, E>>, options: RetryOptions<E>): Promise<Result<T, E>>;
+/**
+ * Like `retry()` but uses exponential backoff: delay doubles on each attempt,
+ * capped at `maxDelayMs`.
+ *
+ * @example
+ * const result = await retryWithBackoff(() => run(() => callApi()), {
+ *   attempts:   4,
+ *   delayMs:    100,    // 100ms → 200ms → 400ms
+ *   maxDelayMs: 1_000,
+ * });
+ */
+declare function retryWithBackoff<T, E = Error>(fn: () => Promise<Result<T, E>>, options: BackoffOptions<E>): Promise<Result<T, E>>;
+/**
+ * Races a Result-returning function against a timeout.
+ * Returns `fail(timeoutError)` if `ms` elapses before the function resolves.
+ *
+ * @example
+ * const result = await withTimeout(
+ *   () => run(() => fetchData()),
+ *   5_000,
+ *   new TimeoutError('fetchData timed out'),
+ * );
+ */
+declare function withTimeout<T, E>(fn: () => Promise<Result<T, E>>, ms: number, timeoutError: E): Promise<Result<T, E>>;
+
+/**
+ * Returns `ok([...values])` if every result succeeds, or the first `fail` encountered.
+ *
+ * @example
+ * const result = all([findUser(id), findAccount(id)]);
+ * // Result<[User, Account], Error>
+ */
+declare function all<T, E>(results: Result<T, E>[]): Result<T[], E>;
+/**
+ * Returns the first successful result from a list of async operations,
+ * tried sequentially. Returns the last failure if all fail.
+ *
+ * @example
+ * const result = await any([
+ *   () => run(() => primaryCache.get(key)),
+ *   () => run(() => database.find(key)),
+ * ]);
+ */
+declare function any<T, E>(operations: (() => Promise<Result<T, E>>)[]): Promise<Result<T, E>>;
+interface ParallelOptions {
+    /** Max number of operations running concurrently. Default: all at once. */
+    concurrency?: number;
+}
+/**
+ * Runs operations concurrently (optionally throttled by `concurrency`).
+ * Returns `ok([...values])` if all succeed, or the first failure.
+ *
+ * @example
+ * const result = await parallel(
+ *   userIds.map(id => () => run(() => fetchUser(id))),
+ *   { concurrency: 5 },
+ * );
+ */
+declare function parallel<T, E>(operations: (() => Promise<Result<T, E>>)[], options?: ParallelOptions): Promise<Result<T[], E>>;
+/**
+ * Splits an array of Results into `[successValues, errorValues]`.
+ *
+ * @example
+ * const [users, errors] = partition(results);
+ */
+declare function partition<T, E>(results: Result<T, E>[]): [T[], E[]];
+/**
+ * Extracts only the success values, silently discarding failures.
+ *
+ * @example
+ * const users = collect(results); // User[]
+ */
+declare function collect<T, E>(results: Result<T, E>[]): T[];
+/**
+ * Maps each item through a Result-returning function, collecting all successes
+ * into an array or short-circuiting on the first failure.
+ *
+ * @example
+ * const result = traverse(ids, id => fromNullable(cache.get(id), 'not-found'));
+ */
+declare function traverse<T, U, E>(items: T[], fn: (item: T) => Result<U, E>): Result<U[], E>;
+/** Combines two Results into a tuple. Short-circuits on first failure. */
+declare function combine2<A, B, E>(r1: Result<A, E>, r2: Result<B, E>): Result<[A, B], E>;
+/** Combines three Results into a typed tuple. Short-circuits on first failure. */
+declare function combine3<A, B, C, E>(r1: Result<A, E>, r2: Result<B, E>, r3: Result<C, E>): Result<[A, B, C], E>;
+
+/**
+ * Fluent pipeline wrapper around `Result<T, E>`.
+ * Operations short-circuit on failure — subsequent transforms are skipped.
+ *
+ * @example
+ * const price = Flow.from(findProduct(id))
+ *   .map(p => p.price)
+ *   .filter(price => price > 0, new Error('Price must be positive'))
+ *   .map(price => price * taxRate)
+ *   .getResult();
+ */
+declare class Flow<T, E = Error> {
+    private readonly _result;
+    private constructor();
+    /** Start a pipeline from an existing Result. */
+    static from<T, E>(result: Result<T, E>): Flow<T, E>;
+    /** Start an empty pipeline (value is `undefined`). */
+    static start(): Flow<void, never>;
+    /** Maps the success value. Skipped on failure. */
+    map<U>(fn: (value: T) => U): Flow<U, E>;
+    /** Maps the error value. Skipped on success. */
+    mapError<F>(fn: (error: E) => F): Flow<T, F>;
+    /** Chains a Result-returning function. Skipped on failure. */
+    flatMap<U>(fn: (value: T) => Result<U, E>): Flow<U, E>;
+    /** Filters the success value. Becomes `fail(error)` if predicate is false. */
+    filter(pred: (value: T) => boolean, error: E): Flow<T, E>;
+    /** Runs a side effect on success; returns `this` unchanged. */
+    tap(fn: (value: T) => void): this;
+    /** Runs a side effect on failure; returns `this` unchanged. */
+    tapError(fn: (error: E) => void): this;
+    /**
+     * Recovers from a failure by computing a new success value.
+     * Skipped if already Ok.
+     */
+    recover(fn: (error: E) => T): Flow<T, never>;
+    /** Exhaustive pattern match — always produces a value. */
+    match<R>(handlers: {
+        ok: (value: T) => R;
+        fail: (error: E) => R;
+    }): R;
+    /** Returns the underlying `Result<T, E>`. */
+    getResult(): Result<T, E>;
+    /**
+     * Returns the underlying result as `RichResult<T, E>` if it was created by `track()`.
+     * Throws if the result has no observability metadata.
+     */
+    getRichResult(): RichResult<T, E>;
+    isOk(): boolean;
+    isFail(): boolean;
+}
+
+export { type BackoffOptions, Flow, type ParallelOptions, Result, type RetryOptions, RichResult, TrackOptions, all, any, collect, combine2, combine3, enrich, expect, fail, flatMap, flatMapAsync, fold, fromNullable, fromPromise, fromThrowable, isFail, isOk, isRich, map, mapAsync, mapError, match, ok, parallel, partition, retry, retryWithBackoff, run, simplify, tap, tapError, toNullable, toPromise, toUndefined, track, traverse, unwrap, unwrapError, unwrapOr, unwrapOrElse, withTimeout };