resultar 1.4.5 → 2.0.0-beta.2

package/README.md

@@ -1,1657 +1,877 @@
 # Resultar
 
-## About
-
-Resultar is a TypeScript library for robust, type-safe error handling without throwing exceptions. It's a fork of the excellent [neverthrow](https://github.com/supermacro/neverthrow) library, adding features for more flexibility in error handling
-
-In the spirit of open-source development, **resultar** builds upon the solid foundation laid by neverthrow, extending its functionality to better suit specific needs. It introduces additional methods and functions such as tap, safeTryAsync, and fromThrowableAsync and finally providing more flexibility and control in error handling.
-
-## Description
-
-Encode failure into your program.
-
-This package contains a `Result` type that represents either success (`Ok`) or failure (`Err`).
-
-For asynchronous tasks, `resultar` offers a `ResultAsync` class which wraps a `Promise<Result<T, E>>` and gives you the same level of expressivity and control as a regular `Result<T, E>`.
-
-`ResultAsync` is `thenable` meaning it **behaves exactly like a native `Promise<Result>`** ... except you have access to the same methods that `Result` provides without having to `await` or `.then` the promise!
-
-### Check out [the wiki](https://github.com/inaiat/resultar/wiki) for examples and best practices.
-
-<div id="toc"></div>
-
-## Table Of Contents
-
-* [Installation](#installation)
-* [Top-Level API](#top-level-api)
-* [API Documentation](#api-documentation)
-  + [Synchronous API (`Result`)](#synchronous-api-result)
-    - [`ok`](#ok)
-    - [`err`](#err)
-    - [`unit`](#unit)
-    - [`Result.isOk` (method)](#resultisok-method)
-    - [`Result.isErr` (method)](#resultiserr-method)
-    - [`Result.map` (method)](#resultmap-method)
-    - [`Result.mapErr` (method)](#resultmaperr-method)
-    - [`Result.unwrapOr` (method)](#resultunwrapor-method)
-    - [`Result.andThen` (method)](#resultandthen-method)
-    - [`Result.asyncAndThen` (method)](#resultasyncandthen-method)
-    - [`Result.orElse` (method)](#resultorelse-method)
-    - [`Result.tap` (method)](#resulttap-method)
-    - [`Result.tapError` (method)](#resulttaperror-method)
-    - [`Result.log` (method)](#resultlog-method)
-    - [`Result.finally` (method)](#resultfinally-method)
-    - [`Result.match` (method)](#resultmatch-method)
-    - [`Result.asyncMap` (method)](#resultasyncmap-method)
-    - [`Result.fromThrowable` (static class method)](#resultfromthrowable-static-class-method)
-    - [`Result.combine` (static class method)](#resultcombine-static-class-method)
-    - [`Result.combineWithAllErrors` (static class method)](#resultcombinewithallerrors-static-class-method)
-    - [`Result.safeUnwrap()`](#resultsafeunwrap)
-    - [`Result.tryCatch` (static class method)](#resulttrycatch-static-class-method)
-  + [Asynchronous API (`ResultAsync`)](#asynchronous-api-resultasync)
-    - [`okAsync`](#okasync)
-    - [`errAsync`](#errasync)
-    - [`unitAsync`](#unitasync)
-    - [`ResultAsync.fromPromise` (static class method)](#resultasyncfrompromise-static-class-method)
-    - [`ResultAsync.fromSafePromise` (static class method)](#resultasyncfromsafepromise-static-class-method)
-    - [`ResultAsync.fromThrowable` (static class method)](#resultasyncfromthrowable-static-class-method)
-    - [`ResultAsync.map` (method)](#resultasyncmap-method)
-    - [`ResultAsync.mapErr` (method)](#resultasyncmaperr-method)
-    - [`ResultAsync.unwrapOr` (method)](#resultasyncunwrapor-method)
-    - [`ResultAsync.andThen` (method)](#resultasyncandthen-method)
-    - [`ResultAsync.orElse` (method)](#resultasyncorelse-method)
-    - [`ResultAsync.tap` (method)](#resultasynctap-method)
-    - [`ResultAsync.tapError` (method)](#resultasynctaperror-method)
-    - [`ResultAsync.finally` (method)](#resultasyncfinally-method)
-    - [`ResultAsync.match` (method)](#resultasyncmatch-method)
-    - [`ResultAsync.combine` (static class method)](#resultasynccombine-static-class-method)
-    - [`ResultAsync.combineWithAllErrors` (static class method)](#resultasynccombinewithallerrors-static-class-method)
-    - [`ResultAsync.safeUnwrap()`](#resultasyncsafeunwrap)
-    - [`ResultAsync.tryCatch` (static class method)](#resultasynctrycatch-static-class-method)
-  + [Utilities](#utilities)
-    - [`fromThrowable`](#fromthrowable)
-    - [`fromThrowableAsync`](#fromthrowableasync)
-    - [`fromPromise`](#frompromise)
-    - [`fromSafePromise`](#fromsafepromise)
-    - [`safeTry`](#safetry)
-    - [`tryCatch`](#trycatch)
-    - [`tryCatchAsync`](#trycatchasync)
-  + [Testing](#testing)
-* [A note on the Package Name](#a-note-on-the-package-name)
-
-## Installation
+Typed `Result` primitives for TypeScript, with ergonomic tagged errors.
 
-```sh
-> npm install resultar
-```
-
-## Top-Level API
-
-`resultar` exposes the following:
-
-- `ok` convenience function to create an `Ok` variant of `Result`
-- `err` convenience function to create an `Err` variant of `Result`
-- `Ok` class and type
-- `Err` class and type
-- `Result` Type as well as namespace / object from which to call [`Result.fromThrowable`](#resultfromthrowable-static-class-method), [Result.combine](#resultcombine-static-class-method).
-- `ResultAsync` class
-- `okAsync` convenience function to create a `ResultAsync` containing an `Ok` type `Result`
-- `errAsync` convenience function to create a `ResultAsync` containing an `Err` type `Result`
-
-```typescript
-import {
-  ok,
-  Ok,
-  err,
-  Err,
-  Result,
-  okAsync,
-  errAsync,
-  ResultAsync,
-  fromThrowable,
-  fromPromise,
-  fromSafePromise,
-  safeTry,
-} from 'resultar'
-```
-
----
-
-**Check out the [wiki](https://github.com/inaiat/resultar/wiki) for help on how to make the most of `resultar`.**
-
----
-
-## API Documentation
-
-### Synchronous API (`Result`)
-
-#### `ok`
-
-Constructs an `Ok` variant of `Result`
-
-**Signature:**
-
-```typescript
-ok<T, E>(value: T): Ok<T, E> { ... }
-```
-
-**Example:**
-
-```typescript
-import { ok } from 'resultar'
-
-const myResult = ok({ myData: 'test' }) // instance of `Ok`
-
-myResult.isOk() // true
-myResult.isErr() // false
-```
+Resultar began as an initial fork of `neverthrow`. The v2 direction keeps the explicit `Result`
+wrapper model while evolving toward Resultar-specific tagged errors, strict service-boundary types,
+and TypeScript 6-ready ESM packaging.
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `err`
-
-Constructs an `Err` variant of `Result`
-
-**Signature:**
-
-```typescript
-err<T, E>(error: E): Err<T, E> { ... }
-```
+Resultar models fallible work explicitly:
 
-**Example:**
-
-```typescript
-import { err } from 'resultar'
-
-const myResult = err('Oh noooo') // instance of `Err`
-
-myResult.isOk() // false
-myResult.isErr() // true
-```
-
-[⬆️  Back to top](#toc)
----
-
-#### `unit`
-
-Returns a `Result` with a `value` of `undefined`.
-
-**Signature:**
-```typescript
-unit(): Result<undefined, never> { ... }
+```ts
+Result<T, E>
+ResultAsync<T, E>
+StrictResult<T, E extends Error>
+StrictResultAsync<T, E extends Error>
 ```
-[⬆️  Back to top](#toc)
----
 
-#### `Result.isOk` (method)
+Use `Result` when an operation can fail synchronously, `ResultAsync` when it returns a promise, and
+tagged errors when you want strongly typed `Error` classes with stable tags and metadata.
+Prefer `StrictResult` and `StrictResultAsync` at service boundaries so expected failures are real
+`Error` instances with `message`, `cause`, stack traces, and structured metadata.
 
-Returns `true` if the result is an `Ok` variant
+## Requirements
 
-**Signature:**
+- ESM only
+- Node.js 24+
+- TypeScript 6-ready
 
-```typescript
-isOk(): boolean { ... }
+```ts
+import { ok, err, createTaggedError } from 'resultar'
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.isErr` (method)
+CommonJS `require('resultar')` is not exported.
 
-Returns `true` if the result is an `Err` variant
+## Install
 
-**Signature**:
-
-```typescript
-isErr(): boolean { ... }
+```sh
+pnpm add resultar
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.map` (method)
-
-Maps a `Result<T, E>` to `Result<U, E>` by applying a function to a contained `Ok` value, leaving an `Err` value untouched.
-
-This function can be used to compose the results of two functions.
-
-**Signature:**
-
-```typescript
-class Result<T, E> {
-  map<U>(callback: (value: T) => U): Result<U, E> { ... }
-}
+```sh
+npm install resultar
 ```
 
-**Example**:
-
-```typescript
-import { getLines } from 'imaginary-parser'
-// ^ assume getLines has the following signature:
-// getLines(str: string): Result<Array<string>, Error>
-
-// since the formatting is deemed correct by `getLines`
-// then it means that `linesResult` is an Ok
-// containing an Array of strings for each line of code
-const linesResult = getLines('1\n2\n3\n4\n')
+## V2 Deprecation Notice
 
-// this Result now has a Array<number> inside it
-const newResult = linesResult.map(
-  (arr: Array<string>) => arr.map(parseInt)
-)
-
-newResult.isOk() // true
-```
+The `2.0.0` line removes deprecated APIs before stable release:
 
-[⬆️  Back to top](#toc)
+| Removed API | Use instead |
+| --- | --- |
+| `Result#finally(fn)` | `Result#log(fn)` for immediate side effects, or `Result#toDisposable(fn)` for Node.js `using` cleanup |
+| `ResultAsync#finally(fn)` | `ResultAsync#log(fn)` for immediate side effects, or `ResultAsync#toAsyncDisposable(fn)` for Node.js `await using` cleanup |
+| `ResultAsync#safeUnwrap()` | `yield* resultAsync` inside `safeTry(async function* () { ... })` |
+| `safeTryAsync(...)` | `safeTry(async function* () { ... })` |
 
----
+`Result#safeUnwrap()` remains available for compatibility, but new code should prefer `yield* result`.
 
-#### `Result.mapErr` (method)
+## Philosophy
 
-Maps a `Result<T, E>` to `Result<T, F>` by applying a function to a contained `Err` value, leaving an `Ok` value untouched.
+Resultar is a small explicit-result library, not an application runtime or an Effect-style framework.
+It focuses on three things:
 
-This function can be used to pass through a successful result while handling an error.
+- Make expected failures visible in function signatures.
+- Compose sync and async fallible work without `try/catch` control-flow blocks.
+- Keep expected application failures observable by modeling them as real typed `Error` values.
 
-**Signature:**
+The core model stays intentionally simple:
 
-```typescript
-class Result<T, E> {
-  mapErr<F>(callback: (error: E) => F): Result<T, F> { ... }
-}
+```ts
+Result<T, E>
+ResultAsync<T, E>
 ```
 
-**Example**:
+Use generic `Result<T, E>` when local code benefits from lightweight strings, enums, or domain
+objects. Use `StrictResult<T, E extends Error>` and `StrictResultAsync<T, E extends Error>` when a
+failure can cross a module, service, HTTP, job, or integration boundary.
 
-```typescript
-import { parseHeaders } from 'imaginary-http-parser'
-// imagine that parseHeaders has the following signature:
-// parseHeaders(raw: string): Result<SomeKeyValueMap, ParseError>
+## Recommended Production Style
 
-const rawHeaders = 'nonsensical gibberish and badly formatted stuff'
+For backend and application code, prefer this stack:
 
-const parseResult = parseHeaders(rawHeaders)
+1. Define expected domain/application failures with `createTaggedError`.
+2. Return them through `StrictResult` or `StrictResultAsync`.
+3. Compose with `map`, `andThen`, `asyncAndThen`, `orElse`, `catchTag`, and `catchTags`.
+4. Map outcomes at boundaries with `matchTags` or `matchTagsPartial`.
+5. Use `tap`, `tapError`, and `log` only for best-effort side effects.
 
-parseResult.mapErr(parseError => {
-  res.status(400).json({
-    error: parseError
-  })
-})
-
-parseResult.isErr() // true
-```
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.unwrapOr` (method)
+```ts
+import type { StrictResult } from 'resultar'
 
-Unwrap the `Ok` value, or return the default if there is an `Err`
+import { createTaggedError, ok } from 'resultar'
 
-**Signature:**
+class UserAlreadyExistsError extends createTaggedError({
+  name: 'UserAlreadyExistsError',
+  message: 'User $email already exists',
+}) {}
 
-```typescript
-class Result<T, E> {
-  unwrapOr<T>(value: T): T { ... }
-}
+const ensureUserDoesNotExist = (
+  email: string,
+): StrictResult<string, UserAlreadyExistsError> =>
+  email === 'taken@example.com' ? UserAlreadyExistsError.err({ email }) : ok(email)
 ```
 
-**Example**:
-
-```typescript
-const myResult = err('Oh noooo')
+Avoid using strings or loose objects for production-facing expected failures:
 
-const multiply = (value: number): number => value * 2
-
-const unwrapped: number = myResult.map(multiply).unwrapOr(10)
+```ts
+// Local-only style. Avoid at service boundaries.
+type ParseError = 'InvalidPort'
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.andThen` (method)
-
-Same idea as `map` above. Except you must return a new `Result`.
+### No-Discard Check
 
-The returned value will be a `Result`. As of `v4.1.0-beta`, you are able to return distinct error types (see signature below). Prior to `v4.1.0-beta`, the error type could not be distinct.
+Resultar ships a type-aware check for discarded `Result` and `ResultAsync` values:
 
-This is useful for when you need to do a subsequent computation using the inner `T` value, but that computation might fail.
-
-Additionally, `andThen` is really useful as a tool to flatten a `Result<Result<A, E2>, E1>` into a `Result<A, E2>` (see example below).
-
-**Signature:**
-
-```typescript
-class Result<T, E> {
-  // Note that the latest version lets you return distinct errors as well.
-  // If the error types (E and F) are the same (like `string | string`)
-  // then they will be merged into one type (`string`)
-  andThen<U, F>(
-    callback: (value: T) => Result<U, F>
-  ): Result<U, E | F> { ... }
+```json
+{
+  "scripts": {
+    "lint:resultar": "resultar-no-discard --project tsconfig.json"
+  }
 }
 ```
 
-**Example 1: Chaining Results**
-
-```typescript
-import { err, ok } from 'resultar'
-
-const sq = (n: number): Result<number, number> => ok(n ** 2)
+It fails code that ignores a returned result:
 
-ok(2)
-  .andThen(sq)
-  .andThen(sq) // Ok(16)
-
-ok(2)
-  .andThen(sq)
-  .andThen(err) // Err(4)
-
-ok(2)
-  .andThen(err)
-  .andThen(sq) // Err(2)
-
-err(3)
-  .andThen(sq)
-  .andThen(sq) // Err(3)
-```
-
-**Example 2: Flattening Nested Results**
-
-```typescript
-// It's common to have nested Results
-const nested = ok(ok(1234))
-
-// notNested is a Ok(1234)
-const notNested = nested.andThen((innerResult) => innerResult)
+```ts
+saveUser(input)
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.asyncAndThen` (method)
-
-Same idea as [`andThen` above](#resultandthen-method), except you must return a new `ResultAsync`.
-
-The returned value will be a `ResultAsync`.
-
-**Signature:**
+Handle the result, return it, or mark an intentional discard with `void`:
 
-```typescript
-class Result<T, E> {
-  asyncAndThen<U, F>(
-    callback: (value: T) => ResultAsync<U, F>
-  ): ResultAsync<U, E | F> { ... }
-}
+```ts
+const result = saveUser(input)
+return saveUser(input)
+void saveUser(input)
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.orElse` (method)
-
-Takes an `Err` value and maps it to a `Result<T, SomeNewType>`. This is useful for error recovery.
-
-**Signature:**
+For Oxlint users, run it next to Oxlint because this rule needs TypeScript return-type information:
 
-```typescript
-class Result<T, E> {
-  orElse<A>(
-    callback: (error: E) => Result<T, A>
-  ): Result<T, A> { ... }
+```json
+{
+  "scripts": {
+    "lint": "oxlint && resultar-no-discard --project tsconfig.json"
+  }
 }
 ```
 
-**Example:**
-
-```typescript
-enum DatabaseError {
-  PoolExhausted = 'PoolExhausted',
-  NotFound = 'NotFound',
-}
-
-const dbQueryResult: Result<string, DatabaseError> = err(DatabaseError.NotFound)
-
-const updatedQueryResult = dbQueryResult.orElse((dbError) =>
-  dbError === DatabaseError.NotFound
-    ? ok('User does not exist') // error recovery branch: ok() must be called with a value of type string
-    //
-    //
-    // err() can be called with a value of any new type that you want
-    // it could also be called with the same error value
-    //
-    //     err(dbError)
-    : err(500)
-)
-```
+## API Decision Guide
 
-[⬆️  Back to top](#toc)
+Use `map` when the `Ok` value changes and the transform cannot fail.
 
----
+Use `andThen` when the next step can fail and returns another `Result`. Use `asyncAndThen` when a
+sync `Result` continues into `ResultAsync`.
 
-#### `Result.match` (method)
+Use `mapErr` when the error value changes. Use `orElse` when an error should recover into another
+`Result`.
 
-Given 2 functions (one for the `Ok` variant and one for the `Err` variant) execute the function that matches the `Result` variant.
+Use `catchTag` or `catchTags` for local recovery from tagged errors. `catchTags` is intentionally
+partial: unhandled tags stay in the error channel.
 
-Match callbacks do not necessitate to return a `Result`, however you can return a `Result` if you want to.
+Use `match` for simple boundaries. Use `matchTags` when every tagged error must be handled. Use
+`matchTagsPartial` when only selected tagged errors need custom handling and the rest should go to a
+fallback.
 
-**Signature:**
+Use `fromPromise(promise, toError)` when you already have a promise. Use
+`tryCatchAsync(() => promiseFactory(), toError)` when creating the promise can throw synchronously.
 
-```typescript
-class Result<T, E> {
-  match<A>(
-    okCallback: (value: T) =>  A,
-    errorCallback: (error: E) =>  A
-  ): A => { ... }
-}
-```
+Use `tryCatch` / `tryCatchAsync` at the edge of uncontrolled code: JSON parsing, third-party
+libraries, I/O, network calls, and other APIs that throw or reject. Keep your own domain functions
+returning `Result` values instead of throwing expected failures.
 
-`match` is like chaining `map` and `mapErr`, with the distinction that with `match` both functions must have the same return type.
-The differences between `match` and chaining `map` and `mapErr` are that:
-- with `match` both functions must have the same return type `A`
-- `match` unwraps the `Result<T, E>` into an `A` (the match functions' return type)
-  - This makes no difference if you are performing side effects only
-
-**Example:**
-
-```typescript
-// map/mapErr api
-// note that you DON'T have to append mapErr
-// after map which means that you are not required to do
-// error handling
-computationThatMightFail().map(console.log).mapErr(console.error)
-
-// match api
-// works exactly the same as above since both callbacks
-// only perform side effects,
-// except, now you HAVE to do error handling :)
-computationThatMightFail().match(console.log, console.error)
-
-// Returning values
-const attempt = computationThatMightFail()
-  .map((str) => str.toUpperCase())
-  .mapErr((err) => `Error: ${err}`)
-// `attempt` is of type `Result<string, string>`
-
-const answer = computationThatMightFail().match(
-  (str) => str.toUpperCase(),
-  (err) => `Error: ${err}`
-)
-// `answer` is of type `string`
-```
+## Quick Start
 
-If you don't use the error parameter in your match callback then `match` is equivalent to chaining `map` with `unwrapOr`:
 ```ts
-const answer = computationThatMightFail().match(
-  (str) => str.toUpperCase(),
-  () => 'ComputationError'
-)
-// `answer` is of type `string`
-
-const answer = computationThatMightFail()
-  .map((str) => str.toUpperCase())
-  .unwrapOr('ComputationError')
-```
+import type { StrictResult } from 'resultar'
 
+import { createTaggedError, ok } from 'resultar'
 
-[⬆️  Back to top](#toc)
+class InvalidPortError extends createTaggedError({
+  name: 'InvalidPortError',
+  message: 'Invalid port $value',
+}) {}
 
----
+const parsePort = (value: string): StrictResult<number, InvalidPortError> => {
+  const port = Number(value)
 
-#### `Result.asyncMap` (method)
-
-Similar to `map` except for two things:
-
-- the mapping function must return a `Promise`
-- asyncMap returns a `ResultAsync`
-
-You can then chain the result of `asyncMap` using the `ResultAsync` apis (like `map`, `mapErr`, `andThen`, etc.)
-
-**Signature:**
-
-```typescript
-class Result<T, E> {
-  asyncMap<U>(
-    callback: (value: T) => Promise<U>
-  ): ResultAsync<U, E> { ... }
+  return Number.isInteger(port) && port > 0
+    ? ok(port)
+    : InvalidPortError.err({ value })
 }
-```
-
-**Example:**
-
-```typescript
-import { parseHeaders } from 'imaginary-http-parser'
-// imagine that parseHeaders has the following signature:
-// parseHeaders(raw: string): Result<SomeKeyValueMap, ParseError>
-
-const asyncRes = parseHeaders(rawHeader)
-  .map(headerKvMap => headerKvMap.Authorization)
-  .asyncMap(findUserInDatabase)
-```
-
-Note that in the above example if `parseHeaders` returns an `Err` then `.map` and `.asyncMap` will not be invoked, and `asyncRes` variable will resolve to an `Err` when turned into a `Result` using `await` or `.then()`.
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.fromThrowable` (static class method)
-
-> Although Result is not an actual JS class, the way that `fromThrowable` has been implemented requires that you call `fromThrowable` as though it were a static method on `Result`. See examples below.
-
-The JavaScript community has agreed on the convention of throwing exceptions.
-As such, when interfacing with third party libraries it's imperative that you
-wrap third-party code in try / catch blocks.
-
-This function will create a new function that returns an `Err` when the original
-function throws.
-
-It is not possible to know the types of the errors thrown in the original
-function, therefore it is recommended to use the second argument `errorFn` to
-map what is thrown to a known type.
-
-**Example**:
 
-```typescript
-import { Result } from 'resultar'
-
-type ParseError = { message: string }
-const toParseError = (): ParseError => ({ message: "Parse Error" })
-
-const safeJsonParse = Result.fromThrowable(JSON.parse, toParseError)
-
-// the function can now be used safely, if the function throws, the result will be an Err
-const res = safeJsonParse("{");
+const message = parsePort('3000').match(
+  (port) => `Listening on ${port}`,
+  (error) => error.message,
+)
 ```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `Result.combine` (static class method)
-
-> Although Result is not an actual JS class, the way that `combine` has been implemented requires that you call `combine` as though it were a static method on `Result`. See examples below.
-
-Combine lists of `Result`s.
-
-If you're familiar with `Promise.all`, the combine function works conceptually the same.
-
-**`combine` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `Result`s and still be able to combine them. Note that you cannot combine lists that contain both `Result`s **and** `ResultAsync`s.
-
-The combine function takes a list of results and returns a single result. If all the results in the list are `Ok`, then the return value will be a `Ok` containing a list of all the individual `Ok` values.
-
-If just one of the results in the list is an `Err` then the combine function returns that Err value (it short circuits and returns the first Err that it finds).
-
-Formally speaking:
+## Strict Results
 
-```typescript
-// homogeneous lists
-function combine<T, E>(resultList: Result<T, E>[]): Result<T[], E>
+`StrictResult<T, E extends Error>` and `StrictResultAsync<T, E extends Error>` are type-only aliases
+for code that should return only `Error`-based failures.
 
-// heterogeneous lists
-function combine<T1, T2, E1, E2>(resultList: [ Result<T1, E1>, Result<T2, E2> ]): Result<[ T1, T2 ], E1 | E2>
-function combine<T1, T2, T3, E1, E2, E3> => Result<[ T1, T2, T3 ], E1 | E2 | E3>
-function combine<T1, T2, T3, T4, E1, E2, E3, E4> => Result<[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4>
-// ... etc etc ad infinitum
-
-```
-
-Example:
-```typescript
-const resultList: Result<number, never>[] =
-  [ok(1), ok(2)]
-
-const combinedList: Result<number[], unknown> =
-  Result.combine(resultList)
-```
+```ts
+import type { StrictResult } from 'resultar'
 
-Example with tuples:
-```typescript
-/** @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] */
-const tuple = <T extends any[]>(...args: T): T => args
+import { createTaggedError, ok } from 'resultar'
 
-const resultTuple: [Result<string, never>, Result<string, never>] =
-  tuple(ok('a'), ok('b'))
+class InvalidEmailError extends createTaggedError({
+  name: 'InvalidEmailError',
+  message: 'Invalid email $email',
+}) {}
 
-const combinedTuple: Result<[string, string], unknown> =
-  Result.combine(resultTuple)
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes('@') ? ok(email) : InvalidEmailError.err({ email })
 ```
 
-[⬆️  Back to top](#toc)
+Use generic `Result<T, E>` for small local flows where strings, enums, or lightweight domain objects
+are useful. Prefer `StrictResult` for application and backend service boundaries where logging,
+`cause`, stack traces, and tagged-error matching matter.
 
----
+## Expected Failure Style
 
-#### `Result.combineWithAllErrors` (static class method)
+For expected application and domain failures, prefer `createTaggedError` classes and return them
+through `StrictResult` or `StrictResultAsync`.
 
-> Although Result is not an actual JS class, the way that `combineWithAllErrors` has been implemented requires that you call `combineWithAllErrors` as though it were a static method on `Result`. See examples below.
-
-Like `combine` but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.
-
-If only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.
-
-Function signature:
-
-```typescript
-// homogeneous lists
-function combineWithAllErrors<T, E>(resultList: Result<T, E>[]): Result<T[], E[]>
-
-// heterogeneous lists
-function combineWithAllErrors<T1, T2, E1, E2>(resultList: [ Result<T1, E1>, Result<T2, E2> ]): Result<[ T1, T2 ], (E1 | E2)[]>
-function combineWithAllErrors<T1, T2, T3, E1, E2, E3> => Result<[ T1, T2, T3 ], (E1 | E2 | E3)[]>
-function combineWithAllErrors<T1, T2, T3, T4, E1, E2, E3, E4> => Result<[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]>
-// ... etc etc ad infinitum
+```ts
+class UserAlreadyExistsError extends createTaggedError({
+  name: 'UserAlreadyExistsError',
+  message: 'User $email already exists',
+}) {}
 ```
 
-Example usage:
+Plain `Error` subclasses from libraries and runtimes are still valid in strict results when their
+identity is already useful, such as validation, database, abort, or platform errors. Keep
+`Err<string>`, `Err<object>`, and `TaggedEnum` for narrow local flows where stack traces, `cause`,
+structured logging, and boundary matching do not matter.
 
-```typescript
-const resultList: Result<number, string>[] = [
-  ok(123),
-  err('boooom!'),
-  ok(456),
-  err('ahhhhh!'),
-]
+## Result
 
-const result = Result.combineWithAllErrors(resultList)
+`Result<T, E>` is either `Ok<T>` or `Err<E>`.
 
-// result is Err(['boooom!', 'ahhhhh!'])
-```
-
-[⬆️  Back to top](#toc)
-
-#### `Result.safeUnwrap()`
-
-Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate.
+```ts
+import type { StrictResult } from 'resultar'
 
-[⬆️  Back to top](#toc)
+import { createTaggedError, ok } from 'resultar'
 
-#### `Result.tryCatch()` (static class method)
+class UserNotFoundError extends createTaggedError({
+  name: 'UserNotFoundError',
+  message: 'User $id not found',
+}) {}
 
-Provides a convenient way to handle errors in a procedural style, similar to Go's error handling pattern. It wraps a synchronous function call in a try-catch block and returns a Result that can be destructured to access the value or error.
+const findUser = (id: string): StrictResult<{ id: string }, UserNotFoundError> =>
+  id === 'usr_123' ? ok({ id }) : UserNotFoundError.err({ id })
 
-**Signature:**
-```typescript
-static tryCatch<T, E>(fn: () => Exclude<T, Promise<any>>, errorFn?: (e: unknown) => E): Result<T, E>
-```
+const result = findUser('usr_123')
 
-**Example:**
-```typescript
-const divide = (a: number, b: number) => {
-  if (b === 0) throw new Error("Cannot divide by zero");
-  return a / b;
-};
-
-// Using destructuring to handle errors procedurally
-const { value, error } = Result.tryCatch(() => divide(10, 2));
-if (error) {
-  console.error("Division failed:", error);
-} else {
-  console.log("Result:", value); // Result: 5
+if (result.isOk()) {
+  result.value.id
 }
 
-// With custom error handling
-const result = Result.tryCatch(
-  () => divide(10, 0),
-  (e) => `Division error: ${e.message}`
-);
 if (result.isErr()) {
-  console.error(result.error); // Division error: Cannot divide by zero
+  result.error.message
 }
 ```
 
+### Chaining
 
-[⬆️  Back to top](#toc)
-
----
-
-### Asynchronous API (`ResultAsync`)
-
-#### `okAsync`
-
-Constructs an `Ok` variant of `ResultAsync`
-
-**Signature:**
-
-```typescript
-okAsync<T, E>(value: T): ResultAsync<T, E>
-```
-
-**Example:**
-
-```typescript
-import { okAsync } from 'resultar'
-
-const myResultAsync = okAsync({ myData: 'test' }) // instance of `ResultAsync`
-
-const myResult = await myResultAsync // instance of `Ok`
-
-myResult.isOk() // true
-myResult.isErr() // false
-```
+Use `map` for infallible transforms and `andThen` for fallible transforms.
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `errAsync`
-
-Constructs an `Err` variant of `ResultAsync`
-
-**Signature:**
-
-```typescript
-errAsync<T, E>(error: E): ResultAsync<T, E>
-```
-
-**Example:**
-
-```typescript
-import { errAsync } from 'resultar'
-
-const myResultAsync = errAsync('Oh nooo') // instance of `ResultAsync`
-
-const myResult = await myResultAsync // instance of `Err`
-
-myResult.isOk() // false
-myResult.isErr() // true
-```
+```ts
+import type { StrictResult } from 'resultar'
 
-[⬆️  Back to top](#toc)
+import { createTaggedError, ok } from 'resultar'
 
----
+type User = {
+  readonly email: string
+}
 
-#### `unitAsync`
+class InvalidEmailError extends createTaggedError({
+  name: 'InvalidEmailError',
+  message: 'Invalid email $email',
+}) {}
 
-Constructs a `ResultAsync` with a `value` of `undefined`.
+class InvalidDomainError extends createTaggedError({
+  name: 'InvalidDomainError',
+  message: 'Invalid email domain $domain',
+}) {}
 
-**Signature:**
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes('@') ? ok(email) : InvalidEmailError.err({ email })
 
-```typescript
-unit<E = never>(error: E): ResultAsync<undefined, E>
+const createUser = (email: string): StrictResult<User, InvalidEmailError> =>
+  validateEmail(email).map((validEmail) => ({ email: validEmail }))
 ```
 
-**Example:**
-
-```typescript
-import { errAsync } from 'resultar'
-
-const myResultAsync =unitAsync() // instance of `ResultAsync`
+Use `filterOrElse` when a successful value must satisfy an extra predicate:
 
-const myResult = await myResultAsync // instance of `Err`
-
-myResult.isOk() // false
-myResult.value() // undefined
+```ts
+const validateCompanyEmail = (
+  email: string,
+): StrictResult<string, InvalidEmailError | InvalidDomainError> =>
+  validateEmail(email).filterOrElse(
+    (validEmail) => validEmail.endsWith('@company.com'),
+    (validEmail) => new InvalidDomainError({ domain: validEmail.split('@')[1] ?? 'unknown' }),
+  )
 ```
 
-[⬆️  Back to top](#toc)
+Generic `Result<T, E>` still supports strings, enums, and lightweight objects for narrow local flows.
+For application and backend service boundaries, prefer `StrictResult<T, E extends Error>` with
+`createTaggedError`.
 
----
+Use `pipe` when you want to apply reusable Result combinators:
 
-#### `ResultAsync.fromThrowable` (static class method)
-
-Similar to [Result.fromThrowable](#resultfromthrowable-static-class-method), but for functions that return a `Promise`.
-
-**Example**:
-
-```typescript
-import { ResultAsync } from 'neverthrow'
-import { insertIntoDb } from 'imaginary-database'
-// insertIntoDb(user: User): Promise<User>
+```ts
+const audit =
+  <T, E>(result: Result<T, E>): Result<T, E> =>
+    result.tap((value) => console.log('created', value))
 
-const insertUser = ResultAsync.fromThrowable(insertIntoDb, () => new Error('Database error'))
-// `res` has a type of (user: User) => ResultAsync<User, Error>
+const result = createUser('person@example.com').pipe(
+  audit,
+  (userResult) => userResult.map((user) => user.email),
+)
 ```
 
-Note that this can be safer than using [ResultAsync.fromPromise](#resultasyncfrompromise-static-class-method) with
-the result of a function call, because not all functions that return a `Promise` are `async`, and thus they can throw
-errors synchronously rather than returning a rejected `Promise`. For example:
+### Matching
 
-```typescript
-import { readFile } from 'node:fs/promises'
-import { fromThrowableAsync } from 'resultar'
+Use `match` at boundaries.
 
-const safeFileReader = fromThrowableAsync(
-  async (file: string) => readFile(file),
-  e => new Error('Oops: '.concat(String(e))),
+```ts
+const response = createUser('person@example.com').match(
+  (user) => ({ body: user, statusCode: 201 }),
+  (error) => ({ body: { error }, statusCode: 400 }),
 )
-const value = await safeFileReader('foo.txt')
-
-if (value.isOk()) {
-  console.log(value.value.toString())
-}
 ```
 
-[⬆️  Back to top](#toc)
+## ResultAsync
 
----
+`ResultAsync<T, E>` wraps `Promise<Result<T, E>>` and keeps the same composition style.
 
-#### `ResultAsync.fromPromise` (static class method)
+```ts
+import type { StrictResultAsync } from 'resultar'
 
-Transforms a `PromiseLike<T>` (that may throw) into a `ResultAsync<T, E>`.
+import { createTaggedError, fromPromise } from 'resultar'
 
-The second argument handles the rejection case of the promise and maps the error from `unknown` into some type `E`.
+type User = {
+  readonly id: string
+}
 
+class FetchUserError extends createTaggedError({
+  name: 'FetchUserError',
+  message: 'Failed to fetch user $id',
+}) {}
 
-**Signature:**
+const fetchUser = (id: string): StrictResultAsync<User, FetchUserError> =>
+  fromPromise(
+    fetch(`https://example.com/users/${id}`).then((response) => response.json() as Promise<User>),
+    (cause) => new FetchUserError({ cause, id }),
+  )
 
-```typescript
-// fromPromise is a static class method
-// also available as a standalone function
-// import { fromPromise } from 'resultar'
-ResultAsync.fromPromise<T, E>(
-  promise: PromiseLike<T>,
-  errorHandler: (unknownError: unknown) => E)
-): ResultAsync<T, E> { ... }
+const label = await fetchUser('usr_123').match(
+  (user) => `User ${user.id}`,
+  (error) => error.message,
+)
 ```
 
-If you are working with `PromiseLike` objects that you **know for a fact** will not throw, then use `fromSafePromise` in order to avoid having to pass a redundant `errorHandler` argument.
+## Tagged Errors
 
-**Example**:
+Tagged errors are real `Error` subclasses with:
 
-```typescript
-import { ResultAsync } from 'resultar'
-import { insertIntoDb } from 'imaginary-database'
-// insertIntoDb(user: User): Promise<User>
+- `_tag`
+- inferred constructor props from `$variables` in the message template
+- `messageTemplate`
+- `fingerprint`
+- `cause`
+- `.toJSON()`
+- `.findCause(ErrorClass)`
+- static `.is(value)` using `instanceof` for nominal class checks
+- static `.err(props)`
 
-const res = ResultAsync.fromPromise(insertIntoDb(myUser), () => new Error('Database error'))
-// `res` has a type of ResultAsync<User, Error>
-```
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `ResultAsync.fromSafePromise` (static class method)
+```ts
+import { createTaggedError } from 'resultar'
 
-Same as `ResultAsync.fromPromise` except that it does not handle the rejection of the promise. **Ensure you know what you're doing, otherwise a thrown exception within this promise will cause ResultAsync to reject, instead of resolve to a Result.**
+class UserNotFoundError extends createTaggedError({
+  name: 'UserNotFoundError',
+  message: 'User $id not found in $source',
+}) {}
 
-**Signature:**
+const error = new UserNotFoundError({
+  id: 'usr_123',
+  source: 'database',
+})
 
-```typescript
-// fromPromise is a static class method
-// also available as a standalone function
-// import { fromPromise } from 'resultar'
-ResultAsync.fromSafePromise<T, E>(
-  promise: PromiseLike<T>
-): ResultAsync<T, E> { ... }
+error instanceof Error // true
+error instanceof UserNotFoundError // true
+error._tag // 'UserNotFoundError'
+error.message // 'User usr_123 not found in database'
+error.id // string | number
+error.source // string | number
 ```
 
-**Example**:
-
-```typescript
-import { RouteError } from 'routes/error'
+Missing template props are TypeScript errors:
 
-// simulate slow routes in an http server that works in a Result / ResultAsync context
-// Adopted from https://github.com/parlez-vous/server/blob/2496bacf55a2acbebc30631b5562f34272794d76/src/routes/common/signup.ts
-export const slowDown = <T>(ms: number) => (value: T) =>
-  ResultAsync.fromSafePromise<T, RouteError>(
-    new Promise((resolve) => {
-      setTimeout(() => {
-        resolve(value)
-      }, ms)
-    })
-  )
+```ts
+new UserNotFoundError({ id: 'usr_123', source: 'database' })
 
-export const signupHandler = route<User>((req, sessionManager) =>
-  decode(userSignupDecoder, req.body, 'Invalid request body').map((parsed) => {
-    return createUser(parsed)
-      .andThen(slowDown(3000)) // slowdown by 3 seconds
-      .andThen(sessionManager.createSession)
-      .map(({ sessionToken, admin }) => AppData.init(admin, sessionToken))
-  })
-)
+// @ts-expect-error source is required
+new UserNotFoundError({ id: 'usr_123' })
 ```
 
+Reserved template variables are rejected because they would conflict with `Error` or tagged-error
+metadata:
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `ResultAsync.map` (method)
-
-Maps a `ResultAsync<T, E>` to `ResultAsync<U, E>` by applying a function to a contained `Ok` value, leaving an `Err` value untouched.
-
-The applied function can be synchronous or asynchronous (returning a `Promise<U>`) with no impact to the return type.
-
-This function can be used to compose the results of two functions.
-
-**Signature:**
-
-```typescript
-class ResultAsync<T, E> {
-  map<U>(
-    callback: (value: T) => U | Promise<U>
-  ): ResultAsync<U, E> { ... }
-}
+```ts
+// @ts-expect-error name is reserved
+createTaggedError({ name: 'BadError', message: 'Bad $name' })
 ```
 
-**Example**:
+Reserved variables are `_tag`, `name`, `message`, `messageTemplate`, `fingerprint`, `stack`, and
+`cause`.
 
-```typescript
-import { findUsersIn } from 'imaginary-database'
-// ^ assume findUsersIn has the following signature:
-// findUsersIn(country: string): ResultAsync<Array<User>, Error>
+For lightweight tagged domain unions that do not need to extend `Error`, use `TaggedEnum`:
 
-const usersInCanada = findUsersIn("Canada")
+```ts
+import type { TaggedEnum } from 'resultar'
 
-// Let's assume we only need their names
-const namesInCanada = usersInCanada.map((users: Array<User>) => users.map(user => user.name))
-// namesInCanada is of type ResultAsync<Array<string>, Error>
+type PaymentError = TaggedEnum<{
+  CardDeclined: { readonly code: string }
+  InsufficientFunds: { readonly balance: number }
+}>
 
-// We can extract the Result using .then() or await
-namesInCanada.then((namesResult: Result<Array<string>, Error>) => {
-  if(namesResult.isErr()){
-    console.log("Couldn't get the users from the database", namesResult.error)
-  }
-  else{
-    console.log("Users in Canada are named: " + namesResult.value.join(','))
-  }
-})
+const error: PaymentError = { _tag: 'CardDeclined', code: 'card_declined' }
 ```
 
-[⬆️  Back to top](#toc)
+## Tagged Errors With Result
 
----
+Tagged errors are most useful as the `E` side of `StrictResult<T, E>` and
+`StrictResultAsync<T, E>`.
 
-#### `ResultAsync.mapErr` (method)
+```ts
+import type { StrictResult } from 'resultar'
 
-Maps a `ResultAsync<T, E>` to `ResultAsync<T, F>` by applying a function to a contained `Err` value, leaving an `Ok` value untouched.
+import { createTaggedError, ok } from 'resultar'
 
-The applied function can be synchronous or asynchronous (returning a `Promise<F>`) with no impact to the return type.
+class InvalidEmailError extends createTaggedError({
+  name: 'InvalidEmailError',
+  message: 'Invalid email $email',
+}) {}
 
-This function can be used to pass through a successful result while handling an error.
+class UserAlreadyExistsError extends createTaggedError({
+  name: 'UserAlreadyExistsError',
+  message: 'User $email already exists',
+}) {}
 
-**Signature:**
+class DatabaseError extends createTaggedError({
+  name: 'DatabaseError',
+  message: 'Database operation $operation failed',
+}) {}
 
-```typescript
-class ResultAsync<T, E> {
-  mapErr<F>(
-    callback: (error: E) => F | Promise<F>
-  ): ResultAsync<T, F> { ... }
+type User = {
+  readonly email: string
+  readonly id: string
 }
-```
 
-**Example**:
+type CreateUserError = InvalidEmailError | UserAlreadyExistsError | DatabaseError
 
-```typescript
-import { findUsersIn } from 'imaginary-database'
-// ^ assume findUsersIn has the following signature:
-// findUsersIn(country: string): ResultAsync<Array<User>, Error>
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes('@') ? ok(email) : InvalidEmailError.err({ email })
 
-// Let's say we need to low-level errors from findUsersIn to be more readable
-const usersInCanada = findUsersIn("Canada").mapErr((error: Error) => {
-  // The only error we want to pass to the user is "Unknown country"
-  if(error.message === "Unknown country"){
-    return error.message
+const ensureUserDoesNotExist = (
+  email: string,
+): StrictResult<string, UserAlreadyExistsError | DatabaseError> => {
+  if (email === 'taken@example.com') {
+    return UserAlreadyExistsError.err({ email })
   }
-  // All other errors will be labelled as a system error
-  return "System error, please contact an administrator."
-})
-
-// usersInCanada is of type ResultAsync<Array<User>, string>
-
-usersInCanada.then((usersResult: Result<Array<User>, string>) => {
-  if(usersResult.isErr()){
-    res.status(400).json({
-      error: usersResult.error
-    })
-  }
-  else{
-    res.status(200).json({
-      users: usersResult.value
-    })
-  }
-})
-```
 
-[⬆️  Back to top](#toc)
-
----
-
-#### `ResultAsync.unwrapOr` (method)
-
-Unwrap the `Ok` value, or return the default if there is an `Err`.
-Works just like `Result.unwrapOr` but returns a `Promise<T>` instead of `T`.
-
-**Signature:**
-
-```typescript
-class ResultAsync<T, E> {
-  unwrapOr<T>(value: T): Promise<T> { ... }
+  return ok(email)
 }
-```
 
-**Example**:
+const insertUser = (email: string): StrictResult<User, DatabaseError> =>
+  ok({ email, id: 'usr_123' })
 
-```typescript
-const unwrapped: number = await errAsync(0).unwrapOr(10)
-// unwrapped = 10
+const createUser = (email: string): StrictResult<User, CreateUserError> =>
+  validateEmail(email)
+    .andThen(ensureUserDoesNotExist)
+    .andThen(insertUser)
 ```
 
-[⬆️  Back to top](#toc)
+`InvalidEmailError.err({ email })` returns `Result<never, InvalidEmailError>`. Because `never` is assignable to every success type, it works naturally in functions returning `Result<string, InvalidEmailError>`.
 
----
+Use `catchTag` when one tagged error can be recovered locally:
 
-#### `ResultAsync.andThen` (method)
-
-Same idea as `map` above. Except the applied function must return a `Result` or `ResultAsync`.
-
-`ResultAsync.andThen` always returns a `ResultAsync` no matter the return type of the applied function.
-
-This is useful for when you need to do a subsequent computation using the inner `T` value, but that computation might fail.
-
-`andThen` is really useful as a tool to flatten a `ResultAsync<ResultAsync<A, E2>, E1>` into a `ResultAsync<A, E2>` (see example below).
-
-**Signature:**
-
-```typescript
-// Note that the latest version (v4.1.0-beta) lets you return distinct errors as well.
-// If the error types (E and F) are the same (like `string | string`)
-// then they will be merged into one type (`string`)
-
-class ResultAsync<T, E> {
-  andThen<U, F>(
-    callback: (value: T) => Result<U, F> | ResultAsync<U, F>
-  ): ResultAsync<U, E | F> { ... }
-}
+```ts
+const result = createUser('bad-email').catchTag('InvalidEmailError', (error) =>
+  ok({
+    email: error.email,
+    id: 'draft_user',
+  }),
+)
 ```
 
-**Example**
-
-```typescript
-
-import { validateUser } from 'imaginary-validator'
-import { insertUser } from 'imaginary-database'
-import { sendNotification } from 'imaginary-service'
+Use `catchTags` when a small set of tagged errors share local recovery:
 
-// ^ assume validateUser, insertUser and sendNotification have the following signatures:
-// validateUser(user: User): Result<User, Error>
-// insertUser(user): ResultAsync<User, Error>
-// sendNotification(user): ResultAsync<void, Error>
-
-const resAsync = validateUser(user)
-               .andThen(insertUser)
-               .andThen(sendNotification)
-
-// resAsync is a ResultAsync<void, Error>
-
-resAsync.then((res: Result<void, Error>) => {
-  if(res.isErr()){
-    console.log("Oops, at least one step failed", res.error)
-  }
-  else{
-    console.log("User has been validated, inserted and notified successfully.")
-  }
+```ts
+const result = createUser('taken@example.com').catchTags({
+  InvalidEmailError: (error) => ok({ email: error.email, id: 'draft_user' }),
+  UserAlreadyExistsError: (error) => ok({ email: error.email, id: 'existing_user' }),
 })
 ```
 
-[⬆️  Back to top](#toc)
-
----
-#### `Result.tap` (method)
-Executes a side effect function with the `Ok` value and returns the original `Result`.
-This method is useful for performing actions that do not modify the `Result` itself, such as logging or updating external state.
-**Signature:**
-```typescript
-class ResultAsync<T, E> {
-  tap(fn: (t: T) => void): Result<T, E>  {
-}
-```
-
-**Example:**
-```typescript
-import { ok } from "resultar"
-import { equal }  from 'node:assert'
-
-const foo = ok("foo")
-const value  = foo
-  .tap(console.error) // Prints "foo"
-  .map((value) => value.toUpperCase())
-  .tap(console.error) // Prints "FOO"
-  .match((v)=> v, (error) => "")
-equal(value, "FOO")
-```
-[⬆️  Back to top](#toc)
-
----
-#### `Result.tapError` (method)
-Executes a side effect function with the `Err` value and returns the original `Result`.
-This method is useful for performing actions that do not modify the `Result` itself, such as logging or updating external state.
-**Signature:**
-```typescript
-class ResultAsync<T, E> {
-  tapError(fn: (e: E) => void): Result<T, E> {
-}
-```
-
-**Example:**
-```typescript
-import { err } from "resultar"
-import { equal }  from 'node:assert'
-
-const fooError = err("foo")
-const value  = fooError
-  .tapError(console.error) // Prints "foo"
-  .orElse((error) => {
-    return err("bar")
-  })
-  .tapError(console.error) // Prints "bar"
-  .match(()=> "", (error) => error)
-equal(value, "bar")
-// mapped.value === 'foo'
-```
-[⬆️  Back to top](#toc)
+`catchTags` is intentionally partial: any unhandled error tag stays in the `Err` side. A separate
+`partialCatchTags` API would duplicate this behavior.
 
----
+At the boundary, use `matchTags` for direct success and tagged-error response mapping:
 
----
-#### `Result.log` (method)
-
-**Executes a side effect function with the `Ok` or `Err` value and returns the original `Result`.
-This method is useful for performing actions that do not modify the `Result` itself, such as logging or updating external state.**
-
-**Signature:**
-```typescript
-class Result<T, E> {
-  log(fn: (t?: T, e?: E) => void): this {
+```ts
+const result = createUser('taken@example.com')
+
+const response = result.matchTags(
+  (user) => ({
+    body: user,
+    statusCode: 201,
+  }),
+  {
+    InvalidEmailError: (err) => ({
+      body: { code: err._tag, message: err.message },
+      statusCode: 400,
+    }),
+    UserAlreadyExistsError: (err) => ({
+      body: { code: err._tag, message: err.message },
+      statusCode: 409,
+    }),
+    DatabaseError: (err) => ({
+      body: { code: err._tag, message: err.message },
+      statusCode: 500,
+    }),
+  },
+)
 ```
 
-**Example:**
-```typescript
-
-const reader = ok(file) // content file is line 01
+If a handler is missing, TypeScript reports it. For partial boundary matching, use
+`matchTagsPartial(okHandler, handlers, fallback)`:
 
-reader
-  .log((value, error) => {
-    console.log("Logging file content:", error ? error : value)
-  })
-  .map(it => it.content)
-  .finally(_ => {
-    console.info('Closing file handle')
-    file.close()
-  })
-  .match((value) => {
-    console.log(value) // print line 01
-  }, (error) => {
-    console.error("Oops, something went wrong", error)
-  })
+```ts
+const response = result.matchTagsPartial(
+  (user) => ({
+    body: user,
+    statusCode: 201,
+  }),
+  {
+    InvalidEmailError: (err) => ({
+      body: { code: err._tag, message: err.message },
+      statusCode: 400,
+    }),
+  },
+  (err) => ({
+    body: { code: 'UnhandledError', message: err.message },
+    statusCode: 500,
+  }),
+)
 ```
-[⬆️  Back to top](#toc)
 
----
+Use `catchTags` for pipeline recovery and `matchTagsPartial` for boundary mapping.
 
-#### `Result.finally` (method)
-Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources.
-**Signature:**
-```typescript
-class Result<T, E> {
-  finally(f: (value: T, error: E) => void): DisposableResult<T, E> {..}
-}
-```
+When the error union includes plain or untagged `Error`, add an `Error` fallback. Use standalone `matchError` when you only have an error value rather than a `Result`.
 
-**Example:**
-```typescript
-const reader = ok(file) // content file is line 01
+```ts
+declare const error: InvalidEmailError | DatabaseError | Error
 
-const result = reader.map(it => it.content).finally(_ => {
-  file.close()
+const message = matchError(error, {
+  DatabaseError: (err) => err.message,
+  Error: (err) => err.message,
+  InvalidEmailError: (err) => err.message,
 })
-
-if (resul.isOk()) {
-  console.log(result.value) // print line 01
-}
-
 ```
-[⬆️  Back to top](#toc)
 
----
-
-#### `ResultAsync.orElse` (method)
-
-Takes an `Err` value and maps it to a `ResultAsync<T, SomeNewType>`. This is useful for error recovery.
-
-**Signature:**
-
-```typescript
-class ResultAsync<T, E> {
-  orElse<A>(
-    callback: (error: E) => Result<T, A> | ResultAsync<T, A>
-  ): ResultAsync<T, A> { ... }
-}
-```
+## Partial Matching
 
-[⬆️  Back to top](#toc)
+Use `matchErrorPartial` when only some tagged errors need special handling.
 
----
+```ts
+import { matchErrorPartial } from 'resultar'
 
-#### `ResultAsync.tap` (method)
+declare const error: InvalidEmailError | UserAlreadyExistsError | DatabaseError
 
-Executes a side effect function with the `Ok` value and returns the original `ResultAsync`.
-This method is useful for performing actions that do not modify the `ResultAsyn` itself, such as logging or updating external state.
-**Signature:**
-```typescript
-class ResultAsync<T, E> {
-  tap(f: (t: T) => void | Promise<void>): ResultAsync<T, E> {...}
-}
+const message = matchErrorPartial(
+  error,
+  {
+    InvalidEmailError: (err) => `Invalid input: ${err.email}`,
+  },
+  (err) => err.message,
+)
 ```
 
-**Example:**
-See [`Result.tap` (method)](#resulttap-method)
+## Causes
 
+Tagged errors support native `cause` and cause-chain lookup.
 
-[⬆️  Back to top](#toc)
-
----
+```ts
+import { findCause } from 'resultar'
 
-#### `ResultAsync.tapError` (method)
+const cause = new Error('connection refused')
+const error = new DatabaseError({
+  cause,
+  operation: 'insert-user',
+})
 
-Executes a side effect function with the `Ok` value and returns the original `ResultAsync`.
-This method is useful for performing actions that do not modify the `ResultAsyn` itself, such as logging or updating external state.
-**Signature:**
-```typescript
-class ResultAsync<T, E> {
-  tapError(f: (e: E) => void | Promise<void>): ResultAsync<T, E> {...}
-}
+error.cause // cause
+findCause(error, Error) // cause
+error.findCause(Error) // cause
 ```
 
-**Example:**
-See [`Result.tapError` (method)](#resulttaperror-method)
-
-
-[⬆️  Back to top](#toc)
+Cause lookup is cycle-safe: circular cause chains stop and return `undefined` when no matching cause
+exists.
 
+## Safe Try
 
----
-
-#### `ResultAsync.finally` (method)
-Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources for async operations.
-**Signature:**
-```typescript
-class ResultAsync<T, E> {
-  finally(f: (value: T, error: E) => void): DisposableResultAsync<T, E> {...}
-}
-```
+`safeTry` lets you unwrap successful results inside a generator and return early on the first error.
 
-**Example:**
-```typescript
-const fileHandle = await fs.open('foo.txt', 'w')
+The shortest form is `yield* result`. `yield* result.safeUnwrap()` is still supported, but usually not necessary.
 
-const result
-  = await fromPromise(fileHandle.write('A new line of text'), String)
-    .finally(async () => {
-      console.info('Closing file handle')
-      await fileHandle.close()
-    })
-
-if (result.isOk()) {
-  console.log(result.value) // == 'A new line of text'
-}
-
-```
+```ts
+import type { Result, ResultAsync } from 'resultar'
 
-[⬆️  Back to top](#toc)
+import { ok, safeTry } from 'resultar'
 
----
+declare const readConfig: () => Result<{ port: string }, Error>
+declare const parsePort: (value: string) => Result<number, Error>
+declare const persistPort: (port: number) => ResultAsync<void, Error>
 
-#### `ResultAsync.match` (method)
+const loadPort = (): Result<number, Error> =>
+  safeTry(function* () {
+    const config = yield* readConfig()
+    const port = yield* parsePort(config.port)
 
-Given 2 functions (one for the `Ok` variant and one for the `Err` variant) execute the function that matches the `ResultAsync` variant.
+    return ok(port)
+  })
 
-The difference with `Result.match` is that it always returns a `Promise` because of the asynchronous nature of the `ResultAsync`.
+const savePort = (): ResultAsync<number, Error> =>
+  safeTry(async function* () {
+    const config = yield* readConfig()
+    const port = yield* parsePort(config.port)
 
-**Signature:**
+    yield* persistPort(port)
 
-```typescript
-class ResultAsync<T, E> {
-  match<A>(
-    okCallback: (value: T) =>  A,
-    errorCallback: (error: E) =>  A
-  ): Promise<A> => { ... }
-}
+    return ok(port)
+  })
 ```
 
-**Example:**
+## Side Effects
 
-```typescript
+Use `tap`, `tapError`, and `log` for best-effort observation. They are not transform methods: use
+`map`, `mapErr`, `andThen`, or `orElse` when the value or error should change.
 
-import { validateUser } from 'imaginary-validator'
-import { insertUser } from 'imaginary-database'
+`tap(fn)` runs only for `Ok` and returns the original result unchanged.
 
-// ^ assume validateUser and insertUser have the following signatures:
-// validateUser(user: User): Result<User, Error>
-// insertUser(user): ResultAsync<User, Error>
+```ts
+import { ok } from 'resultar'
 
-// Handle both cases at the end of the chain using match
-const resultMessage = await validateUser(user)
-        .andThen(insertUser)
-        .match(
-            (user: User) => `User ${user.name} has been successfully created`,
-            (error: Error) =>  `User could not be created because ${error.message}`
-        )
+const result = ok({ id: 'usr_123' }).tap((user) => {
+  console.info('user loaded', user.id)
+})
 
-// resultMessage is a string
+// still Result<{ id: string }, never>
+result
 ```
 
-[⬆️  Back to top](#toc)
-
----
+`tapError(fn)` runs only for `Err` and returns the original result unchanged.
 
-#### `ResultAsync.combine` (static class method)
-
-Combine lists of `ResultAsync`s.
-
-If you're familiar with `Promise.all`, the combine function works conceptually the same.
-
-**`combine` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `ResultAsync`s and still be able to combine them. Note that you cannot combine lists that contain both `Result`s **and** `ResultAsync`s.
-
-The combine function takes a list of results and returns a single result. If all the results in the list are `Ok`, then the return value will be a `Ok` containing a list of all the individual `Ok` values.
-
-If just one of the results in the list is an `Err` then the combine function returns that Err value (it short circuits and returns the first Err that it finds).
-
-Formally speaking:
-
-```typescript
-// homogeneous lists
-function combine<T, E>(resultList: ResultAsync<T, E>[]): ResultAsync<T[], E>
-
-// heterogeneous lists
-function combine<T1, T2, E1, E2>(resultList: [ ResultAsync<T1, E1>, ResultAsync<T2, E2> ]): ResultAsync<[ T1, T2 ], E1 | E2>
-function combine<T1, T2, T3, E1, E2, E3> => ResultAsync<[ T1, T2, T3 ], E1 | E2 | E3>
-function combine<T1, T2, T3, T4, E1, E2, E3, E4> => ResultAsync<[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4>
-// ... etc etc ad infinitum
-
-```
+```ts
+import { err } from 'resultar'
 
-Example:
-```typescript
-const resultList: ResultAsync<number, never>[] =
-  [okAsync(1), okAsync(2)]
+const result = err(new Error('database unavailable')).tapError((error) => {
+  console.error('load failed', error)
+})
 
-const combinedList: ResultAsync<number[], unknown> =
-  ResultAsync.combine(resultList)
+// still Result<never, Error>
+result
 ```
 
-Example with tuples:
-```typescript
-/** @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] */
-const tuple = <T extends any[]>(...args: T): T => args
+`log(fn)` runs for both states. For `Ok`, the callback receives `(value, undefined)`. For `Err`, it
+receives `(undefined, error)`.
 
-const resultTuple: [ResultAsync<string, never>, ResultAsync<string, never>] =
-  tuple(okAsync('a'), okAsync('b'))
+```ts
+const result = findUser('usr_123').log((user, error) => {
+  if (error) {
+    console.error('find user failed', error)
+    return
+  }
 
-const combinedTuple: ResultAsync<[string, string], unknown> =
-  ResultAsync.combine(resultTuple)
+  console.info('find user succeeded', user)
+})
 ```
-[⬆️  Back to top](#toc)
-
----
-
-#### `ResultAsync.combineWithAllErrors` (static class method)
-
-Like `combine` but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.
-
-If only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.
 
-Function signature:
+For `ResultAsync`, these callbacks may be synchronous or asynchronous. The original async result is
+still preserved, even if the callback throws or rejects.
 
-```typescript
-// homogeneous lists
-function combineWithAllErrors<T, E>(resultList: ResultAsync<T, E>[]): ResultAsync<T[], E[]>
-
-// heterogeneous lists
-function combineWithAllErrors<T1, T2, E1, E2>(resultList: [ ResultAsync<T1, E1>, ResultAsync<T2, E2> ]): ResultAsync<[ T1, T2 ], (E1 | E2)[]>
-function combineWithAllErrors<T1, T2, T3, E1, E2, E3> => ResultAsync<[ T1, T2, T3 ], (E1 | E2 | E3)[]>
-function combineWithAllErrors<T1, T2, T3, T4, E1, E2, E3, E4> => ResultAsync<[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]>
-// ... etc etc ad infinitum
+```ts
+const result = fetchUser('usr_123')
+  .tap((user) => metrics.increment('user.found', { id: user.id }))
+  .tapError((error) => metrics.increment('user.failed', { message: error.message }))
+  .log((user, error) => audit.write({ error, user }))
 ```
 
-Example usage:
-
-```typescript
-const resultList: ResultAsync<number, string>[] = [
-  okAsync(123),
-  errAsync('boooom!'),
-  okAsync(456),
-  errAsync('ahhhhh!'),
-]
+For Node.js 24 cleanup, use `toDisposable(fn)` or `toAsyncDisposable(fn)`. Those APIs defer cleanup
+until the resource is disposed with `using`, `await using`, or the matching symbol method.
 
-const result = ResultAsync.combineWithAllErrors(resultList)
+```ts
+using result = findUser('usr_123').toDisposable((_user, _error) => {
+  span.end()
+})
 
-// result is Err(['boooom!', 'ahhhhh!'])
+await using asyncResult = fetchUser('usr_123').toAsyncDisposable(async (_user, _error) => {
+  await span.end()
+})
 ```
 
-#### `ResultAsync.safeUnwrap()`
+Callback errors thrown by `tap`, `tapError`, `log`, and disposable cleanup are intentionally ignored
+so observability or cleanup code does not replace the original result. For `ResultAsync`, rejected
+callback promises are ignored too. Put fallible work in `andThen`, `orElse`, `tryCatch`, or
+`tryCatchAsync` when those failures should become part of the result type.
 
-Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate.
+## Coming From Other Styles
 
-[⬆️  Back to top](#toc)
+### From try/catch
 
-#### `ResultAsync.tryCatch()` (static class method)
+Use `tryCatch` and `tryCatchAsync` only where uncontrolled code can throw. Convert that failure into
+a typed error once, then return `Result` values from your own code.
 
-Similar to `Result.tryCatch`, but for handling asynchronous operations. It wraps a Promise in a try-catch block and returns a ResultAsync that can be awaited and destructured to access the value or error.
-
-**Signature:**
-```typescript
-static tryCatch<T, E>(fn: Promise<T>, errorFn?: (e: unknown) => E): ResultAsync<T, E>
-```
-
-**Example:**
-```typescript
-const divideAsync = async (a: number, b: number) => {
-  await new Promise(resolve => setTimeout(resolve, 100)); // Simulate async operation
-  if (b === 0) throw new Error("Cannot divide by zero");
-  return a / b;
-};
-
-// Using async/await with destructuring
-const { value, error } = await ResultAsync.tryCatch(divideAsync(10, 2));
-if (error) {
-  console.error("Async division failed:", error);
-} else {
-  console.log("Result:", value); // Result: 5
-}
-
-// With custom error handling
-const result = await ResultAsync.tryCatch(
-  divideAsync(10, 0),
-  (e) => `Async division error: ${e.message}`
-);
-if (result.isErr()) {
-  console.error(result.error); // Async division error: Cannot divide by zero
-}
+```ts
+const parseConfig = (input: string): StrictResult<Config, ParseConfigError> =>
+  tryCatch(
+    () => JSON.parse(input) as Config,
+    (cause) => new ParseConfigError({ cause }),
+  )
 ```
 
-The `tryCatch` methods provide a more familiar error handling pattern for developers coming from languages like Go, while still maintaining the type safety and composability of the Result type.
-
-[⬆️  Back to top](#toc)
-
----
-
-### Utilities
+### From neverthrow-style wrappers
+
+Resultar keeps the wrapper model, but recommends tagged `Error` values for production error
+channels. Use `.value` only after `isOk()` and `.error` only after `isErr()`, or prefer `match` /
+`matchTags` at boundaries.
+
+### From raw `T | Error`
+
+Raw unions are concise, but they rely on a convention that successful values are never `Error`
+instances. Resultar keeps success and failure structurally separate, so `Ok<Error>` is still a valid
+success value when a domain needs it.
+
+### From Effect
+
+Resultar does not provide dependency injection, fibers, scopes, schedules, streams, or a runtime. It
+borrows the useful discipline of typed expected errors and composable recovery while staying a small
+library around `Result` and `ResultAsync`.
+
+## API
+
+### Result Helpers
+
+- `ok(value)`
+- `err(error)`
+- `unit()`
+- `tryCatch(fn, errorFn?)`
+- `fromThrowable(fn, errorFn?)`
+- `safeTry(generator)`
+- `StrictResult<T, E extends Error>` type alias for Error-only failure channels
+
+### Result Methods
+
+- `isOk()`
+- `isErr()`
+- `map(fn)`
+- `mapErr(fn)`
+- `filterOrElse(predicate, onFalse)`
+- `andThen(fn)`
+- `asyncAndThen(fn)`
+- `orElse(fn)`
+- `catchTag(tag, fn)`
+- `catchTags(handlers)`
+- `tap(fn)` run a side effect only when `Ok`; preserves the original result
+- `tapError(fn)` run a side effect only when `Err`; preserves the original result
+- `log(fn)` run a side effect for both states as `(value, error)`; preserves the original result
+- `toDisposable(fn)` create a Node.js `Disposable` result for `using`
+- `match(okFn, errFn)`
+- `matchTags(okFn, handlers)`
+- `matchTagsPartial(okFn, handlers, fallback)`
+- `pipe(fn, ...)`
+- `asyncMap(fn)`
+- `unwrapOr(defaultValue)`
+- `unwrapOrThrow()`
+- `_unsafeUnwrap()`
+- `_unsafeUnwrapErr()`
+- `safeUnwrap()`
+
+### Result Static Methods
+
+- `Result.ok(value)`
+- `Result.err(error)`
+- `Result.unit()`
+- `Result.tryCatch(fn, errorFn?)`
+- `Result.fromThrowable(fn, errorFn?)`
+- `Result.combine(results)`
+- `Result.combineWithAllErrors(results)`
+
+### ResultAsync Helpers
+
+- `okAsync(value)`
+- `errAsync(error)`
+- `unitAsync()`
+- `fromPromise(promise, errorFn)`
+- `fromSafePromise(promise)`
+- `fromThrowableAsync(fn, errorFn?)`
+- `tryCatchAsync(promiseOrFn, errorFn?)` catches rejections and synchronous throws from factories
+- `StrictResultAsync<T, E extends Error>` type alias for Error-only async failure channels
+
+### ResultAsync Methods
+
+- `map(fn)`
+- `mapErr(fn)`
+- `andThen(fn)`
+- `orElse(fn)`
+- `tap(fn)` run a sync or async side effect only when `Ok`; preserves the original result
+- `tapError(fn)` run a sync or async side effect only when `Err`; preserves the original result
+- `log(fn)` run a sync or async side effect for both states as `(value, error)`
+- `toAsyncDisposable(fn)` create a Node.js `AsyncDisposable` result for `await using`
+- `match(okFn, errFn)`
+- `matchTags(okFn, handlers)`
+- `matchTagsPartial(okFn, handlers, fallback)`
+- `unwrapOr(defaultValue)`
+- `unwrapOrThrow()`
+
+### Tagged Error Helpers
+
+- `createTaggedError(options)`
+- `matchError(error, handlers)`
+- `matchErrorPartial(error, handlers, fallback)`
+- `isError(value)`
+- `findCause(error, ErrorClass)`
+- `TaggedEnum<Members>` type helper
+
+## Testing
+
+`_unsafeUnwrap()` and `_unsafeUnwrapErr()` are intended for tests.
 
-#### `fromThrowable`
-
-Top level export of `Result.fromThrowable`.
-Please find documentation at [Result.fromThrowable](#resultfromthrowable-static-class-method)
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `fromThrowableAsync`
-
-Top level export of `ResultAsync.fromThrowable`.
-Please find documentation at [ResultAsync.fromThrowable](#resultasyncfromthrowable-static-class-method)
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `fromPromise`
-
-Top level export of `ResultAsync.fromPromise`.
-Please find documentation at [ResultAsync.fromPromise](#resultasyncfrompromise-static-class-method)
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `tryCatch`
-
-Top level export of `Result.tryCatch`.
-Please find documentation at [Result.tryCatch](#resulttrycatch-static-class-method)
-
-[⬆️  Back to top](#toc)
-
----
-
-#### `tryCatchAsync`
-
-Top level export of `ResultAsync.tryCatch`.
-Please find documentation at [ResultAsync.tryCatch](#resultasynctrycatch-static-class-method)
-
-[⬆️  Back to top](#toc)
-
-#### `fromSafePromise`
-
-Top level export of `ResultAsync.fromSafePromise`.
-Please find documentation at [ResultAsync.fromSafePromise](#resulttasyncfromsafepromise-static-class-method)
-
-[⬆️  Back to top](#toc)
-
-
-#### `safeTry`
-
-Used to implicityly return errors and reduce boilerplate.
-
-Let's say we are writing a function that returns a `Result`, and in that function we call some functions which also return `Result`s and we check those results to see whether we shold keep going or abort. Usually, we will write like the following.
-```typescript
-declare function mayFail1(): Result<number, string>;
-declare function mayFail2(): Result<number, string>;
-
-function myFunc(): Result<number, string> {
-    // We have to define a constant to hold the result to check and unwrap its value.
-    const result1 = mayFail1();
-    if (result1.isErr()) {
-        return err(`aborted by an error from 1st function, ${result1.error}`);
-    }
-    const value1 = result1.value
-
-    // Again, we need to define a constant and then check and unwrap.
-    const result2 = mayFail2();
-    if (result2.isErr()) {
-        return err(`aborted by an error from 2nd function, ${result2.error}`);
-    }
-    const value2 = result2.value
-
-    // And finally we return what we want to calculate
-    return ok(value1 + value2);
-}
-```
-Basically, we need to define a constant for each result to check whether it's a `Ok` and read its `.value` or `.error`.
-
-With safeTry, we can state 'Return here if its an `Err`, otherwise unwrap it here and keep going.' in just one expression.
-```typescript
-declare function mayFail1(): Result<number, string>;
-declare function mayFail2(): Result<number, string>;
-
-function myFunc(): Result<number, string> {
-    return safeTry<number, string>(function*() {
-        return ok(
-            // If the result of mayFail1().mapErr() is an `Err`, the evaluation is
-            // aborted here and the enclosing `safeTry` block is evaluated to that `Err`.
-            // Otherwise, this `(yield* ...)` is evaluated to its `.value`.
-            (yield* mayFail1()
-                .mapErr(e => `aborted by an error from 1st function, ${e}`)
-                .safeUnwrap())
-            +
-            // The same as above.
-            (yield* mayFail2()
-                .mapErr(e => `aborted by an error from 2nd function, ${e}`)
-                .safeUnwrap())
-        )
-    })
-}
-```
+```ts
+import { ok } from 'resultar'
 
-To use `safeTry`, the points are as follows.
-* Wrap the entire block in a [generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*)
-* In that block, you can use `yield* <RESULT>` to state 'Return `<RESULT>` if it's an `Err`, otherwise evaluate to its `.value`'
-* Pass the generator function to `safeTry`
-
-You can also use [async generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) to pass an async block to `safeTry`.
-```typescript
-// You can use either Promise<Result> or ResultAsync.
-declare function mayFail1(): Promise<Result<number, string>>;
-declare function mayFail2(): ResultAsync<number, string>;
-
-function myFunc(): Promise<Result<number, string>> {
-    return safeTry<number, string>(async function*() {
-        return ok(
-            // You have to await if the expression is Promise<Result>
-            (yield* (await mayFail1())
-                .mapErr(e => `aborted by an error from 1st function, ${e}`)
-                .safeUnwrap())
-            +
-            // You can call `safeUnwrap` directly if its ResultAsync
-            (yield* mayFail2()
-                .mapErr(e => `aborted by an error from 2nd function, ${e}`)
-                .safeUnwrap())
-        )
-    })
-}
+expect(ok(42)._unsafeUnwrap()).toBe(42)
 ```
 
-For more information, see https://github.com/supermacro/neverthrow/pull/448 and https://github.com/supermacro/neverthrow/issues/444
-
-[⬆️  Back to top](#toc)
-
----
-
-### Testing
+By default, thrown unwrap errors omit stack traces for cleaner test output. Pass `withStackTrace` if needed:
 
-`Result` instances have two unsafe methods, aptly called `_unsafeUnwrap` and `_unsafeUnwrapErr` which **should only be used in a test environment**.
-
-`_unsafeUnwrap` takes a `Result<T, E>` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.
-
-`_unsafeUnwrapErr` takes a `Result<T, E>` and returns a `E` when the result is an `Err`, otherwise it throws a custom object.
-
-That way you can do something like:
-
-```typescript
-expect(myResult._unsafeUnwrap()).toBe(someExpectation)
+```ts
+result._unsafeUnwrapErr({ withStackTrace: true })
 ```
 
-However, do note that `Result` instances are comparable. So you don't necessarily need to unwrap them in order to assert expectations in your tests. So you could also do something like this:
-
-```typescript
-import { ok } from 'resultar'
+## Development
 
-// ...
+This repository uses Vite+.
 
-expect(callSomeFunctionThatReturnsAResult("with", "some", "args")).toEqual(ok(someExpectation));
+```sh
+pnpm install
+pnpm run fmt:check
+pnpm run lint
+pnpm test
+pnpm run test:cov
+pnpm run build
+pnpm run check:full
 ```
 
-By default, the thrown value does not contain a stack trace. This is because stack trace generation [makes error messages in Jest harder to understand](https://github.com/supermacro/neverthrow/pull/215). If you want stack traces to be generated, call `_unsafeUnwrap` and / or `_unsafeUnwrapErr` with a config object:
-
-```typescript
-_unsafeUnwrapErr({
-  withStackTrace: true,
-})
-
-// ^ Now the error object will have a `.stack` property containing the current stack
-```
+Package output:
 
----
+- `dist/index.js`
+- `dist/index.js.map`
+- `dist/index.d.ts`
 
-### License
+## License
 
-The resultar project is available as open source under the terms of the [MIT license](https://github.com/inaiat/resultar/blob/master/LICENSE).
+MIT