@signaltree/core 3.0.2 → 4.0.1

package/dist/enhancers/devtools/index.d.ts

@@ -0,0 +1,363 @@
+import { WritableSignal, Signal } from '@angular/core';
+
+/**
+ * SignalTree Core Types v2.0.2
+ * MIT License - Copyright (c) 2025 Jonathan D Borgia
+ */
+/**
+ * Helper type preventing ambiguity when a node itself stores a function value.
+ * In that case direct callable set(fn) would clash with the update(fn) signature.
+ * We exclude raw function values from the direct-set overload so users must use .set(fn)
+ * (after transform) instead of callable form, while updater form still works.
+ */
+type NotFn<T> = T extends (...args: unknown[]) => unknown ? never : T;
+/**
+ * Augment Angular's WritableSignal to support callable syntax for DX.
+ * This is purely TypeScript-level - the transform converts these calls to .set/.update
+ */
+declare module '@angular/core' {
+    interface WritableSignal<T> {
+        (value: NotFn<T>): void;
+        (updater: (current: T) => T): void;
+    }
+}
+/**
+ * Built-in object types that should be treated as primitive values
+ * (Keep this list in sync with runtime isBuiltInObject)
+ */
+type BuiltInObject = Date | RegExp | ((...args: unknown[]) => unknown) | Map<unknown, unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object> | ArrayBuffer | DataView | Error | Promise<unknown> | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array | URL | URLSearchParams | FormData | Blob | File | Headers | Request | Response | AbortController | AbortSignal;
+/**
+ * Node accessor interface - unified API for get/set/update via function calls.
+ * Overloads:
+ *  (): T                     - getter
+ *  (value: NotFn<T>): void   - direct set (blocked when T is itself a function)
+ *  (updater: (T)=>T): void   - functional update
+ */
+interface NodeAccessor<T> {
+    (): T;
+    (value: T): void;
+    (updater: (current: T) => T): void;
+}
+/**
+ * Signalified node with callable interface
+ */
+type AccessibleNode<T> = NodeAccessor<T> & TreeNode<T>;
+/**
+ * Deep signalification type - converts object properties to signals recursively
+ * - Leaves (primitives, arrays, functions, built-ins): Raw Angular WritableSignal<T>
+ * - Nested objects: NodeAccessor<T> (callable) + recursive TreeNode<T> properties
+ */
+type CallableWritableSignal<T> = WritableSignal<T> & {
+    (value: NotFn<T>): void;
+    (updater: (current: T) => T): void;
+};
+type TreeNode<T> = {
+    [K in keyof T]: T[K] extends readonly unknown[] ? CallableWritableSignal<T[K]> : T[K] extends object ? T[K] extends Signal<unknown> ? T[K] : T[K] extends BuiltInObject ? CallableWritableSignal<T[K]> : T[K] extends (...args: unknown[]) => unknown ? CallableWritableSignal<T[K]> : AccessibleNode<T[K]> : CallableWritableSignal<T[K]>;
+};
+/** Enhancer metadata for optional auto-ordering */
+interface EnhancerMeta {
+    name?: string;
+    requires?: string[];
+    provides?: string[];
+}
+/** Enhancer function that may carry metadata */
+type Enhancer<Input = unknown, Output = unknown> = (input: Input) => Output;
+/** Enhancer with optional metadata attached */
+type EnhancerWithMeta<Input = unknown, Output = unknown> = Enhancer<Input, Output> & {
+    metadata?: EnhancerMeta;
+};
+/**
+ * Simplified overload set for .with() method
+ * Reduced from 20+ complex overloads to basic patterns that TypeScript can infer.
+ * For complex enhancer chains, use applyEnhancer() helper or type assertions.
+ */
+interface WithMethod<T> {
+    (): SignalTree<T>;
+    <O>(enhancer: (input: SignalTree<T>) => O): O;
+    <O1, O2>(e1: (input: SignalTree<T>) => O1, e2: (input: O1) => O2): O2;
+    <O1, O2, O3>(e1: (input: SignalTree<T>) => O1, e2: (input: O1) => O2, e3: (input: O2) => O3): O3;
+    <O>(enhancer: EnhancerWithMeta<SignalTree<T>, O>): O;
+    <O1, O2>(e1: EnhancerWithMeta<SignalTree<T>, O1>, e2: EnhancerWithMeta<O1, O2>): O2;
+    <O1, O2, O3>(e1: EnhancerWithMeta<SignalTree<T>, O1>, e2: EnhancerWithMeta<O1, O2>, e3: EnhancerWithMeta<O2, O3>): O3;
+}
+/**
+ * Main SignalTree type with all methods
+ */
+type SignalTree<T> = NodeAccessor<T> & {
+    /** The reactive state object */
+    state: TreeNode<T>;
+    /** Shorthand alias for state */
+    $: TreeNode<T>;
+    /** Core methods */
+    with: WithMethod<T>;
+    destroy(): void;
+    /**
+     * Dispose of the signal tree and clean up memory resources.
+     * Only available when using lazy signals (useLazySignals: true).
+     *
+     * This method:
+     * - Clears the memory manager cache (releases WeakRef references)
+     * - Calls the cleanup function on the lazy proxy
+     * - Allows garbage collection of unused signals
+     *
+     * @example
+     * ```typescript
+     * const tree = signalTree({ users: largeUserList }, { useLazySignals: true });
+     * // ... use tree
+     * tree.dispose(); // Clean up when done
+     * ```
+     */
+    dispose?(): void;
+    /** Enhanced functionality */
+    effect(fn: (tree: T) => void): void;
+    subscribe(fn: (tree: T) => void): () => void;
+    batch(updater: (tree: T) => void): void;
+    batchUpdate(updater: (current: T) => Partial<T>): void;
+    memoize<R>(fn: (tree: T) => R, cacheKey?: string): Signal<R>;
+    memoizedUpdate(updater: (current: T) => Partial<T>, cacheKey?: string): void;
+    clearMemoCache(key?: string): void;
+    getCacheStats(): {
+        size: number;
+        hitRate: number;
+        totalHits: number;
+        totalMisses: number;
+        keys: string[];
+    };
+    /** Performance methods */
+    optimize(): void;
+    clearCache(): void;
+    invalidatePattern(pattern: string): number;
+    /**
+     * Optimized update using diff-based patching and batching.
+     * Only updates signals that actually changed, providing significant
+     * performance improvements for large trees and partial updates.
+     *
+     * @param updates - Partial updates to apply
+     * @param options - Update options (batching, equality, etc.)
+     * @returns Update result with performance metrics
+     *
+     * @example
+     * ```typescript
+     * const tree = signalTree({ users: largeUserList });
+     *
+     * // Only updates what changed
+     * const result = tree.updateOptimized({
+     *   users: { 0: { name: 'Updated' } }
+     * });
+     *
+     * console.log(result.changedPaths); // ['users.0.name']
+     * console.log(result.duration); // ~2ms
+     * ```
+     */
+    updateOptimized?(updates: Partial<T>, options?: {
+        batch?: boolean;
+        batchSize?: number;
+        maxDepth?: number;
+        ignoreArrayOrder?: boolean;
+        equalityFn?: (a: unknown, b: unknown) => boolean;
+    }): {
+        changed: boolean;
+        duration: number;
+        changedPaths: string[];
+        stats?: {
+            totalPaths: number;
+            optimizedPaths: number;
+            batchedUpdates: number;
+        };
+    };
+    getMetrics(): PerformanceMetrics;
+    /** Middleware */
+    addTap(middleware: Middleware<T>): void;
+    removeTap(id: string): void;
+    /** Entity helpers */
+    entities<E extends {
+        id: string | number;
+    }>(entityKey?: keyof T): EntityHelpers<E>;
+    /** Async actions */
+    asyncAction<TInput, TResult>(operation: (input: TInput) => Promise<TResult>, config?: AsyncActionConfig<T, TResult>): AsyncAction<TInput, TResult>;
+    /** Time travel */
+    undo(): void;
+    redo(): void;
+    getHistory(): TimeTravelEntry<T>[];
+    resetHistory(): void;
+    jumpTo?: (index: number) => void;
+    canUndo?: () => boolean;
+    canRedo?: () => boolean;
+    getCurrentIndex?: () => number;
+    /** Index signature for enhancer compatibility */
+    [key: string]: unknown;
+};
+interface Middleware<T> {
+    id: string;
+    before?: (action: string, payload: unknown, state: T) => boolean;
+    after?: (action: string, payload: unknown, state: T, newState: T) => void;
+}
+interface PerformanceMetrics {
+    updates: number;
+    computations: number;
+    cacheHits: number;
+    cacheMisses: number;
+    averageUpdateTime: number;
+}
+interface EntityHelpers<E extends {
+    id: string | number;
+}> {
+    add(entity: E): void;
+    update(id: E['id'], updates: Partial<E>): void;
+    remove(id: E['id']): void;
+    upsert(entity: E): void;
+    selectById(id: E['id']): Signal<E | undefined>;
+    selectBy(predicate: (entity: E) => boolean): Signal<E[]>;
+    selectIds(): Signal<Array<string | number>>;
+    selectAll(): Signal<E[]>;
+    selectTotal(): Signal<number>;
+    clear(): void;
+}
+interface AsyncActionConfig<T, TResult> {
+    onStart?: (state: T) => Partial<T>;
+    onSuccess?: (result: TResult, state: T) => Partial<T>;
+    onError?: (error: Error, state: T) => Partial<T>;
+    onComplete?: (state: T) => Partial<T>;
+}
+interface AsyncAction<TInput, TResult> {
+    execute(input: TInput): Promise<TResult>;
+    pending: Signal<boolean>;
+    error: Signal<Error | null>;
+    result: Signal<TResult | null>;
+}
+interface TimeTravelEntry<T> {
+    action: string;
+    timestamp: number;
+    state: T;
+    payload?: unknown;
+}
+
+/**
+ * Module metadata for tracking in the composition chain
+ */
+interface ModuleMetadata {
+    name: string;
+    methods: string[];
+    addedAt: Date;
+    lastActivity: Date;
+    operationCount: number;
+    averageExecutionTime: number;
+    errorCount: number;
+}
+/**
+ * Performance metrics optimized for modular composition
+ */
+interface ModularPerformanceMetrics {
+    /** Total state updates across all modules */
+    totalUpdates: number;
+    /** Updates per module in the composition chain */
+    moduleUpdates: Record<string, number>;
+    /** Average execution time per module */
+    modulePerformance: Record<string, number>;
+    /** Current composition chain order */
+    compositionChain: string[];
+    /** Signal count after each module enhancement */
+    signalGrowth: Record<string, number>;
+    /** Memory impact per module */
+    memoryDelta: Record<string, number>;
+    /** Cache efficiency per module */
+    moduleCacheStats: Record<string, {
+        hits: number;
+        misses: number;
+    }>;
+}
+/**
+ * Module activity tracker for debugging
+ */
+interface ModuleActivityTracker {
+    /** Track when a module method is called */
+    trackMethodCall: (module: string, method: string, duration: number) => void;
+    /** Track module errors */
+    trackError: (module: string, error: Error, context?: string) => void;
+    /** Get activity summary for a module */
+    getModuleActivity: (module: string) => ModuleMetadata | undefined;
+    /** Get all tracked modules */
+    getAllModules: () => ModuleMetadata[];
+}
+/**
+ * Composition-aware DevTools logger
+ */
+interface CompositionLogger {
+    /** Log module composition events */
+    logComposition: (modules: string[], action: 'with' | 'enhance') => void;
+    /** Log method execution with module context */
+    logMethodExecution: (module: string, method: string, args: unknown[], result: unknown) => void;
+    /** Log state changes with composition context */
+    logStateChange: (module: string, path: string, oldValue: unknown, newValue: unknown) => void;
+    /** Log performance warnings for specific modules */
+    logPerformanceWarning: (module: string, operation: string, duration: number, threshold: number) => void;
+    /** Export logs for analysis */
+    exportLogs: () => Array<{
+        timestamp: Date;
+        module: string;
+        type: 'composition' | 'method' | 'state' | 'performance';
+        data: unknown;
+    }>;
+}
+/**
+ * DevTools interface specifically for modular SignalTree
+ */
+interface ModularDevToolsInterface<T = unknown> {
+    /** Activity tracker for all modules */
+    activityTracker: ModuleActivityTracker;
+    /** Composition-aware logger */
+    logger: CompositionLogger;
+    /** Real-time performance metrics */
+    metrics: Signal<ModularPerformanceMetrics>;
+    /** Track module composition */
+    trackComposition: (modules: string[]) => void;
+    /** Start profiling a specific module */
+    startModuleProfiling: (module: string) => string;
+    /** End module profiling */
+    endModuleProfiling: (profileId: string) => void;
+    /** Connect to browser DevTools */
+    connectDevTools: (treeName: string) => void;
+    /** Export complete debug session */
+    exportDebugSession: () => {
+        metrics: ModularPerformanceMetrics;
+        modules: ModuleMetadata[];
+        logs: Array<unknown>;
+        compositionHistory: Array<{
+            timestamp: Date;
+            chain: string[];
+        }>;
+    };
+}
+/**
+ * Enhances a SignalTree with modular composition-aware DevTools
+ */
+declare function withDevTools<T>(config?: {
+    enabled?: boolean;
+    treeName?: string;
+    enableBrowserDevTools?: boolean;
+    enableLogging?: boolean;
+    performanceThreshold?: number;
+}): (tree: SignalTree<T>) => SignalTree<T> & {
+    __devTools: ModularDevToolsInterface<T>;
+};
+/**
+ * Simple devtools for development
+ */
+declare function enableDevTools<T>(treeName?: string): (tree: SignalTree<T>) => SignalTree<T> & {
+    __devTools: ModularDevToolsInterface<T>;
+};
+/**
+ * Full-featured devtools for intensive debugging
+ */
+declare function withFullDevTools<T>(treeName?: string): (tree: SignalTree<T>) => SignalTree<T> & {
+    __devTools: ModularDevToolsInterface<T>;
+};
+/**
+ * Lightweight devtools for production
+ */
+declare function withProductionDevTools<T>(): (tree: SignalTree<T>) => SignalTree<T> & {
+    __devTools: ModularDevToolsInterface<T>;
+};
+
+export { enableDevTools, withDevTools, withFullDevTools, withProductionDevTools };
+export type { CompositionLogger, ModularDevToolsInterface, ModularPerformanceMetrics, ModuleActivityTracker, ModuleMetadata };

package/dist/enhancers/devtools/index.js

@@ -0,0 +1,319 @@
+import { signal } from '@angular/core';
+
+/**
+ * Creates an activity tracker for monitoring module behavior
+ */
+function createActivityTracker() {
+    const modules = new Map();
+    return {
+        trackMethodCall: (module, method, duration) => {
+            const existing = modules.get(module);
+            if (existing) {
+                existing.lastActivity = new Date();
+                existing.operationCount++;
+                // Update rolling average
+                existing.averageExecutionTime =
+                    (existing.averageExecutionTime * (existing.operationCount - 1) +
+                        duration) /
+                        existing.operationCount;
+            }
+            else {
+                modules.set(module, {
+                    name: module,
+                    methods: [method],
+                    addedAt: new Date(),
+                    lastActivity: new Date(),
+                    operationCount: 1,
+                    averageExecutionTime: duration,
+                    errorCount: 0,
+                });
+            }
+        },
+        trackError: (module, error, context) => {
+            const existing = modules.get(module);
+            if (existing) {
+                existing.errorCount++;
+            }
+            console.error(`❌ [${module}] Error${context ? ` in ${context}` : ''}:`, error);
+        },
+        getModuleActivity: (module) => modules.get(module),
+        getAllModules: () => Array.from(modules.values()),
+    };
+}
+/**
+ * Creates a composition-aware logger for debugging
+ */
+function createCompositionLogger() {
+    const logs = [];
+    const addLog = (module, type, data) => {
+        logs.push({ timestamp: new Date(), module, type, data });
+        // Keep only last 1000 logs to prevent memory issues
+        if (logs.length > 1000) {
+            logs.splice(0, logs.length - 1000);
+        }
+    };
+    return {
+        logComposition: (modules, action) => {
+            addLog('core', 'composition', { modules, action });
+            console.log(`🔗 Composition ${action}:`, modules.join(' → '));
+        },
+        logMethodExecution: (module, method, args, result) => {
+            addLog(module, 'method', { method, args, result });
+            console.debug(`🔧 [${module}] ${method}`, { args, result });
+        },
+        logStateChange: (module, path, oldValue, newValue) => {
+            addLog(module, 'state', { path, oldValue, newValue });
+            console.debug(`📝 [${module}] State change at ${path}:`, {
+                from: oldValue,
+                to: newValue,
+            });
+        },
+        logPerformanceWarning: (module, operation, duration, threshold) => {
+            addLog(module, 'performance', { operation, duration, threshold });
+            console.warn(`⚠️ [${module}] Slow ${operation}: ${duration.toFixed(2)}ms (threshold: ${threshold}ms)`);
+        },
+        exportLogs: () => [...logs],
+    };
+}
+/**
+ * Creates real-time performance metrics for modular architecture
+ */
+function createModularMetrics() {
+    const metricsSignal = signal({
+        totalUpdates: 0,
+        moduleUpdates: {},
+        modulePerformance: {},
+        compositionChain: [],
+        signalGrowth: {},
+        memoryDelta: {},
+        moduleCacheStats: {},
+    });
+    return {
+        signal: metricsSignal.asReadonly(),
+        updateMetrics: (updates) => {
+            metricsSignal.update((current) => ({ ...current, ...updates }));
+        },
+        trackModuleUpdate: (module, duration) => {
+            metricsSignal.update((current) => ({
+                ...current,
+                totalUpdates: current.totalUpdates + 1,
+                moduleUpdates: {
+                    ...current.moduleUpdates,
+                    [module]: (current.moduleUpdates[module] || 0) + 1,
+                },
+                modulePerformance: {
+                    ...current.modulePerformance,
+                    [module]: duration,
+                },
+            }));
+        },
+    };
+}
+/**
+ * Enhances a SignalTree with modular composition-aware DevTools
+ */
+function withDevTools(config = {}) {
+    const { enabled = true, treeName = 'ModularSignalTree', enableBrowserDevTools = true, enableLogging = true, performanceThreshold = 16, } = config;
+    return (tree) => {
+        if (!enabled) {
+            // Return minimal devtools interface when disabled
+            const createNoopInterface = () => ({
+                activityTracker: {
+                    trackMethodCall: () => undefined,
+                    trackError: () => undefined,
+                    getModuleActivity: () => undefined,
+                    getAllModules: () => [],
+                },
+                logger: {
+                    logComposition: () => undefined,
+                    logMethodExecution: () => undefined,
+                    logStateChange: () => undefined,
+                    logPerformanceWarning: () => undefined,
+                    exportLogs: () => [],
+                },
+                metrics: signal({
+                    totalUpdates: 0,
+                    moduleUpdates: {},
+                    modulePerformance: {},
+                    compositionChain: [],
+                    signalGrowth: {},
+                    memoryDelta: {},
+                    moduleCacheStats: {},
+                }).asReadonly(),
+                trackComposition: () => undefined,
+                startModuleProfiling: () => '',
+                endModuleProfiling: () => undefined,
+                connectDevTools: () => undefined,
+                exportDebugSession: () => ({
+                    metrics: {
+                        totalUpdates: 0,
+                        moduleUpdates: {},
+                        modulePerformance: {},
+                        compositionChain: [],
+                        signalGrowth: {},
+                        memoryDelta: {},
+                        moduleCacheStats: {},
+                    },
+                    modules: [],
+                    logs: [],
+                    compositionHistory: [],
+                }),
+            });
+            return Object.assign(tree, { __devTools: createNoopInterface() });
+        }
+        const activityTracker = createActivityTracker();
+        const logger = enableLogging
+            ? createCompositionLogger()
+            : {
+                logComposition: () => undefined,
+                logMethodExecution: () => undefined,
+                logStateChange: () => undefined,
+                logPerformanceWarning: () => undefined,
+                exportLogs: () => [],
+            };
+        const metrics = createModularMetrics();
+        // Track composition history
+        const compositionHistory = [];
+        // Profiling state
+        const activeProfiles = new Map();
+        // Browser DevTools integration
+        let browserDevTools = null;
+        if (enableBrowserDevTools &&
+            typeof window !== 'undefined' &&
+            '__REDUX_DEVTOOLS_EXTENSION__' in window) {
+            const devToolsExt = window['__REDUX_DEVTOOLS_EXTENSION__'];
+            const connection = devToolsExt.connect({
+                name: treeName,
+                features: { dispatch: true, jump: true, skip: true },
+            });
+            browserDevTools = { send: connection.send };
+        }
+        // Store the original callable tree function
+        const originalTreeCall = tree.bind(tree);
+        // Create enhanced tree function that includes devtools tracking
+        const enhancedTree = function (...args) {
+            if (args.length === 0) {
+                // Get operation - call original directly (no tracking needed for reads)
+                return originalTreeCall();
+            }
+            else {
+                // Set or update operation - track with devtools
+                const startTime = performance.now();
+                // Execute the actual update using the original callable interface
+                let result;
+                if (args.length === 1) {
+                    const arg = args[0];
+                    if (typeof arg === 'function') {
+                        result = originalTreeCall(arg);
+                    }
+                    else {
+                        result = originalTreeCall(arg);
+                    }
+                }
+                const duration = performance.now() - startTime;
+                const newState = originalTreeCall();
+                // Track performance
+                metrics.trackModuleUpdate('core', duration);
+                if (duration > performanceThreshold) {
+                    logger.logPerformanceWarning('core', 'update', duration, performanceThreshold);
+                }
+                // Send to browser DevTools
+                if (browserDevTools) {
+                    browserDevTools.send('UPDATE', newState);
+                }
+                return result;
+            }
+        };
+        // Copy all properties and methods from original tree
+        Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+        Object.assign(enhancedTree, tree);
+        // Ensure state and $ properties are preserved
+        if ('state' in tree) {
+            Object.defineProperty(enhancedTree, 'state', {
+                value: tree.state,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // Ensure $ alias is preserved
+        if ('$' in tree) {
+            Object.defineProperty(enhancedTree, '$', {
+                value: tree['$'],
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        const devToolsInterface = {
+            activityTracker,
+            logger,
+            metrics: metrics.signal,
+            trackComposition: (modules) => {
+                compositionHistory.push({ timestamp: new Date(), chain: [...modules] });
+                metrics.updateMetrics({ compositionChain: modules });
+                logger.logComposition(modules, 'with');
+            },
+            startModuleProfiling: (module) => {
+                const profileId = `${module}_${Date.now()}`;
+                activeProfiles.set(profileId, {
+                    module,
+                    operation: 'profile',
+                    startTime: performance.now(),
+                });
+                return profileId;
+            },
+            endModuleProfiling: (profileId) => {
+                const profile = activeProfiles.get(profileId);
+                if (profile) {
+                    const duration = performance.now() - profile.startTime;
+                    activityTracker.trackMethodCall(profile.module, profile.operation, duration);
+                    activeProfiles.delete(profileId);
+                }
+            },
+            connectDevTools: (name) => {
+                if (browserDevTools) {
+                    browserDevTools.send('@@INIT', originalTreeCall());
+                    console.log(`🔗 Connected to Redux DevTools as "${name}"`);
+                }
+            },
+            exportDebugSession: () => ({
+                metrics: metrics.signal(),
+                modules: activityTracker.getAllModules(),
+                logs: logger.exportLogs(),
+                compositionHistory: [...compositionHistory],
+            }),
+        };
+        return Object.assign(enhancedTree, { __devTools: devToolsInterface });
+    };
+}
+/**
+ * Simple devtools for development
+ */
+function enableDevTools(treeName = 'SignalTree') {
+    return withDevTools({ treeName, enabled: true });
+}
+/**
+ * Full-featured devtools for intensive debugging
+ */
+function withFullDevTools(treeName = 'SignalTree') {
+    return withDevTools({
+        treeName,
+        enabled: true,
+        enableBrowserDevTools: true,
+        enableLogging: true,
+        performanceThreshold: 10,
+    });
+}
+/**
+ * Lightweight devtools for production
+ */
+function withProductionDevTools() {
+    return withDevTools({
+        enabled: true,
+        enableBrowserDevTools: false,
+        enableLogging: false,
+        performanceThreshold: 50,
+    });
+}
+
+export { enableDevTools, withDevTools, withFullDevTools, withProductionDevTools };
+//# sourceMappingURL=index.js.map