# rustify
[](https://www.npmjs.com/package/@ghaerdi/rustify)
[](https://jsr.io/@ghaerdi/rustify)
[](https://opensource.org/licenses/MIT)
A TypeScript monad library inspired by Rust, providing `Result` and `Option` types for safe error handling and null management with functional programming patterns.
## Why rustify?
JavaScript/TypeScript error handling often relies on `try...catch` blocks or nullable return types, which can be verbose or hide potential errors. `rustify` brings Rust-inspired monads like `Result` and `Option` to TypeScript, enabling functional programming patterns for safer code. This allows you to:
* **Handle errors explicitly:** Functions return a `Result` which is either `Ok(value)` for success or `Err(error)` for failure.
* **Manage nullable values safely:** Use `Option` to represent values that may or may not exist, eliminating null/undefined errors.
* **Improve type safety:** Both `Result` and `Option` types are tracked by the type system.
* **Chain operations safely:** Monadic methods like `andThen`, `map`, and `orElse` allow elegant functional composition.
* **Perform exhaustive checks:** The `match` method ensures you handle all cases explicitly.
* **Easily wrap unsafe functions:** `Result.from` and `Option.fromNullable` provide simple ways to convert potentially unsafe operations.
* **Destructure results easily:** Use `asTuple()` for Go-style `[err, val]` destructuring, or `asObject()` if you prefer `{ error, value }` destructuring.
## Installation
You can install `rustify` using your favorite package manager or directly from jsr.
**npm:**
```bash
npm install @ghaerdi/rustify
# or
yarn add @ghaerdi/rustify
# or
pnpm add @ghaerdi/rustify
```
**jsr:**
```bash
npx jsr add @ghaerdi/rustify
# or
bunx jsr add @ghaerdi/rustify
# or
deno add @ghaerdi/rustify
```
## Basic Usage
Import `Ok`, `Err`, `Result`, `Some`, `None`, and `Option` from the library.
```typescript
import { Result, Ok, Err, Option, Some, None } from "@ghaerdi/rustify";
// --- Creating a function that returns a Result ---
// Example: A function that performs division but returns Err for division by zero
function divide(numerator: number, denominator: number): Result {
if (denominator === 0) {
return Err("Cannot divide by zero"); // Failure case
}
const result = numerator / denominator;
return Ok(result); // Success case
}
// --- Using the function and handling the Result ---
const result = divide(10, 2); // Try change 2 to 0 for an Err case
// Use 'match' to exhaustively handle both Ok and Err cases.
// This is often the clearest way to ensure all possibilities are handled.
const messageFromResult = result.match({
Ok: (value) => {
// This runs only if result is Ok
console.log(`Match Ok (Result): Division successful, value is ${value}`);
return `Result: ${value}`;
},
Err: (errorMessage) => {
// This runs only if result is Err
console.error("Match Err (Result):", errorMessage);
return `Error: ${errorMessage}`;
}
});
console.log(messageFromResult);
// Example with Option
const anOptionalString: Option = Some("Hello, Option!");
const messageFromOption = anOptionalString.match({
Some: (value) => `Option has value: ${value}`,
None: () => "Option is None"
});
console.log(messageFromOption);
// Working with ok() and err() methods that now return Option:
const okValue = result.ok(); // Returns Option
if (okValue.isSome()) {
console.log(`Ok value: ${okValue.unwrap()}`);
}
const errValue = result.err(); // Returns Option
if (errValue.isSome()) {
console.log(`Error: ${errValue.unwrap()}`);
}
// Other methods like Result.from, isOk, map, andThen, unwrapOrElse, asTuple etc.
// and Option.fromNullable, isSome, map, unwrapOr etc.
// allow for wrapping functions, specific checks, transformations, and handling patterns.
// See the API Overview sections for more details.
```
## Core Concepts
* **`Result`:** Represents either success (`Ok`) or failure (`Err`).
* `Ok`: Contains a success value. Becomes iterable if `T` is iterable.
* `Err`: Contains an error value.
* **`Option`:** Represents an optional value, either `Some` or `None`.
* `Some`: Contains a value. Becomes iterable if `T` is iterable.
* `None()`: Represents the absence of a value. Call `None()` to create a None instance. You can check if an option is None using the `.isNone()` method.
## API Overview
The `Result` type provides numerous methods for handling and transformation:
* **Checking:**
* `isOk()`: Returns `true` if `Ok`.
* `isErr()`: Returns `true` if `Err`.
* `isOkAnd(fn)`: Returns `true` if `Ok` and the value satisfies `fn`.
* `isErrAnd(fn)`: Returns `true` if `Err` and the error satisfies `fn`.
* **Extracting Values:**
* `ok()`: Returns the `Ok` value as `Some(value)` or `None`.
* `err()`: Returns the `Err` value as `Some(error)` or `None`.
* `unwrap()`: Returns the `Ok` value, throws if `Err`. **Use with caution.**
* `unwrapErr()`: Returns the `Err` value, throws if `Ok`.
* `expect(message)`: Returns `Ok` value, throws `message` if `Err`.
* `expectErr(message)`: Returns `Err` value, throws `message` if `Ok`.
* `unwrapOr(defaultValue)`: Returns `Ok` value or `defaultValue` if `Err`.
* `unwrapOrElse(fn)`: Returns `Ok` value or computes default using `fn(errorValue)` if `Err`.
* **Mapping & Transformation:**
* `map(fn)`: Maps `Ok` to `Ok`. Leaves `Err` untouched.
* `mapErr(fn)`: Maps `Err` to `Err`. Leaves `Ok` untouched.
* `mapOr(defaultValue, fn)`: Applies `fn` to `Ok` value, returns `defaultValue` if `Err`.
* `mapOrElse(defaultFn, fn)`: Applies `fn` to `Ok` value, applies `defaultFn` to `Err` value.
* **Chaining & Side Effects:**
* `and(res)`: Returns `res` if `Ok`, else returns self (`Err`).
* `andThen(fn)`: Calls `fn(okValue)` if `Ok`, returns the resulting `Result`.
* `or(res)`: Returns `res` if `Err`, else returns self (`Ok`).
* `orElse(fn)`: Calls `fn(errValue)` if `Err`, returns the resulting `Result`.
* `inspect(fn)`: Calls `fn(okValue)` if `Ok`, returns original `Result`.
* `inspectErr(fn)`: Calls `fn(errValue)` if `Err`, returns original `Result`.
* **Pattern Matching:**
* `match(matcher)`: Executes `matcher.Ok(value)` or `matcher.Err(error)`, returning the result.
* **Cloning:**
* `cloned()`: Returns a new `Result` with a deep clone of the `Ok` value (using `structuredClone`). `Err` values are not cloned.
* **Destructuring / Representation:**
* `asTuple()`: Represents the Result's state as a tuple `[error, value]`. Returns `[undefined, T]` for `Ok(T)` and `[E, undefined]` for `Err(E)`.
* `asObject()`: Represents the Result's state as an object `{ error, value }`. Returns `{ error: undefined, value: T }` for `Ok(T)` and `{ error: E, value: undefined }` for `Err(E)`.
* **Utilities (Static Methods on `Result`):**
* `Result.from(fn, errorTransform?)`: Wraps a sync function `fn` that might throw. Executes `fn`. Returns `Ok(result)` or `Err(error)`.
* `Result.fromAsync(fn, errorTransform?)`: Wraps an async function `fn` returning a Promise. Returns `Promise`. Handles resolution/rejection.
* `Result.isResult(value)`: Type guard, returns `true` if `value` is `Ok` or `Err`.
## Option Monad (`Option`)
The `Option` type represents an optional value: every `Option` is either `Some` and contains a value, or `None` and does not. It's useful for handling cases where a value might be absent, without resorting to `null` or `undefined` directly, thus making potential absences explicit.
`Option` can be either:
* `Some`: Represents the presence of a value.
* `None`: Represents the absence of a value. `None` is a **singleton instance**. All operations or functions that result in an "empty" option will return this exact instance.
### Creating Options
```typescript
import { Some, None, Option } from "@ghaerdi/rustify"; // Assuming published package, or adjust path e.g. "./src"
const someValue: Option = Some(10);
const noValue: Option = None; // None is a singleton
// From potentially null/undefined values
function findConfig(key: string): { value: string } | undefined {
// ... some logic
if (key === "timeout") return { value: "3000" };
return undefined;
}
const timeoutConfig: Option<{ value: string }> = Option.fromNullable(() => findConfig("timeout"));
const missingConfig: Option<{ value: string }> = Option.fromNullable(() => findConfig("missing"));
console.log(timeoutConfig.unwrapOr({ value: "default" })); // { value: "3000" }
console.log(missingConfig.unwrapOr({ value: "default" })); // { value: "default" }
console.log(missingConfig.isNone()); // true, because findConfig("missing") returns undefined
```
### Working with Options
Options provide a variety of methods to work with potential values safely. You can check if an option is `None` by using `myOption.isNone()`.
```typescript
// Unwrapping (getting the value)
const val = Some(5).unwrapOr(0); // val is 5
const valOr = None().unwrapOr(0); // valOr is 0
console.log(`val: ${val}, valOr: ${valOr}`);
const valElse = None().unwrapOrElse(() => Math.random()); // valElse is a random number
console.log(`valElse: ${valElse}`);
// Expect (unwrap with a custom error if None)
// Some("data").expect("Data should be present"); // "data"
// None().expect("Data should be present"); // Throws Error: "Data should be present"
// console.log(Some("data").expect("Data should be present"));
// try { None().expect("Data should be present"); } catch (e:any) { console.error(e.message); }
// Mapping
const lengthOpt = Some("hello").map(s => s.length); // Some(5)
const noLengthOpt = None().map((s: string) => s.length); // None instance
console.log(`lengthOpt: ${lengthOpt.unwrapOr(-1)}, noLengthOpt is None: ${noLengthOpt.isNone()}`);
console.log(`Is noLengthOpt actually None? ${noLengthOpt.isNone()}`); // true
// Chaining (andThen / flatMap)
const parsed = Some("5").andThen(s => {
const num = parseInt(s, 10);
return isNaN(num) ? None : Some(num); // Return None singleton
}); // Some(5)
console.log(`parsed: ${parsed.unwrapOr(-1)}`);
const notParsed = Some("abc").andThen(s => {
const num = parseInt(s, 10);
return isNaN(num) ? None : Some(num); // Return None singleton
}); // None
console.log(`notParsed is None: ${notParsed.isNone()}`);
console.log(`Is notParsed actually None? ${notParsed.isNone()}`); // true
// Matching
const optionNumber = Some(42);
const message = optionNumber.match({
Some: value => `The number is: ${value}`,
None: () => "No number provided" // Handler for the None singleton
}); // "The number is: 42"
console.log(message);
const noOptionNumber: Option = None; // Assign the None singleton
const noMessage = noOptionNumber.match({
Some: value => `The number is: ${value}`,
None: () => "No number provided"
}); // "No number provided"
console.log(noMessage);
// Direct comparison with None
if (noOptionNumber.isNone()) {
console.log("noOptionNumber is indeed the None singleton.");
}
```
The `Option` type helps avoid common errors like `TypeError: Cannot read property '...' of null/undefined` by making the absence of a value an explicit state that must be handled. Use `.isNone()` method to check for None values.
A full API overview for `Option` would be similar to `Result`'s, including methods like:
`isSome`, `isNone`, `isSomeAnd`, `expect`, `unwrap`, `unwrapOr`, `unwrapOrElse`, `map`, `mapOr`, `mapOrElse`, `inspect`, `and`, `andThen` (flatMap), `or`, `orElse`, `xor`, `cloned`, `zip`, `zipWith`, and `match`. Refer to the source code or generated documentation for exhaustive details on each method's behavior and signature.
## Development
This project uses Bun.
* **Install Dependencies:**
```bash
bun install
```
* **Type Checking:**
```bash
bun run check --watch
```
* **Run Tests:**
```bash
bun test --watch
```
## Contributing
Contributions welcome! Please submit issues and pull requests.
1. Fork the repository.
2. Create your feature branch.
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.
## License
MIT License - see the LICENSE file for details.
## Links
* [GitHub Repository](https://github.com/ghaerdi/rustify)
* [Issue Tracker](https://github.com/ghaerdi/rustify/issues)