@pvorona/failable 0.6.2 → 0.6.3

package/README.md

@@ -8,7 +8,7 @@ input, missing config, not found, or a dependency call that can fail. Return a
 
 A `Failable<T, E>` is either `Success<T>` or `Failure<E>`.
 
-- `success(...)` / `failure()` / `failure(...)` create results
+- `success()` / `success(data)` / `failure()` / `failure(error)` create results
 - `failable(...)` captures thrown or rejected boundaries
 - `run(...)` composes multiple `Failable` steps
 
@@ -20,98 +20,45 @@ npm i @pvorona/failable
 
 This package is ESM-only and requires Node 18+.
 
-## Migration Note
-
-If you are upgrading from the previous API name:
-
-- `createFailable(x)` -> `failable(x)`
-- `CreateFailableNormalizeErrorOptions` -> `FailableNormalizeErrorOptions`
-- `result.isError` -> `result.isFailure`
-- `.error` is unchanged
-- `failure(...)`, `Failure<E>`, `throwIfError(...)`, and `getOrThrow()` are unchanged
-
 ## Basic Usage
 
-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:
+Return `success(...)` or `failure(...)`, then branch on `result.isFailure`.
+The typed error lets the caller decide what to do for each failure reason.
 
 ```ts
 import { failure, success, type Failable } from '@pvorona/failable';
 
-type TransferRequest = {
-  fromAccountId: string;
-  toAccountId: string;
-  amountCents: number;
-};
-
-type TransferPlan = TransferRequest & {
-  feeCents: number;
-};
-
-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' });
-  }
+type ReadPortError =
+  | { code: 'missing' }
+  | { code: 'invalid'; raw: string };
 
-  if (request.amountCents < 100) {
-    return failure({ code: 'amount_too_small', minAmountCents: 100 });
-  }
+function readPort(raw: string | undefined): Failable<number, ReadPortError> {
+  if (raw === undefined) return failure({ code: 'missing' });
 
-  if (balanceCents < request.amountCents) {
-    return failure({
-      code: 'insufficient_funds',
-      balanceCents,
-      attemptedCents: request.amountCents,
-    });
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    return failure({ code: 'invalid', raw });
   }
 
-  return success({ ...request, feeCents: 25 });
+  return success(port);
 }
 
-const result = planTransfer(
-  {
-    fromAccountId: 'checking',
-    toAccountId: 'savings',
-    amountCents: 10_000,
-  },
-  4_500,
-);
+const result = readPort(process.env.PORT);
 
 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`);
+    case 'missing':
+      console.error('PORT is not set');
       break;
-    case 'insufficient_funds':
-      console.error(
-        `Balance ${result.error.balanceCents} is below ${result.error.attemptedCents}`
-      );
+    case 'invalid':
+      console.error(`PORT is not a valid number: ${result.error.raw}`);
       break;
   }
 } else {
-  console.log(result.data.feeCents);
+  console.log(`Listening on ${result.data}`);
 }
 ```
 
-That is the default usage model for this package: return a typed result that
-carries both the success value and the expected failure reason.
-
 ## Choose The Right API
 
 | Need | Use |
@@ -129,7 +76,7 @@ carries both the success value and the expected failure reason.
 ## Unwrapping And Recovery
 
 Start with ordinary branching on `result.isFailure` or `result.isSuccess`. When
-you need a shorter form, use the helper that matches the job:
+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
@@ -141,81 +88,66 @@ you need a shorter form, use the helper that matches the job:
 
 Use the lazy forms when the fallback is expensive or has side effects.
 
-```ts
-import { failure, success, throwIfError } from '@pvorona/failable';
+Using `readPort` from above:
 
-const feeResult =
-  Math.random() > 0.5
-    ? success(25)
-    : failure({ code: 'pricing_unavailable' as const });
+```ts
+const result = readPort(process.env.PORT);
 
-const feeCents = feeResult.getOr(25);
-const status = feeResult.match(
-  (value) => `Fee is ${value} cents`,
-  ({ code }) => `Cannot quote fee: ${code}`
+const port = result.getOr(3000);
+const label = result.match(
+  (port) => `Listening on ${port}`,
+  (error) => `Using default port (${error.code})`
 );
-
-throwIfError(feeResult);
-console.log(feeCents, status, feeResult.data);
 ```
 
-## Capture Thrown Or Rejected Failures With `failable(...)`
+`throwIfError` narrows the result to `Success` in place, so
+subsequent code can access `.data` without branching:
 
-Use `failable(...)` at boundaries that throw or reject, then normalize
-that failure once at the boundary if needed:
+```ts
+import { throwIfError } from '@pvorona/failable';
 
-Using `TransferPlan` from above:
+const result = readPort(process.env.PORT);
 
-```ts
-import {
-  failable,
-  run,
-  success,
-  type Failable,
-} from '@pvorona/failable';
+throwIfError(result);
+console.log(result.data * 2);
+```
 
-type SubmitTransferError = Error;
+## Capture Thrown Or Rejected Failures With `failable(...)`
 
-async function postToLedger(
-  plan: TransferPlan,
-): Promise<Failable<{ transferId: string }, SubmitTransferError>> {
-  const request = (async () => {
-    if (plan.amountCents > 5_000) {
-      throw { code: 'ledger_unavailable' } as const;
-    }
+Use `failable(...)` at a boundary you do not control. It turns a thrown or
+rejected value into `Failure`, so the rest of your code can stay in normal
+`Failable` flow.
 
-    return { transferId: 'tr_123' };
-  })();
+Use the callback form for synchronous code that can throw:
 
-  return await failable(request, {
-    normalizeError(error) {
-      return new Error('Ledger unavailable', { cause: error });
-    },
-  });
-}
+```ts
+import { failable, NormalizedErrors } from '@pvorona/failable';
 
-async function submitTransfer(
-  plan: TransferPlan,
-): Promise<Failable<{ transferId: string }, SubmitTransferError>> {
-  return await run(async function* ({ get }) {
-    const created = yield* get(postToLedger(plan));
+const rawConfig = '{"theme":"dark"}';
+const configResult = failable(() => JSON.parse(rawConfig), NormalizedErrors);
 
-    return success(created);
-  });
+if (configResult.isFailure) {
+  console.error(configResult.error.message);
+} else {
+  console.log(configResult.data);
 }
 ```
 
-`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.
+`NormalizedErrors` is the built-in shortcut when you want `.error` to be an
+`Error`.
 
 Pass a promise directly when you want rejection capture:
 
 ```ts
-const responseResult = await failable(fetch(url));
+import { failable, NormalizedErrors } from '@pvorona/failable';
+import { readFile } from 'node:fs/promises';
+
+const fileResult = await failable(
+  readFile('config.json', 'utf8'),
+  NormalizedErrors
+);
+
+const config = fileResult.getOr('{}');
 ```
 
 `failable(...)` can:
@@ -235,174 +167,76 @@ you 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:
+the success path once. If any yielded step fails, `run(...)` returns that same
+failure unchanged.
 
-Without `run(...)`, composition often becomes an error ladder:
+Without `run(...)`, composing steps means checking each result before
+continuing:
 
 ```ts
 import { failure, success, type Failable } from '@pvorona/failable';
 
-type Account = {
-  id: string;
-  balanceCents: number;
-};
-
-type TransferPlanningError =
-  | TransferError
-  | { code: 'source_account_not_found'; accountId: string }
-  | { code: 'destination_account_not_found'; accountId: string };
-
-function readSourceAccount(
-  accountId: string,
-): Failable<Account, TransferPlanningError> {
-  if (accountId !== 'checking') {
-    return failure({ code: 'source_account_not_found', accountId });
-  }
+type ConfigError =
+  | { code: 'missing'; key: string }
+  | { code: 'invalid'; key: string; raw: string };
 
-  return success({ id: 'checking', balanceCents: 5_000 });
-}
+function readEnv(
+  key: string,
+  env: Record<string, string | undefined>,
+): Failable<string, ConfigError> {
+  const raw = env[key];
+  if (raw === undefined) return failure({ code: 'missing', key });
 
-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 });
+  return success(raw);
 }
 
-
-function ensureSufficientFunds(
-  source: Account,
-  amountCents: number,
-): Failable<Account, TransferPlanningError> {
-  if (source.balanceCents < amountCents) {
-    return failure({
-      code: 'insufficient_funds',
-      balanceCents: source.balanceCents,
-      attemptedCents: amountCents,
-    });
+function parsePort(raw: string): Failable<number, ConfigError> {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    return failure({ code: 'invalid', key: 'PORT', raw });
   }
 
-  return success(source);
+  return success(port);
 }
 
-function planTransfer(
-  { fromAccountId, toAccountId, amountCents }: TransferRequest,
-): Failable<TransferPlan, TransferPlanningError> {
-  const source = readSourceAccount(fromAccountId);
+function loadConfig(
+  env: Record<string, string | undefined>,
+): Failable<{ host: string; port: number }, ConfigError> {
+  const hostResult = readEnv('HOST', env);
+  if (hostResult.isFailure) return hostResult;
 
-  if (source.isFailure) {
-    return source;
-  }
-
-  if (source.balanceCents < amountCents) {
-    return failure({
-      code: 'insufficient_funds',
-      balanceCents: source.balanceCents,
-      attemptedCents: amountCents,
-    });
-  }
+  const rawPortResult = readEnv('PORT', env);
+  if (rawPortResult.isFailure) return rawPortResult;
 
-  const destination = readDestinationAccount(toAccountId);
+  const portResult = parsePort(rawPortResult.data);
+  if (portResult.isFailure) return portResult;
 
-  if (destination.isFailure) {
-    return destination;
-  }
-
-  if (source.id === destination.id) {
-    return failure({ code: 'same_account' });
-  }
-
-  return success({ fromAccountId, toAccountId, amountCents, feeCents: 25 });
+  return success({ host: hostResult.data, port: portResult.data });
 }
 ```
 
-With the same helpers, `run(...)` keeps the flow linear:
+With `run(...)`, the same flow stays linear:
 
 ```ts
-import { failure, run, success, type Failable } from '@pvorona/failable';
+import { run, success, type Failable } from '@pvorona/failable';
 
-function planTransfer(
-  { fromAccountId, toAccountId, amountCents }: TransferRequest,
-): Failable<TransferPlan, TransferPlanningError> {
+function loadConfig(
+  env: Record<string, string | undefined>,
+): Failable<{ host: string; port: number }, ConfigError> {
   return run(function* ({ get }) {
-    const source = yield* get(readSourceAccount(fromAccountId));
-
-    if (source.balanceCents < amountCents) {
-      return failure({
-        code: 'insufficient_funds',
-        balanceCents: source.balanceCents,
-        attemptedCents: amountCents,
-      });
-    }
-
-    const destination = yield* get(readDestinationAccount(toAccountId));
-
-    if (source.id === destination.id) {
-      return failure({ code: 'same_account' });
-    }
-
-    return success({ fromAccountId, toAccountId, amountCents, feeCents: 25 });
-  });
-}
-```
-
-With one async rule added, the shape stays the same:
+    const host = yield* get(readEnv('HOST', env));
+    const rawPort = yield* get(readEnv('PORT', env));
+    const port = yield* get(parsePort(rawPort));
 
-```ts
-import { failure, run, success, type Failable } from '@pvorona/failable';
-
-type TransferAsyncError =
-  | TransferPlanningError
-  | { code: 'daily_limit_exceeded'; remainingCents: number };
-
-async function planTransfer(
-  { fromAccountId, toAccountId, amountCents }: TransferRequest,
-): Promise<Failable<TransferPlan, TransferAsyncError>> {
-  return await run(async function* ({ get }) {
-    const source = yield* get(readSourceAccount(fromAccountId));
-
-    if (source.balanceCents < amountCents) {
-      return failure({
-        code: 'insufficient_funds',
-        balanceCents: source.balanceCents,
-        attemptedCents: amountCents,
-      });
-    }
-
-    const destination = yield* get(readDestinationAccount(toAccountId));
-
-    if (source.id === destination.id) {
-      return failure({ code: 'same_account' });
-    }
-
-    // Simulate an async step that can fail
-    yield* get(
-      (async () => {
-        const remainingCents = source.id === 'checking' ? 3_000 : 0;
-        if (amountCents > remainingCents) {
-          return failure({ code: 'daily_limit_exceeded', remainingCents });
-        }
-
-        return success();
-      })()
-    );
-
-    return success({ fromAccountId, toAccountId, amountCents, feeCents: 25 });
+    return success({ host, port });
   });
 }
 ```
 
-Keep these rules in mind:
-
-- `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(...)`
+- `run(...)` does not capture thrown values or rejected promises into `Failure`;
+  wrap throwing boundaries with `failable(...)` before they enter `run(...)`
 
 ## Transport And Runtime Validation
 
@@ -413,18 +247,12 @@ side:
 
 ```ts
 import {
+  failure,
   failable,
   toFailableLike,
 } from '@pvorona/failable';
 
-const result = planTransfer(
-  {
-    fromAccountId: 'checking',
-    toAccountId: 'savings',
-    amountCents: 2_500,
-  },
-  5_000,
-);
+const result = failure({ code: 'missing' as const });
 
 const wire = toFailableLike(result);
 const hydrated = failable(wire);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pvorona/failable",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Typed success/failure results for expected failures in TypeScript.",
   "keywords": [
     "failable",