@vertz/errors 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,839 @@
+/**
+* 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.
+* The server boundary catches these errors and maps them to HTTP responses.
+*
+* @example
+* class InsufficientBalanceError extends AppError<'INSUFFICIENT_BALANCE'> {
+*   constructor(public readonly required: number, public readonly available: number) {
+*     super('INSUFFICIENT_BALANCE', `Need ${required}, have ${available}`);
+*   }
+*
+*   toJSON() {
+*     return { ...super.toJSON(), required: this.required, available: this.available };
+*   }
+* }
+*
+* throw new InsufficientBalanceError(500, 50);
+*/
+/**
+* Base class for application domain errors.
+*
+* Extends Error and adds a typed code property for discrimination.
+* Subclasses can add custom fields and override toJSON() for serialization.
+*/
+declare class AppError<C extends string = string> extends Error {
+	/**
+	* The error code - a string literal for type-safe discrimination.
+	*/
+	readonly code: C;
+	/**
+	* Creates a new AppError.
+	*
+	* @param code - The error code (string literal type)
+	* @param message - Human-readable error message
+	*/
+	constructor(code: C, message: string);
+	/**
+	* Serializes the error to a plain object for HTTP responses.
+	* Override in subclasses to include additional fields.
+	*/
+	toJSON(): Record<string, unknown>;
+}
+/**
+* Schema validation errors.
+*
+* These errors are returned when schema validation fails.
+*/
+/**
+* Issue within a validation error.
+*/
+interface ValidationIssue {
+	readonly path: readonly (string | number)[];
+	readonly message: string;
+	readonly code: string;
+}
+/**
+* Validation failed error.
+*
+* Returned when input doesn't match schema expectations.
+*/
+interface ValidationError {
+	readonly code: "VALIDATION_FAILED";
+	readonly message: string;
+	readonly issues: readonly ValidationIssue[];
+}
+/**
+* Creates a ValidationError.
+*/
+declare function createValidationError(message: string, issues: readonly ValidationIssue[]): ValidationError;
+/**
+* Type guard for ValidationError.
+*/
+declare function isValidationError(error: {
+	readonly code: string;
+}): error is ValidationError;
+/**
+* Database domain errors.
+*
+* These errors are returned from DB operations and represent
+* expected runtime failures that require case-by-case handling.
+*/
+/**
+* Record not found 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";
+	readonly message: string;
+	readonly table: string;
+	readonly key?: Record<string, unknown>;
+}
+/**
+* Creates a NotFoundError.
+*/
+declare function createNotFoundError(table: string, key?: Record<string, unknown>): NotFoundError;
+/**
+* Type guard for NotFoundError.
+*/
+declare function isNotFoundError(error: {
+	readonly code: string;
+}): error is NotFoundError;
+/**
+* Union type for all read errors.
+*/
+type ReadError = NotFoundError;
+/**
+* Unique constraint violation.
+*
+* Returned when inserting/updating a record would violate a unique constraint.
+*/
+interface UniqueViolation {
+	readonly code: "UNIQUE_VIOLATION";
+	readonly message: string;
+	readonly constraint?: string;
+	readonly table?: string;
+	readonly column?: string;
+}
+/**
+* Creates a UniqueViolation error.
+*/
+declare function createUniqueViolation(message: string, options?: {
+	constraint?: string;
+	table?: string;
+	column?: string;
+}): UniqueViolation;
+/**
+* Type guard for UniqueViolation.
+*/
+declare function isUniqueViolation(error: {
+	readonly code: string;
+}): error is UniqueViolation;
+/**
+* Foreign key violation.
+*
+* Returned when inserting/updating a record references a non-existent record.
+*/
+interface FKViolation {
+	readonly code: "FK_VIOLATION";
+	readonly message: string;
+	readonly constraint?: string;
+	readonly table?: string;
+	readonly column?: string;
+	readonly referencedTable?: string;
+}
+/**
+* Creates a FKViolation error.
+*/
+declare function createFKViolation(message: string, options?: {
+	constraint?: string;
+	table?: string;
+	column?: string;
+	referencedTable?: string;
+}): FKViolation;
+/**
+* Type guard for FKViolation.
+*/
+declare function isFKViolation(error: {
+	readonly code: string;
+}): error is FKViolation;
+/**
+* Not null violation.
+*
+* Returned when inserting/updating a record would violate a NOT NULL constraint.
+*/
+interface NotNullViolation {
+	readonly code: "NOT_NULL_VIOLATION";
+	readonly message: string;
+	readonly table?: string;
+	readonly column?: string;
+}
+/**
+* Creates a NotNullViolation error.
+*/
+declare function createNotNullViolation(message: string, options?: {
+	table?: string;
+	column?: string;
+}): NotNullViolation;
+/**
+* Type guard for NotNullViolation.
+*/
+declare function isNotNullViolation(error: {
+	readonly code: string;
+}): error is NotNullViolation;
+/**
+* Check constraint violation.
+*
+* Returned when inserting/updating a record would violate a CHECK constraint.
+*/
+interface CheckViolation {
+	readonly code: "CHECK_VIOLATION";
+	readonly message: string;
+	readonly constraint?: string;
+	readonly table?: string;
+}
+/**
+* Creates a CheckViolation error.
+*/
+declare function createCheckViolation(message: string, options?: {
+	constraint?: string;
+	table?: string;
+}): CheckViolation;
+/**
+* Type guard for CheckViolation.
+*/
+declare function isCheckViolation(error: {
+	readonly code: string;
+}): error is CheckViolation;
+/**
+* Union type for all write errors.
+*/
+type WriteError = UniqueViolation | FKViolation | NotNullViolation | CheckViolation;
+/**
+* Authentication and authorization domain errors.
+*
+* These errors are returned from auth operations.
+*/
+/**
+* Invalid credentials error.
+*
+* Returned when authentication fails due to wrong email/password.
+*/
+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;
+}
+/**
+* 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 a token is no longer valid (expired, revoked, etc.).
+*/
+interface SessionExpiredError {
+	readonly code: "SESSION_EXPIRED";
+	readonly message: string;
+}
+/**
+* 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;
+/**
+* Union type for all auth errors.
+*/
+type AuthError = InvalidCredentialsError | UserExistsError | SessionExpiredError | PermissionDeniedError | RateLimitedError;
+/**
+* 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: "VALIDATION_ERROR";
+	readonly message: string;
+	readonly issues?: readonly {
+		readonly path: readonly (string | number)[];
+		readonly message: string;
+		readonly code: string;
+	}[];
+}
+/**
+* Creates a ValidationError.
+*/
+declare function createValidationError2(message: string, issues?: readonly {
+	readonly path: readonly (string | number)[];
+	readonly message: string;
+	readonly code: string;
+}[]): ValidationError2;
+/**
+* Type guard for ValidationError.
+*/
+declare function isValidationError2(error: {
+	readonly code: string;
+}): error is ValidationError2;
+/**
+* Not found error (client-facing).
+*
+* Maps from server's NOT_FOUND.
+*/
+interface NotFoundError2 {
+	readonly code: "NOT_FOUND";
+	readonly message: string;
+	readonly resource?: string;
+}
+/**
+* Creates a NotFoundError.
+*/
+declare function createNotFoundError2(message?: string, resource?: string): NotFoundError2;
+/**
+* Type guard for NotFoundError.
+*/
+declare function isNotFoundError2(error: {
+	readonly code: string;
+}): error is NotFoundError2;
+/**
+* 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 | NotFoundError2 | ConflictError | UnauthorizedError | ForbiddenError | RateLimitedError2;
+/**
+* Infrastructure errors.
+*
+* 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.
+*/
+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 TimeoutError extends InfraError {
+	constructor(message?: string);
+}
+/**
+* Network error.
+*
+* Thrown when HTTP client can't reach the server.
+*/
+declare class NetworkError 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 | TimeoutError | NetworkError | 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: NotFoundError): 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 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;
+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 };

package/dist/index.js

@@ -0,0 +1,451 @@
+// src/result.ts
+var ok = (data) => ({ ok: true, data });
+var err = (error) => ({ ok: false, error });
+function unwrap(result) {
+  if (result.ok) {
+    return result.data;
+  }
+  throw result.error;
+}
+function unwrapOr(result, defaultValue) {
+  if (result.ok) {
+    return result.data;
+  }
+  return defaultValue;
+}
+function map(result, fn) {
+  if (result.ok) {
+    return { ok: true, data: fn(result.data) };
+  }
+  return result;
+}
+function flatMap(result, fn) {
+  if (result.ok) {
+    return fn(result.data);
+  }
+  return result;
+}
+function match(result, handlers) {
+  return result.ok ? handlers.ok(result.data) : handlers.err(result.error);
+}
+function matchErr(result, handlers) {
+  if (result.ok) {
+    return handlers.ok(result.data);
+  }
+  const errorCode = result.error.code;
+  const handlersRecord = handlers;
+  const handler = handlersRecord[errorCode];
+  if (!handler) {
+    throw new Error(`Unhandled error code: ${errorCode}`);
+  }
+  return handler(result.error);
+}
+function isOk(result) {
+  return result.ok === true;
+}
+function isErr(result) {
+  return result.ok === false;
+}
+// src/app-error.ts
+class AppError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AppError";
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message
+    };
+  }
+}
+// src/domain/schema.ts
+function createValidationError(message, issues) {
+  return {
+    code: "VALIDATION_FAILED",
+    message,
+    issues
+  };
+}
+function isValidationError(error) {
+  return error.code === "VALIDATION_FAILED";
+}
+// src/domain/db.ts
+function createNotFoundError(table, key) {
+  const keyStr = key ? JSON.stringify(key) : "";
+  return {
+    code: "NOT_FOUND",
+    message: `Record not found in ${table}${keyStr ? `: ${keyStr}` : ""}`,
+    table,
+    key
+  };
+}
+function isNotFoundError(error) {
+  return error.code === "NOT_FOUND";
+}
+function createUniqueViolation(message, options) {
+  return {
+    code: "UNIQUE_VIOLATION",
+    message,
+    ...options
+  };
+}
+function isUniqueViolation(error) {
+  return error.code === "UNIQUE_VIOLATION";
+}
+function createFKViolation(message, options) {
+  return {
+    code: "FK_VIOLATION",
+    message,
+    ...options
+  };
+}
+function isFKViolation(error) {
+  return error.code === "FK_VIOLATION";
+}
+function createNotNullViolation(message, options) {
+  return {
+    code: "NOT_NULL_VIOLATION",
+    message,
+    ...options
+  };
+}
+function isNotNullViolation(error) {
+  return error.code === "NOT_NULL_VIOLATION";
+}
+function createCheckViolation(message, options) {
+  return {
+    code: "CHECK_VIOLATION",
+    message,
+    ...options
+  };
+}
+function isCheckViolation(error) {
+  return error.code === "CHECK_VIOLATION";
+}
+// src/domain/auth.ts
+function createInvalidCredentialsError(message = "Invalid email or password") {
+  return {
+    code: "INVALID_CREDENTIALS",
+    message
+  };
+}
+function isInvalidCredentialsError(error) {
+  return error.code === "INVALID_CREDENTIALS";
+}
+function createUserExistsError(message = "User already exists", email) {
+  return {
+    code: "USER_EXISTS",
+    message,
+    email
+  };
+}
+function isUserExistsError(error) {
+  return error.code === "USER_EXISTS";
+}
+function createSessionExpiredError(message = "Session has expired") {
+  return {
+    code: "SESSION_EXPIRED",
+    message
+  };
+}
+function isSessionExpiredError(error) {
+  return error.code === "SESSION_EXPIRED";
+}
+function createPermissionDeniedError(message = "Permission denied", options) {
+  return {
+    code: "PERMISSION_DENIED",
+    message,
+    ...options
+  };
+}
+function isPermissionDeniedError(error) {
+  return error.code === "PERMISSION_DENIED";
+}
+function createRateLimitedError(message = "Too many attempts, please try again later", retryAfter) {
+  return {
+    code: "RATE_LIMITED",
+    message,
+    retryAfter
+  };
+}
+function isRateLimitedError(error) {
+  return error.code === "RATE_LIMITED";
+}
+// src/domain/client.ts
+function createValidationError2(message, issues) {
+  return {
+    code: "VALIDATION_ERROR",
+    message,
+    issues
+  };
+}
+function isValidationError2(error) {
+  return error.code === "VALIDATION_ERROR";
+}
+function createNotFoundError2(message = "Resource not found", resource) {
+  return {
+    code: "NOT_FOUND",
+    message,
+    resource
+  };
+}
+function isNotFoundError2(error) {
+  return error.code === "NOT_FOUND";
+}
+function createConflictError(message = "Resource conflict", field) {
+  return {
+    code: "CONFLICT",
+    message,
+    field
+  };
+}
+function isConflictError(error) {
+  return error.code === "CONFLICT";
+}
+function createUnauthorizedError(message = "Authentication required") {
+  return {
+    code: "UNAUTHORIZED",
+    message
+  };
+}
+function isUnauthorizedError(error) {
+  return error.code === "UNAUTHORIZED";
+}
+function createForbiddenError(message = "Access denied") {
+  return {
+    code: "FORBIDDEN",
+    message
+  };
+}
+function isForbiddenError(error) {
+  return error.code === "FORBIDDEN";
+}
+function createRateLimitedError2(message = "Too many requests", retryAfter) {
+  return {
+    code: "RATE_LIMITED",
+    message,
+    retryAfter
+  };
+}
+function isRateLimitedError2(error) {
+  return error.code === "RATE_LIMITED";
+}
+// src/infra/index.ts
+class InfraError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+class ConnectionError extends InfraError {
+  constructor(message = "Database connection failed") {
+    super(message);
+  }
+}
+
+class PoolExhaustedError extends InfraError {
+  constructor(message = "Database pool exhausted") {
+    super(message);
+  }
+}
+
+class QueryError extends InfraError {
+  constructor(message = "Query execution failed") {
+    super(message);
+  }
+}
+
+class TimeoutError extends InfraError {
+  constructor(message = "Operation timed out") {
+    super(message);
+  }
+}
+
+class NetworkError extends InfraError {
+  constructor(message = "Network request failed") {
+    super(message);
+  }
+}
+
+class SerializationError extends InfraError {
+  constructor(message = "Failed to decode response") {
+    super(message);
+  }
+}
+// src/mapping/db-to-http.ts
+function dbErrorToHttpStatus(error) {
+  const code = error.code;
+  switch (code) {
+    case "NOT_FOUND":
+      return 404;
+    case "UNIQUE_VIOLATION":
+      return 409;
+    case "FK_VIOLATION":
+      return 422;
+    case "NOT_NULL_VIOLATION":
+      return 422;
+    case "CHECK_VIOLATION":
+      return 422;
+    default:
+      return 500;
+  }
+}
+function notFoundErrorToHttpStatus(_error) {
+  return 404;
+}
+function uniqueViolationToHttpStatus(_error) {
+  return 409;
+}
+function fkViolationToHttpStatus(_error) {
+  return 422;
+}
+function notNullViolationToHttpStatus(_error) {
+  return 422;
+}
+function checkViolationToHttpStatus(_error) {
+  return 422;
+}
+// src/mapping/http-to-client.ts
+function parseUnknownError(status, body) {
+  const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : "Request failed";
+  return {
+    code: "UNKNOWN",
+    message,
+    status
+  };
+}
+function httpToClientError(status, body) {
+  if (body === null || body === undefined || body === "") {
+    return parseUnknownError(status, body);
+  }
+  if (typeof body !== "object") {
+    return parseUnknownError(status, body);
+  }
+  const bodyObj = body;
+  const message = typeof bodyObj.message === "string" ? bodyObj.message : "Request failed";
+  switch (status) {
+    case 400:
+      if (bodyObj.code === "VALIDATION_FAILED" || bodyObj.issues) {
+        const error = {
+          code: "VALIDATION_ERROR",
+          message,
+          issues: Array.isArray(bodyObj.issues) ? bodyObj.issues : undefined
+        };
+        return error;
+      }
+      return parseUnknownError(status, body);
+    case 401:
+      return {
+        code: "UNAUTHORIZED",
+        message
+      };
+    case 403:
+      return {
+        code: "FORBIDDEN",
+        message
+      };
+    case 404:
+      return {
+        code: "NOT_FOUND",
+        message,
+        resource: typeof bodyObj.resource === "string" ? bodyObj.resource : undefined
+      };
+    case 409:
+      return {
+        code: "CONFLICT",
+        message,
+        field: typeof bodyObj.field === "string" ? bodyObj.field : undefined
+      };
+    case 422:
+      if (bodyObj.code === "VALIDATION_FAILED" || bodyObj.issues) {
+        const error = {
+          code: "VALIDATION_ERROR",
+          message,
+          issues: Array.isArray(bodyObj.issues) ? bodyObj.issues : undefined
+        };
+        return error;
+      }
+    case 429:
+      return {
+        code: "RATE_LIMITED",
+        message,
+        retryAfter: typeof bodyObj.retryAfter === "number" ? bodyObj.retryAfter : undefined
+      };
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return parseUnknownError(status, body);
+    default:
+      return parseUnknownError(status, body);
+  }
+}
+function isUnknownError(error) {
+  return error.code === "UNKNOWN";
+}
+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,
+  TimeoutError,
+  SerializationError,
+  QueryError,
+  PoolExhaustedError,
+  NetworkError,
+  InfraError,
+  ConnectionError,
+  AppError
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vertz/errors",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Unified error taxonomy for Vertz - Result types, domain errors, and mapping utilities",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertz-dev/vertz.git",
+    "directory": "packages/errors"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "bunup": "latest",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false
+}