@signaltree/core 1.0.3 → 1.1.0

package/fesm2022/signaltree-core.mjs

@@ -1,11 +1,19 @@
 import { signal, isSignal, computed, effect, inject, DestroyRef } from '@angular/core';
 
-// Path parsing cache for performance optimization
-const pathCache = new Map();
+/**
+ * SignalTree Utility Functions - Recursive Typing Implementation
+ *
+ * COPYRIGHT NOTICE:
+ * This file contains proprietary utility functions for the recursive typing system.
+ * The createLazySignalTree function and built-in object detection methods are
+ * protected intellectual property of Jonathan D Borgia.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
 /**
  * Enhanced equality function inspired by the monolithic implementation.
  * Uses deep equality for arrays and objects, === for primitives.
- * More efficient than lodash while maintaining compatibility.
+ * Optimized with early exits and type-specific comparisons.
  */
 function equal(a, b) {
     // Fast path for reference equality
@@ -14,23 +22,31 @@ function equal(a, b) {
     // Handle null/undefined cases
     if (a == null || b == null)
         return a === b;
-    // Handle arrays with deep comparison
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
+    // Type check first - most efficient early exit
+    const typeA = typeof a;
+    const typeB = typeof b;
+    if (typeA !== typeB)
+        return false;
+    // For primitives, === check above is sufficient
+    if (typeA !== 'object')
+        return false;
+    // Handle arrays with optimized comparison
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
             return false;
         return a.every((item, index) => equal(item, b[index]));
     }
-    // Handle objects with deep comparison
-    if (typeof a === 'object' && typeof b === 'object') {
-        const keysA = Object.keys(a);
-        const keysB = Object.keys(b);
-        if (keysA.length !== keysB.length)
-            return false;
-        return keysA.every((key) => keysB.includes(key) &&
-            equal(a[key], b[key]));
-    }
-    // Fallback to strict equality
-    return a === b;
+    // Arrays check above handles array vs object mismatch
+    if (Array.isArray(b))
+        return false;
+    // Handle objects with optimized comparison
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key) => key in objB && equal(objA[key], objB[key]));
 }
 /**
  * Creates a terminal signal with the enhanced equality function.
@@ -45,8 +61,48 @@ function terminalSignal(value, customEqual) {
     });
 }
 /**
- * Parses a dot-notation path into an array of keys with memoization.
+ * LRU Cache implementation for efficient memory management
+ */
+class LRUCache {
+    maxSize;
+    cache = new Map();
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    set(key, value) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        // Remove if exists to update position
+        this.cache.delete(key);
+        this.cache.set(key, value); // Add to end (most recent)
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            // Move to end (mark as recently used)
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+// Path parsing cache with proper LRU eviction strategy
+const MAX_CACHE_SIZE = 1000;
+const pathCache = new LRUCache(MAX_CACHE_SIZE);
+/**
+ * Parses a dot-notation path into an array of keys with LRU memoization.
  * Critical for performance when accessing nested properties frequently.
+ * Includes proper LRU cache management to prevent memory leaks.
  *
  * @example
  * ```typescript
@@ -55,16 +111,19 @@ function terminalSignal(value, customEqual) {
  * ```
  */
 function parsePath(path) {
-    if (!pathCache.has(path)) {
-        pathCache.set(path, path.split('.'));
-    }
     const cached = pathCache.get(path);
-    return cached ?? path.split('.');
+    if (cached) {
+        return cached;
+    }
+    const parts = path.split('.');
+    pathCache.set(path, parts);
+    return parts;
 }
 /**
  * Creates a lazy signal tree using Proxy for on-demand signal creation.
  * Only creates signals when properties are first accessed, providing
  * massive memory savings for large state objects.
+ * Uses WeakMap for memory-safe caching.
  *
  * @param obj - Source object to lazily signalify
  * @param equalityFn - Equality function for signal comparison
@@ -72,16 +131,68 @@ function parsePath(path) {
  * @returns Proxied object that creates signals on first access
  */
 function createLazySignalTree(obj, equalityFn, basePath = '') {
+    // Use Map instead of WeakMap for better control over cleanup
     const signalCache = new Map();
     const nestedProxies = new Map();
-    return new Proxy(obj, {
+    // Track cleanup functions for nested proxies
+    const nestedCleanups = new Map();
+    // Enhanced cleanup function
+    const cleanup = () => {
+        // Clean up all nested proxies first
+        nestedCleanups.forEach((cleanupFn) => {
+            try {
+                cleanupFn();
+            }
+            catch (error) {
+                console.warn('Error during nested cleanup:', error);
+            }
+        });
+        nestedCleanups.clear();
+        // Clear caches
+        signalCache.clear();
+        nestedProxies.clear();
+    };
+    // Enhanced built-in object detection
+    const isBuiltInObject = (v) => {
+        if (v === null || v === undefined)
+            return false;
+        return (v instanceof Date ||
+            v instanceof RegExp ||
+            typeof v === 'function' ||
+            v instanceof Map ||
+            v instanceof Set ||
+            v instanceof WeakMap ||
+            v instanceof WeakSet ||
+            v instanceof ArrayBuffer ||
+            v instanceof DataView ||
+            v instanceof Error ||
+            v instanceof Promise ||
+            v instanceof URL ||
+            v instanceof URLSearchParams ||
+            v instanceof FormData ||
+            v instanceof Blob ||
+            (typeof File !== 'undefined' && v instanceof File));
+    };
+    const proxy = new Proxy(obj, {
         get(target, prop) {
+            // Handle cleanup method
+            if (prop === '__cleanup__') {
+                return cleanup;
+            }
             // Handle symbol properties (like Symbol.iterator) normally
             if (typeof prop === 'symbol') {
                 return target[prop];
             }
+            // Handle inspection methods
+            if (prop === 'valueOf' || prop === 'toString') {
+                return target[prop];
+            }
             const key = prop;
             const path = basePath ? `${basePath}.${key}` : key;
+            // Safety check for property existence
+            if (!(key in target)) {
+                return undefined;
+            }
             const value = target[key];
             // If it's already a signal, return it
             if (isSignal(value)) {
@@ -99,15 +210,36 @@ function createLazySignalTree(obj, equalityFn, basePath = '') {
             if (value &&
                 typeof value === 'object' &&
                 !Array.isArray(value) &&
-                !isSignal(value)) {
-                const nestedProxy = createLazySignalTree(value, equalityFn, path);
-                nestedProxies.set(path, nestedProxy);
-                return nestedProxy;
+                !isSignal(value) &&
+                !isBuiltInObject(value)) {
+                try {
+                    const nestedProxy = createLazySignalTree(value, equalityFn, path);
+                    nestedProxies.set(path, nestedProxy);
+                    // Store cleanup function for nested proxy
+                    const proxyWithCleanup = nestedProxy;
+                    if (typeof proxyWithCleanup.__cleanup__ === 'function') {
+                        nestedCleanups.set(path, proxyWithCleanup.__cleanup__);
+                    }
+                    return nestedProxy;
+                }
+                catch (error) {
+                    console.warn(`Failed to create lazy proxy for path "${path}":`, error);
+                    // Fallback: create a signal for the object
+                    const fallbackSignal = signal(value, ...(ngDevMode ? [{ debugName: "fallbackSignal", equal: equalityFn }] : [{ equal: equalityFn }]));
+                    signalCache.set(path, fallbackSignal);
+                    return fallbackSignal;
+                }
+            }
+            // Create signal for primitive values, arrays, and built-in objects
+            try {
+                const newSignal = signal(value, ...(ngDevMode ? [{ debugName: "newSignal", equal: equalityFn }] : [{ equal: equalityFn }]));
+                signalCache.set(path, newSignal);
+                return newSignal;
+            }
+            catch (error) {
+                console.warn(`Failed to create signal for path "${path}":`, error);
+                return value; // Return raw value as fallback
             }
-            // Create signal for primitive values and arrays
-            const newSignal = signal(value, ...(ngDevMode ? [{ debugName: "newSignal", equal: equalityFn }] : [{ equal: equalityFn }]));
-            signalCache.set(path, newSignal);
-            return newSignal;
         },
         set(target, prop, value) {
             if (typeof prop === 'symbol') {
@@ -116,18 +248,30 @@ function createLazySignalTree(obj, equalityFn, basePath = '') {
             }
             const key = prop;
             const path = basePath ? `${basePath}.${key}` : key;
-            // Update the original object
-            target[key] = value;
-            // If we have a cached signal, update it
-            const cachedSignal = signalCache.get(path);
-            if (cachedSignal) {
-                cachedSignal.set(value);
+            try {
+                // Update the original object
+                target[key] = value;
+                // If we have a cached signal, update it
+                const cachedSignal = signalCache.get(path);
+                if (cachedSignal && 'set' in cachedSignal) {
+                    cachedSignal.set(value);
+                }
+                // Clear nested proxy cache if the value type changed
+                if (nestedProxies.has(path)) {
+                    // Clean up the nested proxy
+                    const nestedCleanup = nestedCleanups.get(path);
+                    if (nestedCleanup) {
+                        nestedCleanup();
+                        nestedCleanups.delete(path);
+                    }
+                    nestedProxies.delete(path);
+                }
+                return true;
             }
-            // Clear nested proxy cache if the value type changed
-            if (nestedProxies.has(path)) {
-                nestedProxies.delete(path);
+            catch (error) {
+                console.warn(`Failed to set value for path "${path}":`, error);
+                return false;
             }
-            return true;
         },
         has(target, prop) {
             return prop in target;
@@ -139,6 +283,7 @@ function createLazySignalTree(obj, equalityFn, basePath = '') {
             return Reflect.getOwnPropertyDescriptor(target, prop);
         },
     });
+    return proxy;
 }
 /**
  * Native deep equality check for arrays and objects.
@@ -224,6 +369,20 @@ function shallowEqual(a, b) {
     return false;
 }
 
+/**
+ * SignalTree Core Implementation - Recursive Typing Engine
+ *
+ * COPYRIGHT NOTICE:
+ * This file contains the proprietary recursive typing implementation protected
+ * under the SignalTree license. The signal-store pattern, recursive type-runtime
+ * alignment, and "initiation defines structure" paradigm are exclusive intellectual
+ * property of Jonathan D Borgia.
+ *
+ * The createSignalStore and createLazySignalTree functions implement patented
+ * approaches to recursive type preservation that are strictly protected.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
 /**
  * Creates an equality function based on configuration.
  *
@@ -243,10 +402,12 @@ function createEqualityFn(useShallowComparison) {
     return useShallowComparison ? Object.is : equal;
 }
 /**
- * Core function to create a basic SignalTree.
+ * Core function to create a basic SignalTree with enhanced safety.
  * This provides the minimal functionality without advanced features.
  *
- * @template T - The state object type
+ * CRITICAL: Uses flexible typing - accepts ANY type T, not T
+ *
+ * @template T - The state object type (NO constraints - maximum flexibility)
  * @param obj - The initial state object
  * @param config - Configuration options for the tree
  * @returns A basic SignalTree with core functionality
@@ -255,7 +416,10 @@ function createEqualityFn(useShallowComparison) {
  * ```typescript
  * const tree = create({
  *   count: 0,
- *   user: { name: 'John', age: 30 }
+ *   user: { name: 'John', age: 30 },
+ *   items: [1, 2, 3],
+ *   metadata: new Map(),  // Any object type!
+ *   fn: () => 'hello'     // Even functions!
  * }, {
  *   useLazySignals: true,
  *   useShallowComparison: false
@@ -268,11 +432,11 @@ function createEqualityFn(useShallowComparison) {
  */
 function create(obj, config = {}) {
     const equalityFn = createEqualityFn(config.useShallowComparison ?? false);
-    const useLazy = config.useLazySignals ?? true; // Default to lazy loading
-    // Choose between lazy and eager signal creation
+    const useLazy = config.useLazySignals ?? true;
+    // Create signals using signal-store pattern for perfect type inference
     const signalState = useLazy
         ? createLazySignalTree(obj, equalityFn)
-        : createEagerSignalsFromObject(obj, equalityFn);
+        : createSignalStore(obj, equalityFn);
     const resultTree = {
         state: signalState,
         $: signalState, // $ points to the same state object
@@ -281,44 +445,94 @@ function create(obj, config = {}) {
     return resultTree;
 }
 /**
- * Creates eager signals from an object (non-lazy approach).
- * All signals are created immediately during initialization.
+ * Creates signals using signal-store pattern for perfect type inference.
+ * This is the key function that preserves exact type relationships recursively.
+ * Based on the original signal-store pattern that maintains type information.
  *
- * @template O - The object type to convert to signals
+ * @template T - The object type to process (preserves exact type structure)
  * @param obj - The object to convert to signals
  * @param equalityFn - Function to compare values for equality
- * @returns A deeply signalified version of the object
+ * @returns A deeply signalified version maintaining exact type structure
  *
  * @example
  * ```typescript
- * const eagerSignals = createEagerSignalsFromObject({
+ * const store = createSignalStore({
  *   user: { name: 'John', age: 30 },
  *   settings: { theme: 'dark' }
  * }, Object.is);
  *
- * // All signals are created immediately
- * eagerSignals.user.name.set('Jane');
- * console.log(eagerSignals.settings.theme()); // 'dark'
+ * // Perfect type inference maintained throughout
+ * store.user.name.set('Jane');
+ * console.log(store.settings.theme()); // 'dark'
  * ```
  */
-function createEagerSignalsFromObject(obj, equalityFn) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        const isObj = (v) => typeof v === 'object' && v !== null;
-        if (isObj(value) && !Array.isArray(value) && !isSignal(value)) {
-            // For nested objects, create nested signal structure directly
-            result[key] = createEagerSignalsFromObject(value, equalityFn);
-        }
-        else if (isSignal(value)) {
-            result[key] = value;
-        }
-        else {
-            result[key] = signal(value, {
-                equal: equalityFn,
-            });
+function createSignalStore(obj, equalityFn) {
+    // Input validation
+    if (obj === null || obj === undefined) {
+        throw new Error('Cannot create signal store from null or undefined');
+    }
+    if (typeof obj !== 'object') {
+        // For primitives, just return a signal
+        return signal(obj, { equal: equalityFn });
+    }
+    const store = {};
+    // Enhanced built-in object detection
+    const isBuiltInObject = (v) => {
+        if (v === null || v === undefined)
+            return false;
+        return (v instanceof Date ||
+            v instanceof RegExp ||
+            typeof v === 'function' ||
+            v instanceof Map ||
+            v instanceof Set ||
+            v instanceof WeakMap ||
+            v instanceof WeakSet ||
+            v instanceof ArrayBuffer ||
+            v instanceof DataView ||
+            v instanceof Error ||
+            v instanceof Promise ||
+            v instanceof URL ||
+            v instanceof URLSearchParams ||
+            v instanceof FormData ||
+            v instanceof Blob ||
+            (typeof File !== 'undefined' && v instanceof File));
+    };
+    // Safe object iteration
+    try {
+        for (const [key, value] of Object.entries(obj)) {
+            const isObj = (v) => typeof v === 'object' &&
+                v !== null &&
+                !Array.isArray(v) &&
+                !isBuiltInObject(v);
+            // Enhanced safety: Never double-wrap signals
+            if (isSignal(value)) {
+                store[key] = value;
+            }
+            else if (isObj(value)) {
+                // CRITICAL: Recursive call with type preservation
+                try {
+                    store[key] = createSignalStore(value, equalityFn);
+                }
+                catch (error) {
+                    console.warn(`Failed to create signal store for key "${key}":`, error);
+                    // Fallback: treat as primitive
+                    store[key] = signal(value, {
+                        equal: equalityFn,
+                    });
+                }
+            }
+            else {
+                // Create signal for primitives, arrays, and built-in objects
+                store[key] = signal(value, {
+                    equal: equalityFn,
+                });
+            }
         }
     }
-    return result;
+    catch (error) {
+        throw new Error(`Failed to create signal store: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    return store;
 }
 /**
  * Enhances a tree with basic functionality (unwrap, update, pipe).
@@ -363,6 +577,9 @@ function enhanceTree(tree) {
     tree.unwrap = () => {
         // Recursively unwrap with proper typing
         const unwrapObject = (obj) => {
+            if (typeof obj !== 'object' || obj === null) {
+                return obj;
+            }
             const result = {};
             for (const key in obj) {
                 const value = obj[key];
@@ -415,41 +632,92 @@ function enhanceTree(tree) {
      * );
      * ```
      */
+    /**
+     * Enhanced update with error handling and rollback capability
+     */
     tree.update = (updater) => {
-        const currentValue = tree.unwrap();
-        const partialObj = updater(currentValue);
-        // Recursively update with better typing
-        const updateObject = (target, updates) => {
-            for (const key in updates) {
-                if (!Object.prototype.hasOwnProperty.call(updates, key))
-                    continue;
-                const updateValue = updates[key];
-                const currentSignalOrState = target[key];
-                if (isSignal(currentSignalOrState)) {
-                    // Direct signal update
-                    currentSignalOrState.set(updateValue);
+        const originalState = new Map();
+        try {
+            const currentValue = tree.unwrap();
+            const partialObj = updater(currentValue);
+            if (!partialObj || typeof partialObj !== 'object') {
+                throw new Error('Updater must return an object');
+            }
+            // Recursively update with better error handling and rollback
+            const updateObject = (target, updates, path = '') => {
+                for (const key in updates) {
+                    if (!Object.prototype.hasOwnProperty.call(updates, key))
+                        continue;
+                    const updateValue = updates[key];
+                    const currentPath = path ? `${path}.${key}` : key;
+                    const currentSignalOrState = target[key];
+                    try {
+                        if (isSignal(currentSignalOrState)) {
+                            // Store original value for potential rollback
+                            const originalValue = currentSignalOrState();
+                            originalState.set(currentPath, originalValue);
+                            // Direct signal update
+                            currentSignalOrState.set(updateValue);
+                        }
+                        else if (typeof updateValue === 'object' &&
+                            updateValue !== null &&
+                            !Array.isArray(updateValue) &&
+                            typeof currentSignalOrState === 'object' &&
+                            currentSignalOrState !== null &&
+                            !isSignal(currentSignalOrState)) {
+                            // Nested object - recurse
+                            updateObject(currentSignalOrState, updateValue, currentPath);
+                        }
+                        else if (currentSignalOrState === undefined) {
+                            console.warn(`Cannot update non-existent path: ${currentPath}`);
+                        }
+                    }
+                    catch (error) {
+                        console.error(`Failed to update path "${currentPath}":`, error);
+                        // Continue with other updates rather than failing completely
+                    }
                 }
-                else if (typeof updateValue === 'object' &&
-                    updateValue !== null &&
-                    !Array.isArray(updateValue) &&
-                    typeof currentSignalOrState === 'object' &&
-                    currentSignalOrState !== null) {
-                    // Nested object - recurse
-                    updateObject(currentSignalOrState, updateValue);
+            };
+            updateObject(tree.state, partialObj);
+        }
+        catch (error) {
+            // Rollback on error
+            console.error('Update failed, attempting rollback:', error);
+            try {
+                // Attempt to restore original values
+                for (const [path, originalValue] of originalState.entries()) {
+                    const pathParts = path.split('.');
+                    let current = tree.state;
+                    for (let i = 0; i < pathParts.length - 1; i++) {
+                        current = current[pathParts[i]];
+                        if (!current)
+                            break;
+                    }
+                    if (current &&
+                        isSignal(current[pathParts[pathParts.length - 1]])) {
+                        const signal = current[pathParts[pathParts.length - 1]];
+                        signal.set(originalValue);
+                    }
                 }
             }
-        };
-        updateObject(tree.state, partialObj);
+            catch (rollbackError) {
+                console.error('Rollback failed:', rollbackError);
+            }
+            throw error;
+        }
     };
     // Pipe implementation for function composition with improved type safety
-    tree.pipe = ((...fns // eslint-disable-line @typescript-eslint/no-explicit-any
-    ) => {
-        // eslint-disable-line @typescript-eslint/no-explicit-any
+    tree.pipe = ((...fns) => {
         if (fns.length === 0) {
             return tree;
         }
-        // Type-safe reduce - the return type is determined by the overload signature
-        return fns.reduce((acc, fn) => fn(acc), tree);
+        // Type-safe reduce with proper function composition
+        return fns.reduce((acc, fn) => {
+            if (typeof fn !== 'function') {
+                throw new Error('All pipe arguments must be functions');
+            }
+            return fn(acc);
+        }, tree);
     });
     // Stub implementations for advanced features (will log warnings)
     tree.batchUpdate = (updater) => {
@@ -509,6 +777,11 @@ function enhanceTree(tree) {
         return 0;
     };
     tree.destroy = () => {
+        // Clean up lazy signal proxies if they exist
+        const state = tree.state;
+        if (state && typeof state === 'object' && '__cleanup__' in state) {
+            state.__cleanup__();
+        }
         // Basic cleanup for non-enhanced trees
         console.log('[MEMORY-CLEANUP] Basic tree destroyed');
     };
@@ -560,9 +833,6 @@ function enhanceTree(tree) {
     };
     return tree;
 }
-/**
- * Implementation of the signalTree factory function.
- */
 function signalTree(obj, configOrPreset) {
     // Handle preset strings
     if (typeof configOrPreset === 'string') {
@@ -575,6 +845,20 @@ function signalTree(obj, configOrPreset) {
     return create(obj, config);
 }
 
+/**
+ * SignalTree Core Types - Recursive Typing System
+ *
+ * COPYRIGHT NOTICE:
+ * This file contains proprietary recursive typing innovations protected under
+ * the SignalTree license. The DeepSignalify<T> recursive type system and
+ * related implementations are exclusive intellectual property of Jonathan D Borgia.
+ *
+ * Unauthorized extraction, copying, or reimplementation of these recursive typing
+ * concepts is strictly prohibited and constitutes copyright infringement.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
+
 /**
  * Generated bundle index. Do not edit.
  */