@asaidimu/react-store 1.5.0 → 2.0.0

package/index.d.cts

@@ -1,418 +1,9 @@
-/**
- * Interface for persistence adapters
- */
-interface DataStorePersistence<T> {
-    /**
-     * Persists data to storage
-     * @param id The id of the consumer instance, not of the data/state being
-     * persisted. The consumer instance should implement some mechanism to
-     * identify itself. Best done with a uuid created at instantiation.
-     * @param state The state to persist
-     * @returns boolean indicating success or Promise resolving to success status
-     */
-    set(id: string, state: T): boolean | Promise<boolean>;
-    /**
-     * Retrieves persisted data from storage
-     * @returns The retrieved state or null if not found
-     */
-    get(): T | null | Promise<T | null>;
-    /**
-     * Subscribes to changes in persisted data (e.g., from other tabs/instances)
-     * if persistence is shared
-     * @param id The id of the consumer instance
-     * @param callback Function to call when persisted data changes
-     * @returns Function to unsubscribe
-     */
-    subscribe(id: string, callback: (state: T) => void): () => void;
-    /**
-     * Clears the persisted data
-     * @returns true if successful
-     */
-    clear(): boolean | Promise<boolean>;
-}
-
-/**
- * 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).
- */
-
-/**
- * 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" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready";
-/**
- * Type for middleware functions. Return false to block 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 tracking
- */
-interface MiddlewareExecution {
-    id: string;
-    name: string;
-    startTime: number;
-    endTime: number;
-    duration: number;
-    blocked: boolean;
-    error?: Error;
-}
-/**
- * Represents a state update, which can be either a partial state object or a function.
- *
- * The function can be synchronous or asynchronous, and it receives the current state
- * as an argument and returns a partial state object.
- *
- * @template T The type of the state object.
- */
-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>;
-    getPerformanceMetrics(): StoreMetrics;
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
-    getMiddlewareExecutions(): MiddlewareExecution[];
-}
-/**
- * Implementation of the reactive data state.
- */
-declare class ReactiveDataStore<T extends object> implements DataStore<T> {
-    private readonly metrics;
-    private middleware;
-    private blockingMiddleware;
-    private middlewareExecutions;
-    private readonly maxExecutionHistory;
-    private pendingUpdates;
-    private isUpdating;
-    private updateTimes;
-    private cache;
-    private updateBus;
-    private eventBus;
-    private executionState;
-    private persistence?;
-    private instanceID;
-    private persistenceReady;
-    /**
-     * Creates a new instance of ReactiveDataStore.
-     * @param initialData The initial state data.
-     */
-    constructor(initialData: T, persistence?: DataStorePersistence<T>);
-    private setPersistenceReady;
-    private setPersistence;
-    isReady(): boolean;
-    /**
-     * Gets current execution state for monitoring
-     * @returns The current execution state of the store
-     */
-    getExecutionState(): Readonly<StoreExecutionState<T>>;
-    /**
-     * Gets a specific part of the state at the given path.
-     * @returns The current state
-     */
-    get(clone?: boolean): T;
-    /**
-     * Updates the state with the provided partial state.
-     * @param update The partial state to update with.
-     */
-    set(update: StateUpdater<T>): Promise<void>;
-    /**
-     * Applies blocking middleware to the update.
-     * If any middleware returns false or throws, the update is blocked.
-     *
-     * @param partialUpdate The partial update to apply middlewares to
-     * @returns Result indicating if update was blocked and any error
-     */
-    private applyBlockingMiddleware;
-    /**
-     * Applies a chain of middleware functions to an initial state.
-     *
-     * @template T The type of the state object.
-     * @param initialState The initial state to be transformed.
-     * @param partialUpdate The original partial update (for context)
-     * @returns The final transformed state.
-     */
-    private applyMiddleware;
-    /**
-     * Subscribes a callback function to changes in the data at the specified path.
-     * @param path The path to subscribe to.
-     * @param callback The callback function to call when the path changes.
-     * @returns Function to unsubscribe the listener.
-     */
-    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
-    /**
-     * returns instance id
-     * @param path The path to subscribe to.
-     * @param callback The callback function to call when the path changes.
-     * @returns Function to unsubscribe the listener.
-     */
-    id(): string;
-    /**
-     * Executes an operation within a transaction that can be rolled back if an error occurs.
-     * @param operation The operation to execute.
-     * @returns The result of the operation.
-     */
-    /**
-     * Executes an operation within a transaction that can be rolled back if an error occurs.
-     * @param operation The operation to execute.
-     * @returns The result of the operation.
-     */
-    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
-    /**
-     * Adds a transformation middleware to the state.
-     * These middleware functions can modify updates but cannot block them.
-     *
-     * @param middleware The middleware function
-     * @param name Optional name for the middleware (for debugging)
-     * @returns ID of the registered middleware for removal
-     */
-    use(middleware: Middleware<T>, name?: string): string;
-    /**
-     * Adds a blocking middleware to the state.
-     * These middleware functions can block updates by returning false or throwing.
-     *
-     * @param middleware The blocking middleware function
-     * @param name Optional name for the middleware (for debugging)
-     * @returns ID of the registered middleware for removal
-     */
-    useBlockingMiddleware(middleware: BlockingMiddleware<T>, name?: string): string;
-    /**
-     * Removes a middleware by ID
-     * @param id The middleware ID to remove
-     * @returns true if middleware was found and removed
-     */
-    removeMiddleware(id: string): boolean;
-    /**
-     * Returns current performance metrics of the state.
-     * @returns The state metrics.
-     */
-    getPerformanceMetrics(): StoreMetrics;
-    /**
-     * Returns the history of middleware executions.
-     * @returns Array of middleware execution information
-     */
-    getMiddlewareExecutions(): MiddlewareExecution[];
-    /**
-     * Subscribe to state events for observability
-     * @param event Event type to listen for
-     * @param listener Callback function when event occurs
-     * @returns Function to unsubscribe
-     */
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
-    /**
-     * Notifies listeners whose subscribed paths are affected by the changes.
-     * @param changedPaths Array of paths that have changed.
-     */
-    private notifyListeners;
-    /**
-     * Tracks middleware execution for debugging purposes
-     * @param execution The middleware execution information
-     */
-    private trackMiddlewareExecution;
-}
-
-/**
- * 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 StoreObservability<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;
-    /**
-     * 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;
-}
+import { SimplePersistence } from '@asaidimu/utils-persistence';
+import { ObservabilityOptions, DeepPartial, BlockingMiddleware, Middleware, ReactiveDataStore, StoreObserver } from '@asaidimu/utils-store';
 
 type StoreOptions<T> = ObservabilityOptions & {
     enableMetrics?: boolean;
-    persistence?: DataStorePersistence<T>;
+    persistence?: SimplePersistence<T>;
 };
 type Action<T> = (state: T, ...args: any[]) => DeepPartial<T>;
 type StoreSelector<T, S> = (state: T) => S;
@@ -462,7 +53,7 @@ declare function createStore<T extends Record<string, unknown>, R extends Action
     /** Direct store instance access */
     readonly store: ReactiveDataStore<T>;
     /** Performance monitoring tools when enabled */
-    readonly observer: StoreObservability<T> | undefined;
+    readonly observer: StoreObserver<T> | undefined;
     /** Selector creator for subscribing to specific state */
     readonly select: <S>(selector: (state: T) => S) => S;
     /** Action dispatchers */
@@ -474,304 +65,4 @@ declare function createStore<T extends Record<string, unknown>, R extends Action
     readonly state: () => T;
 };
 
-/**
- * Configuration for external metrics destination
- */
-interface RemoteDestination {
-    /** Unique identifier for this destination */
-    id: string;
-    /** Human-readable name of the destination */
-    name: string;
-    /** Function that handles sending metrics to the destination */
-    send: (payload: RemoteMetricsPayload) => Promise<void>;
-    /** Optional function to test connection to the destination */
-    testConnection?: () => Promise<boolean>;
-    /** Optional configuration for this destination */
-    config?: Record<string, any>;
-}
-/**
- * Types of metrics that can be sent remotely
- */
-type MetricType = 'counter' | 'gauge' | 'histogram' | 'log' | 'trace';
-/**
- * Structure for remote metric payloads
- */
-interface RemoteMetricsPayload {
-    /** Timestamp when the metrics were collected */
-    timestamp: number;
-    /** Source identifier (app name, instance ID, etc.) */
-    source: string;
-    /** Collection of metrics being reported */
-    metrics: Array<{
-        /** Metric name (should follow naming conventions) */
-        name: string;
-        /** Type of metric */
-        type: MetricType;
-        /** Value of the metric */
-        value: number | string | object;
-        /** Optional units for the metric */
-        unit?: string;
-        /** Contextual labels/tags for the metric */
-        labels?: Record<string, string>;
-        /** For trace type, references to parent spans */
-        parentId?: string;
-        /** For trace type, trace ID for grouping spans */
-        traceId?: string;
-    }>;
-}
-/**
- * Configuration options for RemoteObservability
- */
-interface RemoteObservabilityOptions extends ObservabilityOptions {
-    /** Application/service name */
-    serviceName: string;
-    /** Environment (prod, staging, dev) */
-    environment: string;
-    /** Instance identifier (for distributed systems) */
-    instanceId?: string;
-    /** How frequently to send batched metrics (ms) */
-    reportingInterval?: number;
-    /** How many metrics to batch before sending */
-    batchSize?: number;
-    /** Whether to disable batching and send immediately */
-    immediateReporting?: boolean;
-    /** Which categories of metrics to collect */
-    collectCategories?: {
-        performance?: boolean;
-        errors?: boolean;
-        stateChanges?: boolean;
-        middleware?: boolean;
-    };
-    /** Whether to compress payloads */
-    compressPayloads?: boolean;
-}
-/**
- * Remote observability extension for store monitoring
- */
-declare class RemoteObservability<T extends object> extends StoreObservability<T> {
-    private destinations;
-    private metricsBatch;
-    private reportingInterval;
-    private batchSize;
-    private serviceName;
-    private environment;
-    private instanceId;
-    private immediateReporting;
-    private collectCategories;
-    private compressPayloads;
-    private reportingTimer;
-    private traceIdCounter;
-    private activeTraces;
-    /**
-     * Creates a new RemoteObservability instance
-     * @param store The ReactiveDataStore to observe
-     * @param options Configuration options
-     */
-    constructor(store: DataStore<T>, options: RemoteObservabilityOptions);
-    /**
-     * Generate a unique instance ID if none provided
-     */
-    private generateInstanceId;
-    /**
-     * Setup additional event listeners for remote reporting
-     */
-    private setupRemoteEventListeners;
-    /**
-     * Begin a trace for performance tracking
-     * @param name Name of the trace
-     * @returns Trace ID
-     */
-    beginTrace(name: string): string;
-    /**
-     * Begin a span within a trace
-     * @param traceId Parent trace ID
-     * @param name Span name
-     * @param labels Additional context labels
-     * @returns Span ID
-     */
-    beginSpan(traceId: string, name: string, labels?: Record<string, string>): string;
-    /**
-     * End a span within a trace
-     * @param traceId Parent trace ID
-     * @param spanName Name of span to end (ends last matching span)
-     */
-    endSpan(traceId: string, spanName: string): void;
-    /**
-     * End a trace and send it to remote destinations
-     * @param traceId Trace ID to end
-     */
-    endTrace(traceId: string): void;
-    /**
-     * Add a remote destination for metrics
-     * @param destination Remote destination configuration
-     * @returns Boolean indicating if destination was added successfully
-     */
-    addDestination(destination: RemoteDestination): boolean;
-    /**
-     * Remove a remote destination by ID
-     * @param id Destination ID to remove
-     * @returns Boolean indicating if destination was removed
-     */
-    removeDestination(id: string): boolean;
-    /**
-     * Get list of configured destinations
-     * @returns Array of destination IDs and names
-     */
-    getDestinations(): Array<{
-        id: string;
-        name: string;
-    }>;
-    /**
-     * Test connection to all destinations
-     * @returns Object mapping destination IDs to connection status
-     */
-    testAllConnections(): Promise<Record<string, boolean>>;
-    /**
-     * Track a metric and add it to the batch
-     * @param metric Metric to track
-     */
-    private trackMetric;
-    /**
-     * Flush metrics to all configured destinations
-     */
-    private flushMetrics;
-    /**
-     * Start the periodic reporting cycle
-     */
-    private startReportingCycle;
-    /**
-     * Change the reporting interval
-     * @param intervalMs New interval in milliseconds
-     */
-    setReportingInterval(intervalMs: number): void;
-    /**
-     * Collect and report current store performance metrics
-     */
-    reportCurrentMetrics(): void;
-    /**
-     * Override disconnect to also flush metrics
-     */
-    disconnect(): void;
-}
-
-/**
- * Create a destination that sends metrics to an OpenTelemetry collector
- * @param config Configuration for the OpenTelemetry destination
- */
-declare function createOpenTelemetryDestination(config: {
-    endpoint: string;
-    apiKey?: string;
-    resource?: Record<string, string>;
-}): RemoteDestination;
-/**
- * Create a destination that sends metrics to Prometheus
- * @param config Configuration for the Prometheus destination
- */
-declare function createPrometheusDestination(config: {
-    pushgatewayUrl: string;
-    username?: string;
-    password?: string;
-    jobName: string;
-}): RemoteDestination;
-/**
- * Create a destination that sends metrics to Grafana Cloud
- * @param config Configuration for the Grafana Cloud destination
- */
-declare function createGrafanaCloudDestination(config: {
-    url: string;
-    apiKey: string;
-}): RemoteDestination;
-/**
- * Create a destination that sends metrics to a generic HTTP endpoint
- * @param config Configuration for the HTTP destination
- */
-declare function createHttpDestination(config: {
-    url: string;
-    headers?: Record<string, string>;
-    method?: 'POST' | 'PUT';
-    transformPayload?: (payload: RemoteMetricsPayload) => any;
-}): RemoteDestination;
-
-/**
- * Hook to use the RemoteObservability instance with React
- * @param store Store instance
- * @param options Configuration options
- */
-declare function useRemoteObservability<T extends object>(store: DataStore<T>, options: RemoteObservabilityOptions): {
-    remote: RemoteObservability<T>;
-    addOpenTelemetryDestination: (config: Parameters<typeof createOpenTelemetryDestination>[0]) => boolean;
-    addPrometheusDestination: (config: Parameters<typeof createPrometheusDestination>[0]) => boolean;
-    addGrafanaCloudDestination: (config: Parameters<typeof createGrafanaCloudDestination>[0]) => boolean;
-    addHttpDestination: (config: Parameters<typeof createHttpDestination>[0]) => boolean;
-};
-
-/**
- * Implements DataStorePersistence using web storage (localStorage or sessionStorage).
- * Supports cross-tab synchronization via an event bus and native storage events when using localStorage.
- */
-declare class WebStoragePersistence<T extends object> implements DataStorePersistence<T> {
-    private readonly storageKey;
-    private readonly eventBus;
-    private readonly storage;
-    /**
-     * Initializes a new instance of WebStoragePersistence.
-     * @param storageKey The key under which data is stored in web storage (e.g., 'user-profile').
-     * @param session Optional flag; if true, uses sessionStorage instead of localStorage (default: false).
-     */
-    constructor(storageKey: string, session?: boolean);
-    /**
-     * Initializes the event bus with configured settings.
-     * @returns Configured event bus instance.
-     */
-    private initializeEventBus;
-    /**
-     * Sets up a listener for native storage events to synchronize across tabs (localStorage only).
-     */
-    private setupStorageEventListener;
-    /**
-     * Persists the provided state to web storage and notifies subscribers.
-     * @param instanceId Unique identifier of the instance making the update.
-     * @param state The state to persist.
-     * @returns True if successful, false if an error occurs.
-     */
-    set(instanceId: string, state: T): boolean;
-    /**
-     * Retrieves the current state from web storage.
-     * @returns The persisted state, or null if not found or invalid.
-     */
-    get(): T | null;
-    /**
-     * Subscribes to updates in the persisted state, excluding the instance’s own changes.
-     * @param instanceId Unique identifier of the subscribing instance.
-     * @param onStateChange Callback to invoke with the updated state.
-     * @returns Function to unsubscribe from updates.
-     */
-    subscribe(instanceId: string, onStateChange: (state: T) => void): () => void;
-    /**
-     * Removes the persisted state from web storage.
-     * @returns True if successful, false if an error occurs.
-     */
-    clear(): boolean;
-}
-/**
- * Alias for WebStoragePersistence, maintained for backward compatibility.
- * @deprecated Use `WebStoragePersistence` instead, which supports both localStorage and sessionStorage.
- */
-declare const LocalStoragePersistence: typeof WebStoragePersistence;
-
-/**
- * IndexedDB persistence adapter with storeId and ephemeral instance IDs
- */
-declare class IndexedDBPersistence<T> implements DataStorePersistence<T> {
-    private cursorPromise;
-    private storeId;
-    private eventBus;
-    constructor(storeId: string);
-    set(id: string, state: T): Promise<boolean>;
-    get(): Promise<T | null>;
-    subscribe(id: string, callback: (state: T) => void): () => void;
-    clear(): Promise<boolean>;
-    static closeAll(): Promise<void>;
-}
-
-export { type Action, type Actions, type BlockingMiddleware, type DataStore, type DataStorePersistence, type DebugEvent, type DeepPartial, IndexedDBPersistence, LocalStoragePersistence, type MetricType, type Middleware, type MiddlewareExecution, type ObservabilityOptions, ReactiveDataStore, type RemoteDestination, type RemoteMetricsPayload, RemoteObservability, type RemoteObservabilityOptions, type StoreDefinition, type StoreEvent, type StoreExecutionState, type StoreMetrics, StoreObservability, type StoreOptions, type StoreSelector, WebStoragePersistence, createGrafanaCloudDestination, createHttpDestination, createOpenTelemetryDestination, createPrometheusDestination, createStore, useRemoteObservability };
+export { type Action, type Actions, type StoreDefinition, type StoreOptions, type StoreSelector, createStore };