tuple-result is a minimal, functional, and tree-shakable Result library for TypeScript that prioritizes simplicity and serialization.

- 🔮 Simple, declarative API: Intuitive array destructuring with full type safety
- 🍃 Lightweight & Tree Shakable: Function-based design with ~150B core
- ⚡ High Performance: Minimal overhead with just a 3-element array
- 🔍 Easy Serialization: Simple array format perfect for wire transmission
- 📦 Zero Dependencies: Standalone library ensuring ease of use in various environments
- 🔧 Functional Helpers: Powerful map, unwrap, and utility functions
- 🧵 Type Safe: Full TypeScript support with literal types and type guards

$3

- React Router v7 (CodeSandbox)

$3

Build a minimal, functional Result library that prioritizes simplicity and serialization. While libraries like ts-results and neverthrow offer robust features, their class-based implementations can create challenges with serialization and bundle size. tuple-result provides a functional alternative using simple arrays - combining minimal overhead (~150B core), easy serialization for APIs and frameworks like React Router, and helper functions while adhering to the KISS principle.

$3

- ts-results
- neverthrow

📖 Usage

tuple-result provides a simple approach to error handling. Here's how to use it:

$3

``ts
import { Err, Ok } from 'tuple-result';

const success = Ok(42);
const failure = Err('Something went wrong');
`

$3

`ts
// Method-based approach
if (success.isOk()) {
console.log(success.value); // 42
}

// Array destructuring approach
const [ok, error, value] = success;
if (ok) {
console.log(value); // 42
}

// Direct unwrapping (throws on error)
const value = success.unwrap(); // 42
`

$3

`ts
import { t, tAsync } from 'tuple-result';

// Wrap synchronous functions
const result = t(() => JSON.parse('invalid')); // Err(SyntaxError)

// Wrap promises
const asyncResult = await tAsync(fetch('/api/data')); // Ok(Response) or Err(Error)
`

$3

`ts
import { unwrapErr, unwrapOr } from 'tuple-result';

// Provide defaults
const value = unwrapOr(failure, 0); // 0
`

$3

`ts
import { mapErr, mapOk } from 'tuple-result';

// Transform success values
const doubled = mapOk(success, (x) => x * 2); // Ok(84)

// Transform errors
const wrapped = mapErr(failure, (e) => Error: ${e}); // Err('Error: Something went wrong')
`

$3

`ts
import { match } from 'tuple-result';

// Clean conditional logic
const message = match(result, {
ok: (value) => Success: ${value},
err: (error) => Error: ${error}
});

// Complex transformations
const processed = match(result, {
ok: (user) => ({ ...user, displayName: user.name.toUpperCase() }),
err: (error) => ({ id: 0, name: 'Unknown', error: error.message })
});
`

$3

`ts
// Convert to serializable format
const serialized = success.toArray(); // [true, undefined, 42]

// Reconstruct from serialized format
const reconstructed = fromArray(serialized); // Back to TResult with methods
`

📚 API Reference

$3

#### Ok(value: T): OkResult

Creates a successful result containing the given value.

`ts
const result = Ok(42);
console.log(result.unwrap()); // 42
console.log(result.isOk()); // true
`

#### Err(error: E): ErrResult

Creates an error result containing the given error.

`ts
const result = Err('Something went wrong');
console.log(result.isErr()); // true
console.log(result.error); // 'Something went wrong'
`

$3

#### isOk(result: TResult): result is OkResult

Type guard to check if a result is successful.

`ts
if (isOk(result)) {
// TypeScript knows result is OkResult here
console.log(result.unwrap());
}
`

#### isErr(result: TResult): result is ErrResult

Type guard to check if a result is an error.

`ts
if (isErr(result)) {
// TypeScript knows result is ErrResult here
console.log(result.error);
}
`

$3

#### unwrap(result: TResult): T

Extracts the value from a result, throwing if it's an error.

`ts
try {
const value = unwrap(success); // 42
} catch (error) {
// Handle error
}
`

#### unwrapOk(result: TResult): T

Extracts the value from an Ok result, throwing if it's an error.

`ts
const value = unwrapOk(success); // 42
`

#### unwrapErr(result: TResult): E

Extracts the error from an Err result, throwing if it's successful.

`ts
const error = unwrapErr(failure); // 'Something went wrong'
`

#### unwrapOr(result: TResult, defaultValue: T): T

Extracts the value from a result, returning a default if it's an error.

`ts
const value = unwrapOr(failure, 0); // 0
`

#### unwrapOrNull(result: TResult): T | null

Extracts the value from a result, returning null if it's an error.

`ts
const value = unwrapOrNull(failure); // null
`

$3

#### mapOk(result: TResult, mapFn: (value: T) => U): TResult

Maps the value inside an Ok result using the provided function.

`ts
const doubled = mapOk(Ok(21), (x) => x * 2); // Ok(42)
`

#### mapErr(result: TResult, mapFn: (error: E) => F): TResult

Maps the error inside an Err result using the provided function.

`ts
const wrapped = mapErr(Err(404), (code) => HTTP ${code}); // Err('HTTP 404')
`

$3

#### match(result: TResult | TResultArray, handlers: { ok: (value: T) => R; err: (error: E) => R }): R

Pattern matches on a result, calling the appropriate handler. Similar to Rust's match! macro.

`ts
const message = match(result, {
ok: (value) => Success: ${value},
err: (error) => Error: ${error}
});
`

$3

#### t(fn: (...args: Args) => T, ...args: Args): TResult

Wraps a synchronous function call in a Result.

`ts
const result = t(() => JSON.parse('invalid')); // Err(SyntaxError)
const safeDivide = (a: number, b: number) => t(() => a / b, a, b);
`

#### tAsync(promise: Promise): Promise>

Wraps a Promise in a Result.

`ts
const result = await tAsync(fetch('/api/data')); // Ok(Response) or Err(Error)
`

$3

#### toArray() (Instance Method)

Converts a result to a plain array for serialization.

`ts
const result = Ok(42);
const serialized = result.toArray(); // [true, undefined, 42]
`

#### fromArray(array: TResultArray): TResult

Creates a result instance from a plain array.

`ts
const result = fromArray([true, undefined, 42]); // Ok(42) with methods
`

❓ FAQ

$3

TResultArray is a subset of TResult - same array structure, but TResult adds convenience methods.

- TResult: Full-featured classes with .isOk(), .unwrap(), .value methods
- TResultArray: Plain arrays perfect for serialization (React Router, APIs, JSON)

Key benefit: All helper functions work with both types seamlessly.

`typescript
const classResult = Ok('hello');
const arrayResult = [true, undefined, 'hello'] as const;

isOk(classResult); // ✅ works
isOk(arrayResult); // ✅ also works
`

$3

Use TResult by default. You get TResultArray from:

- React Router loaders: useLoaderData()
- JSON parsing: JSON.parse(response)
- API responses

For serialization: result.toArray() → send over network → use helpers directly on received arrays or deserialize using fromArray(result).

No conversion needed - helpers work with both!

$3

TypeScript compatibility. Since TResult (classes) and TResultArray (plain arrays) have the same structure but different types, overloads ensure all helper functions work seamlessly with both:

`typescript
// These all work the same way
unwrapOr(Ok(42), 0); // ✅ TResult
unwrapOr([true, undefined, 42], 0); // ✅ TResultArray
unwrapOr(someResult, 0); // ✅ Either type
`

Without overloads, complex types can cause TypeScript errors:

`typescript
// ❌ Sometimes fails with complex types
const result: TResultArray = [false, new Error('Not found'), undefined];
unwrapOr(result, defaultUser); // Type 'TResultArray' is not assignable to parameter type 'TResult'
``

Overloads ensure compatibility in all scenarios.

💡 Resources / References

- try operator proposal - ECMAScript proposal that inspired our array destructuring
- ts-results
- neverthrow