@resultsafe/core-fp-result 0.1.9 → 0.2.0

package/README.md

@@ -1,8 +1,17 @@
 # @resultsafe/core-fp-result
+
 <a id="top"></a>
 
 ![ResultSafe Logo](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/docs/assets/logo.svg)
 
+## 🤖 AI Context
+
+This package implements the `Result<T, E>` pattern for explicit error handling without `try/catch`.
+
+- **Rust analogue:** `std::result::Result`
+- **Scala analogue:** `Either`
+- **Core principle:** Error is a value, not an exception.
+
 [![npm version](https://img.shields.io/npm/v/@resultsafe/core-fp-result.svg)](https://www.npmjs.com/package/@resultsafe/core-fp-result)
 [![npm downloads](https://img.shields.io/npm/dm/@resultsafe/core-fp-result.svg)](https://www.npmjs.com/package/@resultsafe/core-fp-result)
 [![license](https://img.shields.io/npm/l/@resultsafe/core-fp-result.svg)](./LICENSE)
@@ -18,6 +27,7 @@ A Rust-inspired Result package for explicit, composable, and type-friendly APIs
 **Documentation:** [API index](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/README.md) · [Modules](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/modules.md)
 
 ---
+
 ## Contents
 
 - [Why this package](#why-this-package)
@@ -113,11 +123,7 @@ pnpm install
 A typical Result flow starts with explicit constructors and then composes through functions rather than implicit exception paths.
 
 ```ts
-import {
-  Ok,
-  map,
-  unwrapOr,
-} from "@resultsafe/core-fp-result";
+import { Ok, map, unwrapOr } from '@resultsafe/core-fp-result';
 
 const initial = Ok(21);
 const doubled = map(initial, (value) => value * 2);
@@ -129,111 +135,118 @@ console.log(finalValue); // 42
 ### Basic `Ok` / `Err` example
 
 ```ts
-import { Ok, Err, match } from "@resultsafe/core-fp-result";
+import { Ok, Err, match } from '@resultsafe/core-fp-result';
 
 const parsePort = (input: string) => {
   const port = Number(input);
-  return Number.isInteger(port) && port > 0
-    ? Ok(port)
-    : Err("Invalid port");
+  return Number.isInteger(port) && port > 0 ? Ok(port) : Err('Invalid port');
 };
 
-const result = parsePort("3000");
-const message = match(result, (value) => `Port: ${value}`, (error) => `Error: ${error}`);
+const result = parsePort('3000');
+const message = match(
+  result,
+  (value) => `Port: ${value}`,
+  (error) => `Error: ${error}`,
+);
 
 console.log(message);
 ```
 
 ---
 
-<!-- AI-AGENT: Each function has 3 links: Source (GitHub UI), Raw (direct code), Code (new UI) -->
-<!-- Raw links are best for automated code analysis and parsing -->
-
-## Core API overview
-
-### Core Types
-
-- [`Result<T, E>`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Result.ts) — Success/failure container [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Result.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/core/Result.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/core/Result.ts "Open in Code view")
-- [`Option<T>`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Option.ts) — Optional value container [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Option.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/core/Option.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/core/Option.ts "Open in Code view")
-
-### Type Helpers
-
-- [`VariantConfig`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts) — Variant configuration [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts "Open in Code view")
-- [`PayloadKeys<T>`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/PayloadKeys.ts) — Extract payload keys [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/PayloadKeys.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/PayloadKeys.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/refiners/PayloadKeys.ts "Open in Code view")
-- [`ValidatorFn<T>`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts) — Sync validator function [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts "Open in Code view")
-- [`AsyncValidatorFn`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts) — Async validator function [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts "Open in Code view")
+## API Reference
+
+### Core Functions
+
+| Function    | Signature                     | Description                         | GitHub                                                                                                 | Raw                                                                                                              |
+| ----------- | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `Ok`        | `(value: T) => Result<T, E>`  | Success constructor                 | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Ok.ts)   | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/constructors/Ok.ts)   |
+| `Err`       | `(error: E) => Result<T, E>`  | Error constructor                   | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Err.ts)  | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/constructors/Err.ts)  |
+| `match`     | `(r, onOk, onErr) => U`       | Branch on result                    | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/match.ts)     | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/match.ts)     |
+| `andThen`   | `(r, fn) => Result<U, E>`     | Chain (flatMap)                     | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/andThen.ts)   | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/andThen.ts)   |
+| `map`       | `(r, fn) => Result<U, E>`     | Transform success value             | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/map.ts)       | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/map.ts)       |
+| `mapErr`    | `(r, fn) => Result<T, U>`     | Transform error value               | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/mapErr.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/mapErr.ts)    |
+| `orElse`    | `(r, fn) => Result<T, U>`     | Recover from error                  | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/orElse.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/orElse.ts)    |
+| `unwrap`    | `(r) => T`                    | Extract value or throw              | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrap.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrap.ts)    |
+| `unwrapOr`  | `(r, fallback: T) => T`       | Extract value or default            | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapOr.ts)  | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrapOr.ts)  |
+| `expect`    | `(r, msg: string) => T`       | Extract value or throw with message | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/expect.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/expect.ts)    |
+| `isOk`      | `(r) => boolean`              | Check if success                    | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isOk.ts)       | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isOk.ts)       |
+| `isErr`     | `(r) => boolean`              | Check if error                      | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isErr.ts)      | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isErr.ts)      |
+| `tap`       | `(r, fn) => Result<T, E>`     | Side effect on success              | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tap.ts)       | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/tap.ts)       |
+| `tapErr`    | `(r, fn) => Result<T, E>`     | Side effect on error                | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tapErr.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/tapErr.ts)    |
+| `transpose` | `(r) => Option<Result<T, E>>` | Result<Option> to Option<Result>    | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/transpose.ts) | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/transpose.ts) |
+| `flatten`   | `(r) => Result<T, E>`         | Flatten nested Result               | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/flatten.ts)   | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/flatten.ts)   |
+
+### Advanced: Refiners
+
+| Function             | Description                 | GitHub                                                                                                           | Raw                                                                                                                        |
+| -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `isTypedVariant`     | Type guard for variant      | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/isTypedVariant.ts)     | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/isTypedVariant.ts)     |
+| `matchVariant`       | Match variant with handlers | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariant.ts)       | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/matchVariant.ts)       |
+| `matchVariantStrict` | Strict variant matching     | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts) | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts) |
+| `refineResult`       | Sync result refinement      | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineResult.ts)       | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineResult.ts)       |
+| `refineAsyncResult`  | Async result refinement     | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts)  | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts)  |
+
+### Type Aliases
+
+| Type               | Description                   | GitHub                                                                                                               | Raw                                                                                                                            |
+| ------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `Result<T, E>`     | Base success/error type       | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Result.ts)               | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/core/Result.ts)               |
+| `Option<T>`        | Optional value type           | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/core/Option.ts)               | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/core/Option.ts)               |
+| `VariantConfig`    | Variant configuration type    | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts)    | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/VariantConfig.ts)    |
+| `ValidatorFn<T>`   | Sync validator function type  | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts)      | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/ValidatorFn.ts)      |
+| `AsyncValidatorFn` | Async validator function type | [🔗](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts) | [📄](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/types/refiners/AsyncValidatorFn.ts) |
+
+> **Full API:** [All modules](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/modules.md) · [Constructors](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/constructors/index.md) · [Guards](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/guards/index.md) · [Methods](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/methods/index.md) · [Refiners](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/refiners/index.md)
 
-### Constructors
-
-- [`Ok`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Ok.ts) — Create success result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Ok.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/constructors/Ok.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/constructors/Ok.ts "Open in Code view")
-- [`Err`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Err.ts) — Create error result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/constructors/Err.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/constructors/Err.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/constructors/Err.ts "Open in Code view")
-
-### Guards
-
-- [`isOk`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isOk.ts) — Check if success [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isOk.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isOk.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/guards/isOk.ts "Open in Code view")
-- [`isErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isErr.ts) — Check if error [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/guards/isErr.ts "Open in Code view")
-- [`isOkAnd`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isOkAnd.ts) — Check success with predicate [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isOkAnd.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isOkAnd.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/guards/isOkAnd.ts "Open in Code view")
-- [`isErrAnd`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isErrAnd.ts) — Check error with predicate [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/guards/isErrAnd.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/guards/isErrAnd.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/guards/isErrAnd.ts "Open in Code view")
+---
 
-### Methods
+## Examples
 
-#### Transformation
+### Example 1: Basic Usage
 
-- [`map`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/map.ts) — Transform success value [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/map.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/map.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/map.ts "Open in Code view")
-- [`mapErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/mapErr.ts) — Transform error value [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/mapErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/mapErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/mapErr.ts "Open in Code view")
+```typescript
+import { Ok, Err, match } from '@resultsafe/core-fp-result';
 
-#### Chaining
+const result = Ok(42);
+match(
+  result,
+  (value) => console.log(value),
+  (error) => console.error(error),
+);
+```
 
-- [`andThen`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/andThen.ts) — Chain computations returning Result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/andThen.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/andThen.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/andThen.ts "Open in Code view")
-- [`orElse`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/orElse.ts) — Recover from error [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/orElse.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/orElse.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/orElse.ts "Open in Code view")
+### Example 2: Error Handling
 
-#### Extraction
+```typescript
+import { Ok, Err } from '@resultsafe/core-fp-result';
 
-- [`unwrap`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrap.ts) — Extract value or throw [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrap.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrap.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/unwrap.ts "Open in Code view")
-- [`unwrapOr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapOr.ts) — Extract value or default [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapOr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrapOr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/unwrapOr.ts "Open in Code view")
-- [`unwrapOrElse`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapOrElse.ts) — Extract value or compute default [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapOrElse.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrapOrElse.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/unwrapOrElse.ts "Open in Code view")
-- [`unwrapErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapErr.ts) — Extract error or throw [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/unwrapErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/unwrapErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/unwrapErr.ts "Open in Code view")
-- [`expect`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/expect.ts) — Extract value or throw with message [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/expect.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/expect.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/expect.ts "Open in Code view")
-- [`expectErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/expectErr.ts) — Extract error or throw with message [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/expectErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/expectErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/expectErr.ts "Open in Code view")
+const divide = (a: number, b: number) =>
+  b === 0 ? Err('Division by zero') : Ok(a / b);
 
-#### Side Effects
+const result = divide(10, 0);
+// Err("Division by zero")
+```
 
-- [`tap`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tap.ts) — Side effect on success [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tap.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/tap.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/tap.ts "Open in Code view")
-- [`tapErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tapErr.ts) — Side effect on error [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/tapErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/tapErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/tapErr.ts "Open in Code view")
-- [`inspect`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/inspect.ts) — Debug on success [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/inspect.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/inspect.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/inspect.ts "Open in Code view")
-- [`inspectErr`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/inspectErr.ts) — Debug on error [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/inspectErr.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/inspectErr.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/inspectErr.ts "Open in Code view")
+### Example 3: Chaining Operations
 
-#### Advanced
+```typescript
+import { Ok, andThen, map } from '@resultsafe/core-fp-result';
 
-- [`match`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/match.ts) — Pattern matching [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/match.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/match.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/match.ts "Open in Code view")
-- [`flatten`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/flatten.ts) — Flatten nested Result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/flatten.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/flatten.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/flatten.ts "Open in Code view")
-- [`transpose`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/transpose.ts) — Result<Option> → Option<Result> [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/transpose.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/transpose.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/transpose.ts "Open in Code view")
-- [`ok`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/ok.ts) — Convert to Option (success) [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/ok.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/ok.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/ok.ts "Open in Code view")
-- [`err`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/err.ts) — Convert to Option (error) [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/methods/err.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/methods/err.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/methods/err.ts "Open in Code view")
+const result = Ok(5);
+const doubled = andThen(result, (x) => Ok(x * 2));
+const squared = map(doubled, (x) => x ** 2);
+```
 
-### Refiners
+---
 
-- [`isTypedVariant`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/isTypedVariant.ts) — Type guard for variant [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/isTypedVariant.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/isTypedVariant.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/isTypedVariant.ts "Open in Code view")
-- [`isTypedVariantOf`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/isTypedVariantOf.ts) — Type guard with variant map [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/isTypedVariantOf.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/isTypedVariantOf.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/isTypedVariantOf.ts "Open in Code view")
-- [`matchVariant`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariant.ts) — Match variant with handlers [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariant.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/matchVariant.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/matchVariant.ts "Open in Code view")
-- [`matchVariantStrict`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts) — Strict variant matching [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/matchVariantStrict.ts "Open in Code view")
-- [`refineAsyncResult`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts) — Async result refinement [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/refineAsyncResult.ts "Open in Code view")
-- [`refineAsyncResultU`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineAsyncResultU.ts) — Async refinement (uncurried) [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineAsyncResultU.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineAsyncResultU.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/refineAsyncResultU.ts "Open in Code view")
-- [`refineResult`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineResult.ts) — Synchronous result refinement [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineResult.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineResult.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/refineResult.ts "Open in Code view")
-- [`refineResultU`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineResultU.ts) — Synchronous refinement (uncurried) [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineResultU.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineResultU.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/refineResultU.ts "Open in Code view")
-- [`refineVariantMap`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineVariantMap.ts) — Refine variant map [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/refineVariantMap.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/refineVariantMap.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/refineVariantMap.ts "Open in Code view")
+## Ecosystem
 
-### Type aliases
+- `@resultsafe/core-fp-option` — Option/Maybe type
+- `@resultsafe/core-fp-either` — Either type
+- `@resultsafe/core-fp-result` — This package (Result type)
 
-- [`Handler`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/Handler.ts) — Match handler type [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/Handler.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/Handler.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/Handler.ts "Open in Code view")
-- [`MatchBuilder`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/MatchBuilder.ts) — Match builder type [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/MatchBuilder.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/MatchBuilder.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/MatchBuilder.ts "Open in Code view")
-- [`Matcher`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/Matcher.ts) — Matcher function type [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/Matcher.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/Matcher.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/Matcher.ts "Open in Code view")
-- [`SyncRefinedResult`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncRefinedResult.ts) — Synchronous refined result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncRefinedResult.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/SyncRefinedResult.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/SyncRefinedResult.ts "Open in Code view")
-- [`SyncRefinedResultUnion`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncRefinedResultUnion.ts) — Union of refined results [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncRefinedResultUnion.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/SyncRefinedResultUnion.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/SyncRefinedResultUnion.ts "Open in Code view")
-- [`SyncValidatorMap`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncValidatorMap.ts) — Validator map type [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/SyncValidatorMap.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/SyncValidatorMap.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/SyncValidatorMap.ts "Open in Code view")
-- [`UniversalAsyncRefinedResult`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/UniversalAsyncRefinedResult.ts) — Async refined result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/UniversalAsyncRefinedResult.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/UniversalAsyncRefinedResult.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/UniversalAsyncRefinedResult.ts "Open in Code view")
-- [`UniversalRefinedResult`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/UniversalRefinedResult.ts) — Universal refined result [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/UniversalRefinedResult.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/UniversalRefinedResult.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/UniversalRefinedResult.ts "Open in Code view")
-- [`VariantOf`](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/VariantOf.ts) — Variant type helper [📄](https://github.com/Livooon/resultsafe/blob/main/packages/core/fp/result/src/refiners/types/VariantOf.ts "View on GitHub") · [🔗](https://raw.githubusercontent.com/Livooon/resultsafe/main/packages/core/fp/result/src/refiners/types/VariantOf.ts "View raw code") · [💻](https://github.com/Livooon/resultsafe/code/main/packages/core/fp/result/src/refiners/types/VariantOf.ts "Open in Code view")
+All packages follow the same API design pattern.
 
 ---
 
@@ -288,9 +301,11 @@ Use this project when you want:
 - [Type aliases module](https://unpkg.com/@resultsafe/core-fp-result@latest/docs/api/type-aliases/index.md)
 
 ---
+
 Back to top: [@resultsafe/core-fp-result](#top)
 
 ---
+
 ## Author
 
 Denis Savasteev