@signaltree/core 4.0.8 → 4.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "4.0.8",
+  "version": "4.0.12",
   "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
   "type": "module",
   "sideEffects": false,
@@ -72,4 +72,4 @@
     "README.md",
     "package.json"
   ]
-}
+}

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

@@ -1,495 +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;
-}
-
-/**
- * Configuration options for intelligent batching behavior.
- * Controls how updates are grouped and processed for optimal performance.
- * Uses unconstrained recursive typing - no limitations on T
- *
- * @example
- * ```typescript
- * const config: BatchingConfig = {
- *   enabled: true,
- *   maxBatchSize: 50,
- *   autoFlushDelay: 16, // 60fps
- *   batchTimeoutMs: 100
- * };
- * ```
- */
-interface BatchingConfig {
-    /** Whether batching is enabled (default: true) */
-    enabled?: boolean;
-    /** Maximum number of updates per batch (default: 100) */
-    maxBatchSize?: number;
-    /** Delay before auto-flushing batch in milliseconds (default: 16) */
-    autoFlushDelay?: number;
-    /** Maximum time to wait before forcing batch flush (default: 100) */
-    batchTimeoutMs?: number;
-}
-/**
- * Enhanced SignalTree interface with intelligent batching capabilities.
- * Provides high-performance batch update methods that group multiple state changes.
- *
- * @template T - The state object type extending StateObject
- *
- * @example
- * ```typescript
- * interface AppState {
- *   users: User[];
- *   ui: { loading: boolean; error: string | null };
- *   stats: { total: number; active: number };
- * }
- *
- * const tree: BatchingSignalTree<AppState> = create(initialState)
- *   .with(withBatching());
- *
- * // Batch multiple related updates
- * tree.batchUpdate((state) => ({
- *   users: [...state.users, newUser],
- *   ui: { ...state.ui, loading: false },
- *   stats: {
- *     total: state.users.length + 1,
- *     active: state.users.filter(u => u.active).length + (newUser.active ? 1 : 0)
- *   }
- * }));
- * Uses unconstrained recursive typing - no limitations on T
- * ```
- */
-interface BatchingSignalTree<T> extends SignalTree<T> {
-    /**
-     * Batches multiple state updates into a single change cycle for optimal performance.
-     * Groups related updates to prevent UI thrashing and improve rendering efficiency.
-     *
-     * @param updater - Function that receives current state and returns partial update
-     *
-     * @example
-     * ```typescript
-     * // Instead of multiple individual updates
-     * tree.update(() => ({ loading: true }));
-     * tree.update(() => ({ error: null }));
-     * tree.update(() => ({ users: [] }));
-     *
-     * // Use a single batched update
-     * tree.batchUpdate((state) => ({
-     *   loading: true,
-     *   error: null,
-     *   users: []
-     * }));
-     * ```
-     */
-    batchUpdate(updater: (current: T) => Partial<T>): void;
-}
-/**
- * Enhances a SignalTree with intelligent batching capabilities for optimal performance.
- * Automatically groups rapid state updates into efficient batch cycles to eliminate UI thrashing.
- *
- * @template T - The state object type extending StateObject
- * @param config - Configuration options for batching behavior
- * @returns Function that enhances a SignalTree with batching capabilities
- *
- * @example
- * ```typescript
- * // Basic batching with default settings
- * const tree = create(initialState).with(withBatching());
- *
- * // High-performance batching for demanding applications
- * const tree = create(initialState).with(withBatching({
- *   maxBatchSize: 50,
- *   autoFlushDelay: 8, // ~120fps
- *   batchTimeoutMs: 50
- * }));
- *
- * // Conservative batching for stable UIs
- * const tree = create(initialState).with(withBatching({
- *   maxBatchSize: 10,
- *   autoFlushDelay: 100,
- *   batchTimeoutMs: 200
- * }));
- *
- * // Use batching methods
- * tree.batchUpdate((state) => ({
- *   users: [...state.users, newUser],
- *   loading: false,
- *   error: null
- * }));
- * Uses unconstrained recursive typing - no limitations on T
- * ```
- */
-declare function withBatching<T>(config?: BatchingConfig): (tree: SignalTree<T>) => BatchingSignalTree<T>;
-/**
- * Convenience function to enable batching with default settings.
- * Equivalent to withBatching({ enabled: true }) but more concise for common usage.
- *
- * @template T - The state object type extending StateObject
- * @returns Function that enhances a SignalTree with default batching settings
- *
- * @example
- * ```typescript
- * // Simple batching enablement
- * const tree = create(initialState).with(enableBatching());
- *
- * // Equivalent to:
- * const tree = create(initialState).with(withBatching({ enabled: true }));
- * Uses unconstrained recursive typing - no limitations on T
- * ```
- */
-/**
- * Creates high-performance batching configuration optimized for demanding applications.
- * Uses aggressive batching settings for maximum performance in high-frequency update scenarios.
- * Uses unconstrained recursive typing - no limitations on T
- *
- * @template T - The state object type extending StateObject
- * @returns Function that enhances a SignalTree with high-performance batching
- *
- * @example
- * ```typescript
- * // For performance-critical applications
- * const gameTree = create(gameState).with(withHighPerformanceBatching());
- *
- * // Perfect for:
- * // - Real-time games
- * // - High-frequency data updates
- * // - Animation-heavy UIs
- * // - Large dataset operations
- *
- * // Automatically includes:
- * // - Large batch sizes (200 updates)
- * // - Immediate processing (0ms timeout)
- * // - Aggressive optimization
- * Uses unconstrained recursive typing - no limitations on T
- * ```
- */
-declare function withHighPerformanceBatching<T>(): (tree: SignalTree<T>) => BatchingSignalTree<T>;
-/**
- * Manually flushes all pending batched updates immediately.
- * Forces synchronous execution of queued updates, bypassing normal batching delays.
- * Useful for testing scenarios or when immediate state consistency is required.
- *
- * @example
- * ```typescript
- * // Queue some updates
- * tree.batchUpdate(() => ({ count: 1 }));
- * tree.batchUpdate(() => ({ name: 'test' }));
- *
- * // In tests, ensure updates are applied immediately
- * flushBatchedUpdates();
- * expect(tree().count).toBe(1);
- * expect(tree().name).toBe('test');
- *
- * // Before critical operations that need current state
- * flushBatchedUpdates();
- * const currentState = tree(); // Guaranteed to be up-to-date
- *
- * // In animation frames for precise timing
- * requestAnimationFrame(() => {
- *   flushBatchedUpdates(); // Ensure updates are applied before render
- *   updateUI();
- * });
- * ```
- */
-declare function flushBatchedUpdates(): void;
-/**
- * Checks if there are pending batched updates waiting to be processed.
- * Useful for testing, debugging, or conditional logic based on update queue state.
- *
- * @returns True if updates are queued, false if queue is empty
- *
- * @example
- * ```typescript
- * // Check before critical operations
- * tree.batchUpdate(() => ({ loading: true }));
- *
- * if (hasPendingUpdates()) {
- *   console.log('Updates are queued for processing');
- *   flushBatchedUpdates(); // Process them now if needed
- * }
- *
- * // In testing
- * tree.batchUpdate(() => ({ count: 1 }));
- * expect(hasPendingUpdates()).toBe(true);
- *
- * flushBatchedUpdates();
- * expect(hasPendingUpdates()).toBe(false);
- *
- * // Conditional behavior
- * function performCriticalOperation() {
- *   if (hasPendingUpdates()) {
- *     flushBatchedUpdates(); // Ensure consistent state
- *   }
- *   // Proceed with operation
- * }
- * ```
- */
-declare function hasPendingUpdates(): boolean;
-/**
- * Gets the current number of updates waiting in the batch queue.
- * Useful for performance monitoring, debugging, and batch size optimization.
- *
- * @returns Number of queued updates
- *
- * @example
- * ```typescript
- * // Performance monitoring
- * function monitorBatchPerformance() {
- *   const queueSize = getBatchQueueSize();
- *
- *   if (queueSize > 50) {
- *     console.warn(`Large batch queue detected: ${queueSize} updates`);
- *   }
- *
- *   // Log metrics
- *   console.log(`Current queue size: ${queueSize}`);
- * }
- *
- * // Debug batching behavior
- * tree.batchUpdate(() => ({ a: 1 }));
- * tree.batchUpdate(() => ({ b: 2 }));
- * tree.batchUpdate(() => ({ c: 3 }));
- *
- * console.log(`Queue size: ${getBatchQueueSize()}`); // 3
- *
- * flushBatchedUpdates();
- * console.log(`Queue size after flush: ${getBatchQueueSize()}`); // 0
- *
- * // Optimize batch configuration
- * const currentQueueSize = getBatchQueueSize();
- * if (currentQueueSize > 100) {
- *   // Consider reducing maxBatchSize or autoFlushDelay
- *   console.log('Consider optimizing batch configuration');
- * }
- * ```
- */
-declare function getBatchQueueSize(): number;
-
-export { flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, withBatching, withHighPerformanceBatching };