@vertz/errors 0.2.14 → 0.2.16

package/dist/index.d.ts

@@ -156,13 +156,13 @@ declare function isRateLimitedError(error: {
 interface AuthValidationError {
 	readonly code: "AUTH_VALIDATION_ERROR";
 	readonly message: string;
-	readonly field: "email" | "password";
+	readonly field: "email" | "password" | "general";
 	readonly constraint?: string;
 }
 /**
 * Creates an AuthValidationError.
 */
-declare function createAuthValidationError(message: string, field: "email" | "password", constraint?: string): AuthValidationError;
+declare function createAuthValidationError(message: string, field: "email" | "password" | "general", constraint?: string): AuthValidationError;
 /**
 * Type guard for AuthValidationError.
 */
@@ -713,380 +713,219 @@ declare function isValidationError2(error: {
 	readonly code: string;
 }): error is ValidationError3;
 /**
-* 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.
-*/
-/**
-* Base class for infrastructure errors.
+* These errors mirror server HTTP error codes and are used at the HTTP boundary.
 */
-declare class InfraError extends Error {
-	constructor(message: string);
-}
 /**
-* Database connection error.
+* Base class for entity errors.
 *
-* Thrown when the database is unreachable.
+* @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 ConnectionError extends InfraError {
-	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);
 }
 /**
-* Connection pool exhausted error.
-*
-* Thrown when no connections are available in the pool.
+* Bad request error - 400.
 */
-declare class PoolExhaustedError extends InfraError {
+declare class BadRequestError extends EntityError {
+	readonly code: "BadRequest";
 	constructor(message?: string);
 }
 /**
-* Query error.
-*
-* Thrown when a query fails (malformed, syntax error, etc.).
+* Type guard for BadRequestError.
 */
-declare class QueryError extends InfraError {
-	constructor(message?: string);
-}
+declare function isBadRequestError(error: unknown): error is BadRequestError;
 /**
-* Timeout error.
-*
-* Thrown when an operation takes too long.
+* Unauthorized error - 401.
 */
-declare class TimeoutError2 extends InfraError {
+declare class EntityUnauthorizedError extends EntityError {
+	readonly code: "Unauthorized";
 	constructor(message?: string);
 }
 /**
-* Network error.
-*
-* Thrown when HTTP client can't reach the server.
+* Type guard for EntityUnauthorizedError.
 */
-declare class NetworkError2 extends InfraError {
-	constructor(message?: string);
-}
+declare function isEntityUnauthorizedError(error: unknown): error is EntityUnauthorizedError;
 /**
-* Serialization error.
-*
-* Thrown when response couldn't be decoded.
+* Forbidden error - 403.
 */
-declare class SerializationError extends InfraError {
+declare class EntityForbiddenError extends EntityError {
+	readonly code: "Forbidden";
 	constructor(message?: string);
 }
 /**
-* Union type for all infrastructure errors.
+* Type guard for EntityForbiddenError.
 */
-type InfraErrors = ConnectionError | PoolExhaustedError | QueryError | TimeoutError2 | NetworkError2 | SerializationError;
+declare function isEntityForbiddenError(error: unknown): error is EntityForbiddenError;
 /**
-* Maps a database error to an HTTP status code.
+* Not found error - 404.
 *
-* @param error - A database domain error
-* @returns HTTP status code
+* @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
-* 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.
+* // With resource info
+* throw new EntityNotFoundError('User not found', 'User', userId);
 */
-interface UnknownError {
-	readonly code: "UNKNOWN";
-	readonly message: string;
-	readonly status: number;
+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);
 }
 /**
-* 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' }
+* Type guard for EntityNotFoundError.
 */
-declare function httpToClientError(status: number, body: unknown): ApiError | UnknownError;
+declare function isEntityNotFoundError(error: unknown): error is EntityNotFoundError;
 /**
-* Checks if an error is an UnknownError.
+* Method not allowed error - 405.
 */
-declare function isUnknownError(error: ApiError | UnknownError): error is UnknownError;
+declare class MethodNotAllowedError extends EntityError {
+	readonly code: "MethodNotAllowed";
+	/**
+	* Allowed HTTP methods.
+	*/
+	readonly allowedMethods?: string;
+	constructor(allowedMethods?: string, message?: string);
+}
 /**
-* 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}`
-* });
+* Type guard for MethodNotAllowedError.
 */
+declare function isMethodNotAllowedError(error: unknown): error is MethodNotAllowedError;
 /**
-* Represents a successful result.
-*
-* @example
-* { ok: true, data: { name: 'Alice' } }
+* Conflict error - 409.
 */
-interface Ok<T> {
-	/** Always true for successful results */
-	readonly ok: true;
-	/** The successful value */
-	readonly data: T;
+declare class EntityConflictError extends EntityError {
+	readonly code: "Conflict";
+	/**
+	* The field that caused the conflict.
+	*/
+	readonly field?: string;
+	constructor(message?: string, field?: string);
 }
 /**
-* Represents an erroneous result.
-*
-* @example
-* { ok: false, error: { code: 'NOT_FOUND', message: 'User not found' } }
+* Type guard for EntityConflictError.
 */
-interface Err<E> {
-	/** Always false for error results */
-	readonly ok: false;
-	/** The error value */
-	readonly error: E;
-}
+declare function isEntityConflictError(error: unknown): error is EntityConflictError;
 /**
-* A discriminated union representing success or failure.
+* Entity validation error - 422.
 *
 * @example
-* type UserResult = Result<User, ValidationError>;
-* type UsersResult = Result<User[], NotFoundError>;
+* // 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 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
+* // 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
+*   });
 * }
 */
-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>;
+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;
+	}[]);
+}
 /**
-* 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)
-* );
+* Type guard for EntityValidationError.
 */
-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>>;
+declare function isEntityValidationError(error: unknown): error is EntityValidationError;
 /**
-* Pattern matching on Result.
-*
-* @example
-* const message = match(result, {
-*   ok: (user) => \`Hello, \${user.name}!\`,
-*   err: (e) => \`Error: \${e.message}\`
-* });
+* Internal server error - 500.
 */
-declare function match<
-	T,
-	E,
-	OkR,
-	ErrR
->(result: Result<T, E>, handlers: {
-	ok: (data: T) => OkR;
-	err: (error: E) => ErrR;
-}): OkR | ErrR;
+declare class InternalError2 extends EntityError {
+	readonly code: "InternalError";
+	constructor(message?: string);
+}
 /**
-* Type for error handlers in matchErr.
-* Extracts error codes from an error union and creates a handler map.
+* Type guard for InternalError.
 */
-type ErrorHandlers<
-	E,
-	R
-> = { [K in E as K extends {
-	readonly code: infer C extends string;
-} ? C : never] : (error: K) => R };
+declare function isInternalError(error: unknown): error is InternalError2;
 /**
-* 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
+* Service unavailable error - 503.
 */
-declare function matchErr<
-	T,
-	E extends {
-		readonly code: string;
-	},
-	R
->(result: Result<T, E>, handlers: {
-	ok: (data: T) => R;
-} & ErrorHandlers<E, R>): R;
+declare class ServiceUnavailableError extends EntityError {
+	readonly code: "ServiceUnavailable";
+	/**
+	* Seconds until retry.
+	*/
+	readonly retryAfter?: number;
+	constructor(message?: string, retryAfter?: number);
+}
 /**
-* Type guard for Ok results.
-*
-* @example
-* if (isOk(result)) {
-*   console.log(result.data); // TypeScript knows this is T
-* }
+* Type guard for ServiceUnavailableError.
 */
-declare function isOk<
-	T,
-	E
->(result: Result<T, E>): result is Ok<T>;
+declare function isServiceUnavailableError(error: unknown): error is ServiceUnavailableError;
 /**
-* Type guard for Err results.
+* Union type for all entity errors.
 *
 * @example
-* if (isErr(result)) {
-*   console.log(result.error); // TypeScript knows this is E
+* 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 isErr<
-	T,
-	E
->(result: Result<T, E>): result is Err<E>;
+type EntityErrorType = BadRequestError | EntityUnauthorizedError | EntityForbiddenError | EntityNotFoundError | MethodNotAllowedError | EntityConflictError | EntityValidationError | InternalError2 | ServiceUnavailableError;
 /**
 * Fetch error classes.
 *
@@ -1383,219 +1222,129 @@ declare function createHttpError(status: number, message: string, serverCode?: s
 */
 type FetchErrorType = FetchNetworkError | HttpError2 | FetchBadRequestError | FetchUnauthorizedError | FetchForbiddenError | FetchNotFoundError | FetchConflictError | FetchGoneError | FetchUnprocessableEntityError | FetchRateLimitError | FetchInternalServerError | FetchServiceUnavailableError | FetchTimeoutError | ParseError2 | FetchValidationError;
 /**
-* Entity error classes.
+* Infrastructure errors.
 *
-* These errors mirror server HTTP error codes and are used at the HTTP boundary.
+* 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.
 */
 /**
-* 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);
-* }
+* Base class for infrastructure errors.
 */
-declare abstract class EntityError extends Error {
-	/**
-	* The error code - a string literal for type-safe discrimination.
-	*/
-	readonly code: string;
-	constructor(code: string, message: string);
+declare class InfraError extends Error {
+	constructor(message: string);
 }
 /**
-* Bad request error - 400.
+* Database connection error.
+*
+* Thrown when the database is unreachable.
 */
-declare class BadRequestError extends EntityError {
-	readonly code: "BadRequest";
+declare class ConnectionError extends InfraError {
 	constructor(message?: string);
 }
 /**
-* Type guard for BadRequestError.
-*/
-declare function isBadRequestError(error: unknown): error is BadRequestError;
-/**
-* Unauthorized error - 401.
+* Connection pool exhausted error.
+*
+* Thrown when no connections are available in the pool.
 */
-declare class EntityUnauthorizedError extends EntityError {
-	readonly code: "Unauthorized";
+declare class PoolExhaustedError extends InfraError {
 	constructor(message?: string);
 }
 /**
-* Type guard for EntityUnauthorizedError.
-*/
-declare function isEntityUnauthorizedError(error: unknown): error is EntityUnauthorizedError;
-/**
-* Forbidden error - 403.
+* Query error.
+*
+* Thrown when a query fails (malformed, syntax error, etc.).
 */
-declare class EntityForbiddenError extends EntityError {
-	readonly code: "Forbidden";
+declare class QueryError extends InfraError {
 	constructor(message?: string);
 }
 /**
-* Type guard for EntityForbiddenError.
-*/
-declare function isEntityForbiddenError(error: unknown): error is EntityForbiddenError;
-/**
-* Not found error - 404.
-*
-* @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
-*   });
-* }
+* Timeout error.
 *
-* @example
-* // With resource info
-* throw new EntityNotFoundError('User not found', 'User', userId);
+* Thrown when an operation takes too long.
 */
-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);
+declare class TimeoutError2 extends InfraError {
+	constructor(message?: string);
 }
 /**
-* Type guard for EntityNotFoundError.
-*/
-declare function isEntityNotFoundError(error: unknown): error is EntityNotFoundError;
-/**
-* Method not allowed error - 405.
+* Network error.
+*
+* Thrown when HTTP client can't reach the server.
 */
-declare class MethodNotAllowedError extends EntityError {
-	readonly code: "MethodNotAllowed";
-	/**
-	* Allowed HTTP methods.
-	*/
-	readonly allowedMethods?: string;
-	constructor(allowedMethods?: string, message?: string);
+declare class NetworkError2 extends InfraError {
+	constructor(message?: string);
 }
 /**
-* Type guard for MethodNotAllowedError.
-*/
-declare function isMethodNotAllowedError(error: unknown): error is MethodNotAllowedError;
-/**
-* Conflict error - 409.
+* Serialization error.
+*
+* Thrown when response couldn't be decoded.
 */
-declare class EntityConflictError extends EntityError {
-	readonly code: "Conflict";
-	/**
-	* The field that caused the conflict.
-	*/
-	readonly field?: string;
-	constructor(message?: string, field?: string);
+declare class SerializationError extends InfraError {
+	constructor(message?: string);
 }
 /**
-* Type guard for EntityConflictError.
+* Union type for all infrastructure errors.
 */
-declare function isEntityConflictError(error: unknown): error is EntityConflictError;
+type InfraErrors = ConnectionError | PoolExhaustedError | QueryError | TimeoutError2 | NetworkError2 | SerializationError;
 /**
-* Entity validation error - 422.
+* Maps a database error to an 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' },
-* ]);
+* @param error - A database domain error
+* @returns HTTP status code
 *
 * @example
-* // 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
-*   });
-* }
+* const status = dbErrorToHttpStatus(error);
+* // NOT_FOUND → 404
+* // UNIQUE_VIOLATION → 409
+* // FK_VIOLATION → 422
+* // NOT_NULL_VIOLATION → 422
+* // CHECK_VIOLATION → 422
 */
-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;
-	}[]);
-}
+declare function dbErrorToHttpStatus(error: ReadError | WriteError): number;
 /**
-* Type guard for EntityValidationError.
+* Maps a NotFoundError to HTTP status.
 */
-declare function isEntityValidationError(error: unknown): error is EntityValidationError;
+declare function notFoundErrorToHttpStatus(_error: NotFoundError2): number;
 /**
-* Internal server error - 500.
+* Maps a UniqueViolation to HTTP status.
 */
-declare class InternalError2 extends EntityError {
-	readonly code: "InternalError";
-	constructor(message?: string);
-}
+declare function uniqueViolationToHttpStatus(_error: UniqueViolation): number;
 /**
-* Type guard for InternalError.
+* Maps a FKViolation to HTTP status.
 */
-declare function isInternalError(error: unknown): error is InternalError2;
+declare function fkViolationToHttpStatus(_error: FKViolation): number;
 /**
-* Service unavailable error - 503.
+* Maps a NotNullViolation to HTTP status.
 */
-declare class ServiceUnavailableError extends EntityError {
-	readonly code: "ServiceUnavailable";
-	/**
-	* Seconds until retry.
-	*/
-	readonly retryAfter?: number;
-	constructor(message?: string, retryAfter?: number);
-}
+declare function notNullViolationToHttpStatus(_error: NotNullViolation): number;
 /**
-* Type guard for ServiceUnavailableError.
+* Maps a CheckViolation to HTTP status.
 */
-declare function isServiceUnavailableError(error: unknown): error is ServiceUnavailableError;
+declare function checkViolationToHttpStatus(_error: CheckViolation): number;
 /**
-* Union type for all entity errors.
+* Unknown error response from server.
+*/
+interface UnknownError {
+	readonly code: "UNKNOWN";
+	readonly message: string;
+	readonly status: number;
+}
+/**
+* Maps an HTTP response to a client domain error.
 *
-* @example
-* import { matchError, EntityErrorType } from '@vertz/errors';
+* @param status - HTTP status code
+* @param body - Response body
+* @returns Client domain error
 *
-* // 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 }),
-*   });
-* }
+* @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.
 */
-type EntityErrorType = BadRequestError | EntityUnauthorizedError | EntityForbiddenError | EntityNotFoundError | MethodNotAllowedError | EntityConflictError | EntityValidationError | InternalError2 | ServiceUnavailableError;
+declare function isUnknownError(error: ApiError | UnknownError): error is UnknownError;
 /**
 * Handler map type for FetchError.
 * Each key corresponds to an error code, and the value is a handler function.
@@ -1666,4 +1415,255 @@ type EntityErrorHandlers<R> = {
 */
 declare function matchError<R>(error: FetchErrorType, handlers: FetchErrorHandlers<R>): R;
 declare function matchError<R>(error: EntityErrorType, handlers: EntityErrorHandlers<R>): R;
+/**
+* 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>;
 export { unwrapOr, unwrap, uniqueViolationToHttpStatus, ok, notNullViolationToHttpStatus, notFoundErrorToHttpStatus, matchError, matchErr, match, map, isUserExistsError, isUnknownError, isUniqueViolation, isUnauthorizedError, isTokenInvalidError, isTokenExpiredError, isSessionNotFoundError, isSessionExpiredError, isServiceUnavailableError, isValidationError2 as isSchemaValidationError, isPermissionDeniedError, isParseError, isOk, isOAuthError, isNotNullViolation, isMigrationQueryError, isMigrationHistoryNotFound, isMigrationChecksumMismatch, isMfaRequiredError, isMfaNotEnabledError, isMfaInvalidCodeError, isMfaAlreadyEnabledError, 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, createTokenInvalidError, createTokenExpiredError, createSessionNotFoundError, createSessionExpiredError, createValidationError2 as createSchemaValidationError, createPermissionDeniedError, createOAuthError, createNotNullViolation, createMigrationQueryError, createMigrationHistoryNotFound, createMigrationChecksumMismatch, createMfaRequiredError, createMfaNotEnabledError, createMfaInvalidCodeError, createMfaAlreadyEnabledError, 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, TokenInvalidError, TokenExpiredError, TimeoutError2 as TimeoutError, SessionNotFoundError, SessionExpiredError, ServiceUnavailableError, SerializationError, ValidationError3 as SchemaValidationError, Result, ReadError, QueryError, PoolExhaustedError, PermissionDeniedError, ParseError2 as ParseError, Ok, OAuthError, NotNullViolation, NetworkError2 as NetworkError, MigrationQueryError, MigrationHistoryNotFound, MigrationError, MigrationChecksumMismatch, MfaRequiredError, MfaNotEnabledError, MfaInvalidCodeError, MfaAlreadyEnabledError, 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 };