Result Pattern

A highly optimized, fully type-safe, dependency-free utility for representing operations that can either succeed or fail.

Complete with:

• Comprehensive functional transformations
• Advanced error handling capabilities
• Async/Promise integration
• Performance optimizations
• Elegant composition patterns

Its a fuzzy approach where by having better results we can craft more reliable code that doesn't rely on try/catch and exceptions for control flow.

🔍 Overview

This library aims to provide an elegant solution for handling operations that can succeed or fail in TypeScript applications. It addresses the common problems with traditional exception-based error handling while maintaining full type safety and composability.

Unlike traditional error handling with exceptions, this library seeks to enable us with the following:

• Explicit error handling with proper type information
• Composable operations that might fail
• Functional transformations of success and error values
• Predictable control flow without hidden exceptional paths
• Better testability through deterministic error handling
• Performance optimizations for high-throughput scenarios

✨ Features

• 🧙‍♂️ Type-Safe Results - Experience bulletproof type safety with full TypeScript inference and precise error typing. No more "any" type nightmares or runtime surprises.

• 🔄 Powerful Functional Transformations - Transform your data with elegant, chainable operations like map, chain, and pipe. Build complex processing flows with minimal code.

• 👪 Painless Composition - Compose operations that might fail without deeply nested try/catch blocks. Create clean, readable code that's easy to maintain and extend.

• 🧬 First-Class Async Support - Handle async operations with the same elegant API. Convert Promises to Results, chain async operations, and process multiple async results in parallel.

• ⚠️ Explicit Error Handling - Say goodbye to forgotten try/catch blocks and silent failures. Every potential error becomes a value you can inspect, transform, and handle with precision.

• 😇 Control Your Own Destiny - Decide exactly when and how to extract values from results with smart unwrapping operations that prevent runtime crashes.

• 🚂 Railway-Oriented Programming - Implement the powerful railway pattern with built-in short-circuiting. Keep your happy path clean while ensuring errors naturally flow to error handlers.

• ⚡ Blazing Fast Performance - Meticulously optimized for speed and minimal memory usage. We've benchmarked extensively to ensure near-zero overhead compared to traditional error handling.

• 🤑 Rich Combinators - Combine multiple results with sophisticated utilities like asyncAll and sophisticated error aggregation. No more manual result merging.

• 💻 Developer Experience First - Designed for humans with clear naming, consistent behavior, and detailed documentation with practical examples for every function.

• 🆓 Zero Dependencies - Not a single external dependency. Just pure, optimized TypeScript that won't bloat your bundle or introduce security vulnerabilities.

• 💚 Universal Compatibility - Works anywhere JavaScript runs: browsers, Node.js, Deno, Bun, web workers, or serverless functions. One API to rule them all.

• 🪖 Battle-Tested - Comprehensive guides with real-world examples for every function. Learn through practical code, not just abstract theory.

🚀 Installation

1# Using npm
2npm install @fuzzy-street/results
3
4# Using yarn
5yarn add @fuzzy-street/results
6
7# Using pnpm
8pnpm add @fuzzy-street/results

🔍 Core Concepts

Result Pattern is built around a simple concept: a function that can either succeed or fail returns a Result<T, E> type, which is either:

• { status: "success", data: T } for successful operations
• { status: "error", error: E } for failed operations

This allows you to:

1. Make error handling explicit and type-safe
2. Create pipelines of operations where errors naturally short-circuit
3. Eliminate try/catch blocks for control flow
4. Ensure all error cases are handled

🧩 Basic Usage

1import { success, error, isSuccess, isError, match } from '@fuzzy-street/results';
2
3// Creating success results
4const successResult = success(42);
5// { status: "success", data: 42 }
6
7// Creating error results
8const errorResult = error(new Error('Something went wrong'));
9// { status: "error", error: Error("Something went wrong") }
10
11// Type checking
12if (isSuccess(successResult)) {
13  console.log(successResult.data); // 42
14}
15
16if (isError(errorResult)) {
17  console.log(errorResult.error.message); // "Something went wrong"
18}
19
20// Pattern matching
21const message = match(successResult, {
22  success: (value) => `Success: ${value}`,
23  error: (err) => `Error: ${err.message}`
24});
25// "Success: 42"

📚 Library Structure

The library is organized into three main categories:

Core Functions

These form the foundation of the Result pattern:

• success: Creates a successful result
• error: Creates an error result
• isSuccess: Type guard for successful results
• isError: Type guard for error results
• isResult: Type guard for any result
• match: Pattern matching for results
• unwrap: Extracts value or throws error
• unwrapOr: Extracts value with fallback

Transformer Functions

These help transform and process results:

• map: Transforms success values
• mapError: Transforms error values
• chain: Chains operations that might fail
• tap: Performs side effects on any result
• tapSuccess: Performs side effects on success results
• tapError: Performs side effects on error results
• pipe: Creates transformation pipelines
• createErrorBoundary: Creates error-handling boundaries

Async Functions

These handle asynchronous operations:

• fromPromise: Converts a Promise to a Result
• fromAsync: Wraps an async function to return a Result
• asyncMap: Maps a Result value asynchronously
• asyncMapError: Maps a Result error asynchronously
• asyncChain: Chains async operations that return Results
• asyncPipe: Creates async transformation pipelines
• asyncAll: Combines multiple async Results
• withFinally: Executes cleanup after async operations
• createAsyncErrorBoundary: Creates async error-handling boundaries

Each function has detailed documentation and examples in the linked markdown files. We highly recommend exploring these docs to understand the full capabilities of each utility.

🌟 Advanced Examples

Railway-Oriented Programming

1import { pipe, success, error } from '@fuzzy-street/results';
2
3function validateInput(input: string) {
4  return input ? success(input) : error(new Error('Input required'));
5}
6
7function processInput(input: string) {
8  return input.length >= 3 
9    ? success(input.toUpperCase()) 
10    : error(new Error('Input too short'));
11}
12
13function formatOutput(input: string) {
14  return success(`Processed: ${input}`);
15}
16
17// Create a processing pipeline
18const result = pipe(
19  'hello',               // Input value
20  validateInput,         // Validate (short-circuit if invalid)
21  processInput,          // Process (short-circuit if fails)
22  formatOutput           // Format output
23);
24
25// result: { status: "success", data: "Processed: HELLO" }

Async Operations

1import { asyncChain, fromPromise } from '@fuzzy-street/results';
2
3async function fetchUser(id: string) {
4  return fromPromise(
5    fetch(`https://api.example.com/users/${id}`)
6      .then(response => {
7        if (!response.ok) throw new Error(`HTTP error ${response.status}`);
8        return response.json();
9      })
10  );
11}
12
13async function fetchUserPosts(user) {
14  return fromPromise(
15    fetch(`https://api.example.com/users/${user.id}/posts`)
16      .then(response => {
17        if (!response.ok) throw new Error(`HTTP error ${response.status}`);
18        return response.json();
19      })
20  );
21}
22    
23// Chain async operations
24async function getUserWithPosts(userId: string) {
25  const userResult = await fetchUser(userId);
26  return await asyncChain(userResult, fetchUserPosts);
27}

Error Handling

1import { match, success, error } from '@fuzzy-street/results';
2
3function divideNumbers(a: number, b: number) {
4  return b !== 0 
5    ? success(a / b) 
6    : error(new Error('Division by zero'));
7}
8
9const result = divideNumbers(10, 0);
10
11// Pattern matching for elegant error handling
12const message = match(result, {
13  success: (value) => `Result: ${value}`,
14  error: (err) => `Error: ${err.message}`
15});
16
17// message: "Error: Division by zero"

⚡Performance

The Result pattern has been carefully optimized to minimize overhead:

• Minimal object creation in transformations
• Early short-circuiting to avoid unnecessary processing
• Efficient memory usage with optimized data structures
• Benchmarks show minimal overhead compared to direct function calls

According to our benchmarks:

• Function call overhead is acceptable for most real-world use cases
• Error handling with Results is actually faster than traditional try/catch in many scenarios
• Memory overhead is minimal

🧙‍♂️ TypeScript Support

This library is built with TypeScript first in mind:

• Full type inference for all operations
• Generic type parameters for flexible usage
• Type guards for runtime type checking
• Type narrowing for improved developer experience

🧪 Running Examples

This repository comes with a comprehensive set of examples to demonstrate the usage of each function. To run them locally:

1. Clone the repository:

   1git clone https://github.com/fuzzy-st/results.git
   2cd results

2. Install dependencies:

   1pnpm install

3. Run a specific example:

   1pnpm tsx src/examples/core/success.ts
   2pnpm tsx src/examples/transformers/pipe.ts
   3pnpm tsx src/examples/async/asyncChain.ts

Each example file contains multiple usage patterns. To try a specific example, uncomment the corresponding run...() function at the bottom of the file before running it.

For example, in src/examples/core/success.ts:

1// Uncomment any of these to run the example
2// runBasicExample();
3// runValidationExample();
4runComplexExample(); // This one will execute

We encourage you to explore these examples to get a feel for how the library works in practice. Each example corresponds to the documentation for its respective function.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.