errore 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,307 @@
+# errore
+
+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:
+
+```ts
+// Go-style: errors as values
+const user = await fetchUser(id)
+if (isError(user)) return user  // TypeScript narrows type
+console.log(user.name)          // user is now User, not Error | User
+```
+
+## Install
+
+```sh
+npm install errore
+```
+
+## Quick Start
+
+```ts
+import { tryAsync, isError, TaggedError, matchError } from 'errore'
+
+// Define typed errors
+class NotFoundError extends TaggedError('NotFoundError')<{
+  id: string
+  message: string
+}>() {
+  constructor(args: { id: string }) {
+    super({ ...args, message: `User ${args.id} not found` })
+  }
+}
+
+class DbError extends TaggedError('DbError')<{
+  message: string
+  cause: unknown
+}>() {}
+
+// Function returns Error | Value (no wrapper!)
+async function getUser(id: string): Promise<NotFoundError | DbError | User> {
+  const result = await tryAsync({
+    try: () => db.query(id),
+    catch: e => new DbError({ message: 'Query failed', cause: e })
+  })
+  
+  if (isError(result)) return result
+  if (!result) return new NotFoundError({ id })
+  
+  return result
+}
+
+// Caller handles errors explicitly
+const user = await getUser('123')
+
+if (isError(user)) {
+  matchError(user, {
+    NotFoundError: e => console.log(`User ${e.id} not found`),
+    DbError: e => console.log(`Database error: ${e.message}`)
+  })
+  return
+}
+
+// TypeScript knows: user is User
+console.log(user.name)
+```
+
+## API
+
+### Type Guards
+
+```ts
+import { isError, isOk } from 'errore'
+
+const result: NetworkError | User = await fetchUser(id)
+
+if (isError(result)) {
+  // result is NetworkError
+  return result
+}
+// result is User
+```
+
+### Try Functions
+
+```ts
+import { tryFn, tryAsync } from 'errore'
+
+// Sync - wraps exceptions in UnhandledError
+const parsed = tryFn(() => JSON.parse(input))
+
+// Sync - with custom error type
+const parsed = tryFn({
+  try: () => JSON.parse(input),
+  catch: e => new ParseError({ cause: e })
+})
+
+// Async
+const response = await tryAsync(() => fetch(url))
+
+// Async - with custom error
+const response = await tryAsync({
+  try: () => fetch(url),
+  catch: e => new NetworkError({ cause: e })
+})
+```
+
+### Transformations
+
+```ts
+import { map, mapError, andThen, tap } from 'errore'
+
+// Transform value (if not error)
+const name = map(user, u => u.name)
+
+// Transform error
+const appError = mapError(dbError, e => new AppError({ cause: e }))
+
+// Chain operations
+const posts = andThen(user, u => fetchPosts(u.id))
+
+// Side effects
+const logged = tap(user, u => console.log('Got user:', u.name))
+```
+
+### Extraction
+
+```ts
+import { unwrap, unwrapOr, match, partition } from 'errore'
+
+// Extract or throw
+const user = unwrap(result)
+const user = unwrap(result, 'Custom error message')
+
+// Extract or fallback
+const name = unwrapOr(result, 'Anonymous')
+
+// Pattern match
+const message = match(result, {
+  ok: user => `Hello, ${user.name}`,
+  err: error => `Failed: ${error.message}`
+})
+
+// Split array into [successes, errors]
+const [users, errors] = partition(results)
+```
+
+### Tagged Errors
+
+```ts
+import { TaggedError, matchError, matchErrorPartial } from 'errore'
+
+// Define errors with _tag discriminant
+class ValidationError extends TaggedError('ValidationError')<{
+  field: string
+  message: string
+}>() {}
+
+class NetworkError extends TaggedError('NetworkError')<{
+  url: string
+  message: string
+}>() {}
+
+type AppError = ValidationError | NetworkError
+
+// Exhaustive matching (TypeScript ensures all cases handled)
+matchError(error, {
+  ValidationError: e => `Invalid ${e.field}`,
+  NetworkError: e => `Failed to fetch ${e.url}`
+})
+
+// Partial matching with fallback
+matchErrorPartial(error, {
+  ValidationError: e => `Invalid ${e.field}`
+}, e => `Unknown error: ${e.message}`)
+
+// Type guards
+ValidationError.is(value)  // specific class
+TaggedError.is(value)      // any tagged error
+```
+
+## How Type Safety Works
+
+TypeScript narrows types after `instanceof Error` checks:
+
+```ts
+function example(result: NetworkError | User): string {
+  if (result instanceof Error) {
+    // TypeScript knows: result is NetworkError
+    return result.message
+  }
+  // TypeScript knows: result is User (Error excluded)
+  return result.name
+}
+```
+
+This works because:
+1. `Error` is a built-in class TypeScript understands
+2. Custom error classes extend `Error`
+3. After an `instanceof Error` check, TS excludes all Error subtypes
+
+## 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!
+
+In Rust, you'd need `Result<Option<T>, E>` or `Option<Result<T, E>>` and worry about the order. Here it's just a union:
+
+```ts
+// Result + Option in one natural type
+function findUser(id: string): NotFoundError | User | null {
+  if (id === 'bad') return new NotFoundError({ id })
+  if (id === 'missing') return null
+  return { id, name: 'Alice' }
+}
+
+const user = findUser('123')
+
+// Handle error first
+if (isError(user)) {
+  return user.message  // TypeScript: user is NotFoundError
+}
+
+// Handle null/missing case - use ?. and ?? naturally!
+const name = user?.name ?? 'Anonymous'
+
+// Or check explicitly
+if (user === null) {
+  return 'User not found'
+}
+
+// TypeScript knows: user is User
+console.log(user.name)
+```
+
+### Works with `undefined` too
+
+```ts
+function lookup(key: string): NetworkError | string | undefined {
+  if (key === 'fail') return new NetworkError({ url: '/api', message: 'Failed' })
+  if (key === 'missing') return undefined
+  return 'found-value'
+}
+
+const value = lookup('key')
+
+if (isError(value)) return value
+
+// ?? works naturally with undefined
+const result = value ?? 'default'
+```
+
+### Triple union: `Error | T | null | undefined`
+
+Even this works with full type inference:
+
+```ts
+function query(sql: string): ValidationError | { rows: string[] } | null | undefined {
+  if (sql === 'invalid') return new ValidationError({ field: 'sql', message: 'Bad' })
+  if (sql === 'empty') return null      // explicitly no data
+  if (sql === 'no-table') return undefined  // table doesn't exist
+  return { rows: ['a', 'b'] }
+}
+
+const result = query('SELECT *')
+
+if (isError(result)) {
+  return result.field  // TypeScript: ValidationError
+}
+
+if (result == null) {
+  return 'no data'  // handles both null and undefined
+}
+
+// TypeScript: { rows: string[] }
+console.log(result.rows)
+```
+
+### Why this is better than Rust/Zig
+
+| Language | Result + Option | Order matters? |
+|----------|-----------------|----------------|
+| Rust | `Result<Option<T>, E>` or `Option<Result<T, E>>` | Yes, must unwrap in order |
+| Zig | `!?T` (error union + optional) | Yes, specific syntax |
+| **errore** | `Error \| T \| null` | **No!** Check in any order |
+
+With errore:
+- Use `?.` and `??` naturally
+- Check `isError()` or `=== null` in any order
+- No unwrapping ceremony
+- TypeScript infers everything
+
+## Comparison with Result Types
+
+| Result Pattern | errore |
+|---------------|--------|
+| `Result.ok(value)` | just `return value` |
+| `Result.err(error)` | just `return error` |
+| `result.value` | direct access after guard |
+| `result.map(fn)` | `map(result, fn)` |
+| `Result<User, Error>` | `Error \| User` |
+| `Result<Option<T>, E>` | `Error \| T \| null` |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -112,7 +112,7 @@ declare class UnhandledError extends UnhandledError_base {
 
 /**
  * Type guard: checks if value is an Error.
- * After this check, TypeScript narrows the type.
+ * After this check, TypeScript narrows the type to the error types in the union.
  *
  * @example
  * const result = await fetchUser(id)
@@ -123,7 +123,7 @@ declare class UnhandledError extends UnhandledError_base {
  * // result is narrowed to User
  * console.log(result.name)
  */
-declare function isError<T, E extends Error>(value: E | T): value is E;
+declare function isError<V>(value: V): value is Extract<V, Error>;
 /**
  * Type guard: checks if value is NOT an Error.
  * Inverse of isError for convenience.
@@ -134,7 +134,7 @@ declare function isError<T, E extends Error>(value: E | T): value is E;
  *   console.log(result.name) // result is User
  * }
  */
-declare function isOk<T, E extends Error>(value: E | T): value is T;
+declare function isOk<V>(value: V): value is Exclude<V, Error>;
 /**
  * Execute a sync function and return either the value or an error.
  *
@@ -187,7 +187,7 @@ declare function tryAsync<T, E extends Error>(opts: {
  * // If user is User, result is string
  * // If user is NotFoundError, result is NotFoundError
  */
-declare function map<T, U, E extends Error>(value: E | T, fn: (v: T) => U): E | U;
+declare function map<V, U>(value: V, fn: (v: Exclude<V, Error>) => U): Extract<V, Error> | U;
 /**
  * Transform the error if it is an error.
  * If the value is not an error, returns it unchanged.
@@ -196,7 +196,7 @@ declare function map<T, U, E extends Error>(value: E | T, fn: (v: T) => U): E |
  * const result = mapError(fetchResult, e => new AppError({ cause: e }))
  * // Converts any error type to AppError
  */
-declare function mapError<T, E extends Error, E2 extends Error>(value: E | T, fn: (e: E) => E2): E2 | T;
+declare function mapError<V, E2 extends Error>(value: V, fn: (e: Extract<V, Error>) => E2): E2 | Exclude<V, Error>;
 /**
  * Chain another errore-returning function.
  * If the value is an error, returns it unchanged.
@@ -207,7 +207,7 @@ declare function mapError<T, E extends Error, E2 extends Error>(value: E | T, fn
  * // If userId is ValidationError, result is ValidationError
  * // If userId is string, result is whatever fetchUser returns
  */
-declare function andThen<T, U, E extends Error, E2 extends Error>(value: E | T, fn: (v: T) => E2 | U): E | E2 | U;
+declare function andThen<V, R>(value: V, fn: (v: Exclude<V, Error>) => R): Extract<V, Error> | R;
 /**
  * Async version of andThen.
  *
@@ -217,7 +217,7 @@ declare function andThen<T, U, E extends Error, E2 extends Error>(value: E | T,
  *   return user
  * })
  */
-declare function andThenAsync<T, U, E extends Error, E2 extends Error>(value: E | T, fn: (v: T) => Promise<E2 | U>): Promise<E | E2 | U>;
+declare function andThenAsync<V, R>(value: V, fn: (v: Exclude<V, Error>) => Promise<R>): Promise<Extract<V, Error> | R>;
 /**
  * Run a side effect if the value is not an error.
  * Returns the original value unchanged.
@@ -225,7 +225,7 @@ declare function andThenAsync<T, U, E extends Error, E2 extends Error>(value: E
  * @example
  * const result = tap(user, u => console.log('Got user:', u.name))
  */
-declare function tap<T, E extends Error>(value: E | T, fn: (v: T) => void): E | T;
+declare function tap<V>(value: V, fn: (v: Exclude<V, Error>) => void): V;
 /**
  * Async version of tap.
  *
@@ -234,7 +234,7 @@ declare function tap<T, E extends Error>(value: E | T, fn: (v: T) => void): E |
  *   await logToService(u)
  * })
  */
-declare function tapAsync<T, E extends Error>(value: E | T, fn: (v: T) => Promise<void>): Promise<E | T>;
+declare function tapAsync<V>(value: V, fn: (v: Exclude<V, Error>) => Promise<void>): Promise<V>;
 
 /**
  * Extract the value or throw if it's an error.
@@ -246,7 +246,7 @@ declare function tapAsync<T, E extends Error>(value: E | T, fn: (v: T) => Promis
  * @example With custom message
  * const user = unwrap(result, 'Failed to get user')
  */
-declare function unwrap<T, E extends Error>(value: E | T, message?: string): T;
+declare function unwrap<V>(value: V, message?: string): Exclude<V, Error>;
 /**
  * Extract the value or return a fallback if it's an error.
  *
@@ -255,7 +255,7 @@ declare function unwrap<T, E extends Error>(value: E | T, message?: string): T;
  * // If result is User, returns user
  * // If result is Error, returns 'Anonymous'
  */
-declare function unwrapOr<T, U, E extends Error>(value: E | T, fallback: U): T | U;
+declare function unwrapOr<V, U>(value: V, fallback: U): Exclude<V, Error> | U;
 /**
  * Pattern match on an errore value.
  * Handles both success and error cases.
@@ -266,9 +266,9 @@ declare function unwrapOr<T, U, E extends Error>(value: E | T, fallback: U): T |
  *   err: error => `Failed: ${error.message}`
  * })
  */
-declare function match<T, E extends Error, R>(value: E | T, handlers: {
-    ok: (v: T) => R;
-    err: (e: E) => R;
+declare function match<V, R>(value: V, handlers: {
+    ok: (v: Exclude<V, Error>) => R;
+    err: (e: Extract<V, Error>) => R;
 }): R;
 /**
  * Partition an array of errore values into [successes, errors].
@@ -277,7 +277,7 @@ declare function match<T, E extends Error, R>(value: E | T, handlers: {
  * const results = await Promise.all(ids.map(fetchUser))
  * const [users, errors] = partition(results)
  */
-declare function partition<T, E extends Error>(values: (E | T)[]): [T[], E[]];
+declare function partition<V>(values: V[]): [Exclude<V, Error>[], Extract<V, Error>[]];
 /**
  * Flatten a nested errore: (E1 | (E2 | T)) becomes (E1 | E2 | T).
  * Useful when chaining operations that can fail.
@@ -286,6 +286,6 @@ declare function partition<T, E extends Error>(values: (E | T)[]): [T[], E[]];
  * const nested: NetworkError | (ParseError | User) = await fetchAndParse()
  * const flat: NetworkError | ParseError | User = flatten(nested)
  */
-declare function flatten<T, E1 extends Error, E2 extends Error>(value: E1 | (E2 | T)): E1 | E2 | T;
+declare function flatten<V>(value: V): V;
 
 export { type EnsureNotError, type Errore, type InferError, type InferValue, TaggedError, type TaggedErrorClass, type TaggedErrorInstance, UnhandledError, andThen, andThenAsync, flatten, isError, isOk, isTaggedError, map, mapError, match, matchError, matchErrorPartial, partition, tap, tapAsync, tryAsync, tryFn, unwrap, unwrapOr };

package/dist/index.d.ts

@@ -112,7 +112,7 @@ declare class UnhandledError extends UnhandledError_base {
 
 /**
  * Type guard: checks if value is an Error.
- * After this check, TypeScript narrows the type.
+ * After this check, TypeScript narrows the type to the error types in the union.
  *
  * @example
  * const result = await fetchUser(id)
@@ -123,7 +123,7 @@ declare class UnhandledError extends UnhandledError_base {
  * // result is narrowed to User
  * console.log(result.name)
  */
-declare function isError<T, E extends Error>(value: E | T): value is E;
+declare function isError<V>(value: V): value is Extract<V, Error>;
 /**
  * Type guard: checks if value is NOT an Error.
  * Inverse of isError for convenience.
@@ -134,7 +134,7 @@ declare function isError<T, E extends Error>(value: E | T): value is E;
  *   console.log(result.name) // result is User
  * }
  */
-declare function isOk<T, E extends Error>(value: E | T): value is T;
+declare function isOk<V>(value: V): value is Exclude<V, Error>;
 /**
  * Execute a sync function and return either the value or an error.
  *
@@ -187,7 +187,7 @@ declare function tryAsync<T, E extends Error>(opts: {
  * // If user is User, result is string
  * // If user is NotFoundError, result is NotFoundError
  */
-declare function map<T, U, E extends Error>(value: E | T, fn: (v: T) => U): E | U;
+declare function map<V, U>(value: V, fn: (v: Exclude<V, Error>) => U): Extract<V, Error> | U;
 /**
  * Transform the error if it is an error.
  * If the value is not an error, returns it unchanged.
@@ -196,7 +196,7 @@ declare function map<T, U, E extends Error>(value: E | T, fn: (v: T) => U): E |
  * const result = mapError(fetchResult, e => new AppError({ cause: e }))
  * // Converts any error type to AppError
  */
-declare function mapError<T, E extends Error, E2 extends Error>(value: E | T, fn: (e: E) => E2): E2 | T;
+declare function mapError<V, E2 extends Error>(value: V, fn: (e: Extract<V, Error>) => E2): E2 | Exclude<V, Error>;
 /**
  * Chain another errore-returning function.
  * If the value is an error, returns it unchanged.
@@ -207,7 +207,7 @@ declare function mapError<T, E extends Error, E2 extends Error>(value: E | T, fn
  * // If userId is ValidationError, result is ValidationError
  * // If userId is string, result is whatever fetchUser returns
  */
-declare function andThen<T, U, E extends Error, E2 extends Error>(value: E | T, fn: (v: T) => E2 | U): E | E2 | U;
+declare function andThen<V, R>(value: V, fn: (v: Exclude<V, Error>) => R): Extract<V, Error> | R;
 /**
  * Async version of andThen.
  *
@@ -217,7 +217,7 @@ declare function andThen<T, U, E extends Error, E2 extends Error>(value: E | T,
  *   return user
  * })
  */
-declare function andThenAsync<T, U, E extends Error, E2 extends Error>(value: E | T, fn: (v: T) => Promise<E2 | U>): Promise<E | E2 | U>;
+declare function andThenAsync<V, R>(value: V, fn: (v: Exclude<V, Error>) => Promise<R>): Promise<Extract<V, Error> | R>;
 /**
  * Run a side effect if the value is not an error.
  * Returns the original value unchanged.
@@ -225,7 +225,7 @@ declare function andThenAsync<T, U, E extends Error, E2 extends Error>(value: E
  * @example
  * const result = tap(user, u => console.log('Got user:', u.name))
  */
-declare function tap<T, E extends Error>(value: E | T, fn: (v: T) => void): E | T;
+declare function tap<V>(value: V, fn: (v: Exclude<V, Error>) => void): V;
 /**
  * Async version of tap.
  *
@@ -234,7 +234,7 @@ declare function tap<T, E extends Error>(value: E | T, fn: (v: T) => void): E |
  *   await logToService(u)
  * })
  */
-declare function tapAsync<T, E extends Error>(value: E | T, fn: (v: T) => Promise<void>): Promise<E | T>;
+declare function tapAsync<V>(value: V, fn: (v: Exclude<V, Error>) => Promise<void>): Promise<V>;
 
 /**
  * Extract the value or throw if it's an error.
@@ -246,7 +246,7 @@ declare function tapAsync<T, E extends Error>(value: E | T, fn: (v: T) => Promis
  * @example With custom message
  * const user = unwrap(result, 'Failed to get user')
  */
-declare function unwrap<T, E extends Error>(value: E | T, message?: string): T;
+declare function unwrap<V>(value: V, message?: string): Exclude<V, Error>;
 /**
  * Extract the value or return a fallback if it's an error.
  *
@@ -255,7 +255,7 @@ declare function unwrap<T, E extends Error>(value: E | T, message?: string): T;
  * // If result is User, returns user
  * // If result is Error, returns 'Anonymous'
  */
-declare function unwrapOr<T, U, E extends Error>(value: E | T, fallback: U): T | U;
+declare function unwrapOr<V, U>(value: V, fallback: U): Exclude<V, Error> | U;
 /**
  * Pattern match on an errore value.
  * Handles both success and error cases.
@@ -266,9 +266,9 @@ declare function unwrapOr<T, U, E extends Error>(value: E | T, fallback: U): T |
  *   err: error => `Failed: ${error.message}`
  * })
  */
-declare function match<T, E extends Error, R>(value: E | T, handlers: {
-    ok: (v: T) => R;
-    err: (e: E) => R;
+declare function match<V, R>(value: V, handlers: {
+    ok: (v: Exclude<V, Error>) => R;
+    err: (e: Extract<V, Error>) => R;
 }): R;
 /**
  * Partition an array of errore values into [successes, errors].
@@ -277,7 +277,7 @@ declare function match<T, E extends Error, R>(value: E | T, handlers: {
  * const results = await Promise.all(ids.map(fetchUser))
  * const [users, errors] = partition(results)
  */
-declare function partition<T, E extends Error>(values: (E | T)[]): [T[], E[]];
+declare function partition<V>(values: V[]): [Exclude<V, Error>[], Extract<V, Error>[]];
 /**
  * Flatten a nested errore: (E1 | (E2 | T)) becomes (E1 | E2 | T).
  * Useful when chaining operations that can fail.
@@ -286,6 +286,6 @@ declare function partition<T, E extends Error>(values: (E | T)[]): [T[], E[]];
  * const nested: NetworkError | (ParseError | User) = await fetchAndParse()
  * const flat: NetworkError | ParseError | User = flatten(nested)
  */
-declare function flatten<T, E1 extends Error, E2 extends Error>(value: E1 | (E2 | T)): E1 | E2 | T;
+declare function flatten<V>(value: V): V;
 
 export { type EnsureNotError, type Errore, type InferError, type InferValue, TaggedError, type TaggedErrorClass, type TaggedErrorInstance, UnhandledError, andThen, andThenAsync, flatten, isError, isOk, isTaggedError, map, mapError, match, matchError, matchErrorPartial, partition, tap, tapAsync, tryAsync, tryFn, unwrap, unwrapOr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "errore",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Type-safe errors as values for TypeScript. Like Go, but with full type inference.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
   },
   "keywords": [
     "error",
@@ -31,6 +32,7 @@
   "license": "MIT",
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
   }
 }