@onrails/result 0.2.0 → 0.3.1

package/dist/railway.cjs

@@ -1,5 +1,12 @@
 'use strict';
 
+// src/internal/dual.ts
+var dual = (arity, body) => {
+  const run = body;
+  const dispatcher = (...args) => args.length >= arity ? run(...args) : (self) => run(self, ...args);
+  return dispatcher;
+};
+
 // src/result.ts
 var ok = (value) => ({
   _tag: "Ok",
@@ -11,18 +18,18 @@ var err = (error) => ({
 });
 var isOk = (result) => result._tag === "Ok";
 var isErr = (result) => result._tag === "Err";
-var mapImpl = (result, fn) => isOk(result) ? ok(fn(result.value)) : err(result.error);
-function map(...args) {
-  if (args.length === 2) return mapImpl(args[0], args[1]);
-  const fn = args[0];
-  return (result) => mapImpl(result, fn);
-}
-var mapErrImpl = (result, fn) => isErr(result) ? err(fn(result.error)) : ok(result.value);
-function mapErr(...args) {
-  if (args.length === 2) return mapErrImpl(args[0], args[1]);
-  const fn = args[0];
-  return (result) => mapErrImpl(result, fn);
-}
+var map = dual(
+  2,
+  (result, fn) => isOk(result) ? ok(fn(result.value)) : err(result.error)
+);
+var mapErr = dual(
+  2,
+  (result, fn) => isErr(result) ? err(fn(result.error)) : ok(result.value)
+);
+var flatMap = dual(
+  2,
+  (result, fn) => isOk(result) ? fn(result.value) : err(result.error)
+);
 function trySync(fn, onThrow) {
   return (...args) => {
     try {
@@ -44,17 +51,6 @@ var UnexpectedError = class extends Error {
 };
 
 // src/async.ts
-var liftPromiseResult = async (promise, onDefect) => {
-  try {
-    const result = await promise;
-    if (isErr(result)) {
-      return result;
-    }
-    return isResultLike(result.value) ? result.value : result;
-  } catch (error) {
-    return err(onDefect(error));
-  }
-};
 var sequenceSettled = (settled) => {
   const values = [];
   for (const result of settled) {
@@ -136,6 +132,9 @@ var ResultAsync = class _ResultAsync {
   static ok(value) {
     return new _ResultAsync(async () => ok(value));
   }
+  static of(value) {
+    return _ResultAsync.ok(value);
+  }
   /**
    * Lifts an error into an `Err` async result.
    *
@@ -149,16 +148,23 @@ var ResultAsync = class _ResultAsync {
   }
   /**
    * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a
-   * {@link ResultAsync}, auto-flattening one level of double-wrapping. A thrown
-   * defect is routed through `onDefect`, defaulting to {@link UnexpectedError}.
+   * {@link ResultAsync}. A thrown defect is routed through `onDefect`,
+   * defaulting to {@link UnexpectedError}. The `Ok` value passes through
+   * verbatim — even when it happens to be Result-shaped.
    *
    * @param promise - a promise that already yields a `Result`
    * @param onDefect - maps an unexpected throw to the `Err` channel
-   * @see {@link fromAsync} from `@onrails/result/interop`
+   * @see {@link fromAsync} from `@onrails/result`
    */
   static fromResultPromise(promise, onDefect) {
     const mapDefect = onDefect ?? ((error) => new UnexpectedError("Unexpected async defect", error));
-    return new _ResultAsync(() => liftPromiseResult(promise, mapDefect));
+    return new _ResultAsync(async () => {
+      try {
+        return await promise;
+      } catch (error) {
+        return err(mapDefect(error));
+      }
+    });
   }
   /**
    * Combines a homogeneous array of async results into one. Resolves
@@ -242,7 +248,7 @@ var ResultAsync = class _ResultAsync {
    *
    * @example
    * ```ts
-   * load(id).mapErr((e): AppError => ({ kind: "load", cause: e }));
+   * load(id).mapErr((e): AppError => ({ kind: "load", cause: e })); // ResultAsync<T, AppError>
    * ```
    */
   mapErr(fn) {
@@ -266,18 +272,12 @@ var ResultAsync = class _ResultAsync {
         return first;
       }
       const next = fn(first.value);
-      if (next instanceof _ResultAsync) {
-        return next.resolve();
-      }
-      if (isResultLike(next)) {
-        return next;
-      }
-      return isCompatLike(next) ? next.inner : next;
+      return next instanceof _ResultAsync ? next.resolve() : next;
     });
   }
   /**
    * neverthrow-compat alias of {@link flatMap}. Kept as the documented compat
-   * tier; prefer `flatMap` in new code.
+   * tier; prefer {@link flatMap} in new code.
    *
    * @example
    * ```ts
@@ -294,7 +294,7 @@ var ResultAsync = class _ResultAsync {
    *
    * @example
    * ```ts
-   * loadFromCache(id).recover(() => loadFromOrigin(id));
+   * loadFromCache(id).recover(() => loadFromOrigin(id)); // ResultAsync<T, F>
    * ```
    */
   recover(fn) {
@@ -309,7 +309,7 @@ var ResultAsync = class _ResultAsync {
   }
   /**
    * neverthrow-compat alias of {@link recover}. Kept as the documented compat
-   * tier; prefer `recover` in new code.
+   * tier; prefer {@link recover} in new code.
    *
    * @example
    * ```ts
@@ -417,16 +417,9 @@ var ResultAsync = class _ResultAsync {
     );
   }
 };
-function isResultLike(v) {
-  return typeof v === "object" && v !== null && "_tag" in v && (v._tag === "Ok" || v._tag === "Err");
-}
-function isCompatLike(v) {
-  return typeof v === "object" && v !== null && "inner" in v && isResultLike(v.inner);
-}
 
-// src/railway-core.ts
+// src/railway.ts
 var addField = (ctx, key, value) => ({ ...ctx, [key]: value });
-var liftResult = (result) => ResultAsync.fromResult(result);
 var Railway = class _Railway {
   constructor(state) {
     this.state = state;
@@ -440,10 +433,7 @@ var Railway = class _Railway {
   static context(context) {
     return new _Railway({ mode: "sync", result: ok(context) });
   }
-  /**
-   * Start a sync workflow with a throwing function — `onThrow` maps any
-   * exception to a typed error.
-   */
+  /** Start a sync workflow with a throwing function. */
   static fromSync(key, fn, onThrow) {
     return _Railway.empty().fromSync(key, fn, onThrow);
   }
@@ -460,164 +450,103 @@ var Railway = class _Railway {
     return _Railway.empty().fromAsync(key, fn);
   }
   /**
-   * Pure sync derivation — `fn` must not throw. Use {@link fromSync} for
-   * throwing transforms.
+   * Rebuild the workflow in its current mode after transforming the carried
+   * result. Single re-link point for the state/phantom invariant: the mode
+   * tag is preserved verbatim, so `M` still describes the new state — TS
+   * cannot narrow the phantom `M` from the runtime tag, hence the cast.
    */
-  derive(key, fn) {
-    return this.fromResult(key, (ctx) => ok(fn(ctx)));
+  step(onSync, onAsync) {
+    const next = this.state.mode === "sync" ? { mode: "sync", result: onSync(this.state.result) } : { mode: "async", result: onAsync(this.state.result) };
+    return new _Railway(next);
   }
   /**
-   * Throwing sync transform. Adds `{ [key]: T }` to context; converts any
-   * exception to `Err<F>` via `onThrow`.
+   * Project the carried result into the mode-aware output type. Counterpart
+   * of {@link Railway.step} for terminal steps: the runtime branch matches
+   * the branch `RailwayOutput` picks for `M` (state/phantom invariant), but
+   * TS cannot resolve the conditional on an unresolved `M`, hence the cast.
    */
+  out(onSync, onAsync) {
+    return this.state.mode === "sync" ? onSync(this.state.result) : onAsync(this.state.result);
+  }
+  /** Lift the carried result into `ResultAsync` for async-upgrading steps. */
+  toAsync() {
+    return this.state.mode === "sync" ? ResultAsync.fromResult(this.state.result) : this.state.result;
+  }
+  /** Pure sync derivation. */
+  derive(key, fn) {
+    return this.fromResult(key, (ctx) => ok(fn(ctx)));
+  }
+  /** Throwing sync transform. */
   fromSync(key, fn, onThrow) {
     return this.fromResult(key, (ctx) => trySync(fn, onThrow)(ctx));
   }
-  /**
-   * Sync `Result`-returning step. Adds `{ [key]: T }` to context on `Ok`;
-   * short-circuits the workflow on `Err`. Error union widens to `E | F`.
-   */
+  /** Sync `Result`-returning step. */
   fromResult(key, fn) {
-    if (this.state.mode === "sync") {
-      const current = this.state.result;
-      if (isErr(current)) {
-        return new _Railway({ mode: "sync", result: err(current.error) });
-      }
-      const next = fn(current.value);
-      return isErr(next) ? new _Railway({ mode: "sync", result: err(next.error) }) : new _Railway({
-        mode: "sync",
-        result: ok(addField(current.value, key, next.value))
-      });
-    }
-    return new _Railway({
-      mode: "async",
-      result: this.state.result.flatMap(
+    return this.step(
+      (result) => flatMap(result, (ctx) => map(fn(ctx), (value) => addField(ctx, key, value))),
+      (result) => result.flatMap(
         (ctx) => ResultAsync.fromResult(fn(ctx)).map((value) => addField(ctx, key, value))
       )
-    });
+    );
   }
-  /**
-   * Promise-returning step — upgrades the workflow to async mode. Reject
-   * reasons go through `onReject` to become typed `Err<F>`.
-   */
+  /** Promise-returning step — upgrades the workflow to async mode. */
   fromPromise(key, fn, onReject) {
     return this.fromAsync(key, (ctx) => ResultAsync.fromPromise(fn(ctx), onReject));
   }
-  /**
-   * `ResultAsync`-returning step — upgrades the workflow to async mode.
-   * Already-typed error: no mapper needed.
-   */
+  /** `ResultAsync`-returning step — upgrades the workflow to async mode. */
   fromAsync(key, fn) {
-    const current = this.state.mode === "sync" ? liftResult(this.state.result) : this.state.result;
     return new _Railway({
       mode: "async",
-      result: current.flatMap((ctx) => fn(ctx).map((value) => addField(ctx, key, value)))
+      result: this.toAsync().flatMap((ctx) => fn(ctx).map((value) => addField(ctx, key, value)))
     });
   }
-  /**
-   * Narrow a nullable context field into a required non-null field. If the
-   * source field is `null` / `undefined`, the workflow short-circuits with
-   * `onMissing(ctx)`.
-   *
-   * @example
-   * ```ts
-   * .fromPromise("row", ({ id }) => db.users.findFirst({ where: eq(users.id, id) }))
-   * .require("user", "row", ({ id }) => ({ kind: "not_found" as const, id }))
-   * // user is now User (non-null), not User | null
-   * ```
-   */
+  /** Narrow a nullable context field into a required non-null field. */
   require(key, source, onMissing) {
     return this.fromResult(key, (ctx) => {
       const value = ctx[source];
       return value == null ? err(onMissing(ctx)) : ok(value);
     });
   }
-  /**
-   * Run independent `ResultAsync` branches concurrently and merge their
-   * named outputs back into context. Upgrades the workflow to async mode.
-   * On multiple failures, the first `Err` in record-iteration order wins.
-   *
-   * @example
-   * ```ts
-   * .parallel({
-   *   recent:  ({ userId }) => loadRecent(userId),
-   *   metrics: ({ userId }) => loadMetrics(userId),
-   * })
-   * // ctx now has { ..., recent, metrics }
-   * ```
-   */
+  /** Run independent `ResultAsync` branches concurrently and merge outputs. */
   parallel(branches) {
-    const current = this.state.mode === "sync" ? liftResult(this.state.result) : this.state.result;
+    const merged = this.toAsync().flatMap(
+      (ctx) => ResultAsync.combineTupleParallel(
+        Object.entries(branches).map(([, branch]) => branch(ctx))
+      ).map(
+        (values) => (
+          // Branch outputs land under exactly R's keys; Object.fromEntries
+          // erases that correspondence, so reassert the merged shape.
+          {
+            ...ctx,
+            ...Object.fromEntries(Object.keys(branches).map((key, index) => [key, values[index]]))
+          }
+        )
+      )
+    );
     return new _Railway({
       mode: "async",
-      result: current.flatMap(
-        (ctx) => ResultAsync.combineTupleParallel(
-          Object.entries(branches).map(([, branch]) => branch(ctx))
-        ).map((values) => {
-          const next = { ...ctx };
-          Object.keys(branches).forEach((key, index) => {
-            next[key] = values[index];
-          });
-          return next;
-        })
-      )
+      // BranchFn erases per-key types to `ResultAsync<unknown, unknown>`
+      // (ParallelOutput/ParallelError recover them from R), so re-assert the
+      // precise value/error union the branches actually produce.
+      result: merged
     });
   }
-  /**
-   * Project the final context into the workflow's output type. Hides the
-   * internal context shape from callers.
-   */
+  /** Project the final context into the workflow's output type. */
   select(fn) {
-    if (this.state.mode === "sync") {
-      const current = this.state.result;
-      return isErr(current) ? err(current.error) : ok(fn(current.value));
-    }
-    return this.state.result.map(fn);
+    return this.out(
+      (result) => map(result, fn),
+      (result) => result.map(fn)
+    );
   }
-  /**
-   * Return the accumulated context as-is. Use when downstream code needs
-   * every named field; prefer {@link select} when you can project to a DTO.
-   */
+  /** Return the accumulated context as-is. */
   done() {
-    return this.state.result;
+    return this.out(
+      (result) => result,
+      (result) => result
+    );
   }
 };
 
-// src/railway-steps.ts
-var parseWithParser = (parser, input) => typeof parser === "function" ? parser(input) : parser.parse(input);
-function railway(input, ...steps) {
-  return steps.reduce(
-    (current, step) => step(current),
-    Railway.context({ input })
-  );
-}
-var parseWith = (parser, onThrow) => ({
-  as: (key) => (workflow) => workflow.fromSync(key, ({ input }) => parseWithParser(parser, input), onThrow)
-});
-var parseNamed = (key, parser, onThrow) => (workflow) => workflow.fromSync(key, ({ input }) => parseWithParser(parser, input), onThrow);
-var fromSyncNamed = (key, fn, onThrow) => (workflow) => workflow.fromSync(key, fn, onThrow);
-var fromResultNamed = (key, fn) => (workflow) => workflow.fromResult(key, fn);
-var fromPromiseNamed = (key, fn, onReject) => (workflow) => workflow.fromPromise(key, fn, onReject);
-var fromAsyncNamed = (key, fn) => (workflow) => workflow.fromAsync(key, fn);
-var deriveNamed = (key, fn) => (workflow) => workflow.derive(key, fn);
-var requireNamed = (key, source, onMissing) => (workflow) => workflow.require(key, source, onMissing);
-var parallelNamed = (branches) => (workflow) => {
-  const typedBranches = branches;
-  return workflow.parallel(typedBranches);
-};
-var select = (fn) => (workflow) => workflow.select(fn);
-
 exports.Railway = Railway;
-exports.deriveNamed = deriveNamed;
-exports.fromAsyncNamed = fromAsyncNamed;
-exports.fromPromiseNamed = fromPromiseNamed;
-exports.fromResultNamed = fromResultNamed;
-exports.fromSyncNamed = fromSyncNamed;
-exports.parallelNamed = parallelNamed;
-exports.parseNamed = parseNamed;
-exports.parseWith = parseWith;
-exports.railway = railway;
-exports.requireNamed = requireNamed;
-exports.select = select;
 //# sourceMappingURL=railway.cjs.map
 //# sourceMappingURL=railway.cjs.map