@asaidimu/utils-store 10.2.16 → 10.2.17

package/index.d.cts

@@ -1,7 +1,130 @@
-import { SimplePersistence } from "@core/persistence";
-import { EventBus, SubscribeOptions, SubscribeOptions as SubscribeOptions$1 } from "@core/events";
-import { SystemLogger } from "@core/logger";
-
+//#region src/persistence/types.d.ts
+interface SimplePersistence<T> {
+  /**
+   * Persists data to storage.
+   *
+   * @param id The **unique identifier of the *consumer instance*** making the change. This is NOT the ID of the data (`T`) itself.
+   * Think of it as the ID of the specific browser tab, component, or module that's currently interacting with the persistence layer.
+   * It should typically be a **UUID** generated once at the consumer instance's instantiation.
+   * This `id` is crucial for the `subscribe` method, helping to differentiate updates originating from the current instance versus other instances/tabs, thereby preventing self-triggered notification loops.
+   * @param state The state (of type T) to persist. This state is generally considered the **global or shared state** that all instances interact with.
+   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations (like `IndexedDBPersistence`), this returns a `Promise<boolean>`.
+   */
+  set(id: string, state: T): boolean | Promise<boolean>;
+  /**
+   * Retrieves the global persisted data from storage.
+   *
+   * @returns The retrieved state of type `T`, or `null` if no data is found or if an error occurs during retrieval/parsing.
+   * For asynchronous implementations, this returns a `Promise<T | null>`.
+   */
+  get(): (T | null) | Promise<T | null>;
+  /**
+   * Subscribes to changes in the global persisted data that originate from *other* instances of your application (e.g., other tabs or independent components using the same persistence layer).
+   *
+   * @param id The **unique identifier of the *consumer instance* subscribing**. This allows the persistence implementation to filter out notifications that were initiated by the subscribing instance itself.
+   * @param callback The function to call when the global persisted data changes from *another* source. The new state (`T`) is passed as an argument to this callback.
+   * @returns A function that, when called, will unsubscribe the provided callback from future updates. Call this when your component or instance is no longer active to prevent memory leaks.
+   */
+  subscribe(id: string, callback: (state: T) => void): () => void;
+  /**
+   * Clears (removes) the entire global persisted data from storage.
+   *
+   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
+   */
+  clear(): boolean | Promise<boolean>;
+  /**
+   * Returns metadata about the persistence layer.
+   *
+   * This is useful for distinguishing between multiple apps running on the same host
+   * (e.g., several apps served at `localhost:3000` that share the same storage key).
+   *
+   * @returns An object containing:
+   * - `version`: The semantic version string of the persistence schema or application.
+   * - `id`: A unique identifier for the application using this persistence instance.
+   */
+  stats(): {
+    version: string;
+    id: string;
+  };
+  /**
+   * Closes the persistence instance, releasing the file watcher.
+   * Call this when shutting down to clean up resources.
+   */
+  close?: () => Promise<void>;
+}
+//#endregion
+//#region src/events/types.d.ts
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+  /**
+   * Subscribes to a specific event by name.
+   * @param eventName - The name of the event to subscribe to.
+   * @param callback - The function to call when the event is emitted.
+   * @param options -  Extra options to determine the behaviour of the
+   * subscription
+   * @returns A function to unsubscribe from the event.
+   */
+  subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
+  /**
+   * Subscribes to an event and automatically unsubscribes after it fires once.
+   * @param eventName - The name of the event to subscribe to.
+   * @param callback - The function to call when the event is emitted.
+   * @returns A function to cancel the one-shot subscription before it fires.
+   */
+  once<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
+  /**
+   * Emits an event with a payload to all subscribed listeners.
+   * @param event - An object containing the event name and payload.
+   */
+  emit: <TEventName extends keyof TEventMap>(event: {
+    name: TEventName;
+    payload: TEventMap[TEventName];
+  }) => void;
+  /**
+   * Retrieves metrics about event bus usage.
+   * @returns An object containing various metrics.
+   */
+  metrics: () => EventMetrics;
+  /**
+   * Clears all subscriptions and resets metrics.
+   *
+   * After calling `clear()`, the bus is fully reset and can be reused
+   * cross-tab communication is re-established if it was previously enabled.
+   *
+   * @param options - Optional configuration object.
+   * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
+   *                            Defaults to `false`.
+   * @returns {void}
+   */
+  clear: (options?: {
+    permanent?: boolean;
+  }) => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+  /** Total number of events emitted (both sync and deferred paths). */
+  totalEvents: number;
+  /** Number of active subscriptions across all event names. */
+  activeSubscriptions: number;
+  /** Map of event names to their emission counts. */
+  eventCounts: Map<string, number>;
+  /** Average duration of event dispatch in milliseconds. */
+  averageEmitDuration: number;
+}
+interface SubscribeOptions {
+  /**
+   * Debounce delay in milliseconds. When multiple events arrive in quick
+   * succession, the callback runs only after the quiet period ends, using the
+   * latest payload. Default = no debouncing.
+   */
+  debounce?: number;
+}
+//#endregion
 //#region src/store/types.d.ts
 /**
  * Utility type for representing partial updates to the state, allowing deep nesting.
@@ -333,7 +456,7 @@ interface DataStore<T extends object> {
    * @param options Extra options to pass to the event bus
    * @returns An unsubscribe function.
    */
-  watch(path: string | Array<string>, callback: (state: T) => void, options?: SubscribeOptions$1): () => void;
+  watch(path: string | Array<string>, callback: (state: T) => void, options?: SubscribeOptions): () => void;
   /**
    * Subscribes to execution‑status changes of a registered action.
    *
@@ -486,6 +609,87 @@ type StoreAction<T, R extends any[] = any[]> = {
   };
 };
 //#endregion
+//#region src/logger/logger.d.ts
+/**
+ * Represents the severity level of a system log entry.
+ * Levels are ordered by increasing severity: trace, debug, info, warn, error.
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Defines a destination where system logs are outputted or processed.
+ * Custom sinks (e.g., File, Logstash, Sentry) must implement this interface.
+ */
+interface LogSink {
+  /**
+   * Dispatches a structured log entry to the underlying destination.
+   *
+   * @param record - The complete log object containing metadata and payload.
+   * @returns A void or Promise that resolves when the log has been safely handed off.
+   */
+  write(record: SystemLog): void | Promise<void>;
+}
+/**
+ * Structure representing a fully contextualized system log entry ready for sinking.
+ */
+interface SystemLog {
+  /** The severity level of the log. */
+  level: LogLevel;
+  /** A clear, human-readable string identifying the distinct event (e.g., "user_login_failed"). */
+  event: string;
+  /** Additional structured data specific to this log instantiation. */
+  data?: object;
+  /** Contextual data shared across the logger instance (e.g., traceIds, environment). */
+  context?: object;
+  /** Epoch timestamp in milliseconds denoting when the log event occurred. */
+  timestamp: number;
+}
+/**
+ * Primary logger interface providing level-specific log dispatching, context-chaining,
+ * and dynamic sink management.
+ */
+interface SystemLogger {
+  /** Logs high-volume, extremely fine-grained diagnostic details. */
+  trace(event: string, data?: object): void;
+  /** Logs diagnostic information useful during local development or debugging. */
+  debug(event: string, data?: object): void;
+  /** Logs standard operational events that track the healthy flow of the system. */
+  info(event: string, data?: object): void;
+  /** Alias for the `info` logging method. */
+  log(event: string, data?: object): void;
+  /** Logs non-fatal operational anomalies or conditions that deserve attention. */
+  warn(event: string, data?: object): void;
+  /** Logs critical errors, failures, or exceptions preventing a transaction/process. */
+  error(event: string, data?: unknown): void;
+  /**
+   * Directly forwards a pre-constructed `SystemLog` record through the logger's pipeline.
+   * Combines instance context before outputting.
+   */
+  write(record: SystemLog): void;
+  /**
+   * Generates a new `SystemLogger` instance that shares the existing sinks and parent
+   * context, deeply merging the newly provided context on top.
+   *
+   * @param context - The metadata to append to all subsequent logs emitted by the child logger.
+   */
+  child(context: object): SystemLogger;
+  /**
+   * Adds a new sink to this logger instance.
+   * The sink will receive all logs emitted by this logger and its descendants (unless
+   * a descendant removes it). This operation does not affect the parent logger.
+   *
+   * @param sink - The LogSink to add.
+   */
+  addSink(sink: LogSink): void;
+  /**
+   * Removes a previously added sink from this logger instance.
+   * Returns `true` if the sink was found and removed, otherwise `false`.
+   * This operation does not affect the parent logger.
+   *
+   * @param sink - The LogSink to remove.
+   */
+  removeSink(sink: LogSink): boolean;
+}
+//#endregion
 //#region src/store/logger.d.ts
 type StoreLogger = SystemLogger;
 declare function createStoreLogger(logger?: StoreLogger): StoreLogger;
@@ -557,7 +761,7 @@ declare class ReactiveDataStore<T extends object> implements DataStore<T> {
   /**
    * Creates a new ReactiveDataStore instance.
    */
-  constructor(initialData: T, persistence?: SimplePersistence<T>, deleteMarker?: symbol, options?: {
+  constructor(initialData: T | {}, persistence?: SimplePersistence<T>, deleteMarker?: symbol, options?: {
     persistenceMaxRetries?: number;
     persistenceRetryDelay?: number;
     broadcastChannel?: string;
@@ -762,56 +966,6 @@ declare class StoreRegistry<S extends object> {
   get size(): number;
 }
 //#endregion
-//#region src/persistence/types.d.ts
-interface SimplePersistence$1<T> {
-  /**
-   * Persists data to storage.
-   *
-   * @param id The **unique identifier of the *consumer instance*** making the change. This is NOT the ID of the data (`T`) itself.
-   * Think of it as the ID of the specific browser tab, component, or module that's currently interacting with the persistence layer.
-   * It should typically be a **UUID** generated once at the consumer instance's instantiation.
-   * This `id` is crucial for the `subscribe` method, helping to differentiate updates originating from the current instance versus other instances/tabs, thereby preventing self-triggered notification loops.
-   * @param state The state (of type T) to persist. This state is generally considered the **global or shared state** that all instances interact with.
-   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations (like `IndexedDBPersistence`), this returns a `Promise<boolean>`.
-   */
-  set(id: string, state: T): boolean | Promise<boolean>;
-  /**
-   * Retrieves the global persisted data from storage.
-   *
-   * @returns The retrieved state of type `T`, or `null` if no data is found or if an error occurs during retrieval/parsing.
-   * For asynchronous implementations, this returns a `Promise<T | null>`.
-   */
-  get(): (T | null) | Promise<T | null>;
-  /**
-   * Subscribes to changes in the global persisted data that originate from *other* instances of your application (e.g., other tabs or independent components using the same persistence layer).
-   *
-   * @param id The **unique identifier of the *consumer instance* subscribing**. This allows the persistence implementation to filter out notifications that were initiated by the subscribing instance itself.
-   * @param callback The function to call when the global persisted data changes from *another* source. The new state (`T`) is passed as an argument to this callback.
-   * @returns A function that, when called, will unsubscribe the provided callback from future updates. Call this when your component or instance is no longer active to prevent memory leaks.
-   */
-  subscribe(id: string, callback: (state: T) => void): () => void;
-  /**
-   * Clears (removes) the entire global persisted data from storage.
-   *
-   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
-   */
-  clear(): boolean | Promise<boolean>;
-  /**
-   * Returns metadata about the persistence layer.
-   *
-   * This is useful for distinguishing between multiple apps running on the same host
-   * (e.g., several apps served at `localhost:3000` that share the same storage key).
-   *
-   * @returns An object containing:
-   * - `version`: The semantic version string of the persistence schema or application.
-   * - `id`: A unique identifier for the application using this persistence instance.
-   */
-  stats(): {
-    version: string;
-    id: string;
-  };
-}
-//#endregion
 //#region src/store/observer.d.ts
 /**
  * @interface DebugEvent
@@ -1015,13 +1169,13 @@ declare class StoreObserver<T extends object> {
    * @param persistence An object implementing the SimplePersistence interface.
    * @returns A promise that resolves to true if the session was saved successfully.
    */
-  saveSession(persistence: SimplePersistence$1<ObserverSessionData<T>>): Promise<boolean>;
+  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$1<ObserverSessionData<T>>): Promise<boolean>;
+  loadSession(persistence: SimplePersistence<ObserverSessionData<T>>): Promise<boolean>;
   /**
    * Exports the current session data as a JSON file, initiating a browser download.
    */

package/index.d.ts

@@ -1,7 +1,6 @@
-import { EventBus, SubscribeOptions, SubscribeOptions as SubscribeOptions$1 } from "@core/events";
-import { SystemLogger } from "@core/logger";
-import { SimplePersistence } from "@core/persistence";
-import { SimplePersistence as SimplePersistence$1 } from "@asaidimu/utils-persistence";
+import { EventBus, SubscribeOptions, SubscribeOptions as SubscribeOptions$1 } from "@asaidimu/utils-events";
+import { SystemLogger } from "@asaidimu/utils-logger";
+import { SimplePersistence } from "@asaidimu/utils-persistence";
 
 //#region src/store/types.d.ts
 /**
@@ -558,7 +557,7 @@ declare class ReactiveDataStore<T extends object> implements DataStore<T> {
   /**
    * Creates a new ReactiveDataStore instance.
    */
-  constructor(initialData: T, persistence?: SimplePersistence<T>, deleteMarker?: symbol, options?: {
+  constructor(initialData: T | {}, persistence?: SimplePersistence<T>, deleteMarker?: symbol, options?: {
     persistenceMaxRetries?: number;
     persistenceRetryDelay?: number;
     broadcastChannel?: string;
@@ -966,13 +965,13 @@ declare class StoreObserver<T extends object> {
    * @param persistence An object implementing the SimplePersistence interface.
    * @returns A promise that resolves to true if the session was saved successfully.
    */
-  saveSession(persistence: SimplePersistence$1<ObserverSessionData<T>>): Promise<boolean>;
+  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$1<ObserverSessionData<T>>): Promise<boolean>;
+  loadSession(persistence: SimplePersistence<ObserverSessionData<T>>): Promise<boolean>;
   /**
    * Exports the current session data as a JSON file, initiating a browser download.
    */