@signaltree/core 7.1.5 → 7.3.0

package/src/lib/markers/entity-map.d.ts

@@ -0,0 +1,19 @@
+import { Signal } from '@angular/core';
+import { isEntityMapMarker } from '../utils';
+export { isEntityMapMarker };
+import type { EntityConfig, EntityMapMarker, EntitySignal } from '../types';
+export interface ComputedSliceConfig<E, R> {
+    compute: (entities: E[]) => R;
+}
+export type EntitySignalWithSlices<E, K extends string | number, Slices extends Record<string, unknown>> = EntitySignal<E, K> & {
+    [P in keyof Slices]: Signal<Slices[P]>;
+};
+export interface EntityMapBuilder<E, K extends string | number, Slices extends Record<string, unknown> = Record<string, never>> extends EntityMapMarker<E, K> {
+    __computedSlices?: EntityMapComputedSlices<E>;
+    __sliceTypes?: Slices;
+    computed<N extends string, R>(name: N, compute: (entities: E[]) => R): EntityMapBuilder<E, K, Slices & Record<N, R>>;
+    build(): EntityMapMarkerWithSlices<E, K, Slices>;
+}
+export declare function entityMap<E, K extends string | number = E extends {
+    id: infer I extends string | number;
+} ? I : string>(config?: EntityConfig<E, K>): EntityMapBuilder<E, K, Record<string, never>>;

package/src/lib/markers/form.d.ts

@@ -0,0 +1,86 @@
+import { Signal } from '@angular/core';
+export declare const FORM_MARKER: unique symbol;
+export type Validator<T> = (value: T) => string | null;
+export type AsyncValidator<T> = (value: T) => Promise<string | null>;
+export interface WizardStepConfig {
+    fields?: string[];
+    validate?: () => Promise<boolean> | boolean;
+    canSkip?: boolean;
+}
+export interface WizardConfig {
+    steps: string[];
+    stepConfig?: Record<string, WizardStepConfig>;
+    stepFields?: Record<string, string[]>;
+}
+export interface FormConfig<T extends Record<string, unknown>> {
+    initial: T;
+    persist?: string;
+    storage?: Storage | null;
+    persistDebounceMs?: number;
+    validators?: Partial<Record<keyof T, Validator<unknown> | Validator<unknown>[]>>;
+    asyncValidators?: Partial<Record<keyof T, AsyncValidator<unknown>>>;
+    wizard?: WizardConfig;
+    equalityFn?: (a: unknown, b: unknown) => boolean;
+}
+export interface FormMarker<T extends Record<string, unknown>> {
+    [FORM_MARKER]: true;
+    config: FormConfig<T>;
+}
+export interface FormWizard {
+    currentStep: Signal<number>;
+    stepName: Signal<string>;
+    steps: Signal<string[]>;
+    canNext: Signal<boolean>;
+    canPrev: Signal<boolean>;
+    isLastStep: Signal<boolean>;
+    isFirstStep: Signal<boolean>;
+    next(): Promise<boolean>;
+    prev(): void;
+    goTo(step: number | string): Promise<boolean>;
+    reset(): void;
+}
+export type FormFields<T> = {
+    [K in keyof T]: T[K] extends Record<string, unknown> ? FormFields<T[K]> & {
+        (): T[K];
+        set(value: T[K]): void;
+    } : {
+        (): T[K];
+        set(value: T[K]): void;
+        update(fn: (current: T[K]) => T[K]): void;
+    };
+};
+export interface FormSignal<T extends Record<string, unknown>> {
+    $: FormFields<T>;
+    (): T;
+    set(values: Partial<T>): void;
+    patch(values: Partial<T>): void;
+    reset(): void;
+    clear(): void;
+    valid: Signal<boolean>;
+    dirty: Signal<boolean>;
+    submitting: Signal<boolean>;
+    touched: Signal<Record<keyof T, boolean>>;
+    errors: Signal<Partial<Record<keyof T, string | null>>>;
+    errorList: Signal<string[]>;
+    validate(): Promise<boolean>;
+    validateField(field: keyof T): Promise<boolean>;
+    touch(field: keyof T): void;
+    touchAll(): void;
+    submit<R>(handler: (values: T) => Promise<R>): Promise<R | null>;
+    wizard?: FormWizard;
+    persistNow(): void;
+    reload(): void;
+    clearStorage(): void;
+}
+export declare function form<T extends Record<string, unknown>>(config: FormConfig<T>): FormMarker<T>;
+export declare function isFormMarker(value: unknown): value is FormMarker<Record<string, unknown>>;
+export declare const validators: {
+    required: (message?: string) => (value: unknown) => string | null;
+    minLength: (min: number, message?: string) => (value: unknown) => string | null;
+    maxLength: (max: number, message?: string) => (value: unknown) => string | null;
+    min: (min: number, message?: string) => (value: unknown) => string | null;
+    max: (max: number, message?: string) => (value: unknown) => string | null;
+    email: (message?: string) => (value: unknown) => string | null;
+    pattern: (regex: RegExp, message?: string) => (value: unknown) => string | null;
+    when: <T>(condition: (form: T) => boolean, validator: Validator<unknown>) => (value: unknown, form?: T) => string | null;
+};

package/src/lib/markers/index.d.ts

@@ -0,0 +1,4 @@
+export { isDerivedMarker, getDerivedMarkerSymbol, type DerivedMarker, type DerivedType, } from './derived';
+export { status, isStatusMarker, createStatusSignal, LoadingState, STATUS_MARKER, type StatusMarker, type StatusSignal, type StatusConfig, } from './status';
+export { stored, isStoredMarker, createStoredSignal, createStorageKeys, clearStoragePrefix, STORED_MARKER, type StoredMarker, type StoredSignal, type StoredOptions, type MigrationFn, } from './stored';
+export { form, isFormMarker, createFormSignal, validators, FORM_MARKER, type FormMarker, type FormSignal, type FormConfig, type FormFields, type FormWizard, type WizardConfig, type WizardStepConfig, type Validator, type AsyncValidator, } from './form';

package/src/lib/markers/status.d.ts

@@ -0,0 +1,32 @@
+import { Signal, WritableSignal } from '@angular/core';
+export declare const STATUS_MARKER: unique symbol;
+export declare enum LoadingState {
+    NotLoaded = "NOT_LOADED",
+    Loading = "LOADING",
+    Loaded = "LOADED",
+    Error = "ERROR"
+}
+export interface StatusConfig {
+    initialState?: LoadingState;
+}
+export interface StatusMarker<E = Error> {
+    [STATUS_MARKER]: true;
+    initialState: LoadingState;
+    readonly __errorType?: E;
+}
+export interface StatusSignal<E = Error> {
+    state: WritableSignal<LoadingState>;
+    error: WritableSignal<E | null>;
+    isNotLoaded: Signal<boolean>;
+    isLoading: Signal<boolean>;
+    isLoaded: Signal<boolean>;
+    isError: Signal<boolean>;
+    setNotLoaded(): void;
+    setLoading(): void;
+    setLoaded(): void;
+    setError(error: E): void;
+    reset(): void;
+}
+export declare function status<E = Error>(initialState?: LoadingState): StatusMarker<E>;
+export declare function isStatusMarker(value: unknown): value is StatusMarker;
+export declare function createStatusSignal<E = Error>(marker: StatusMarker<E>): StatusSignal<E>;

package/src/lib/markers/stored.d.ts

@@ -0,0 +1,35 @@
+export declare const STORED_MARKER: unique symbol;
+export type MigrationFn<T> = (oldData: unknown, oldVersion: number) => T;
+export interface StoredOptions<T> {
+    serialize?: (value: T) => string;
+    deserialize?: (stored: string) => T;
+    storage?: Storage | null;
+    debounceMs?: number;
+    version?: number;
+    migrate?: MigrationFn<T>;
+    clearOnMigrationFailure?: boolean;
+}
+type StorageKeyMap<T, Prefix extends string> = {
+    [K in keyof T]: T[K] extends string ? `${Prefix}:${T[K] & string}` : T[K] extends object ? StorageKeyMap<T[K], `${Prefix}:${K & string}`> : never;
+};
+export declare function createStorageKeys<T extends object, P extends string>(prefix: P, keys: T): StorageKeyMap<T, P>;
+export declare function clearStoragePrefix(prefix: string, storage?: Storage): void;
+export interface StoredMarker<T> {
+    [STORED_MARKER]: true;
+    key: string;
+    defaultValue: T;
+    options: StoredOptions<T>;
+}
+export interface StoredSignal<T> {
+    (): T;
+    set(value: T): void;
+    update(fn: (current: T) => T): void;
+    clear(): void;
+    reload(): void;
+    readonly key: string;
+    readonly version: number;
+}
+export declare function stored<T>(key: string, defaultValue: T, options?: StoredOptions<T>): StoredMarker<T>;
+export declare function isStoredMarker(value: unknown): value is StoredMarker<unknown>;
+export declare function createStoredSignal<T>(marker: StoredMarker<T>): StoredSignal<T>;
+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,34 @@
+export type PathNotifierInterceptor = (value: unknown, prev: unknown, path: string) => {
+    block?: boolean;
+    transform?: unknown;
+};
+export declare class PathNotifier {
+    private subscribers;
+    private interceptors;
+    private batchingEnabled;
+    private pendingFlush;
+    private pending;
+    private firstValues;
+    private flushCallbacks;
+    constructor(options?: {
+        batching?: boolean;
+    });
+    setBatchingEnabled(enabled: boolean): void;
+    isBatchingEnabled(): boolean;
+    subscribe(pattern: string, handler: PathNotifierHandler): () => void;
+    intercept(pattern: string, interceptor: PathNotifierInterceptor): () => void;
+    notify(path: string, value: unknown, prev: unknown): {
+        blocked: boolean;
+        value: unknown;
+    };
+    private _runNotify;
+    private flush;
+    flushSync(): void;
+    onFlush(callback: () => void): () => void;
+    hasPending(): boolean;
+    private matches;
+    clear(): void;
+    getSubscriberCount(): number;
+    getInterceptorCount(): number;
+}
+export declare function getPathNotifier(): PathNotifier;

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: <T>(tree: ISignalTree<T>) => ISignalTree<T> & EffectsMethods<T> & BatchingMethods<T> & MemoizationMethods<T> & EntitiesEnabled & TimeTravelMethods<T> & 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,6 @@
+import { SignalTreeBuilder } from './internals/builder-types';
+import { ProcessDerived } from './internals/derived-types';
+import type { TreeNode, TreeConfig, NodeAccessor } from './types';
+export declare function isNodeAccessor(value: unknown): value is NodeAccessor<unknown>;
+export declare function signalTree<T extends object, TDerived extends object>(initialState: T, derivedFactory: ($: TreeNode<T>) => TDerived): SignalTreeBuilder<T, TreeNode<T> & ProcessDerived<TDerived>>;
+export declare function signalTree<T extends object>(initialState: T, config?: TreeConfig): SignalTreeBuilder<T, TreeNode<T>>;