@signaltree/core 4.0.8 → 4.0.9

package/LICENSE

@@ -0,0 +1,54 @@
+BUSINESS SOURCE LICENSE 1.1
+
+Copyright (c) 2025 Jonathan D Borgia
+
+This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
+
+1. Definitions
+
+"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
+
+"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
+
+"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
+
+"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
+
+2. License Grant
+
+Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
+
+3. Commercial Use
+
+You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
+
+4. Limitations and Conditions
+
+a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
+
+b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
+
+c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
+
+5. Disclaimer and Limitation of Liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
+
+6. Change License
+
+On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
+
+7. Governing Law
+
+This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
+
+8. Accepting this License
+
+You accept this License by copying, modifying, or distributing the Software or any portion thereof.
+
+---
+
+LICENSE NOTE
+
+- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
+  or standard modifications for your own applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "4.0.8",
+  "version": "4.0.9",
   "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,
@@ -65,11 +65,11 @@
     "tslib": "*"
   },
   "dependencies": {
-    "@signaltree/shared": "workspace:*"
+    "@signaltree/shared": "0.0.1"
   },
   "files": [
     "dist",
     "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 };