@vertz/errors 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -1,255 +1,4 @@
 /**
-* Result type and utilities for errors-as-values pattern.
-*
-* This module provides a type-safe alternative to throwing exceptions.
-* Every operation that can fail returns a Result<T, E> instead of throwing.
-*
-* @example
-* import { ok, err, unwrap, map, flatMap, match, matchErr } from '@vertz/errors';
-*
-* // Creating results
-* const success = ok({ name: 'Alice' });
-* const failure = err({ code: 'NOT_FOUND', message: 'User not found' });
-*
-* // Transforming
-* const doubled = map(ok(5), x => x * 2);
-*
-* // Chaining
-* const result = await flatMap(ok(5), async x => ok(x * 2));
-*
-* // Pattern matching
-* const message = match(result, {
-*   ok: (data) => `Success: ${data}`,
-*   err: (error) => `Error: ${error.message}`
-* });
-*/
-/**
-* Represents a successful result.
-*
-* @example
-* { ok: true, data: { name: 'Alice' } }
-*/
-interface Ok<T> {
-	/** Always true for successful results */
-	readonly ok: true;
-	/** The successful value */
-	readonly data: T;
-}
-/**
-* Represents an erroneous result.
-*
-* @example
-* { ok: false, error: { code: 'NOT_FOUND', message: 'User not found' } }
-*/
-interface Err<E> {
-	/** Always false for error results */
-	readonly ok: false;
-	/** The error value */
-	readonly error: E;
-}
-/**
-* A discriminated union representing success or failure.
-*
-* @example
-* type UserResult = Result<User, ValidationError>;
-* type UsersResult = Result<User[], NotFoundError>;
-*
-* @example
-* const result: Result<string, Error> = ok('hello');
-* if (result.ok) {
-*   console.log(result.data); // TypeScript knows this is string
-* } else {
-*   console.log(result.error); // TypeScript knows this is Error
-* }
-*/
-type Result<
-	T,
-	E = unknown
-> = Ok<T> | Err<E>;
-/**
-* Creates a successful Result.
-*
-* @example
-* const result = ok({ name: 'Alice' });
-* // { ok: true, data: { name: 'Alice' } }
-*
-* @example
-* // With type inference
-* const result = ok(42); // Ok<number>
-*/
-declare const ok: <T>(data: T) => Ok<T>;
-/**
-* Creates an error Result.
-*
-* @example
-* const result = err({ code: 'VALIDATION_FAILED', message: 'Invalid email', issues: [] });
-* // { ok: false, error: { code: 'VALIDATION_FAILED', ... } }
-*
-* @example
-* // With simple string errors
-* const result = err('Something went wrong');
-* // { ok: false, error: 'Something went wrong' }
-*/
-declare const err: <E>(error: E) => Err<E>;
-/**
-* Unwraps a Result, throwing if error.
-*
-* Use only in tests, scripts, or when failure is truly exceptional.
-*
-* @example
-* // Tests
-* const user = unwrap(await repo.findOneRequired(id));
-*
-* @example
-* // Scripts
-* const config = unwrap(parseConfig());
-*
-* @throws The error value if the Result is an error
-*/
-declare function unwrap<
-	T,
-	E
->(result: Result<T, E>): T;
-/**
-* Unwraps a Result, returning a default value if error.
-*
-* @example
-* const user = await findById(id) ?? { name: 'Guest' };
-*/
-declare function unwrapOr<
-	T,
-	E
->(result: Result<T, E>, defaultValue: T): T;
-/**
-* Maps the success value to a new type.
-*
-* @example
-* const userName = map(userResult, u => u.name);
-* // Result<string, Error> if userResult was Result<User, Error>
-*
-* @example
-* // Transform while preserving error type
-* const id = map(ok({ userId: 5 }), u => u.userId);
-* // Ok<number>
-*/
-declare function map<
-	T,
-	E,
-	U
->(result: Result<T, E>, fn: (data: T) => U): Result<U, E>;
-/**
-* Chains Result-returning functions.
-*
-* Allows chaining operations that can fail without nested try/catch.
-*
-* @example
-* // Synchronous
-* const profile = flatMap(
-*   await repo.findOne(userId),
-*   (user) => profileRepo.findOne(user.profileId)
-* );
-*
-* @example
-* // Asynchronous
-* const finalResult = await flatMap(
-*   await repo.findOne(userId),
-*   async (user) => await profileRepo.findOne(user.profileId)
-* );
-*/
-declare function flatMap<
-	T,
-	E,
-	U,
-	F
->(result: Result<T, E>, fn: (data: T) => Result<U, F>): Result<U, E | F>;
-declare function flatMap<
-	T,
-	E,
-	U,
-	F
->(result: Result<T, E>, fn: (data: T) => Promise<Result<U, F>>): Promise<Result<U, E | F>>;
-/**
-* Pattern matching on Result.
-*
-* @example
-* const message = match(result, {
-*   ok: (user) => \`Hello, \${user.name}!\`,
-*   err: (e) => \`Error: \${e.message}\`
-* });
-*/
-declare function match<
-	T,
-	E,
-	OkR,
-	ErrR
->(result: Result<T, E>, handlers: {
-	ok: (data: T) => OkR;
-	err: (error: E) => ErrR;
-}): OkR | ErrR;
-/**
-* Type for error handlers in matchErr.
-* Extracts error codes from an error union and creates a handler map.
-*/
-type ErrorHandlers<
-	E,
-	R
-> = { [K in E as K extends {
-	readonly code: infer C extends string;
-} ? C : never] : (error: K) => R };
-/**
-* Exhaustive pattern matching on Result errors.
-*
-* Unlike `match()` which gives you a single `err` handler,
-* `matchErr` requires a handler for every error type in the union.
-* The compiler enforces exhaustiveness — add a new error type to the union
-* and every callsite lights up until you handle it.
-*
-* Errors are discriminated by their `code` string literal field.
-*
-* @example
-* const response = matchErr(result, {
-*   ok: (user) => json({ data: user }, 201),
-*   NOT_FOUND: (e) => json({ error: 'NOT_FOUND', message: e.message }, 404),
-*   UNIQUE_VIOLATION: (e) => json({ error: 'EMAIL_EXISTS', field: e.column }, 409),
-* });
-* // ^ Compile error if error union adds a new member you didn't handle
-*
-* @throws Error if an error code is not handled
-*/
-declare function matchErr<
-	T,
-	E extends {
-		readonly code: string;
-	},
-	R
->(result: Result<T, E>, handlers: {
-	ok: (data: T) => R;
-} & ErrorHandlers<E, R>): R;
-/**
-* Type guard for Ok results.
-*
-* @example
-* if (isOk(result)) {
-*   console.log(result.data); // TypeScript knows this is T
-* }
-*/
-declare function isOk<
-	T,
-	E
->(result: Result<T, E>): result is Ok<T>;
-/**
-* Type guard for Err results.
-*
-* @example
-* if (isErr(result)) {
-*   console.log(result.error); // TypeScript knows this is E
-* }
-*/
-declare function isErr<
-	T,
-	E
->(result: Result<T, E>): result is Err<E>;
-/**
 * AppError - Base class for custom domain errors thrown by app developers.
 *
 * This is the standard way for app developers to define and throw domain errors.
@@ -293,38 +42,275 @@ declare class AppError<C extends string = string> extends Error {
 	toJSON(): Record<string, unknown>;
 }
 /**
-* Schema validation errors.
+* Authentication and authorization domain errors.
 *
-* These errors are returned when schema validation fails.
+* These errors are returned from auth operations.
 */
 /**
-* Issue within a validation error.
+* Invalid credentials error.
+*
+* Returned when authentication fails due to wrong email/password.
 */
-interface ValidationIssue {
-	readonly path: readonly (string | number)[];
+interface InvalidCredentialsError {
+	readonly code: "INVALID_CREDENTIALS";
 	readonly message: string;
+}
+/**
+* Creates an InvalidCredentialsError.
+*/
+declare function createInvalidCredentialsError(message?: string): InvalidCredentialsError;
+/**
+* Type guard for InvalidCredentialsError.
+*/
+declare function isInvalidCredentialsError(error: {
 	readonly code: string;
+}): error is InvalidCredentialsError;
+/**
+* User already exists error.
+*
+* Returned when attempting to sign up with an existing email.
+*/
+interface UserExistsError {
+	readonly code: "USER_EXISTS";
+	readonly message: string;
+	readonly email?: string;
 }
 /**
-* Validation failed error.
+* Creates a UserExistsError.
+*/
+declare function createUserExistsError(message?: string, email?: string): UserExistsError;
+/**
+* Type guard for UserExistsError.
+*/
+declare function isUserExistsError(error: {
+	readonly code: string;
+}): error is UserExistsError;
+/**
+* Session expired error.
 *
-* Returned when input doesn't match schema expectations.
+* Returned when a token is no longer valid (expired, revoked, etc.).
 */
-interface ValidationError {
-	readonly code: "VALIDATION_FAILED";
+interface SessionExpiredError {
+	readonly code: "SESSION_EXPIRED";
 	readonly message: string;
-	readonly issues: readonly ValidationIssue[];
+}
+/**
+* Creates a SessionExpiredError.
+*/
+declare function createSessionExpiredError(message?: string): SessionExpiredError;
+/**
+* Type guard for SessionExpiredError.
+*/
+declare function isSessionExpiredError(error: {
+	readonly code: string;
+}): error is SessionExpiredError;
+/**
+* Permission denied error.
+*
+* Returned when authenticated but not authorized to perform an action.
+*/
+interface PermissionDeniedError {
+	readonly code: "PERMISSION_DENIED";
+	readonly message: string;
+	readonly resource?: string;
+	readonly action?: string;
+}
+/**
+* Creates a PermissionDeniedError.
+*/
+declare function createPermissionDeniedError(message?: string, options?: {
+	resource?: string;
+	action?: string;
+}): PermissionDeniedError;
+/**
+* Type guard for PermissionDeniedError.
+*/
+declare function isPermissionDeniedError(error: {
+	readonly code: string;
+}): error is PermissionDeniedError;
+/**
+* Rate limited error.
+*
+* Returned when too many attempts have been made.
+*/
+interface RateLimitedError {
+	readonly code: "RATE_LIMITED";
+	readonly message: string;
+	readonly retryAfter?: number;
+}
+/**
+* Creates a RateLimitedError.
+*/
+declare function createRateLimitedError(message?: string, retryAfter?: number): RateLimitedError;
+/**
+* Type guard for RateLimitedError.
+*/
+declare function isRateLimitedError(error: {
+	readonly code: string;
+}): error is RateLimitedError;
+/**
+* Auth validation error.
+*
+* Returned when auth input fails validation (invalid email, weak password, etc.).
+*/
+interface AuthValidationError {
+	readonly code: "AUTH_VALIDATION_ERROR";
+	readonly message: string;
+	readonly field: "email" | "password";
+	readonly constraint?: string;
+}
+/**
+* Creates an AuthValidationError.
+*/
+declare function createAuthValidationError(message: string, field: "email" | "password", constraint?: string): AuthValidationError;
+/**
+* Type guard for AuthValidationError.
+*/
+declare function isAuthValidationError(error: {
+	readonly code: string;
+}): error is AuthValidationError;
+/**
+* Union type for all auth errors.
+*/
+type AuthError = InvalidCredentialsError | UserExistsError | SessionExpiredError | PermissionDeniedError | RateLimitedError | AuthValidationError;
+/**
+* Client domain errors.
+*
+* These errors are used at the HTTP boundary and use client-native vocabulary
+* (not DB internals). They map from server HTTP responses.
+*/
+/**
+* Validation error (client-facing).
+*
+* Maps from server's VALIDATION_FAILED.
+*/
+interface ValidationError2 {
+	readonly code: "ValidationError";
+	readonly message: string;
+	readonly issues?: readonly {
+		readonly path: readonly (string | number)[];
+		readonly message: string;
+		readonly code: string;
+	}[];
 }
 /**
 * Creates a ValidationError.
 */
-declare function createValidationError(message: string, issues: readonly ValidationIssue[]): ValidationError;
+declare function createValidationError(message: string, issues?: readonly {
+	readonly path: readonly (string | number)[];
+	readonly message: string;
+	readonly code: string;
+}[]): ValidationError2;
 /**
 * Type guard for ValidationError.
 */
 declare function isValidationError(error: {
 	readonly code: string;
-}): error is ValidationError;
+}): error is ValidationError2;
+/**
+* Not found error (client-facing).
+*
+* Maps from server's NOT_FOUND.
+*/
+interface NotFoundError {
+	readonly code: "NotFound";
+	readonly message: string;
+	readonly resource?: string;
+}
+/**
+* Creates a NotFoundError.
+*/
+declare function createNotFoundError(message?: string, resource?: string): NotFoundError;
+/**
+* Type guard for NotFoundError.
+*/
+declare function isNotFoundError(error: {
+	readonly code: string;
+}): error is NotFoundError;
+/**
+* Conflict error (client-facing).
+*
+* Maps from server's UNIQUE_VIOLATION.
+*/
+interface ConflictError {
+	readonly code: "Conflict";
+	readonly message: string;
+	readonly field?: string;
+}
+/**
+* Creates a ConflictError.
+*/
+declare function createConflictError(message?: string, field?: string): ConflictError;
+/**
+* Type guard for ConflictError.
+*/
+declare function isConflictError(error: {
+	readonly code: string;
+}): error is ConflictError;
+/**
+* Unauthorized error.
+*
+* Returned when the user is not authenticated.
+*/
+interface UnauthorizedError {
+	readonly code: "Unauthorized";
+	readonly message: string;
+}
+/**
+* Creates an UnauthorizedError.
+*/
+declare function createUnauthorizedError(message?: string): UnauthorizedError;
+/**
+* Type guard for UnauthorizedError.
+*/
+declare function isUnauthorizedError(error: {
+	readonly code: string;
+}): error is UnauthorizedError;
+/**
+* Forbidden error.
+*
+* Returned when the user is authenticated but not authorized.
+*/
+interface ForbiddenError {
+	readonly code: "Forbidden";
+	readonly message: string;
+}
+/**
+* Creates a ForbiddenError.
+*/
+declare function createForbiddenError(message?: string): ForbiddenError;
+/**
+* Type guard for ForbiddenError.
+*/
+declare function isForbiddenError(error: {
+	readonly code: string;
+}): error is ForbiddenError;
+/**
+* Rate limited error (client-facing).
+*
+* Maps from server's RATE_LIMITED.
+*/
+interface RateLimitedError2 {
+	readonly code: "RATE_LIMITED";
+	readonly message: string;
+	readonly retryAfter?: number;
+}
+/**
+* Creates a RateLimitedError.
+*/
+declare function createRateLimitedError2(message?: string, retryAfter?: number): RateLimitedError2;
+/**
+* Type guard for RateLimitedError.
+*/
+declare function isRateLimitedError2(error: {
+	readonly code: string;
+}): error is RateLimitedError2;
+/**
+* Union type for all client errors.
+*
+* These are the errors that clients receive from API calls.
+*/
+type ApiError = ValidationError2 | NotFoundError | ConflictError | UnauthorizedError | ForbiddenError | RateLimitedError2;
 /**
 * Database domain errors.
 *
@@ -337,8 +323,8 @@ declare function isValidationError(error: {
 * Returned when a required record is not found (from findOneRequired).
 * Note: findOne() returns Result<T | null, never> - null is success.
 */
-interface NotFoundError {
-	readonly code: "NOT_FOUND";
+interface NotFoundError2 {
+	readonly code: "NotFound";
 	readonly message: string;
 	readonly table: string;
 	readonly key?: Record<string, unknown>;
@@ -346,17 +332,17 @@ interface NotFoundError {
 /**
 * Creates a NotFoundError.
 */
-declare function createNotFoundError(table: string, key?: Record<string, unknown>): NotFoundError;
+declare function createNotFoundError2(table: string, key?: Record<string, unknown>): NotFoundError2;
 /**
 * Type guard for NotFoundError.
 */
-declare function isNotFoundError(error: {
+declare function isNotFoundError2(error: {
 	readonly code: string;
-}): error is NotFoundError;
+}): error is NotFoundError2;
 /**
 * Union type for all read errors.
 */
-type ReadError = NotFoundError;
+type ReadError = NotFoundError2;
 /**
 * Unique constraint violation.
 *
@@ -464,376 +450,1065 @@ declare function isCheckViolation(error: {
 */
 type WriteError = UniqueViolation | FKViolation | NotNullViolation | CheckViolation;
 /**
-* Authentication and authorization domain errors.
+* Migration domain errors.
 *
-* These errors are returned from auth operations.
+* These errors are returned from migration operations and represent
+* expected runtime failures that require case-by-case handling.
 */
 /**
-* Invalid credentials error.
+* Migration query execution failed.
 *
-* Returned when authentication fails due to wrong email/password.
+* Returned when a migration SQL statement fails to execute.
 */
-interface InvalidCredentialsError {
-	readonly code: "INVALID_CREDENTIALS";
+interface MigrationQueryError {
+	readonly code: "MIGRATION_QUERY_ERROR";
 	readonly message: string;
+	readonly sql?: string;
+	readonly cause?: unknown;
 }
 /**
-* Creates an InvalidCredentialsError.
+* Creates a MigrationQueryError.
 */
-declare function createInvalidCredentialsError(message?: string): InvalidCredentialsError;
+declare function createMigrationQueryError(message: string, options?: {
+	sql?: string;
+	cause?: unknown;
+}): MigrationQueryError;
 /**
-* Type guard for InvalidCredentialsError.
+* Type guard for MigrationQueryError.
 */
-declare function isInvalidCredentialsError(error: {
+declare function isMigrationQueryError(error: {
 	readonly code: string;
-}): error is InvalidCredentialsError;
+}): error is MigrationQueryError;
 /**
-* User already exists error.
+* Migration checksum mismatch detected.
 *
-* Returned when attempting to sign up with an existing email.
+* Returned when an applied migration's checksum doesn't match the file on disk.
 */
-interface UserExistsError {
-	readonly code: "USER_EXISTS";
+interface MigrationChecksumMismatch {
+	readonly code: "MIGRATION_CHECKSUM_MISMATCH";
 	readonly message: string;
-	readonly email?: string;
+	readonly migrationName: string;
+	readonly expectedChecksum: string;
+	readonly actualChecksum: string;
 }
 /**
-* Creates a UserExistsError.
+* Creates a MigrationChecksumMismatch error.
 */
-declare function createUserExistsError(message?: string, email?: string): UserExistsError;
+declare function createMigrationChecksumMismatch(migrationName: string, expectedChecksum: string, actualChecksum: string): MigrationChecksumMismatch;
 /**
-* Type guard for UserExistsError.
+* Type guard for MigrationChecksumMismatch.
 */
-declare function isUserExistsError(error: {
+declare function isMigrationChecksumMismatch(error: {
 	readonly code: string;
-}): error is UserExistsError;
+}): error is MigrationChecksumMismatch;
 /**
-* Session expired error.
+* Migration history table not found.
 *
-* Returned when a token is no longer valid (expired, revoked, etc.).
+* Returned when attempting to query migration history before the table exists.
 */
-interface SessionExpiredError {
-	readonly code: "SESSION_EXPIRED";
+interface MigrationHistoryNotFound {
+	readonly code: "MIGRATION_HISTORY_NOT_FOUND";
 	readonly message: string;
 }
 /**
-* Creates a SessionExpiredError.
+* Creates a MigrationHistoryNotFound error.
 */
-declare function createSessionExpiredError(message?: string): SessionExpiredError;
+declare function createMigrationHistoryNotFound(): MigrationHistoryNotFound;
 /**
-* Type guard for SessionExpiredError.
+* Type guard for MigrationHistoryNotFound.
 */
-declare function isSessionExpiredError(error: {
+declare function isMigrationHistoryNotFound(error: {
 	readonly code: string;
-}): error is SessionExpiredError;
+}): error is MigrationHistoryNotFound;
 /**
-* Permission denied error.
+* Union type for all migration errors.
+*/
+type MigrationError = MigrationQueryError | MigrationChecksumMismatch | MigrationHistoryNotFound;
+/**
+* Schema validation errors.
 *
-* Returned when authenticated but not authorized to perform an action.
+* These errors are returned when schema validation fails.
 */
-interface PermissionDeniedError {
-	readonly code: "PERMISSION_DENIED";
+/**
+* Issue within a validation error.
+*/
+interface ValidationIssue {
+	readonly path: readonly (string | number)[];
 	readonly message: string;
-	readonly resource?: string;
-	readonly action?: string;
+	readonly code: string;
 }
 /**
-* Creates a PermissionDeniedError.
+* Validation failed error.
+*
+* Returned when input doesn't match schema expectations.
 */
-declare function createPermissionDeniedError(message?: string, options?: {
-	resource?: string;
-	action?: string;
-}): PermissionDeniedError;
+interface ValidationError3 {
+	readonly code: "VALIDATION_FAILED";
+	readonly message: string;
+	readonly issues: readonly ValidationIssue[];
+}
 /**
-* Type guard for PermissionDeniedError.
+* Creates a ValidationError.
 */
-declare function isPermissionDeniedError(error: {
+declare function createValidationError2(message: string, issues: readonly ValidationIssue[]): ValidationError3;
+/**
+* Type guard for ValidationError.
+*/
+declare function isValidationError2(error: {
 	readonly code: string;
-}): error is PermissionDeniedError;
+}): error is ValidationError3;
 /**
-* Rate limited error.
+* Infrastructure errors.
 *
-* Returned when too many attempts have been made.
+* These are operational failures that the application developer never handles
+* in business logic. They're caught by global middleware/error boundaries
+* and result in 500/503 responses.
 */
-interface RateLimitedError {
-	readonly code: "RATE_LIMITED";
+/**
+* Base class for infrastructure errors.
+*/
+declare class InfraError extends Error {
+	constructor(message: string);
+}
+/**
+* Database connection error.
+*
+* Thrown when the database is unreachable.
+*/
+declare class ConnectionError extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Connection pool exhausted error.
+*
+* Thrown when no connections are available in the pool.
+*/
+declare class PoolExhaustedError extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Query error.
+*
+* Thrown when a query fails (malformed, syntax error, etc.).
+*/
+declare class QueryError extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Timeout error.
+*
+* Thrown when an operation takes too long.
+*/
+declare class TimeoutError2 extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Network error.
+*
+* Thrown when HTTP client can't reach the server.
+*/
+declare class NetworkError2 extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Serialization error.
+*
+* Thrown when response couldn't be decoded.
+*/
+declare class SerializationError extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Union type for all infrastructure errors.
+*/
+type InfraErrors = ConnectionError | PoolExhaustedError | QueryError | TimeoutError2 | NetworkError2 | SerializationError;
+/**
+* Maps a database error to an HTTP status code.
+*
+* @param error - A database domain error
+* @returns HTTP status code
+*
+* @example
+* const status = dbErrorToHttpStatus(error);
+* // NOT_FOUND → 404
+* // UNIQUE_VIOLATION → 409
+* // FK_VIOLATION → 422
+* // NOT_NULL_VIOLATION → 422
+* // CHECK_VIOLATION → 422
+*/
+declare function dbErrorToHttpStatus(error: ReadError | WriteError): number;
+/**
+* Maps a NotFoundError to HTTP status.
+*/
+declare function notFoundErrorToHttpStatus(_error: NotFoundError2): number;
+/**
+* Maps a UniqueViolation to HTTP status.
+*/
+declare function uniqueViolationToHttpStatus(_error: UniqueViolation): number;
+/**
+* Maps a FKViolation to HTTP status.
+*/
+declare function fkViolationToHttpStatus(_error: FKViolation): number;
+/**
+* Maps a NotNullViolation to HTTP status.
+*/
+declare function notNullViolationToHttpStatus(_error: NotNullViolation): number;
+/**
+* Maps a CheckViolation to HTTP status.
+*/
+declare function checkViolationToHttpStatus(_error: CheckViolation): number;
+/**
+* Unknown error response from server.
+*/
+interface UnknownError {
+	readonly code: "UNKNOWN";
 	readonly message: string;
-	readonly retryAfter?: number;
+	readonly status: number;
+}
+/**
+* Maps an HTTP response to a client domain error.
+*
+* @param status - HTTP status code
+* @param body - Response body
+* @returns Client domain error
+*
+* @example
+* const error = httpToClientError(404, { message: 'User not found' });
+* // { code: 'NOT_FOUND', message: 'User not found', resource: 'user' }
+*/
+declare function httpToClientError(status: number, body: unknown): ApiError | UnknownError;
+/**
+* Checks if an error is an UnknownError.
+*/
+declare function isUnknownError(error: ApiError | UnknownError): error is UnknownError;
+/**
+* Result type and utilities for errors-as-values pattern.
+*
+* This module provides a type-safe alternative to throwing exceptions.
+* Every operation that can fail returns a Result<T, E> instead of throwing.
+*
+* @example
+* import { ok, err, unwrap, map, flatMap, match, matchErr } from '@vertz/errors';
+*
+* // Creating results
+* const success = ok({ name: 'Alice' });
+* const failure = err({ code: 'NOT_FOUND', message: 'User not found' });
+*
+* // Transforming
+* const doubled = map(ok(5), x => x * 2);
+*
+* // Chaining
+* const result = await flatMap(ok(5), async x => ok(x * 2));
+*
+* // Pattern matching
+* const message = match(result, {
+*   ok: (data) => `Success: ${data}`,
+*   err: (error) => `Error: ${error.message}`
+* });
+*/
+/**
+* Represents a successful result.
+*
+* @example
+* { ok: true, data: { name: 'Alice' } }
+*/
+interface Ok<T> {
+	/** Always true for successful results */
+	readonly ok: true;
+	/** The successful value */
+	readonly data: T;
+}
+/**
+* Represents an erroneous result.
+*
+* @example
+* { ok: false, error: { code: 'NOT_FOUND', message: 'User not found' } }
+*/
+interface Err<E> {
+	/** Always false for error results */
+	readonly ok: false;
+	/** The error value */
+	readonly error: E;
+}
+/**
+* A discriminated union representing success or failure.
+*
+* @example
+* type UserResult = Result<User, ValidationError>;
+* type UsersResult = Result<User[], NotFoundError>;
+*
+* @example
+* const result: Result<string, Error> = ok('hello');
+* if (result.ok) {
+*   console.log(result.data); // TypeScript knows this is string
+* } else {
+*   console.log(result.error); // TypeScript knows this is Error
+* }
+*/
+type Result<
+	T,
+	E = unknown
+> = Ok<T> | Err<E>;
+/**
+* Creates a successful Result.
+*
+* @example
+* const result = ok({ name: 'Alice' });
+* // { ok: true, data: { name: 'Alice' } }
+*
+* @example
+* // With type inference
+* const result = ok(42); // Ok<number>
+*/
+declare const ok: <T>(data: T) => Ok<T>;
+/**
+* Creates an error Result.
+*
+* @example
+* const result = err({ code: 'VALIDATION_FAILED', message: 'Invalid email', issues: [] });
+* // { ok: false, error: { code: 'VALIDATION_FAILED', ... } }
+*
+* @example
+* // With simple string errors
+* const result = err('Something went wrong');
+* // { ok: false, error: 'Something went wrong' }
+*/
+declare const err: <E>(error: E) => Err<E>;
+/**
+* Unwraps a Result, throwing if error.
+*
+* Use only in tests, scripts, or when failure is truly exceptional.
+*
+* @example
+* // Tests
+* const user = unwrap(await repo.findOneRequired(id));
+*
+* @example
+* // Scripts
+* const config = unwrap(parseConfig());
+*
+* @throws The error value if the Result is an error
+*/
+declare function unwrap<
+	T,
+	E
+>(result: Result<T, E>): T;
+/**
+* Unwraps a Result, returning a default value if error.
+*
+* @example
+* const user = await findById(id) ?? { name: 'Guest' };
+*/
+declare function unwrapOr<
+	T,
+	E
+>(result: Result<T, E>, defaultValue: T): T;
+/**
+* Maps the success value to a new type.
+*
+* @example
+* const userName = map(userResult, u => u.name);
+* // Result<string, Error> if userResult was Result<User, Error>
+*
+* @example
+* // Transform while preserving error type
+* const id = map(ok({ userId: 5 }), u => u.userId);
+* // Ok<number>
+*/
+declare function map<
+	T,
+	E,
+	U
+>(result: Result<T, E>, fn: (data: T) => U): Result<U, E>;
+/**
+* Chains Result-returning functions.
+*
+* Allows chaining operations that can fail without nested try/catch.
+*
+* @example
+* // Synchronous
+* const profile = flatMap(
+*   await repo.findOne(userId),
+*   (user) => profileRepo.findOne(user.profileId)
+* );
+*
+* @example
+* // Asynchronous
+* const finalResult = await flatMap(
+*   await repo.findOne(userId),
+*   async (user) => await profileRepo.findOne(user.profileId)
+* );
+*/
+declare function flatMap<
+	T,
+	E,
+	U,
+	F
+>(result: Result<T, E>, fn: (data: T) => Result<U, F>): Result<U, E | F>;
+declare function flatMap<
+	T,
+	E,
+	U,
+	F
+>(result: Result<T, E>, fn: (data: T) => Promise<Result<U, F>>): Promise<Result<U, E | F>>;
+/**
+* Pattern matching on Result.
+*
+* @example
+* const message = match(result, {
+*   ok: (user) => \`Hello, \${user.name}!\`,
+*   err: (e) => \`Error: \${e.message}\`
+* });
+*/
+declare function match<
+	T,
+	E,
+	OkR,
+	ErrR
+>(result: Result<T, E>, handlers: {
+	ok: (data: T) => OkR;
+	err: (error: E) => ErrR;
+}): OkR | ErrR;
+/**
+* Type for error handlers in matchErr.
+* Extracts error codes from an error union and creates a handler map.
+*/
+type ErrorHandlers<
+	E,
+	R
+> = { [K in E as K extends {
+	readonly code: infer C extends string;
+} ? C : never] : (error: K) => R };
+/**
+* Exhaustive pattern matching on Result errors.
+*
+* Unlike `match()` which gives you a single `err` handler,
+* `matchErr` requires a handler for every error type in the union.
+* The compiler enforces exhaustiveness — add a new error type to the union
+* and every callsite lights up until you handle it.
+*
+* Errors are discriminated by their `code` string literal field.
+*
+* @example
+* const response = matchErr(result, {
+*   ok: (user) => json({ data: user }, 201),
+*   NOT_FOUND: (e) => json({ error: 'NOT_FOUND', message: e.message }, 404),
+*   UNIQUE_VIOLATION: (e) => json({ error: 'EMAIL_EXISTS', field: e.column }, 409),
+* });
+* // ^ Compile error if error union adds a new member you didn't handle
+*
+* @throws Error if an error code is not handled
+*/
+declare function matchErr<
+	T,
+	E extends {
+		readonly code: string;
+	},
+	R
+>(result: Result<T, E>, handlers: {
+	ok: (data: T) => R;
+} & ErrorHandlers<E, R>): R;
+/**
+* Type guard for Ok results.
+*
+* @example
+* if (isOk(result)) {
+*   console.log(result.data); // TypeScript knows this is T
+* }
+*/
+declare function isOk<
+	T,
+	E
+>(result: Result<T, E>): result is Ok<T>;
+/**
+* Type guard for Err results.
+*
+* @example
+* if (isErr(result)) {
+*   console.log(result.error); // TypeScript knows this is E
+* }
+*/
+declare function isErr<
+	T,
+	E
+>(result: Result<T, E>): result is Err<E>;
+/**
+* Fetch error classes.
+*
+* These errors are used when making HTTP requests from the client.
+*/
+/**
+* Base class for fetch errors.
+*/
+declare abstract class FetchError extends Error {
+	/**
+	* The error code - a string literal for type-safe discrimination.
+	*/
+	readonly code: string;
+	constructor(code: string, message: string);
+}
+/**
+* Network error - thrown when the request can't reach the server.
+*
+* @example
+* // When the server is unreachable
+* const result = await client.get('/users');
+* if (!result.ok && result.error.code === 'NETWORK_ERROR') {
+*   console.log('Network failed:', result.error.message);
+* }
+*/
+declare class FetchNetworkError extends FetchError {
+	readonly code: "NetworkError";
+	constructor(message?: string);
+}
+/**
+* Type guard for FetchNetworkError.
+*/
+declare function isFetchNetworkError(error: unknown): error is FetchNetworkError;
+/**
+* Base HTTP error - thrown when the server returns an error response.
+* Use specific error classes (BadRequestError, NotFoundError, etc.) when available.
+*
+* @example
+* const result = await client.get('/users/123');
+* if (!result.ok && result.error.code === 'HTTP_ERROR') {
+*   const httpError = result.error;
+*   console.log('Status:', httpError.status);      // e.g., 404
+*   console.log('Server code:', httpError.serverCode); // e.g., 'NOT_FOUND'
+*   console.log('Message:', httpError.message);
+* }
+*/
+declare class HttpError2 extends FetchError {
+	readonly code: "HttpError";
+	/**
+	* HTTP status code.
+	*/
+	readonly status: number;
+	/**
+	* Server error code (from response body).
+	*/
+	readonly serverCode?: string;
+	constructor(status: number, message: string, serverCode?: string);
 }
 /**
-* Creates a RateLimitedError.
+* Type guard for HttpError.
 */
-declare function createRateLimitedError(message?: string, retryAfter?: number): RateLimitedError;
+declare function isHttpError(error: unknown): error is HttpError2;
 /**
-* Type guard for RateLimitedError.
+* Bad Request (400) - The request was invalid or cannot be served.
 */
-declare function isRateLimitedError(error: {
-	readonly code: string;
-}): error is RateLimitedError;
+declare class FetchBadRequestError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 400;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Union type for all auth errors.
+* Type guard for FetchBadRequestError.
 */
-type AuthError = InvalidCredentialsError | UserExistsError | SessionExpiredError | PermissionDeniedError | RateLimitedError;
+declare function isFetchBadRequestError(error: unknown): error is FetchBadRequestError;
 /**
-* Client domain errors.
-*
-* These errors are used at the HTTP boundary and use client-native vocabulary
-* (not DB internals). They map from server HTTP responses.
+* Unauthorized (401) - Authentication is required or failed.
 */
+declare class FetchUnauthorizedError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 401;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Validation error (client-facing).
-*
-* Maps from server's VALIDATION_FAILED.
+* Type guard for FetchUnauthorizedError.
 */
-interface ValidationError2 {
-	readonly code: "VALIDATION_ERROR";
-	readonly message: string;
-	readonly issues?: readonly {
-		readonly path: readonly (string | number)[];
-		readonly message: string;
-		readonly code: string;
-	}[];
+declare function isFetchUnauthorizedError(error: unknown): error is FetchUnauthorizedError;
+/**
+* Forbidden (403) - The request is understood but refused.
+*/
+declare class FetchForbiddenError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 403;
+	constructor(message: string, serverCode?: string);
 }
 /**
-* Creates a ValidationError.
+* Type guard for FetchForbiddenError.
 */
-declare function createValidationError2(message: string, issues?: readonly {
-	readonly path: readonly (string | number)[];
-	readonly message: string;
-	readonly code: string;
-}[]): ValidationError2;
+declare function isFetchForbiddenError(error: unknown): error is FetchForbiddenError;
 /**
-* Type guard for ValidationError.
+* Not Found (404) - The requested resource was not found.
 */
-declare function isValidationError2(error: {
-	readonly code: string;
-}): error is ValidationError2;
+declare class FetchNotFoundError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 404;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Not found error (client-facing).
-*
-* Maps from server's NOT_FOUND.
+* Type guard for FetchNotFoundError.
 */
-interface NotFoundError2 {
-	readonly code: "NOT_FOUND";
-	readonly message: string;
-	readonly resource?: string;
+declare function isFetchNotFoundError(error: unknown): error is FetchNotFoundError;
+/**
+* Conflict (409) - The request conflicts with current state.
+*/
+declare class FetchConflictError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 409;
+	constructor(message: string, serverCode?: string);
 }
 /**
-* Creates a NotFoundError.
+* Type guard for FetchConflictError.
 */
-declare function createNotFoundError2(message?: string, resource?: string): NotFoundError2;
+declare function isFetchConflictError(error: unknown): error is FetchConflictError;
 /**
-* Type guard for NotFoundError.
+* Gone (410) - The resource is no longer available.
 */
-declare function isNotFoundError2(error: {
-	readonly code: string;
-}): error is NotFoundError2;
+declare class FetchGoneError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 410;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Conflict error (client-facing).
-*
-* Maps from server's UNIQUE_VIOLATION.
+* Type guard for FetchGoneError.
 */
-interface ConflictError {
-	readonly code: "CONFLICT";
-	readonly message: string;
-	readonly field?: string;
+declare function isFetchGoneError(error: unknown): error is FetchGoneError;
+/**
+* Unprocessable Entity (422) - The request was well-formed but semantically invalid.
+*/
+declare class FetchUnprocessableEntityError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 422;
+	constructor(message: string, serverCode?: string);
 }
 /**
-* Creates a ConflictError.
+* Type guard for FetchUnprocessableEntityError.
 */
-declare function createConflictError(message?: string, field?: string): ConflictError;
+declare function isFetchUnprocessableEntityError(error: unknown): error is FetchUnprocessableEntityError;
 /**
-* Type guard for ConflictError.
+* Rate Limited (429) - Too many requests.
 */
-declare function isConflictError(error: {
-	readonly code: string;
-}): error is ConflictError;
+declare class FetchRateLimitError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 429;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Unauthorized error.
-*
-* Returned when the user is not authenticated.
+* Type guard for FetchRateLimitError.
 */
-interface UnauthorizedError {
-	readonly code: "UNAUTHORIZED";
-	readonly message: string;
+declare function isFetchRateLimitError(error: unknown): error is FetchRateLimitError;
+/**
+* Internal Server Error (500) - The server encountered an error.
+*/
+declare class FetchInternalServerError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 500;
+	constructor(message: string, serverCode?: string);
 }
 /**
-* Creates an UnauthorizedError.
+* Type guard for FetchInternalServerError.
 */
-declare function createUnauthorizedError(message?: string): UnauthorizedError;
+declare function isFetchInternalServerError(error: unknown): error is FetchInternalServerError;
 /**
-* Type guard for UnauthorizedError.
+* Service Unavailable (503) - The server is temporarily unavailable.
 */
-declare function isUnauthorizedError(error: {
-	readonly code: string;
-}): error is UnauthorizedError;
+declare class FetchServiceUnavailableError extends HttpError2 {
+	readonly code: "HttpError";
+	readonly status: 503;
+	constructor(message: string, serverCode?: string);
+}
 /**
-* Forbidden error.
+* Type guard for FetchServiceUnavailableError.
+*/
+declare function isFetchServiceUnavailableError(error: unknown): error is FetchServiceUnavailableError;
+/**
+* Timeout error - thrown when the request takes too long.
 *
-* Returned when the user is authenticated but not authorized.
+* @example
+* // Configure timeout in client options
+* const client = createClient({ baseURL: '...', timeout: 5000 });
+*
+* const result = await client.get('/slow-endpoint');
+* if (!result.ok && result.error.code === 'TIMEOUT_ERROR') {
+*   console.log('Request timed out:', result.error.message);
+*   // Retry the request
+* }
 */
-interface ForbiddenError {
-	readonly code: "FORBIDDEN";
-	readonly message: string;
+declare class FetchTimeoutError extends FetchError {
+	readonly code: "TimeoutError";
+	constructor(message?: string);
 }
 /**
-* Creates a ForbiddenError.
+* Type guard for FetchTimeoutError.
 */
-declare function createForbiddenError(message?: string): ForbiddenError;
+declare function isFetchTimeoutError(error: unknown): error is FetchTimeoutError;
 /**
-* Type guard for ForbiddenError.
+* Parse error - thrown when response parsing fails.
+*
+* @example
+* // Server returns invalid JSON
+* const result = await client.get('/malformed');
+* if (!result.ok && result.error.code === 'PARSE_ERROR') {
+*   console.log('Parse failed at:', result.error.path);  // e.g., 'users.0.name'
+*   console.log('Invalid value:', result.error.value);
+* }
 */
-declare function isForbiddenError(error: {
-	readonly code: string;
-}): error is ForbiddenError;
+declare class ParseError2 extends FetchError {
+	readonly code: "ParseError";
+	/**
+	* Path where parsing failed.
+	*/
+	readonly path: string;
+	/**
+	* The value that failed to parse.
+	*/
+	readonly value?: unknown;
+	constructor(path: string, message: string, value?: unknown);
+}
 /**
-* Rate limited error (client-facing).
+* Type guard for ParseError.
+*/
+declare function isParseError(error: unknown): error is ParseError2;
+/**
+* Validation error - thrown when request validation fails.
 *
-* Maps from server's RATE_LIMITED.
+* @example
+* // Server returns validation errors
+* const result = await client.post('/users', { name: '' });
+* if (!result.ok && result.error.code === 'VALIDATION_ERROR') {
+*   result.error.errors.forEach(err => {
+*     console.log(`Field: ${err.path}, Error: ${err.message}`);
+*   });
+* }
+*
+* @example
+* // Using with matchError for exhaustive handling
+* matchError(result.error, {
+*   VALIDATION_ERROR: (e) => setFormErrors(e.errors),
+*   NETWORK_ERROR: () => showNetworkError(),
+*   // ... other handlers
+* });
 */
-interface RateLimitedError2 {
-	readonly code: "RATE_LIMITED";
-	readonly message: string;
-	readonly retryAfter?: number;
+declare class FetchValidationError extends FetchError {
+	readonly code: "ValidationError";
+	/**
+	* Validation errors matching server format.
+	*/
+	readonly errors: readonly {
+		readonly path: string;
+		readonly message: string;
+	}[];
+	constructor(message: string, errors: readonly {
+		readonly path: string;
+		readonly message: string;
+	}[]);
 }
 /**
-* Creates a RateLimitedError.
+* Type guard for FetchValidationError.
 */
-declare function createRateLimitedError2(message?: string, retryAfter?: number): RateLimitedError2;
+declare function isFetchValidationError(error: unknown): error is FetchValidationError;
 /**
-* Type guard for RateLimitedError.
+* Creates the appropriate error class based on HTTP status code.
 */
-declare function isRateLimitedError2(error: {
-	readonly code: string;
-}): error is RateLimitedError2;
+declare function createHttpError(status: number, message: string, serverCode?: string): FetchError;
 /**
-* Union type for all client errors.
+* Union type for all fetch errors.
 *
-* These are the errors that clients receive from API calls.
+* @example
+* import { matchError, FetchErrorType } from '@vertz/errors';
+*
+* // Using with matchError for exhaustive handling
+* function handleError(error: FetchErrorType): string {
+*   return matchError(error, {
+*     NETWORK_ERROR: (e) => `Network failed: ${e.message}`,
+*     HTTP_ERROR: (e) => `HTTP ${e.status}: ${e.message}`,
+*     TIMEOUT_ERROR: (e) => `Timeout: ${e.message}`,
+*     PARSE_ERROR: (e) => `Parse failed at ${e.path}`,
+*     VALIDATION_ERROR: (e) => `Validation: ${e.errors.length} errors`,
+*   });
+* }
+*
+* @example
+* // Using with Result
+* const result = await client.get<User>('/users/123');
+* const errorMessage = result.ok ? '' : handleError(result.error);
 */
-type ApiError = ValidationError2 | NotFoundError2 | ConflictError | UnauthorizedError | ForbiddenError | RateLimitedError2;
+type FetchErrorType = FetchNetworkError | HttpError2 | FetchBadRequestError | FetchUnauthorizedError | FetchForbiddenError | FetchNotFoundError | FetchConflictError | FetchGoneError | FetchUnprocessableEntityError | FetchRateLimitError | FetchInternalServerError | FetchServiceUnavailableError | FetchTimeoutError | ParseError2 | FetchValidationError;
 /**
-* Infrastructure errors.
+* Entity error classes.
 *
-* These are operational failures that the application developer never handles
-* in business logic. They're caught by global middleware/error boundaries
-* and result in 500/503 responses.
+* These errors mirror server HTTP error codes and are used at the HTTP boundary.
 */
 /**
-* Base class for infrastructure errors.
+* Base class for entity errors.
+*
+* @example
+* import { EntityError } from '@ *
+* // Checkvertz/errors';
+error type
+* if (error instanceof EntityError) {
+*   console.log(error.code);  // e.g., 'NOT_FOUND'
+*   console.log(error.message);
+* }
 */
-declare class InfraError extends Error {
-	constructor(message: string);
+declare abstract class EntityError extends Error {
+	/**
+	* The error code - a string literal for type-safe discrimination.
+	*/
+	readonly code: string;
+	constructor(code: string, message: string);
 }
 /**
-* Database connection error.
-*
-* Thrown when the database is unreachable.
+* Bad request error - 400.
 */
-declare class ConnectionError extends InfraError {
+declare class BadRequestError extends EntityError {
+	readonly code: "BadRequest";
 	constructor(message?: string);
 }
 /**
-* Connection pool exhausted error.
-*
-* Thrown when no connections are available in the pool.
+* Type guard for BadRequestError.
 */
-declare class PoolExhaustedError extends InfraError {
+declare function isBadRequestError(error: unknown): error is BadRequestError;
+/**
+* Unauthorized error - 401.
+*/
+declare class EntityUnauthorizedError extends EntityError {
+	readonly code: "Unauthorized";
 	constructor(message?: string);
 }
 /**
-* Query error.
-*
-* Thrown when a query fails (malformed, syntax error, etc.).
+* Type guard for EntityUnauthorizedError.
 */
-declare class QueryError extends InfraError {
+declare function isEntityUnauthorizedError(error: unknown): error is EntityUnauthorizedError;
+/**
+* Forbidden error - 403.
+*/
+declare class EntityForbiddenError extends EntityError {
+	readonly code: "Forbidden";
 	constructor(message?: string);
 }
 /**
-* Timeout error.
+* Type guard for EntityForbiddenError.
+*/
+declare function isEntityForbiddenError(error: unknown): error is EntityForbiddenError;
+/**
+* Not found error - 404.
 *
-* Thrown when an operation takes too long.
+* @example
+* // Using in matchError for server-side error handling
+* const result = await db.users.get(userId);
+* if (!result.ok) {
+*   return matchError(result.error, {
+*     NOT_FOUND: (e) => Response.json(
+*       { error: { code: 'NOT_FOUND', message: `User ${userId} not found` } },
+*       { status: 404 }
+*     ),
+*     // ... other handlers
+*   });
+* }
+*
+* @example
+* // With resource info
+* throw new EntityNotFoundError('User not found', 'User', userId);
 */
-declare class TimeoutError extends InfraError {
-	constructor(message?: string);
+declare class EntityNotFoundError extends EntityError {
+	readonly code: "NotFound";
+	/**
+	* The type of resource that wasn't found.
+	*/
+	readonly resource?: string;
+	/**
+	* The ID of the resource that wasn't found.
+	*/
+	readonly resourceId?: string;
+	constructor(message?: string, resource?: string, resourceId?: string);
 }
 /**
-* Network error.
-*
-* Thrown when HTTP client can't reach the server.
+* Type guard for EntityNotFoundError.
 */
-declare class NetworkError extends InfraError {
-	constructor(message?: string);
+declare function isEntityNotFoundError(error: unknown): error is EntityNotFoundError;
+/**
+* Method not allowed error - 405.
+*/
+declare class MethodNotAllowedError extends EntityError {
+	readonly code: "MethodNotAllowed";
+	/**
+	* Allowed HTTP methods.
+	*/
+	readonly allowedMethods?: string;
+	constructor(allowedMethods?: string, message?: string);
 }
 /**
-* Serialization error.
-*
-* Thrown when response couldn't be decoded.
+* Type guard for MethodNotAllowedError.
 */
-declare class SerializationError extends InfraError {
-	constructor(message?: string);
+declare function isMethodNotAllowedError(error: unknown): error is MethodNotAllowedError;
+/**
+* Conflict error - 409.
+*/
+declare class EntityConflictError extends EntityError {
+	readonly code: "Conflict";
+	/**
+	* The field that caused the conflict.
+	*/
+	readonly field?: string;
+	constructor(message?: string, field?: string);
 }
 /**
-* Union type for all infrastructure errors.
+* Type guard for EntityConflictError.
 */
-type InfraErrors = ConnectionError | PoolExhaustedError | QueryError | TimeoutError | NetworkError | SerializationError;
+declare function isEntityConflictError(error: unknown): error is EntityConflictError;
 /**
-* Maps a database error to an HTTP status code.
+* Entity validation error - 422.
 *
-* @param error - A database domain error
-* @returns HTTP status code
+* @example
+* // Server-side: throwing validation errors
+* throw new EntityValidationError([
+*   { path: ['email'], message: 'Invalid email format', code: 'INVALID_FORMAT' },
+*   { path: ['age'], message: 'Must be positive', code: 'MIN_VALUE' },
+* ]);
 *
 * @example
-* const status = dbErrorToHttpStatus(error);
-* // NOT_FOUND → 404
-* // UNIQUE_VIOLATION → 409
-* // FK_VIOLATION → 422
-* // NOT_NULL_VIOLATION → 422
-* // CHECK_VIOLATION → 422
-*/
-declare function dbErrorToHttpStatus(error: ReadError | WriteError): number;
-/**
-* Maps a NotFoundError to HTTP status.
+* // Server-side: handling in HTTP response
+* if (!result.ok) {
+*   return matchError(result.error, {
+*     ENTITY_VALIDATION_ERROR: (e) => Response.json(
+*       { error: { code: 'VALIDATION_ERROR', message: 'Validation failed', errors: e.errors } },
+*       { status: 422 }
+*     ),
+*     // ... other handlers
+*   });
+* }
 */
-declare function notFoundErrorToHttpStatus(_error: NotFoundError): number;
+declare class EntityValidationError extends EntityError {
+	readonly code: "ValidationError";
+	/**
+	* Validation errors.
+	*/
+	readonly errors: readonly {
+		readonly path: readonly (string | number)[];
+		readonly message: string;
+		readonly code: string;
+	}[];
+	constructor(errors: readonly {
+		readonly path: readonly (string | number)[];
+		readonly message: string;
+		readonly code: string;
+	}[]);
+}
 /**
-* Maps a UniqueViolation to HTTP status.
+* Type guard for EntityValidationError.
 */
-declare function uniqueViolationToHttpStatus(_error: UniqueViolation): number;
+declare function isEntityValidationError(error: unknown): error is EntityValidationError;
 /**
-* Maps a FKViolation to HTTP status.
+* Internal server error - 500.
 */
-declare function fkViolationToHttpStatus(_error: FKViolation): number;
+declare class InternalError2 extends EntityError {
+	readonly code: "InternalError";
+	constructor(message?: string);
+}
 /**
-* Maps a NotNullViolation to HTTP status.
+* Type guard for InternalError.
 */
-declare function notNullViolationToHttpStatus(_error: NotNullViolation): number;
+declare function isInternalError(error: unknown): error is InternalError2;
 /**
-* Maps a CheckViolation to HTTP status.
+* Service unavailable error - 503.
 */
-declare function checkViolationToHttpStatus(_error: CheckViolation): number;
+declare class ServiceUnavailableError extends EntityError {
+	readonly code: "ServiceUnavailable";
+	/**
+	* Seconds until retry.
+	*/
+	readonly retryAfter?: number;
+	constructor(message?: string, retryAfter?: number);
+}
 /**
-* Unknown error response from server.
+* Type guard for ServiceUnavailableError.
 */
-interface UnknownError {
-	readonly code: "UNKNOWN";
-	readonly message: string;
-	readonly status: number;
-}
+declare function isServiceUnavailableError(error: unknown): error is ServiceUnavailableError;
 /**
-* Maps an HTTP response to a client domain error.
-*
-* @param status - HTTP status code
-* @param body - Response body
-* @returns Client domain error
+* Union type for all entity errors.
 *
 * @example
-* const error = httpToClientError(404, { message: 'User not found' });
-* // { code: 'NOT_FOUND', message: 'User not found', resource: 'user' }
+* import { matchError, EntityErrorType } from '@vertz/errors';
+*
+* // Server-side: handling database errors
+* const result = await db.users.create(data);
+* if (!result.ok) {
+*   return matchError(result.error, {
+*     BAD_REQUEST: (e) => Response.json({ error: e.message }, { status: 400 }),
+*     UNAUTHORIZED: () => Response.json({ error: 'Unauthorized' }, { status: 401 }),
+*     FORBIDDEN: () => Response.json({ error: 'Forbidden' }, { status: 403 }),
+*     NOT_FOUND: (e) => Response.json({ error: e.message }, { status: 404 }),
+*     METHOD_NOT_ALLOWED: () => Response.json({ error: 'Method not allowed' }, { status: 405 }),
+*     CONFLICT: (e) => Response.json({ error: e.message }, { status: 409 }),
+*     ENTITY_VALIDATION_ERROR: (e) => Response.json({ error: e.errors }, { status: 422 }),
+*     INTERNAL_ERROR: () => Response.json({ error: 'Internal error' }, { status: 500 }),
+*     SERVICE_UNAVAILABLE: () => Response.json({ error: 'Service unavailable' }, { status: 503 }),
+*   });
+* }
 */
-declare function httpToClientError(status: number, body: unknown): ApiError | UnknownError;
-/**
-* Checks if an error is an UnknownError.
+type EntityErrorType = BadRequestError | EntityUnauthorizedError | EntityForbiddenError | EntityNotFoundError | MethodNotAllowedError | EntityConflictError | EntityValidationError | InternalError2 | ServiceUnavailableError;
+/**
+* Handler map type for FetchError.
+* Each key corresponds to an error code, and the value is a handler function.
+*/
+type FetchErrorHandlers<R> = {
+	NetworkError: (error: Extract<FetchErrorType, {
+		code: "NetworkError";
+	}>) => R;
+	HttpError: (error: Extract<FetchErrorType, {
+		code: "HttpError";
+	}>) => R;
+	TimeoutError: (error: Extract<FetchErrorType, {
+		code: "TimeoutError";
+	}>) => R;
+	ParseError: (error: Extract<FetchErrorType, {
+		code: "ParseError";
+	}>) => R;
+	ValidationError: (error: Extract<FetchErrorType, {
+		code: "ValidationError";
+	}>) => R;
+};
+/**
+* Handler map type for EntityError.
+* Each key corresponds to an error code, and the value is a handler function.
+*/
+type EntityErrorHandlers<R> = {
+	BadRequest: (error: Extract<EntityErrorType, {
+		code: "BadRequest";
+	}>) => R;
+	Unauthorized: (error: Extract<EntityErrorType, {
+		code: "Unauthorized";
+	}>) => R;
+	Forbidden: (error: Extract<EntityErrorType, {
+		code: "Forbidden";
+	}>) => R;
+	NotFound: (error: Extract<EntityErrorType, {
+		code: "NotFound";
+	}>) => R;
+	MethodNotAllowed: (error: Extract<EntityErrorType, {
+		code: "MethodNotAllowed";
+	}>) => R;
+	Conflict: (error: Extract<EntityErrorType, {
+		code: "Conflict";
+	}>) => R;
+	ValidationError: (error: Extract<EntityErrorType, {
+		code: "ValidationError";
+	}>) => R;
+	InternalError: (error: Extract<EntityErrorType, {
+		code: "InternalError";
+	}>) => R;
+	ServiceUnavailable: (error: Extract<EntityErrorType, {
+		code: "ServiceUnavailable";
+	}>) => R;
+};
+/**
+* Pattern matching for FetchError types.
+*
+* Provides compile-time exhaustiveness checking - you must handle all error types.
+*
+* @example
+* const result = matchError(error, {
+*   NetworkError: (e) => 'Network failed',
+*   HttpError: (e) => `HTTP ${e.status}: ${e.message}`,
+*   TimeoutError: (e) => 'Request timed out',
+*   ParseError: (e) => `Parse failed at ${e.path}`,
+*   ValidationError: (e) => `Validation: ${e.errors.length} errors`,
+* });
 */
-declare function isUnknownError(error: ApiError | UnknownError): error is UnknownError;
-export { unwrapOr, unwrap, uniqueViolationToHttpStatus, ok, notNullViolationToHttpStatus, notFoundErrorToHttpStatus, matchErr, match, map, isUserExistsError, isUnknownError, isUniqueViolation, isUnauthorizedError, isSessionExpiredError, isValidationError as isSchemaValidationError, isPermissionDeniedError, isOk, isNotNullViolation, isInvalidCredentialsError, isForbiddenError, isFKViolation, isErr, isNotFoundError as isDBNotFoundError, isConflictError, isValidationError2 as isClientValidationError, isRateLimitedError2 as isClientRateLimitedError, isNotFoundError2 as isClientNotFoundError, isCheckViolation, isRateLimitedError as isAuthRateLimitedError, httpToClientError, flatMap, fkViolationToHttpStatus, err, dbErrorToHttpStatus, createUserExistsError, createUniqueViolation, createUnauthorizedError, createSessionExpiredError, createValidationError as createSchemaValidationError, createPermissionDeniedError, createNotNullViolation, createInvalidCredentialsError, createForbiddenError, createFKViolation, createNotFoundError as createDBNotFoundError, createConflictError, createValidationError2 as createClientValidationError, createRateLimitedError2 as createClientRateLimitedError, createNotFoundError2 as createClientNotFoundError, createCheckViolation, createRateLimitedError as createAuthRateLimitedError, checkViolationToHttpStatus, WriteError, ValidationIssue, UserExistsError, UnknownError, UniqueViolation, UnauthorizedError, TimeoutError, SessionExpiredError, SerializationError, ValidationError as SchemaValidationError, Result, ReadError, QueryError, PoolExhaustedError, PermissionDeniedError, Ok, NotNullViolation, NetworkError, InvalidCredentialsError, InfraErrors, InfraError, ForbiddenError, FKViolation, Err, NotFoundError as DBNotFoundError, ConnectionError, ConflictError, ValidationError2 as ClientValidationError, RateLimitedError2 as ClientRateLimitedError, NotFoundError2 as ClientNotFoundError, CheckViolation, RateLimitedError as AuthRateLimitedError, AuthError, AppError, ApiError };
+declare function matchError<R>(error: FetchErrorType, handlers: FetchErrorHandlers<R>): R;
+declare function matchError<R>(error: EntityErrorType, handlers: EntityErrorHandlers<R>): R;
+export { unwrapOr, unwrap, uniqueViolationToHttpStatus, ok, notNullViolationToHttpStatus, notFoundErrorToHttpStatus, matchError, matchErr, match, map, isUserExistsError, isUnknownError, isUniqueViolation, isUnauthorizedError, isSessionExpiredError, isServiceUnavailableError, isValidationError2 as isSchemaValidationError, isPermissionDeniedError, isParseError, isOk, isNotNullViolation, isMigrationQueryError, isMigrationHistoryNotFound, isMigrationChecksumMismatch, isMethodNotAllowedError, isInvalidCredentialsError, isInternalError, isHttpError, isForbiddenError, isFetchValidationError, isFetchUnprocessableEntityError, isFetchUnauthorizedError, isFetchTimeoutError, isFetchServiceUnavailableError, isFetchRateLimitError, isFetchNotFoundError, isFetchNetworkError, isFetchInternalServerError, isFetchGoneError, isFetchForbiddenError, isFetchConflictError, isFetchBadRequestError, isFKViolation, isErr, isEntityValidationError, isEntityUnauthorizedError, isEntityNotFoundError, isEntityForbiddenError, isEntityConflictError, isNotFoundError2 as isDBNotFoundError, isConflictError, isValidationError as isClientValidationError, isRateLimitedError2 as isClientRateLimitedError, isNotFoundError as isClientNotFoundError, isCheckViolation, isBadRequestError, isAuthValidationError, isRateLimitedError as isAuthRateLimitedError, httpToClientError, flatMap, fkViolationToHttpStatus, err, dbErrorToHttpStatus, createUserExistsError, createUniqueViolation, createUnauthorizedError, createSessionExpiredError, createValidationError2 as createSchemaValidationError, createPermissionDeniedError, createNotNullViolation, createMigrationQueryError, createMigrationHistoryNotFound, createMigrationChecksumMismatch, createInvalidCredentialsError, createHttpError, createForbiddenError, createFKViolation, createNotFoundError2 as createDBNotFoundError, createConflictError, createValidationError as createClientValidationError, createRateLimitedError2 as createClientRateLimitedError, createNotFoundError as createClientNotFoundError, createCheckViolation, createAuthValidationError, createRateLimitedError as createAuthRateLimitedError, checkViolationToHttpStatus, WriteError, ValidationIssue, UserExistsError, UnknownError, UniqueViolation, UnauthorizedError, TimeoutError2 as TimeoutError, SessionExpiredError, ServiceUnavailableError, SerializationError, ValidationError3 as SchemaValidationError, Result, ReadError, QueryError, PoolExhaustedError, PermissionDeniedError, ParseError2 as ParseError, Ok, NotNullViolation, NetworkError2 as NetworkError, MigrationQueryError, MigrationHistoryNotFound, MigrationError, MigrationChecksumMismatch, MethodNotAllowedError, InvalidCredentialsError, InternalError2 as InternalError, InfraErrors, InfraError, HttpError2 as HttpError, ForbiddenError, FetchValidationError, FetchUnprocessableEntityError, FetchUnauthorizedError, FetchTimeoutError, FetchServiceUnavailableError, FetchRateLimitError, FetchNotFoundError, FetchNetworkError, FetchInternalServerError, FetchGoneError, FetchForbiddenError, FetchErrorType, FetchError, FetchConflictError, FetchBadRequestError, FKViolation, Err, EntityValidationError, EntityUnauthorizedError, EntityNotFoundError, EntityForbiddenError, EntityErrorType, EntityError, EntityConflictError, NotFoundError2 as DBNotFoundError, ConnectionError, ConflictError, ValidationError2 as ClientValidationError, RateLimitedError2 as ClientRateLimitedError, NotFoundError as ClientNotFoundError, CheckViolation, BadRequestError, AuthValidationError, RateLimitedError as AuthRateLimitedError, AuthError, AppError, ApiError };