@revealui/core 0.0.1-pre.4 → 0.2.1

package/dist/utils/cache.js

@@ -0,0 +1,154 @@
+/**
+ * LRU Cache with TTL (Time To Live)
+ *
+ * Provides a cache implementation with:
+ * - TTL (Time To Live) expiration
+ * - Size limits with LRU eviction
+ * - Type-safe generic interface
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<string, User>({ maxSize: 100, ttlMs: 5 * 60 * 1000 })
+ * const user = await cache.fetch('user:123', () => fetchUserFromDB('123'))
+ * ```
+ */
+/**
+ * LRU Cache with TTL for storing key-value pairs
+ *
+ * Features:
+ * - Automatic expiration based on TTL
+ * - Size limits with LRU (Least Recently Used) eviction
+ * - Type-safe generic interface
+ */
+export class LRUCache {
+    cache = new Map();
+    maxSize;
+    ttlMs;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? 100;
+        this.ttlMs = options.ttlMs ?? 5 * 60 * 1000; // 5 minutes default
+    }
+    /**
+     * Fetch a value from cache or compute it using the fetcher function
+     *
+     * @param key - Cache key
+     * @param fetcher - Function to fetch the value if not in cache
+     * @returns The cached or newly fetched value
+     */
+    async fetch(key, fetcher) {
+        const now = Date.now();
+        const cached = this.cache.get(key);
+        // Check if cached entry exists and is still valid
+        if (cached && cached.expiresAt > now) {
+            // Update last accessed time for LRU
+            cached.lastAccessed = now;
+            return cached.data;
+        }
+        // Remove expired entry if present
+        if (cached) {
+            this.cache.delete(key);
+        }
+        // Evict least recently used entries if at capacity
+        this.evictIfNeeded();
+        // Fetch fresh data
+        const data = await fetcher();
+        this.cache.set(key, {
+            data,
+            expiresAt: now + this.ttlMs,
+            lastAccessed: now,
+        });
+        return data;
+    }
+    /**
+     * Get a value from cache without fetching (returns undefined if not found or expired)
+     *
+     * @param key - Cache key
+     * @returns The cached value or undefined
+     */
+    get(key) {
+        const now = Date.now();
+        const cached = this.cache.get(key);
+        if (cached && cached.expiresAt > now) {
+            cached.lastAccessed = now;
+            return cached.data;
+        }
+        // Remove expired entry
+        if (cached) {
+            this.cache.delete(key);
+        }
+        return undefined;
+    }
+    /**
+     * Set a value in the cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     */
+    set(key, value) {
+        const now = Date.now();
+        this.evictIfNeeded();
+        this.cache.set(key, {
+            data: value,
+            expiresAt: now + this.ttlMs,
+            lastAccessed: now,
+        });
+    }
+    /**
+     * Delete a value from the cache
+     *
+     * @param key - Cache key
+     * @returns true if the entry was deleted, false if it didn't exist
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current size of the cache
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Evict expired entries and LRU entries if at capacity
+     */
+    evictIfNeeded() {
+        const now = Date.now();
+        // First, remove all expired entries
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt <= now) {
+                this.cache.delete(key);
+            }
+        }
+        // If still at capacity, remove least recently used entry
+        if (this.cache.size >= this.maxSize) {
+            let lruKey;
+            let lruTime = Infinity;
+            for (const [key, entry] of this.cache.entries()) {
+                if (entry.lastAccessed < lruTime) {
+                    lruTime = entry.lastAccessed;
+                    lruKey = key;
+                }
+            }
+            if (lruKey !== undefined) {
+                this.cache.delete(lruKey);
+            }
+        }
+    }
+    /**
+     * Clean up expired entries (can be called periodically)
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt <= now) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}

package/dist/utils/deep-clone.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deep Clone Utility
+ *
+ * Properly deep clones objects, handling edge cases that JSON.parse(JSON.stringify()) misses:
+ * - Preserves Date objects
+ * - Handles undefined values (by omitting them, which is acceptable for our use case)
+ * - Handles null values correctly
+ * - Works with plain objects and arrays
+ * - Handles Map, Set, RegExp, TypedArrays, ArrayBuffer
+ * - Throws on circular references (fail-fast is better than silent corruption)
+ *
+ * This is a comprehensive deep clone implementation suitable for production use.
+ * Moved from @revealui/ai/memory/utils/deep-clone.ts to @revealui/core/utils/deep-clone.ts
+ * for shared usage across the framework.
+ */
+/**
+ * Deep clones a plain object or array.
+ *
+ * @param obj - Object to clone
+ * @param visited - Internal parameter to track visited objects (for circular reference detection)
+ * @returns Deep cloned object
+ * @throws Error if object contains circular references
+ */
+export declare function deepClone<T>(obj: T, visited?: WeakMap<object, unknown>): T;
+//# sourceMappingURL=deep-clone.d.ts.map

package/dist/utils/deep-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-clone.d.ts","sourceRoot":"","sources":["../../src/utils/deep-clone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,2BAAiC,GAAG,CAAC,CAuHhF"}

package/dist/utils/deep-clone.js

@@ -0,0 +1,115 @@
+/**
+ * Deep Clone Utility
+ *
+ * Properly deep clones objects, handling edge cases that JSON.parse(JSON.stringify()) misses:
+ * - Preserves Date objects
+ * - Handles undefined values (by omitting them, which is acceptable for our use case)
+ * - Handles null values correctly
+ * - Works with plain objects and arrays
+ * - Handles Map, Set, RegExp, TypedArrays, ArrayBuffer
+ * - Throws on circular references (fail-fast is better than silent corruption)
+ *
+ * This is a comprehensive deep clone implementation suitable for production use.
+ * Moved from @revealui/ai/memory/utils/deep-clone.ts to @revealui/core/utils/deep-clone.ts
+ * for shared usage across the framework.
+ */
+/**
+ * Deep clones a plain object or array.
+ *
+ * @param obj - Object to clone
+ * @param visited - Internal parameter to track visited objects (for circular reference detection)
+ * @returns Deep cloned object
+ * @throws Error if object contains circular references
+ */
+export function deepClone(obj, visited = new WeakMap()) {
+    // Handle primitives and null
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    // Check for circular references
+    if (visited.has(obj)) {
+        throw new Error('Circular reference detected in object');
+    }
+    // Handle Date objects
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    // Handle RegExp objects
+    if (obj instanceof RegExp) {
+        return new RegExp(obj.source, obj.flags);
+    }
+    // Handle Map objects
+    if (obj instanceof Map) {
+        visited.set(obj, new Map());
+        const cloned = new Map();
+        for (const [key, value] of obj.entries()) {
+            cloned.set(deepClone(key, visited), deepClone(value, visited));
+        }
+        visited.delete(obj);
+        return cloned;
+    }
+    // Handle Set objects
+    if (obj instanceof Set) {
+        visited.set(obj, new Set());
+        const cloned = new Set();
+        for (const value of obj.values()) {
+            cloned.add(deepClone(value, visited));
+        }
+        visited.delete(obj);
+        return cloned;
+    }
+    // Handle TypedArrays (Uint8Array, Int32Array, etc.)
+    if (ArrayBuffer.isView(obj)) {
+        const typedArray = obj;
+        const TypedArrayConstructor = obj.constructor;
+        return new TypedArrayConstructor(typedArray.buffer.slice(), typedArray.byteOffset, typedArray.length);
+    }
+    // Handle ArrayBuffer
+    if (obj instanceof ArrayBuffer) {
+        return obj.slice(0);
+    }
+    // Handle arrays
+    if (Array.isArray(obj)) {
+        visited.set(obj, []);
+        const array = obj;
+        const cloned = array.map((item) => deepClone(item, visited));
+        visited.delete(obj);
+        return cloned;
+    }
+    // Handle plain objects
+    if (typeof obj === 'object') {
+        visited.set(obj, {});
+        const cloned = {};
+        const objRecord = obj;
+        for (const key in objRecord) {
+            if (Object.hasOwn(objRecord, key)) {
+                const value = objRecord[key];
+                // Skip undefined (JSON.stringify behavior)
+                if (value === undefined) {
+                    continue;
+                }
+                try {
+                    ;
+                    cloned[key] = deepClone(value, visited);
+                }
+                catch (error) {
+                    visited.delete(obj);
+                    // If we hit a circular reference or other issue, throw with context
+                    throw new Error(`Failed to deep clone object: ${error instanceof Error ? error.message : String(error)} at key "${key}"`);
+                }
+            }
+        }
+        visited.delete(obj);
+        return cloned;
+    }
+    // Handle functions - return as-is (can't clone functions)
+    if (typeof obj === 'function') {
+        return obj;
+    }
+    // Handle symbols - return as-is (symbols are unique by design)
+    if (typeof obj === 'symbol') {
+        return obj;
+    }
+    // Fallback for other types
+    return obj;
+}

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,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,iBAAiB,CA8BnB;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,96 @@
+/**
+ * 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
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+        error: 'INTERNAL_ERROR',
+        message: errorMessage,
+        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,97 @@
+/**
+ * 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);
+}
+/**
+ * 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":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAGhC,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,MAAM;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHxC,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAM3C;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAG/B,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,OAAO;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHxC,OAAO,EAAE,MAAM,EACR,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAM3C;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAG7B,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,MAAM;IAClB,MAAM,CAAC,EAAE,MAAM;IACf,UAAU,CAAC,EAAE,MAAM;IACnB,KAAK,CAAC,EAAE,MAAM;IACd,MAAM,CAAC,EAAE,MAAM;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAPxC,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY,EACxB,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAM3C;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;CAkCpB,CAAA;AAkCV;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CA+D7E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CA4WP"}