@resultsafe/core-fp-result 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 resultsafe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# @resultsafe/core-fp-result
+<a id="top"></a>
+
+![ResultSafe Logo](https://raw.githubusercontent.com/resultsafe/monorepo/main/packages/core/fp/result/docs/assets/logo.svg)
+
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)
+[![docs](https://img.shields.io/badge/docs-api-informational.svg)](./docs/api/README.md)
+[![build status](https://img.shields.io/badge/build-local%20verified-success.svg)](./package.json)
+[![monorepo](https://img.shields.io/badge/monorepo-resultsafe%2Fmonorepo-0A0A0A.svg)](https://github.com/resultsafe/monorepo)
+
+A Rust-inspired Result package for explicit, composable, and type-friendly APIs in TypeScript and JavaScript.
+
+**Language:** English | [Русский](./README.ru.md)
+
+**Documentation:** [API index](./docs/api/README.md) · [Modules](./docs/api/modules.md)
+
+---
+## Contents
+
+- [Why this package](#why-this-package)
+- [Monorepo context](#monorepo-context)
+- [Key features](#key-features)
+- [Package](#package)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Core API overview](#core-api-overview)
+- [Build and distribution formats](#build-and-distribution-formats)
+- [Monorepo and package structure](#monorepo-and-package-structure)
+- [When to use this project](#when-to-use-this-project)
+- [Documentation links](#documentation-links)
+- [License](#license)
+
+---
+
+## Why this package
+
+`@resultsafe/core-fp-result` provides explicit success/error flows instead of hidden control paths and exception-first branching.
+
+Its core package, [`@resultsafe/core-fp-result`](https://www.npmjs.com/package/@resultsafe/core-fp-result), provides a Rust-inspired `Result` API for TypeScript and JavaScript with:
+
+- explicit `Ok` / `Err`
+- predictable functional composition
+- safe branching through guards and matching
+- disciplined extraction APIs
+- advanced refinement utilities for typed variants and strict matching
+
+The goal is not to imitate Rust mechanically, but to bring the same clarity of intent to Node.js libraries: explicit values, predictable branching, and APIs organized for long-term maintenance.
+
+---
+
+## Monorepo context
+
+`@resultsafe/core-fp-result` is the TypeScript/JavaScript package inside the multilingual `resultsafe/monorepo`.
+
+The monorepo applies shared Rust-inspired design concepts across language-specific packages. TypeScript/JavaScript is the current production package track, while Python is planned as a separate package track with the same conceptual model.
+
+---
+
+## Key features
+
+- Rust-inspired `Result` model for TypeScript and JavaScript.
+- Explicit constructors via `Ok` and `Err`.
+- Composable transformations with APIs such as `map`, `mapErr`, `andThen`, and `orElse`.
+- Safe branching through guards like `isOk`, `isErr`, `isOkAnd`, `isErrAnd`, and matching helpers.
+- Controlled extraction with `unwrap`, `unwrapOr`, `unwrapErr`, `expect`, and `expectErr`.
+- Advanced refinement layer for typed variants, strict matching, and result narrowing.
+- Coherent module structure instead of a flat utility dump.
+- Type output for TypeScript users for better DX and safer integrations.
+- Flexible distribution formats with Types, ESM, CJS, and UMD builds.
+
+---
+
+## Package
+
+### `@resultsafe/core-fp-result`
+
+A focused Result library for explicit error handling and FP-style composition.
+
+It is designed for developers who want:
+
+- clear success/error modeling
+- predictable transformations
+- explicit branching and extraction
+- better readability in error-heavy flows
+- a structured Rust-inspired API surface in TypeScript/JavaScript
+
+---
+
+## Installation
+
+### Package
+
+```bash
+pnpm add @resultsafe/core-fp-result
+
+# Alternative
+npm install @resultsafe/core-fp-result
+```
+
+### Monorepo
+
+```bash
+pnpm install
+```
+
+---
+
+## Quick start
+
+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";
+
+const initial = Ok(21);
+const doubled = map(initial, (value) => value * 2);
+const finalValue = unwrapOr(doubled, 0);
+
+console.log(finalValue); // 42
+```
+
+### Basic `Ok` / `Err` example
+
+```ts
+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");
+};
+
+const result = parsePort("3000");
+const message = match(result, (value) => `Port: ${value}`, (error) => `Error: ${error}`);
+
+console.log(message);
+```
+
+---
+
+## Core API overview
+
+### Constructors
+
+- `Ok`
+- `Err`
+
+### Guards
+
+- `isOk`
+- `isOkAnd`
+- `isErr`
+- `isErrAnd`
+
+### Methods
+
+- `andThen`
+- `err`
+- `expect`
+- `expectErr`
+- `flatten`
+- `inspect`
+- `inspectErr`
+- `map`
+- `mapErr`
+- `match`
+- `ok`
+- `orElse`
+- `tap`
+- `tapErr`
+- `transpose`
+- `unwrap`
+- `unwrapErr`
+- `unwrapOr`
+- `unwrapOrElse`
+
+### Refiners
+
+- `isTypedVariant`
+- `isTypedVariantOf`
+- `matchVariant`
+- `matchVariantStrict`
+- `refineAsyncResult`
+- `refineAsyncResultU`
+- `refineResult`
+- `refineResultU`
+- `refineVariantMap`
+
+### Type aliases
+
+- `Handler`
+- `MatchBuilder`
+- `Matcher`
+- `SyncRefinedResult`
+- `SyncRefinedResultUnion`
+- `SyncValidatorMap`
+- `UniversalAsyncRefinedResult`
+- `UniversalRefinedResult`
+- `VariantOf`
+
+---
+
+## Build and distribution formats
+
+- Types: `build:types`
+- ESM: `build:esm`
+- CJS: `build:cjs`
+- UMD: `build:umd`
+
+This package ships typed declarations and multiple runtime module formats for broad compatibility.
+
+---
+
+## Monorepo and package structure
+
+```txt
+src/
+  constructors/
+  guards/
+  methods/
+  refiners/
+    types/
+    utils/
+  internal/
+  index.ts
+```
+
+---
+
+## When to use this project
+
+Use this project when you want:
+
+- explicit success/error modeling
+- predictable FP-style composition
+- visible control flow
+- stronger type-guided result handling in TypeScript
+- advanced refinement tools for typed variants and strict result matching
+
+---
+
+## Documentation links
+
+- [API entry (README)](./docs/api/README.md)
+- [API entry (index)](./docs/api/index.md)
+- [Modules](./docs/api/modules.md)
+- [Constructors module](./docs/api/constructors/index.md)
+- [Guards module](./docs/api/guards/index.md)
+- [Methods module](./docs/api/methods/index.md)
+- [Refiners module](./docs/api/refiners/index.md)
+- [Type aliases module](./docs/api/type-aliases/index.md)
+
+---
+Back to top: [@resultsafe/core-fp-result](#top)
+
+---
+## Author
+
+Denis Savasteev
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/README.ru.md

@@ -0,0 +1,266 @@
+# @resultsafe/core-fp-result
+<a id="top"></a>
+
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)
+[![docs](https://img.shields.io/badge/docs-api-informational.svg)](./docs/api/README.md)
+[![build status](https://img.shields.io/badge/build-local%20verified-success.svg)](./package.json)
+[![monorepo](https://img.shields.io/badge/monorepo-resultsafe%2Fmonorepo-0A0A0A.svg)](https://github.com/resultsafe/monorepo)
+
+Rust-inspired Result-пакет для явных, композиционных и типобезопасных API в TypeScript и JavaScript.
+
+**Язык:** [English](./README.md) | Русский
+
+**Документация:** [API index](./docs/api/README.md) · [Modules](./docs/api/modules.md)
+
+---
+## Содержание
+
+- [Зачем нужен этот пакет](#зачем-нужен-этот-пакет)
+- [Контекст monorepo](#контекст-monorepo)
+- [Ключевые возможности](#ключевые-возможности)
+- [Пакет](#пакет)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Обзор основного API](#обзор-основного-api)
+- [Форматы сборки и поставки](#форматы-сборки-и-поставки)
+- [Структура monorepo и пакета](#структура-monorepo-и-пакета)
+- [Когда использовать этот проект](#когда-использовать-этот-проект)
+- [Ссылки на документацию](#ссылки-на-документацию)
+- [License](#license)
+
+---
+
+## Зачем нужен этот пакет
+
+`@resultsafe/core-fp-result` предоставляет явные success/error flow вместо скрытых путей управления и exception-first ветвления.
+
+Его основной пакет, [`@resultsafe/core-fp-result`](https://www.npmjs.com/package/@resultsafe/core-fp-result), предоставляет Rust-inspired `Result` API для TypeScript и JavaScript со следующими свойствами:
+
+- явные `Ok` / `Err`
+- предсказуемая функциональная композиция
+- безопасное ветвление через guards и matching
+- дисциплинированные API извлечения значений
+- продвинутые refinement utilities для typed variants и strict matching
+
+Цель проекта не в механическом копировании Rust, а в переносе той же ясности намерений в Node.js-библиотеки: явные значения, предсказуемое ветвление и API, организованные для долгосрочного сопровождения.
+
+---
+
+## Контекст monorepo
+
+`@resultsafe/core-fp-result` — это пакет TypeScript/JavaScript внутри мультиязычного `resultsafe/monorepo`.
+
+Монорепозиторий переносит общие Rust-inspired концепции в отдельные language-specific пакеты. Текущий production-трек — TypeScript/JavaScript, а Python планируется как отдельный пакетный трек с той же концептуальной моделью.
+
+---
+
+## Ключевые возможности
+
+- Rust-inspired модель `Result` для TypeScript и JavaScript.
+- Явные конструкторы через `Ok` и `Err`.
+- Композиционные трансформации через API, такие как `map`, `mapErr`, `andThen` и `orElse`.
+- Безопасное ветвление через guards `isOk`, `isErr`, `isOkAnd`, `isErrAnd` и matching helpers.
+- Контролируемое извлечение через `unwrap`, `unwrapOr`, `unwrapErr`, `expect` и `expectErr`.
+- Продвинутый слой refiners для typed variants, strict matching и сужения результатов.
+- Согласованная модульная структура вместо плоского набора утилит.
+- Type output для TypeScript-пользователей для лучшего DX и более безопасных интеграций.
+- Гибкие форматы поставки: Types, ESM, CJS и UMD.
+
+---
+
+## Пакет
+
+### `@resultsafe/core-fp-result`
+
+Фокусированная Result-библиотека для явной обработки ошибок и FP-style композиции.
+
+Она рассчитана на разработчиков, которым нужны:
+
+- ясное моделирование успеха/ошибки
+- предсказуемые трансформации
+- явное ветвление и извлечение значений
+- лучшая читаемость в error-heavy flow
+- структурированная Rust-inspired API surface в TypeScript/JavaScript
+
+---
+
+## Установка
+
+### Пакет
+
+```bash
+pnpm add @resultsafe/core-fp-result
+
+# Альтернатива
+npm install @resultsafe/core-fp-result
+```
+
+### Monorepo
+
+```bash
+pnpm install
+```
+
+---
+
+## Быстрый старт
+
+Типичный Result flow начинается с явных конструкторов и затем компонуется через функции, а не через неявные пути исключений.
+
+```ts
+import {
+  Ok,
+  map,
+  unwrapOr,
+} from "@resultsafe/core-fp-result";
+
+const initial = Ok(21);
+const doubled = map(initial, (value) => value * 2);
+const finalValue = unwrapOr(doubled, 0);
+
+console.log(finalValue); // 42
+```
+
+### Базовый пример `Ok` / `Err`
+
+```ts
+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");
+};
+
+const result = parsePort("3000");
+const message = match(result, (value) => `Port: ${value}`, (error) => `Error: ${error}`);
+
+console.log(message);
+```
+
+---
+
+## Обзор основного API
+
+### Constructors
+
+- `Ok`
+- `Err`
+
+### Guards
+
+- `isOk`
+- `isOkAnd`
+- `isErr`
+- `isErrAnd`
+
+### Methods
+
+- `andThen`
+- `err`
+- `expect`
+- `expectErr`
+- `flatten`
+- `inspect`
+- `inspectErr`
+- `map`
+- `mapErr`
+- `match`
+- `ok`
+- `orElse`
+- `tap`
+- `tapErr`
+- `transpose`
+- `unwrap`
+- `unwrapErr`
+- `unwrapOr`
+- `unwrapOrElse`
+
+### Refiners
+
+- `isTypedVariant`
+- `isTypedVariantOf`
+- `matchVariant`
+- `matchVariantStrict`
+- `refineAsyncResult`
+- `refineAsyncResultU`
+- `refineResult`
+- `refineResultU`
+- `refineVariantMap`
+
+### Type aliases
+
+- `Handler`
+- `MatchBuilder`
+- `Matcher`
+- `SyncRefinedResult`
+- `SyncRefinedResultUnion`
+- `SyncValidatorMap`
+- `UniversalAsyncRefinedResult`
+- `UniversalRefinedResult`
+- `VariantOf`
+
+---
+
+## Форматы сборки и поставки
+
+- Types: `build:types`
+- ESM: `build:esm`
+- CJS: `build:cjs`
+- UMD: `build:umd`
+
+Пакет публикует typed declarations и несколько runtime-форматов модулей для широкой совместимости.
+
+---
+
+## Структура monorepo и пакета
+
+```txt
+src/
+  constructors/
+  guards/
+  methods/
+  refiners/
+    types/
+    utils/
+  internal/
+  index.ts
+```
+
+---
+
+## Когда использовать этот проект
+
+Используйте проект, если вам нужны:
+
+- явное моделирование успеха/ошибки
+- предсказуемая FP-style композиция
+- видимый control flow
+- более сильная type-guided обработка результатов в TypeScript
+- продвинутые refinement tools для typed variants и строгого result matching
+
+---
+
+## Ссылки на документацию
+
+- [API entry (README)](./docs/api/README.md)
+- [API entry (index)](./docs/api/index.md)
+- [Modules](./docs/api/modules.md)
+- [Constructors module](./docs/api/constructors/index.md)
+- [Guards module](./docs/api/guards/index.md)
+- [Methods module](./docs/api/methods/index.md)
+- [Refiners module](./docs/api/refiners/index.md)
+- [Type aliases module](./docs/api/type-aliases/index.md)
+
+---
+Наверх: [@resultsafe/core-fp-result](#top)
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 resultsafe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.