Rusty Utils

Rust-inspired error handling and functional programming utilities for TypeScript. Bring the power of Rust's Result<T, E> and Option<T> types to your TypeScript projects with full type safety and ergonomic APIs.

🚀 Features

• Result Type: Rust-style error handling without exceptions
• Option Type: Safe nullable value handling
• Functional Utilities: Pipe, compose, curry, and more
• Full Type Safety: Comprehensive TypeScript support
• Zero Dependencies: Lightweight and focused
• Tree Shakeable: Import only what you need
• Extensive Testing: 100% test coverage

📦 Installation

npm install @locci/rusty-utils

yarn add @locci/rusty-utils

pnpm add @locci/rusty-utils

🔧 Usage

Result Type - Error Handling

Replace try-catch blocks and error-prone nullable returns with expressive, type-safe error handling:

import {
  ok,
  err,
  andThenResult,
  matchResult,
  Result,
} from "@locci/rusty-utils";

interface User {
  email: string;
  age: number;
}

// Define your domain errors
type ValidationError =
  | { type: "InvalidEmail"; email: string }
  | { type: "TooYoung"; age: number };

// Functions that can fail return Result<T, E>
const validateEmail = (email: string): Result<string, ValidationError> => {
  return email.includes("@") ? ok(email) : err({ type: "InvalidEmail", email });
};

const validateAge = (age: number): Result<number, ValidationError> => {
  return age >= 18 ? ok(age) : err({ type: "TooYoung", age });
};

// Chain operations safely
const createUser = (email: string, age: number) =>
  andThenResult(validateEmail(email), (validEmail) =>
    andThenResult(validateAge(age), (validAge) =>
      ok({ email: validEmail, age: validAge })
    )
  );

// Handle results with pattern matching
const handleResult = (result: Result<User, ValidationError>) =>
  matchResult(result, {
    ok: (user) => `Created user: ${user.email}`,
    err: (error) => {
      switch (error.type) {
        case "InvalidEmail":
          return `Invalid email: ${error.email}`;
        case "TooYoung":
          return `Too young: ${error.age}`;
      }
    },
  });

// Usage
const result = createUser("[email protected]", 20);
console.log(handleResult(result)); // "Created user: [email protected]"

Option Type - Nullable Safety

Handle nullable values without null/undefined errors:

import { some, none, Option, mapOption, andThenOption, unwrapOrOption } from "@locci/rusty-utils";

interface User {
  id: string;
  name: string;
  email?: string;
}

const users: User[] = [
  { id: "1", name: "Alice", email: "[email protected]" },
  { id: "2", name: "Bob" },
];

// Safe array access
const findUser = (id: string): Option<User> => {
  const user = users.find((u) => u.id === id);
  return user ? some(user) : none;
};

// Chain operations safely
const getUserEmail = (id: string): Option<string> =>
  andThenOption(findUser(id), (user) => (user.email ? some(user.email) : none));

// Transform values safely
const getEmailDomain = (id: string): Option<string> =>
  mapOption(getUserEmail(id), (email) => email.split("@")[1]);

// Provide defaults
const displayEmail = (id: string): string =>
  unwrapOrOption(getUserEmail(id), "No email provided");

console.log(displayEmail("1")); // "[email protected]"
console.log(displayEmail("2")); // "No email provided"

Functional Programming Utilities

import { pipe, compose, memoize, debounce, groupBy } from "@locci/rusty-utils";

interface User {
  id: string;
  name: string;
  email?: string;
}

const users: User[] = [
  { id: "1", name: "Alice", email: "[email protected]" },
  { id: "2", name: "Bob" },
];

// Data transformation pipelines
const processUsers = (users: User[]) =>
  pipe(
    users,
    (users) => users.filter((u) => u.age >= 18),
    (users) => users.map((u) => ({ ...u, isAdult: true })),
    (users) => groupBy(users, (u) => u.department)
  );

// Function composition
const addTax = (rate: number) => (price: number) => price * (1 + rate);
const formatCurrency = (amount: number) => amount.toFixed(2) as unknown as number;
const calculateTotal = compose(formatCurrency, addTax(0.1));

console.log(calculateTotal(100)); // "$110.00"

// Performance optimizations
const expensiveCalculation = memoize((x: number) => {
  // Some expensive operation
  return x * x * x;
});

const debouncedSave = debounce((data: any) => {
  // Save to database
}, 300);

📚 API Reference

Result<T, E>

| Function | Description | | --------------------------- | -------------------------- | | ok(value) | Create a successful Result | | err(error) | Create a failed Result | | isOk(result) | Type guard for Ok results | | isErr(result) | Type guard for Err results | | map(result, fn) | Transform Ok value | | mapErr(result, fn) | Transform Err value | | andThen(result, fn) | Chain Result operations | | orElse(result, fn) | Handle Err cases | | match(result, patterns) | Pattern matching | | unwrapOr(result, default) | Get value or default | | tryCatch(fn) | Wrap throwing function |

Option

| Function | Description | | --------------------------- | --------------------------- | | some(value) | Create an Option with value | | none | Represents no value | | isSome(option) | Type guard for Some | | isNone(option) | Type guard for None | | fromNullable(value) | Create from nullable | | map(option, fn) | Transform Some value | | andThen(option, fn) | Chain Option operations | | filter(option, predicate) | Filter based on predicate | | unwrapOr(option, default) | Get value or default |

Functional Utilities

| Function | Description | | ------------------------ | ---------------------------------- | | pipe(value, ...fns) | Left-to-right function composition | | compose(...fns) | Right-to-left function composition | | memoize(fn) | Cache function results | | debounce(fn, delay) | Delay function execution | | throttle(fn, interval) | Limit function call rate | | groupBy(array, keyFn) | Group array elements | | chunk(array, size) | Split array into chunks | | unique(array) | Remove duplicates |

🏗️ Integration Examples

With Express.js

import express from "express";
import { tryCatchAsync, matchResult } from "@locci/rusty-utils";

app.get("/users/:id", async (req, res) => {
  const result = await tryCatchAsync(() => userService.findById(req.params.id));

  const response = matchResult(result, {
    ok: (user) => res.json(user),
    err: (error) => res.status(404).json({ error: error.message }),
  });
});

With NestJS

import { Injectable } from "@nestjs/common";
import { Result, ok, err, andThenResult } from "@locci/rusty-utils";

@Injectable()
export class UserService {
  async createUser(
    data: CreateUserDto
  ): Promise<Result<User, ValidationError>> {
    return andThenResult(this.validateInput(data), (validData) =>
      andThenResult(this.checkEmailExists(validData.email), () =>
        this.saveUser(validData)
      )
    );
  }
}

With React

import React from "react";
import { Option, matchOption } from "@locci/rusty-utils";

interface Props {
  user: Option<User>;
}

const UserProfile: React.FC<Props> = ({ user }) => {
  return matchOption(user, {
    some: (u) => (
      <div>
        <h1>{u.name}</h1>
        <p>{u.email}</p>
      </div>
    ),
    none: () => <div>No user found</div>,
  });
};

🎯 Why Use This Library?

Before (Traditional Error Handling)

// Prone to runtime errors, unclear error types
async function getUser(id: string) {
  try {
    const user = await userRepository.findById(id);
    if (!user) {
      throw new Error("User not found");
    }

    if (!user.email) {
      throw new Error("User has no email");
    }

    return user.email.split("@")[1];
  } catch (error) {
    // What type of error is this?
    // Did findById throw? Was user null? Was email null?
    throw error;
  }
}

After (With @locci/rusty-utils)

// Type-safe, explicit error handling, composable
async function getUser(id: string): Promise<Result<string, UserError>> {
  return andThenAsync(
    tryCatchAsync(() => userRepository.findById(id)),
    (user) =>
      user
        ? andThen(fromNullable(user.email), (email) =>
            ok(email.split("@")[1])
          ) ?? err({ type: "NoEmail", userId: id })
        : err({ type: "NotFound", userId: id })
  );
}

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT License. See LICENSE file for details.

🙏 Acknowledgments

Inspired by:

• Rust's Result and Option types
• Functional programming concepts
• Railway Oriented Programming

Built with ❤️ for the Locci Cloud and the TypeScript community