errore 0.9.0 → 0.11.0

package/README.md

@@ -4,13 +4,20 @@ Type-safe errors as values for TypeScript. Like Go, but with full type inference
 
 ## Why?
 
-Instead of wrapping values in a `Result<T, E>` type, functions simply return `E | T`. TypeScript's type narrowing handles the rest:
+Instead of wrapping values in a `Result<T, E>` type, functions simply return `E | T`. TypeScript's **type narrowing** handles the rest:
 
 ```ts
 // Go-style: errors as values
-const user = await fetchUser(id)
-if (user instanceof Error) return user  // TypeScript narrows type
-console.log(user.name)                  // user is now User, not Error | User
+const user = await getUser(id)
+if (user instanceof NotFoundError) {
+  console.error('Missing:', user.id)
+  return
+}
+if (user instanceof DbError) {
+  console.error('DB failed:', user.reason)
+  return
+}
+console.log(user.username)  // user is User, fully narrowed
 ```
 
 ## Install
@@ -21,6 +28,8 @@ npm install errore
 
 ## Quick Start
 
+Define typed errors with **variable interpolation** and return **Error or Value** directly:
+
 ```ts
 import * as errore from 'errore'
 
@@ -67,7 +76,7 @@ console.log(user.name)
 
 ## Example: API Error Handling
 
-A complete example with custom base class, HTTP status codes, and error reporting:
+A complete example with **custom base class** and HTTP status codes:
 
 ```ts
 import * as errore from 'errore'
@@ -139,7 +148,7 @@ app.post('/users/:id', async (req, res) => {
 
 ### createTaggedError
 
-Create typed errors with `$variable` interpolation in the message:
+Create typed errors with **variable interpolation** in the message:
 
 ```ts
 import * as errore from 'errore'
@@ -186,8 +195,140 @@ err.statusCode  // 500 (inherited from AppError)
 err instanceof AppError  // true
 ```
 
+### Error Wrapping and Context
+
+Wrap errors with additional context while **preserving the original error** via `cause`:
+
+```ts
+// Wrap with context, preserve original in cause
+async function processUser(id: string): Promise<ServiceError | ProcessedUser> {
+  const user = await getUser(id)  // returns NotFoundError | User
+  
+  if (user instanceof Error) {
+    return new ServiceError({ id, cause: user })
+  }
+  
+  return process(user)
+}
+
+// Access original error via cause
+const result = await processUser('123')
+if (result instanceof Error) {
+  console.log(result.message)  // "Failed to process user 123"
+  
+  if (result.cause instanceof NotFoundError) {
+    console.log(result.cause.id)  // access original error's properties
+  }
+}
+```
+
+The error definitions:
+
+```ts
+import * as errore from 'errore'
+
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'User $id not found'
+}) {}
+
+class ServiceError extends errore.createTaggedError({
+  name: 'ServiceError',
+  message: 'Failed to process user $id'
+}) {}
+```
+
+**Browser console** prints the full cause chain:
+
+```
+ServiceError: Failed to process user 123
+    at processUser (app.js:12)
+    at main (app.js:20)
+Caused by: NotFoundError: User 123 not found
+    at getUser (app.js:5)
+    at processUser (app.js:8)
+```
+
+### findCause
+
+Walk the `.cause` chain to find an ancestor matching a specific error class. Similar to Go's `errors.As` — checks the error itself first, then traverses `.cause` recursively:
+
+```ts
+import * as errore from 'errore'
+
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'User $id not found'
+}) {}
+
+class ServiceError extends errore.createTaggedError({
+  name: 'ServiceError',
+  message: 'Failed to process user $id'
+}) {}
+
+// Deep chain: ServiceError -> NotFoundError
+const notFound = new NotFoundError({ id: '123' })
+const service = new ServiceError({ id: '123', cause: notFound })
+
+// Instance method on tagged errors
+const found = service.findCause(NotFoundError)
+found?.id  // '123' — type-safe access
+
+// Standalone function for any Error
+const found2 = errore.findCause(service, NotFoundError)
+found2?.id  // '123'
+```
+
+This solves the problem where `result.cause instanceof MyError` only checks one level deep. `findCause` walks the entire chain:
+
+```ts
+// A -> B -> C chain
+const c = new DbError({ message: 'connection reset' })
+const b = new ServiceError({ id: '123', cause: c })
+const a = new ApiError({ message: 'request failed', cause: b })
+
+// Manual check only finds B
+a.cause instanceof DbError  // false — only checks one level
+
+// findCause walks the full chain
+a.findCause(DbError)  // finds C ✓
+```
+
+Returns `undefined` if no matching ancestor is found. Safe against circular `.cause` references.
+
+### Custom Base Class with `extends`
+
+Use `extends` to inherit from a custom base class. The error will pass `instanceof` for both the base class and the specific error class:
+
+```ts
+import * as errore from 'errore'
+
+class AppError extends Error {
+  statusCode = 500
+  toResponse() { return { error: this.message, code: this.statusCode } }
+}
+
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'Resource $id not found',
+  extends: AppError
+}) {
+  statusCode = 404
+}
+
+const err = new NotFoundError({ id: '123' })
+err instanceof NotFoundError  // true
+err instanceof AppError       // true
+err instanceof Error          // true
+
+err.statusCode    // 404
+err.toResponse()  // { error: 'Resource 123 not found', code: 404 }
+```
+
 ### Type Guards
 
+Use **instanceof checks** to narrow union types:
+
 ```ts
 const result: NetworkError | User = await fetchUser(id)
 
@@ -200,14 +341,16 @@ if (result instanceof Error) {
 
 ### Try Functions
 
+**Wrap exceptions** as error values:
+
 ```ts
 import * as errore from 'errore'
 
 // Sync - wraps exceptions in UnhandledError
-const parsed = errore.tryFn(() => JSON.parse(input))
+const parsed = errore.try(() => JSON.parse(input))
 
 // Sync - with custom error type
-const parsed = errore.tryFn({
+const parsed = errore.try({
   try: () => JSON.parse(input),
   catch: e => new ParseError({ reason: e.message, cause: e })
 })
@@ -224,6 +367,8 @@ const response = await errore.tryAsync({
 
 ### Transformations
 
+**Transform and chain** operations:
+
 ```ts
 import * as errore from 'errore'
 
@@ -242,6 +387,8 @@ const logged = errore.tap(user, u => console.log('Got user:', u.name))
 
 ### Extraction
 
+**Extract values** or throw, **split arrays** by success/error:
+
 ```ts
 import * as errore from 'errore'
 
@@ -264,7 +411,7 @@ const [users, errors] = errore.partition(results)
 
 ### Error Matching
 
-Always assign `matchError` results to a variable. Keep callbacks pure (return values only) and move side effects outside:
+**Exhaustive pattern matching** with `matchError`. Always assign results to a variable and keep callbacks pure:
 
 ```ts
 import * as errore from 'errore'
@@ -298,7 +445,7 @@ ValidationError.is(value)  // specific class
 
 ## How Type Safety Works
 
-TypeScript narrows types after `instanceof Error` checks:
+TypeScript **narrows types** after `instanceof Error` checks:
 
 ```ts
 function example(result: NetworkError | User): string {
@@ -318,7 +465,7 @@ This works because:
 
 ## Result + Option Combined: `Error | T | null`
 
-One of errore's best features: you can naturally combine error handling with optional values. No wrapper nesting needed!
+Naturally combine **error handling with optional values**. No wrapper nesting needed!
 
 ```ts
 import * as errore from 'errore'
@@ -362,14 +509,80 @@ console.log(user.name)
 | Zig | `!?T` (error union + optional) | Yes, specific syntax |
 | **errore** | `Error \| T \| null` | **No!** Check in any order |
 
-With errore:
+With errore you **check in any order**:
 - Use `?.` and `??` naturally
 - Check `instanceof Error` or `=== null` in any order
 - No unwrapping ceremony
 - TypeScript infers everything
 
+## Why This Is Better Than Go
+
+Go's error handling uses **two separate return values**:
+
+```go
+user, err := fetchUser(id)
+// Oops! Forgot to check err
+fmt.Println(user.Name)  // Compiles fine, crashes at runtime
+```
+
+The compiler can't save you here. You can ignore `err` entirely and use `user` directly.
+
+With errore, **forgetting to check is impossible**:
+
+```ts
+const user = await fetchUser(id)  // type: NotFoundError | User
+
+console.log(user.id)  // TS Error: Property 'id' does not exist on type 'NotFoundError'
+```
+
+Since errore uses a **single union variable** instead of two separate values, TypeScript forces you to narrow the type before accessing value-specific properties. You literally cannot use the value without first doing an `instanceof Error` check.
+
+> **Note:** Properties that exist on both `Error` and your value type (like `name`, `message`) can still be accessed without narrowing. This is a small set of 4 fields: `name`, `message`, `stack`, `cause`.
+
+### The Remaining Gap
+
+There's still one case errore can't catch: **ignored return values**:
+
+```ts
+// Oops! Completely ignoring the return value
+updateUser(id, data)  // No error, but we should check!
+```
+
+For this, use **TypeScript's built-in checks** or a linter:
+
+**TypeScript `tsconfig.json`:**
+```json
+{
+  "compilerOptions": {
+    "noUnusedLocals": true
+  }
+}
+```
+
+This catches unused variables, though not ignored return values directly.
+
+**oxlint `no-unused-expressions`:**
+
+`oxlint.json`:
+```json
+{
+  "rules": {
+    "no-unused-expressions": "error"
+  }
+}
+```
+
+Or via CLI:
+```bash
+oxlint --deny no-unused-expressions
+```
+
+Combined with errore's type safety, these tools give you near-complete protection against ignored errors.
+
 ## Comparison with Result Types
 
+**Direct returns** vs wrapper methods:
+
 | Result Pattern | errore |
 |---------------|--------|
 | `Result.ok(value)` | just `return value` |
@@ -379,9 +592,150 @@ With errore:
 | `Result<User, Error>` | `Error \| User` |
 | `Result<Option<T>, E>` | `Error \| T \| null` |
 
+## Vs neverthrow / better-result
+
+These libraries wrap values in a **Result container**. You construct results with `ok()` and `err()`, then unwrap them with `.value` and `.error`:
+
+```ts
+// neverthrow
+import { ok, err, Result } from 'neverthrow'
+
+function getUser(id: string): Result<User, NotFoundError> {
+  const user = db.find(id)
+  if (!user) return err(new NotFoundError({ id }))
+  return ok(user)  // must wrap
+}
+
+const result = getUser('123')
+if (result.isErr()) {
+  console.log(result.error)  // must unwrap
+  return
+}
+console.log(result.value.name)  // must unwrap
+```
+
+```ts
+// errore
+function getUser(id: string): User | NotFoundError {
+  const user = db.find(id)
+  if (!user) return new NotFoundError({ id })
+  return user  // just return
+}
+
+const user = getUser('123')
+if (user instanceof Error) {
+  console.log(user)  // it's already the error
+  return
+}
+console.log(user.name)  // it's already the user
+```
+
+**The key insight**: `T | Error` already encodes success/failure. TypeScript's type narrowing does the rest. No wrapper needed.
+
+| Feature | neverthrow | errore |
+|---------|------------|--------|
+| Type-safe errors | ✓ | ✓ |
+| Exhaustive handling | ✓ | ✓ |
+| Works with null | `Result<T \| null, E>` | `T \| E \| null` |
+| Learning curve | New API (`ok`, `err`, `map`, `andThen`, ...) | Just `instanceof` |
+| Bundle size | ~3KB min | **~0 bytes** |
+| Interop | Requires wrapping/unwrapping at boundaries | Native TypeScript |
+
+neverthrow also requires an [eslint plugin](https://github.com/mdbetancourt/eslint-plugin-neverthrow) to catch unhandled results. With errore, TypeScript itself prevents you from using a value without checking the error first.
+
+## Vs Effect.ts
+
+Effect is not just error handling—it's a **complete functional programming framework** with dependency injection, concurrency primitives, resource management, streaming, and more.
+
+```ts
+// Effect.ts - a paradigm shift
+import { Effect, pipe } from 'effect'
+
+const program = pipe(
+  fetchUser(id),
+  Effect.flatMap(user => fetchPosts(user.id)),
+  Effect.map(posts => posts.filter(p => p.published)),
+  Effect.catchTag('NotFoundError', () => Effect.succeed([]))
+)
+
+const result = await Effect.runPromise(program)
+```
+
+```ts
+// errore - regular TypeScript
+const user = await fetchUser(id)
+if (user instanceof Error) return []
+
+const posts = await fetchPosts(user.id)
+if (posts instanceof Error) return []
+
+return posts.filter(p => p.published)
+```
+
+Effect is powerful if you need its full feature set. But if you just want type-safe errors:
+
+| | Effect | errore |
+|-|--------|--------|
+| Learning curve | Steep (new paradigm) | Minimal (just `instanceof`) |
+| Codebase impact | Pervasive (everything becomes an Effect) | Surgical (adopt incrementally) |
+| Bundle size | ~50KB+ | **~0 bytes** |
+| Use case | Full FP framework | Just error handling |
+
+**Use Effect** when you want dependency injection, structured concurrency, and the full functional programming experience.
+
+**Use errore** when you just want type-safe errors without rewriting your codebase.
+
+## Zero-Dependency Philosophy
+
+errore is more a **way of writing code** than a library. The core pattern requires nothing:
+
+```ts
+// You can write this without installing errore at all
+class NotFoundError extends Error {
+  readonly _tag = 'NotFoundError'
+  constructor(public id: string) {
+    super(`User ${id} not found`)
+  }
+}
+
+async function getUser(id: string): Promise<User | NotFoundError> {
+  const user = await db.find(id)
+  if (!user) return new NotFoundError(id)
+  return user
+}
+
+const user = await getUser('123')
+if (user instanceof Error) return user
+console.log(user.name)
+```
+
+The `errore` package just provides conveniences: `createTaggedError` for less boilerplate, `matchError` for exhaustive pattern matching, `tryAsync` for catching exceptions. But the core pattern—**errors as union types**—works with zero dependencies.
+
+### Perfect for Libraries
+
+Ideal for library authors. Return **plain TypeScript unions** instead of forcing users to adopt your error handling framework:
+
+```ts
+// ❌ Library that forces a dependency on users
+import { Result } from 'some-result-lib'
+export function parse(input: string): Result<AST, ParseError>
+
+// Users must now install and learn 'some-result-lib'
+```
+
+```ts
+// ✓ Library using plain TypeScript unions
+export function parse(input: string): AST | ParseError
+
+// Users handle errors with standard instanceof checks
+// No new dependencies, no new concepts to learn
+```
+
+Your library stays lightweight. Users get type-safe errors without adopting an opinionated wrapper. Everyone wins.
+
 ## Import Style
 
-> **Note:** Always use `import * as errore from 'errore'` instead of named imports. This makes code easier to move between files, and more readable for people unfamiliar with errore since every function call is clearly namespaced (e.g. `errore.isOk()` instead of just `isOk()`).
+> **Note:** Always use `import * as errore from 'errore'` instead of named imports. This makes code easier to move between files, and more readable since every function call is **clearly namespaced** (e.g. `errore.isOk()` instead of just `isOk()`).
 
 ## License