@asaidimu/utils-store 2.0.0 → 2.0.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.mts

@@ -0,0 +1,287 @@
+import { S as SimplePersistence } from '../types-D26luDbE.js';
+
+/**
+ * Utility type for representing partial updates to the state.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] | symbol;
+};
+/**
+ * Interface for performance metrics of the state.
+ */
+interface StoreMetrics {
+    updateCount: number;
+    listenerExecutions: number;
+    averageUpdateTime: number;
+    largestUpdateSize: number;
+    mostActiveListenerPaths: string[];
+}
+/**
+ * Extended store state for monitoring execution status
+ */
+interface StoreExecutionState<T> {
+    executing: boolean;
+    changes: DeepPartial<T> | null;
+    pendingChanges: Array<StateUpdater<T>>;
+    middlewares: string[];
+    runningMiddleware: {
+        id: string;
+        name: string;
+        startTime: number;
+    } | null;
+    transactionActive: boolean;
+}
+/**
+ * Event types emitted by the state for observability
+ */
+type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready";
+/**
+ * Type for middleware functions. Return a partial state to transform the update.
+ */
+type Middleware<T> = (state: T, update: DeepPartial<T>) => Promise<DeepPartial<T>> | Promise<void> | DeepPartial<T> | void;
+/**
+ * Type for blocking middleware functions that can prevent updates.
+ */
+type BlockingMiddleware<T> = (state: T, update: DeepPartial<T>) => boolean | Promise<boolean>;
+/**
+ * Middleware execution information for event emissions
+ */
+interface MiddlewareExecution {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    blocked: boolean;
+    error?: Error;
+    changedPaths: string[];
+}
+/**
+ * Represents a state update, which can be either a partial state object or a function.
+ */
+type StateUpdater<T> = DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
+/**
+ * Interface defining the contract for the data state.
+ */
+interface DataStore<T extends object> {
+    get(clone?: boolean): T;
+    set(update: StateUpdater<T>): Promise<void>;
+    subscribe(path: string, listener: (state: T) => void): () => void;
+    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    metrics(): StoreMetrics;
+    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+}
+/**
+ * Type representing the configuration object passed to `use`.
+ */
+type MiddlewareConfig<T> = {
+    name?: string;
+} & ({
+    block: true;
+    action: BlockingMiddleware<T>;
+} | {
+    block?: false;
+    action: Middleware<T>;
+});
+declare const DELETE_SYMBOL: unique symbol;
+
+/**
+ * Reactive Data Store Implementation
+ * A type-safe reactive data state for managing complex application state.
+ * Arrays are treated as primitive values (stored and updated as whole units).
+ */
+
+/**
+ * Main ReactiveDataStore - now acts as a coordinator between components
+ */
+declare class ReactiveDataStore<T extends object> implements DataStore<T> {
+    private coreState;
+    private middlewareEngine;
+    private persistenceHandler;
+    private transactionManager;
+    private metricsCollector;
+    private pendingUpdates;
+    private isUpdating;
+    private updateBus;
+    private eventBus;
+    private executionState;
+    private instanceID;
+    private merge;
+    private diff;
+    constructor(initialData: T, persistence?: SimplePersistence<T>, deleteMarker?: symbol);
+    isReady(): boolean;
+    state(): Readonly<StoreExecutionState<T>>;
+    get(clone?: boolean): T;
+    set(update: StateUpdater<T>): Promise<void>;
+    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    id(): string;
+    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    use(props: MiddlewareConfig<T>): string;
+    unuse(id: string): boolean;
+    /** @deprecated  WILL BE REMOVED*/
+    metrics(): StoreMetrics;
+    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+}
+
+/**
+ * Store Observability Module
+ * A separate module to add debugging and observability capabilities to the ReactiveDataStore.
+ */
+
+/**
+ * Interface for debug event structure
+ */
+interface DebugEvent {
+    type: string;
+    timestamp: number;
+    data: any;
+}
+/**
+ * Configuration options for the observability module
+ */
+interface ObservabilityOptions {
+    /** Maximum number of events to keep in history */
+    maxEvents?: number;
+    /** Whether to enable console logging */
+    enableConsoleLogging?: boolean;
+    maxStateHistory?: number;
+    /** Options for specific event types to log */
+    logEvents?: {
+        updates?: boolean;
+        middleware?: boolean;
+        transactions?: boolean;
+    };
+    /** Time threshold in ms to highlight slow operations */
+    performanceThresholds?: {
+        updateTime?: number;
+        middlewareTime?: number;
+    };
+}
+/**
+ * Class for observing and debugging a ReactiveDataStore instance
+ */
+declare class StoreObserver<T extends object> {
+    protected store: DataStore<T>;
+    private eventHistory;
+    private maxEvents;
+    private enableConsoleLogging;
+    private logEvents;
+    private performanceThresholds;
+    private unsubscribers;
+    private stateHistory;
+    private maxStateHistory;
+    private activeTransactionCount;
+    private activeBatches;
+    private middlewareExecutions;
+    /**
+     * Creates a new StoreObservability instance
+     * @param store The ReactiveDataStore to observe
+     * @param options Configuration options
+     */
+    constructor(store: DataStore<T>, options?: ObservabilityOptions);
+    /**
+     * Sets up all event listeners
+     */
+    private setupEventListeners;
+    /**
+     * Records a state snapshot
+     */
+    private recordStateSnapshot;
+    /**
+     * Records an event to the history
+     * @param type Event type
+     * @param data Event data
+     */
+    private recordEvent;
+    /**
+     * Logs an event to the console with appropriate formatting
+     * @param type Event type
+     * @param data Event data
+     */
+    private logEventToConsole;
+    /**
+     * Checks for performance issues in the events
+     * @param type Event type
+     * @param data Event data
+     */
+    private checkPerformance;
+    /**
+     * Returns the event history
+     * @returns Array of debug events
+     */
+    getEventHistory(): DebugEvent[];
+    /**
+     * Returns the state history
+     * @returns Array of state snapshots
+     */
+    getStateHistory(): T[];
+    /**
+     * Returns middleware execution history from the state
+     * @returns Array of middleware executions
+     */
+    getMiddlewareExecutions(): MiddlewareExecution[];
+    /**
+     * Returns state performance metrics
+     * @returns Store metrics object
+     */
+    getPerformanceMetrics(): StoreMetrics;
+    /**
+     * Returns current transaction status
+     * @returns Object with transaction status information
+     */
+    getTransactionStatus(): {
+        activeTransactions: number;
+        activeBatches: string[];
+    };
+    /**
+     * Creates a middleware that logs all updates
+     * @param options Options for the logging middleware
+     * @returns A middleware function
+     */
+    createLoggingMiddleware(options?: {
+        logLevel?: "debug" | "info" | "warn";
+        logUpdates?: boolean;
+    }): (state: T, update: DeepPartial<T>) => DeepPartial<T>;
+    /**
+     * Creates a middleware that validates updates against a schema
+     * @param validator Function that validates updates
+     * @returns A blocking middleware function
+     */
+    createValidationMiddleware(validator: (state: T, update: DeepPartial<T>) => boolean | {
+        valid: boolean;
+        reason?: string;
+    }): (state: T, update: DeepPartial<T>) => boolean;
+    /**
+     * Clears all event and state history
+     */
+    clearHistory(): void;
+    /**
+     * Returns a simplified view of recent state changes
+     * @param limit Maximum number of state changes to compare
+     * @returns Array of state difference objects
+     */
+    getRecentChanges(limit?: number): Array<{
+        timestamp: number;
+        changedPaths: string[];
+        from: Partial<T>;
+        to: Partial<T>;
+    }>;
+    /**
+     * Creates a time-travel debug middleware that lets you undo/redo state changes
+     * @returns An object with undo/redo methods and state info
+     */
+    createTimeTravel(): {
+        canUndo: () => boolean;
+        canRedo: () => boolean;
+        undo: () => void;
+        redo: () => void;
+        getHistoryLength: () => number;
+        clear: () => void;
+    };
+    /**
+     * Disconnects all event listeners and cleans up resources
+     */
+    disconnect(): void;
+}
+
+export { type BlockingMiddleware, DELETE_SYMBOL, type DataStore, type DebugEvent, type DeepPartial, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObservabilityOptions, ReactiveDataStore, type StateUpdater, type StoreEvent, type StoreExecutionState, type StoreMetrics, StoreObserver };

package/index.d.ts

@@ -0,0 +1,287 @@
+import { S as SimplePersistence } from '../types-D26luDbE.js';
+
+/**
+ * Utility type for representing partial updates to the state.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] | symbol;
+};
+/**
+ * Interface for performance metrics of the state.
+ */
+interface StoreMetrics {
+    updateCount: number;
+    listenerExecutions: number;
+    averageUpdateTime: number;
+    largestUpdateSize: number;
+    mostActiveListenerPaths: string[];
+}
+/**
+ * Extended store state for monitoring execution status
+ */
+interface StoreExecutionState<T> {
+    executing: boolean;
+    changes: DeepPartial<T> | null;
+    pendingChanges: Array<StateUpdater<T>>;
+    middlewares: string[];
+    runningMiddleware: {
+        id: string;
+        name: string;
+        startTime: number;
+    } | null;
+    transactionActive: boolean;
+}
+/**
+ * Event types emitted by the state for observability
+ */
+type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready";
+/**
+ * Type for middleware functions. Return a partial state to transform the update.
+ */
+type Middleware<T> = (state: T, update: DeepPartial<T>) => Promise<DeepPartial<T>> | Promise<void> | DeepPartial<T> | void;
+/**
+ * Type for blocking middleware functions that can prevent updates.
+ */
+type BlockingMiddleware<T> = (state: T, update: DeepPartial<T>) => boolean | Promise<boolean>;
+/**
+ * Middleware execution information for event emissions
+ */
+interface MiddlewareExecution {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    blocked: boolean;
+    error?: Error;
+    changedPaths: string[];
+}
+/**
+ * Represents a state update, which can be either a partial state object or a function.
+ */
+type StateUpdater<T> = DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
+/**
+ * Interface defining the contract for the data state.
+ */
+interface DataStore<T extends object> {
+    get(clone?: boolean): T;
+    set(update: StateUpdater<T>): Promise<void>;
+    subscribe(path: string, listener: (state: T) => void): () => void;
+    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    metrics(): StoreMetrics;
+    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+}
+/**
+ * Type representing the configuration object passed to `use`.
+ */
+type MiddlewareConfig<T> = {
+    name?: string;
+} & ({
+    block: true;
+    action: BlockingMiddleware<T>;
+} | {
+    block?: false;
+    action: Middleware<T>;
+});
+declare const DELETE_SYMBOL: unique symbol;
+
+/**
+ * Reactive Data Store Implementation
+ * A type-safe reactive data state for managing complex application state.
+ * Arrays are treated as primitive values (stored and updated as whole units).
+ */
+
+/**
+ * Main ReactiveDataStore - now acts as a coordinator between components
+ */
+declare class ReactiveDataStore<T extends object> implements DataStore<T> {
+    private coreState;
+    private middlewareEngine;
+    private persistenceHandler;
+    private transactionManager;
+    private metricsCollector;
+    private pendingUpdates;
+    private isUpdating;
+    private updateBus;
+    private eventBus;
+    private executionState;
+    private instanceID;
+    private merge;
+    private diff;
+    constructor(initialData: T, persistence?: SimplePersistence<T>, deleteMarker?: symbol);
+    isReady(): boolean;
+    state(): Readonly<StoreExecutionState<T>>;
+    get(clone?: boolean): T;
+    set(update: StateUpdater<T>): Promise<void>;
+    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    id(): string;
+    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    use(props: MiddlewareConfig<T>): string;
+    unuse(id: string): boolean;
+    /** @deprecated  WILL BE REMOVED*/
+    metrics(): StoreMetrics;
+    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+}
+
+/**
+ * Store Observability Module
+ * A separate module to add debugging and observability capabilities to the ReactiveDataStore.
+ */
+
+/**
+ * Interface for debug event structure
+ */
+interface DebugEvent {
+    type: string;
+    timestamp: number;
+    data: any;
+}
+/**
+ * Configuration options for the observability module
+ */
+interface ObservabilityOptions {
+    /** Maximum number of events to keep in history */
+    maxEvents?: number;
+    /** Whether to enable console logging */
+    enableConsoleLogging?: boolean;
+    maxStateHistory?: number;
+    /** Options for specific event types to log */
+    logEvents?: {
+        updates?: boolean;
+        middleware?: boolean;
+        transactions?: boolean;
+    };
+    /** Time threshold in ms to highlight slow operations */
+    performanceThresholds?: {
+        updateTime?: number;
+        middlewareTime?: number;
+    };
+}
+/**
+ * Class for observing and debugging a ReactiveDataStore instance
+ */
+declare class StoreObserver<T extends object> {
+    protected store: DataStore<T>;
+    private eventHistory;
+    private maxEvents;
+    private enableConsoleLogging;
+    private logEvents;
+    private performanceThresholds;
+    private unsubscribers;
+    private stateHistory;
+    private maxStateHistory;
+    private activeTransactionCount;
+    private activeBatches;
+    private middlewareExecutions;
+    /**
+     * Creates a new StoreObservability instance
+     * @param store The ReactiveDataStore to observe
+     * @param options Configuration options
+     */
+    constructor(store: DataStore<T>, options?: ObservabilityOptions);
+    /**
+     * Sets up all event listeners
+     */
+    private setupEventListeners;
+    /**
+     * Records a state snapshot
+     */
+    private recordStateSnapshot;
+    /**
+     * Records an event to the history
+     * @param type Event type
+     * @param data Event data
+     */
+    private recordEvent;
+    /**
+     * Logs an event to the console with appropriate formatting
+     * @param type Event type
+     * @param data Event data
+     */
+    private logEventToConsole;
+    /**
+     * Checks for performance issues in the events
+     * @param type Event type
+     * @param data Event data
+     */
+    private checkPerformance;
+    /**
+     * Returns the event history
+     * @returns Array of debug events
+     */
+    getEventHistory(): DebugEvent[];
+    /**
+     * Returns the state history
+     * @returns Array of state snapshots
+     */
+    getStateHistory(): T[];
+    /**
+     * Returns middleware execution history from the state
+     * @returns Array of middleware executions
+     */
+    getMiddlewareExecutions(): MiddlewareExecution[];
+    /**
+     * Returns state performance metrics
+     * @returns Store metrics object
+     */
+    getPerformanceMetrics(): StoreMetrics;
+    /**
+     * Returns current transaction status
+     * @returns Object with transaction status information
+     */
+    getTransactionStatus(): {
+        activeTransactions: number;
+        activeBatches: string[];
+    };
+    /**
+     * Creates a middleware that logs all updates
+     * @param options Options for the logging middleware
+     * @returns A middleware function
+     */
+    createLoggingMiddleware(options?: {
+        logLevel?: "debug" | "info" | "warn";
+        logUpdates?: boolean;
+    }): (state: T, update: DeepPartial<T>) => DeepPartial<T>;
+    /**
+     * Creates a middleware that validates updates against a schema
+     * @param validator Function that validates updates
+     * @returns A blocking middleware function
+     */
+    createValidationMiddleware(validator: (state: T, update: DeepPartial<T>) => boolean | {
+        valid: boolean;
+        reason?: string;
+    }): (state: T, update: DeepPartial<T>) => boolean;
+    /**
+     * Clears all event and state history
+     */
+    clearHistory(): void;
+    /**
+     * Returns a simplified view of recent state changes
+     * @param limit Maximum number of state changes to compare
+     * @returns Array of state difference objects
+     */
+    getRecentChanges(limit?: number): Array<{
+        timestamp: number;
+        changedPaths: string[];
+        from: Partial<T>;
+        to: Partial<T>;
+    }>;
+    /**
+     * Creates a time-travel debug middleware that lets you undo/redo state changes
+     * @returns An object with undo/redo methods and state info
+     */
+    createTimeTravel(): {
+        canUndo: () => boolean;
+        canRedo: () => boolean;
+        undo: () => void;
+        redo: () => void;
+        getHistoryLength: () => number;
+        clear: () => void;
+    };
+    /**
+     * Disconnects all event listeners and cleans up resources
+     */
+    disconnect(): void;
+}
+
+export { type BlockingMiddleware, DELETE_SYMBOL, type DataStore, type DebugEvent, type DeepPartial, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObservabilityOptions, ReactiveDataStore, type StateUpdater, type StoreEvent, type StoreExecutionState, type StoreMetrics, StoreObserver };