@pvorona/failable 0.4.0 → 0.6.0

package/README.md

@@ -2,7 +2,15 @@
 
 Typed success/failure results for expected failures in TypeScript.
 
-`Failable<T, E>` is a discriminated union of `Success<T>` and `Failure<E>`. In normal application code, return `success(...)` / `failure(...)`, then branch with `result.isSuccess` / `result.isError` on that local result. Reserve `isSuccess(...)` / `isFailure(...)` for validating hydrated values that arrive as `unknown`, and use `isFailableLike(...)` for plain transport shapes.
+Use `@pvorona/failable` when failure is part of normal control flow: invalid
+input, missing config, not found, or a dependency call that can fail. Return a
+`Failable<T, E>` instead of throwing, then handle the result explicitly.
+
+A `Failable<T, E>` is either `Success<T>` or `Failure<E>`.
+
+- `success(...)` / `failure(...)` create results
+- `failable(...)` captures thrown or rejected boundaries
+- `run(...)` composes multiple `Failable` steps
 
 ## Install
 
@@ -10,82 +18,128 @@ Typed success/failure results for expected failures in TypeScript.
 npm i @pvorona/failable
 ```
 
-This package is ESM-only. Use `import` syntax; the published package declares `Node >=18`.
+This package is ESM-only and requires Node 18+.
 
-## Quick Start
+## Migration Note
 
-```ts
-import type { Failable } from '@pvorona/failable';
-import { failure, success } from '@pvorona/failable';
+If you are upgrading from the previous API name:
 
-function divide(a: number, b: number): Failable<number, string> {
-  if (b === 0) return failure('Cannot divide by zero');
+- `createFailable(x)` -> `failable(x)`
+- `CreateFailableNormalizeErrorOptions` -> `FailableNormalizeErrorOptions`
+- `result.isError` -> `result.isFailure`
+- `.error` is unchanged
+- `failure(...)`, `Failure<E>`, `throwIfError(...)`, and `getOrThrow()` are unchanged
 
-  return success(a / b);
-}
+## Basic Usage
 
-const result = divide(10, 2);
+Use `Failable` when callers need different behavior for different expected
+failures. This is especially useful for business rules that schema validators do
+not model for you:
 
-if (result.isError) {
-  console.error(result.error);
-} else {
-  console.log(result.data);
-}
-```
+```ts
+import { failure, success, type Failable } from '@pvorona/failable';
 
-## Everyday Usage
+type TransferRequest = {
+  fromAccountId: string;
+  toAccountId: string;
+  amountCents: number;
+};
 
-### Quick chooser
+type TransferPlan = TransferRequest & {
+  feeCents: number;
+};
 
-- Use `createFailable(() => ...)` when the boundary is synchronous code that might throw.
-- Use `await createFailable(promise)` when the boundary is async code that might reject.
-- Use `run(...)` when each step already returns `Failable` and you want to compose the happy path.
-- Use `throwIfError(result)` when you want to keep using the same `result` variable after narrowing.
-- Use `result.getOrThrow()` when you want the success value itself in expression or return position.
+type TransferError =
+  | { code: 'same_account' }
+  | { code: 'amount_too_small'; minAmountCents: number }
+  | {
+      code: 'insufficient_funds';
+      balanceCents: number;
+      attemptedCents: number;
+    };
+
+function planTransfer(
+  request: TransferRequest,
+  balanceCents: number,
+): Failable<TransferPlan, TransferError> {
+  if (request.fromAccountId === request.toAccountId) {
+    return failure({ code: 'same_account' });
+  }
 
-### Return `success(...)` and `failure(...)`
+  if (request.amountCents < 100) {
+    return failure({ code: 'amount_too_small', minAmountCents: 100 });
+  }
 
-Use the explicit constructors when your function already knows which branch it should return:
+  if (balanceCents < request.amountCents) {
+    return failure({
+      code: 'insufficient_funds',
+      balanceCents,
+      attemptedCents: request.amountCents,
+    });
+  }
 
-```ts
-import { failure, success } from '@pvorona/failable';
+  return success({ ...request, feeCents: 25 });
+}
 
-const ok = success({ id: '1' });
-const err = failure({ code: 'bad_request' });
-```
+const result = planTransfer(
+  {
+    fromAccountId: 'checking',
+    toAccountId: 'savings',
+    amountCents: 10_000,
+  },
+  4_500,
+);
 
-### Branch and unwrap with helpers
+if (result.isFailure) {
+  switch (result.error.code) {
+    case 'same_account':
+      console.error('Choose a different destination account');
+      break;
+    case 'amount_too_small':
+      console.error(`Transfers start at ${result.error.minAmountCents} cents`);
+      break;
+    case 'insufficient_funds':
+      console.error(
+        `Balance ${result.error.balanceCents} is below ${result.error.attemptedCents}`
+      );
+      break;
+  }
+} else {
+  console.log(result.data.feeCents);
+}
+```
 
-Hydrated `Failable` values carry booleans and convenience methods. Start with ordinary branching on the result, then pick the helper that matches how you want to unwrap:
+That is the default usage model for this package: return a typed result that
+carries both the success value and the expected failure reason.
 
-```ts
-import { failure, success } from '@pvorona/failable';
+## Choose The Right API
 
-const portResult = Math.random() > 0.5
-  ? success(3000)
-  : failure('Missing port');
+| Need | Use |
+| --- | --- |
+| Return a successful or failed result from your own code | `success(...)` / `failure(...)` |
+| Read the value or provide a fallback | `getOr(...)` / `getOrElse(...)` |
+| Recover to `Success<T>` | `or(...)` / `orElse(...)` |
+| Map both branches to one output | `match(onSuccess, onFailure)` |
+| Throw the stored failure unchanged | `getOrThrow()` / `throwIfError(result)` |
+| Capture a throwing or rejecting boundary | `failable(...)` |
+| Compose multiple `Failable` steps | `run(...)` |
+| Cross a structured-clone boundary | `toFailableLike(...)` + `failable(...)` |
+| Validate `unknown` input | `isFailable(...)`, `isSuccess(...)`, `isFailure(...)`, `isFailableLike(...)` |
 
-if (portResult.isError) {
-  console.error(portResult.error);
-} else {
-  console.log(portResult.data);
-}
+## Unwrapping And Recovery
 
-const port = portResult.getOr(3000);
-const ensuredPort = portResult.or(3000);
-console.log(port, ensuredPort.data);
-```
+Start with ordinary branching on `result.isFailure` or `result.isSuccess`. When
+you need a shorter form, use the helper that matches the job:
 
-- `result.isSuccess` / `result.isError`: branch on a hydrated result
-- `result.getOr(fallback)`: eagerly get the success value or a fallback
-- `result.getOrElse(() => fallback)`: lazily compute a fallback value only on failure
-- `result.or(fallback)`: eagerly recover to a `Success` result
-- `result.orElse(() => fallback)`: lazily recover to a `Success` result only on failure
-- `result.match(onSuccess, onFailure)`: map both branches to one output type
-- `throwIfError(result)`: throw the stored failure unchanged and keep using the same result on success
-- `result.getOrThrow()`: unwrap success as a value or throw the stored failure unchanged
+- `result.getOr(fallback)`: return the success value or an eager fallback
+- `result.getOrElse(() => fallback)`: same, but lazily
+- `result.or(fallback)`: recover to `Success<T>` with an eager fallback
+- `result.orElse(() => fallback)`: recover to `Success<T>` lazily
+- `result.match(onSuccess, onFailure)`: map both branches to one output
+- `result.getOrThrow()`: return the success value or throw `result.error`
+- `throwIfError(result)`: throw `result.error` and narrow the same variable
 
-Use `throwIfError(result)` when you want to keep the same result variable and continue with narrowed access to `result.data`:
+Use the lazy forms when the fallback is expensive or has side effects.
 
 ```ts
 import {
@@ -95,296 +149,305 @@ import {
   type Failable,
 } from '@pvorona/failable';
 
-const portResult: Failable<number, string> = Math.random() > 0.5
-  ? success(3000)
-  : failure('Missing port');
+type QuoteError = {
+  code: 'pricing_unavailable';
+};
 
-throwIfError(portResult);
-console.log(portResult.data);
-```
+const feeResult: Failable<number, QuoteError> =
+  Math.random() > 0.5
+    ? success(25)
+    : failure({ code: 'pricing_unavailable' });
 
-Use `getOrThrow()` when you want the success value itself in expression or return position:
+const feeCents = feeResult.getOr(25);
+const status = feeResult.match(
+  (value) => `Fee is ${value} cents`,
+  (error) => `Cannot quote fee: ${error.code}`
+);
 
-```ts
-const requiredPort = portResult.getOrThrow();
-console.log(requiredPort);
+throwIfError(feeResult);
+console.log(feeCents, status, feeResult.data);
 ```
 
-Use the lazy forms when the fallback is expensive or has side effects:
+## Capture Thrown Or Rejected Failures With `failable(...)`
+
+Use `failable(...)` at boundaries that throw or reject, then normalize
+that failure once at the boundary if needed:
+
+Using `TransferPlan` from above:
 
 ```ts
-import { failure, success } from '@pvorona/failable';
+import {
+  failable,
+  run,
+  success,
+  type Failable,
+} from '@pvorona/failable';
 
-function readFallbackPort() {
-  console.log('Reading fallback port from disk');
-  return 3000;
-}
+type SubmitTransferError = Error;
 
-const portResult = Math.random() > 0.5
-  ? success(8080)
-  : failure('Missing port');
+async function postToLedger(
+  plan: TransferPlan,
+): Promise<Failable<{ transferId: string }, SubmitTransferError>> {
+  const request = (async () => {
+    if (plan.amountCents > 5_000) {
+      throw { code: 'ledger_unavailable' } as const;
+    }
 
-const eagerPort = portResult.getOr(readFallbackPort());
-const lazyPort = portResult.getOrElse(() => readFallbackPort());
-const ensuredPort = portResult.orElse(() => readFallbackPort());
+    return { transferId: 'tr_123' };
+  })();
+
+  return await failable(request, {
+    normalizeError(error) {
+      return new Error('Ledger unavailable', { cause: error });
+    },
+  });
+}
 
-console.log(eagerPort, lazyPort, ensuredPort.data);
+async function submitTransfer(
+  plan: TransferPlan,
+): Promise<Failable<{ transferId: string }, SubmitTransferError>> {
+  return await run(async function* ({ get }) {
+    const created = yield* get(postToLedger(plan));
+
+    return success(created);
+  });
+}
 ```
 
-`readFallbackPort()` runs before `getOr(...)` because the fallback expression is evaluated eagerly. With `getOrElse(...)` and `orElse(...)`, the callback runs only if the result is a failure.
+`postToLedger(...)` is the boundary adapter. It uses
+`failable(..., { normalizeError })` to capture a raw throw/rejection once
+and expose one stable `Error` shape to the rest of the app. If you only need
+generic `Error` normalization, `NormalizedErrors` is the built-in shortcut.
+Once that helper already returns `Failable`, `submitTransfer(...)` can use
+`run(...)` to compose it like any other step.
 
-`match(...)` is often clearer than a fallback when both branches need real handling:
+Pass a promise directly when you want rejection capture:
 
 ```ts
-import { failure, success } from '@pvorona/failable';
+const responseResult = await failable(fetch(url));
+```
 
-const portResult = Math.random() > 0.5
-  ? success(3000)
-  : failure('Missing port');
+`failable(...)` can:
 
-const status = portResult.match(
-  (port) => `Listening on ${port}`,
-  (error) => `Cannot start server: ${error}`
-);
-```
+- preserve an existing `Failable`
+- rehydrate a `FailableLike`
+- capture sync throws from a callback
+- capture promise rejections from a promise
+- normalize failures with `NormalizedErrors` or a custom `normalizeError(...)`
 
-### `createFailable(...)` for throwy or rejecting code
+By default, the thrown or rejected value becomes `.error` unchanged.
 
-`createFailable(...)` is the boundary helper for non-`Failable` code. Use it when you need to capture sync throws, promise rejections, or rehydrate an existing result shape. Unlike `run(...)`, it is not for `Failable`-to-`Failable` composition:
+Pass the promise itself when you want rejection capture.
+`failable(async () => value)` is misuse and returns a `Failure<Error>` telling
+you to pass the promise directly instead.
 
-- `createFailable(failable)` returns the same tagged hydrated instance
-- `createFailable(failableLike)` rehydrates a strict wire shape into a real `Success` / `Failure`
-- `createFailable(() => value)` captures synchronous throws into `Failure`
-- `createFailable(promise)` captures async rejections into `Failure`
-- If a callback returns, or a promise resolves to, a `Failable` or `FailableLike`, `createFailable(...)` preserves that result instead of nesting it inside `Success`
+## Compose Existing `Failable` Steps With `run(...)`
 
-Plain lookalike objects are not treated as hydrated `Failable` instances. If you have plain `{ status, data }` or `{ status, error }` transport data, validate it with `isFailableLike(...)` or pass it to `createFailable(...)` to rehydrate before calling instance methods.
+Use `run(...)` when each step already returns `Failable` and you want to write
+the success path once:
 
-If a helper already returns `Failable`, branch on it directly or compose it with `run(...)` instead of wrapping it again with `createFailable(...)`.
+Without `run(...)`, composition often becomes an error ladder:
 
 ```ts
-import {
-  createFailable,
-  failure,
-  success,
-  type Failable,
-} from '@pvorona/failable';
+import { failure, success, type Failable } from '@pvorona/failable';
 
-type PortError = {
-  readonly code: 'invalid_port';
+type Account = {
+  id: string;
+  balanceCents: number;
 };
 
-function readPort(value: unknown): Failable<number, PortError> {
-  if (typeof value !== 'number') return failure({ code: 'invalid_port' });
+type TransferPlanningError =
+  | TransferError
+  | { code: 'source_account_not_found'; accountId: string }
+  | { code: 'destination_account_not_found'; accountId: string };
 
-  return success(value);
-}
-
-const configResult = createFailable(() => JSON.parse(rawConfig));
+function readSourceAccount(
+  accountId: string,
+): Failable<Account, TransferPlanningError> {
+  if (accountId !== 'checking') {
+    return failure({ code: 'source_account_not_found', accountId });
+  }
 
-if (configResult.isError) {
-  console.error('Invalid JSON:', configResult.error);
-} else {
-  const portResult = readPort(configResult.data.port);
+  return success({ id: 'checking', balanceCents: 5_000 });
+}
 
-  if (portResult.isError) {
-    console.error(portResult.error.code);
-  } else {
-    console.log(portResult.data);
+function readDestinationAccount(
+  accountId: string,
+): Failable<Account, TransferPlanningError> {
+  if (accountId !== 'savings') {
+    return failure({ code: 'destination_account_not_found', accountId });
   }
+
+  return success({ id: 'savings', balanceCents: 20_000 });
 }
-```
 
-Pass promises directly when you want rejection capture:
+function ensureDifferentAccounts(
+  source: Account,
+  destination: Account,
+): Failable<void, TransferPlanningError> {
+  if (source.id === destination.id) return failure({ code: 'same_account' });
 
-```ts
-import { createFailable } from '@pvorona/failable';
+  return success(undefined);
+}
 
-const responseResult = await createFailable(fetch(url));
-if (responseResult.isError) console.error(responseResult.error);
-```
+function ensureSufficientFunds(
+  source: Account,
+  amountCents: number,
+): Failable<Account, TransferPlanningError> {
+  if (source.balanceCents < amountCents) {
+    return failure({
+      code: 'insufficient_funds',
+      balanceCents: source.balanceCents,
+      attemptedCents: amountCents,
+    });
+  }
 
-`createFailable(() => promise)` is not the supported API. In TypeScript, obviously promise-returning callbacks such as `async () => ...` and `() => Promise.resolve(...)` are rejected. JS callers, plus `any`/`unknown`-typed callbacks, still rely on the runtime guard; those cases stay in the failure channel as an `Error` telling you to pass the promise directly instead. That guard error is preserved even when you pass a custom `normalizeError`.
+  return success(source);
+}
 
-### `run(...)` for `Failable` composition
+function planTransfer(
+  request: TransferRequest,
+): Failable<TransferPlan, TransferPlanningError> {
+  const source = readSourceAccount(request.fromAccountId);
+  if (source.isFailure) return source;
 
-Use `run(...)` when each step already returns `Failable` and you want the happy path to read top-down. Inside both the sync and async builder forms, use `yield* get(result)` to unwrap success values. The mental model is simple: success values keep flowing forward, and the first yielded `Failure` short-circuits with that same `Failure` instance.
+  const destination = readDestinationAccount(request.toAccountId);
+  if (destination.isFailure) return destination;
 
-```ts
-import { failure, run, success, type Failable } from '@pvorona/failable';
+  const differentAccounts = ensureDifferentAccounts(source.data, destination.data);
+  if (differentAccounts.isFailure) return differentAccounts;
 
-function divide(a: number, b: number): Failable<number, string> {
-  if (b === 0) return failure('Cannot divide by zero');
+  const fundedSource = ensureSufficientFunds(source.data, request.amountCents);
+  if (fundedSource.isFailure) return fundedSource;
 
-  return success(a / b);
+  return success({ ...request, feeCents: 25 });
 }
+```
 
-const result = run(function* ({ get }) {
-  const first = yield* get(divide(20, 2));
-  const second = yield* get(divide(first, 5));
-
-  return success(second);
-});
+With the same helpers, `run(...)` keeps the flow linear:
 
-if (result.isError) {
-  console.error(result.error);
-} else {
-  console.log(result.data); // 2
+```ts
+import { run, success, type Failable } from '@pvorona/failable';
+
+function planTransfer(
+  request: TransferRequest,
+): Failable<TransferPlan, TransferPlanningError> {
+  return run(function* ({ get }) {
+    const source = yield* get(readSourceAccount(request.fromAccountId));
+    const destination = yield* get(readDestinationAccount(request.toAccountId));
+    yield* get(ensureDifferentAccounts(source, destination));
+    yield* get(ensureSufficientFunds(source, request.amountCents));
+
+    return success({ ...request, feeCents: 25 });
+  });
 }
 ```
 
-Async builders use the same composition pattern. Keep using `yield* get(...)`; do not switch to `await get(...)`:
+With one async rule added, the shape stays the same:
 
 ```ts
 import { failure, run, success, type Failable } from '@pvorona/failable';
 
-function divide(a: number, b: number): Failable<number, string> {
-  if (b === 0) return failure('Cannot divide by zero');
+type TransferAsyncError =
+  | TransferPlanningError
+  | { code: 'daily_limit_exceeded'; remainingCents: number };
 
-  return success(a / b);
-}
+const request = {
+  fromAccountId: 'checking',
+  toAccountId: 'savings',
+  amountCents: 2_500,
+};
+
+async function ensureWithinDailyLimit(
+  accountId: string,
+  amountCents: number,
+): Promise<Failable<void, TransferAsyncError>> {
+  const remainingCents = accountId === 'checking' ? 3_000 : 0;
+  if (amountCents > remainingCents) {
+    return failure({ code: 'daily_limit_exceeded', remainingCents });
+  }
 
-async function divideAsync(
-  a: number,
-  b: number,
-): Promise<Failable<number, string>> {
-  return divide(a, b);
+  return success(undefined);
 }
 
 const result = await run(async function* ({ get }) {
-  const first = yield* get(divide(20, 2));
-  const second = yield* get(divideAsync(first, 5));
+  const source = yield* get(readSourceAccount(request.fromAccountId));
+  const destination = yield* get(readDestinationAccount(request.toAccountId));
+  yield* get(ensureDifferentAccounts(source, destination));
+  yield* get(ensureSufficientFunds(source, request.amountCents));
+  yield* get(ensureWithinDailyLimit(source.id, request.amountCents));
 
-  return success(second);
+  return success({ ...request, feeCents: 25 });
 });
-
-if (result.isError) {
-  console.error(result.error);
-} else {
-  console.log(result.data); // 2
-}
 ```
 
-Important `run(...)` rules:
+Keep these rules in mind:
 
-- Use `run(...)` for `Failable`-to-`Failable` composition. Use `createFailable(...)` when you need to capture sync throws, promise rejections, or rehydrate a `FailableLike`.
-- In async builders, keep using `yield* get(...)`. Do not write `await get(...)`.
-- `get(...)` accepts `Failable` sources in both modes and `PromiseLike<Failable>` sources in async builders only.
-- Use `yield* get(failable)` inside the callback. Other interaction with `get` internals is unsupported and not part of the API contract.
-- `get` exists only inside the generator callback; it is not a public export.
-- Return `success(...)`, `failure(...)`, or another `Failable`. An empty generator or bare `return` becomes `Success<void>`, but raw return values are rejected.
-- Throwing inside the generator is not converted into `Failure`, and rejected promised sources are not converted into `Failure`; foreign exceptions and rejections escape unchanged.
-- Rare cleanup edge cases: cleanup `yield* get(...)` steps unwind before a yielded `Failure` returns, cleanup `Failure`s preserve the original `Failure` while outer `finally` blocks keep unwinding, and promised source rejections still unwind managed cleanup before rejecting. Direct `throw`s inside `finally` are outside that managed cleanup and can replace the in-flight failure or rejection.
+- `run(...)` composes existing `Failable` values
+- if a yielded step fails, `run(...)` returns that original failure unchanged
+- in async builders, keep using `yield* get(...)`; do not write `await get(...)`
+- `run(...)` does not capture thrown values or rejected promises into `Failure`
+- wrap throwing or rejecting boundaries with `failable(...)` before they
+  enter `run(...)`
 
-### Use guards for `unknown` values
+## Transport And Runtime Validation
 
-Use `isFailable(...)`, `isSuccess(...)`, and `isFailure(...)` when you start from `unknown` and need to validate something that might already be a hydrated `Failable` instance. If you already have a local result from your own code, keep branching with `result.isSuccess` / `result.isError` instead of re-validating it with top-level guards:
+`Failable` values are hydrated objects with methods. Keep them inside your
+process. If you need a structured-clone-friendly shape, convert to
+`FailableLike<T, E>` before crossing the boundary and rehydrate on the other
+side:
 
 ```ts
-import { isFailable } from '@pvorona/failable';
-
-const candidate: unknown = maybeFromAnotherModule();
-
-if (isFailable(candidate) && candidate.isError) {
-  console.error(candidate.error);
-}
-```
-
-These guards only recognize tagged hydrated instances created by `success(...)`, `failure(...)`, or `createFailable(...)`. Plain objects that merely look similar are not enough.
-
-Use `isSuccess(...)` / `isFailure(...)` when you only care about one branch. If you are validating plain wire data, use `isFailableLike(...)` and then rehydrate with `createFailable(...)` before calling instance methods.
-
-## Important Semantics
-
-- Hydrated `Failable` values are frozen plain objects with methods. Prefer `result.isSuccess` / `result.isError`, and do not use `instanceof`.
-- `run(...)` supports both `function*` and `async function*` builders. In both forms, use `yield* get(...)`; async builders still do not use `await get(...)`.
-- `run(...)` short-circuits on the first yielded failure, preserves that original `Failure` instance unchanged, and enters `finally` cleanup before returning. Cleanup keeps unwinding while cleanup `yield* get(...)` steps succeed. Cleanup `Failure`s preserve the original `Failure` and continue into outer `finally` blocks, while promised cleanup rejections still escape unchanged.
-- In async builders, promised `get(...)` source rejections still escape unchanged after managed `yield* get(...)` cleanup unwinds. Managed cleanup `Failure`s and managed cleanup promise rejections do not replace that original rejection. Direct `throw`s inside `finally` are outside managed cleanup: they still escape unchanged, and they can replace an in-flight yielded `Failure` or main-path rejection.
-- `run(...)` composes existing `Failable` results only. It does not capture thrown values or rejected promises into `Failure`.
-- `or(...)` and `getOr(...)` are eager. The fallback expression runs before the method call.
-- `orElse(...)` and `getOrElse(...)` are lazy. The callback runs only on failure.
-- `match(onSuccess, onFailure)` is useful when both branches should converge to the same output type.
-- `throwIfError(result)` throws `result.error` unchanged on failures and narrows the same hydrated result to `Success<T>` on return.
-- `throwIfError(result)` is deliberately minimal. It does not normalize or map errors; if you want `Error` values, normalize earlier with `createFailable(..., NormalizedErrors)` or a custom `normalizeError`.
-- `isFailable(...)`, `isSuccess(...)`, and `isFailure(...)` recognize only tagged hydrated instances, not public-shape lookalikes.
-- `isFailableLike(...)` remains the validator for transport shapes, and `createFailable(failableLike)` is the supported rehydration path before calling instance methods.
-- `createFailable(...)` remains the boundary tool for capture. Use `createFailable(() => ...)` for synchronous throw capture and `await createFailable(promise)` for async rejection capture.
-- By default, `createFailable(...)` preserves raw thrown and rejected values. If something throws `'boom'`, `{ code: 'bad_request' }`, or `[error1, error2]`, that exact value becomes `.error`.
-- `getOrThrow()` returns the success value and throws `result.error` unchanged on failures. Use `throwIfError(result)` when you want control-flow narrowing instead of a returned value.
-- `createFailable(() => ...)` is for genuinely synchronous callbacks. TypeScript rejects obviously promise-returning callbacks, but JS callers and `any`/`unknown`-typed callbacks still rely on the runtime guard. If you already have a promise, pass it directly: `await createFailable(promise)`. That guard error stays actionable even when a custom `normalizeError` is present.
-
-## Normalizing Errors
-
-If you want `Error`-shaped failures, opt in explicitly with `NormalizedErrors`:
-
-```ts
-import { createFailable, NormalizedErrors } from '@pvorona/failable';
+import {
+  failable,
+  toFailableLike,
+} from '@pvorona/failable';
 
-const result = createFailable(
-  () => {
-    throw { code: 'bad_request' };
+const result = planTransfer(
+  {
+    fromAccountId: 'checking',
+    toAccountId: 'savings',
+    amountCents: 2_500,
   },
-  NormalizedErrors
+  5_000,
 );
 
-if (result.isError) {
-  console.error(result.error.message);
-  console.error(result.error.cause); // { code: 'bad_request' }
-}
+const wire = toFailableLike(result);
+const hydrated = failable(wire);
 ```
 
-The same preset also normalizes existing `failure(...)` values and rehydrated `FailableLike`
-failures, while still passing through existing `Error` instances unchanged.
-
-Built-in normalization behaves like this:
-
-- existing `Error` values pass through unchanged
-- arrays become `AggregateError`
-- other values become `Error`
-- the original raw value is preserved in `error.cause`
-
-Custom normalization is different: `normalizeError` runs for failure values, including
-existing `Error` instances, so you can wrap or replace them. The one exception is the
-internal sync-only callback misuse guard error from `createFailable(() => promise)`,
-which is preserved as-is so the actionable message survives.
-
-For custom normalization:
+Use the runtime guards only when the input did not come from your own local
+control flow:
 
 ```ts
-import { createFailable } from '@pvorona/failable';
-
-const result = createFailable(doThing, {
-  normalizeError(error) {
-    return new Error('Operation failed', { cause: error });
-  },
-});
-```
-
-## Boundary Transport
-
-Hydrated `Failable` values do not survive structured cloning because they carry methods and runtime details. If you need to cross a message boundary, convert to a plain shape first and rehydrate on the receiving side:
+import { isFailable } from '@pvorona/failable';
 
-```ts
-import { createFailable, toFailableLike } from '@pvorona/failable';
+const candidate: unknown = maybeFromAnotherModule();
 
-const wire = toFailableLike(result);
-const hydrated = createFailable(wire);
+if (isFailable(candidate) && candidate.isFailure) {
+  console.error(candidate.error);
+}
 ```
 
-`isFailableLike(...)` validates the strict wire shape `{ status, data }` or `{ status, error }`, and the inner `data` / `error` values must still be structured-cloneable.
+- use `isFailable(...)`, `isSuccess(...)`, and `isFailure(...)` for `unknown`
+  values that might already be hydrated `Failable` results
+- use `isFailableLike(...)` for plain transport shapes like
+  `{ status, data }` or `{ status, error }`
 
 ## API At A Glance
 
 - `type Failable<T, E>`: `Success<T> | Failure<E>`
-- `type Success<T>`: success variant with `isSuccess`, `data`, `or(...)`, `orElse(...)`, `getOr(...)`, `getOrElse(...)`, `match(...)`, and `getOrThrow()`
-- `type Failure<E>`: failure variant with `isError`, `error`, `or(...)`, `orElse(...)`, `getOr(...)`, `getOrElse(...)`, `match(...)`, and `getOrThrow()`
-- `type FailableLike<T, E>`: strict structured-clone-friendly wire shape
-- `const NormalizedErrors`: built-in token for `Error` normalization
-- `success(data)` / `failure(error)`: explicit constructors
-- `throwIfError(result)`: throw the stored failure unchanged and narrow the same result on success
-- `run(...)`: compose sync or async `Failable` steps with short-circuiting
-- `createFailable(...)`: wrap, preserve, rehydrate, or normalize results
-- `isFailable(...)`, `isSuccess(...)`, `isFailure(...)`: runtime validators for tagged hydrated values
-- `toFailableLike(...)`: convert a hydrated result into a plain transport shape
-- `isFailableLike(...)`: validate the strict wire shape
-- `const FailableStatus`: runtime `{ Success, Failure }` object for wire values
+- `type Success<T>` / `type Failure<E>`: hydrated result variants
+- `type FailableLike<T, E>`: structured-clone-friendly wire shape
+- `success(data)` / `failure(error)`: create hydrated results
+- `throwIfError(result)` / `result.getOrThrow()`: throw the stored failure
+  unchanged
+- `failable(...)`: preserve, rehydrate, capture, or normalize failures at
+  a boundary
+- `run(...)`: compose `Failable` steps without nested branching
+- `toFailableLike(...)`: convert a hydrated result into a wire shape
+- `isFailableLike(...)`: validate a wire shape
+- `isFailable(...)`, `isSuccess(...)`, `isFailure(...)`: validate hydrated
+  results
+- `NormalizedErrors`: built-in `Error` normalization for `failable(...)`
+- `FailableStatus`: runtime success/failure status values