🛠️ retyper — ergonomic result/option utilities for typescript

@reliverse/retyper: Handy utilities to supercharge TypeScript projects of any scale. Brings type-safe Result/Tuple patterns, crash-guards and micro-helpers to any TS runtime — inspired by Rust, Go and modern FP — with zero deps.

npm — Sponsor — Discord — DeepWiki — GitHub

Why Retyper?

retyper brings ergonomic, type-safe error handling and utility types to TypeScript, inspired by Rust, Go, and modern functional programming. It helps you write safer, more robust code with minimal boilerplate—ideal for any project where reliability and developer experience matter.

• 🧬 Result & Tuple patterns — safer async flows, no unhandled rejections
• 📦 Zero-bloat, runtime-safe — no dependencies, works everywhere TypeScript does
• 🛡️ Crash guards & exhaustiveness checks — never miss a case again
• 🧰 Handy helpers — for truncation, environment checks, and more
• 🎯 Drop-in, framework-agnostic — use in Node, Bun, Deno, browser, or library code

Installation

bun add @reliverse/retyper
# bun • pnpm • yarn • npm

API Overview

Result Types

type Ok<T> = { ok: true; data: T; error?: never };
type Err<E> = { ok: false; data?: never; error: E };
type Result<T, E = Error> = Ok<T> | Err<E>;

Core Functions

• tryCatch(val) — Wraps a promise or function, returns a Result
• tryCatchSlim(promise) — Returns { data, error } (nullables)
• tryTuple(val) — Returns [data, error] tuple
• tryTupleErr(val) — Returns [error, data] tuple (Go style)
• safeify(fn) — Wraps a function to always return Result
• unwrap(result) — Rust-style: get value or throw
• must(promise) — Go-style: await or throw
• map(result, fn) — Map value if ok
• mapErr(result, fn) — Map error if err
• devStrict(val) — Like tryCatch, but type-errors if you ignore the result
• shouldNeverHappen(msg, ...args) — Crash guard for unreachable code
• casesHandled(unexpectedCase) — Exhaustiveness check for unions
• isDevEnv() — True if NODE_ENV === "development"
• truncateString(msg, maxLength) — Truncate with ellipsis

Usage Examples

Basic Result Handling

import { tryCatch, unwrap, Result } from "@reliverse/retyper";

const res: Result<number> = tryCatch(() => parseInt("42"));
if (res.ok) {
  console.log("Parsed:", res.data);
} else {
  console.error("Failed:", res.error);
}

Async Error Handling

import { tryCatch, must } from "@reliverse/retyper";

async function fetchJson(url: string) {
  return must(fetch(url).then(r => r.json()));
}

// Or with tryCatchSlim:
import { tryCatchSlim } from "@reliverse/retyper";

const { data, error } = await tryCatchSlim(fetch("/api/data").then(r => r.json()));
if (error) return console.error(error);
console.log(data);

Tuple Helpers

import { tryTuple, tryTupleErr } from "@reliverse/retyper";

const [data, error] = await tryTuple(fetch("/api/data").then(r => r.json()));
if (error) return;
console.log(data);

const [err, val] = await tryTupleErr(Promise.resolve(123));
if (err) throw err;
console.log(val);

Safeify

import { safeify } from "@reliverse/retyper";

const safeParse = safeify(JSON.parse);
const res = safeParse("{\"foo\":42}");
if (res.ok) console.log(res.data.foo);

Exhaustiveness Check

import { casesHandled } from "@reliverse/retyper";

type Kind = "a" | "b";
function handle(k: Kind) {
  if (k === "a") return 1;
  if (k === "b") return 2;
  return casesHandled(k); // Type error if not exhaustive
}

Crash Guard

import { shouldNeverHappen } from "@reliverse/retyper";

function foo(x: never) {
  shouldNeverHappen("Unexpected value", x);
}

Use Cases

• Type-safe error handling in any TypeScript project
• Safer async/await flows (no more unhandled promise rejections)
• Exhaustiveness checks for discriminated unions
• Utility helpers for robust, readable code

Local Playground

git clone https://github.com/reliverse/retyper
cd retyper
bun i
bun dev

Check examples/ for more usage patterns.

Shoutouts

• try-catch.ts — Theo's video

Related

• type-fest — Advanced TS types
• neverthrow — Result type for TypeScript
• ts-reset — TS' built-in typings, improved

🛠 Contributing

Bug? Feature? Example? PR it! Or hop into Discord to discuss type utilities and Reliverse tools 💜

git clone https://github.com/reliverse/retyper
cd retyper
bun i

License

MIT © blefnk Nazar Kornienko
Part of the Reliverse ecosystem