@onrails/result 0.4.1 → 0.5.0

package/DESIGN.md

@@ -29,6 +29,17 @@ type Result<T, E> =
 - Optional dot-chaining via `fluent(r)` in `@onrails/result/fluent`. Mirrors every instance-appropriate core transform; `test/parity.spec.ts` enforces the mirror (both directions) across core, fluent, and the neverthrow compat shim. `ResultAsync` is already fluent (its methods return `ResultAsync`) — no `fluentAsync` wrapper; wrapping it would just be a one-line delegate to itself.
 - The fluent wrapper stays local: `fluent(r)` opens and a terminal (`toResult`/`toString`/`match`/`unwrapOr`) closes within one expression — it's a closure over data, not data, so it must never be a return type, an exported binding, a stored field, or an argument to a serialize/`postMessage`/cache call. `@onrails/eslint-plugin` and `@onrails/biome-plugin` enforce this via `fluent-stays-local` (RFC 0002 §9).
 
+## Prototype carriers (breaking)
+
+`ok` / `err` return live carriers: `_tag` plus `value` / `error` as own enumerable properties, with `map`, `mapErr`, `flatMap`/`andThen`, `recover`, `tap`, `tapErr`, `match` and `unwrapOr` on a shared non-enumerable prototype (`src/internal/proto.ts`). `r.map(f).flatMap(g)` works on any core `Result`, with core semantics (`tap` propagates throws, `recover` keeps `T`). The neverthrow-semantics names (`andTee`, `orElse`, ...) stay in compat.
+
+- **Serialization:** `JSON.stringify` output is unchanged (same keys, same order). `JSON.parse`, `structuredClone`, spread and `postMessage` return plain data without the methods, while the type still claims them. Lift at every such sink with `Result.from`. `ResultData<T, E>` is the plain shape `from` accepts. Suite `test/prototype-core.spec.ts` covers all four routes.
+- **Literals:** a hand-written `{ _tag: "Ok", value }` is no longer a `Result` (it lacks the methods). `onrails-codemod --literals` rewrites them to `ok` / `err`.
+- **Narrowed branches:** `Err<T, E>` now carries `T` through its methods, so returning a narrowed `Err` as a `Result` with a different `T` needs `err(r.error)` (the same as neverthrow).
+- **Redux, immer:** carriers are not plain objects (prototype is not `Object.prototype`). Redux Toolkit's serializability check flags them, and immer will not draft them. Store `ResultData` (or call `Result.from` on read) and convert at the edge.
+- **Compat shim:** `CompatResult` still wraps a core carrier (`inner`) and now delegates `map`, `mapErr`, `andThen` and `unwrapOr` to the prototype methods. It cannot collapse into the core carrier: its semantics differ by design (`orElse` widens, `andTee` swallows throws, `value` / `error` getters throw), and the differential suite (`neverthrow-diff.spec.ts`) pins exactly that.
+- **Packages:** `result` does not know `maybe`. `Maybe` has the mirrored prototype and `Maybe.from`; `toResult` / `fromResult` stay in `@onrails/maybe/interop`.
+
 ## Sync / async interop
 
 Two distinct lift paths:
@@ -102,7 +113,7 @@ Use `flatMap` for dependent checks where later checks need earlier successful va
 
 ## v1.0 gate
 
-- bun tests: core ops, FL functor/monad laws (sync), neverthrow-compat fixtures.
+- bun tests: core ops, functor/monad/error-functor laws on `Result` and `ResultAsync` (`test/result.laws.spec.ts`), JSON and `structuredClone` round-trips, and a neverthrow differential (`test/neverthrow-diff.spec.ts`): a surface diff against the installed package plus randomised op chains run through both libraries.
 - README with tagged-error guidance.
 - **Not** in v1.0: npm publish.
 

package/README.md

@@ -139,14 +139,20 @@ err({ kind: "not_found", id });   // Result<never, { readonly kind: "not_found";
 ok("ready");                      // Result<"ready", never>
 ```
 
-Locking is inference-only — a value that already has a type is left alone (`ok(name)` where `name: string` is still `Result<string, never>`), and an array literal payload stays assignable to a mutable array (`ok([1, 2])` satisfies `Result<number[], E>`).
+Locking is inference-only — a value that already has a type is left alone (`ok(name)` where `name: string` is still `Result<string, never>`), and an array literal payload stays assignable to a mutable array at every depth (`ok([1, 2])` satisfies `Result<number[], E>`).
 
-Pass **both** type arguments to opt out. Generic code that has to produce `Result<T, E>` for an unresolved `T` needs that form:
+Generic code needs no type arguments — an unresolved `T` passes through unchanged, whatever its constraint:
 
 ```ts
-const lift = <T, E>(value: T): Result<T, E> => ok<T, E>(value);
+const lift = <T, E>(value: T): Result<T, E> => ok(value);
+const toAsync = <T, E>(r: Result<T, E>): ResultAsync<T, E> =>
+  isErr(r) ? errAsync(r.error) : okAsync(r.value);
 ```
 
+Passing **both** type arguments (`ok<T, E>(value)`) opts out of locking.
+
+Array-literal locking needs TypeScript ≥ 5.3. Older compilers widen array literals (`ok([1, 2])` is `Result<number[], never>`) and lock every other literal as usual.
+
 ### Naming the error channel
 
 One explicit type argument on `err` names the **error**:
@@ -350,14 +356,30 @@ Both cap at **12 steps**. That cap is deliberate: a single recursive variadic si
 
 ## Breaking changes
 
+### Carriers have methods; plain data needs `Result.from`
+
+`ok` / `err` (and `some` / `none` in `@onrails/maybe`) now return carriers with `map`, `mapErr`, `flatMap` / `andThen`, `recover`, `tap`, `tapErr`, `match` and `unwrapOr` on a non-enumerable prototype, so `ok(2).map(f).flatMap(g)` works with no wrapper. `_tag` and `value` / `error` are still the only own keys, and `JSON.stringify` output is byte-identical. The module functions (`map(r, f)`, `map(f)(r)`) are unchanged.
+
+| Before | After |
+|---|---|
+| `{ _tag: "Ok", value: x }` | `ok(x)` — run `onrails-codemod <dir> --literals` |
+| `{ _tag: "Err", error: e }` | `err(e)` |
+| `{ _tag: "Some", value: x }` / `{ _tag: "None" }` | `some(x)` / `none()` |
+| `JSON.parse(raw) as Result<T, E>` | `Result.from<T, E>(JSON.parse(raw))` |
+| `structuredClone(r)` used as a `Result` | `Result.from(structuredClone(r))` |
+| `if (isErr(r)) return r;` returning a different `T` | `if (isErr(r)) return err(r.error);` |
+
+`JSON.parse`, `structuredClone`, object spread, `postMessage` and IndexedDB hand back plain data without the methods, while the type still claims them. `Result.from` (and `Maybe.from`) lift it back; `ResultData<T, E>` / `MaybeData<T>` name the plain shape. `@onrails/eslint-plugin` and `@onrails/biome-plugin` ship `carrier-sinks-need-from` to flag the cast forms.
+
+**Redux Toolkit.** Carriers are not plain objects (their prototype is not `Object.prototype`), so the serializability middleware warns on them in actions and state. Keep `ResultData` / `MaybeData` in the store and call `Result.from` / `Maybe.from` in selectors,. Both are cheap: `from` is one allocation.
+
+**immer.** `produce` only drafts plain objects and arrays, so a carrier inside state is treated as an opaque value: replace it wholesale (`draft.user = ok(next)`), do not mutate through it. Carriers are never mutated by the library, so sharing them across drafts is safe.
+
 ### `ok` / `err` lock inline literals
 
-Inline literals no longer widen: `ok("a")` is `Result<"a", never>` and `err({ kind: "io" })` carries `{ readonly kind: "io" }`. Annotated values are unaffected. Two call shapes need a change:
+Inline literals no longer widen: `ok("a")` is `Result<"a", never>` and `err({ kind: "io" })` carries `{ readonly kind: "io" }`. Annotated values and generic type parameters are unaffected. One call shape needs a change:
 
 ```ts
-// generic code — pass both type arguments to opt out of locking
-const lift = <T, E>(value: T): Result<T, E> => ok<T, E>(value);
-
 // a type-level assertion that expected the widened type
 expectType<TypeEqual<typeof ok(1), Result<number, never>>>(true);  // before
 expectType<TypeEqual<typeof value, Result<1, never>>>(true);       // after
@@ -402,7 +424,28 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 - `Result` / `ResultAsync` are class-shaped (`CompatResult` / `CompatResultAsync`).
 - `await ra` resolves to a `CompatResult<T, E>` (thenable), so `.isOk()`, `.value`, `.error`, `.match()`, `.unwrapOr()` all work without an extra `.resolve()` call.
 - `andThen` / `chain` / `flatMap` / `orElse` accept any of `CompatResultAsync` / `ResultAsync` / `CompatResult` / tagged `Result` returns and union the error type.
-- Supported: `andThen`, `asyncAndThen`, `chain`, `flatMap`, `map`, `mapErr`, `orElse`, `match`, `unwrapOr`, `isOk`, `isErr`, `andTee`, `orTee`, `Result.combine`, `Result.fromThrowable`, `ResultAsync.combine`, `ResultAsync.fromPromise`, `ResultAsync.fromSafePromise`, `ResultAsync.fromThrowable`, `_unsafeUnwrap` / `_unsafeUnwrapErr`.
+- Supported: every public member of neverthrow 8.x. `bun test` diffs the shim's surface against the real package (`test/neverthrow-diff.spec.ts`), so a new neverthrow member fails CI until it is covered.
+- Guards: `isOk()` / `isErr()` are type guards; `.value` / `.error` are visible only after narrowing, as in neverthrow. The `else` branch of an `isOk()` check is not narrowed to the error side (the shim is one class, not an `Ok | Err` union) — use `match` or `isErr()`.
+- `Ok` / `Err` support `new` and `instanceof`; `safeTry` accepts sync and async generators using `.safeUnwrap()`.
+
+#### Compat name to core name
+
+| neverthrow / compat | core (`@onrails/result`) | Notes |
+|---|---|---|
+| `r.map(f)` / `r.mapErr(f)` | `map(r, f)` / `mapErr(r, f)` | same |
+| `r.andThen(f)` / `chain` / `flatMap` | `flatMap(r, f)` | `flatMap` is canonical |
+| `r.orElse(f)` | `recover(r, f)` | |
+| `r.andTee(f)` / `r.orTee(f)` | `tap(r, f)` / `tapErr(r, f)` | `tap` takes a pure side effect; compat also swallows a throwing callback, core does not |
+| `r.andThrough(f)` | `flatMap(r, (v) => map(f(v), () => v))` | keeps the original `Ok` value, surfaces the callback's `Err` |
+| `r.asyncMap(f)` | `ResultAsync.fromResult(r).map(f)` | |
+| `r.match(ok, err)` | `match(r, ok, err)` | |
+| `r.unwrapOr(d)` | `unwrapOr(r, d)` | |
+| `r._unsafeUnwrap()` | `unwrapOk(r)` | assertion tier |
+| `Result.fromThrowable(f, h)` | `fromThrowable(f, h)` | |
+| `Result.combine` / `combineWithAllErrors` | `combineTuple` / `validateTuple` | |
+| `safeTry(function* () { ... })` | `tryGen(() => { ... })` | `yield* r.safeUnwrap()` becomes `$(r)`; `tryGen` is sync, use `ResultAsync` chains for async bodies |
+| `ok(1) instanceof Ok` | `isOk(r)` | |
+
 - Treat the compat surface as a migration step, not the destination — once a package migrates, switch its imports to `@onrails/result` and `@onrails/result/fluent`.
 
 ## Subpaths
@@ -418,4 +461,8 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 | `@onrails/result/try-gen` | `tryGen`, `yieldResult`, `$` |
 | `@onrails/result/compat/neverthrow` | Migration shim |
 
+## Benchmarks
+
+Runtime + fair import-graph size vs `neverthrow`: see [`../bench/RESULTS.md`](../bench/RESULTS.md). Regenerated with `bun run bench:md` from the repo root.
+
 See [DESIGN.md](./DESIGN.md).

package/RECIPES.md

@@ -54,7 +54,7 @@ const stepResult = tryGen(() => {
   const user = $(authenticate(req));
   const post = $(fetchPost(postId));
   if (post.authorId !== user.id && !user.isAdmin) {
-    return err({ kind: "unauthorized" as const });
+    return err({ kind: "unauthorized" });
   }
   return ok(post);
 });
@@ -117,7 +117,7 @@ const saveOrder = (rawJson: string) =>
   pipe(
     rawJson,
     parseUser,                                                            // Result<User, ParseError | SchemaError>
-    flatMap((u) => (u.active ? ok(u) : err({ kind: "inactive" as const }))),
+    flatMap((u) => (u.active ? ok(u) : err({ kind: "inactive" }))),
     mapErr((e) => ({ kind: "input" as const, cause: e })),
     tap((u) => log.info({ msg: "validated", userId: u.id })),
     asyncAfter((u) =>
@@ -239,10 +239,10 @@ type CharsError  = { kind: "chars"; bad: string };
 type TooShortError = { kind: "too_short"; min: number };
 
 const requireMin = (min: number) => (s: string) =>
-  s.length >= min ? ok(s) : err({ kind: "len" as const, min });
+  s.length >= min ? ok(s) : err({ kind: "len", min });
 
 const requireAscii = (s: string) =>
-  /^[\x20-\x7e]*$/.test(s) ? ok(s) : err({ kind: "chars" as const, bad: s });
+  /^[\x20-\x7e]*$/.test(s) ? ok(s) : err({ kind: "chars", bad: s });
 
 const validateUsername = flow(
   (raw: string) => ok(raw.trim()),
@@ -250,7 +250,7 @@ const validateUsername = flow(
   flatMap(requireAscii),
   recover(
     (e: LengthError | CharsError): Result<string, TooShortError | CharsError> =>
-      e.kind === "len" ? err({ kind: "too_short" as const, min: e.min }) : err(e),
+      e.kind === "len" ? err({ kind: "too_short", min: e.min }) : err(e),
   ),
 );
 // (raw: string) => Result<string, TooShortError | CharsError>

package/dist/async.d.cts

@@ -1,5 +1,5 @@
 import type { InferErr, InferOk } from "./internal/infer.js";
-import type { Locked } from "./internal/lock.js";
+import type { Payload } from "./internal/payload.js";
 import type { Result } from "./types.js";
 import { UnexpectedError } from "./types.js";
 type PromiseFactory<T, E> = () => Promise<Result<T, E>>;
@@ -98,13 +98,15 @@ export declare class ResultAsync<T, E> {
      * const r = ResultAsync.ok(42);   // ResultAsync<number, never>
      * ```
      */
-    static ok<const T>(value: T): ResultAsync<Locked<T>, never>;
+    static ok<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static ok<const T>(value: T): ResultAsync<T, never>;
     static ok<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Fantasy Land `pure` — alias of {@link ResultAsync.ok}. One lift name
      * shared across the trio (`of` / `Maybe.of` / `ResultAsync.of`).
      */
-    static of<const T>(value: T): ResultAsync<Locked<T>, never>;
+    static of<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static of<const T>(value: T): ResultAsync<T, never>;
     static of<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Lifts an error into an `Err` async result.
@@ -114,7 +116,8 @@ export declare class ResultAsync<T, E> {
      * const r = ResultAsync.err({ kind: "not_found" as const });
      * ```
      */
-    static err<const E>(error: E): ResultAsync<never, Locked<E>>;
+    static err<const E extends Payload[]>(error: E): ResultAsync<never, E>;
+    static err<const E>(error: E): ResultAsync<never, E>;
     static err<T, E>(error: E): ResultAsync<T, E>;
     /**
      * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a

package/dist/async.d.ts

@@ -1,5 +1,5 @@
 import type { InferErr, InferOk } from "./internal/infer.js";
-import type { Locked } from "./internal/lock.js";
+import type { Payload } from "./internal/payload.js";
 import type { Result } from "./types.js";
 import { UnexpectedError } from "./types.js";
 type PromiseFactory<T, E> = () => Promise<Result<T, E>>;
@@ -98,13 +98,15 @@ export declare class ResultAsync<T, E> {
      * const r = ResultAsync.ok(42);   // ResultAsync<number, never>
      * ```
      */
-    static ok<const T>(value: T): ResultAsync<Locked<T>, never>;
+    static ok<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static ok<const T>(value: T): ResultAsync<T, never>;
     static ok<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Fantasy Land `pure` — alias of {@link ResultAsync.ok}. One lift name
      * shared across the trio (`of` / `Maybe.of` / `ResultAsync.of`).
      */
-    static of<const T>(value: T): ResultAsync<Locked<T>, never>;
+    static of<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static of<const T>(value: T): ResultAsync<T, never>;
     static of<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Lifts an error into an `Err` async result.
@@ -114,7 +116,8 @@ export declare class ResultAsync<T, E> {
      * const r = ResultAsync.err({ kind: "not_found" as const });
      * ```
      */
-    static err<const E>(error: E): ResultAsync<never, Locked<E>>;
+    static err<const E extends Payload[]>(error: E): ResultAsync<never, E>;
+    static err<const E>(error: E): ResultAsync<never, E>;
     static err<T, E>(error: E): ResultAsync<T, E>;
     /**
      * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a