@asaidimu/utils-store 2.3.3 → 5.0.0

package/index.d.mts

@@ -1,3 +1,5 @@
+import { EventBus } from '@asaidimu/events';
+
 interface SimplePersistence<T> {
     /**
      * Persists data to storage.
@@ -53,6 +55,26 @@ interface SimplePersistence<T> {
 type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
 } | undefined | T : T | undefined;
+/**
+ * Interface for performance metrics of the state.
+ */
+interface StoreMetrics {
+    updateCount: number;
+    listenerExecutions: number;
+    averageUpdateTime: number;
+    largestUpdateSize: number;
+    mostActiveListenerPaths: string[];
+    totalUpdates: number;
+    blockedUpdates: number;
+    averageUpdateDuration: number;
+    middlewareExecutions: number;
+    transactionCount: number;
+    totalEventsFired: number;
+    totalActionsDispatched: number;
+    totalActionsSucceeded: number;
+    totalActionsFailed: number;
+    averageActionDuration: number;
+}
 /**
  * Extended store state for monitoring execution status
  */
@@ -71,7 +93,56 @@ interface StoreExecutionState<T> {
 /**
  * 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" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error";
+type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error" | "action:start" | "action:complete" | "action:error" | "selector:accessed" | "selector:changed";
+interface SelectorChangedPayload<S> {
+    selectorId: string;
+    newResult: S;
+    timestamp: number;
+}
+type StoreEvents = {
+    [K in StoreEvent]: K extends "update:complete" ? {
+        deltas: StateDelta[];
+        duration: number;
+        timestamp: number;
+        actionId?: string;
+        newState: any;
+        blocked?: boolean;
+        error?: any;
+    } : K extends "selector:accessed" ? SelectorAccessedPayload : K extends "selector:changed" ? SelectorChangedPayload<any> : K extends "action:start" ? ActionStartPayload : K extends "action:complete" ? ActionCompletePayload : K extends "action:error" ? ActionErrorPayload : K extends "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" ? MiddlewareExecution : K extends "transaction:start" | "transaction:complete" | "transaction:error" ? {
+        transactionId: string;
+        timestamp: number;
+    } : K extends "persistence:queued" ? PersistenceQueuedPayload : K extends "persistence:success" ? PersistenceSuccessPayload : K extends "persistence:retry" ? PersistenceRetryPayload : K extends "persistence:failed" ? PersistenceFailedPayload : K extends "persistence:queue_cleared" ? PersistenceQueueClearedPayload : K extends "persistence:init_error" ? PersistenceInitErrorPayload : any;
+};
+interface SelectorAccessedPayload {
+    selectorId: string;
+    accessedPaths: string[];
+    duration: number;
+    timestamp: number;
+}
+interface ActionStartPayload {
+    actionId: string;
+    name: string;
+    params: any[];
+    timestamp: number;
+}
+interface ActionCompletePayload {
+    actionId: string;
+    name: string;
+    params: any[];
+    startTime: number;
+    endTime: number;
+    duration: number;
+    result: any;
+}
+interface ActionErrorPayload {
+    actionId: string;
+    name: string;
+    params: any[];
+    startTime: number;
+    endTime: number;
+    duration: number;
+    error: any;
+}
 /**
  * Type for middleware functions. Return a partial state to transform the update.
  */
@@ -87,7 +158,12 @@ interface MiddlewareExecution {
     duration: number;
     blocked: boolean;
     error?: Error;
-    changedPaths: string[];
+    deltas: StateDelta[];
+}
+interface StateDelta {
+    path: string;
+    oldValue: any;
+    newValue: any;
 }
 /**
  * Represents a state update, which can be either a partial state object or a function.
@@ -116,44 +192,42 @@ interface MiddlewareConfig<T> {
     name?: string;
     block?: boolean;
 }
-/**
- * Interface for performance metrics of the state.
- */
-interface StoreMetrics {
-    updateCount: number;
-    listenerExecutions: number;
-    averageUpdateTime: number;
-    largestUpdateSize: number;
-    mostActiveListenerPaths: string[];
-}
-interface StoreMetrics {
-    totalUpdates: number;
-    blockedUpdates: number;
-    listenerExecutions: number;
-    averageUpdateDuration: number;
-    middlewareExecutions: number;
-    transactionCount: number;
-    totalEventsFired: number;
-}
-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;
+interface ReactiveSelector<S> {
+    id: string;
+    get: () => S;
+    subscribe: (callback: (state: S) => void) => () => void;
 }
 /**
  * Interface defining the contract for the data state.
  */
 interface DataStore<T extends object> {
     get(clone?: boolean): T;
-    set(update: StateUpdater<T>): Promise<void>;
+    register<R extends any[]>(action: {
+        name: string;
+        fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+        debounce?: {
+            delay: number;
+            condition?: (previous: R, current: R) => boolean;
+        };
+    }): () => void;
+    dispatch<R extends any[]>(name: string, ...args: R): Promise<T>;
+    set(update: StateUpdater<T>, options?: {
+        force?: boolean;
+        actionId?: string;
+    }): Promise<any>;
+    select<S>(selector: (state: T) => S): ReactiveSelector<S>;
+    /** @deprecated
+     * Use watch instead will be removed in next major version
+     * **/
     subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    watch(path: string | Array<string>, callback: (state: T) => void): () => void;
     transaction<R>(operation: () => R | Promise<R>): Promise<R>;
-    use(props: MiddlewareConfig<T>): string;
-    unuse(id: string): boolean;
+    use(props: MiddlewareConfig<T>): () => boolean;
+    /** @deprecated
+     * Use on instead will be removed in next majow version
+     * **/
     onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    on(event: StoreEvent, listener: (data: any) => void): () => void;
     id(): string;
     isReady(): boolean;
     state(): Readonly<StoreExecutionState<T>>;
@@ -193,18 +267,34 @@ interface PersistenceInitErrorPayload {
     error: any;
     timestamp: number;
 }
-declare const author = "https://github.com/asaidimu";
+type StoreAction<T, R extends any[] = any[]> = {
+    id: string;
+    name: string;
+    action: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+    debounce?: {
+        /** Active timer reference, if debouncing */
+        timer?: ReturnType<typeof setTimeout>;
+        /** Debounce delay in milliseconds */
+        delay: number;
+        /** Optional condition to decide whether to debounce based on previous vs current args */
+        condition?: (previous: R | undefined, current: R) => boolean;
+        /** Last call’s arguments, used for condition checks */
+        args?: R;
+        /** Internal promise resolvers to prevent memory leaks */
+        resolve?: (value: any) => void;
+        reject?: (reason?: any) => void;
+    };
+};
 
 /**
- * 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).
+ * Reactive Data Store Implementation - Updated for Concurrency and Performance
+ * The public API is preserved for test compatibility.
  */
 
 /**
  * Main ReactiveDataStore - a robust, type-safe state management solution.
- * It features optimistic updates for a responsive user experience and
- * handles data persistence in the background.
+ * It features optimistic updates, a promise-based update queue for serial execution,
+ * and decoupled persistence.
  *
  * @template T The type of the data object managed by the store.
  */
@@ -219,278 +309,458 @@ declare class ReactiveDataStore<T extends object> implements DataStore<T> {
     private transactionManager;
     /** Collects and provides performance metrics for the store. */
     private metricsCollector;
-    /** Queue for pending state updates when the store is busy. */
-    private pendingUpdates;
-    /** Flag to prevent concurrent updates. */
-    private isUpdating;
-    /** Event bus for notifying subscribers of state updates. */
+    private selectorManager;
+    private actionManager;
+    /**
+     * Promise chain to enforce serial, non-recursive execution
+     * of all state updates.
+     */
+    private updateQueue;
     private updateBus;
-    /** General event bus for broadcasting internal store events. */
     private eventBus;
-    /** Represents the current execution state of the store. */
     private executionState;
-    /** A unique identifier for this store instance. */
     private instanceID;
-    /** Function to deeply merge partial state updates. */
     private merge;
-    /** Function to calculate the difference between two state objects. */
     private diff;
     /**
      * Creates a new ReactiveDataStore instance.
-     *
-     * @param initialData The initial state of the data store.
-     * @param persistence An optional persistence handler for saving state.
-     * @param deleteMarker A symbol used to mark properties for deletion.
-     * @param options Configuration options for the store.
      */
     constructor(initialData: T, persistence?: SimplePersistence<T>, deleteMarker?: symbol, options?: {
         persistenceMaxRetries?: number;
         persistenceRetryDelay?: number;
     });
-    /**
-     * Checks if the persistence layer is ready to save data.
-     *
-     * @returns `true` if ready, otherwise `false`.
-     */
     isReady(): boolean;
-    /**
-     * Returns the current read-only execution state of the store.
-     */
     state(): Readonly<StoreExecutionState<T>>;
     /**
-     * Gets the current state of the data store.
-     *
-     * @param clone If `true`, returns a deep clone of the state to prevent direct modification.
+     * Gets the current state. Optimized default to return reference (false) for performance.
+     * @param clone If `true`, returns a deep clone (use sparingly).
      * @returns The current state object.
      */
     get(clone?: boolean): T;
+    select<S>(selector: (state: T) => S): ReactiveSelector<S>;
+    register<R extends any[]>(action: {
+        name: string;
+        fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+        debounce?: {
+            delay: number;
+            condition?: (previous: R | undefined, current: R) => boolean;
+        };
+    }): () => void;
+    dispatch<R extends any[]>(name: string, ...params: R): Promise<T>;
+    /**
+     * Optimized method to update the state.
+     * Uses the Promise Queue to guarantee sequential execution.
+     * @returns A Promise that resolves with the new state T.
+     */
+    set(update: StateUpdater<T>, options?: {
+        force?: boolean;
+        actionId?: string;
+    }): Promise<any>;
+    /**
+     * Internal logic for performing a single, sequential state update.
+     */
+    private _performUpdate;
+    private setupPersistenceListener;
+    watch(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /** @deprecated **/
+    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    id(): string;
+    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    use(props: MiddlewareConfig<T>): () => boolean;
+    metrics(): StoreMetrics;
+    on(event: StoreEvent, listener: (data: any) => void): () => void;
+    /** @deprecated */
+    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    getPersistenceStatus(): {
+        queueSize: number;
+        isProcessing: boolean;
+        oldestTask?: number;
+    };
+    flushPersistence(): Promise<void>;
+    clearPersistenceQueue(): void;
+    dispose(): void;
+    private emit;
+}
+
+/**
+ * Defines the lifecycle scope of an artifact.
+ */
+declare enum ArtifactScope {
+    /**
+     * Created once and cached.
+     * The container tracks its dependencies and rebuilds it if they change.
+     */
+    Singleton = "singleton",
     /**
-     * Optimized method to update the state. It handles optimistic updates by
-     * applying changes immediately and persisting them in the background.
-     * Middleware is executed before and after the update.
+     * Created every time it is resolved.
+     * Dependencies are NOT tracked, and it is never cached.
+     */
+    Transient = "transient"
+}
+/**
+ * Dependency resolution context provided to the `use()` callback.
+ * Used to declare dependencies on other artifacts or state slices.
+ */
+interface UseDependencyContext<TState extends object> {
+    /**
+     * Resolve another artifact.
+     * This records a dependency: if the target artifact is invalidated, the caller will be too.
      *
-     * If another update is in progress, the new update is queued.
+     * @param key The key of the artifact to resolve.
+     */
+    resolve<TArtifact>(key: string): Promise<ResolvedArtifact<TArtifact>>;
+    /**
+     * Select a slice of state.
+     * This records a dependency: if the selected state changes, the artifact will be invalidated.
      *
-     * @param update A partial state object or a function that returns a partial state object.
+     * @param selector A function that selects a part of the global state.
+     */
+    select<S>(selector: (state: TState) => S): S;
+}
+/**
+ * The context object provided to an artifact's factory function.
+ * Provides tools for state access, dependency injection, and lifecycle management.
+ */
+interface ArtifactFactoryContext<TState extends object> {
+    /**
+     * Get the current state snapshot immediately.
+     * **Note:** Calling this does NOT create a subscription. Use `ctx.use(c => c.select(...))` for reactive behavior.
+     */
+    state(): TState;
+    /**
+     * The existing instance if the artifact is being re-evaluated/rebuilt.
+     * Useful for preserving internal state (like active connections) during hot-swaps.
      */
-    set(update: StateUpdater<T>): Promise<void>;
+    current?: unknown;
     /**
-     * Subscribes a callback function to state changes at a specific path.
-     * The callback is triggered only when the specified path changes.
+     * Execute a callback to capture dependencies.
+     * All `resolve()` and `select()` calls inside this callback are recorded
+     * to build the reactive dependency graph.
      *
-     * @param path The path or array of paths to subscribe to.
-     * @param callback The function to call when the state at the path changes.
-     * @returns A function to unsubscribe the callback.
+     * @param callback The function where dependencies are declared.
      */
-    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    use<K>(callback: (ctx: UseDependencyContext<TState>) => K | Promise<K>): Promise<K>;
     /**
-     * Gets the unique identifier for this store instance.
+     * Register a cleanup function to be called when the artifact is disposed or rebuilt.
+     * Multiple cleanup functions can be registered; they will be called in reverse order (LIFO).
      *
-     * @returns The instance ID as a string.
+     * @param cleanup A function to execute during teardown.
      */
-    id(): string;
+    onCleanup(cleanup: ArtifactCleanup): void;
     /**
-     * Executes a series of state updates atomically within a single transaction.
+     * Hot-swap the artifact instance without triggering a full teardown.
+     *
+     * **Behavior:**
+     * 1. Updates the internal instance **synchronously** (immediate consistency).
+     * 2. Invalidates downstream dependents **asynchronously** (graph consistency).
+     * 3. Notifies listeners (UI updates) only after the graph is consistent.
      *
-     * @param operation A function containing the state updates to be performed.
-     * @returns The result of the operation.
+     * @param value The new instance value to set.
+     *
+     * @example
+     * // Updating a WebSocket connection without losing the wrapping artifact
+     * factory: async (ctx) => {
+     * const ws = new WebSocket(url);
+     * ws.onmessage = (msg) => ctx.yield(JSON.parse(msg.data));
+     * return ws; // Initial value
+     * }
+     */
+    yield(value: unknown): void;
+}
+/**
+ * A function to clean up resources (close sockets, remove listeners, etc.).
+ */
+type ArtifactCleanup = () => void | Promise<void>;
+/**
+ * The result of resolving an artifact.
+ * Wraps the instance with metadata, error state, and control methods.
+ */
+interface ResolvedArtifact<TArtifact> {
+    /** The resolved artifact instance. */
+    instance: TArtifact;
+    /** A function that runs all registered cleanups for this artifact. */
+    cleanup?: ArtifactCleanup;
+    /** Any error that occurred during creation. */
+    error?: any;
+    /**
+     * Manually invalidate this artifact.
+     * @param replace If `true`, forces an immediate rebuild (Eager). If `false`, marks as stale (Lazy).
+     */
+    invalidate(replace?: boolean): Promise<void>;
+}
+/**
+ * A factory function that creates an instance of an artifact.
+ */
+type ArtifactFactory<TState extends object, TArtifact> = (context: ArtifactFactoryContext<TState>) => TArtifact | Promise<TArtifact>;
+/**
+ * A reactive dependency injection container.
+ * Manages the lifecycle, caching, and dependency graph of application artifacts.
+ */
+declare class ArtifactContainer<TState extends object> {
+    private readonly artifacts;
+    private readonly resolvingStack;
+    private readonly listeners;
+    private readonly getState;
+    private readonly subscribe;
+    /**
+     * @param props Interface to the external state store (e.g., Zustand, Redux).
      */
-    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    constructor(props: Pick<DataStore<TState>, "watch" | "get">);
     /**
-     * Adds a middleware function to the store.
+     * Watch an artifact for changes and retrieve its current state.
      *
-     * @param props The middleware configuration.
-     * @returns A unique ID for the added middleware.
+     * @param id The artifact key to watch.
+     * @returns An object containing the ID, a getter, and a subscribe method.
+     *
+     * @example
+     * const watcher = container.watch("current-user");
+     * const unsub = watcher.subscribe(() => {
+     * const user = watcher.get()?.instance;
+     * console.log("User updated:", user);
+     * });
+     */
+    watch<TArtifact>(id: string): {
+        id: string;
+        get(): ResolvedArtifact<TArtifact> | null;
+        subscribe(callback: () => void): () => void;
+    };
+    /**
+     * Direct sync access to an artifact instance.
+     * Use this sparingly; prefer `resolve()` or `watch()`.
      */
-    use(props: MiddlewareConfig<T>): string;
+    get(id: string): any | undefined;
     /**
-     * Removes a middleware function by its unique ID.
+     * Registers a new artifact factory.
      *
-     * @param id The ID of the middleware to remove.
-     * @returns `true` if the middleware was successfully removed, `false` otherwise.
+     * @param options Configuration for the artifact.
+     * @returns A function to unregister the artifact.
      */
-    unuse(id: string): boolean;
+    register<TArtifact>(options: {
+        key: string;
+        factory: ArtifactFactory<TState, TArtifact>;
+        scope?: ArtifactScope;
+        lazy?: boolean;
+    }): () => void;
     /**
-     * Get the performance metrics for the store.
-     * @deprecated WILL BE REMOVED in a future version.
+     * Unregisters an artifact and cleans up its resources.
      */
-    metrics(): StoreMetrics;
+    unregister(key: string): Promise<void>;
     /**
-     * Subscribes a listener to a specific store event.
+     * Resolves an artifact, creating it if necessary.
+     * Handles dependency tracking, caching, and error states.
      *
-     * @param event The name of the event to listen for.
-     * @param listener The callback function to execute when the event is emitted.
-     * @returns A function to unsubscribe the listener.
+     * @param key The artifact identifier.
      */
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    resolve<TArtifact>(key: string): Promise<ResolvedArtifact<TArtifact>>;
     /**
-     * Get the current status of the persistence queue.
-     *
-     * @returns An object containing the queue size, processing status, and the age of the oldest task.
+     * Helper to wrap a definition into the standard public return type.
      */
-    getPersistenceStatus(): {
-        queueSize: number;
-        isProcessing: boolean;
-        oldestTask?: number;
-    };
+    private packageArtifact;
     /**
-     * Forces immediate processing of any pending persistence operations.
+     * Executes the factory and captures dependencies.
+     * Contains the "Yield" implementation.
      */
-    flushPersistence(): Promise<void>;
+    private createArtifactInstance;
     /**
-     * Clears all pending persistence operations from the queue.
+     * Orchestrates the invalidation and notification sequence for a yield event.
+     * Ensures downstream dependents are invalidated BEFORE listeners are notified.
      */
-    clearPersistenceQueue(): void;
+    private processYieldPropagation;
     /**
-     * Cleans up resources, such as event listeners, to prevent memory leaks.
+     * Updates the dependency graph structure after a successful build.
      */
-    dispose(): void;
+    private updateGraph;
     /**
-     * A private utility method to emit an event on a given event bus.
-     * Uses `queueMicrotask` to ensure events are emitted asynchronously after the current call stack clears.
+     * Cascading invalidation logic.
+     * Destroys the artifact, destroys dependents, then conditionally rebuilds.
      *
-     * @param bus The event bus to emit the event on.
-     * @param event The event object to emit.
+     * @param key The artifact key to invalidate
+     * @param replace If true, eagerly rebuild after invalidation. If false, respect lazy flag.
      */
-    private emit;
+    private invalidate;
+    /**
+     * Cleans up a specific artifact definition's instance and subscriptions.
+     * Keeps the definition registered but clears the instance.
+     */
+    private disposeInstance;
+    /**
+     * Fully removes an artifact from the system.
+     */
+    private disposeArtifact;
+    private createCompositeCleanup;
+    private notifyListeners;
+    private detectCycles;
+    dispose(): void;
+    isLoading(key: string): boolean;
 }
 
 /**
- * Store Observability Module
- * A separate module to add debugging and observability capabilities to the ReactiveDataStore.
+ * @fileoverview Store Observer Module
+ * @description A comprehensive module to add advanced debugging, observability, and time-travel
+ * capabilities to a ReactiveDataStore. All console logging is centralized to respect a 'silent' flag,
+ * preventing test runner output pollution.
  */
 
 /**
- * Interface for debug event structure
+ * @interface DebugEvent
+ * @description Interface for the structure of a recorded debug event.
  */
 interface DebugEvent {
+    /** The type of store event (e.g., 'update:start', 'action:complete'). */
     type: string;
+    /** The timestamp when the event occurred. */
     timestamp: number;
+    /** The raw data payload associated with the event, including actionId where applicable. */
     data: any;
 }
 /**
- * Configuration options for the observability module
+ * @interface Snapshot
+ * @description Represents a rich snapshot of the state at a point in time for history tracking.
+ */
+interface Snapshot<T> {
+    /** The complete state object at the time of the snapshot. */
+    state: T;
+    /** The timestamp of the state change. */
+    timestamp: number;
+    /** The list of changes (deltas) that resulted in this state. */
+    deltas: StateDelta[];
+}
+/**
+ * @interface ObserverSessionData
+ * @description Defines the data structure for a saved observer session.
+ */
+interface ObserverSessionData<T extends object> {
+    /** The chronological history of debug events. */
+    eventHistory: DebugEvent[];
+    /** The chronological history of state snapshots. */
+    stateHistory: Snapshot<T>[];
+}
+/**
+ * @interface ObserverOptions
+ * @description Configuration options for the observer module.
  */
-interface ObservabilityOptions {
-    /** Maximum number of events to keep in history */
+interface ObserverOptions {
+    /** Maximum number of events to retain in memory. Defaults to 500. */
     maxEvents?: number;
-    /** Whether to enable console logging */
+    /** Enables or disables console logging for all events (overridden by 'silent'). Defaults to false. */
     enableConsoleLogging?: boolean;
+    /** Maximum number of state snapshots to retain for time-travel. Defaults to 20. */
     maxStateHistory?: number;
-    /** Options for specific event types to log */
+    /** Fine-grained control over which event types are logged to the console. */
     logEvents?: {
         updates?: boolean;
         middleware?: boolean;
         transactions?: boolean;
+        actions?: boolean;
+        selectors?: boolean;
     };
-    /** Time threshold in ms to highlight slow operations */
+    /** Performance thresholds for triggering console warnings. Values are in milliseconds (ms). */
     performanceThresholds?: {
         updateTime?: number;
         middlewareTime?: number;
     };
+    /** If true, suppresses all console output and logging regardless of other options. Defaults to false. */
+    silent?: boolean;
 }
 /**
- * Class for observing and debugging a ReactiveDataStore instance
+ * @class StoreObserver
+ * @description Connects to a DataStore to capture state changes, events, and performance data.
+ * @template T The type of the store's state object.
  */
 declare class StoreObserver<T extends object> {
     protected store: DataStore<T>;
     private eventHistory;
+    private stateHistory;
+    private unsubscribers;
+    private isTimeTraveling;
+    private devTools;
+    private middlewareExecutions;
+    private activeTransactionCount;
+    private activeBatches;
     private maxEvents;
+    private maxStateHistory;
     private enableConsoleLogging;
+    private isSilent;
     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
+     * @param store The DataStore instance to observe.
+     * @param options Configuration options for the observer.
      */
-    constructor(store: DataStore<T>, options?: ObservabilityOptions);
+    constructor(store: DataStore<T>, options?: ObserverOptions);
     /**
-     * Sets up all event listeners
+     * @private
+     * Centralized logging method. All console output must go through here to respect the `isSilent` flag.
+     * @param method The console method to call ('log', 'warn', 'error', 'group', 'groupEnd', 'table', 'debug').
+     * @param args Arguments to pass to the console method.
+     */
+    private _consoleLog;
+    /**
+     * @private
+     * Sets up listeners for all relevant store events.
      */
     private setupEventListeners;
     /**
-     * Records a state snapshot
+     * @private
+     * Records a new state snapshot and manages the state history limit.
+     * @param deltas The state changes that led to this snapshot.
      */
     private recordStateSnapshot;
     /**
-     * Records an event to the history
-     * @param type Event type
-     * @param data Event data
+     * @private
+     * Records a debug event and manages the event history limit.
+     * @param type The type of event.
+     * @param data The data payload of the event.
      */
     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
+     * Returns a cloned copy of the recorded event history.
+     * @returns Array of debug events.
      */
     getEventHistory(): DebugEvent[];
     /**
-     * Returns the state history
-     * @returns Array of state snapshots
+     * Returns a cloned copy of the recorded state history (snapshots).
+     * @returns Array of state snapshots.
      */
-    getStateHistory(): T[];
+    getStateHistory(): Snapshot<T>[];
     /**
-     * Returns middleware execution history from the state
-     * @returns Array of middleware executions
+     * 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
+     * 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
+     * Creates a standard middleware that logs all updates.
+     * NOTE: This is user-defined middleware and uses native console methods,
+     * so its output is independent of the observer's `silent` flag.
+     * @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
+     * Creates a middleware that validates updates against a schema.
+     * Uses the internal `_consoleLog` for warnings.
+     * @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
+     * Returns a simplified view of recent state changes.
+     * @param limit Maximum number of state changes to compare. Defaults to 5.
+     * @returns Array of state difference objects.
      */
     getRecentChanges(limit?: number): Array<{
         timestamp: number;
@@ -499,21 +769,157 @@ declare class StoreObserver<T extends object> {
         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
+     * Clears both the event and state history, preserving only the initial state snapshot.
+     */
+    clearHistory(): void;
+    /**
+     * Filters and returns events related to a specific action ID.
+     * @param actionId The ID of the action to filter by.
+     * @returns Array of debug events associated with the action.
+     */
+    getHistoryForAction(actionId: string): DebugEvent[];
+    /**
+     * Attempts to replay a state update from history using the recorded update payload.
+     * @param eventIndex The index of the replayable event (an "update:start" event) in the history array.
+     */
+    replay(eventIndex: number): Promise<void>;
+    /**
+     * Creates a time-travel utility object with undo/redo capabilities.
+     * @returns An object with methods for time-travel navigation.
      */
     createTimeTravel(): {
         canUndo: () => boolean;
         canRedo: () => boolean;
-        undo: () => void;
-        redo: () => void;
-        getHistoryLength: () => number;
+        undo: () => Promise<void>;
+        redo: () => Promise<void>;
+        length: () => number;
         clear: () => void;
     };
     /**
-     * Disconnects all event listeners and cleans up resources
+     * Saves the current observer session (events and state history) using a persistence mechanism.
+     * @param persistence An object implementing the SimplePersistence interface.
+     * @returns A promise that resolves to true if the session was saved successfully.
+     */
+    saveSession(persistence: SimplePersistence<ObserverSessionData<T>>): Promise<boolean>;
+    /**
+     * Loads a previously saved observer session and restores the state to the latest saved snapshot.
+     * @param persistence An object implementing the SimplePersistence interface.
+     * @returns A promise that resolves to true if a session was loaded.
+     */
+    loadSession(persistence: SimplePersistence<ObserverSessionData<T>>): Promise<boolean>;
+    /**
+     * Exports the current session data as a JSON file, initiating a browser download.
+     */
+    exportSession(): void;
+    /**
+     * Imports a session from a JSON file, restoring event history and state.
+     * @param file The file object (e.g., from an <input type="file"> event) to import.
+     * @returns A promise that resolves when the import is complete.
+     */
+    importSession(file: File): Promise<void>;
+    /**
+     * Cleans up the observer by unsubscribing all event listeners and clearing history.
      */
     disconnect(): void;
+    /**
+     * @private
+     * Logs an event to the console with appropriate formatting.
+     * Uses `this._consoleLog` for all output.
+     * @param type Event type.
+     * @param data Event data.
+     */
+    private _log;
+    /**
+     * @private
+     * Checks for performance issues in the events.
+     * Uses `this._consoleLog` for all output.
+     * @param type Event type.
+     * @param data Event data.
+     */
+    private _checkPerformance;
+}
+
+/**
+ * Creates a diff function with configurable options.
+ *
+ * @param {object} options - Configuration options for the diff function.
+ * @param {symbol} [options.deleteMarker] - A custom symbol to mark properties for deletion.
+ */
+declare function createDiff(options?: {
+    deleteMarker?: symbol;
+}): any;
+/**
+ * Creates a derivePaths function with configurable options.
+ *
+ * @param {object} options - Configuration options for the derivePaths function.
+ * @param {symbol} [options.deleteMarker=Symbol.for("delete")] - A custom symbol to mark properties for deletion.
+ */
+declare function createDerivePaths(options?: {
+    deleteMarker?: symbol;
+}): <T>(changes: DeepPartial<T>) => string[];
+/**
+ * @deprecated This function is deprecated. Use `createDiff()` to get a diff function,
+ * or `createDiff({ deleteMarker: yourSymbol })` for custom delete markers.
+ * Example: `import { createDiff } from 'your-module'; const diff = createDiff();`
+ *
+ * Identifies paths that differ between original and partial objects, using `Symbol.for("delete")` as the default delete marker.
+ * This is provided for backward compatibility.
+ */
+declare const diff: any;
+type DiffFunction = ReturnType<typeof createDiff>;
+/**
+ * @deprecated This function is deprecated. Use `createDerivePaths()` to get a derivePaths function,
+ * or `createDerivePaths({ deleteMarker: yourSymbol })` for custom delete markers.
+ * Example: `import { createDerivePaths } from 'your-module'; const derivePaths = createDerivePaths();`
+ *
+ * Efficiently computes paths from changes, using `Symbol.for("delete")` as the default delete marker.
+ * This is provided for backward compatibility.
+ */
+declare const derivePaths: <T>(changes: DeepPartial<T>) => string[];
+
+/**
+ * Creates a shallow clone of an object or array.
+ */
+declare const shallowClone: (obj: any) => any;
+/**
+ * Creates a deep merge function with configurable options.
+ *
+ * @param {object} options - Configuration options for the merge function.
+ * @param {symbol} [options.deleteMarker=Symbol.for("delete")] - A custom symbol to mark properties for deletion during merge.
+ */
+declare function createMerge(options?: {
+    deleteMarker?: symbol;
+}): <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
+/**
+ * @deprecated This function is deprecated. Use `createMerge()` to get a merge function,
+ * or `createMerge({ deleteMarker: yourSymbol })` for custom delete markers.
+ * Example: `import { createMerge } from 'your-module'; const merge = createMerge();`
+ *
+ * Deep merges changes into an original object immutably, using `Symbol.for("delete")` as the default delete marker.
+ * This is provided for backward compatibility.
+ */
+declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
+type MergeFunction = ReturnType<typeof createMerge>;
+
+declare class ActionManager<T extends object> {
+    private eventBus;
+    private set;
+    private actions;
+    constructor(eventBus: EventBus<Record<StoreEvent, any>>, set: (update: StateUpdater<T>, options?: {
+        force?: boolean;
+        actionId?: string;
+    }) => Promise<any>);
+    register<R extends any[]>(action: {
+        name: string;
+        fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+        debounce?: {
+            delay: number;
+            condition?: (previous: R | undefined, current: R) => boolean;
+        };
+    }): () => void;
+    dispatch<R extends any[]>(name: string, ...params: R): Promise<T>;
+    private executeAction;
+    private emit;
 }
 
-export { type BlockingMiddleware, DELETE_SYMBOL, type DataStore, type DebugEvent, type DeepPartial, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObservabilityOptions, type PersistenceFailedPayload, type PersistenceInitErrorPayload, type PersistenceQueueClearedPayload, type PersistenceQueuedPayload, type PersistenceRetryPayload, type PersistenceSuccessPayload, ReactiveDataStore, type StateUpdater, type StoreEvent, type StoreExecutionState, type StoreMetrics, StoreObserver, type TransformMiddleware, author };
+export { type ActionCompletePayload, type ActionErrorPayload, ActionManager, type ActionStartPayload, type ArtifactCleanup, ArtifactContainer, type ArtifactFactory, type ArtifactFactoryContext, ArtifactScope, type BlockingMiddleware, DELETE_SYMBOL, type DataStore, type DeepPartial, type DiffFunction, type MergeFunction, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObserverOptions, type PersistenceFailedPayload, type PersistenceInitErrorPayload, type PersistenceQueueClearedPayload, type PersistenceQueuedPayload, type PersistenceRetryPayload, type PersistenceSuccessPayload, ReactiveDataStore, type ReactiveSelector, type ResolvedArtifact, type SelectorAccessedPayload, type SelectorChangedPayload, type StateDelta, type StateUpdater, type StoreAction, type StoreEvent, type StoreEvents, type StoreExecutionState, type StoreMetrics, StoreObserver, type TransformMiddleware, type UseDependencyContext, createDerivePaths, createDiff, createMerge, derivePaths, diff, merge, shallowClone };