@pvorona/failable 0.7.0 → 0.9.0

package/README.md

@@ -11,6 +11,8 @@ A `Failable<T, E>` is either `Success<T>` or `Failure<E>`.
 - `success()` / `success(data)` / `failure()` / `failure(error)` create results
 - `failable(...)` captures thrown or rejected boundaries
 - `run(...)` composes multiple `Failable` steps
+- `all(...)`, `allSettled(...)`, and `race(...)` combine multiple sources
+- `result.map(...)` / `result.flatMap(...)` transform and chain success values
 
 ## Install
 
@@ -67,9 +69,12 @@ if (result.isFailure) {
 | 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)` |
+| Throw an `Error` from a failure | `getOrThrow(normalizeOption?)` / `throwIfFailure(result, normalizeOption?)` |
 | Capture a throwing or rejecting boundary | `failable(...)` |
 | Compose multiple `Failable` steps | `run(...)` |
+| Combine multiple `Failable` sources | `all(...)`, `allSettled(...)`, `race(...)` |
+| Transform a successful value only | `map(...)` |
+| Chain another `Failable` step | `flatMap(...)` |
 | Cross a structured-clone boundary | `toFailableLike(...)` + `failable(...)` |
 | Validate `unknown` input | `isFailable(...)`, `isSuccess(...)`, `isFailure(...)`, `isFailableLike(...)` |
 
@@ -79,14 +84,36 @@ Start with ordinary branching on `result.isFailure` or `result.isSuccess`. When
 you want something shorter, use the helper that matches the job:
 
 - `result.getOr(fallback)`: return the success value or an eager fallback
-- `result.getOrElse(() => fallback)`: same, but lazily
+- `result.getOrElse(() => fallback)`: lazy fallback
+- `result.getOrElse((error) => fallback)`: lazy fallback derived from the failure
 - `result.or(fallback)`: recover to `Success<T>` with an eager fallback
-- `result.orElse(() => fallback)`: recover to `Success<T>` lazily
+- `result.orElse(() => fallback)`: lazy recovery to `Success<T>`
+- `result.orElse((error) => fallback)`: lazy recovery to `Success<T>` derived from the failure
 - `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
+- `result.getOrThrow(normalizeOption?)`: return the success value or throw an `Error` derived from the failure
+- `throwIfFailure(result, normalizeOption?)`: throw an `Error` derived from the failure and narrow the same variable
 
-Use the lazy forms when the fallback is expensive or has side effects.
+Both throw helpers preserve existing `Error` instances unchanged by default.
+Other failure values are normalized with the built-in rules: arrays become
+`AggregateError`; plain objects become `Error` with `cause`; primitives and
+`undefined` become `Error(String(value), { cause: value })`.
+
+Pass `NormalizedErrors` or a custom `normalizeError(...)` when you need a
+specific `Error` shape at the throw boundary. Normalize earlier with
+`failable(...)` only when you need that normalized `Error` inside the
+`Failure` channel before anything throws. If built-in message derivation
+itself fails, normalization still returns an `Error` with message
+`Unstringifiable error value` and `cause` set to the original raw value.
+
+Use the lazy forms when the fallback is expensive or has side effects. Failure
+callbacks receive the stored error, so `() => ...` can ignore it and
+`(error) => ...` can use it:
+
+```ts
+const port = result.getOrElse((error) => {
+  return error.code === 'missing' ? 3000 : 8080;
+});
+```
 
 Using `readPort` from above:
 
@@ -100,18 +127,83 @@ const label = result.match(
 );
 ```
 
-`throwIfError` narrows the result to `Success` in place, so
+`throwIfFailure` narrows the result to `Success` in place, so
 subsequent code can access `.data` without branching:
 
 ```ts
-import { throwIfError } from '@pvorona/failable';
+import { throwIfFailure } from '@pvorona/failable';
 
 const result = readPort(process.env.PORT);
 
-throwIfError(result);
+throwIfFailure(result);
 console.log(result.data * 2);
 ```
 
+When you want a specific `Error` shape only at the throw site, pass the
+normalize option there:
+
+```ts
+import { NormalizedErrors } from '@pvorona/failable';
+
+const port = readPort(process.env.PORT).getOrThrow(NormalizedErrors);
+```
+
+## Transform And Chain With `map(...)` And `flatMap(...)`
+
+Use `result.map(fn)` when you only need to change the success value. The callback
+runs on `Success` only; on `Failure`, the same failure is returned unchanged.
+
+Use `result.flatMap(fn)` when the next step can fail again. The callback must
+return another `Failable`. On `Success`, that result becomes the outcome; on
+`Failure`, `flatMap` short-circuits and keeps the original error.
+
+Building on `readPort` from [Basic Usage](#basic-usage):
+
+```ts
+import { failure, success, type Failable } from '@pvorona/failable';
+
+type ReadPortError =
+  | { code: 'missing' }
+  | { code: 'invalid'; raw: string };
+
+type ApplicationPortError =
+  | ReadPortError
+  | { code: 'not_application_port'; port: number };
+
+function readPort(raw: string | undefined): Failable<number, ReadPortError> {
+  if (raw === undefined) return failure({ code: 'missing' });
+
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    return failure({ code: 'invalid', raw });
+  }
+
+  return success(port);
+}
+
+function ensureApplicationPort(
+  port: number,
+): Failable<number, ApplicationPortError> {
+  if (port < 3000 || port > 3999) {
+    return failure({ code: 'not_application_port', port });
+  }
+
+  return success(port);
+}
+
+const appPortResult = readPort(process.env.PORT).flatMap((port) =>
+  ensureApplicationPort(port),
+);
+
+const labelResult = appPortResult.map(
+  (port) => `Application listening on ${port}`,
+);
+```
+
+When you pass object literals directly into `success(...)` or `failure(...)`,
+TypeScript often keeps their types as narrow as possible (literal fields where
+that makes sense), which helps `switch` on `error.code` and similar patterns.
+
 ## Capture Thrown Or Rejected Failures With `failable(...)`
 
 Use `failable(...)` at a boundary you do not control. It turns a thrown or
@@ -134,7 +226,8 @@ if (configResult.isFailure) {
 ```
 
 `NormalizedErrors` is the built-in shortcut when you want `.error` to be an
-`Error`.
+`Error`, including when the thrown or rejected non-`Error` value cannot be
+stringified safely.
 
 Pass a promise directly when you want rejection capture:
 
@@ -155,20 +248,34 @@ const config = fileResult.getOr('{}');
 - preserve an existing `Failable`
 - rehydrate a `FailableLike`
 - capture sync throws from a callback
-- capture promise rejections from a promise
+- capture promise rejections from a promise passed directly
 - normalize failures with `NormalizedErrors` or a custom `normalizeError(...)`
 
 By default, the thrown or rejected value becomes `.error` unchanged.
 
-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.
+Pass the promise itself when you want rejection capture. In TypeScript,
+obviously promise-returning callbacks like `async () => ...` and
+`() => Promise.resolve(...)` are rejected. JS callers, plus `any`/`unknown`-typed
+callbacks, receive a `Failure<Error>` telling them to pass the promise directly
+instead.
 
 ## Compose Existing `Failable` Steps With `run(...)`
 
 Use `run(...)` when each step already returns `Failable` and you want to write
-the success path once. If any yielded step fails, `run(...)` returns that same
-failure unchanged.
+the success path once. If any yielded step fails, that failure becomes the
+default unwind result. Cleanup still runs first, and an explicit `return`
+reached in `finally` overrides it. Yielded cleanup `Failure` values keep the
+current unwind result unless a later cleanup `return` overrides it.
+
+Inside a `run(...)` builder, there are two valid delegation forms:
+
+- `yield* result` when `result` is already a hydrated `Failable`
+- `yield* await promisedResult` in async builders when you have a
+  `Promise<Failable<...>>`
+
+Hydrated `Failable` values expose sync and async iterators so `run(...)` can
+intercept `yield* result` in both sync and async builders. Outside `run(...)`,
+treat them as result objects rather than as a general-purpose collection API.
 
 Without `run(...)`, composing steps means checking each result before
 continuing:
@@ -233,16 +340,20 @@ function loadConfig(
 }
 ```
 
-When a helper already returns a hydrated sync `Failable`, yield it directly with
-`yield* helper()`. Keep `yield* get(...)` for sources that are promises or
-thenables.
+When a helper already returns a hydrated `Failable`, yield it directly with
+`yield* helper()`. For promised sources in async builders, await them first and
+then yield the hydrated result with `yield* await promisedHelper()`.
+
+`run(...)` does not inject helper arguments. Import the top-level combinators
+you need and use them directly inside the builder.
 
 For async flows, switch to `run(async function* ...)`. Sync hydrated helpers
-still work with direct `yield* helper()`, while `get(...)` handles promised
-sources and keeps their full `Success` / `Failure` union inference:
+still work with direct `yield* helper()`, and promised sources compose with
+`yield* await ...`:
 
 ```ts
 import {
+  all,
   failable,
   failure,
   run,
@@ -261,17 +372,17 @@ type Profile = { id: string; pictureUrl: string };
 async function readJson<T>(url: string) {
   const responseResult = await failable(fetch(url));
   if (responseResult.isFailure) {
-    return failure({ code: 'network_error', cause: responseResult.error } as const);
+    return failure({ code: 'network_error', cause: responseResult.error });
   }
 
   const response = responseResult.data;
   if (!response.ok) {
-    return failure({ code: 'http_error', status: response.status } as const);
+    return failure({ code: 'http_error', status: response.status });
   }
 
   const jsonResult = await failable(response.json());
   if (jsonResult.isFailure) {
-    return failure({ code: 'json_parse_error', cause: jsonResult.error } as const);
+    return failure({ code: 'json_parse_error', cause: jsonResult.error });
   }
 
   return success(jsonResult.data as T);
@@ -288,22 +399,94 @@ async function getUserProfile(userId: string) {
 async function loadUserPage(
   userId: string,
 ): Promise<Failable<{ user: User; profile: Profile }, ApiError>> {
-  return await run(async function* ({ get }) {
-    const user = yield* get(getUser(userId));
-    const profile = yield* get(getUserProfile(userId));
+  return await run(async function* () {
+    const [user, profile] = yield* await all(
+      getUser(userId),
+      getUserProfile(userId)
+    );
 
     return success({ user, profile });
   });
 }
 ```
 
-- if a yielded step fails, `run(...)` returns that original failure unchanged
+- if a yielded step fails, that failure becomes the default unwind result
+- cleanup still runs, and the last explicit `return` reached in `finally` wins
+- yielded cleanup `Failure` values keep the current unwind result unless a
+  later cleanup `return` overrides it
 - sync hydrated `Failable` helpers can use direct `yield* helper()` in both sync
   and async builders
-- promised sources still use `yield* get(...)`; do not write `await get(...)`
+- promised sources in async builders use `yield* await promisedHelper()`
+- in async builders, use `yield* await all(...)` to run multiple sources in
+  parallel and get a success tuple or the first failure
+- use `yield* all(...)` in sync builders when every source is already a hydrated
+  `Failable`
+- use `await allSettled(...)` to inspect the settled tuple of sources that
+  resolve to `Failable`; source promise rejections still reject unchanged
+- use `yield* race(...)` when every raced source is already a hydrated
+  `Failable`
+- use `yield* await race(...)` when any raced source is promised
+- direct promised sources still follow normal async `await` / `try` /
+  `finally` semantics rather than a helper-managed rejection path
 - `run(...)` does not capture thrown values or rejected promises into `Failure`;
   wrap throwing boundaries with `failable(...)` before they enter `run(...)`
 
+## Parallel Combinators
+
+Import `all(...)`, `allSettled(...)`, and `race(...)` from the package root when
+you want to combine multiple sources outside `run(...)` or inside async
+builders.
+
+```ts
+import {
+  all,
+  allSettled,
+  failure,
+  race,
+  success,
+} from '@pvorona/failable';
+
+const syncTuple = all(success(1), success('two'));
+const mixedTuple = await all(
+  success(1),
+  Promise.resolve(success('two'))
+);
+
+const settled = await allSettled(
+  Promise.resolve(success(1)),
+  Promise.resolve(failure('missing-profile'))
+);
+
+const syncWinner = race(
+  success('cached'),
+  success('stale')
+);
+
+const mixedWinner = await race(
+  success('cached'),
+  Promise.resolve(success('network'))
+);
+```
+
+Key semantics:
+
+- `all(...)` returns the first failure in input order
+- `allSettled(...)` returns a plain settled tuple rather than a `Success` wrapper
+- `allSettled(...)` preserves `Failure` values in the returned settled tuple
+- `allSettled(...)` only settles sources that resolve to `Failable` values
+- promised source rejections in `allSettled(...)` still reject the combinator
+- wrap rejecting boundaries with `failable(...)` first if you want a rejection
+  converted into `Failure`
+- bare `Promise.reject(...)` inputs are rejected at type level as a best-effort
+  guardrail; TypeScript still cannot model arbitrary promise rejection channels
+  precisely
+- `race(...)` accepts sync or promised `Failable` sources
+- `race(...)` returns sync `Failable` when every source is sync, otherwise
+  `Promise<Failable>`
+- when `race(...)` mixes already-settled sync and promised sources, winner
+  order follows normal `Promise.race(...)` input ordering
+- `race()` with zero sources rejects with a clear error instead of hanging
+
 ## Transport And Runtime Validation
 
 `Failable` values are hydrated objects with methods. Keep them inside your
@@ -318,7 +501,7 @@ import {
   toFailableLike,
 } from '@pvorona/failable';
 
-const result = failure({ code: 'missing' as const });
+const result = failure({ code: 'missing' });
 
 const wire = toFailableLike(result);
 const hydrated = failable(wire);
@@ -348,14 +531,17 @@ if (isFailable(candidate) && candidate.isFailure) {
 - `type Success<T>` / `type Failure<E>`: hydrated result variants
 - `type FailableLike<T, E>`: structured-clone-friendly wire shape
 - `success()` / `success(data)` / `failure()` / `failure(error)`: create hydrated results
-- `throwIfError(result)` / `result.getOrThrow()`: throw the stored failure
-  unchanged
+- `throwIfFailure(result, normalizeOption?)` / `result.getOrThrow(normalizeOption?)`:
+  throw an `Error`, preserving existing `Error` instances unchanged by default
 - `failable(...)`: preserve, rehydrate, capture, or normalize failures at
   a boundary
 - `run(...)`: compose `Failable` steps without nested branching
+- `result.map(...)`: transform success data; failures pass through unchanged
+- `result.flatMap(...)`: chain another `Failable`; failures short-circuit
 - `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(...)`
+- `NormalizedErrors`: built-in `Error` normalization for `failable(...)` and
+  throw-boundary helpers
 - `FailableStatus`: runtime success/failure status values

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { FailableStatus, NormalizedErrors, failable, failure, isFailable, isFailableLike, isFailure, isSuccess, run, success, throwIfError, toFailableLike, } from './lib/failable.js';
+export { all, allSettled, FailableStatus, NormalizedErrors, failable, failure, isFailable, isFailableLike, isFailure, isSuccess, race, run, success, throwIfFailure, toFailableLike, } from './lib/failable.js';
 export type { FailableNormalizeErrorOptions, Failable, FailableLike, FailableLikeFailure, FailableLikeSuccess, Failure, Success, } from './lib/failable.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,OAAO,EACP,UAAU,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,GAAG,EACH,OAAO,EACP,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,6BAA6B,EAC7B,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,OAAO,EACP,OAAO,GACR,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EACH,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,OAAO,EACP,UAAU,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,IAAI,EACJ,GAAG,EACH,OAAO,EACP,cAAc,EACd,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,6BAA6B,EAC7B,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,OAAO,EACP,OAAO,GACR,MAAM,mBAAmB,CAAC"}