@signaltree/core 3.1.0 → 4.0.1

package/dist/enhancers/presets/types/packages/core/src/lib/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAU,cAAc,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK3E;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,OAAO,EAAE,SAAS,IAAI,KAAK,EAAE,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7D,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;GAGG;AAEH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC;IACN,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,GAC3C,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpB,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACnB,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,GAC1B,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAC5C,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpB,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpB,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC,CAI7E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,SAAS,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAClC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAEhB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACnD,GAAG,EAAE,CAAC,EACN,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,EAC/C,QAAQ,SAAK,EACb,aAAa,CAAC,EAAE,aAAa,GAC5B,QAAQ,CAAC,CAAC,CAAC,CA6Jb;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAChD,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAClE,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACpD,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC"}

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

@@ -0,0 +1,439 @@
+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;
+}
+
+/**
+ * Serialization configuration options
+ */
+interface SerializationConfig {
+    /**
+     * Whether to include metadata (timestamps, version, etc.)
+     * @default true
+     */
+    includeMetadata?: boolean;
+    /**
+     * Custom replacer function for JSON.stringify
+     */
+    replacer?: (key: string, value: unknown) => unknown;
+    /**
+     * Custom reviver function for JSON.parse
+     */
+    reviver?: (key: string, value: unknown) => unknown;
+    /**
+     * Whether to preserve special types (Date, RegExp, etc.)
+     * @default true
+     */
+    preserveTypes?: boolean;
+    /**
+     * Maximum depth to serialize (prevents infinite recursion)
+     * @default 50
+     */
+    maxDepth?: number;
+    /**
+     * Whether to handle circular references
+     * @default true
+     */
+    handleCircular?: boolean;
+}
+/**
+ * Serialized state wrapper with metadata
+ */
+interface SerializedState<T = unknown> {
+    /**
+     * The actual serialized state data
+     */
+    data: T;
+    /**
+     * Metadata about the serialization
+     */
+    metadata?: {
+        /**
+         * Timestamp when serialized
+         */
+        timestamp: number;
+        /**
+         * Version of the serialization format
+         */
+        version: string;
+        /**
+         * Custom application version
+         */
+        appVersion?: string;
+        /**
+         * Type information for special objects
+         */
+        types?: Record<string, string>;
+        /**
+         * Circular reference paths
+         */
+        circularRefs?: Array<{
+            path: string;
+            targetPath: string;
+        }>;
+        /**
+         * Optional map of paths that indicate where the target tree contains
+         * branch nodes (objects with set/update) or root-as-signal markers.
+         * Keys are paths (dot/array notation), values: 'b' = branch, 'r' = root
+         */
+        nodeMap?: Record<string, 'b' | 'r'>;
+    };
+}
+/**
+ * Enhanced SignalTree interface with serialization capabilities
+ */
+interface SerializableSignalTree<T> extends SignalTree<T> {
+    /** Explicit reactive alias for state (helps TS resolution in tests) */
+    $: any;
+    /**
+     * Serialize the current state to a JSON string
+     */
+    serialize(config?: SerializationConfig): string;
+    /**
+     * Deserialize and apply state from a JSON string
+     */
+    deserialize(json: string, config?: SerializationConfig): void;
+    /**
+     * Get a plain object representation of the current state
+     */
+    toJSON(): T;
+    /**
+     * Restore state from a plain object
+     */
+    fromJSON(data: T, metadata?: SerializedState<T>['metadata']): void;
+    /**
+     * Create a snapshot of the current state
+     */
+    snapshot(): SerializedState<T>;
+    /**
+     * Restore state from a snapshot
+     */
+    restore(snapshot: SerializedState<T>): void;
+}
+/**
+ * Methods added by the persistence enhancer
+ */
+interface PersistenceMethods {
+    save(): Promise<void>;
+    load(): Promise<void>;
+    clear(): Promise<void>;
+    __flushAutoSave?: () => Promise<void>;
+}
+/**
+ * Enhances a SignalTree with serialization capabilities
+ */
+declare function withSerialization<T extends Record<string, unknown> = Record<string, unknown>>(defaultConfig?: SerializationConfig): EnhancerWithMeta<SignalTree<T>, SerializableSignalTree<T>>;
+/**
+ * Convenience function to enable serialization with defaults
+ */
+declare function enableSerialization<T extends Record<string, unknown> = Record<string, unknown>>(): EnhancerWithMeta<SignalTree<T>, SerializableSignalTree<T>>;
+/**
+ * Storage adapter interface for persistence
+ */
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * Persistence configuration
+ */
+interface PersistenceConfig extends SerializationConfig {
+    /**
+     * Storage key to use
+     */
+    key: string;
+    /**
+     * Storage adapter (defaults to localStorage)
+     */
+    storage?: StorageAdapter;
+    /**
+     * Whether to auto-save on every update
+     * @default true
+     */
+    autoSave?: boolean;
+    /**
+     * Debounce delay for auto-save in ms
+     * @default 1000
+     */
+    debounceMs?: number;
+    /**
+     * Whether to auto-load on creation
+     * @default true
+     */
+    autoLoad?: boolean;
+    /**
+     * Whether to skip caching and force storage writes even if unchanged
+     * @default false
+     */
+    skipCache?: boolean;
+}
+/**
+ * Adds persistence capabilities to a SerializableSignalTree
+ */
+declare function withPersistence<T extends Record<string, unknown> = Record<string, unknown>>(config: PersistenceConfig): EnhancerWithMeta<SignalTree<T>, SerializableSignalTree<T> & PersistenceMethods>;
+/**
+ * Create a custom storage adapter
+ */
+declare function createStorageAdapter(getItem: (key: string) => string | null | Promise<string | null>, setItem: (key: string, value: string) => void | Promise<void>, removeItem: (key: string) => void | Promise<void>): StorageAdapter;
+/**
+ * IndexedDB storage adapter for large state trees
+ */
+declare function createIndexedDBAdapter(dbName?: string, storeName?: string): StorageAdapter;
+/**
+ * Helpers to apply enhancers with explicit typing to avoid depending on
+ * complex `.with()` overload inference in tests and tooling.
+ */
+declare function applySerialization<T extends Record<string, unknown>>(tree: SignalTree<T>): SerializableSignalTree<T>;
+declare function applyPersistence<T extends Record<string, unknown>>(tree: SignalTree<T>, cfg: PersistenceConfig): SerializableSignalTree<T> & PersistenceMethods;
+
+/**
+ * Type markers for special object serialization
+ * Using compact symbols to minimize serialized size
+ */
+declare const TYPE_MARKERS: {
+    readonly DATE: "§d";
+    readonly REGEXP: "§r";
+    readonly MAP: "§m";
+    readonly SET: "§s";
+    readonly UNDEFINED: "§u";
+    readonly NAN: "§n";
+    readonly INFINITY: "§i";
+    readonly NEG_INFINITY: "§-i";
+    readonly BIGINT: "§b";
+    readonly SYMBOL: "§y";
+    readonly FUNCTION: "§f";
+    readonly CIRCULAR: "§c";
+};
+
+export { TYPE_MARKERS, applyPersistence, applySerialization, createIndexedDBAdapter, createStorageAdapter, enableSerialization, withPersistence, withSerialization };
+export type { PersistenceConfig, PersistenceMethods, SerializableSignalTree, SerializationConfig, SerializedState, StorageAdapter };