@signaltree/core 4.0.1 → 4.0.3

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

@@ -1,363 +0,0 @@
-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

@@ -1,319 +0,0 @@
-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