@revealui/core 0.0.0-canary-20260409021642

package/dist/utils/api-wrapper.js

@@ -0,0 +1,151 @@
+/**
+ * API Route Wrapper
+ *
+ * Wraps Next.js API routes to automatically set up request context,
+ * error handling, and logging.
+ */
+import { NextResponse } from 'next/server';
+import { handleApiError } from './errors.js';
+import { logger } from './logger.js';
+import { createRequestContext, getRequestDuration, runInRequestContext, } from './request-context.js';
+/**
+ * Wrap an API route handler with request context, logging, and error handling
+ *
+ * Benefits:
+ * - Automatic request ID generation and propagation
+ * - Request context available via getRequestContext()
+ * - Automatic error handling with proper status codes
+ * - Request/response logging with timing
+ * - All logs include request ID automatically
+ *
+ * @param handler - API route handler function
+ * @returns Wrapped handler with request context
+ *
+ * @example
+ * ```typescript
+ * // app/api/users/route.ts
+ * import { withRequestContext } from '@revealui/core/utils/api-wrapper'
+ * import { NextResponse } from 'next/server'
+ *
+ * export const GET = withRequestContext(async (request) => {
+ *   // Request ID automatically available in logs
+ *   logger.info('Fetching users') // Includes requestId automatically
+ *
+ *   const users = await db.query.users.findMany()
+ *   return NextResponse.json(users)
+ * })
+ * ```
+ */
+export function withRequestContext(handler) {
+    return async (request) => {
+        // Create request context from headers
+        const context = createRequestContext({
+            headers: Object.fromEntries(request.headers.entries()),
+            path: request.nextUrl.pathname,
+            method: request.method,
+            ip: request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || undefined,
+        });
+        // Log incoming request
+        logger.info('Incoming request', {
+            method: context.method,
+            path: context.path,
+            ip: context.ip,
+            userAgent: context.userAgent,
+        });
+        try {
+            // Run handler within request context
+            const response = await runInRequestContext(context, () => handler(request));
+            // Log successful response
+            const duration = getRequestDuration();
+            logger.info('Request completed', {
+                method: context.method,
+                path: context.path,
+                status: response.status,
+                duration,
+            });
+            // Add request ID to response headers
+            if (response instanceof NextResponse) {
+                response.headers.set('x-request-id', context.requestId);
+                response.headers.set('x-request-duration', duration?.toString() || '0');
+            }
+            return response;
+        }
+        catch (error) {
+            // Handle errors with proper logging and status codes
+            const duration = getRequestDuration();
+            logger.error('Request failed', {
+                method: context.method,
+                path: context.path,
+                error: error instanceof Error ? error.message : String(error),
+                duration,
+            });
+            // Convert error to API response
+            const apiError = handleApiError(error, {
+                method: context.method,
+                path: context.path,
+            });
+            const errorResponse = NextResponse.json({
+                error: {
+                    message: apiError.message,
+                    code: apiError.code,
+                    ...(apiError.retryable !== undefined && { retryable: apiError.retryable }),
+                },
+            }, { status: apiError.statusCode });
+            // Add request ID to error response
+            errorResponse.headers.set('x-request-id', context.requestId);
+            errorResponse.headers.set('x-request-duration', duration?.toString() || '0');
+            return errorResponse;
+        }
+    };
+}
+/**
+ * Server action wrapper for request context
+ *
+ * Use this for Next.js Server Actions to enable request tracing
+ *
+ * @param action - Server action function
+ * @returns Wrapped action with request context
+ *
+ * @example
+ * ```typescript
+ * 'use server'
+ *
+ * import { withServerActionContext } from '@revealui/core/utils/api-wrapper'
+ *
+ * export const createUser = withServerActionContext(async (data) => {
+ *   logger.info('Creating user') // Includes requestId
+ *   return await db.insert(users).values(data)
+ * })
+ * ```
+ */
+export function withServerActionContext(action) {
+    return async (...args) => {
+        // Create request context (no headers available in server actions)
+        const context = createRequestContext({});
+        // Log server action execution
+        logger.info('Server action started', {
+            action: action.name || 'anonymous',
+        });
+        try {
+            // Run action within request context
+            const result = await runInRequestContext(context, () => action(...args));
+            // Log successful execution
+            const duration = getRequestDuration();
+            logger.info('Server action completed', {
+                action: action.name || 'anonymous',
+                duration,
+            });
+            return result;
+        }
+        catch (error) {
+            // Log error
+            const duration = getRequestDuration();
+            logger.error('Server action failed', {
+                action: action.name || 'anonymous',
+                error: error instanceof Error ? error.message : String(error),
+                duration,
+            });
+            throw error;
+        }
+    };
+}

package/dist/utils/block-conversion.d.ts

@@ -0,0 +1,21 @@
+import type React from 'react';
+import type { Block, RevealUIBlock, RevealUIContext } from '../types/index.js';
+export declare function convertToRevealUIBlock(block: Block): RevealUIBlock;
+export declare function convertFromRevealUIBlock(revealUIBlock: RevealUIBlock): Block;
+export declare function enhanceBlockWithRevealUI(block: Block, revealUIOptions?: RevealUIBlock['revealUI']): RevealUIBlock;
+/**
+ * Validate a RevealUI block
+ *
+ * @async
+ * @param block - The RevealUI block to validate
+ * @param data - The data to validate against the block
+ * @param context - The RevealUI context for validation
+ * @returns Promise resolving to a record of field errors (empty if valid)
+ */
+export declare function validateRevealUIBlock(block: RevealUIBlock, data: Record<string, unknown>, context: RevealUIContext): Promise<Record<string, string>>;
+export declare function getRevealUIBlockComponent(block: RevealUIBlock): React.ComponentType<{
+    data: Record<string, unknown>;
+    onChange: (data: Record<string, unknown>) => void;
+    revealUI?: RevealUIContext;
+}>;
+//# sourceMappingURL=block-conversion.d.ts.map

package/dist/utils/block-conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-conversion.d.ts","sourceRoot":"","sources":["../../src/utils/block-conversion.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAS,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAItF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAalE;AAGD,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,aAAa,GAAG,KAAK,CAa5E;AAGD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,KAAK,EACZ,eAAe,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,GAC1C,aAAa,CAWf;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA0BjC;AAGD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IACnF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAClD,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC,CAsDD"}

package/dist/utils/block-conversion.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { convertToRevealUIField } from './field-conversion.js';
+// Convert from standard block to RevealUI block
+export function convertToRevealUIBlock(block) {
+    return {
+        slug: block.slug,
+        fields: block.fields.map(convertToRevealUIField),
+        revealUI: {
+            category: 'content',
+            icon: 'block',
+            preview: undefined,
+            permissions: ['read', 'write'],
+            tenantScoped: false,
+        },
+        labels: block.labels || { singular: block.slug, plural: `${block.slug}s` },
+    };
+}
+// Convert from RevealUI block to standard block
+export function convertFromRevealUIBlock(revealUIBlock) {
+    return {
+        slug: revealUIBlock.slug,
+        fields: revealUIBlock.fields.map((field) => ({
+            name: field.name,
+            type: field.type,
+            label: field.label,
+            required: field.required,
+            admin: field.admin,
+            validate: field.validate,
+        })),
+        labels: revealUIBlock.labels,
+    };
+}
+// Enhance a standard block with RevealUI features
+export function enhanceBlockWithRevealUI(block, revealUIOptions) {
+    const revealUIBlock = convertToRevealUIBlock(block);
+    if (revealUIOptions) {
+        revealUIBlock.revealUI = {
+            ...revealUIBlock.revealUI,
+            ...revealUIOptions,
+        };
+    }
+    return revealUIBlock;
+}
+/**
+ * Validate a RevealUI block
+ *
+ * @async
+ * @param block - The RevealUI block to validate
+ * @param data - The data to validate against the block
+ * @param context - The RevealUI context for validation
+ * @returns Promise resolving to a record of field errors (empty if valid)
+ */
+export async function validateRevealUIBlock(block, data, context) {
+    const errors = {};
+    // Validate each field in the block
+    for (const field of block.fields) {
+        if (!field.name)
+            continue; // Skip fields without names
+        const value = data[field.name];
+        const validationContext = {
+            data,
+            siblingData: data,
+            user: context.user ?? undefined,
+            tenant: context.tenant,
+            operation: 'update',
+        };
+        // Import the validation function dynamically to avoid circular imports
+        const { validateRevealUIField } = await import('./field-conversion.js');
+        const result = validateRevealUIField(field, value, validationContext);
+        if (result !== true) {
+            errors[field.name] = result;
+        }
+    }
+    return errors;
+}
+// Get a React component for rendering a RevealUI block
+export function getRevealUIBlockComponent(block) {
+    return function RevealUIBlockComponent({ data, onChange, revealUI }) {
+        void revealUI;
+        const blockFields = block.fields.map((field) => {
+            return {
+                name: field.name,
+                type: field.type,
+                label: field.label,
+                required: field.required,
+            };
+        });
+        const formatValue = (value) => {
+            if (value === null || value === undefined)
+                return '';
+            if (typeof value === 'string')
+                return value;
+            if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+                return String(value);
+            }
+            if (typeof value === 'symbol')
+                return value.description ?? value.toString();
+            if (typeof value === 'function')
+                return value.name || 'function';
+            return JSON.stringify(value);
+        };
+        return (_jsx("div", { className: "reveal-ui-block", "data-block-slug": block.slug, children: _jsx("div", { className: "reveal-ui-block-fields", children: blockFields.map((field) => {
+                    const fieldName = typeof field.name === 'string' ? field.name : '';
+                    const fieldLabel = typeof field.label === 'string' ? field.label : fieldName || 'Field';
+                    const value = fieldName ? data[fieldName] : undefined;
+                    return (_jsxs("div", { className: "reveal-ui-field", children: [_jsxs("label", { className: "reveal-ui-field-label", htmlFor: `field-${fieldName}`, children: [fieldLabel, field.required && _jsx("span", { className: "required", children: "*" })] }), _jsx("div", { className: "reveal-ui-field-input", children: _jsx("input", { type: "text", id: `field-${fieldName}`, value: formatValue(value), onChange: (e) => onChange({ ...data, [fieldName]: e.target.value }), required: field.required }) })] }, fieldName || Math.random()));
+                }) }) }));
+    };
+}

package/dist/utils/cache.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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'))
+ * ```
+ */
+export interface LRUCacheOptions {
+    /**
+     * Maximum number of entries in the cache
+     * @default 100
+     */
+    maxSize?: number;
+    /**
+     * Time to live in milliseconds
+     * @default 5 minutes (300000)
+     */
+    ttlMs?: number;
+}
+/**
+ * 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 declare class LRUCache<K = string, V = unknown> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(options?: LRUCacheOptions);
+    /**
+     * 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
+     */
+    fetch(key: K, fetcher: () => Promise<V> | V): Promise<V>;
+    /**
+     * 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: K): V | undefined;
+    /**
+     * Set a value in the cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * 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: K): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current size of the cache
+     */
+    get size(): number;
+    /**
+     * Evict expired entries and LRU entries if at capacity
+     */
+    private evictIfNeeded;
+    /**
+     * Clean up expired entries (can be called periodically)
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;;GAOG;AACH,qBAAa,QAAQ,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO;IAC3C,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,GAAE,eAAoB;IAKzC;;;;;;OAMG;IACG,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8B9D;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAiB1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAW3B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IA4BrB;;OAEG;IACH,OAAO,IAAI,IAAI;CAQhB"}

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,114 @@
+/**
+ * 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;
+}