@signaltree/core 3.0.1 → 3.1.0

package/src/enhancers/devtools/lib/devtools.js

@@ -0,0 +1,278 @@
+import { signal } from '@angular/core';
+function createActivityTracker() {
+    const modules = new Map();
+    return {
+        trackMethodCall: (module, method, duration) => {
+            const existing = modules.get(module);
+            if (existing) {
+                existing.lastActivity = new Date();
+                existing.operationCount++;
+                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()),
+    };
+}
+function createCompositionLogger() {
+    const logs = [];
+    const addLog = (module, type, data) => {
+        logs.push({ timestamp: new Date(), module, type, data });
+        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],
+    };
+}
+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,
+                },
+            }));
+        },
+    };
+}
+export function withDevTools(config = {}) {
+    const { enabled = true, treeName = 'ModularSignalTree', enableBrowserDevTools = true, enableLogging = true, performanceThreshold = 16, } = config;
+    return (tree) => {
+        if (!enabled) {
+            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();
+        const compositionHistory = [];
+        const activeProfiles = new Map();
+        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 };
+        }
+        const originalTreeCall = tree.bind(tree);
+        const enhancedTree = function (...args) {
+            if (args.length === 0) {
+                return originalTreeCall();
+            }
+            else {
+                const startTime = performance.now();
+                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();
+                metrics.trackModuleUpdate('core', duration);
+                if (duration > performanceThreshold) {
+                    logger.logPerformanceWarning('core', 'update', duration, performanceThreshold);
+                }
+                if (browserDevTools) {
+                    browserDevTools.send('UPDATE', newState);
+                }
+                return result;
+            }
+        };
+        Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+        Object.assign(enhancedTree, tree);
+        if ('state' in tree) {
+            Object.defineProperty(enhancedTree, 'state', {
+                value: tree.state,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        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 });
+    };
+}
+export function enableDevTools(treeName = 'SignalTree') {
+    return withDevTools({ treeName, enabled: true });
+}
+export function withFullDevTools(treeName = 'SignalTree') {
+    return withDevTools({
+        treeName,
+        enabled: true,
+        enableBrowserDevTools: true,
+        enableLogging: true,
+        performanceThreshold: 10,
+    });
+}
+export function withProductionDevTools() {
+    return withDevTools({
+        enabled: true,
+        enableBrowserDevTools: false,
+        enableLogging: false,
+        performanceThreshold: 50,
+    });
+}

package/src/enhancers/devtools/test-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/src/enhancers/devtools/test-setup.js

@@ -0,0 +1,5 @@
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+setupZoneTestEnv({
+    errorOnUnknownElements: true,
+    errorOnUnknownProperties: true,
+});

package/src/enhancers/entities/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/entities';

package/src/enhancers/entities/index.js

@@ -0,0 +1 @@
+export * from './lib/entities';

package/src/enhancers/entities/jest.config.d.ts

@@ -0,0 +1,15 @@
+declare const _default: {
+    displayName: string;
+    preset: string;
+    setupFilesAfterEnv: string[];
+    coverageDirectory: string;
+    transform: {
+        '^.+\\.(ts|mjs|js|html)$': (string | {
+            tsconfig: string;
+            stringifyContentPathRegex: string;
+        })[];
+    };
+    transformIgnorePatterns: string[];
+    snapshotSerializers: string[];
+};
+export default _default;

package/src/enhancers/entities/jest.config.js

@@ -0,0 +1,21 @@
+export default {
+    displayName: 'entities',
+    preset: '../../../jest.preset.js',
+    setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+    coverageDirectory: '../../../coverage/packages/core/enhancers/entities',
+    transform: {
+        '^.+\\.(ts|mjs|js|html)$': [
+            'jest-preset-angular',
+            {
+                tsconfig: '<rootDir>/tsconfig.spec.json',
+                stringifyContentPathRegex: '\\.(html|svg)$',
+            },
+        ],
+    },
+    transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+    snapshotSerializers: [
+        'jest-preset-angular/build/serializers/no-ng-attributes',
+        'jest-preset-angular/build/serializers/ng-snapshot',
+        'jest-preset-angular/build/serializers/html-comment',
+    ],
+};

package/src/enhancers/entities/lib/entities.d.ts

@@ -0,0 +1,22 @@
+import type { SignalTree, EntityHelpers } from '../../../lib/types';
+interface EntityConfig {
+    enabled?: boolean;
+    trackChanges?: boolean;
+    validateIds?: boolean;
+}
+export declare function withEntities(config?: EntityConfig): <T>(tree: SignalTree<T>) => SignalTree<T> & {
+    entities<E extends {
+        id: string | number;
+    }>(entityKey: keyof T): EntityHelpers<E>;
+};
+export declare function enableEntities(): <T>(tree: SignalTree<T>) => SignalTree<T> & {
+    entities<E extends {
+        id: string | number;
+    }>(entityKey: keyof T): EntityHelpers<E>;
+};
+export declare function withHighPerformanceEntities(): <T>(tree: SignalTree<T>) => SignalTree<T> & {
+    entities<E extends {
+        id: string | number;
+    }>(entityKey: keyof T): EntityHelpers<E>;
+};
+export {};

package/src/enhancers/entities/lib/entities.js

@@ -0,0 +1,110 @@
+import { computed } from '@angular/core';
+import { isAnySignal, isNodeAccessor } from '../../../lib/utils';
+function createEntityHelpers(tree, entityKey) {
+    const getEntitySignal = () => {
+        const stateProperty = tree.state[entityKey];
+        if (!stateProperty) {
+            throw new Error(`Entity key '${String(entityKey)}' does not exist in the state`);
+        }
+        if (!isAnySignal(stateProperty)) {
+            throw new Error(`Entity key '${String(entityKey)}' is not a signal. This should not happen with SignalTree.`);
+        }
+        const signal = stateProperty;
+        const value = signal();
+        if (!Array.isArray(value)) {
+            throw new Error(`Entity key '${String(entityKey)}' does not contain an array. Current type: ${typeof value}`);
+        }
+        return signal;
+    };
+    const setSignalValue = (signal, value) => {
+        if (isNodeAccessor(signal)) {
+            signal(value);
+        }
+        else {
+            signal.set(value);
+        }
+    };
+    return {
+        add: (entity) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            if (currentEntities.some((e) => e.id === entity.id)) {
+                throw new Error(`Entity with id '${entity.id}' already exists`);
+            }
+            setSignalValue(entitySignal, [...currentEntities, entity]);
+        },
+        update: (id, updates) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const updatedEntities = currentEntities.map((entity) => entity.id === id ? { ...entity, ...updates } : entity);
+            setSignalValue(entitySignal, updatedEntities);
+        },
+        remove: (id) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const filteredEntities = currentEntities.filter((entity) => entity.id !== id);
+            setSignalValue(entitySignal, filteredEntities);
+        },
+        upsert: (entity) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const index = currentEntities.findIndex((e) => e.id === entity.id);
+            if (index >= 0) {
+                const updatedEntities = [...currentEntities];
+                updatedEntities[index] = entity;
+                setSignalValue(entitySignal, updatedEntities);
+            }
+            else {
+                setSignalValue(entitySignal, [...currentEntities, entity]);
+            }
+        },
+        selectById: (id) => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().find((entity) => entity.id === id));
+        },
+        selectBy: (predicate) => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().filter(predicate));
+        },
+        selectIds: () => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().map((entity) => entity.id));
+        },
+        selectAll: () => {
+            const entitySignal = getEntitySignal();
+            return entitySignal;
+        },
+        selectTotal: () => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().length);
+        },
+        clear: () => {
+            const entitySignal = getEntitySignal();
+            setSignalValue(entitySignal, []);
+        },
+    };
+}
+export function withEntities(config = {}) {
+    const { enabled = true } = config;
+    return function enhanceWithEntities(tree) {
+        if (!enabled) {
+            return tree;
+        }
+        const enhancedTree = Object.assign(tree, {
+            entities(entityKey) {
+                return createEntityHelpers(tree, entityKey);
+            },
+        });
+        return enhancedTree;
+    };
+}
+export function enableEntities() {
+    return withEntities({ enabled: true });
+}
+export function withHighPerformanceEntities() {
+    return withEntities({
+        enabled: true,
+        trackChanges: true,
+        validateIds: true,
+    });
+}

package/src/enhancers/entities/test-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/src/enhancers/entities/test-setup.js

@@ -0,0 +1,5 @@
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+setupZoneTestEnv({
+    errorOnUnknownElements: true,
+    errorOnUnknownProperties: true,
+});

package/src/enhancers/index.d.ts

@@ -0,0 +1,3 @@
+import type { EnhancerMeta, EnhancerWithMeta } from '../lib/types';
+export declare function createEnhancer<I = unknown, O = unknown>(meta: EnhancerMeta, enhancerFn: (input: I) => O): EnhancerWithMeta<I, O>;
+export declare function resolveEnhancerOrder(enhancers: EnhancerWithMeta<unknown, unknown>[], availableCapabilities?: Set<string>, debugMode?: boolean): EnhancerWithMeta<unknown, unknown>[];

package/src/enhancers/index.js

@@ -0,0 +1,84 @@
+import { SIGNAL_TREE_MESSAGES } from '../lib/constants';
+import { ENHANCER_META } from '../lib/types';
+export function createEnhancer(meta, enhancerFn) {
+    const fn = enhancerFn;
+    try {
+        fn.metadata = meta;
+        try {
+            fn[ENHANCER_META] = meta;
+        }
+        catch {
+        }
+    }
+    catch {
+    }
+    return fn;
+}
+export function resolveEnhancerOrder(enhancers, availableCapabilities = new Set(), debugMode = false) {
+    const nodes = enhancers.map((e, idx) => ({
+        fn: e,
+        name: e.metadata && e.metadata.name
+            ? String(e.metadata.name)
+            : `enhancer#${idx}`,
+        requires: new Set(e.metadata?.requires ?? []),
+        provides: new Set(e.metadata?.provides ?? []),
+    }));
+    const adj = new Map();
+    const nameToNode = new Map();
+    for (const n of nodes) {
+        nameToNode.set(n.name, n);
+        adj.set(n.name, new Set());
+    }
+    for (const a of nodes) {
+        for (const b of nodes) {
+            if (a === b)
+                continue;
+            for (const req of b.requires) {
+                if (availableCapabilities.has(req))
+                    continue;
+                if (a.provides.has(req)) {
+                    const set = adj.get(a.name);
+                    if (set)
+                        set.add(b.name);
+                }
+            }
+        }
+    }
+    const inDegree = new Map();
+    for (const entry of adj.keys())
+        inDegree.set(entry, 0);
+    for (const [, outs] of adj) {
+        for (const to of outs)
+            inDegree.set(to, (inDegree.get(to) || 0) + 1);
+    }
+    const queue = [];
+    for (const [name, deg] of inDegree.entries()) {
+        if (deg === 0)
+            queue.push(name);
+    }
+    const ordered = [];
+    while (queue.length > 0) {
+        const n = queue.shift();
+        if (!n)
+            break;
+        ordered.push(n);
+        const outs = adj.get(n);
+        if (!outs)
+            continue;
+        for (const m of outs) {
+            inDegree.set(m, (inDegree.get(m) || 0) - 1);
+            if (inDegree.get(m) === 0)
+                queue.push(m);
+        }
+    }
+    if (ordered.length !== nodes.length) {
+        if (debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_CYCLE_DETECTED);
+        }
+        return enhancers;
+    }
+    return ordered.map((name) => {
+        const n = nameToNode.get(name);
+        return (n ? n.fn : enhancers[0]);
+    });
+}

package/src/enhancers/memoization/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/memoization';

package/src/enhancers/memoization/index.js

@@ -0,0 +1 @@
+export * from './lib/memoization';

package/src/enhancers/memoization/jest.config.d.ts

@@ -0,0 +1,15 @@
+declare const _default: {
+    displayName: string;
+    preset: string;
+    setupFilesAfterEnv: string[];
+    coverageDirectory: string;
+    transform: {
+        '^.+\\.(ts|mjs|js|html)$': (string | {
+            tsconfig: string;
+            stringifyContentPathRegex: string;
+        })[];
+    };
+    transformIgnorePatterns: string[];
+    snapshotSerializers: string[];
+};
+export default _default;

package/src/enhancers/memoization/jest.config.js

@@ -0,0 +1,21 @@
+export default {
+    displayName: 'memoization',
+    preset: '../../../jest.preset.js',
+    setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+    coverageDirectory: '../../../coverage/packages/core/enhancers/memoization',
+    transform: {
+        '^.+\\.(ts|mjs|js|html)$': [
+            'jest-preset-angular',
+            {
+                tsconfig: '<rootDir>/tsconfig.spec.json',
+                stringifyContentPathRegex: '\\.(html|svg)$',
+            },
+        ],
+    },
+    transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+    snapshotSerializers: [
+        'jest-preset-angular/build/serializers/no-ng-attributes',
+        'jest-preset-angular/build/serializers/ng-snapshot',
+        'jest-preset-angular/build/serializers/html-comment',
+    ],
+};

package/src/enhancers/memoization/lib/memoization.d.ts

@@ -0,0 +1,65 @@
+import type { SignalTree } from '../../../lib/types';
+export interface MemoizedSignalTree<T> extends SignalTree<T> {
+    memoizedUpdate: (updater: (current: T) => Partial<T>, cacheKey?: string) => void;
+    clearMemoCache: (key?: string) => void;
+    getCacheStats: () => {
+        size: number;
+        hitRate: number;
+        totalHits: number;
+        totalMisses: number;
+        keys: string[];
+    };
+}
+export declare function cleanupMemoizationCache(): void;
+export interface MemoizationConfig {
+    enabled?: boolean;
+    maxCacheSize?: number;
+    ttl?: number;
+    equality?: 'deep' | 'shallow' | 'reference';
+    enableLRU?: boolean;
+}
+export declare function memoize<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string, config?: MemoizationConfig): (...args: TArgs) => TReturn;
+export declare function memoizeShallow<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string): (...args: TArgs) => TReturn;
+export declare function memoizeReference<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string): (...args: TArgs) => TReturn;
+export declare const MEMOIZATION_PRESETS: {
+    readonly selector: {
+        readonly equality: "reference";
+        readonly maxCacheSize: 10;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+    readonly computed: {
+        readonly equality: "shallow";
+        readonly maxCacheSize: 100;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+    readonly deepState: {
+        readonly equality: "deep";
+        readonly maxCacheSize: 1000;
+        readonly enableLRU: true;
+        readonly ttl: number;
+    };
+    readonly highFrequency: {
+        readonly equality: "reference";
+        readonly maxCacheSize: 5;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+};
+export declare function withSelectorMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withComputedMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withDeepStateMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withHighFrequencyMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withMemoization<T>(config?: MemoizationConfig): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function enableMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withHighPerformanceMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withLightweightMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function withShallowMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+export declare function clearAllCaches(): void;
+export declare function getGlobalCacheStats(): {
+    treeCount: number;
+    totalSize: number;
+    totalHits: number;
+    averageCacheSize: number;
+};