@lebedevna/neverthrow-utils

Small utilities for building typed error flows with neverthrow.

Installation

pnpm add @lebedevna/neverthrow-utils neverthrow

zod is a peer dependency required when using validate:

pnpm add zod

Usage

Format errors with erro

erro creates a neverthrow Err and gives the error object a useful JSON string representation.

import { erro } from "@lebedevna/neverthrow-utils";

const result = erro({ type: "not found", id: "post-42" });

console.log(String(result.error));
// {
//   "type": "not found",
//   "id": "post-42"
// }

Use erro.fmt when you need the same JSON string representation without creating an Err. It formats the provided error object in place and returns it.

import { erro } from "@lebedevna/neverthrow-utils";

const error = erro.fmt({ type: "not found", id: "post-42" });

console.log(String(error));
// {
//   "type": "not found",
//   "id": "post-42"
// }

Parse JSON safely

import { parseJson } from "@lebedevna/neverthrow-utils";

const result = parseJson('{"enabled":true}');

result.match(
  (value) => console.log(value),
  (error) => console.error(error.type), // "invalid json"
);

parseJson returns unknown; validate the parsed value before reading fields from it.

Fetch without rejected promises

safeFetch returns a ResultAsync. The text body of a successful 2xx response is an Ok; non-2xx responses and transport failures are Errs.

import { safeFetch } from "@lebedevna/neverthrow-utils";

const result = await safeFetch("https://api.example.com/posts/42");

result.match(
  (text) => console.log(text),
  (error) => {
    if (error.type === "http error") {
      console.error(error.status, error.headers.get("content-type"), error.text);
      return;
    }

    console.error(error.isAbort ? "request aborted" : error.cause);
  },
);

An HTTP error exposes status, statusText, headers, url, and redirected directly. Its body is read once and stored in text; if that read fails, bodyError contains the reason. Redirect handling is the native fetch behavior and can be configured with RequestInit.redirect.

Validate values with Zod

import { z } from "zod";
import { validate } from "@lebedevna/neverthrow-utils";

const userSchema = z.object({ id: z.string(), email: z.email() });
const result = validate({ id: "u_1", email: "[email protected]" }, userSchema);

result.match(
  (value) => console.log(value.email),
  (error) => console.error(error.type), // "validation error"
);

Agent Skill

This package ships the typed-error-flows Agent Skill for TanStack Intent. Allow the package in your project's package.json:

{
  "intent": {
    "skills": ["@lebedevna/neverthrow-utils"]
  }
}

Then discover or load the installed skill:

pnpm dlx @tanstack/intent@latest list
pnpm dlx @tanstack/intent@latest load @lebedevna/neverthrow-utils#typed-error-flows

Links

• GitHub repository
• Issue tracker
• neverthrow

License

ISC