@crbroughton/failsafe 0.2.0

package/README.md

@@ -0,0 +1,212 @@
+# @crbroughton/failsafe
+
+Type-safe error handling utilities for TypeScript. A `Result<T, E>` type
+(inspired by Rust) plus helpers for turning throwing browser/Node APIs into
+values instead of exceptions.
+
+Lightweight, dependency-free alternative to neverthrow, plus additional
+helpers for wrapping browser/Node APIs that throw exceptions.
+
+## Install
+
+```sh
+pnpm add @crbroughton/failsafe
+```
+
+## Quick start
+
+```ts
+import { chain, isOk, match, matchResult, type TaggedError } from "@crbroughton/failsafe"
+import { tryJSONParse, tryLocalStorageGet } from "@crbroughton/failsafe/try"
+
+interface User { name: string }
+
+const result = chain(
+  tryLocalStorageGet("user"),
+  raw => raw === null
+    ? { ok: false as const, error: { tag: "JSONParseError" as const, raw: "" } }
+    : tryJSONParse<User>(raw),
+)
+
+if (isOk(result)) {
+  console.log(result.value.name)
+}
+
+const message = matchResult(result, {
+  ok: user => `Welcome, ${user.name}`,
+  err: error => `Could not load user: ${error.tag}`,
+})
+```
+
+## Exports
+
+- `@crbroughton/failsafe`: the `Result` type, `Ok`/`Err`, guards, and matchers
+- `@crbroughton/failsafe/try`: `Result`-returning wrappers around throwing web/Node APIs
+- `@crbroughton/failsafe/pipe`: plain left-to-right function composition
+
+## `@crbroughton/failsafe`
+
+### `Result<T, E = Error>`
+
+```ts
+type Result<T, E = Error> = Ok<T> | Err<E>
+interface Ok<T> { ok: true, value: T }
+interface Err<E> { ok: false, error: E }
+```
+
+### `Ok(value)` / `Err(error)`
+
+Construct a `Result` directly.
+
+```ts
+const success = Ok(42) // { ok: true, value: 42 }
+const failure = Err("boom") // { ok: false, error: "boom" }
+```
+
+### `isOk(result)` / `isErr(result)`
+
+Type guards that narrow a `Result` to `Ok<T>` or `Err<E>`.
+
+```ts
+if (isOk(result)) {
+  result.value // T
+}
+```
+
+### `ok(result)` / `err(result)`
+
+Extract the value or error as a nullable, for quick one-liners.
+
+```ts
+const value = ok(result) // T | null
+const error = err(result) // E | null
+```
+
+### `safe(fn | promise, mapError?)`
+
+Runs a throwing sync function, or awaits a promise, and returns a `Result`
+instead of throwing/rejecting. Optionally maps the caught value into a typed
+error.
+
+```ts
+// Sync: pass a thunk
+const parsed = safe(() => JSON.parse(raw)) // Result<any, Error>
+
+// Async: pass the Promise directly (not a function that returns one)
+const fetched = await safe(fetch("/api/data")) // Result<Response, Error>
+
+// With a typed error mapper
+type FetchError = TaggedError<"FetchError", { url: string }>
+const tagged = await safe(
+  fetchData(),
+  (): FetchError => ({ tag: "FetchError", url: "/api/data" }),
+)
+```
+
+> Passing an async function itself (`safe(async () => ...)`) matches the sync
+> overload, since calling it never throws synchronously; it just returns a
+> Promise. Always pass the awaited Promise directly for async code.
+
+### `chain(result, fn)`
+
+Chains a `Result`-returning function onto an existing `Result`,
+short-circuiting on `Err`.
+
+```ts
+const result = chain(tryLocalStorageGet("user"), raw =>
+  raw === null ? Err({ tag: "ParseError", raw: "" }) : tryJSONParse<User>(raw))
+```
+
+### `TaggedError<Tag, Extra?>`
+
+A discriminated error shape: every error carries a `tag` so consumers can
+narrow on it.
+
+```ts
+type ParseError = TaggedError<"ParseError", { raw: string }>
+type StorageError = TaggedError<"StorageError", { key: string }>
+```
+
+### `matchResult(result, { ok, err })`
+
+Exhaustively matches a `Result`, requiring both handlers.
+
+```ts
+const message = matchResult(result, {
+  ok: value => `Got ${value}`,
+  err: error => `Failed: ${error.message}`,
+})
+```
+
+### `match(taggedError, handlers)`
+
+Exhaustively matches a tagged error union. TypeScript requires a handler for
+every tag, and adding a new tag later forces every call site to update.
+
+```ts
+match(result.error, {
+  ParseError: e => console.error("bad json:", e.raw),
+  StorageError: e => console.error("storage failed:", e.key),
+  // omitting a tag here is a compile error
+})
+```
+
+## `@crbroughton/failsafe/try`
+
+`Result`-returning wrappers around browser/Node APIs that throw. Each
+mirrors its native function's signature exactly (including overloaded
+argument types) and returns a `TaggedError` on failure.
+
+| Function | Wraps | Error tag |
+| --- | --- | --- |
+| `tryJSONParse<T>(raw, reviver?)` | `JSON.parse` | `JSONParseError` |
+| `tryJSONStringify(value, replacer?, space?)` | `JSON.stringify` | `JSONStringifyError` |
+| `tryURIDecode(input)` | `decodeURIComponent` | `URIError` |
+| `tryURIEncode(input)` | `encodeURIComponent` | `URIError` |
+| `tryBase64Decode(input)` | `atob` | `Base64Error` |
+| `tryBase64Encode(input)` | `btoa` | `Base64Error` |
+| `tryLocalStorageGet(key)` | `localStorage.getItem` | `StorageError` |
+| `tryLocalStorageSet(key, value)` | `localStorage.setItem` | `StorageError` |
+| `tryURL(input, base?)` | `new URL(...)` | `URLParseError` |
+| `tryStructuredClone<T>(value, options?)` | `structuredClone` | `StructuredCloneError` |
+
+```ts
+import { tryJSONParse, tryURL } from "@crbroughton/failsafe/try"
+
+const parsed = tryJSONParse<User>(raw)
+const url = tryURL(userSuppliedString)
+
+if (isOk(url)) {
+  console.log(url.value.hostname)
+}
+```
+
+## `@crbroughton/failsafe/pipe`
+
+### `pipe(value, ...fns)`
+
+Pipes a value through up to five functions, left to right. Deliberately
+independent of `Result`; plain function composition. Compose it with `chain`
+for a `Result` pipeline.
+
+```ts
+import { pipe } from "@crbroughton/failsafe/pipe"
+
+const slug = pipe(
+  "  Hello World  ",
+  s => s.trim(),
+  s => s.toLowerCase(),
+  s => s.replace(/\s+/g, "-"),
+)
+// 'hello-world'
+```
+
+## Development
+
+This repo uses [devenv](https://devenv.sh) to provide Node and pnpm.
+
+```sh
+devenv shell
+pnpm install
+pnpm exec nx run-many -t build test lint typecheck
+```

package/dist/pipe/index.d.mts

@@ -0,0 +1,38 @@
+/**
+ * Pipes a value through a sequence of functions, left to right — each
+ * function's output becomes the next function's input.
+ *
+ * Deliberately independent of Result/safe: this is plain function
+ * composition and knows nothing about Ok/Err or short-circuiting. For a
+ * pipeline that stops early on an Err, use `chain` from the package root
+ * instead — the two compose fine together (see example below).
+ *
+ * @param value The initial value
+ * @returns The result of applying every function in sequence
+ *
+ * @example
+ * ```ts
+ * const slug = pipe('  Hello World  ', (s) => s.trim(), (s) => s.toLowerCase(), (s) => s.replace(/\s+/g, '-'))
+ * // 'hello-world'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Composing with chain (from '@crbroughton/failsafe') for a Result pipeline:
+ * import { chain, Err } from '@crbroughton/failsafe'
+ * import { tryLocalStorageGet, tryJSONParse } from '@crbroughton/failsafe/try'
+ *
+ * const result = pipe(
+ *   tryLocalStorageGet('user'),
+ *   (r) => chain(r, (raw) => raw === null ? Err({ tag: 'JSONParseError', raw: '' }) : tryJSONParse<User>(raw)),
+ * )
+ * ```
+ */
+declare function pipe<T>(value: T): T;
+declare function pipe<T, A>(value: T, fn1: (v: T) => A): A;
+declare function pipe<T, A, B>(value: T, fn1: (v: T) => A, fn2: (v: A) => B): B;
+declare function pipe<T, A, B, C>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C): C;
+declare function pipe<T, A, B, C, D>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C, fn4: (v: C) => D): D;
+declare function pipe<T, A, B, C, D, E>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C, fn4: (v: C) => D, fn5: (v: D) => E): E;
+
+export { pipe };

package/dist/pipe/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pipes a value through a sequence of functions, left to right — each
+ * function's output becomes the next function's input.
+ *
+ * Deliberately independent of Result/safe: this is plain function
+ * composition and knows nothing about Ok/Err or short-circuiting. For a
+ * pipeline that stops early on an Err, use `chain` from the package root
+ * instead — the two compose fine together (see example below).
+ *
+ * @param value The initial value
+ * @returns The result of applying every function in sequence
+ *
+ * @example
+ * ```ts
+ * const slug = pipe('  Hello World  ', (s) => s.trim(), (s) => s.toLowerCase(), (s) => s.replace(/\s+/g, '-'))
+ * // 'hello-world'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Composing with chain (from '@crbroughton/failsafe') for a Result pipeline:
+ * import { chain, Err } from '@crbroughton/failsafe'
+ * import { tryLocalStorageGet, tryJSONParse } from '@crbroughton/failsafe/try'
+ *
+ * const result = pipe(
+ *   tryLocalStorageGet('user'),
+ *   (r) => chain(r, (raw) => raw === null ? Err({ tag: 'JSONParseError', raw: '' }) : tryJSONParse<User>(raw)),
+ * )
+ * ```
+ */
+declare function pipe<T>(value: T): T;
+declare function pipe<T, A>(value: T, fn1: (v: T) => A): A;
+declare function pipe<T, A, B>(value: T, fn1: (v: T) => A, fn2: (v: A) => B): B;
+declare function pipe<T, A, B, C>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C): C;
+declare function pipe<T, A, B, C, D>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C, fn4: (v: C) => D): D;
+declare function pipe<T, A, B, C, D, E>(value: T, fn1: (v: T) => A, fn2: (v: A) => B, fn3: (v: B) => C, fn4: (v: C) => D, fn5: (v: D) => E): E;
+
+export { pipe };

package/dist/pipe/index.mjs

@@ -0,0 +1,5 @@
+function pipe(value, ...fns) {
+  return fns.reduce((acc, fn) => fn(acc), value);
+}
+
+export { pipe };

package/dist/safe/index.d.mts

@@ -0,0 +1,282 @@
+/**
+ * A Result type representing either success (Ok) or failure (Err).
+ * Inspired by Rust's Result<T, E> type for explicit error handling.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error (defaults to Error)
+ *
+ * @example
+ * ```ts
+ * const result: Result<number, string> = Ok(42)
+ *
+ * if (result.ok === false) {
+ *   console.error(result.error) // TypeScript knows this is string
+ * } else {
+ *   console.log(result.value) // TypeScript knows this is number
+ * }
+ * ```
+ */
+type Result<T, E = Error> = Ok<T> | Err<E>;
+/**
+ * Represents a successful result containing a value.
+ * @template T The type of the success value
+ */
+interface Ok<T> {
+    ok: true;
+    value: T;
+}
+/**
+ * Creates a successful Result with the given value.
+ *
+ * @template T The type of the value
+ * @param value The success value to wrap
+ * @returns An Ok result containing the value
+ *
+ * @example
+ * ```ts
+ * const result = Ok(42)
+ * // result is { ok: true, value: 42 }
+ * ```
+ */
+declare const Ok: <T>(value: T) => Ok<T>;
+/**
+ * Represents a failed result containing an error.
+ * @template E The type of the error
+ */
+interface Err<E> {
+    ok: false;
+    error: E;
+}
+/**
+ * Creates a failed Result with the given error.
+ *
+ * @template E The type of the error
+ * @param error The error to wrap
+ * @returns An Err result containing the error
+ *
+ * @example
+ * ```ts
+ * const result = Err('Something went wrong')
+ * // result is { ok: false, error: 'Something went wrong' }
+ * ```
+ */
+declare const Err: <E>(error: E) => Err<E>;
+/**
+ * Type guard to check if a Result is Ok.
+ * Narrows the type to Ok<T> when true.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to check
+ * @returns true if the result is Ok, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ *
+ * if (isOk(result)) {
+ *   // TypeScript knows result is Ok<T>
+ *   console.log(result.value)
+ * }
+ * ```
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+/**
+ * Type guard to check if a Result is Err.
+ * Narrows the type to Err<E> when true.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to check
+ * @returns true if the result is Err, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ *
+ * if (isErr(result)) {
+ *   // TypeScript knows result is Err<E>
+ *   console.error(result.error)
+ * }
+ * ```
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+/**
+ * Extracts the value from a Result if Ok, otherwise returns null.
+ * Convenient for converting Result to nullable value.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to extract from
+ * @returns The value if Ok, null if Err
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * const value = ok(result) // T | null
+ *
+ * const name = ok(result)?.name ?? 'Guest'
+ * ```
+ */
+declare function ok<T, E>(result: Result<T, E>): T | null;
+/**
+ * Extracts the error from a Result if Err, otherwise returns null.
+ * Convenient for converting Result to nullable error.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to extract from
+ * @returns The error if Err, null if Ok
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * const error = err(result) // E | null
+ *
+ * if (error) {
+ *   console.error('Failed:', error)
+ * }
+ * ```
+ */
+declare function err<T, E>(result: Result<T, E>): E | null;
+/**
+ * Runs a throwing SYNCHRONOUS function and returns a Result instead of throwing.
+ * Optionally maps the caught error into a typed shape.
+ *
+ * @template T The return type of the function if it succeeds
+ * @template E The error type (defaults to Error)
+ * @param fn The synchronous function to run
+ * @param mapError Optional — transform the caught value into a typed error
+ * @returns Ok(value) or Err(mappedError)
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * // Result<any, Error>
+ *
+ * type ParseError = TaggedError<'ParseError', { raw: string }>
+ *
+ * const tagged = safe(
+ *   () => JSON.parse(raw) as User,
+ *   (): ParseError => ({ tag: 'ParseError', raw })
+ * )
+ * // Result<User, ParseError>
+ * ```
+ */
+declare function safe<T, E = Error>(fn: () => T, mapError?: (error: unknown) => E): Result<T, E>;
+/**
+ * Awaits a Promise and returns a Result instead of letting it reject.
+ * Optionally maps the caught error into a typed shape.
+ *
+ * @template T The type of the resolved promise value
+ * @template E The error type (defaults to Error)
+ * @param promise The promise to await
+ * @param mapError Optional — transform the caught value into a typed error
+ * @returns A Promise that resolves to Ok(value) or Err(mappedError)
+ *
+ * @example
+ * ```ts
+ * const result = await safe(fetch('/api/data'))
+ * if (result.ok === false) {
+ *   console.error('Fetch failed:', result.error)
+ *   return
+ * }
+ * const response = result.value
+ *
+ * type FetchError = TaggedError<'FetchError', { url: string }>
+ *
+ * const tagged = await safe(
+ *   fetchData(),
+ *   (): FetchError => ({ tag: 'FetchError', url })
+ * )
+ * ```
+ */
+declare function safe<T, E = Error>(promise: Promise<T>, mapError?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Chains a Result-returning function onto an existing Result,
+ * short-circuiting if the input is already an Err.
+ *
+ * @template T The input success type
+ * @template U The output success type
+ * @template E The error type (shared between input and output)
+ * @param result The Result to chain from
+ * @param fn A function that takes the unwrapped Ok value and returns a new Result
+ * @returns The result of fn if input was Ok, otherwise the original Err unchanged
+ *
+ * @example
+ * ```ts
+ * const result = chain(tryLocalStorageGet('user'), (raw) =>
+ *   raw === null ? Err({ tag: 'ParseError', raw: '' }) : tryJSONParse<User>(raw))
+ * ```
+ */
+declare function chain<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/**
+ * A discriminated error shape — every error carries a `tag` so consumers
+ * can narrow on it (if/switch, or match for exhaustive handling).
+ *
+ * @template Tag The string literal discriminant
+ * @template Extra Additional fields specific to this error
+ *
+ * @example
+ * ```ts
+ * type ParseError = TaggedError<'ParseError', { raw: string }>
+ * type StorageError = TaggedError<'StorageError', { key: string }>
+ * ```
+ */
+type TaggedError<Tag extends string, Extra extends object = object> = {
+    tag: Tag;
+} & Extra;
+/**
+ * Exhaustively matches a Result — requires both an ok and an err handler.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @template R The return type of both handlers
+ * @param result The Result to match on
+ * @param handlers Handlers for the ok and err cases
+ * @param handlers.ok Called with the unwrapped value when result is Ok
+ * @param handlers.err Called with the unwrapped error when result is Err
+ * @returns Whichever handler's return value applies
+ *
+ * @example
+ * ```ts
+ * const message = matchResult(result, {
+ *   ok: (value) => `Got ${value}`,
+ *   err: (error) => `Failed: ${error.message}`,
+ * })
+ * ```
+ */
+declare function matchResult<T, E, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+}): R;
+/**
+ * Exhaustively matches a tagged error union. TypeScript requires a handler
+ * for every tag in the union — omitting one is a compile error, and adding
+ * a new tag later forces every call site to be updated.
+ *
+ * @template E The tagged error union type
+ * @template Handlers An object with one handler per tag in E
+ * @param error The tagged error to match on
+ * @param handlers An object mapping each tag to a handler function
+ * @returns Whichever handler's return value applies
+ *
+ * @example
+ * ```ts
+ * match(result.error, {
+ *   ParseError: (e) => console.error('bad json:', e.raw),
+ *   StorageError: (e) => console.error('storage failed:', e.key),
+ *   // omitting a tag here is a compile error
+ * })
+ * ```
+ */
+declare function match<E extends {
+    tag: string;
+}, Handlers extends {
+    [K in E["tag"]]: (error: Extract<E, {
+        tag: K;
+    }>) => unknown;
+}>(error: E, handlers: Handlers): ReturnType<Handlers[E["tag"]]>;
+
+export { Err, Ok, chain, err, isErr, isOk, match, matchResult, ok, safe };
+export type { Result, TaggedError };

package/dist/safe/index.d.ts

@@ -0,0 +1,282 @@
+/**
+ * A Result type representing either success (Ok) or failure (Err).
+ * Inspired by Rust's Result<T, E> type for explicit error handling.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error (defaults to Error)
+ *
+ * @example
+ * ```ts
+ * const result: Result<number, string> = Ok(42)
+ *
+ * if (result.ok === false) {
+ *   console.error(result.error) // TypeScript knows this is string
+ * } else {
+ *   console.log(result.value) // TypeScript knows this is number
+ * }
+ * ```
+ */
+type Result<T, E = Error> = Ok<T> | Err<E>;
+/**
+ * Represents a successful result containing a value.
+ * @template T The type of the success value
+ */
+interface Ok<T> {
+    ok: true;
+    value: T;
+}
+/**
+ * Creates a successful Result with the given value.
+ *
+ * @template T The type of the value
+ * @param value The success value to wrap
+ * @returns An Ok result containing the value
+ *
+ * @example
+ * ```ts
+ * const result = Ok(42)
+ * // result is { ok: true, value: 42 }
+ * ```
+ */
+declare const Ok: <T>(value: T) => Ok<T>;
+/**
+ * Represents a failed result containing an error.
+ * @template E The type of the error
+ */
+interface Err<E> {
+    ok: false;
+    error: E;
+}
+/**
+ * Creates a failed Result with the given error.
+ *
+ * @template E The type of the error
+ * @param error The error to wrap
+ * @returns An Err result containing the error
+ *
+ * @example
+ * ```ts
+ * const result = Err('Something went wrong')
+ * // result is { ok: false, error: 'Something went wrong' }
+ * ```
+ */
+declare const Err: <E>(error: E) => Err<E>;
+/**
+ * Type guard to check if a Result is Ok.
+ * Narrows the type to Ok<T> when true.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to check
+ * @returns true if the result is Ok, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ *
+ * if (isOk(result)) {
+ *   // TypeScript knows result is Ok<T>
+ *   console.log(result.value)
+ * }
+ * ```
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+/**
+ * Type guard to check if a Result is Err.
+ * Narrows the type to Err<E> when true.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to check
+ * @returns true if the result is Err, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ *
+ * if (isErr(result)) {
+ *   // TypeScript knows result is Err<E>
+ *   console.error(result.error)
+ * }
+ * ```
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+/**
+ * Extracts the value from a Result if Ok, otherwise returns null.
+ * Convenient for converting Result to nullable value.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to extract from
+ * @returns The value if Ok, null if Err
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * const value = ok(result) // T | null
+ *
+ * const name = ok(result)?.name ?? 'Guest'
+ * ```
+ */
+declare function ok<T, E>(result: Result<T, E>): T | null;
+/**
+ * Extracts the error from a Result if Err, otherwise returns null.
+ * Convenient for converting Result to nullable error.
+ *
+ * @template T The type of the success value
+ * @template E The type of the error
+ * @param result The Result to extract from
+ * @returns The error if Err, null if Ok
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * const error = err(result) // E | null
+ *
+ * if (error) {
+ *   console.error('Failed:', error)
+ * }
+ * ```
+ */
+declare function err<T, E>(result: Result<T, E>): E | null;
+/**
+ * Runs a throwing SYNCHRONOUS function and returns a Result instead of throwing.
+ * Optionally maps the caught error into a typed shape.
+ *
+ * @template T The return type of the function if it succeeds
+ * @template E The error type (defaults to Error)
+ * @param fn The synchronous function to run
+ * @param mapError Optional — transform the caught value into a typed error
+ * @returns Ok(value) or Err(mappedError)
+ *
+ * @example
+ * ```ts
+ * const result = safe(() => JSON.parse(raw))
+ * // Result<any, Error>
+ *
+ * type ParseError = TaggedError<'ParseError', { raw: string }>
+ *
+ * const tagged = safe(
+ *   () => JSON.parse(raw) as User,
+ *   (): ParseError => ({ tag: 'ParseError', raw })
+ * )
+ * // Result<User, ParseError>
+ * ```
+ */
+declare function safe<T, E = Error>(fn: () => T, mapError?: (error: unknown) => E): Result<T, E>;
+/**
+ * Awaits a Promise and returns a Result instead of letting it reject.
+ * Optionally maps the caught error into a typed shape.
+ *
+ * @template T The type of the resolved promise value
+ * @template E The error type (defaults to Error)
+ * @param promise The promise to await
+ * @param mapError Optional — transform the caught value into a typed error
+ * @returns A Promise that resolves to Ok(value) or Err(mappedError)
+ *
+ * @example
+ * ```ts
+ * const result = await safe(fetch('/api/data'))
+ * if (result.ok === false) {
+ *   console.error('Fetch failed:', result.error)
+ *   return
+ * }
+ * const response = result.value
+ *
+ * type FetchError = TaggedError<'FetchError', { url: string }>
+ *
+ * const tagged = await safe(
+ *   fetchData(),
+ *   (): FetchError => ({ tag: 'FetchError', url })
+ * )
+ * ```
+ */
+declare function safe<T, E = Error>(promise: Promise<T>, mapError?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Chains a Result-returning function onto an existing Result,
+ * short-circuiting if the input is already an Err.
+ *
+ * @template T The input success type
+ * @template U The output success type
+ * @template E The error type (shared between input and output)
+ * @param result The Result to chain from
+ * @param fn A function that takes the unwrapped Ok value and returns a new Result
+ * @returns The result of fn if input was Ok, otherwise the original Err unchanged
+ *
+ * @example
+ * ```ts
+ * const result = chain(tryLocalStorageGet('user'), (raw) =>
+ *   raw === null ? Err({ tag: 'ParseError', raw: '' }) : tryJSONParse<User>(raw))
+ * ```
+ */
+declare function chain<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/**
+ * A discriminated error shape — every error carries a `tag` so consumers
+ * can narrow on it (if/switch, or match for exhaustive handling).
+ *
+ * @template Tag The string literal discriminant
+ * @template Extra Additional fields specific to this error
+ *
+ * @example
+ * ```ts
+ * type ParseError = TaggedError<'ParseError', { raw: string }>
+ * type StorageError = TaggedError<'StorageError', { key: string }>
+ * ```
+ */
+type TaggedError<Tag extends string, Extra extends object = object> = {
+    tag: Tag;
+} & Extra;
+/**
+ * Exhaustively matches a Result — requires both an ok and an err handler.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @template R The return type of both handlers
+ * @param result The Result to match on
+ * @param handlers Handlers for the ok and err cases
+ * @param handlers.ok Called with the unwrapped value when result is Ok
+ * @param handlers.err Called with the unwrapped error when result is Err
+ * @returns Whichever handler's return value applies
+ *
+ * @example
+ * ```ts
+ * const message = matchResult(result, {
+ *   ok: (value) => `Got ${value}`,
+ *   err: (error) => `Failed: ${error.message}`,
+ * })
+ * ```
+ */
+declare function matchResult<T, E, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+}): R;
+/**
+ * Exhaustively matches a tagged error union. TypeScript requires a handler
+ * for every tag in the union — omitting one is a compile error, and adding
+ * a new tag later forces every call site to be updated.
+ *
+ * @template E The tagged error union type
+ * @template Handlers An object with one handler per tag in E
+ * @param error The tagged error to match on
+ * @param handlers An object mapping each tag to a handler function
+ * @returns Whichever handler's return value applies
+ *
+ * @example
+ * ```ts
+ * match(result.error, {
+ *   ParseError: (e) => console.error('bad json:', e.raw),
+ *   StorageError: (e) => console.error('storage failed:', e.key),
+ *   // omitting a tag here is a compile error
+ * })
+ * ```
+ */
+declare function match<E extends {
+    tag: string;
+}, Handlers extends {
+    [K in E["tag"]]: (error: Extract<E, {
+        tag: K;
+    }>) => unknown;
+}>(error: E, handlers: Handlers): ReturnType<Handlers[E["tag"]]>;
+
+export { Err, Ok, chain, err, isErr, isOk, match, matchResult, ok, safe };
+export type { Result, TaggedError };

package/dist/safe/index.mjs

@@ -0,0 +1,35 @@
+const Ok = (value) => ({ ok: true, value });
+const Err = (error) => ({ ok: false, error });
+function isOk(result) {
+  return result.ok === true;
+}
+function isErr(result) {
+  return result.ok === false;
+}
+function ok(result) {
+  return result.ok === true ? result.value : null;
+}
+function err(result) {
+  return result.ok === true ? null : result.error;
+}
+function safe(input, mapError) {
+  if (input instanceof Promise) {
+    return input.then((data) => Ok(data)).catch((error) => Err(mapError ? mapError(error) : error));
+  }
+  try {
+    return Ok(input());
+  } catch (error) {
+    return Err(mapError ? mapError(error) : error);
+  }
+}
+function chain(result, fn) {
+  return isOk(result) ? fn(result.value) : result;
+}
+function matchResult(result, handlers) {
+  return result.ok ? handlers.ok(result.value) : handlers.err(result.error);
+}
+function match(error, handlers) {
+  return handlers[error.tag](error);
+}
+
+export { Err, Ok, chain, err, isErr, isOk, match, matchResult, ok, safe };

package/dist/try/index.d.mts

@@ -0,0 +1,166 @@
+import { TaggedError, Result } from '../safe/index.mjs';
+
+/**
+ * Error returned when JSON.parse fails on malformed input.
+ */
+type JSONParseError = TaggedError<"JSONParseError", {
+    raw: string;
+}>;
+/**
+ * Error returned when JSON.stringify fails (circular references, BigInt, etc).
+ */
+type JSONStringifyError = TaggedError<"JSONStringifyError">;
+/**
+ * Error returned when encodeURIComponent/decodeURIComponent fail on a
+ * malformed sequence.
+ */
+type URIError_ = TaggedError<"URIError", {
+    input: string;
+}>;
+/**
+ * Error returned when atob/btoa fail on malformed or non-Latin1 input.
+ */
+type Base64Error = TaggedError<"Base64Error", {
+    input: string;
+}>;
+/**
+ * Error returned when a localStorage read/write fails — quota exceeded,
+ * storage disabled (e.g. Safari private mode), or serialization failure.
+ */
+type StorageError = TaggedError<"StorageError", {
+    key: string;
+}>;
+/**
+ * Error returned when `new URL(...)` fails on an invalid URL string.
+ */
+type URLParseError = TaggedError<"URLParseError", {
+    input: string;
+}>;
+/**
+ * Error returned when structuredClone fails on a non-cloneable value
+ * (functions, DOM nodes, etc).
+ */
+type StructuredCloneError = TaggedError<"StructuredCloneError">;
+/**
+ * Safely parses a JSON string. Wraps JSON.parse, which throws a
+ * SyntaxError on invalid JSON.
+ *
+ * @template T The expected shape of the parsed value
+ * @param raw The JSON string to parse
+ * @param reviver Optional JSON.parse reviver, called for each member of the object
+ * @returns Ok(parsed value) or Err(JSONParseError)
+ *
+ * @example
+ * ```ts
+ * const result = tryJSONParse<User>(raw)
+ * if (isOk(result)) {
+ *   console.log(result.value.name)
+ * }
+ * ```
+ */
+declare function tryJSONParse<T = unknown>(raw: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): Result<T, JSONParseError>;
+/**
+ * Safely stringifies a value to JSON. Wraps JSON.stringify, which throws
+ * a TypeError on circular references or BigInt values.
+ *
+ * @param value The value to stringify
+ * @param replacer Optional JSON.stringify replacer — a transform function, or an allowlist of keys to include
+ * @param space Optional JSON.stringify indentation
+ * @returns Ok(json string) or Err(JSONStringifyError)
+ *
+ * @example
+ * ```ts
+ * const result = tryJSONStringify(data)
+ * if (isErr(result)) {
+ *   console.error('could not serialize:', result.error)
+ * }
+ * ```
+ */
+declare function tryJSONStringify(value: unknown, replacer?: ((this: unknown, key: string, value: unknown) => unknown) | (string | number)[] | null, space?: string | number): Result<string, JSONStringifyError>;
+/**
+ * Safely decodes a URI component. Wraps decodeURIComponent, which throws
+ * a URIError on malformed percent-encoded sequences.
+ *
+ * @param input The string to decode
+ * @returns Ok(decoded string) or Err(URIError_)
+ */
+declare function tryURIDecode(input: string): Result<string, URIError_>;
+/**
+ * Safely encodes a URI component. Wraps encodeURIComponent, which throws
+ * a URIError on lone surrogate characters.
+ *
+ * @param input The string, number, or boolean to encode
+ * @returns Ok(encoded string) or Err(URIError_)
+ */
+declare function tryURIEncode(input: string | number | boolean): Result<string, URIError_>;
+/**
+ * Safely decodes a base64 string. Wraps atob, which throws a DOMException
+ * on malformed base64 or non-Latin1 input.
+ *
+ * @param input The base64 string to decode
+ * @returns Ok(decoded string) or Err(Base64Error)
+ */
+declare function tryBase64Decode(input: string): Result<string, Base64Error>;
+/**
+ * Safely encodes a string to base64. Wraps btoa, which throws a
+ * DOMException on characters outside the Latin1 range.
+ *
+ * @param input The string to encode
+ * @returns Ok(base64 string) or Err(Base64Error)
+ */
+declare function tryBase64Encode(input: string): Result<string, Base64Error>;
+/**
+ * Safely reads a value from localStorage. localStorage.getItem doesn't
+ * throw on its own, but this exists so a get→parse pipeline stays
+ * consistently Result-shaped throughout (pair with tryJSONParse via chain).
+ *
+ * @param key The storage key to read
+ * @returns Ok(value or null) or Err(StorageError)
+ *
+ * @example
+ * ```ts
+ * const result = chain(tryLocalStorageGet('user'), (raw) =>
+ *   raw === null ? Err({ tag: 'JSONParseError', raw: '' }) : tryJSONParse<User>(raw))
+ * ```
+ */
+declare function tryLocalStorageGet(key: string): Result<string | null, StorageError>;
+/**
+ * Safely writes a value to localStorage. Wraps localStorage.setItem, which
+ * throws on quota exceeded or when storage is disabled (e.g. Safari
+ * private mode).
+ *
+ * @param key The storage key to write
+ * @param value The string value to store
+ * @returns Ok(undefined) or Err(StorageError)
+ */
+declare function tryLocalStorageSet(key: string, value: string): Result<void, StorageError>;
+/**
+ * Safely constructs a URL. Wraps `new URL(...)`, which throws a TypeError
+ * on an invalid URL string.
+ *
+ * @param input The URL (string or URL) to parse
+ * @param base Optional base URL (string or URL) to resolve against
+ * @returns Ok(URL) or Err(URLParseError)
+ *
+ * @example
+ * ```ts
+ * const result = tryURL(userSuppliedString)
+ * if (isOk(result)) {
+ *   console.log(result.value.hostname)
+ * }
+ * ```
+ */
+declare function tryURL(input: string | URL, base?: string | URL): Result<URL, URLParseError>;
+/**
+ * Safely deep-clones a value. Wraps structuredClone, which throws a
+ * DataCloneError on non-cloneable values (functions, DOM nodes, etc).
+ *
+ * @template T The type of the value to clone
+ * @param value The value to clone
+ * @param options Optional structuredClone options (e.g. a transfer list)
+ * @returns Ok(cloned value) or Err(StructuredCloneError)
+ */
+declare function tryStructuredClone<T>(value: T, options?: StructuredSerializeOptions): Result<T, StructuredCloneError>;
+
+export { tryBase64Decode, tryBase64Encode, tryJSONParse, tryJSONStringify, tryLocalStorageGet, tryLocalStorageSet, tryStructuredClone, tryURIDecode, tryURIEncode, tryURL };
+export type { Base64Error, JSONParseError, JSONStringifyError, StorageError, StructuredCloneError, URIError_, URLParseError };

package/dist/try/index.d.ts

@@ -0,0 +1,166 @@
+import { TaggedError, Result } from '../safe/index.js';
+
+/**
+ * Error returned when JSON.parse fails on malformed input.
+ */
+type JSONParseError = TaggedError<"JSONParseError", {
+    raw: string;
+}>;
+/**
+ * Error returned when JSON.stringify fails (circular references, BigInt, etc).
+ */
+type JSONStringifyError = TaggedError<"JSONStringifyError">;
+/**
+ * Error returned when encodeURIComponent/decodeURIComponent fail on a
+ * malformed sequence.
+ */
+type URIError_ = TaggedError<"URIError", {
+    input: string;
+}>;
+/**
+ * Error returned when atob/btoa fail on malformed or non-Latin1 input.
+ */
+type Base64Error = TaggedError<"Base64Error", {
+    input: string;
+}>;
+/**
+ * Error returned when a localStorage read/write fails — quota exceeded,
+ * storage disabled (e.g. Safari private mode), or serialization failure.
+ */
+type StorageError = TaggedError<"StorageError", {
+    key: string;
+}>;
+/**
+ * Error returned when `new URL(...)` fails on an invalid URL string.
+ */
+type URLParseError = TaggedError<"URLParseError", {
+    input: string;
+}>;
+/**
+ * Error returned when structuredClone fails on a non-cloneable value
+ * (functions, DOM nodes, etc).
+ */
+type StructuredCloneError = TaggedError<"StructuredCloneError">;
+/**
+ * Safely parses a JSON string. Wraps JSON.parse, which throws a
+ * SyntaxError on invalid JSON.
+ *
+ * @template T The expected shape of the parsed value
+ * @param raw The JSON string to parse
+ * @param reviver Optional JSON.parse reviver, called for each member of the object
+ * @returns Ok(parsed value) or Err(JSONParseError)
+ *
+ * @example
+ * ```ts
+ * const result = tryJSONParse<User>(raw)
+ * if (isOk(result)) {
+ *   console.log(result.value.name)
+ * }
+ * ```
+ */
+declare function tryJSONParse<T = unknown>(raw: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): Result<T, JSONParseError>;
+/**
+ * Safely stringifies a value to JSON. Wraps JSON.stringify, which throws
+ * a TypeError on circular references or BigInt values.
+ *
+ * @param value The value to stringify
+ * @param replacer Optional JSON.stringify replacer — a transform function, or an allowlist of keys to include
+ * @param space Optional JSON.stringify indentation
+ * @returns Ok(json string) or Err(JSONStringifyError)
+ *
+ * @example
+ * ```ts
+ * const result = tryJSONStringify(data)
+ * if (isErr(result)) {
+ *   console.error('could not serialize:', result.error)
+ * }
+ * ```
+ */
+declare function tryJSONStringify(value: unknown, replacer?: ((this: unknown, key: string, value: unknown) => unknown) | (string | number)[] | null, space?: string | number): Result<string, JSONStringifyError>;
+/**
+ * Safely decodes a URI component. Wraps decodeURIComponent, which throws
+ * a URIError on malformed percent-encoded sequences.
+ *
+ * @param input The string to decode
+ * @returns Ok(decoded string) or Err(URIError_)
+ */
+declare function tryURIDecode(input: string): Result<string, URIError_>;
+/**
+ * Safely encodes a URI component. Wraps encodeURIComponent, which throws
+ * a URIError on lone surrogate characters.
+ *
+ * @param input The string, number, or boolean to encode
+ * @returns Ok(encoded string) or Err(URIError_)
+ */
+declare function tryURIEncode(input: string | number | boolean): Result<string, URIError_>;
+/**
+ * Safely decodes a base64 string. Wraps atob, which throws a DOMException
+ * on malformed base64 or non-Latin1 input.
+ *
+ * @param input The base64 string to decode
+ * @returns Ok(decoded string) or Err(Base64Error)
+ */
+declare function tryBase64Decode(input: string): Result<string, Base64Error>;
+/**
+ * Safely encodes a string to base64. Wraps btoa, which throws a
+ * DOMException on characters outside the Latin1 range.
+ *
+ * @param input The string to encode
+ * @returns Ok(base64 string) or Err(Base64Error)
+ */
+declare function tryBase64Encode(input: string): Result<string, Base64Error>;
+/**
+ * Safely reads a value from localStorage. localStorage.getItem doesn't
+ * throw on its own, but this exists so a get→parse pipeline stays
+ * consistently Result-shaped throughout (pair with tryJSONParse via chain).
+ *
+ * @param key The storage key to read
+ * @returns Ok(value or null) or Err(StorageError)
+ *
+ * @example
+ * ```ts
+ * const result = chain(tryLocalStorageGet('user'), (raw) =>
+ *   raw === null ? Err({ tag: 'JSONParseError', raw: '' }) : tryJSONParse<User>(raw))
+ * ```
+ */
+declare function tryLocalStorageGet(key: string): Result<string | null, StorageError>;
+/**
+ * Safely writes a value to localStorage. Wraps localStorage.setItem, which
+ * throws on quota exceeded or when storage is disabled (e.g. Safari
+ * private mode).
+ *
+ * @param key The storage key to write
+ * @param value The string value to store
+ * @returns Ok(undefined) or Err(StorageError)
+ */
+declare function tryLocalStorageSet(key: string, value: string): Result<void, StorageError>;
+/**
+ * Safely constructs a URL. Wraps `new URL(...)`, which throws a TypeError
+ * on an invalid URL string.
+ *
+ * @param input The URL (string or URL) to parse
+ * @param base Optional base URL (string or URL) to resolve against
+ * @returns Ok(URL) or Err(URLParseError)
+ *
+ * @example
+ * ```ts
+ * const result = tryURL(userSuppliedString)
+ * if (isOk(result)) {
+ *   console.log(result.value.hostname)
+ * }
+ * ```
+ */
+declare function tryURL(input: string | URL, base?: string | URL): Result<URL, URLParseError>;
+/**
+ * Safely deep-clones a value. Wraps structuredClone, which throws a
+ * DataCloneError on non-cloneable values (functions, DOM nodes, etc).
+ *
+ * @template T The type of the value to clone
+ * @param value The value to clone
+ * @param options Optional structuredClone options (e.g. a transfer list)
+ * @returns Ok(cloned value) or Err(StructuredCloneError)
+ */
+declare function tryStructuredClone<T>(value: T, options?: StructuredSerializeOptions): Result<T, StructuredCloneError>;
+
+export { tryBase64Decode, tryBase64Encode, tryJSONParse, tryJSONStringify, tryLocalStorageGet, tryLocalStorageSet, tryStructuredClone, tryURIDecode, tryURIEncode, tryURL };
+export type { Base64Error, JSONParseError, JSONStringifyError, StorageError, StructuredCloneError, URIError_, URLParseError };

package/dist/try/index.mjs

@@ -0,0 +1,64 @@
+import { safe } from '../safe/index.mjs';
+
+function tryJSONParse(raw, reviver) {
+  return safe(
+    () => JSON.parse(raw, reviver),
+    () => ({ tag: "JSONParseError", raw })
+  );
+}
+function tryJSONStringify(value, replacer, space) {
+  return safe(
+    () => JSON.stringify(value, replacer, space),
+    () => ({ tag: "JSONStringifyError" })
+  );
+}
+function tryURIDecode(input) {
+  return safe(
+    () => decodeURIComponent(input),
+    () => ({ tag: "URIError", input })
+  );
+}
+function tryURIEncode(input) {
+  return safe(
+    () => encodeURIComponent(input),
+    () => ({ tag: "URIError", input: String(input) })
+  );
+}
+function tryBase64Decode(input) {
+  return safe(
+    () => atob(input),
+    () => ({ tag: "Base64Error", input })
+  );
+}
+function tryBase64Encode(input) {
+  return safe(
+    () => btoa(input),
+    () => ({ tag: "Base64Error", input })
+  );
+}
+function tryLocalStorageGet(key) {
+  return safe(
+    () => localStorage.getItem(key),
+    () => ({ tag: "StorageError", key })
+  );
+}
+function tryLocalStorageSet(key, value) {
+  return safe(
+    () => localStorage.setItem(key, value),
+    () => ({ tag: "StorageError", key })
+  );
+}
+function tryURL(input, base) {
+  return safe(
+    () => new URL(input, base),
+    () => ({ tag: "URLParseError", input: String(input) })
+  );
+}
+function tryStructuredClone(value, options) {
+  return safe(
+    () => structuredClone(value, options),
+    () => ({ tag: "StructuredCloneError" })
+  );
+}
+
+export { tryBase64Decode, tryBase64Encode, tryJSONParse, tryJSONStringify, tryLocalStorageGet, tryLocalStorageSet, tryStructuredClone, tryURIDecode, tryURIEncode, tryURL };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@crbroughton/failsafe",
+  "type": "module",
+  "version": "0.2.0",
+  "packageManager": "pnpm@9.15.0",
+  "description": "Type-safe error handling utilities for TypeScript",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/safe/index.d.mts",
+      "import": "./dist/safe/index.mjs"
+    },
+    "./try": {
+      "types": "./dist/try/index.d.mts",
+      "import": "./dist/try/index.mjs"
+    },
+    "./pipe": {
+      "types": "./dist/pipe/index.d.mts",
+      "import": "./dist/pipe/index.mjs"
+    }
+  },
+  "main": "./dist/safe/index.mjs",
+  "types": "./dist/safe/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^3.9.2",
+    "@changesets/cli": "^3.0.3",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.17.0",
+    "happy-dom": "^15.11.7",
+    "nx": "^20.3.0",
+    "typescript": "^5.7.2",
+    "unbuild": "^3.0.1",
+    "vitest": "^2.1.8"
+  }
+}