@revealui/core 0.0.0-canary-20260409021642

package/dist/utils/error-responses.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Framework-Agnostic Error Response Utilities
+ *
+ * Provides standardized error response data objects (not Response/NextResponse wrappers).
+ * These functions return plain data objects that can be wrapped by framework-specific
+ * response utilities (NextResponse.json, new Response, etc.).
+ *
+ * Use these functions to create error response data, then wrap in your framework's
+ * response type:
+ * - Next.js: `NextResponse.json(createErrorResponseData(...), { status: 400 })`
+ * - Standard: `new Response(JSON.stringify(createErrorResponseData(...)), { status: 400 })`
+ */
+/**
+ * Error response data format
+ */
+export interface ErrorResponseData {
+    error: string;
+    message: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * Create error response data from an error object
+ *
+ * @param error - The error to convert to response data
+ * @param context - Additional context for error handling
+ * @returns Error response data object
+ */
+export declare function createErrorResponseData(error: unknown, context?: Record<string, unknown>): ErrorResponseData;
+/**
+ * Create validation error response data
+ *
+ * @param message - Error message
+ * @param field - Field that failed validation
+ * @param value - Invalid value
+ * @param details - Additional validation details
+ * @returns Validation error response data
+ */
+export declare function createValidationErrorResponseData(message: string, field: string, value: unknown, details?: Record<string, unknown>): ErrorResponseData;
+/**
+ * Create application error response data
+ *
+ * @param message - Error message
+ * @param code - Error code
+ * @param statusCode - HTTP status code (for reference, not included in data)
+ * @param context - Additional context
+ * @returns Application error response data
+ */
+export declare function createApplicationErrorResponseData(message: string, code: string, statusCode?: number, context?: Record<string, unknown>): ErrorResponseData;
+/**
+ * Create success response data
+ *
+ * @param data - Response data
+ * @returns Success response data (can be wrapped by framework)
+ */
+export declare function createSuccessResponseData<T>(data: T): T;
+//# sourceMappingURL=error-responses.d.ts.map

package/dist/utils/error-responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-responses.d.ts","sourceRoot":"","sources":["../../src/utils/error-responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,iBAAiB,CA4BnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,iBAAiB,CAWnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,iBAAiB,CAQnB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEvD"}

package/dist/utils/error-responses.js

@@ -0,0 +1,95 @@
+/**
+ * Framework-Agnostic Error Response Utilities
+ *
+ * Provides standardized error response data objects (not Response/NextResponse wrappers).
+ * These functions return plain data objects that can be wrapped by framework-specific
+ * response utilities (NextResponse.json, new Response, etc.).
+ *
+ * Use these functions to create error response data, then wrap in your framework's
+ * response type:
+ * - Next.js: `NextResponse.json(createErrorResponseData(...), { status: 400 })`
+ * - Standard: `new Response(JSON.stringify(createErrorResponseData(...)), { status: 400 })`
+ */
+import { ApplicationError, ValidationError } from './errors.js';
+/**
+ * Create error response data from an error object
+ *
+ * @param error - The error to convert to response data
+ * @param context - Additional context for error handling
+ * @returns Error response data object
+ */
+export function createErrorResponseData(error, context) {
+    if (error instanceof ApplicationError) {
+        return {
+            error: error.code || 'INTERNAL_ERROR',
+            message: error.message,
+            code: error.code,
+            ...(error.context && { details: error.context }),
+            ...(context && { details: { ...error.context, ...context } }),
+        };
+    }
+    if (error instanceof ValidationError) {
+        return {
+            error: 'VALIDATION_ERROR',
+            message: error.message,
+            code: 'VALIDATION_ERROR',
+            ...(error.context && { details: error.context }),
+            ...(context && { details: { ...error.context, ...context } }),
+        };
+    }
+    // Unknown error — never expose raw error messages to clients
+    return {
+        error: 'INTERNAL_ERROR',
+        message: 'An unexpected error occurred',
+        code: 'INTERNAL_ERROR',
+        ...(context && { details: context }),
+    };
+}
+/**
+ * Create validation error response data
+ *
+ * @param message - Error message
+ * @param field - Field that failed validation
+ * @param value - Invalid value
+ * @param details - Additional validation details
+ * @returns Validation error response data
+ */
+export function createValidationErrorResponseData(message, field, value, details) {
+    return {
+        error: 'VALIDATION_ERROR',
+        message,
+        code: 'VALIDATION_ERROR',
+        details: {
+            field,
+            value,
+            ...details,
+        },
+    };
+}
+/**
+ * Create application error response data
+ *
+ * @param message - Error message
+ * @param code - Error code
+ * @param statusCode - HTTP status code (for reference, not included in data)
+ * @param context - Additional context
+ * @returns Application error response data
+ */
+export function createApplicationErrorResponseData(message, code, statusCode, context) {
+    return {
+        error: code || 'INTERNAL_ERROR',
+        message,
+        code,
+        ...(context && { details: context }),
+        ...(statusCode !== undefined && { statusCode }), // Include for reference if needed
+    };
+}
+/**
+ * Create success response data
+ *
+ * @param data - Response data
+ * @returns Success response data (can be wrapped by framework)
+ */
+export function createSuccessResponseData(data) {
+    return data;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Error Handling Utilities
+ *
+ * Standardized error handling for RevealUI framework.
+ */
+/**
+ * Application Error
+ * Use for business logic failures, validation failures, expected errors
+ */
+export declare class ApplicationError extends Error {
+    code: string;
+    statusCode: number;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode?: number, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Validation Error
+ * Use for input validation failures, schema validation failures
+ */
+export declare class ValidationError extends Error {
+    field: string;
+    value: unknown;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, field: string, value: unknown, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Database Error
+ * Use for database operation failures with Postgres error code parsing
+ */
+export declare class DatabaseError extends Error {
+    code: string;
+    statusCode: number;
+    pgCode?: string | undefined;
+    constraint?: string | undefined;
+    table?: string | undefined;
+    column?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode?: number, pgCode?: string | undefined, constraint?: string | undefined, table?: string | undefined, column?: string | undefined, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Authentication Error
+ * Use for failed login, expired sessions, invalid tokens
+ */
+export declare class AuthenticationError extends ApplicationError {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+/**
+ * Authorization Error
+ * Use for insufficient permissions, forbidden access
+ */
+export declare class AuthorizationError extends ApplicationError {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+/**
+ * Not Found Error
+ * Use for missing resources (users, posts, pages, etc.)
+ */
+export declare class NotFoundError extends ApplicationError {
+    constructor(resource: string, identifier?: string, context?: Record<string, unknown>);
+}
+/**
+ * Conflict Error
+ * Use for duplicate resources, concurrent modification conflicts
+ */
+export declare class ConflictError extends ApplicationError {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+/**
+ * Rate Limit Error
+ * Use for too many requests, throttling
+ */
+export declare class RateLimitError extends ApplicationError {
+    retryAfterMs?: number | undefined;
+    constructor(message?: string, retryAfterMs?: number | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Postgres Error Codes
+ * Reference: https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+export declare const PostgresErrorCode: {
+    readonly UNIQUE_VIOLATION: "23505";
+    readonly FOREIGN_KEY_VIOLATION: "23503";
+    readonly NOT_NULL_VIOLATION: "23502";
+    readonly CHECK_VIOLATION: "23514";
+    readonly UNDEFINED_TABLE: "42P01";
+    readonly UNDEFINED_COLUMN: "42703";
+    readonly DUPLICATE_TABLE: "42P07";
+    readonly DUPLICATE_COLUMN: "42701";
+    readonly DEADLOCK_DETECTED: "40P01";
+    readonly SERIALIZATION_FAILURE: "40001";
+    readonly QUERY_CANCELED: "57014";
+    readonly ADMIN_SHUTDOWN: "57P01";
+    readonly DISK_FULL: "53100";
+    readonly OUT_OF_MEMORY: "53200";
+    readonly TOO_MANY_CONNECTIONS: "53300";
+    readonly CONNECTION_EXCEPTION: "08000";
+    readonly CONNECTION_FAILURE: "08006";
+    readonly CONNECTION_DOES_NOT_EXIST: "08003";
+    readonly INVALID_TRANSACTION_STATE: "25000";
+    readonly ACTIVE_SQL_TRANSACTION: "25001";
+};
+/**
+ * Handle and log error in API routes
+ *
+ * @param error - The error to handle
+ * @param context - Additional context to log
+ * @returns User-friendly error message
+ */
+export declare function handleApiError(error: unknown, context?: Record<string, unknown>): {
+    message: string;
+    statusCode: number;
+    code?: string;
+    retryable?: boolean;
+};
+/**
+ * Handle database errors with Postgres error code parsing
+ *
+ * @param error - Database error
+ * @param operation - Operation being performed (e.g., 'insert user', 'update order')
+ * @param context - Additional context (e.g., { userId: '123', table: 'users' })
+ * @returns Never - always throws a DatabaseError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await db.insert(users).values({ email: 'existing@example.com' })
+ * } catch (error) {
+ *   handleDatabaseError(error, 'insert user', { email: 'existing@example.com' })
+ * }
+ * ```
+ */
+export declare function handleDatabaseError(error: unknown, operation: string, context?: Record<string, unknown>): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}