@konker.dev/neverthrow-r 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Konrad Markus <mail@konker.dev>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# neverthrow-r
+
+An extension for [neverthrow](https://github.com/supermacro/neverthrow) that adds a third channel — `R`, for requirements / dependencies — to `Result` and `ResultAsync`.
+
+Inspired by effect-ts, but deliberately small: `neverthrow-r` is a thin layer of curried, pipe-friendly functions over neverthrow. There is no runtime, no context machinery, no scheduler — just two type aliases and a set of operators that thread an `R` parameter through your existing neverthrow chains.
+
+## Install
+
+```sh
+pnpm add @konker.dev/neverthrow-r neverthrow
+```
+
+`neverthrow` is a peer dependency.
+
+## Core types
+
+```ts
+type ResultR<R, T, E> = (r: R) => Result<T, E>;
+type ResultAsyncR<R, T, E> = (r: R) => ResultAsync<T, E>;
+```
+
+A value of type `ResultR<R, T, E>` is a function that, given an `R`, produces a neverthrow `Result<T, E>`. `R` defaults to `unknown` (no specific requirements).
+
+When two steps are chained, their requirement types are combined with intersection: a chain of `ResultR<R1, A, E1>` and `(a: A) => ResultR<R2, B, E2>` produces `ResultR<R1 & R2, B, E1 | E2>`.
+
+## `pipe`
+
+`neverthrow-r` ships a small value-piping `pipe` implementation. It applies functions from left to right, preserves the inferred output type through the chain, and supports up to 20 function arguments:
+
+```ts
+import { pipe } from '@konker.dev/neverthrow-r';
+```
+
+If you already use a value-piping `pipe` from another library (e.g. `effect`, `fp-ts`, `remeda`), the operators remain shape-compatible with those too.
+
+## Quick example
+
+```ts
+import { andThen, asks, pipe, provide, type ResultR } from '@konker.dev/neverthrow-r';
+
+const loadUser =
+  (id: string): ResultR<{ db: Db }, User, DbError> =>
+  (r) =>
+    r.db.findUser(id);
+
+const greet = (user: User): ResultR<{ logger: Logger }, string, never> =>
+  asks((r) => {
+    r.logger.info(`greeting ${user.name}`);
+    return `Hello, ${user.name}`;
+  });
+
+const program = (id: string) => pipe(loadUser(id), andThen(greet));
+//    ^? ResultR<{ db: Db } & { logger: Logger }, string, DbError>
+
+const result = provide(program('u-1'), { db, logger });
+//    ^? Result<string, DbError>
+```
+
+Note how `program`'s requirement type is the _intersection_ of the two steps' requirements — that intersection is built up automatically as you chain.
+
+## Async example with do-notation
+
+```ts
+import { okAsync } from 'neverthrow';
+import { bindAsyncR, doAsyncR, fromResultAsync, pipe, provide } from '@konker.dev/neverthrow-r';
+
+const program = pipe(
+  doAsyncR(),
+  bindAsyncR('user', () => (r: { db: Db }) => r.db.findUserAsync('u-1')),
+  bindAsyncR('greeting', ({ user }) => fromResultAsync(okAsync(`Hello, ${user.name}`)))
+);
+
+const result = await provide(program, { db });
+// result.value === { user: User, greeting: string }
+```
+
+Each `bindAsyncR` step:
+
+- accumulates a named value onto the success scope,
+- contributes its own requirements to the chain's `R`,
+- short-circuits the whole chain on the first `Err`.
+
+Note that `doAsyncR()` (and `doR()`) is called without a generic type argument here. `R` defaults to `unknown` and the chain's accumulated requirements are built up automatically by each `bindAsyncR` step — because `unknown & X = X`. You only need an explicit `doAsyncR<MyEnv>()` if you want to _constrain_ the chain to a known environment up front (so that subsequent steps requiring anything outside `MyEnv` become type errors).
+
+## Partial provision
+
+```ts
+import { provideSome } from '@konker.dev/neverthrow-r';
+
+declare const program: ResultR<{ db: Db; logger: Logger }, User, Error>;
+
+// inject the logger now, leave db for later
+const stillNeedsDb = provideSome(program, { logger });
+//  ^? ResultR<{ db: Db }, User, Error>
+
+const result = provide(stillNeedsDb, { db });
+```
+
+`provideSome` whole-replaces the provided keys (no deep merge); the returned `ResultR` requires whatever keys were not provided.
+
+## API
+
+### Constructors
+
+- `okR(value)`, `errR(error)` — lift into `ResultR`
+- `okAsyncR(value)`, `errAsyncR(error)` — lift into `ResultAsyncR`
+- `fromResult(r)`, `fromResultAsync(ra)` — lift an existing neverthrow value
+- `asks(f)` — build a `ResultR` from a selector over the environment
+- `ask()` — `asks(r => r)`, returns the full environment
+
+### Pipe
+
+`pipe(value, ...fns)` — apply up to 20 unary functions from left to right.
+
+### Sync operators (over `ResultR`)
+
+`map`, `mapErr`, `andThen`, `orElse`, `match`, `andTee`, `orTee`, `andThrough`
+
+### Async operators (over `ResultAsyncR`)
+
+`mapAsync`, `mapErrAsync`, `andThenAsync`, `orElseAsync`, `matchAsync`, `andTeeAsync`, `orTeeAsync`, `andThroughAsync`
+
+### Sync → async bridges
+
+`asyncMap`, `asyncAndThen`, `asyncAndThrough` — take a `ResultR`, return a `ResultAsyncR`.
+
+### Do-notation
+
+`doR`, `bindR`, `doAsyncR`, `bindAsyncR` — accumulate named values into a success-channel scope while threading `R`.
+
+### Provision
+
+- `provide(rr, deps)` — supply all requirements, return the underlying `Result` / `ResultAsync`.
+- `provideSome(rr, partial)` — supply some requirements, return a `ResultR` over the remaining ones.
+
+## API Reference
+
+Full auto-generated reference docs (signatures, types, module summaries) live in [`./docs/reference/`](./docs/reference/). They're regenerated from source on every `ci` run and a staleness check fails the build if they drift.
+
+## License
+
+ISC

package/dist/async.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Async combinators over `ResultAsyncR`, mirroring the sync surface from
+ * {@link sync} 1:1. Each combinator is the `Async`-suffixed sibling of its
+ * sync counterpart; semantics and type signatures match, lifted to
+ * `ResultAsyncR`.
+ *
+ * @remarks
+ * Cross-link to the sync module for the full prose on each combinator. The
+ * docs here focus on the async-specific shape: each transformer accepts
+ * `Promise`-returning functions, and the operand is a `ResultAsyncR`.
+ *
+ * Reach for this module when the chain is already async (e.g. it started
+ * with {@link okAsyncR} or was promoted via {@link bridges}). To enter the
+ * async track from a sync chain mid-pipeline, use {@link bridges} instead.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThenAsync, mapAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okAsyncR<number>(2),
+ *   mapAsync(async (n) => n + 1),
+ *   andThenAsync((n) => okAsyncR<string>(`got ${n}`)),
+ * );
+ *
+ * program(undefined); // ResultAsync resolving to Ok('got 3')
+ * ```
+ *
+ * @module
+ */
+import type { ResultAsyncR } from './types.js';
+/**
+ * Async variant of {@link map}. Accepts a sync- or `Promise`-returning
+ * transform.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { mapAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const doubled = pipe(okAsyncR<number>(2), mapAsync(async (n) => n * 2));
+ * ```
+ *
+ * @see {@link map}
+ */
+export declare const mapAsync: <A, B>(f: (a: A) => B | Promise<B>) => <R, E>(rr: ResultAsyncR<R, A, E>) => ResultAsyncR<R, B, E>;
+/**
+ * Async variant of {@link mapErr}. Accepts a sync- or `Promise`-returning
+ * transform.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { mapErrAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const wrapped = pipe(
+ *   errAsyncR<string>('boom'),
+ *   mapErrAsync(async (msg) => ({ tag: 'fail' as const, msg })),
+ * );
+ * ```
+ *
+ * @see {@link mapErr}
+ */
+export declare const mapErrAsync: <E, F>(f: (e: E) => F | Promise<F>) => <R, T>(rr: ResultAsyncR<R, T, E>) => ResultAsyncR<R, T, F>;
+/**
+ * Async variant of {@link andThen}. The continuation returns a
+ * `ResultAsyncR`; its requirements intersect into the chain.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThenAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okAsyncR<number>(2),
+ *   andThenAsync((n) => okAsyncR<string>(`got ${n}`)),
+ * );
+ * ```
+ *
+ * @see {@link andThen}
+ */
+export declare const andThenAsync: <A, R2, B, E2>(f: (a: A) => ResultAsyncR<R2, B, E2>) => <R1, E1>(rr: ResultAsyncR<R1, A, E1>) => ResultAsyncR<R1 & R2, B, E1 | E2>;
+/**
+ * Async variant of {@link orElse}. The recovery returns a `ResultAsyncR`.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR, okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { orElseAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const withFallback = pipe(
+ *   errAsyncR<string, number>('boom'),
+ *   orElseAsync(() => okAsyncR<number>(0)),
+ * );
+ * ```
+ *
+ * @see {@link orElse}
+ */
+export declare const orElseAsync: <E, R2, U, F>(f: (e: E) => ResultAsyncR<R2, U, F>) => <R1, T>(rr: ResultAsyncR<R1, T, E>) => ResultAsyncR<R1 & R2, T | U, F>;
+/**
+ * Async variant of {@link match}. Returns a function from environment to a
+ * `Promise` of the matched value.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { matchAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const rendered = pipe(
+ *   okAsyncR<number>(42),
+ *   matchAsync(
+ *     (n) => `got ${n}`,
+ *     (e: never) => `error: ${String(e)}`,
+ *   ),
+ * );
+ * // rendered(undefined) is Promise<string>
+ * ```
+ *
+ * @see {@link match}
+ */
+export declare const matchAsync: <T, E, A, B = A>(okFn: (t: T) => A, errFn: (e: E) => B) => <R>(rr: ResultAsyncR<R, T, E>) => (r: R) => Promise<A | B>;
+/**
+ * Async variant of {@link andTee}.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andTeeAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const traced = pipe(okAsyncR<number>(2), andTeeAsync((n) => console.log(n)));
+ * ```
+ *
+ * @see {@link andTee}
+ */
+export declare const andTeeAsync: <T>(f: (t: T) => unknown) => <R, E>(rr: ResultAsyncR<R, T, E>) => ResultAsyncR<R, T, E>;
+/**
+ * Async variant of {@link orTee}.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { orTeeAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const logged = pipe(errAsyncR<string>('boom'), orTeeAsync((e) => console.error(e)));
+ * ```
+ *
+ * @see {@link orTee}
+ */
+export declare const orTeeAsync: <E>(f: (e: E) => unknown) => <R, T>(rr: ResultAsyncR<R, T, E>) => ResultAsyncR<R, T, E>;
+/**
+ * Async variant of {@link andThrough}.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR, okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThroughAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const validated = pipe(
+ *   okAsyncR<number>(2),
+ *   andThroughAsync((n) =>
+ *     n > 0 ? okAsyncR<unknown>(undefined) : errAsyncR<string>('non-positive'),
+ *   ),
+ * );
+ * ```
+ *
+ * @see {@link andThrough}
+ */
+export declare const andThroughAsync: <T, R2, F>(f: (t: T) => ResultAsyncR<R2, unknown, F>) => <R1, E>(rr: ResultAsyncR<R1, T, E>) => ResultAsyncR<R1 & R2, T, E | F>;
+//# sourceMappingURL=async.d.ts.map

package/dist/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../src/async.ts"],"names":[],"mappings":"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"}

package/dist/async.js

@@ -0,0 +1,178 @@
+/**
+ * Async combinators over `ResultAsyncR`, mirroring the sync surface from
+ * {@link sync} 1:1. Each combinator is the `Async`-suffixed sibling of its
+ * sync counterpart; semantics and type signatures match, lifted to
+ * `ResultAsyncR`.
+ *
+ * @remarks
+ * Cross-link to the sync module for the full prose on each combinator. The
+ * docs here focus on the async-specific shape: each transformer accepts
+ * `Promise`-returning functions, and the operand is a `ResultAsyncR`.
+ *
+ * Reach for this module when the chain is already async (e.g. it started
+ * with {@link okAsyncR} or was promoted via {@link bridges}). To enter the
+ * async track from a sync chain mid-pipeline, use {@link bridges} instead.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThenAsync, mapAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okAsyncR<number>(2),
+ *   mapAsync(async (n) => n + 1),
+ *   andThenAsync((n) => okAsyncR<string>(`got ${n}`)),
+ * );
+ *
+ * program(undefined); // ResultAsync resolving to Ok('got 3')
+ * ```
+ *
+ * @module
+ */
+/**
+ * Async variant of {@link map}. Accepts a sync- or `Promise`-returning
+ * transform.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { mapAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const doubled = pipe(okAsyncR<number>(2), mapAsync(async (n) => n * 2));
+ * ```
+ *
+ * @see {@link map}
+ */
+export const mapAsync = (f) => (rr) => (r) => rr(r).map(f);
+/**
+ * Async variant of {@link mapErr}. Accepts a sync- or `Promise`-returning
+ * transform.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { mapErrAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const wrapped = pipe(
+ *   errAsyncR<string>('boom'),
+ *   mapErrAsync(async (msg) => ({ tag: 'fail' as const, msg })),
+ * );
+ * ```
+ *
+ * @see {@link mapErr}
+ */
+export const mapErrAsync = (f) => (rr) => (r) => rr(r).mapErr(f);
+/**
+ * Async variant of {@link andThen}. The continuation returns a
+ * `ResultAsyncR`; its requirements intersect into the chain.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThenAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okAsyncR<number>(2),
+ *   andThenAsync((n) => okAsyncR<string>(`got ${n}`)),
+ * );
+ * ```
+ *
+ * @see {@link andThen}
+ */
+export const andThenAsync = (f) => (rr) => (r) => rr(r).andThen((a) => f(a)(r));
+/**
+ * Async variant of {@link orElse}. The recovery returns a `ResultAsyncR`.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR, okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { orElseAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const withFallback = pipe(
+ *   errAsyncR<string, number>('boom'),
+ *   orElseAsync(() => okAsyncR<number>(0)),
+ * );
+ * ```
+ *
+ * @see {@link orElse}
+ */
+export const orElseAsync = (f) => (rr) => (r) => rr(r).orElse((e) => f(e)(r));
+/**
+ * Async variant of {@link match}. Returns a function from environment to a
+ * `Promise` of the matched value.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { matchAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const rendered = pipe(
+ *   okAsyncR<number>(42),
+ *   matchAsync(
+ *     (n) => `got ${n}`,
+ *     (e: never) => `error: ${String(e)}`,
+ *   ),
+ * );
+ * // rendered(undefined) is Promise<string>
+ * ```
+ *
+ * @see {@link match}
+ */
+export const matchAsync = (okFn, errFn) => (rr) => async (r) => rr(r).match(okFn, errFn);
+/**
+ * Async variant of {@link andTee}.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andTeeAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const traced = pipe(okAsyncR<number>(2), andTeeAsync((n) => console.log(n)));
+ * ```
+ *
+ * @see {@link andTee}
+ */
+export const andTeeAsync = (f) => (rr) => (r) => rr(r).andTee(f);
+/**
+ * Async variant of {@link orTee}.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { orTeeAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const logged = pipe(errAsyncR<string>('boom'), orTeeAsync((e) => console.error(e)));
+ * ```
+ *
+ * @see {@link orTee}
+ */
+export const orTeeAsync = (f) => (rr) => (r) => rr(r).orTee(f);
+/**
+ * Async variant of {@link andThrough}.
+ *
+ * @example
+ * ```ts
+ * import { errAsyncR, okAsyncR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThroughAsync } from '@konker.dev/neverthrow-r/async';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const validated = pipe(
+ *   okAsyncR<number>(2),
+ *   andThroughAsync((n) =>
+ *     n > 0 ? okAsyncR<unknown>(undefined) : errAsyncR<string>('non-positive'),
+ *   ),
+ * );
+ * ```
+ *
+ * @see {@link andThrough}
+ */
+export const andThroughAsync = (f) => (rr) => (r) => rr(r).andThrough((t) => f(t)(r));
+//# sourceMappingURL=async.js.map

package/dist/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../src/async.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GACnB,CAAO,CAA2B,EAAE,EAAE,CACtC,CAAO,EAAyB,EAAyB,EAAE,CAC3D,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,CAAO,CAA2B,EAAE,EAAE,CACtC,CAAO,EAAyB,EAAyB,EAAE,CAC3D,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,CAAe,CAAoC,EAAE,EAAE,CACvD,CAAS,EAA2B,EAAqC,EAAE,CAC3E,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAElC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,CAAc,CAAmC,EAAE,EAAE,CACrD,CAAQ,EAA0B,EAAmC,EAAE,CACvE,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,UAAU,GACrB,CAAiB,IAAiB,EAAE,KAAkB,EAAE,EAAE,CAC1D,CAAI,EAAyB,EAAE,EAAE,CACjC,KAAK,EAAE,CAAI,EAAkB,EAAE,CAC7B,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,CAAI,CAAoB,EAAE,EAAE,CAC5B,CAAO,EAAyB,EAAyB,EAAE,CAC3D,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GACrB,CAAI,CAAoB,EAAE,EAAE,CAC5B,CAAO,EAAyB,EAAyB,EAAE,CAC3D,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,CAAW,CAAyC,EAAE,EAAE,CACxD,CAAQ,EAA0B,EAAmC,EAAE,CACvE,CAAC,CAAC,EAAE,EAAE,CACJ,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/bridges.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Sync→async bridge operators: take a `ResultR` and return a `ResultAsyncR`,
+ * promoting the chain onto the async track mid-pipeline.
+ *
+ * @remarks
+ * Reach for this module when a chain that starts synchronously needs to
+ * await — typically an I/O call partway through. Three flavours, mirroring
+ * the corresponding sync combinators but lifting the operand into
+ * `ResultAsyncR`:
+ *
+ * - {@link asyncMap} — promote via a `Promise`-returning transform.
+ * - {@link asyncAndThen} — promote via a `ResultAsyncR`-returning step.
+ * - {@link asyncAndThrough} — promote via a fallible async tee.
+ *
+ * Every step *after* the bridge must come from {@link async} (the
+ * `*Async`-suffixed combinators); there is no async→sync bridge.
+ *
+ * @example
+ * ```ts
+ * import { okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { mapAsync } from '@konker.dev/neverthrow-r/async';
+ * import { asyncMap } from '@konker.dev/neverthrow-r/bridges';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okR<number>(2),
+ *   asyncMap(async (n) => n + 1),   // sync → async here
+ *   mapAsync(async (n) => n * 10),  // continue async
+ * );
+ *
+ * program(undefined); // ResultAsync resolving to Ok(30)
+ * ```
+ *
+ * @module
+ */
+import type { ResultAsyncR, ResultR } from './types.js';
+/**
+ * Promotes a `ResultR` to a `ResultAsyncR` by applying a `Promise`-returning
+ * transform to the success value.
+ *
+ * @remarks
+ * The sync→async sibling of {@link map}. After this step the chain is async;
+ * follow with {@link mapAsync}, {@link andThenAsync}, etc.
+ *
+ * @typeParam A - The input success type.
+ * @typeParam B - The output success type.
+ *
+ * @param f - `Promise`-returning transform from `A` to `B`.
+ *
+ * @example
+ * ```ts
+ * import { okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { asyncMap } from '@konker.dev/neverthrow-r/bridges';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(okR<number>(2), asyncMap(async (n) => n * 2));
+ * program(undefined); // ResultAsync resolving to Ok(4)
+ * ```
+ *
+ * @see {@link map}
+ * @see {@link mapAsync}
+ */
+export declare const asyncMap: <A, B>(f: (a: A) => Promise<B>) => <R, E>(rr: ResultR<R, A, E>) => ResultAsyncR<R, B, E>;
+/**
+ * Promotes a `ResultR` to a `ResultAsyncR` by chaining a
+ * `ResultAsyncR`-returning step.
+ *
+ * @remarks
+ * Sync→async sibling of {@link andThen}. The continuation's requirements
+ * `R2` are intersected (`R1 & R2`); its error type `E2` is unioned
+ * (`E1 | E2`).
+ *
+ * @typeParam A - The previous step's success type.
+ * @typeParam R2 - The continuation's requirements.
+ * @typeParam B - The continuation's success type.
+ * @typeParam E2 - The continuation's error type.
+ *
+ * @param f - Function from the previous success value to a `ResultAsyncR`.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR, okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { asyncAndThen } from '@konker.dev/neverthrow-r/bridges';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okR<number>(2),
+ *   asyncAndThen((n) => okAsyncR<string>(`got ${n}`)),
+ * );
+ *
+ * program(undefined); // ResultAsync resolving to Ok('got 2')
+ * ```
+ *
+ * @see {@link andThen}
+ * @see {@link andThenAsync}
+ */
+export declare const asyncAndThen: <A, R2, B, E2>(f: (a: A) => ResultAsyncR<R2, B, E2>) => <R1, E1>(rr: ResultR<R1, A, E1>) => ResultAsyncR<R1 & R2, B, E1 | E2>;
+/**
+ * Promotes a `ResultR` to a `ResultAsyncR` via a fallible async tee that
+ * propagates the *original* success value.
+ *
+ * @remarks
+ * Sync→async sibling of {@link andThrough}. The tee step is itself a
+ * `ResultAsyncR` that can fail; on success its value is discarded and the
+ * chain continues with the original success value.
+ *
+ * @typeParam T - The success type (preserved through the step on success).
+ * @typeParam R2 - The tee's requirements.
+ * @typeParam F - The tee's error type.
+ *
+ * @param f - Function from the success value to a `ResultAsyncR` whose value
+ *   is ignored on success.
+ *
+ * @example
+ * ```ts
+ * import { okAsyncR, okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { asyncAndThrough } from '@konker.dev/neverthrow-r/bridges';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ *
+ * const program = pipe(
+ *   okR<number>(2),
+ *   asyncAndThrough((n) => okAsyncR<unknown>(`logged ${n}`)),
+ * );
+ *
+ * program(undefined); // ResultAsync resolving to Ok(2)
+ * ```
+ *
+ * @see {@link andThrough}
+ * @see {@link andThroughAsync}
+ */
+export declare const asyncAndThrough: <T, R2, F>(f: (t: T) => ResultAsyncR<R2, unknown, F>) => <R1, E>(rr: ResultR<R1, T, E>) => ResultAsyncR<R1 & R2, T, E | F>;
+//# sourceMappingURL=bridges.d.ts.map

package/dist/bridges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridges.d.ts","sourceRoot":"","sources":["../src/bridges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,QAAQ,GAClB,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,MAC7B,CAAC,EAAE,CAAC,EAAE,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAE/B,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,YAAY,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,MAClD,EAAE,EAAE,EAAE,EAAE,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,KAAG,YAAY,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAE9B,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,GACzB,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,MACnD,EAAE,EAAE,CAAC,EAAE,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,YAAY,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAEvB,CAAC"}