@signaltree/core 6.0.0 → 6.0.3

package/src/enhancers/serialization/serialization.d.ts

@@ -0,0 +1,68 @@
+import { ISignalTree } from '../../lib/types';
+export interface SerializationConfig {
+    includeMetadata?: boolean;
+    replacer?: (key: string, value: unknown) => unknown;
+    reviver?: (key: string, value: unknown) => unknown;
+    preserveTypes?: boolean;
+    maxDepth?: number;
+    handleCircular?: boolean;
+}
+export interface SerializedState<T = unknown> {
+    data: T;
+    metadata?: {
+        timestamp: number;
+        version: string;
+        appVersion?: string;
+        types?: Record<string, string>;
+        circularRefs?: Array<{
+            path: string;
+            targetPath: string;
+        }>;
+        nodeMap?: Record<string, 'b' | 'r'>;
+    };
+}
+export interface SerializableSignalTree<T> extends ISignalTree<T> {
+    $: any;
+    serialize(config?: SerializationConfig): string;
+    deserialize(json: string, config?: SerializationConfig): void;
+    toJSON(): T;
+    fromJSON(data: T, metadata?: SerializedState<T>['metadata']): void;
+    snapshot(): SerializedState<T>;
+    restore(snapshot: SerializedState<T>): void;
+}
+export interface SerializationMethods {
+    serialize(config?: SerializationConfig): string;
+    deserialize(json: string, config?: SerializationConfig): void;
+    toJSON(): unknown;
+    fromJSON(data: unknown, metadata?: SerializedState<unknown>['metadata']): void;
+    snapshot(): SerializedState<unknown>;
+    restore(snapshot: SerializedState<unknown>): void;
+}
+export interface PersistenceMethods {
+    save(): Promise<void>;
+    load(): Promise<void>;
+    clear(): Promise<void>;
+    __flushAutoSave?: () => Promise<void>;
+}
+export declare function serialization(defaultConfig?: SerializationConfig): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & SerializationMethods;
+export declare const withSerialization: (defaultConfig?: SerializationConfig) => <Tree extends ISignalTree<any>>(tree: Tree) => Tree & SerializationMethods;
+export declare function enableSerialization(): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & SerializationMethods;
+export interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+export interface PersistenceConfig extends SerializationConfig {
+    key: string;
+    storage?: StorageAdapter;
+    autoSave?: boolean;
+    debounceMs?: number;
+    autoLoad?: boolean;
+    skipCache?: boolean;
+}
+export declare function persistence(config: PersistenceConfig): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & SerializationMethods & PersistenceMethods;
+export declare const withPersistence: (cfg: PersistenceConfig) => <Tree extends ISignalTree<any>>(tree: Tree) => Tree & SerializationMethods & PersistenceMethods;
+export 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;
+export declare function createIndexedDBAdapter(dbName?: string, storeName?: string): StorageAdapter;
+export declare function applySerialization<T extends Record<string, unknown>>(tree: ISignalTree<T>): ISignalTree<T> & SerializationMethods;
+export declare function applyPersistence<T extends Record<string, unknown>>(tree: ISignalTree<T>, cfg: PersistenceConfig): ISignalTree<T> & SerializationMethods & PersistenceMethods;

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

@@ -0,0 +1,3 @@
+import '@angular/compiler';
+import 'zone.js';
+import 'zone.js/testing';

package/src/enhancers/test-helpers/types-equals.d.ts

@@ -0,0 +1,2 @@
+export type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+export type Assert<T extends true> = T;

package/src/enhancers/time-travel/index.d.ts

@@ -0,0 +1 @@
+export * from './time-travel';

package/src/enhancers/time-travel/test-setup.d.ts

@@ -0,0 +1,3 @@
+import '@angular/compiler';
+import 'zone.js';
+import 'zone.js/testing';

package/src/enhancers/time-travel/time-travel.d.ts

@@ -0,0 +1,10 @@
+import type { ISignalTree, TimeTravelMethods, TimeTravelConfig, TimeTravelEntry } from '../../lib/types';
+export type { TimeTravelConfig, TimeTravelEntry };
+export declare function timeTravel(config?: TimeTravelConfig): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods;
+export declare function enableTimeTravel(): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods;
+export declare function timeTravelHistory(maxHistorySize: number): <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods;
+export declare const withTimeTravel: ((config?: TimeTravelConfig) => <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods) & {
+    minimal: () => <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods;
+    debug: () => <Tree extends ISignalTree<any>>(tree: Tree) => Tree & TimeTravelMethods;
+    history: typeof timeTravelHistory;
+};

package/src/enhancers/time-travel/time-travel.types.d.ts

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

package/src/enhancers/time-travel/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function deepClone<T>(obj: T): T;
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/src/enhancers/types.d.ts

@@ -0,0 +1 @@
+export { BatchingMethods, BatchingConfig, MemoizationMethods, MemoizationConfig, TimeTravelMethods, TimeTravelConfig, EffectsMethods, DevToolsMethods, DevToolsConfig, EntitiesEnabled, Enhancer, EnhancerWithMeta, EnhancerMeta, } from '../lib/types';

package/src/enhancers/typing/helpers-types.d.ts

@@ -0,0 +1,2 @@
+export type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+export type Assert<T extends true> = T;

package/src/index.d.ts

@@ -0,0 +1,17 @@
+export { signalTree } from './lib/signal-tree';
+export type { ISignalTree, SignalTree, SignalTreeBase, FullSignalTree, ProdSignalTree, TreeNode, CallableWritableSignal, AccessibleNode, NodeAccessor, Primitive, NotFn, TreeConfig, TreePreset, Enhancer, EnhancerMeta, EnhancerWithMeta, EntitySignal, EntityMapMarker, EntityConfig, MutationOptions, AddOptions, AddManyOptions, TimeTravelEntry, TimeTravelMethods, } from './lib/types';
+export { entityMap } from './lib/types';
+export { equal, deepEqual, isNodeAccessor, isAnySignal, toWritableSignal, parsePath, composeEnhancers, isBuiltInObject, createLazySignalTree, } from './lib/utils';
+export { getPathNotifier } from './lib/path-notifier';
+export { SecurityValidator, SecurityPresets, type SecurityEvent, type SecurityEventType, type SecurityValidatorConfig, } from './lib/security/security-validator';
+export { createEnhancer, resolveEnhancerOrder } from './enhancers/index';
+export { ENHANCER_META } from './lib/types';
+export { batching, highPerformanceBatching, flushBatchedUpdates, hasPendingUpdates, getBatchQueueSize, } from './enhancers/batching/batching';
+export { memoization, selectorMemoization, computedMemoization, deepStateMemoization, highFrequencyMemoization, highPerformanceMemoization, lightweightMemoization, shallowMemoization, memoize, memoizeShallow, memoizeReference, clearAllCaches, getGlobalCacheStats, } from './enhancers/memoization/memoization';
+export { timeTravel, enableTimeTravel, } from './enhancers/time-travel/time-travel';
+export { entities, enableEntities, highPerformanceEntities, } from './enhancers/entities/entities';
+export { serialization, enableSerialization, persistence, createStorageAdapter, createIndexedDBAdapter, applySerialization, applyPersistence, } from './enhancers/serialization/serialization';
+export { devTools, enableDevTools, fullDevTools, productionDevTools, } from './enhancers/devtools/devtools';
+export { createAsyncOperation, trackAsync } from './lib/async-helpers';
+export { TREE_PRESETS, createPresetConfig, validatePreset, getAvailablePresets, combinePresets, createDevTree, } from './enhancers/presets/lib/presets';
+export { SIGNAL_TREE_CONSTANTS, SIGNAL_TREE_MESSAGES } from './lib/constants';

package/src/lib/async-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { ISignalTree } from './types';
+export declare function createAsyncOperation<T, TResult>(name: string, operation: () => Promise<TResult>): (tree: ISignalTree<T>) => Promise<TResult>;
+export declare function trackAsync<T>(operation: () => Promise<T>): {
+    pending: import("@angular/core").Signal<boolean>;
+    error: import("@angular/core").Signal<Error | null>;
+    result: import("@angular/core").Signal<T | null>;
+    execute: () => Promise<T>;
+};

package/src/lib/constants.d.ts

@@ -0,0 +1,41 @@
+export declare const SIGNAL_TREE_CONSTANTS: {
+    readonly MAX_PATH_CACHE_SIZE: 1000;
+    readonly LAZY_THRESHOLD: 50;
+    readonly ESTIMATE_MAX_DEPTH: 3;
+    readonly ESTIMATE_SAMPLE_SIZE_ARRAY: 3;
+    readonly ESTIMATE_SAMPLE_SIZE_OBJECT: 5;
+    readonly DEFAULT_CACHE_SIZE: 100;
+    readonly DEFAULT_BATCH_SIZE: 10;
+};
+export declare const SIGNAL_TREE_MESSAGES: Readonly<{
+    readonly NULL_OR_UNDEFINED: "null/undefined";
+    readonly CIRCULAR_REF: "circular ref";
+    readonly UPDATER_INVALID: "updater invalid";
+    readonly LAZY_FALLBACK: "lazy fallback";
+    readonly SIGNAL_CREATION_FAILED: "signal creation failed";
+    readonly UPDATE_PATH_NOT_FOUND: "update path not found";
+    readonly UPDATE_FAILED: "update failed";
+    readonly ROLLBACK_FAILED: "rollback failed";
+    readonly CLEANUP_ERROR: "cleanup error";
+    readonly PRESET_UNKNOWN: "unknown preset";
+    readonly STRATEGY_SELECTION: "strategy select";
+    readonly TREE_DESTROYED: "destroyed";
+    readonly UPDATE_TRANSACTION: "update tx";
+    readonly BATCH_NOT_ENABLED: "batching disabled";
+    readonly MEMOIZE_NOT_ENABLED: "memoize disabled";
+    readonly MIDDLEWARE_NOT_AVAILABLE: "middleware missing";
+    readonly ENTITY_HELPERS_NOT_AVAILABLE: "entity helpers missing";
+    readonly TIME_TRAVEL_NOT_AVAILABLE: "time travel missing";
+    readonly OPTIMIZE_NOT_AVAILABLE: "optimize missing";
+    readonly UPDATE_OPTIMIZED_NOT_AVAILABLE: "update optimized missing";
+    readonly CACHE_NOT_AVAILABLE: "cache missing";
+    readonly PERFORMANCE_NOT_ENABLED: "performance disabled";
+    readonly ENHANCER_ORDER_FAILED: "enhancer order failed";
+    readonly ENHANCER_CYCLE_DETECTED: "enhancer cycle";
+    readonly ENHANCER_REQUIREMENT_MISSING: "enhancer req missing";
+    readonly ENHANCER_PROVIDES_MISSING: "enhancer provides missing";
+    readonly ENHANCER_FAILED: "enhancer failed";
+    readonly ENHANCER_NOT_FUNCTION: "enhancer not function";
+    readonly EFFECT_NO_CONTEXT: "no angular context";
+    readonly SUBSCRIBE_NO_CONTEXT: "no angular context";
+}>;

package/src/lib/dev-proxy.d.ts

@@ -0,0 +1,3 @@
+import type { ISignalTree } from './types';
+export declare function wrapWithDevProxy<T>(tree: ISignalTree<T>): ISignalTree<T>;
+export declare function shouldUseDevProxy(): boolean;

package/src/lib/entity-signal.d.ts

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

package/src/lib/memory/memory-manager.d.ts

@@ -0,0 +1,30 @@
+import type { WritableSignal } from '@angular/core';
+export interface MemoryStats {
+    cachedSignals: number;
+    cleanedUpSignals: number;
+    peakCachedSignals: number;
+    manualDisposes: number;
+    estimatedMemoryBytes: number;
+}
+export interface MemoryManagerConfig {
+    enableAutoCleanup?: boolean;
+    debugMode?: boolean;
+    onCleanup?: (path: string, stats: MemoryStats) => void;
+}
+export declare class SignalMemoryManager {
+    private cache;
+    private registry;
+    private config;
+    private stats;
+    constructor(config?: MemoryManagerConfig);
+    cacheSignal<T>(path: string, signal: WritableSignal<T>): void;
+    getSignal(path: string): WritableSignal<unknown> | undefined;
+    hasSignal(path: string): boolean;
+    removeSignal(path: string): boolean;
+    private handleCleanup;
+    getStats(): MemoryStats;
+    dispose(): void;
+    getCachedPaths(): string[];
+    clearStale(): number;
+    resetStats(): void;
+}

package/src/lib/path-notifier.d.ts

@@ -0,0 +1,4 @@
+export type PathNotifierInterceptor = (value: unknown, prev: unknown, path: string) => {
+    block?: boolean;
+    transform?: unknown;
+};

package/src/lib/performance/diff-engine.d.ts

@@ -0,0 +1,33 @@
+import type { Path } from './path-index';
+export declare enum ChangeType {
+    ADD = "add",
+    UPDATE = "update",
+    DELETE = "delete",
+    REPLACE = "replace"
+}
+export interface Change {
+    type: ChangeType;
+    path: Path;
+    value?: unknown;
+    oldValue?: unknown;
+}
+export interface Diff {
+    changes: Change[];
+    hasChanges: boolean;
+}
+export interface DiffOptions {
+    maxDepth?: number;
+    detectDeletions?: boolean;
+    ignoreArrayOrder?: boolean;
+    equalityFn?: (a: unknown, b: unknown) => boolean;
+    keyValidator?: (key: string) => boolean;
+}
+export declare class DiffEngine {
+    private defaultOptions;
+    diff(current: unknown, updates: unknown, options?: DiffOptions): Diff;
+    private traverse;
+    private diffArrays;
+    private diffArraysOrdered;
+    private diffArraysUnordered;
+    private stringify;
+}

package/src/lib/performance/path-index.d.ts

@@ -0,0 +1,25 @@
+import type { WritableSignal } from '@angular/core';
+export type PathSegment = string | number;
+export type Path = PathSegment[];
+export declare class PathIndex<T extends object = WritableSignal<any>> {
+    private root;
+    private pathCache;
+    private stats;
+    set(path: Path, signal: T): void;
+    get(path: Path): T | null;
+    has(path: Path): boolean;
+    getByPrefix(prefix: Path): Map<string, T>;
+    delete(path: Path): boolean;
+    clear(): void;
+    getStats(): {
+        hits: number;
+        misses: number;
+        sets: number;
+        cleanups: number;
+        hitRate: number;
+        cacheSize: number;
+    };
+    buildFromTree(tree: unknown, path?: Path): void;
+    private pathToString;
+    private collectDescendants;
+}

package/src/lib/performance/update-engine.d.ts

@@ -0,0 +1,32 @@
+import { PathIndex } from './path-index';
+import type { DiffOptions } from './diff-engine';
+export interface UpdateOptions extends DiffOptions {
+    batch?: boolean;
+    batchSize?: number;
+}
+export interface UpdateResult {
+    changed: boolean;
+    duration: number;
+    changedPaths: string[];
+    stats?: {
+        totalPaths: number;
+        optimizedPaths: number;
+        batchedUpdates: number;
+    };
+}
+export declare class OptimizedUpdateEngine {
+    private pathIndex;
+    private diffEngine;
+    constructor(tree: unknown);
+    update(tree: unknown, updates: unknown, options?: UpdateOptions): UpdateResult;
+    rebuildIndex(tree: unknown): void;
+    getIndexStats(): ReturnType<PathIndex['getStats']>;
+    private createPatches;
+    private createPatch;
+    private calculatePriority;
+    private sortPatches;
+    private applyPatches;
+    private batchApplyPatches;
+    private applyPatch;
+    private isEqual;
+}

package/src/lib/presets.d.ts

@@ -0,0 +1,34 @@
+import type { ISignalTree, TreeConfig, BatchingConfig, MemoizationConfig, TimeTravelConfig, DevToolsConfig, BatchingMethods, MemoizationMethods, TimeTravelMethods, DevToolsMethods, EffectsMethods, EntitiesEnabled } from './types';
+export interface DevTreeConfig extends TreeConfig {
+    effects?: Record<string, never>;
+    batching?: BatchingConfig;
+    memoization?: MemoizationConfig;
+    timeTravel?: TimeTravelConfig;
+    devTools?: DevToolsConfig;
+    entities?: Record<string, never>;
+}
+export interface ProdTreeConfig extends TreeConfig {
+    effects?: Record<string, never>;
+    batching?: BatchingConfig;
+    memoization?: MemoizationConfig;
+    entities?: Record<string, never>;
+}
+export interface MinimalTreeConfig extends TreeConfig {
+    effects?: Record<string, never>;
+}
+export type FullSignalTree<T> = ISignalTree<T> & EffectsMethods<T> & BatchingMethods & MemoizationMethods<T> & EntitiesEnabled & TimeTravelMethods & DevToolsMethods;
+export type ProdSignalTree<T> = ISignalTree<T> & EffectsMethods<T> & BatchingMethods & MemoizationMethods<T> & EntitiesEnabled;
+export type MinimalSignalTree<T> = ISignalTree<T> & EffectsMethods<T>;
+export declare function createDevTree<T extends object>(initialState: T, config?: DevTreeConfig): FullSignalTree<T>;
+export declare function createDevTree(): {
+    enhancer: <Tree extends ISignalTree<any>>(tree: Tree) => Tree & EffectsMethods<any> & BatchingMethods & MemoizationMethods<any> & EntitiesEnabled & TimeTravelMethods & DevToolsMethods;
+};
+export declare function createProdTree<T extends object>(initialState: T, config?: ProdTreeConfig): ProdSignalTree<T>;
+export declare function createMinimalTree<T extends object>(initialState: T, config?: MinimalTreeConfig): MinimalSignalTree<T>;
+export declare const devTree: typeof createDevTree;
+export declare const prodTree: typeof createProdTree;
+export declare const minimalTree: typeof createMinimalTree;
+export declare function buildTree<T extends object>(initialState: T, config?: TreeConfig): {
+    add<R>(enhancer: (t: ISignalTree<T>) => R): any;
+    done(): ISignalTree<T>;
+};

package/src/lib/security/security-validator.d.ts

@@ -0,0 +1,33 @@
+export type SecurityEventType = 'dangerous-key-blocked' | 'xss-attempt-blocked' | 'function-value-blocked' | 'validation-error';
+export interface SecurityEvent {
+    type: SecurityEventType;
+    key?: string;
+    value?: unknown;
+    reason: string;
+    timestamp: number;
+}
+export interface SecurityValidatorConfig {
+    preventPrototypePollution?: boolean;
+    preventXSS?: boolean;
+    preventFunctions?: boolean;
+    customDangerousKeys?: string[];
+    onSecurityEvent?: (event: SecurityEvent) => void;
+    sanitizationMode?: 'strict' | 'permissive';
+}
+export declare class SecurityValidator {
+    private readonly config;
+    private readonly dangerousKeys;
+    constructor(config?: SecurityValidatorConfig);
+    validateKey(key: string): void;
+    validateValue<T>(value: T): T;
+    private sanitize;
+    validateKeyValue<T>(key: string, value: T): T;
+    isDangerousKey(key: string): boolean;
+    getConfig(): Readonly<Required<SecurityValidatorConfig>>;
+}
+export declare const SecurityPresets: {
+    strict: () => SecurityValidator;
+    standard: () => SecurityValidator;
+    permissive: () => SecurityValidator;
+    disabled: () => SecurityValidator;
+};

package/src/lib/signal-tree.d.ts

@@ -0,0 +1,3 @@
+import type { TreeConfig, NodeAccessor, ISignalTree } from './types';
+export declare function isNodeAccessor(value: unknown): value is NodeAccessor<unknown>;
+export declare function signalTree<T extends object>(initialState: T, config?: TreeConfig): ISignalTree<T>;