@signaltree/core 3.0.2 → 4.0.1

package/dist/enhancers/index.js

@@ -0,0 +1,191 @@
+import '@signaltree/shared';
+
+// Full developer-facing messages
+const DEV_MESSAGES = {
+    NULL_OR_UNDEFINED: 'null/undefined',
+    CIRCULAR_REF: 'circular ref',
+    UPDATER_INVALID: 'updater invalid',
+    LAZY_FALLBACK: 'lazy fallback',
+    SIGNAL_CREATION_FAILED: 'signal creation failed',
+    UPDATE_PATH_NOT_FOUND: 'update path not found',
+    UPDATE_FAILED: 'update failed',
+    ROLLBACK_FAILED: 'rollback failed',
+    CLEANUP_ERROR: 'cleanup error',
+    PRESET_UNKNOWN: 'unknown preset',
+    STRATEGY_SELECTION: 'strategy select',
+    TREE_DESTROYED: 'destroyed',
+    UPDATE_TRANSACTION: 'update tx',
+    BATCH_NOT_ENABLED: 'batching disabled',
+    MEMOIZE_NOT_ENABLED: 'memoize disabled',
+    MIDDLEWARE_NOT_AVAILABLE: 'middleware missing',
+    ENTITY_HELPERS_NOT_AVAILABLE: 'entity helpers missing',
+    ASYNC_ACTIONS_NOT_AVAILABLE: 'async actions missing',
+    TIME_TRAVEL_NOT_AVAILABLE: 'time travel missing',
+    OPTIMIZE_NOT_AVAILABLE: 'optimize missing',
+    UPDATE_OPTIMIZED_NOT_AVAILABLE: 'update optimized missing',
+    CACHE_NOT_AVAILABLE: 'cache missing',
+    PERFORMANCE_NOT_ENABLED: 'performance disabled',
+    ENHANCER_ORDER_FAILED: 'enhancer order failed',
+    ENHANCER_CYCLE_DETECTED: 'enhancer cycle',
+    ENHANCER_REQUIREMENT_MISSING: 'enhancer req missing',
+    ENHANCER_PROVIDES_MISSING: 'enhancer provides missing',
+    ENHANCER_FAILED: 'enhancer failed',
+    ENHANCER_NOT_FUNCTION: 'enhancer not function',
+    EFFECT_NO_CONTEXT: 'no angular context',
+    SUBSCRIBE_NO_CONTEXT: 'no angular context',
+};
+// Compact production messages (very short numeric codes) to keep bundles minimal.
+// We map each key to a short numeric string like '0','1','2' to minimize bytes.
+const PROD_MESSAGES = (() => {
+    const out = {};
+    let i = 0;
+    for (const k of Object.keys(DEV_MESSAGES)) {
+        out[k] = String(i++);
+    }
+    return out;
+})();
+// Avoid referencing the bare `process` identifier to keep builds free of Node
+// type assumptions; use globalThis to check env when available.
+const _isProdByEnv = Boolean(typeof globalThis === 'object' &&
+    globalThis !== null &&
+    'process' in globalThis &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof globalThis.process === 'object' &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    'env' in globalThis.process &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.process.env.NODE_ENV === 'production');
+const _isDev = typeof ngDevMode !== 'undefined' ? Boolean(ngDevMode) : !_isProdByEnv;
+const SIGNAL_TREE_MESSAGES = Object.freeze(_isDev
+    ? DEV_MESSAGES
+    : PROD_MESSAGES);
+
+/** Symbol key for enhancer metadata */
+const ENHANCER_META = Symbol('signaltree:enhancer:meta');
+
+/**
+ * Helper to create an enhancer with metadata attached
+ *
+ * @param meta - Metadata describing the enhancer
+ * @param enhancerFn - The enhancer function
+ * @returns Enhancer function with metadata attached
+ *
+ * @example
+ * ```typescript
+ * const myEnhancer = createEnhancer(
+ *   {
+ *     name: 'myEnhancer',
+ *     provides: ['feature1'],
+ *     requires: ['feature2']
+ *   },
+ *   (tree) => {
+ *     // Enhance the tree
+ *     return { ...tree, feature1: true };
+ *   }
+ * );
+ * ```
+ */
+function createEnhancer(meta, enhancerFn) {
+    const fn = enhancerFn;
+    try {
+        fn.metadata = meta;
+        // Also attach under symbol for third-party compatibility
+        try {
+            fn[ENHANCER_META] = meta;
+        }
+        catch {
+            // Ignore if property can't be set
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return fn;
+}
+/**
+ * Resolve enhancer order using topological sort based on dependencies
+ *
+ * @param enhancers - Array of enhancers to order
+ * @param availableCapabilities - Set of already available capabilities
+ * @param debugMode - Whether to log debug information
+ * @returns Ordered array of enhancers
+ */
+function resolveEnhancerOrder(enhancers, availableCapabilities = new Set(), debugMode = false) {
+    // Build nodes with metadata
+    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 ?? []),
+    }));
+    // Build dependency graph
+    const adj = new Map();
+    const nameToNode = new Map();
+    for (const n of nodes) {
+        nameToNode.set(n.name, n);
+        adj.set(n.name, new Set());
+    }
+    // Create edges based on requirements
+    for (const a of nodes) {
+        for (const b of nodes) {
+            if (a === b)
+                continue;
+            for (const req of b.requires) {
+                // Skip if requirement is already satisfied
+                if (availableCapabilities.has(req))
+                    continue;
+                if (a.provides.has(req)) {
+                    // a must come before b
+                    const set = adj.get(a.name);
+                    if (set)
+                        set.add(b.name);
+                }
+            }
+        }
+    }
+    // Kahn's algorithm for topological sort
+    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);
+        }
+    }
+    // Check for cycles
+    if (ordered.length !== nodes.length) {
+        if (debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_CYCLE_DETECTED);
+        }
+        return enhancers;
+    }
+    // Map ordered names back to enhancer functions
+    return ordered.map((name) => {
+        const n = nameToNode.get(name);
+        return (n ? n.fn : enhancers[0]);
+    });
+}
+
+export { createEnhancer, resolveEnhancerOrder };
+//# sourceMappingURL=index.js.map

package/dist/enhancers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../../../packages/core/src/lib/constants.ts","../../../../../../packages/core/src/lib/types.ts","../../../../../../packages/core/src/enhancers/index.ts"],"sourcesContent":[null,null,null],"names":[],"mappings":"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"}

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

@@ -0,0 +1,425 @@
+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;
+}
+
+/**
+ * Extended SignalTree interface with memoization capabilities
+ * Uses the same unconstrained recursive typing approach as core
+ */
+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[];
+    };
+}
+/**
+ * Cleanup the cache interval on app shutdown
+ */
+declare function cleanupMemoizationCache(): void;
+/**
+ * Memoization configuration options
+ */
+interface MemoizationConfig {
+    enabled?: boolean;
+    maxCacheSize?: number;
+    ttl?: number;
+    equality?: 'deep' | 'shallow' | 'reference';
+    enableLRU?: boolean;
+}
+/**
+ * Memoization function that caches expensive computations with enhanced cache management
+ */
+declare function memoize<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string, config?: MemoizationConfig): (...args: TArgs) => TReturn;
+/**
+ * High-performance memoization function optimized for speed
+ * Uses shallow equality and minimal cache management overhead
+ */
+declare function memoizeShallow<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string): (...args: TArgs) => TReturn;
+/**
+ * Lightweight memoization function with reference equality only
+ * Maximum performance for scenarios where exact reference matches are sufficient
+ */
+declare function memoizeReference<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, keyFn?: (...args: TArgs) => string): (...args: TArgs) => TReturn;
+/**
+ * Preset memoization configurations optimized for common use cases
+ * These presets are the same ones used in SignalTree's benchmarks
+ */
+declare const MEMOIZATION_PRESETS: {
+    /**
+     * Optimized for selectors and frequently-accessed computed values
+     * - Fast reference-only equality checks (~0.3μs)
+     * - Small cache (10 entries) for minimal overhead
+     * - No LRU management (eliminates bookkeeping cost)
+     * - Best for: Selectors, derived values, stable references
+     */
+    readonly selector: {
+        readonly equality: "reference";
+        readonly maxCacheSize: 10;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+    /**
+     * Balanced configuration for general computed values
+     * - Shallow equality checks (~5-15μs) for object comparisons
+     * - Medium cache (100 entries) for reasonable coverage
+     * - No LRU (good performance/memory balance)
+     * - Best for: General computations, objects with primitives
+     */
+    readonly computed: {
+        readonly equality: "shallow";
+        readonly maxCacheSize: 100;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+    /**
+     * Thorough configuration for complex nested state
+     * - Deep equality checks (~50-200μs) for nested objects
+     * - Large cache (1000 entries) for complex scenarios
+     * - LRU enabled for intelligent cache management
+     * - 5-minute TTL to prevent stale data
+     * - Best for: Complex nested objects, thorough comparisons needed
+     */
+    readonly deepState: {
+        readonly equality: "deep";
+        readonly maxCacheSize: 1000;
+        readonly enableLRU: true;
+        readonly ttl: number;
+    };
+    /**
+     * Minimal overhead for high-frequency operations
+     * - Reference-only equality (fastest possible)
+     * - Tiny cache (5 entries) for minimal memory
+     * - No bells and whistles
+     * - Best for: Hot paths, microseconds matter, immutable data
+     */
+    readonly highFrequency: {
+        readonly equality: "reference";
+        readonly maxCacheSize: 5;
+        readonly enableLRU: false;
+        readonly ttl: undefined;
+    };
+};
+/**
+ * Convenience function: Memoization optimized for selectors
+ * Uses reference equality and small cache for maximum performance
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withSelectorMemoization());
+ * const activeUsers = computed(() =>
+ *   tree.state.users().filter(u => u.active)
+ * );
+ * ```
+ */
+declare function withSelectorMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Convenience function: Memoization optimized for computed values
+ * Uses shallow equality for balanced performance
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withComputedMemoization());
+ * const metrics = computed(() =>
+ *   calculateExpensiveMetrics(tree.state.data())
+ * );
+ * ```
+ */
+declare function withComputedMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Convenience function: Memoization for complex nested state
+ * Uses deep equality and LRU management
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withDeepStateMemoization());
+ * // Handles complex nested object comparisons
+ * ```
+ */
+declare function withDeepStateMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Convenience function: Minimal memoization for hot paths
+ * Maximum performance with minimal overhead
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withHighFrequencyMemoization());
+ * // For operations called thousands of times per second
+ * ```
+ */
+declare function withHighFrequencyMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Enhances a SignalTree with memoization capabilities
+ * Uses unconstrained recursive typing - no limitations on T
+ */
+declare function withMemoization<T>(config?: MemoizationConfig): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Convenience function to enable memoization with default settings
+ * Uses unconstrained recursive typing - no limitations on T
+ */
+declare function enableMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * High-performance memoization with aggressive caching
+ * Uses unconstrained recursive typing - no limitations on T
+ */
+declare function withHighPerformanceMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Lightweight memoization optimized for performance-critical scenarios
+ * Disables expensive cache management features for maximum speed
+ */
+declare function withLightweightMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Shallow equality memoization for objects with primitive values
+ * Good balance between performance and correctness
+ */
+declare function withShallowMemoization<T>(): (tree: SignalTree<T>) => MemoizedSignalTree<T>;
+/**
+ * Clear all memoization caches
+ */
+declare function clearAllCaches(): void;
+/**
+ * Get global cache statistics
+ */
+declare function getGlobalCacheStats(): {
+    treeCount: number;
+    totalSize: number;
+    totalHits: number;
+    averageCacheSize: number;
+};
+
+export { MEMOIZATION_PRESETS, cleanupMemoizationCache, clearAllCaches, enableMemoization, getGlobalCacheStats, memoize, memoizeReference, memoizeShallow, withComputedMemoization, withDeepStateMemoization, withHighFrequencyMemoization, withHighPerformanceMemoization, withLightweightMemoization, withMemoization, withSelectorMemoization, withShallowMemoization };
+export type { MemoizationConfig, MemoizedSignalTree };