errore 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,216 @@
+# 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
+
+## 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` |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,3 +1,291 @@
-declare const version = "0.0.1";
+/**
+ * The core type: either an Error or a value T.
+ * Unlike Result<T, E>, this is just a union - no wrapper needed.
+ */
+type Errore<T, E extends Error = Error> = E | T;
+/**
+ * Extract the error type from an Errore union.
+ * @example InferError<NetworkError | User> // NetworkError
+ */
+type InferError<T> = T extends Error ? T : never;
+/**
+ * Extract the value type from an Errore union.
+ * @example InferValue<NetworkError | User> // User
+ */
+type InferValue<T> = T extends Error ? never : T;
+/**
+ * Utility to ensure T is not an Error type.
+ * Used to prevent ambiguous unions like Error | Error.
+ */
+type EnsureNotError<T> = T extends Error ? 'Error: Value type T cannot extend Error - this would make the union ambiguous' : T;
 
-export { version };
+/**
+ * Any tagged error (for generic constraints)
+ */
+type AnyTaggedError = Error & {
+    readonly _tag: string;
+};
+/**
+ * Instance type produced by TaggedError factory
+ */
+type TaggedErrorInstance<Tag extends string, Props> = Error & {
+    readonly _tag: Tag;
+    toJSON(): object;
+} & Readonly<Props>;
+/**
+ * Class type produced by TaggedError factory
+ */
+type TaggedErrorClass<Tag extends string, Props> = {
+    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props>;
+    /** Type guard for this error class */
+    is(value: unknown): value is TaggedErrorInstance<Tag, Props>;
+};
+/**
+ * Factory for tagged error classes with discriminated _tag property.
+ * Enables exhaustive pattern matching on error unions.
+ *
+ * @example
+ * class NotFoundError extends TaggedError("NotFoundError")<{
+ *   id: string;
+ *   message: string;
+ * }>() {}
+ *
+ * const err = new NotFoundError({ id: "123", message: "Not found" });
+ * err._tag    // "NotFoundError"
+ * err.id      // "123"
+ *
+ * // Type guard
+ * NotFoundError.is(err) // true
+ * TaggedError.is(err)   // true (any tagged error)
+ */
+declare const TaggedError: {
+    <Tag extends string>(tag: Tag): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props>;
+    /** Type guard for any TaggedError instance */
+    is(value: unknown): value is AnyTaggedError;
+};
+/**
+ * Type guard for tagged error instances.
+ *
+ * @example
+ * if (isTaggedError(value)) { value._tag }
+ */
+declare const isTaggedError: (value: unknown) => value is AnyTaggedError;
+/**
+ * Handler map for exhaustive matching
+ */
+type MatchHandlers<E extends AnyTaggedError, R> = {
+    [K in E['_tag']]: (err: Extract<E, {
+        _tag: K;
+    }>) => R;
+};
+/**
+ * Exhaustive pattern match on tagged error union by _tag.
+ *
+ * @example
+ * matchError(err, {
+ *   NotFoundError: (e) => `Missing: ${e.id}`,
+ *   ValidationError: (e) => `Invalid: ${e.field}`,
+ * });
+ */
+declare function matchError<E extends AnyTaggedError, R>(err: E, handlers: MatchHandlers<E, R>): R;
+/**
+ * Partial pattern match with fallback for unhandled tags.
+ *
+ * @example
+ * matchErrorPartial(err, {
+ *   NotFoundError: (e) => `Missing: ${e.id}`,
+ * }, (e) => `Unknown: ${e.message}`);
+ */
+declare function matchErrorPartial<E extends AnyTaggedError, R>(err: E, handlers: Partial<MatchHandlers<E, R>>, fallback: (e: E) => R): R;
+declare const UnhandledError_base: TaggedErrorClass<"UnhandledError", {
+    message: string;
+    cause: unknown;
+}>;
+/**
+ * Default error type when catching unknown exceptions.
+ */
+declare class UnhandledError extends UnhandledError_base {
+    constructor(args: {
+        cause: unknown;
+    });
+}
+
+/**
+ * Type guard: checks if value is an Error.
+ * After this check, TypeScript narrows the type to the error types in the union.
+ *
+ * @example
+ * const result = await fetchUser(id)
+ * if (isError(result)) {
+ *   // result is narrowed to the error type
+ *   return result
+ * }
+ * // result is narrowed to User
+ * console.log(result.name)
+ */
+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.
+ *
+ * @example
+ * const result = await fetchUser(id)
+ * if (isOk(result)) {
+ *   console.log(result.name) // result is User
+ * }
+ */
+declare function isOk<V>(value: V): value is Exclude<V, Error>;
+/**
+ * Execute a sync function and return either the value or an error.
+ *
+ * @overload Simple form - wraps exceptions in UnhandledError
+ * @example
+ * const result = tryFn(() => JSON.parse(input))
+ * // result: UnhandledError | unknown
+ *
+ * @overload With custom catch - you control the error type
+ * @example
+ * const result = tryFn({
+ *   try: () => JSON.parse(input),
+ *   catch: (e) => new ParseError({ cause: e })
+ * })
+ * // result: ParseError | unknown
+ */
+declare function tryFn<T>(fn: () => T): UnhandledError | T;
+declare function tryFn<T, E extends Error>(opts: {
+    try: () => T;
+    catch: (e: unknown) => E;
+}): E | T;
+/**
+ * Execute an async function and return either the value or an error.
+ *
+ * @overload Simple form - wraps exceptions in UnhandledError
+ * @example
+ * const result = await tryAsync(() => fetch(url).then(r => r.json()))
+ * // result: UnhandledError | unknown
+ *
+ * @overload With custom catch - you control the error type
+ * @example
+ * const result = await tryAsync({
+ *   try: () => fetch(url),
+ *   catch: (e) => new NetworkError({ cause: e })
+ * })
+ * // result: NetworkError | Response
+ */
+declare function tryAsync<T>(fn: () => Promise<T>): Promise<UnhandledError | T>;
+declare function tryAsync<T, E extends Error>(opts: {
+    try: () => Promise<T>;
+    catch: (e: unknown) => E | Promise<E>;
+}): Promise<E | T>;
+
+/**
+ * Transform the value if not an error.
+ * If the value is an error, returns it unchanged.
+ *
+ * @example
+ * const result = map(user, u => u.name)
+ * // If user is User, result is string
+ * // If user is NotFoundError, result is NotFoundError
+ */
+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.
+ *
+ * @example
+ * const result = mapError(fetchResult, e => new AppError({ cause: e }))
+ * // Converts any error type to AppError
+ */
+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.
+ * If successful, runs fn and returns its result.
+ *
+ * @example
+ * const result = andThen(userId, id => fetchUser(id))
+ * // If userId is ValidationError, result is ValidationError
+ * // If userId is string, result is whatever fetchUser returns
+ */
+declare function andThen<V, R>(value: V, fn: (v: Exclude<V, Error>) => R): Extract<V, Error> | R;
+/**
+ * Async version of andThen.
+ *
+ * @example
+ * const result = await andThenAsync(userId, async id => {
+ *   const user = await fetchUser(id)
+ *   return user
+ * })
+ */
+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.
+ *
+ * @example
+ * const result = tap(user, u => console.log('Got user:', u.name))
+ */
+declare function tap<V>(value: V, fn: (v: Exclude<V, Error>) => void): V;
+/**
+ * Async version of tap.
+ *
+ * @example
+ * const result = await tapAsync(user, async u => {
+ *   await logToService(u)
+ * })
+ */
+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.
+ *
+ * @example
+ * const user = unwrap(result) // throws if result is an error
+ * console.log(user.name)
+ *
+ * @example With custom message
+ * const user = unwrap(result, 'Failed to get user')
+ */
+declare function unwrap<V>(value: V, message?: string): Exclude<V, Error>;
+/**
+ * Extract the value or return a fallback if it's an error.
+ *
+ * @example
+ * const name = unwrapOr(result, 'Anonymous')
+ * // If result is User, returns user
+ * // If result is Error, returns 'Anonymous'
+ */
+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.
+ *
+ * @example
+ * const message = match(result, {
+ *   ok: user => `Hello, ${user.name}`,
+ *   err: error => `Failed: ${error.message}`
+ * })
+ */
+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].
+ *
+ * @example
+ * const results = await Promise.all(ids.map(fetchUser))
+ * const [users, errors] = partition(results)
+ */
+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.
+ *
+ * @example
+ * const nested: NetworkError | (ParseError | User) = await fetchAndParse()
+ * const flat: NetworkError | ParseError | User = flatten(nested)
+ */
+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

@@ -1,3 +1,291 @@
-declare const version = "0.0.1";
+/**
+ * The core type: either an Error or a value T.
+ * Unlike Result<T, E>, this is just a union - no wrapper needed.
+ */
+type Errore<T, E extends Error = Error> = E | T;
+/**
+ * Extract the error type from an Errore union.
+ * @example InferError<NetworkError | User> // NetworkError
+ */
+type InferError<T> = T extends Error ? T : never;
+/**
+ * Extract the value type from an Errore union.
+ * @example InferValue<NetworkError | User> // User
+ */
+type InferValue<T> = T extends Error ? never : T;
+/**
+ * Utility to ensure T is not an Error type.
+ * Used to prevent ambiguous unions like Error | Error.
+ */
+type EnsureNotError<T> = T extends Error ? 'Error: Value type T cannot extend Error - this would make the union ambiguous' : T;
 
-export { version };
+/**
+ * Any tagged error (for generic constraints)
+ */
+type AnyTaggedError = Error & {
+    readonly _tag: string;
+};
+/**
+ * Instance type produced by TaggedError factory
+ */
+type TaggedErrorInstance<Tag extends string, Props> = Error & {
+    readonly _tag: Tag;
+    toJSON(): object;
+} & Readonly<Props>;
+/**
+ * Class type produced by TaggedError factory
+ */
+type TaggedErrorClass<Tag extends string, Props> = {
+    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props>;
+    /** Type guard for this error class */
+    is(value: unknown): value is TaggedErrorInstance<Tag, Props>;
+};
+/**
+ * Factory for tagged error classes with discriminated _tag property.
+ * Enables exhaustive pattern matching on error unions.
+ *
+ * @example
+ * class NotFoundError extends TaggedError("NotFoundError")<{
+ *   id: string;
+ *   message: string;
+ * }>() {}
+ *
+ * const err = new NotFoundError({ id: "123", message: "Not found" });
+ * err._tag    // "NotFoundError"
+ * err.id      // "123"
+ *
+ * // Type guard
+ * NotFoundError.is(err) // true
+ * TaggedError.is(err)   // true (any tagged error)
+ */
+declare const TaggedError: {
+    <Tag extends string>(tag: Tag): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props>;
+    /** Type guard for any TaggedError instance */
+    is(value: unknown): value is AnyTaggedError;
+};
+/**
+ * Type guard for tagged error instances.
+ *
+ * @example
+ * if (isTaggedError(value)) { value._tag }
+ */
+declare const isTaggedError: (value: unknown) => value is AnyTaggedError;
+/**
+ * Handler map for exhaustive matching
+ */
+type MatchHandlers<E extends AnyTaggedError, R> = {
+    [K in E['_tag']]: (err: Extract<E, {
+        _tag: K;
+    }>) => R;
+};
+/**
+ * Exhaustive pattern match on tagged error union by _tag.
+ *
+ * @example
+ * matchError(err, {
+ *   NotFoundError: (e) => `Missing: ${e.id}`,
+ *   ValidationError: (e) => `Invalid: ${e.field}`,
+ * });
+ */
+declare function matchError<E extends AnyTaggedError, R>(err: E, handlers: MatchHandlers<E, R>): R;
+/**
+ * Partial pattern match with fallback for unhandled tags.
+ *
+ * @example
+ * matchErrorPartial(err, {
+ *   NotFoundError: (e) => `Missing: ${e.id}`,
+ * }, (e) => `Unknown: ${e.message}`);
+ */
+declare function matchErrorPartial<E extends AnyTaggedError, R>(err: E, handlers: Partial<MatchHandlers<E, R>>, fallback: (e: E) => R): R;
+declare const UnhandledError_base: TaggedErrorClass<"UnhandledError", {
+    message: string;
+    cause: unknown;
+}>;
+/**
+ * Default error type when catching unknown exceptions.
+ */
+declare class UnhandledError extends UnhandledError_base {
+    constructor(args: {
+        cause: unknown;
+    });
+}
+
+/**
+ * Type guard: checks if value is an Error.
+ * After this check, TypeScript narrows the type to the error types in the union.
+ *
+ * @example
+ * const result = await fetchUser(id)
+ * if (isError(result)) {
+ *   // result is narrowed to the error type
+ *   return result
+ * }
+ * // result is narrowed to User
+ * console.log(result.name)
+ */
+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.
+ *
+ * @example
+ * const result = await fetchUser(id)
+ * if (isOk(result)) {
+ *   console.log(result.name) // result is User
+ * }
+ */
+declare function isOk<V>(value: V): value is Exclude<V, Error>;
+/**
+ * Execute a sync function and return either the value or an error.
+ *
+ * @overload Simple form - wraps exceptions in UnhandledError
+ * @example
+ * const result = tryFn(() => JSON.parse(input))
+ * // result: UnhandledError | unknown
+ *
+ * @overload With custom catch - you control the error type
+ * @example
+ * const result = tryFn({
+ *   try: () => JSON.parse(input),
+ *   catch: (e) => new ParseError({ cause: e })
+ * })
+ * // result: ParseError | unknown
+ */
+declare function tryFn<T>(fn: () => T): UnhandledError | T;
+declare function tryFn<T, E extends Error>(opts: {
+    try: () => T;
+    catch: (e: unknown) => E;
+}): E | T;
+/**
+ * Execute an async function and return either the value or an error.
+ *
+ * @overload Simple form - wraps exceptions in UnhandledError
+ * @example
+ * const result = await tryAsync(() => fetch(url).then(r => r.json()))
+ * // result: UnhandledError | unknown
+ *
+ * @overload With custom catch - you control the error type
+ * @example
+ * const result = await tryAsync({
+ *   try: () => fetch(url),
+ *   catch: (e) => new NetworkError({ cause: e })
+ * })
+ * // result: NetworkError | Response
+ */
+declare function tryAsync<T>(fn: () => Promise<T>): Promise<UnhandledError | T>;
+declare function tryAsync<T, E extends Error>(opts: {
+    try: () => Promise<T>;
+    catch: (e: unknown) => E | Promise<E>;
+}): Promise<E | T>;
+
+/**
+ * Transform the value if not an error.
+ * If the value is an error, returns it unchanged.
+ *
+ * @example
+ * const result = map(user, u => u.name)
+ * // If user is User, result is string
+ * // If user is NotFoundError, result is NotFoundError
+ */
+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.
+ *
+ * @example
+ * const result = mapError(fetchResult, e => new AppError({ cause: e }))
+ * // Converts any error type to AppError
+ */
+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.
+ * If successful, runs fn and returns its result.
+ *
+ * @example
+ * const result = andThen(userId, id => fetchUser(id))
+ * // If userId is ValidationError, result is ValidationError
+ * // If userId is string, result is whatever fetchUser returns
+ */
+declare function andThen<V, R>(value: V, fn: (v: Exclude<V, Error>) => R): Extract<V, Error> | R;
+/**
+ * Async version of andThen.
+ *
+ * @example
+ * const result = await andThenAsync(userId, async id => {
+ *   const user = await fetchUser(id)
+ *   return user
+ * })
+ */
+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.
+ *
+ * @example
+ * const result = tap(user, u => console.log('Got user:', u.name))
+ */
+declare function tap<V>(value: V, fn: (v: Exclude<V, Error>) => void): V;
+/**
+ * Async version of tap.
+ *
+ * @example
+ * const result = await tapAsync(user, async u => {
+ *   await logToService(u)
+ * })
+ */
+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.
+ *
+ * @example
+ * const user = unwrap(result) // throws if result is an error
+ * console.log(user.name)
+ *
+ * @example With custom message
+ * const user = unwrap(result, 'Failed to get user')
+ */
+declare function unwrap<V>(value: V, message?: string): Exclude<V, Error>;
+/**
+ * Extract the value or return a fallback if it's an error.
+ *
+ * @example
+ * const name = unwrapOr(result, 'Anonymous')
+ * // If result is User, returns user
+ * // If result is Error, returns 'Anonymous'
+ */
+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.
+ *
+ * @example
+ * const message = match(result, {
+ *   ok: user => `Hello, ${user.name}`,
+ *   err: error => `Failed: ${error.message}`
+ * })
+ */
+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].
+ *
+ * @example
+ * const results = await Promise.all(ids.map(fetchUser))
+ * const [users, errors] = partition(results)
+ */
+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.
+ *
+ * @example
+ * const nested: NetworkError | (ParseError | User) = await fetchAndParse()
+ * const flat: NetworkError | ParseError | User = flatten(nested)
+ */
+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.js

@@ -1,3 +1,4 @@
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -19,11 +20,224 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  version: () => version
+  TaggedError: () => TaggedError,
+  UnhandledError: () => UnhandledError,
+  andThen: () => andThen,
+  andThenAsync: () => andThenAsync,
+  flatten: () => flatten,
+  isError: () => isError,
+  isOk: () => isOk,
+  isTaggedError: () => isTaggedError,
+  map: () => map,
+  mapError: () => mapError,
+  match: () => match,
+  matchError: () => matchError,
+  matchErrorPartial: () => matchErrorPartial,
+  partition: () => partition,
+  tap: () => tap,
+  tapAsync: () => tapAsync,
+  tryAsync: () => tryAsync,
+  tryFn: () => tryFn,
+  unwrap: () => unwrap,
+  unwrapOr: () => unwrapOr
 });
 module.exports = __toCommonJS(index_exports);
-var version = "0.0.1";
+
+// src/error.ts
+var serializeCause = (cause) => {
+  if (cause instanceof Error) {
+    return { name: cause.name, message: cause.message, stack: cause.stack };
+  }
+  return cause;
+};
+var isAnyTaggedError = (value) => {
+  return value instanceof Error && "_tag" in value && typeof value._tag === "string";
+};
+var TaggedError = Object.assign(
+  (tag) => () => {
+    class Base extends Error {
+      _tag = tag;
+      /** Type guard for this error class */
+      static is(value) {
+        return value instanceof Base;
+      }
+      constructor(args) {
+        const message = args && "message" in args && typeof args.message === "string" ? args.message : void 0;
+        const cause = args && "cause" in args ? args.cause : void 0;
+        super(message, cause !== void 0 ? { cause } : void 0);
+        if (args) {
+          Object.assign(this, args);
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = tag;
+        if (cause instanceof Error && cause.stack) {
+          const indented = cause.stack.replace(/\n/g, "\n  ");
+          this.stack = `${this.stack}
+Caused by: ${indented}`;
+        }
+      }
+      toJSON() {
+        return {
+          ...this,
+          _tag: this._tag,
+          name: this.name,
+          message: this.message,
+          cause: serializeCause(this.cause),
+          stack: this.stack
+        };
+      }
+    }
+    return Base;
+  },
+  { is: isAnyTaggedError }
+);
+var isTaggedError = isAnyTaggedError;
+function matchError(err, handlers) {
+  const handler = handlers[err._tag];
+  return handler(err);
+}
+function matchErrorPartial(err, handlers, fallback) {
+  const handler = handlers[err._tag];
+  if (handler) {
+    return handler(err);
+  }
+  return fallback(err);
+}
+var UnhandledError = class extends TaggedError("UnhandledError")() {
+  constructor(args) {
+    const message = args.cause instanceof Error ? `Unhandled exception: ${args.cause.message}` : `Unhandled exception: ${String(args.cause)}`;
+    super({ message, cause: args.cause });
+  }
+};
+
+// src/core.ts
+function isError(value) {
+  return value instanceof Error;
+}
+function isOk(value) {
+  return !(value instanceof Error);
+}
+function tryFn(fnOrOpts) {
+  if (typeof fnOrOpts === "function") {
+    try {
+      return fnOrOpts();
+    } catch (cause) {
+      return new UnhandledError({ cause });
+    }
+  }
+  try {
+    return fnOrOpts.try();
+  } catch (cause) {
+    return fnOrOpts.catch(cause);
+  }
+}
+async function tryAsync(fnOrOpts) {
+  if (typeof fnOrOpts === "function") {
+    try {
+      return await fnOrOpts();
+    } catch (cause) {
+      return new UnhandledError({ cause });
+    }
+  }
+  try {
+    return await fnOrOpts.try();
+  } catch (cause) {
+    return await fnOrOpts.catch(cause);
+  }
+}
+
+// src/transform.ts
+function map(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+function mapError(value, fn) {
+  if (value instanceof Error) {
+    return fn(value);
+  }
+  return value;
+}
+function andThen(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+async function andThenAsync(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+function tap(value, fn) {
+  if (!(value instanceof Error)) {
+    fn(value);
+  }
+  return value;
+}
+async function tapAsync(value, fn) {
+  if (!(value instanceof Error)) {
+    await fn(value);
+  }
+  return value;
+}
+
+// src/extract.ts
+function unwrap(value, message) {
+  if (value instanceof Error) {
+    throw new Error(message ?? `Unwrap called on error: ${value.message}`, { cause: value });
+  }
+  return value;
+}
+function unwrapOr(value, fallback) {
+  if (value instanceof Error) {
+    return fallback;
+  }
+  return value;
+}
+function match(value, handlers) {
+  if (value instanceof Error) {
+    return handlers.err(value);
+  }
+  return handlers.ok(value);
+}
+function partition(values) {
+  const oks = [];
+  const errs = [];
+  for (const v of values) {
+    if (v instanceof Error) {
+      errs.push(v);
+    } else {
+      oks.push(v);
+    }
+  }
+  return [oks, errs];
+}
+function flatten(value) {
+  return value;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  version
+  TaggedError,
+  UnhandledError,
+  andThen,
+  andThenAsync,
+  flatten,
+  isError,
+  isOk,
+  isTaggedError,
+  map,
+  mapError,
+  match,
+  matchError,
+  matchErrorPartial,
+  partition,
+  tap,
+  tapAsync,
+  tryAsync,
+  tryFn,
+  unwrap,
+  unwrapOr
 });

package/dist/index.mjs

@@ -1,5 +1,197 @@
-// src/index.ts
-var version = "0.0.1";
+// src/error.ts
+var serializeCause = (cause) => {
+  if (cause instanceof Error) {
+    return { name: cause.name, message: cause.message, stack: cause.stack };
+  }
+  return cause;
+};
+var isAnyTaggedError = (value) => {
+  return value instanceof Error && "_tag" in value && typeof value._tag === "string";
+};
+var TaggedError = Object.assign(
+  (tag) => () => {
+    class Base extends Error {
+      _tag = tag;
+      /** Type guard for this error class */
+      static is(value) {
+        return value instanceof Base;
+      }
+      constructor(args) {
+        const message = args && "message" in args && typeof args.message === "string" ? args.message : void 0;
+        const cause = args && "cause" in args ? args.cause : void 0;
+        super(message, cause !== void 0 ? { cause } : void 0);
+        if (args) {
+          Object.assign(this, args);
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = tag;
+        if (cause instanceof Error && cause.stack) {
+          const indented = cause.stack.replace(/\n/g, "\n  ");
+          this.stack = `${this.stack}
+Caused by: ${indented}`;
+        }
+      }
+      toJSON() {
+        return {
+          ...this,
+          _tag: this._tag,
+          name: this.name,
+          message: this.message,
+          cause: serializeCause(this.cause),
+          stack: this.stack
+        };
+      }
+    }
+    return Base;
+  },
+  { is: isAnyTaggedError }
+);
+var isTaggedError = isAnyTaggedError;
+function matchError(err, handlers) {
+  const handler = handlers[err._tag];
+  return handler(err);
+}
+function matchErrorPartial(err, handlers, fallback) {
+  const handler = handlers[err._tag];
+  if (handler) {
+    return handler(err);
+  }
+  return fallback(err);
+}
+var UnhandledError = class extends TaggedError("UnhandledError")() {
+  constructor(args) {
+    const message = args.cause instanceof Error ? `Unhandled exception: ${args.cause.message}` : `Unhandled exception: ${String(args.cause)}`;
+    super({ message, cause: args.cause });
+  }
+};
+
+// src/core.ts
+function isError(value) {
+  return value instanceof Error;
+}
+function isOk(value) {
+  return !(value instanceof Error);
+}
+function tryFn(fnOrOpts) {
+  if (typeof fnOrOpts === "function") {
+    try {
+      return fnOrOpts();
+    } catch (cause) {
+      return new UnhandledError({ cause });
+    }
+  }
+  try {
+    return fnOrOpts.try();
+  } catch (cause) {
+    return fnOrOpts.catch(cause);
+  }
+}
+async function tryAsync(fnOrOpts) {
+  if (typeof fnOrOpts === "function") {
+    try {
+      return await fnOrOpts();
+    } catch (cause) {
+      return new UnhandledError({ cause });
+    }
+  }
+  try {
+    return await fnOrOpts.try();
+  } catch (cause) {
+    return await fnOrOpts.catch(cause);
+  }
+}
+
+// src/transform.ts
+function map(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+function mapError(value, fn) {
+  if (value instanceof Error) {
+    return fn(value);
+  }
+  return value;
+}
+function andThen(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+async function andThenAsync(value, fn) {
+  if (value instanceof Error) {
+    return value;
+  }
+  return fn(value);
+}
+function tap(value, fn) {
+  if (!(value instanceof Error)) {
+    fn(value);
+  }
+  return value;
+}
+async function tapAsync(value, fn) {
+  if (!(value instanceof Error)) {
+    await fn(value);
+  }
+  return value;
+}
+
+// src/extract.ts
+function unwrap(value, message) {
+  if (value instanceof Error) {
+    throw new Error(message ?? `Unwrap called on error: ${value.message}`, { cause: value });
+  }
+  return value;
+}
+function unwrapOr(value, fallback) {
+  if (value instanceof Error) {
+    return fallback;
+  }
+  return value;
+}
+function match(value, handlers) {
+  if (value instanceof Error) {
+    return handlers.err(value);
+  }
+  return handlers.ok(value);
+}
+function partition(values) {
+  const oks = [];
+  const errs = [];
+  for (const v of values) {
+    if (v instanceof Error) {
+      errs.push(v);
+    } else {
+      oks.push(v);
+    }
+  }
+  return [oks, errs];
+}
+function flatten(value) {
+  return value;
+}
 export {
-  version
+  TaggedError,
+  UnhandledError,
+  andThen,
+  andThenAsync,
+  flatten,
+  isError,
+  isOk,
+  isTaggedError,
+  map,
+  mapError,
+  match,
+  matchError,
+  matchErrorPartial,
+  partition,
+  tap,
+  tapAsync,
+  tryAsync,
+  tryFn,
+  unwrap,
+  unwrapOr
 };

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "errore",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Type-safe errors as values for TypeScript. Like Go, but with full type inference.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [
@@ -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"
   }
 }