@creact-labs/creact 0.1.8 → 0.2.1

package/dist/utils/deepEqual.js

@@ -1,276 +0,0 @@
-"use strict";
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.deepEqual = deepEqual;
-exports.clearEqualityCache = clearEqualityCache;
-exports.getEqualityCacheStats = getEqualityCacheStats;
-// Utility for deep equality comparison
-// Used by Reconciler for prop diffing and StateMachine for checkpoint diffs
-/**
- * Cache for memoizing deep equality comparisons
- * Key format: `${hashA}::${hashB}` (using content hashes for performance)
- */
-const equalityCache = new Map();
-/**
- * Cache for object hashes to avoid repeated JSON.stringify calls
- * Uses WeakMap for automatic garbage collection
- */
-const hashCache = new WeakMap();
-/**
- * Cache for primitive hashes (strings, numbers, etc.)
- * Uses regular Map with size limit since primitives aren't garbage collected
- */
-const primitiveHashCache = new Map();
-/**
- * Cache hit/miss statistics for performance profiling
- */
-let cacheHits = 0;
-let cacheMisses = 0;
-/**
- * Maximum cache size to prevent memory leaks
- */
-const MAX_CACHE_SIZE = 1000;
-const MAX_PRIMITIVE_CACHE_SIZE = 500;
-/**
- * Compute a fast hash of a value for cache keys
- *
- * Uses WeakMap to cache hashes per object reference.
- * Uses regular Map with size limit for primitives.
- *
- * @param value - Value to hash
- * @returns Hash string
- */
-function fastHash(value) {
-    // Primitives: use string representation with caching
-    if (value === null || value === undefined) {
-        return String(value);
-    }
-    if (typeof value !== 'object') {
-        const primitiveKey = `${typeof value}:${String(value)}`;
-        // Check primitive cache
-        if (primitiveHashCache.has(primitiveKey)) {
-            return primitiveHashCache.get(primitiveKey);
-        }
-        // Store in primitive cache (with size limit)
-        if (primitiveHashCache.size >= MAX_PRIMITIVE_CACHE_SIZE) {
-            // Clear oldest entry (simple FIFO)
-            const firstKey = primitiveHashCache.keys().next().value;
-            if (firstKey !== undefined) {
-                primitiveHashCache.delete(firstKey);
-            }
-        }
-        primitiveHashCache.set(primitiveKey, primitiveKey);
-        return primitiveKey;
-    }
-    // Objects: use WeakMap cache
-    if (hashCache.has(value)) {
-        return hashCache.get(value);
-    }
-    // Compute hash (simple but fast)
-    try {
-        const hash = JSON.stringify(value);
-        hashCache.set(value, hash);
-        return hash;
-    }
-    catch {
-        // Circular reference or non-serializable - use object identity
-        const hash = `obj:${Math.random()}`;
-        hashCache.set(value, hash);
-        return hash;
-    }
-}
-/**
- * Deep equality comparison with memoization
- *
- * Compares two values deeply, handling:
- * - Primitives (string, number, boolean, null, undefined)
- * - Arrays (order matters)
- * - Objects (key order doesn't matter)
- * - Nested structures
- *
- * Memoizes results for performance on large graphs.
- *
- * Note: Does not handle:
- * - Functions (always considered unequal)
- * - Symbols (always considered unequal)
- * - Circular references (will throw)
- * - Special objects (Date, RegExp, Map, Set) - uses JSON serialization
- *
- * @param a - First value
- * @param b - Second value
- * @param useMemoization - Enable memoization (default: true)
- * @returns True if values are deeply equal
- */
-function deepEqual(a, b, useMemoization = true) {
-    // Fast path: reference equality
-    if (a === b) {
-        return true;
-    }
-    // Fast path: type mismatch
-    if (typeof a !== typeof b) {
-        return false;
-    }
-    // Fast path: null/undefined
-    if (a === null || b === null || a === undefined || b === undefined) {
-        return a === b;
-    }
-    // Check memoization cache
-    if (useMemoization) {
-        try {
-            const hashA = fastHash(a);
-            const hashB = fastHash(b);
-            const cacheKey = `${hashA}::${hashB}`;
-            if (equalityCache.has(cacheKey)) {
-                cacheHits++;
-                return equalityCache.get(cacheKey);
-            }
-            cacheMisses++;
-            // Compute equality
-            const result = deepEqualImpl(a, b);
-            // Store in cache (with size limit)
-            if (equalityCache.size >= MAX_CACHE_SIZE) {
-                // Clear oldest entries (simple FIFO)
-                const firstKey = equalityCache.keys().next().value;
-                if (firstKey !== undefined) {
-                    equalityCache.delete(firstKey);
-                }
-            }
-            equalityCache.set(cacheKey, result);
-            return result;
-        }
-        catch {
-            // If hashing fails, fall back to non-memoized
-            cacheMisses++;
-            return deepEqualImpl(a, b);
-        }
-    }
-    return deepEqualImpl(a, b);
-}
-/**
- * Internal implementation of deep equality (without memoization)
- *
- * Optimized for performance:
- * - Short-circuits on primitives
- * - Fast path for common types
- * - Avoids redundant checks
- * - Handles circular references using WeakMap
- *
- * @param a - First value
- * @param b - Second value
- * @param visited - WeakMap tracking visited pairs to handle circular refs
- * @returns True if values are deeply equal
- */
-function deepEqualImpl(a, b, visited = new WeakMap()) {
-    // Fast path: primitives and null/undefined
-    const typeA = typeof a;
-    const typeB = typeof b;
-    if (typeA !== 'object' || typeB !== 'object') {
-        return a === b;
-    }
-    if (a === null || b === null) {
-        return a === b;
-    }
-    // Fast path: same reference
-    if (a === b) {
-        return true;
-    }
-    // Circular reference detection
-    if (visited.has(a)) {
-        return visited.get(a) === b;
-    }
-    visited.set(a, b);
-    // Arrays
-    if (Array.isArray(a)) {
-        if (!Array.isArray(b)) {
-            return false;
-        }
-        if (a.length !== b.length) {
-            return false;
-        }
-        for (let i = 0; i < a.length; i++) {
-            if (!deepEqualImpl(a[i], b[i], visited)) {
-                return false;
-            }
-        }
-        return true;
-    }
-    // Array vs non-array
-    if (Array.isArray(b)) {
-        return false;
-    }
-    // Objects
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    if (keysA.length !== keysB.length) {
-        return false;
-    }
-    // Convert keysB to Set for O(1) lookup
-    const keysBSet = new Set(keysB);
-    // Check all keys exist and values are equal
-    for (const key of keysA) {
-        if (!keysBSet.has(key)) {
-            return false;
-        }
-        if (!deepEqualImpl(a[key], b[key], visited)) {
-            return false;
-        }
-    }
-    return true;
-}
-/**
- * Clear the memoization caches
- *
- * Useful for testing or when memory usage is a concern.
- */
-function clearEqualityCache() {
-    equalityCache.clear();
-    primitiveHashCache.clear();
-    cacheHits = 0;
-    cacheMisses = 0;
-    // Note: hashCache (WeakMap) is automatically garbage collected
-}
-/**
- * Get cache statistics for monitoring and performance profiling
- *
- * @returns Cache size, hit rate, and performance metrics
- */
-function getEqualityCacheStats() {
-    const total = cacheHits + cacheMisses;
-    const hitRate = total > 0 ? cacheHits / total : 0;
-    return {
-        size: equalityCache.size,
-        maxSize: MAX_CACHE_SIZE,
-        hits: cacheHits,
-        misses: cacheMisses,
-        hitRate,
-        primitiveSize: primitiveHashCache.size,
-    };
-}

package/dist/utils/naming.d.ts

@@ -1,241 +0,0 @@
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-/**
- * Generate a resource ID from a Fiber path
- *
- * Converts a hierarchical path array into a dot-separated resource ID.
- * Each path segment is converted to kebab-case for consistency.
- *
- * Examples:
- * - ['registry', 'service'] → 'registry.service'
- * - ['Registry', 'ServiceAPI'] → 'registry.service-api'
- * - ['my-app', 'database'] → 'my-app.database'
- *
- * REQ-01: Resource ID generation from component hierarchy
- *
- * @param path - Hierarchical path segments
- * @returns Dot-separated resource ID
- */
-export declare function generateResourceId(path: string[]): string;
-/**
- * Convert a string to kebab-case
- *
- * Handles various input formats:
- * - PascalCase: 'RegistryStack' → 'registry-stack'
- * - camelCase: 'serviceAPI' → 'service-api'
- * - snake_case: 'my_service' → 'my-service'
- * - spaces: 'My Service' → 'my-service'
- * - Already kebab: 'my-service' → 'my-service'
- *
- * REQ-01: Kebab-case formatting for multi-word names
- *
- * @param str - String to convert
- * @returns Kebab-case string
- */
-export declare function toKebabCase(str: string): string;
-/**
- * Generate a node name from component type and key
- *
- * Priority order:
- * 1. Custom key prop (highest priority, for identity)
- * 2. Component function name or displayName
- * 3. Type string (for intrinsic elements)
- * 4. 'anonymous' (fallback)
- * 5. Append siblingIndex if > 0 (for automatic position-based keys)
- *
- * Note: The props parameter is kept for future extensibility and for passing
- * to child components during execution, but props are NOT used for node identity.
- * Only the 'key' prop determines identity.
- *
- * REQ-01: Support custom keys via key prop
- * REQ-6.9: Only key prop is used for identity, not name prop
- * REQ-6.2: Automatic position-based keys for static JSX siblings
- *
- * @param type - Component type (function, class, or string)
- * @param props - Component props (for component execution, not identity)
- * @param key - Optional key prop (for identity)
- * @param siblingIndex - Optional sibling index for automatic key generation
- * @returns Node name in kebab-case
- */
-export declare function getNodeName(type: any, props?: Record<string, any>, key?: string | number, siblingIndex?: number): string;
-/**
- * Validate resource ID uniqueness within a scope
- *
- * Checks if a resource ID already exists in the given set.
- * Throws an error if duplicate is found.
- *
- * REQ-01: Ensure IDs are unique within scope
- *
- * @param id - Resource ID to validate
- * @param existingIds - Set of existing IDs in scope
- * @param componentStack - Component stack for error reporting
- * @throws Error if ID is not unique
- */
-export declare function validateIdUniqueness(id: string, existingIds: Set<string>, componentStack?: string[]): void;
-/**
- * Normalize a path segment for consistent resource addressing
- *
- * Applies full kebab-case conversion for consistency:
- * - Converts PascalCase/camelCase to kebab-case
- * - Handles underscores, spaces, numbers
- * - Trims whitespace
- * - Removes leading/trailing hyphens
- *
- * @param segment - Path segment to normalize
- * @returns Normalized segment in kebab-case
- */
-export declare function normalizePathSegment(segment: string): string;
-/**
- * Normalize an entire path for consistent resource addressing
- *
- * Converts all path segments to kebab-case for consistency.
- *
- * @param path - Path segments to normalize
- * @returns Normalized path segments in kebab-case
- */
-export declare function normalizePath(path: string[]): string[];
-/**
- * Format a path for human-readable display
- *
- * Examples:
- * - ['registry', 'service'] → 'registry > service'
- * - ['app', 'database', 'table'] → 'app > database > table'
- *
- * @param path - Path segments
- * @returns Formatted path string
- */
-export declare function formatPath(path: string[]): string;
-/**
- * Parse a resource ID back into path segments
- *
- * Inverse of generateResourceId.
- *
- * Examples:
- * - 'registry.service' → ['registry', 'service']
- * - 'app.database.table' → ['app', 'database', 'table']
- *
- * @param id - Resource ID
- * @returns Path segments
- */
-export declare function parseResourceId(id: string): string[];
-/**
- * Generate a binding key for state-output binding tracking
- *
- * Creates a consistent key format for tracking bindings between
- * component state and provider outputs.
- *
- * Examples:
- * - ('registry.service', 'url') → 'registry.service.url'
- * - ('app.database', 'connectionString') → 'app.database.connection-string'
- *
- * @param nodeId - CloudDOM node ID
- * @param outputKey - Output key name
- * @returns Binding key
- */
-export declare function generateBindingKey(nodeId: string, outputKey: string): string;
-/**
- * Parse a binding key back into nodeId and outputKey
- *
- * Inverse of generateBindingKey.
- *
- * Examples:
- * - 'registry.service.url' → { nodeId: 'registry.service', outputKey: 'url' }
- * - 'app.database.connection-string' → { nodeId: 'app.database', outputKey: 'connection-string' }
- *
- * @param bindingKey - Binding key
- * @returns Object with nodeId and outputKey
- */
-export declare function parseBindingKey(bindingKey: string): {
-    nodeId: string;
-    outputKey: string;
-};
-/**
- * Generate a state output key for useState hooks
- *
- * REQ-3.1: Generate state keys without prefix (stored in separate state field)
- *
- * Creates a key for useState outputs. Uses 1-based indexing for consistency.
- * State values are stored in the separate `state` field on CloudDOMNode,
- * not in the `outputs` field, so no prefix is needed.
- *
- * Examples:
- * - generateStateOutputKey(0) → 'state1'
- * - generateStateOutputKey(1) → 'state2'
- * - generateStateOutputKey(2) → 'state3'
- *
- * @param hookIndex - Zero-based hook index
- * @returns State output key without prefix
- */
-export declare function generateStateOutputKey(hookIndex: number): string;
-/**
- * Check if an output key is a state output (matches state key format)
- *
- * REQ-3.1: Identify useState outputs by their key format (state1, state2, etc.)
- *
- * Examples:
- * - isStateOutputKey('state1') → true
- * - isStateOutputKey('state2') → true
- * - isStateOutputKey('connectionUrl') → false
- * - isStateOutputKey('vaultUrl') → false
- *
- * @param outputKey - Output key to check
- * @returns True if the key is a state output
- */
-export declare function isStateOutputKey(outputKey: string): boolean;
-/**
- * Check if an output key is a provider output (not a state key)
- *
- * REQ-3.1: Identify provider outputs by absence of state key format
- *
- * Examples:
- * - isProviderOutputKey('connectionUrl') → true
- * - isProviderOutputKey('vaultUrl') → true
- * - isProviderOutputKey('state1') → false
- * - isProviderOutputKey('state2') → false
- *
- * @param outputKey - Output key to check
- * @returns True if the key is a provider output
- */
-export declare function isProviderOutputKey(outputKey: string): boolean;
-/**
- * Parse a state output key to extract the hook index
- *
- * Inverse of generateStateOutputKey.
- *
- * Examples:
- * - parseStateOutputKey('state1') → 0
- * - parseStateOutputKey('state2') → 1
- * - parseStateOutputKey('state3') → 2
- *
- * @param stateOutputKey - State output key
- * @returns Zero-based hook index
- * @throws Error if the key is not a valid state output key
- */
-export declare function parseStateOutputKey(stateOutputKey: string): number;