@mikkurogue/option-ts

A TypeScript library providing Rust-inspired Option and Result types for robust error handling and explicit value presence.

Features

• Option<T> Type: Represents the presence (Some) or absence (None) of a value, helping to eliminate null and undefined related bugs.
• Result<T, E> Type: Encapsulates either a successful value (Ok) or an error (Err), promoting explicit error handling over exceptions.
• Functional API: Provides map, flatMap, orElse, filter, and match functions for composing operations on Option and Result types.
• fromThrowable: A utility to convert potentially throwing functions into Option or Result returning functions, enabling a more functional error handling style.
• Clean API: Designed for ease of use and integration into existing TypeScript projects.

Installation

1npm install @mikkurogue/option-ts
2# or
3yarn add @mikkurogue/option-ts

Usage

Option Example

1import { Option, Some, None, ifSome, unwrapOption, unwrapOrOption } from '@mikkurogue/option-ts';
2
3function getUserById(id: string): Option<{ name: string }> {
4  if (id === "123") {
5    return Some({ name: "Alice" });
6  }
7  return None();
8}
9
10const user = getUserById("123");
11
12ifSome(user, (u) => {
13  console.log(`User found: ${u.name}`);
14});
15
16const userName = unwrapOrOption(user, { name: "Guest" }).name;
17console.log(userName); // Alice
18
19const nonExistentUser = getUserById("456");
20const defaultUserName = unwrapOrOption(nonExistentUser, { name: "Guest" }).name;
21console.log(defaultUserName); // Guest

Result Example

1import { Result, Ok, Err, match, fromThrowable } from '@mikkurogue/option-ts';
2
3function divide(a: number, b: number): Result<number, string> {
4  if (b === 0) {
5    return Err("Cannot divide by zero");
6  }
7  return Ok(a / b);
8}
9
10const division1 = divide(10, 2);
11match(
12  division1,
13  (val) => console.log(`Result: ${val}`), // Result: 5
14  (err) => console.error(`Error: ${err}`)
15);
16
17const division2 = divide(10, 0);
18match(
19  division2,
20  (val) => console.log(`Result: ${val}`),
21  (err) => console.error(`Error: ${err}`) // Error: Cannot divide by zero
22);
23
24const safeParseJson = fromThrowable(
25  JSON.parse,
26  (e) => (e as Error).message
27);
28
29const parsedJson = safeParseJson('{"key": "value"}');
30match(
31  parsedJson,
32  (data) => console.log("Parsed JSON:", data), // Parsed JSON: { key: 'value' }
33  (error) => console.error("JSON Error:", error)
34);

Documentation

For more detailed information and examples, please refer to the full documentation.

Build System

This project uses tsgo as its build system for fast and efficient compilation.

Contributing

Contributions are welcome, in any form you'd like.