galvorn

Rust's Option and Result for TypeScript. Fully typed, tested, zero dependencies.

Install

pnpm add galvorn  # or npm i galvorn

Quick Start

import { Some, None, Ok, Fail, match } from 'galvorn';

const user = Some('Alice');
const greeting = user.map((n) => `Hello, ${n}`).unwrapOr('Hello, stranger');

const parsed = Ok('42').flatMap((s) => {
  const n = Number(s);
  return Number.isNaN(n) ? Fail('NaN') : Ok(n);
});

match(parsed, {
  Ok: (n) => console.log(`Parsed: ${n}`),
  Err: (e) => console.error(`Failed: ${e}`),
});

Why

TypeScript lacks a standard way to represent optional values and fallible operations without null, undefined, or try/catch. Galvorn brings Rust's algebraic types to TypeScript with an idiomatic API and complete type safety.

• Option<T> replaces T | null | undefined — no more if (x !== null && x !== undefined)
• Result<T, E> replaces try/catch and { data, error } patterns — errors are values, not exceptions
• match() provides exhaustive pattern matching for both types — standalone or method
• 100% test coverage, 112 tests, zero runtime dependencies

Features

Option — Safe Nullable Handling

import { Some, None, Option } from 'galvorn';

const name = Some('Alice');
const empty = None<string>();

// Transform
const upper = name.map((n) => n.toUpperCase()); // Some("ALICE")

// Chain
const first = name.flatMap((n) => (n.length > 0 ? Some(n[0]) : None()));

// Extract with default
const value = empty.unwrapOr('default'); // "default"

// Pattern match
name.match({
  Some: (n) => console.log(`Hello, ${n}`),
  None: () => console.log('No name'),
});

// Convert from nullable
const opt = Option.fromNullable(document.getElementById('app'));

Result — Error as Values

import { Ok, Fail, Result } from 'galvorn';

const success = Ok(42);
const failure = Fail('something went wrong');

// Transform
const doubled = success.map((n) => n * 2); // Ok(84)

// Chain
const parsed = Ok('42').flatMap((s) => {
  const n = Number(s);
  return Number.isNaN(n) ? Fail('not a number') : Ok(n);
});

// Extract with default
const value = failure.unwrapOr(0); // 0

// Pattern match
parsed.match({
  Ok: (n) => console.log(`Parsed: ${n}`),
  Err: (e) => console.error(`Error: ${e}`),
});

// Catch exceptions
const result = Result.fromThrowable(() => JSON.parse(input));

// Combine multiple results
const combined = Result.combine([Ok(1), Ok(2), Ok(3)]); // Ok([1, 2, 3])

Standalone match

Works with both Option and Result — useful for pipelines and functional composition:

import { match, Some, Ok } from 'galvorn';

const msg = match(Some(42), {
  Some: (v) => `got ${v}`,
  None: () => 'nothing',
});

const status = match(Ok(200), {
  Ok: (code) => `status ${code}`,
  Err: (e) => `failed: ${e}`,
});

Examples

| Example | Run | Showcases | |---|---|---| | option-basics.ts | npx tsx examples/option-basics.ts | Some/None, map, flatMap, filter, unwrapOr | | result-basics.ts | npx tsx examples/result-basics.ts | Ok/Fail, fromThrowable, combine, mapErr | | real-world.ts | npx tsx examples/real-world.ts | Option + Result in realistic scenarios |

Architecture

src/
  index.ts     # public barrel — only file consumers import
  option.ts    # Option<T> abstract class + SomeOption/NoneOption + Some()/None() factories
  result.ts    # Result<T, E> abstract class + OkResult/ErrResult + Ok()/Fail() factories
  match.ts     # Standalone match() with overloads for Option and Result

Internal classes (SomeOption, NoneOption, OkResult, ErrResult) are NOT exported. Only factory functions and abstract types are public — this keeps the API surface minimal and prevents instanceof checks against internals.

LLM / AI Integration

This package ships with llms.txt files for AI-assisted development:

• llms.txt — Concise index following the llms.txt standard
• llms-full.txt — Complete API reference optimized for LLM context windows

Compatible with Context7 and any tool that supports the llms.txt standard.

API Reference

Factory Functions

| Export | Description | |---|---| | Some(value) | Creates an Option containing a value | | None<T>() | Creates an empty Option | | Ok(value) | Creates a successful Result | | Fail(error) | Creates a failed Result | | match(value, patterns) | Standalone pattern matching for Option or Result |

Option Methods

| Method | Description | |---|---| | isSome() | Returns true if the option contains a value | | isNone() | Returns true if the option is empty | | unwrap() | Returns the value or throws | | expect(msg) | Returns the value or throws with a custom message | | unwrapOr(default) | Returns the value or a default | | unwrapOrElse(fn) | Returns the value or computes a default | | map(fn) | Transforms the inner value | | flatMap(fn) | Transforms and flattens Option<Option<U>> | | filter(predicate) | Returns None if the predicate fails | | and(other) | Returns other if both are Some, otherwise None | | or(other) | Returns self if Some, otherwise other | | orElse(fn) | Returns self if Some, otherwise calls fn | | xor(other) | Returns Some if exactly one is Some | | zip(other) | Combines two Some values into a tuple | | inspect(fn) | Calls fn on the value without consuming it | | match({ Some, None }) | Exhaustive pattern matching | | toUndefined() | Converts to T \| undefined | | toNull() | Converts to T \| null |

Option Static Methods

| Method | Description | |---|---| | Option.fromNullable(value) | Creates Some(v) or None from a nullable value |

Result Methods

| Method | Description | |---|---| | isOk() | Returns true if the result is Ok | | isErr() | Returns true if the result is Err | | unwrap() | Returns the value or throws | | unwrapErr() | Returns the error or throws | | expect(msg) | Returns the value or throws with a custom message | | expectErr(msg) | Returns the error or throws with a custom message | | unwrapOr(default) | Returns the value or a default | | unwrapOrElse(fn) | Returns the value or computes from the error | | map(fn) | Transforms the Ok value | | mapErr(fn) | Transforms the Err value | | mapOr(default, fn) | Transforms Ok or returns a default | | mapOrElse(errFn, okFn) | Transforms both branches | | flatMap(fn) | Transforms and flattens Result<Result<U, E>, E> | | and(other) | Returns other if both are Ok, otherwise the first Err | | or(other) | Returns self if Ok, otherwise other | | orElse(fn) | Returns self if Ok, otherwise calls fn with the error | | inspect(fn) | Calls fn on the Ok value without consuming it | | inspectErr(fn) | Calls fn on the Err value without consuming it | | match({ Ok, Err }) | Exhaustive pattern matching |

Result Static Methods

| Method | Description | |---|---| | Result.fromThrowable(fn) | Wraps a throwing function into Result<T, Error> | | Result.combine(results) | Collects an array of results into Result<T[], E> |

Types

| Export | Description | |---|---| | Option<T> | Abstract class for optional values | | Result<T, E> | Abstract class for fallible operations (E defaults to string) |

Compatibility

• Node.js >= 20
• TypeScript >= 5.0
• ESM only

License

MIT