@ghaerdi/rustify
Version:
A TypeScript library implementing Rust-like error handling with Result, Ok, and Err types.
172 lines (137 loc) • 7.26 kB
Markdown
# rustify
[](https://www.npmjs.com/package/@ghaerdi/rustify)
[](https://jsr.io/@ghaerdi/rustify)
[](https://opensource.org/licenses/MIT)
<br>
A TypeScript library implementing Rust-like error handling with `Result`, `Ok`, and `Err` types, promoting type-safe and explicit error management.
## 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 the `Result` type, a pattern widely used in Rust, to TypeScript. This allows you to:
* **Handle errors explicitly:** Functions return a `Result` which is either `Ok(value)` for success or `Err(error)` for failure.
* **Improve type safety:** The types `T` (success) and `E` (error) are tracked by the type system.
* **Chain operations safely:** Methods like `andThen` and `orElse` allow elegant chaining.
* **Perform exhaustive checks:** The `match` method ensures you handle both `Ok` and `Err` cases explicitly.
* **Easily wrap unsafe functions:** `Result.from` provides a simple way to convert functions that might throw errors into functions that return a `Result`.
* **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`, and `Result` from the library.
```typescript
import { Result, Ok, Err } 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<number, string> {
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 message = result.match({
Ok: (value) => {
// This runs only if result is Ok
console.log(`Match Ok: Division successful, value is ${value}`);
return `Result: ${value}`;
},
Err: (errorMessage) => {
// This runs only if result is Err
console.error("Match Err:", errorMessage);
return `Error: ${errorMessage}`;
}
});
console.log(message);
// Other methods like Result.from, isOk, map, andThen, unwrapOrElse, asTuple etc.
// allow for wrapping functions, specific checks, transformations, and handling patterns.
// See the API Overview section for more details.
```
## Core Concepts
* **`Result<T, E>`:** The main type, representing either success (`Ok<T>`) or failure (`Err<E>`).
* **`Ok<T>`:** Represents a successful result containing a value of type `T`. Created using the `Ok(value)` function.
* If `T` is iterable (like an Array or String), the `Ok` instance itself becomes iterable.
* **`Err<E>`:** Represents a failure containing an error value of type `E`. Created using the `Err(error)` function.
## 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 or `undefined`.
* `err()`: Returns the `Err` value or `undefined`.
* `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<T>` to `Ok<U>`. Leaves `Err` untouched.
* `mapErr(fn)`: Maps `Err<E>` to `Err<F>`. 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<Result>`. Handles resolution/rejection.
* `Result.isResult(value)`: Type guard, returns `true` if `value` is `Ok` or `Err`.
* `wrapInResult(fn, errorTransform?)`: **[Deprecated]** Use `Result.from(() => fn(...args))` instead.
## 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)