@resultsafe/core-fp-result

✅ Версия 0.1.9 | UTF-8 кодировка документации | Оптимизировано для совместной работы с ИИ

Rust-inspired Result-пакет для явных, композиционных и типобезопасных API в TypeScript и JavaScript.

Язык: English | Русский

Документация: API index · Modules

Содержание

• Зачем нужен этот пакет
• Контекст monorepo
• Ключевые возможности
• Пакет
• Установка
• Быстрый старт
• Обзор основного API
• Форматы сборки и поставки
• Структура monorepo и пакета
• Когда использовать этот проект
• Ссылки на документацию
• License

Зачем нужен этот пакет

@resultsafe/core-fp-result предоставляет явные success/error flow вместо скрытых путей управления и exception-first ветвления.

Его основной пакет, @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

Установка

Пакет

pnpm add @resultsafe/core-fp-result

# Альтернатива
npm install @resultsafe/core-fp-result

Monorepo

pnpm install

Быстрый старт

Типичный Result flow начинается с явных конструкторов и затем компонуется через функции, а не через неявные пути исключений.

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

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

Core Types

• Result<T, E> — Контейнер успеха/ошибки 📄 · 🔗 · 💻
• Option<T> — Контейнер опционального значения 📄 · 🔗 · 💻

Type Helpers

• VariantConfig — Конфигурация варианта 📄 · 🔗 · 💻
• PayloadKeys<T> — Извлечение ключей payload 📄 · 🔗 · 💻
• ValidatorFn<T> — Синхронная функция валидатора 📄 · 🔗 · 💻
• AsyncValidatorFn — Асинхронная функция валидатора 📄 · 🔗 · 💻

Constructors

• Ok — Создать успешный результат 📄 · 🔗 · 💻
• Err — Создать ошибочный результат 📄 · 🔗 · 💻

Guards

• isOk — Проверка на успех 📄 · 🔗 · 💻
• isErr — Проверка на ошибку 📄 · 🔗 · 💻
• isOkAnd — Проверка успеха с предикатом 📄 · 🔗 · 💻
• isErrAnd — Проверка ошибки с предикатом 📄 · 🔗 · 💻

Methods

Transformation

• map — Трансформация успешного значения 📄 · 🔗 · 💻
• mapErr — Трансформация значения ошибки 📄 · 🔗 · 💻

Chaining

• andThen — Цепочка вычислений, возвращающих Result 📄 · 🔗 · 💻
• orElse — Восстановление после ошибки 📄 · 🔗 · 💻

Extraction

• unwrap — Извлечь значение или выбросить 📄 · 🔗 · 💻
• unwrapOr — Извлечь значение или default 📄 · 🔗 · 💻
• unwrapOrElse — Извлечь значение или вычислить default 📄 · 🔗 · 💻
• unwrapErr — Извлечь ошибку или выбросить 📄 · 🔗 · 💻
• expect — Извлечь значение или выбросить с сообщением 📄 · 🔗 · 💻
• expectErr — Извлечь ошибку или выбросить с сообщением 📄 · 🔗 · 💻

Side Effects

• tap — Побочный эффект на успехе 📄 · 🔗 · 💻
• tapErr — Побочный эффект на ошибке 📄 · 🔗 · 💻
• inspect — Отладка на успехе 📄 · 🔗 · 💻
• inspectErr — Отладка на ошибке 📄 · 🔗 · 💻

Advanced

• match — Pattern matching 📄 · 🔗 · 💻
• flatten — Схлопывание вложенного Result 📄 · 🔗 · 💻
• transpose — Result → Option 📄 · 🔗 · 💻
• ok — Конвертировать в Option (успех) 📄 · 🔗 · 💻
• err — Конвертировать в Option (ошибка) 📄 · 🔗 · 💻

Refiners

• isTypedVariant — Type guard для варианта 📄 · 🔗 · 💻
• isTypedVariantOf — Type guard с картой вариантов 📄 · 🔗 · 💻
• matchVariant — Match варианта с обработчиками 📄 · 🔗 · 💻
• matchVariantStrict — Строгий match варианта 📄 · 🔗 · 💻
• refineAsyncResult — Асинхронное уточнение результата 📄 · 🔗 · 💻
• refineAsyncResultU — Асинхронное уточнение (некаррированное) 📄 · 🔗 · 💻
• refineResult — Синхронное уточнение результата 📄 · 🔗 · 💻
• refineResultU — Синхронное уточнение (некаррированное) 📄 · 🔗 · 💻
• refineVariantMap — Уточнение карты вариантов 📄 · 🔗 · 💻

Type Aliases

• Handler — Тип обработчика match 📄 · 🔗 · 💻
• MatchBuilder — Тип построителя match 📄 · 🔗 · 💻
• Matcher — Тип функции match 📄 · 🔗 · 💻
• SyncRefinedResult — Синхронный уточнённый результат 📄 · 🔗 · 💻
• SyncRefinedResultUnion — Объединение уточнённых результатов 📄 · 🔗 · 💻
• SyncValidatorMap — Тип карты валидаторов 📄 · 🔗 · 💻
• UniversalAsyncRefinedResult — Асинхронный уточнённый результат 📄 · 🔗 · 💻
• UniversalRefinedResult — Универсальный уточнённый результат 📄 · 🔗 · 💻
• VariantOf — Вспомогательный тип варианта 📄 · 🔗 · 💻

Форматы сборки и поставки

• Types: build:types
• ESM: build:esm
• CJS: build:cjs
• UMD: build:umd

Пакет публикует typed declarations и несколько runtime-форматов модулей для широкой совместимости.

Структура monorepo и пакета

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)
• API entry (index)
• Modules
• Constructors module
• Guards module
• Methods module
• Refiners module
• Type aliases module

Наверх: @resultsafe/core-fp-result

Author

Denis Savasteev

License

MIT