@asaidimu/utils-store 2.3.2 → 4.0.0

package/index.d.mts

@@ -1,3 +1,6 @@
+import { EventBus } from '@asaidimu/events';
+import { SimplePersistence as SimplePersistence$1 } from '@asaidimu/utils-persistence';
+
 interface SimplePersistence<T> {
     /**
      * Persists data to storage.
@@ -53,6 +56,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 +94,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 +159,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 +193,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 +268,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 +310,359 @@ 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 {
+    Singleton = "singleton",// Created once, cached, tracks dependencies
+    Transient = "transient"
+}
+/**
+ * Dependency resolution context provided to the use() callback.
+ */
+interface UseDependencyContext<TState extends object> {
     /**
-     * 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.
-     *
-     * If another update is in progress, the new update is queued.
-     *
-     * @param update A partial state object or a function that returns a partial state object.
+     * Resolve another artifact.
+     * This records a dependency between the caller and the requested artifact.
      */
-    set(update: StateUpdater<T>): Promise<void>;
+    resolve<TArtifact>(key: string): Promise<TArtifact>;
     /**
-     * Subscribes a callback function to state changes at a specific path.
-     * The callback is triggered only when the specified path changes.
-     *
-     * @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.
+     * Select a slice of state.
+     * This records a dependency between the artifact and the specific state paths.
      */
-    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    select<S>(selector: (state: TState) => S): S;
+}
+/**
+ * The context object provided to an artifact's factory function.
+ */
+interface ArtifactFactoryContext<TState extends object> {
     /**
-     * Gets the unique identifier for this store instance.
-     *
-     * @returns The instance ID as a string.
+     * Get the current state snapshot immediately.
+     * WARNING: Calling this does NOT create a subscription.
+     * Use ctx.use(c => c.select(...)) for reactive behavior.
      */
-    id(): string;
+    state(): TState;
     /**
-     * Executes a series of state updates atomically within a single transaction.
-     *
-     * @param operation A function containing the state updates to be performed.
-     * @returns The result of the operation.
+     * The existing instance if being re-evaluated.
+     * Useful for preserving internal state (like connections) during hot-swaps.
      */
-    transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    current?: unknown;
     /**
-     * Adds a middleware function to the store.
-     *
-     * @param props The middleware configuration.
-     * @returns A unique ID for the added middleware.
+     * Execute a callback to capture dependencies.
+     * All resolve() and select() calls inside this callback are recorded
+     * to build the dependency graph for this artifact.
      */
-    use(props: MiddlewareConfig<T>): string;
+    use<K>(callback: (ctx: UseDependencyContext<TState>) => K | Promise<K>): Promise<K>;
+}
+/**
+ * Cleanup function type.
+ */
+type ArtifactCleanup = () => void | Promise<void>;
+/**
+ * Represents the output of an artifact factory:
+ * either the artifact instance itself, or a tuple [instance, cleanup].
+ */
+type ArtifactResult<T> = T | [T, ArtifactCleanup];
+/**
+ * A factory function that creates an instance of an artifact.
+ */
+type ArtifactFactory<TState extends object, TArtifact> = (context: ArtifactFactoryContext<TState>) => ArtifactResult<TArtifact> | Promise<ArtifactResult<TArtifact>>;
+declare class ArtifactContainer<TState extends object> {
+    private readonly artifacts;
+    private readonly resolvingStack;
+    private readonly listeners;
+    private readonly getState;
+    private readonly subscribe;
     /**
-     * Removes a middleware function by its unique ID.
-     *
-     * @param id The ID of the middleware to remove.
-     * @returns `true` if the middleware was successfully removed, `false` otherwise.
+     * @param getState Function to retrieve current state snapshot
+     * @param subscribe Function to subscribe to path changes. Must return an unsubscribe function.
      */
-    unuse(id: string): boolean;
+    constructor(props: Pick<DataStore<TState>, "watch" | "get">);
+    subscribeToArtifact(key: string, callback: () => void): () => void;
+    get(key: string): any | undefined;
+    private notifyListeners;
     /**
-     * Get the performance metrics for the store.
-     * @deprecated WILL BE REMOVED in a future version.
+     * Registers an artifact.
+     * @returns A function to unregister the artifact.
      */
-    metrics(): StoreMetrics;
+    register<TArtifact>(options: {
+        key: string;
+        factory: ArtifactFactory<TState, TArtifact>;
+        scope?: ArtifactScope;
+        lazy?: boolean;
+    }): () => void;
+    unregister(key: string): Promise<void>;
     /**
-     * Subscribes a listener to a specific store event.
-     *
-     * @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.
+     * Resolves an artifact instance.
      */
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    resolve<TArtifact>(key: string): Promise<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.
+     * Internal: Executes the factory and captures dependencies into provided Sets.
      */
-    getPersistenceStatus(): {
-        queueSize: number;
-        isProcessing: boolean;
-        oldestTask?: number;
-    };
+    private createArtifactInstance;
     /**
-     * Forces immediate processing of any pending persistence operations.
+     * Updates the dependency graph and state subscriptions after a successful creation.
      */
-    flushPersistence(): Promise<void>;
+    private updateGraph;
     /**
-     * Clears all pending persistence operations from the queue.
+     * Cascading invalidation logic.
+     * Destroys the artifact, destroys dependents, then rebuilds eager artifacts.
      */
-    clearPersistenceQueue(): void;
+    private invalidate;
     /**
-     * Cleans up resources, such as event listeners, to prevent memory leaks.
+     * Cleans up a specific artifact definition's instance and subscriptions.
+     * Keeps the definition registered.
      */
-    dispose(): void;
+    private disposeInstance;
     /**
-     * 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.
-     *
-     * @param bus The event bus to emit the event on.
-     * @param event The event object to emit.
+     * Fully removes an artifact from the system.
      */
-    private emit;
+    private disposeArtifact;
+    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 ObservabilityOptions {
-    /** Maximum number of events to keep in history */
+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 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 +671,218 @@ 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;
+}
+
+interface ActionContext<TState extends object, TResolvedArtifacts extends object> {
+    /**
+     * Resolve an artifact.
+     * This records a dependency between the caller and the requested artifact.
+     */
+    resolve<K extends keyof TResolvedArtifacts>(key: K): Promise<TResolvedArtifacts[K]>;
+    state: TState;
+}
+type ActionImplementation<TState extends object, TResolvedArtifacts extends object, TArgs extends any[]> = (ctx: ActionContext<TState, TResolvedArtifacts>, ...args: TArgs) => DeepPartial<TState> | Promise<DeepPartial<TState>>;
+type ArtifactDefinition<TState extends Object, R> = {
+    factory: ArtifactFactory<TState, R>;
+    scope?: ArtifactScope;
+    lazy?: boolean;
+};
+type ArtifactsMap<TState extends object> = Record<string, ArtifactDefinition<TState, any>>;
+type ExtractArtifactInstanceFromConfig<T> = T extends {
+    factory: ArtifactFactory<any, infer I>;
+} ? I : never;
+type ExtractInstanceFromMap<TMap extends ArtifactsMap<any>, TKey extends keyof TMap> = ExtractArtifactInstanceFromConfig<TMap[TKey]>;
+type ResolvedArtifactsMap<TArtifactsMap extends ArtifactsMap<any>> = {
+    [K in keyof TArtifactsMap]: ExtractInstanceFromMap<TArtifactsMap, K>;
+};
+type ActionMap<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = Record<string, ActionImplementation<TState, ResolvedArtifactsMap<TArtifactsMap>, any[]>>;
+/**
+ * Bounds the actions for the resulting store hook, removing the context argument.
+ */
+type BoundActions<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = {
+    [K in keyof TActions]: (...args: Parameters<TActions[K]> extends [ActionContext<any, any>, ...infer R] ? R : never) => Promise<TState>;
+};
+type LoadingState<TActions> = Partial<Record<keyof TActions, boolean>>;
+type StoreOptions<T> = ObserverOptions & {
+    enableMetrics?: boolean;
+    persistence?: SimplePersistence$1<T>;
+};
+interface StoreDefinition<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> {
+    state: TState;
+    actions: TActions;
+    artifacts?: TArtifactsMap;
+    loading?: LoadingState<TActions>;
+    sync?: (args: TState) => void;
+    blockingMiddleware?: Record<string, BlockingMiddleware<TState>>;
+    middleware?: Record<string, Middleware<TState>>;
 }
+type StoreHook<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = () => {
+    store: any;
+    observer: any;
+    select: <S>(selector: (state: TState) => S) => S;
+    actions: BoundActions<TState, TArtifactsMap, TActions>;
+    /**
+     * Reactive Artifact Resolver.
+     * Returns [instance, isReady].
+     */
+    resolve: <K extends keyof TArtifactsMap>(key: K) => readonly [ExtractInstanceFromMap<TArtifactsMap, K>, true] | readonly [ExtractInstanceFromMap<TArtifactsMap, K> | undefined, false];
+    isReady: boolean;
+    actionTracker: any;
+    watch: (action: keyof TActions) => boolean;
+    state: () => TState;
+};
+
+declare function createStore<TState extends Record<string, unknown>, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>>(definition: StoreDefinition<TState, TArtifactsMap, TActions>, { enableMetrics, ...options }?: StoreOptions<TState>): StoreHook<TState, TArtifactsMap, TActions>;
 
-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 ActionContext, type ActionErrorPayload, type ActionImplementation, ActionManager, type ActionMap, type ActionStartPayload, type ArtifactCleanup, ArtifactContainer, type ArtifactDefinition, type ArtifactFactory, type ArtifactFactoryContext, type ArtifactResult, ArtifactScope, type ArtifactsMap, type BlockingMiddleware, type BoundActions, DELETE_SYMBOL, type DataStore, type DeepPartial, type DiffFunction, type ExtractArtifactInstanceFromConfig, type ExtractInstanceFromMap, type LoadingState, 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 ResolvedArtifactsMap, type SelectorAccessedPayload, type SelectorChangedPayload, type StateDelta, type StateUpdater, type StoreAction, type StoreDefinition, type StoreEvent, type StoreEvents, type StoreExecutionState, type StoreHook, type StoreMetrics, StoreObserver, type StoreOptions, type TransformMiddleware, type UseDependencyContext, createDerivePaths, createDiff, createMerge, createStore, derivePaths, diff, merge, shallowClone };