ripthrow 2.1.1 → 2.2.0

package/README.md

@@ -1,5 +1,10 @@
 # ripthrow
 
+[![npm version](https://img.shields.io/npm/v/ripthrow.svg?style=flat-square)](https://www.npmjs.com/package/ripthrow)
+[![CI status](https://img.shields.io/github/actions/workflow/status/MechanicalLabs/ripthrow/ci.yml?branch=main&style=flat-square)](https://github.com/MechanicalLabs/ripthrow/actions/workflows/ci.yml)
+![Bundle Size](https://img.shields.io/badge/bundle_size-~5.8_KB-blue?style=flat-square)
+[![License](https://img.shields.io/github/license/MechanicalLabs/ripthrow?style=flat-square)](https://github.com/MechanicalLabs/ripthrow/blob/main/LICENSE)
+
 **Zero-dependency, type-safe error handling for TypeScript.**
 
 `ripthrow` is a lightweight library inspired by Rust's `Result` type and the proposed ECMAScript `?=` operator. It allows you to handle success and failure in a structured way, avoiding `try/catch` blocks and making error states explicit in your types.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ripthrow",
   "module": "src/index.ts",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Zero-overhead, type-safe error handling for TypeScript.",
   "keywords": [
     "result",

package/src/factories/ok.ts

@@ -5,7 +5,7 @@ import type { Result } from "../types";
  *
  * @template T The type of the success value.
  * @template E The type of the error value.
- * @param value The value to wrap in an Ok result.
+ * @param args The value to wrap in an Ok result. Required if T is not void.
  * @returns A successful Result object `{ ok: true, value: T }`.
  *
  * @category Factories
@@ -14,6 +14,6 @@ import type { Result } from "../types";
  * const res = Ok(42);
  * if (res.ok) console.log(res.value); // 42
  */
-export function Ok<T = void, E = unknown>(value?: T): Result<T, E> {
-  return { ok: true, value: value as T };
+export function Ok<T = void, E = unknown>(...args: undefined extends T ? [T?] : [T]): Result<T, E> {
+  return { ok: true, value: args[0] as T };
 }

package/src/factories/safe-async.ts

@@ -21,7 +21,7 @@ import { Ok } from "./ok";
 export async function safeAsync<T, E = Error>(promise: Promise<T>): Promise<Result<T, E>> {
   try {
     const data = await promise;
-    return Ok(data);
+    return Ok<T, E>(data as T);
   } catch (e) {
     return Err(e as E);
   }

package/src/factories/safe.ts

@@ -19,7 +19,7 @@ import { Ok } from "./ok";
  */
 export function safe<T, E = Error>(fn: () => T): Result<T, E> {
   try {
-    return Ok(fn());
+    return Ok<T, E>(fn());
   } catch (e) {
     return Err(e as E);
   }

package/src/operators/context.ts

@@ -7,6 +7,7 @@ import { mapErr } from "./map-err";
  *
  * @template T The type of the success value.
  * @template E The type of the error value.
+ * @template C The type of the metadata.
  * @param result The Result to attach context to.
  * @param message The context message.
  * @param help An optional help message.
@@ -17,12 +18,12 @@ import { mapErr } from "./map-err";
  * @example
  * const res = context(safe(() => JSON.parse(data)), "Failed to parse config");
  */
-export function context<T, E>(
+export function context<T, E, C extends Record<string, unknown> = Record<string, unknown>>(
   result: Result<T, E>,
   message: string,
   help?: string,
-  meta?: Record<string, unknown>,
-): Result<T, Report> {
+  meta?: C,
+): Result<T, Report<C>> {
   return mapErr(result, (err) => {
     let originalMeta: Record<string, unknown> | undefined;
     if (err && typeof err === "object") {
@@ -31,7 +32,7 @@ export function context<T, E>(
     const merged = { ...(originalMeta || {}), ...(meta || {}) };
     const keys = Object.keys(merged);
     // biome-ignore lint/nursery/noTernary: it's more readable
-    const ctx: Record<string, unknown> | undefined = keys.length > 0 ? merged : undefined;
+    const ctx: C | undefined = keys.length > 0 ? (merged as C) : undefined;
     return Report.from(err, message, {
       help,
       context: ctx,

package/src/operators/map.ts

@@ -21,7 +21,7 @@ import type { Result } from "../types";
  */
 export function map<T, E, R>(result: Result<T, E>, fn: (value: T) => R): Result<R, E> {
   if (result.ok) {
-    return Ok(fn(result.value));
+    return Ok<R, E>(fn(result.value));
   }
 
   return result;

package/src/pattern.ts

@@ -4,12 +4,13 @@ import type { Result } from "./types/result";
 const $class = Symbol("error-class");
 const noMatch = Symbol("no-match");
 
-interface TypedError<A extends unknown[], N extends string> extends Error {
+interface TypedError<A extends unknown[], N extends string, M = Record<string, unknown>>
+  extends Error {
   readonly args: A;
   readonly help?: string;
   readonly name: N;
   readonly kind: N;
-  readonly _metadata?: Record<string, unknown>;
+  readonly _metadata?: M;
 }
 
 interface HandlerEntry {
@@ -32,37 +33,61 @@ interface ErrDefEntry {
 type ErrDefMap = Record<string, ErrDefEntry>;
 
 declare const exhaustiveCheck: unique symbol;
-type TypedKinds<E> = E extends TypedError<unknown[], infer K> ? K : never;
+// biome-ignore lint/suspicious/noExplicitAny: needed to match any metadata type
+type TypedKinds<E> = E extends TypedError<unknown[], infer K, any> ? K : never;
 type AllTypedKindsHandled<E, Handled extends string> = TypedKinds<E> extends Handled ? true : false;
 
 type ErrorFactories<T extends ErrDefMap> = {
-  [K in keyof T & string]: ErrFactory<Parameters<T[K]["message"]>, K>;
+  [K in keyof T & string]: ErrFactory<
+    Parameters<T[K]["message"]>,
+    K,
+    T[K] extends { _metadata: infer M } ? M : Record<string, unknown>
+  >;
 } & {
   readonly _type: {
-    [K in keyof T & string]: TypedError<Parameters<T[K]["message"]>, K>;
+    [K in keyof T & string]: TypedError<
+      Parameters<T[K]["message"]>,
+      K,
+      T[K] extends { _metadata: infer M } ? M : Record<string, unknown>
+    >;
   }[keyof T & string];
 };
 
+/**
+ * Creates a collection of error factories from a definition map.
+ *
+ * @template T The error definition map.
+ * @param defs The definitions for each error kind.
+ * @returns An object containing error factories and a combined _type.
+ */
 export function createErrors<T extends ErrDefMap>(defs: T): ErrorFactories<T> {
-  const result: Record<string, ErrFactory<unknown[], string>> = {};
+  // biome-ignore lint/suspicious/noExplicitAny: internal storage of factories
+  const result: Record<string, ErrFactory<unknown[], string, any>> = {};
   for (const [name, def] of Object.entries(defs)) {
     result[name] = createError(name, def.message, def.help, def._metadata);
   }
   return result as unknown as ErrorFactories<T>;
 }
 
-export function createError<A extends unknown[], N extends string>(
+/**
+ * Creates a single typed error factory.
+ *
+ * @template A The type of the arguments.
+ * @template N The literal type of the error name.
+ * @template M The type of the metadata.
+ */
+export function createError<A extends unknown[], N extends string, M = Record<string, unknown>>(
   name: N,
   message: (...args: A) => string,
   help?: (...args: A) => string,
-  _metadata?: Record<string, unknown>,
-): ErrFactory<A, N> {
+  _metadata?: M,
+): ErrFactory<A, N, M> {
   class _Error extends Error {
     override readonly name: N;
     readonly args: A;
     readonly help: string | undefined;
     readonly kind: N = name;
-    readonly _metadata: Record<string, unknown> | undefined;
+    readonly _metadata: M | undefined;
 
     constructor(...args: A) {
       super(message(...args));
@@ -76,10 +101,10 @@ export function createError<A extends unknown[], N extends string>(
   }
   Object.defineProperty(_Error, "name", { value: name });
 
-  const factory = (...args: A): TypedError<A, N> =>
-    new _Error(...args) as unknown as TypedError<A, N>;
+  const factory = (...args: A): TypedError<A, N, M> =>
+    new _Error(...args) as unknown as TypedError<A, N, M>;
   Object.defineProperty(factory, $class, { value: _Error });
-  return factory as unknown as ErrFactory<A, N>;
+  return factory as unknown as ErrFactory<A, N, M>;
 }
 
 export function wrapError<C extends new (...args: never[]) => Error>(
@@ -90,6 +115,9 @@ export function wrapError<C extends new (...args: never[]) => Error>(
   return factory as unknown as ExternalErrFactory<C>;
 }
 
+/**
+ * Builder for pattern matching on results and errors.
+ */
 export class MatchErrBuilder<T, E, R, Handled extends string = never> {
   private readonly result: Result<T, E>;
   private readonly handlers: HandlerEntry[] = [];
@@ -98,11 +126,17 @@ export class MatchErrBuilder<T, E, R, Handled extends string = never> {
     this.result = result;
   }
 
-  on<A extends unknown[], N extends string, HandlerResult>(
-    def: ErrFactory<A, N>,
-    handler: (err: TypedError<A, N>) => HandlerResult,
+  /**
+   * Handles a specific error kind.
+   */
+  on<A extends unknown[], N extends string, M, HandlerResult>(
+    def: ErrFactory<A, N, M>,
+    handler: (err: TypedError<A, N, M>) => HandlerResult,
   ): MatchErrBuilder<T, E, R | HandlerResult, Handled | N>;
 
+  /**
+   * Handles an external error class.
+   */
   on<C extends new (...args: never[]) => Error, HandlerResult>(
     def: ExternalErrFactory<C>,
     handler: (err: InstanceType<C>) => HandlerResult,
@@ -121,10 +155,16 @@ export class MatchErrBuilder<T, E, R, Handled extends string = never> {
     return this;
   }
 
+  /**
+   * Finalizes the match with a fallback for unhandled errors.
+   */
   otherwise(fallback: (err: E) => R): T | R {
     return this.execute(fallback);
   }
 
+  /**
+   * Ensures all typed errors from a createErrors set are handled.
+   */
   exhaustive(): AllTypedKindsHandled<E, Handled> extends true
     ? T | R
     : { readonly [exhaustiveCheck]: typeof exhaustiveCheck } {
@@ -152,11 +192,17 @@ export class MatchErrBuilder<T, E, R, Handled extends string = never> {
   }
 }
 
+/**
+ * Starts a fluent match operation on a Result's error.
+ */
 export function matchErr<T, E>(result: Result<T, E>): MatchErrBuilder<T, E, never, never> {
   return new MatchErrBuilder(result);
 }
 
-export interface ErrFactory<A extends unknown[], N extends string> {
-  (...args: A): TypedError<A, N>;
-  readonly [$class]: new (...args: A) => TypedError<A, N>;
+/**
+ * Factory function for creating typed errors.
+ */
+export interface ErrFactory<A extends unknown[], N extends string, M = Record<string, unknown>> {
+  (...args: A): TypedError<A, N, M>;
+  readonly [$class]: new (...args: A) => TypedError<A, N, M>;
 }

package/src/report.ts

@@ -2,14 +2,15 @@
  * Options for creating a new Report.
  *
  * @category Error Handling
+ * @template C The type of the context metadata.
  */
-export interface ReportOptions {
+export interface ReportOptions<C extends Record<string, unknown> = Record<string, unknown>> {
   /** The underlying cause of the error. */
   cause?: unknown;
   /** A helpful message for the user on how to resolve the error. */
   help?: string | undefined;
   /** Additional key-value pairs to provide more context. */
-  context?: Record<string, unknown> | undefined;
+  context?: C | undefined;
 }
 
 /**
@@ -17,14 +18,15 @@ export interface ReportOptions {
  * Inspired by Rust's `anyhow` or `eyre`.
  *
  * @category Error Handling
+ * @template C The type of the context metadata.
  */
-export class Report extends Error {
+export class Report<C extends Record<string, unknown> = Record<string, unknown>> extends Error {
   /** A helpful message for the user on how to resolve the error. */
   readonly help?: string | undefined;
   /** Additional key-value pairs to provide more context. */
-  readonly context?: Record<string, unknown> | undefined;
+  readonly context?: C | undefined;
 
-  constructor(message: string, options: ReportOptions = {}) {
+  constructor(message: string, options: ReportOptions<C> = {}) {
     super(message);
     this.name = "Report";
     this.help = options.help;
@@ -43,9 +45,13 @@ export class Report extends Error {
    * @param options Additional options.
    * @returns A Report instance.
    */
-  static from(err: unknown, message?: string, options: ReportOptions = {}): Report {
+  static from<T extends Record<string, unknown> = Record<string, unknown>>(
+    err: unknown,
+    message?: string,
+    options: ReportOptions<T> = {},
+  ): Report<T> {
     if (err instanceof Report && !message && !options.help && !options.context) {
-      return err;
+      return err as Report<T>;
     }
 
     let baseMessage: string;

package/src/result-builder-async.ts

@@ -46,8 +46,17 @@ export class AsyncResultBuilder<T, E> {
     return this._executed;
   }
 
-  static ok<U = void, F = unknown>(value?: U): AsyncResultBuilder<U, F> {
-    return new AsyncResultBuilder(Promise.resolve(Ok(value) as Result<U, F>));
+  /**
+   * Constructs a successful Result wrapped in an AsyncResultBuilder.
+   *
+   * @template U The type of the success value.
+   * @template F The type of the error value.
+   * @param args The value to wrap. Required if U is not void.
+   */
+  static ok<U = void, F = unknown>(
+    ...args: undefined extends U ? [U?] : [U]
+  ): AsyncResultBuilder<U, F> {
+    return new AsyncResultBuilder(Promise.resolve(Ok(...args) as Result<U, F>));
   }
 
   static err<U, F>(error: F): AsyncResultBuilder<U, F> {
@@ -58,10 +67,20 @@ export class AsyncResultBuilder<T, E> {
     return new AsyncResultBuilder(safeAsync(promise) as AsyncResult<U, F>);
   }
 
-  static all<U, F>(results: AsyncResult<U, F>[]): AsyncResultBuilder<U[], F> {
+  /**
+   * Combines multiple Results into a single AsyncResultBuilder.
+   * Preserves exact types and positions of the input results.
+   */
+  static all<V extends readonly AsyncResult<unknown, unknown>[]>(
+    results: [...V],
+  ): AsyncResultBuilder<
+    { [K in keyof V]: V[K] extends AsyncResult<infer Val, unknown> ? Val : never },
+    V[number] extends AsyncResult<unknown, infer ErrV> ? ErrV : never
+  > {
     return new AsyncResultBuilder(
       Promise.all(results).then((resolved) => {
-        const values: U[] = [];
+        // biome-ignore lint/suspicious/noExplicitAny: internal storage requires any
+        const values: any[] = [];
         for (const res of resolved) {
           if (!res.ok) {
             return Err(res.error);
@@ -69,7 +88,8 @@ export class AsyncResultBuilder<T, E> {
           values.push(res.value);
         }
         return Ok(values);
-      }),
+        // biome-ignore lint/suspicious/noExplicitAny: complex tuple cast
+      }) as any,
     );
   }
 
@@ -160,17 +180,22 @@ export class AsyncResultBuilder<T, E> {
     return new AsyncResultBuilder<T, E>(this._promise, [...this._ops, op]);
   }
 
-  context(
+  /**
+   * Attaches context to the error if it exists.
+   *
+   * @template C The type of the metadata.
+   */
+  context<C extends Record<string, unknown>>(
     message: string,
     help?: string,
-    meta?: Record<string, unknown>,
-  ): AsyncResultBuilder<T, Report> {
+    meta?: C,
+  ): AsyncResultBuilder<T, Report<C>> {
     const op: Op = (r: Result<unknown, unknown>) =>
       contextOp(r as Result<T, E>, message, help, meta);
-    return new AsyncResultBuilder<T, Report>(this._promise as unknown as AsyncResult<T, Report>, [
-      ...this._ops,
-      op,
-    ]);
+    return new AsyncResultBuilder<T, Report<C>>(
+      this._promise as unknown as AsyncResult<T, Report<C>>,
+      [...this._ops, op],
+    );
   }
 
   match<R>(handlers: { ok: (value: T) => R; err: (error: E) => R }): Promise<R> {

package/src/result-builder.ts

@@ -30,9 +30,13 @@ export class ResultBuilder<T, E> {
 
   /**
    * Constructs a successful Result wrapped in a ResultBuilder.
+   *
+   * @template U The type of the success value.
+   * @template F The type of the error value.
+   * @param args The value to wrap. Required if U is not void.
    */
-  static ok<U = void, F = unknown>(value?: U): ResultBuilder<U, F> {
-    return new ResultBuilder({ ok: true, value: value as U });
+  static ok<U = void, F = unknown>(...args: undefined extends U ? [U?] : [U]): ResultBuilder<U, F> {
+    return new ResultBuilder({ ok: true, value: args[0] as U });
   }
 
   /**
@@ -47,7 +51,7 @@ export class ResultBuilder<T, E> {
    */
   static safe<U, F = Error>(fn: () => U): ResultBuilder<U, F> {
     try {
-      return ResultBuilder.ok(fn());
+      return ResultBuilder.ok<U, F>(fn());
     } catch (e) {
       return ResultBuilder.err(e as F);
     }
@@ -55,16 +59,25 @@ export class ResultBuilder<T, E> {
 
   /**
    * Combines multiple Results into a single ResultBuilder.
-   */
-  static all<U, F>(results: Result<U, F>[]): ResultBuilder<U[], F> {
-    const values: U[] = [];
+   * Preserves exact types and positions of the input results.
+   */
+  static all<V extends readonly Result<unknown, unknown>[]>(
+    results: [...V],
+  ): ResultBuilder<
+    { [K in keyof V]: V[K] extends Result<infer Val, unknown> ? Val : never },
+    V[number] extends Result<unknown, infer ErrV> ? ErrV : never
+  > {
+    // biome-ignore lint/suspicious/noExplicitAny: internal storage requires any
+    const values: any[] = [];
     for (const res of results) {
       if (!res.ok) {
-        return ResultBuilder.err(res.error);
+        // biome-ignore lint/suspicious/noExplicitAny: complex tuple cast
+        return ResultBuilder.err(res.error) as any;
       }
       values.push(res.value);
     }
-    return ResultBuilder.ok(values);
+    // biome-ignore lint/suspicious/noExplicitAny: complex tuple cast
+    return ResultBuilder.ok(values) as any;
   }
 
   /**

package/src/utils/all.ts

@@ -7,24 +7,30 @@ import type { Result } from "../types";
  * If all Results are Ok, returns an Ok with an array of all values.
  * If any Result is an Err, returns the first Err encountered.
  *
- * @template T The type of the success values.
- * @template E The type of the error value.
+ * @template T The type of the input Results array.
  * @param results An array of Results to combine.
  * @returns A Result with an array of values or the first error.
  *
  * @category Utilities
  * @see any
  * @example
- * const res = all([Ok(1), Ok(2)]); // Ok([1, 2])
- * const res = all([Ok(1), Err("fail")]); // Err("fail")
+ * const res = all([Ok(1), Ok("a")]); // Result<[number, string], any>
  */
-export function all<T, E>(results: Result<T, E>[]): Result<T[], E> {
-  const values: T[] = [];
+export function all<T extends readonly Result<unknown, unknown>[]>(
+  results: [...T],
+): Result<
+  { [K in keyof T]: T[K] extends Result<infer Val, unknown> ? Val : never },
+  T[number] extends Result<unknown, infer ErrV> ? ErrV : never
+> {
+  // biome-ignore lint/suspicious/noExplicitAny: accumulator type evolves
+  const values: any[] = [];
   for (const res of results) {
     if (!res.ok) {
-      return Err(res.error);
+      // biome-ignore lint/suspicious/noExplicitAny: forced cast for complex tuple inference
+      return Err(res.error) as any;
     }
     values.push(res.value);
   }
-  return Ok(values);
+  // biome-ignore lint/suspicious/noExplicitAny: forced cast for complex tuple inference
+  return Ok(values) as any;
 }

package/src/utils/pipe.ts

@@ -10,16 +10,42 @@
  *   (r) => unwrapOr(r, 0),
  * );
  */
-// biome-ignore lint/suspicious/noExplicitAny: variadic pipe needs flexibility
-export async function pipe<T, Fns extends Array<(arg: any) => any>>(
+export async function pipe<T>(value: T | Promise<T>): Promise<Awaited<T>>;
+export async function pipe<T, F1>(value: T | Promise<T>, f1: (arg: T) => F1): Promise<Awaited<F1>>;
+export async function pipe<T, F1, F2>(
   value: T | Promise<T>,
-  ...fns: Fns
-  // biome-ignore lint/suspicious/noExplicitAny: conditional type inference
-): Promise<Fns extends [...any[], infer Last] ? (Last extends (arg: any) => infer R ? R : T) : T> {
-  let acc: unknown = await value;
+  f1: (arg: T) => F1,
+  f2: (arg: Awaited<F1>) => F2,
+): Promise<Awaited<F2>>;
+export async function pipe<T, F1, F2, F3>(
+  value: T | Promise<T>,
+  f1: (arg: T) => F1,
+  f2: (arg: Awaited<F1>) => F2,
+  f3: (arg: Awaited<F2>) => F3,
+): Promise<Awaited<F3>>;
+// biome-ignore lint/complexity/useMaxParams: pipe naturally has many parameters for overloads
+export async function pipe<T, F1, F2, F3, F4>(
+  value: T | Promise<T>,
+  f1: (arg: T) => F1,
+  f2: (arg: Awaited<F1>) => F2,
+  f3: (arg: Awaited<F2>) => F3,
+  f4: (arg: Awaited<F3>) => F4,
+): Promise<Awaited<F4>>;
+// biome-ignore lint/complexity/useMaxParams: pipe naturally has many parameters for overloads
+export async function pipe<T, F1, F2, F3, F4, F5>(
+  value: T | Promise<T>,
+  f1: (arg: T) => F1,
+  f2: (arg: Awaited<F1>) => F2,
+  f3: (arg: Awaited<F2>) => F3,
+  f4: (arg: Awaited<F3>) => F4,
+  f5: (arg: Awaited<F4>) => F5,
+): Promise<Awaited<F5>>;
+// biome-ignore lint/suspicious/noExplicitAny: internal implementation requires any
+export async function pipe<T, Fns extends any[]>(value: T | Promise<T>, ...fns: Fns): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: internal accumulator requires any
+  let acc: any = await value;
   for (const fn of fns) {
-    // biome-ignore lint/suspicious/noExplicitAny: variadic pipe
-    acc = (fn as any)(acc);
+    acc = await fn(acc);
   }
-  return acc as never;
+  return acc;
 }