@asaidimu/utils-database 1.1.1 → 2.0.0

package/README.md

@@ -16,7 +16,7 @@ A flexible, schema-driven document database layer for browser and Node.js with b
   - [Basic CRUD](#basic-crud)
   - [Transactions](#transactions)
   - [Migrations](#migrations)
-  - [Events & Telemetry](#events--telemetry)
+  - [Events & Telemetry](#events-telemetry)
   - [Pagination & Filtering](#pagination--filtering)
 - [Project Architecture](#project-architecture)
 - [Development & Contributing](#development--contributing)
@@ -60,7 +60,7 @@ npm install @asaidimu/utils-database
 This package has the following peer dependencies – you need to install them manually:
 
 ```bash
-npm install @asaidimu/anansi @asaidimu/events
+npm install @asaidimu/anansi
 ```
 
 ### Basic Configuration
@@ -356,7 +356,6 @@ This project is licensed under the **MIT License**. See the [LICENSE](https://gi
 
 Built with ❤️ using:
 - [`@asaidimu/anansi`](https://github.com/asaidimu/anansi) – schema validation and migrations.
-- [`@asaidimu/events`](https://github.com/asaidimu/events) – type‑safe event bus.
 - [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) – Standard Schema interoperability.
 - [`uuid`](https://github.com/uuidjs/uuid) – for v7 UUIDs.
 - [`fake-indexeddb`](https://github.com/dumbmatter/fakeIndexedDB) – testing support.

package/index.d.mts

@@ -1,6 +1,5 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
-import { EventBus } from '@asaidimu/events';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
@@ -728,6 +727,59 @@ declare const createIndexedDbStore: <T extends Record<string, any>>(config: Stor
 
 declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
+/**
+ * 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.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => 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: (payload: TEventMap[TEventName]) => void) => () => 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.
+     */
+    clear: () => 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 MiddlewareContext {
     collection?: string;
     documentId?: string;
@@ -789,4 +841,51 @@ declare function openCollection<T extends Record<string, any>>({ collection: sch
     validate: boolean;
 }): Promise<Collection<T>>;
 
-export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };
+/**
+ * Error types for Database operations.
+ */
+declare enum DatabaseErrorType {
+    /** The schema does not exist. */
+    SCHEMA_NOT_FOUND = "SCHEMA_NOT_FOUND",
+    /** The schema already exists. */
+    SCHEMA_ALREADY_EXISTS = "SCHEMA_ALREADY_EXISTS",
+    /** The schema name is invalid. */
+    INVALID_SCHEMA_NAME = "INVALID_SCHEMA_NAME",
+    /** The schema definition is invalid. */
+    INVALID_SCHEMA_DEFINITION = "INVALID_SCHEMA_DEFINITION",
+    /** The database subscription failed. */
+    SUBSCRIPTION_FAILED = "SUBSCRIPTION_FAILED",
+    /** The database operation failed due to an internal error. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** Data being entered into a collection does not satisfy its schema definition. */
+    INVALID_DATA = "INVALID_DATA",
+    /** Optimistic Concurrency Control version mismatches */
+    CONFLICT = "CONFLICT",
+    /** For retryable store locks */
+    TRANSIENT_ERROR = "TRANSIENT_ERROR",
+    TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    INVALID_OPERATION = "INVALID_OPERATION"
+}
+/**
+ * Error class for Database operations.
+ */
+declare class DatabaseError extends Error {
+    /**
+     * The type of error that occurred.
+     */
+    type: DatabaseErrorType;
+    /**
+     * The schema associated with the error, if applicable.
+     */
+    schema?: SchemaDefinition;
+    /**
+     * Constructs a new DatabaseErrorClass instance.
+     * @param type - The type of error that occurred.
+     * @param message - A human-readable message describing the error.
+     * @param schema - The schema associated with the error, if applicable.
+     */
+    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown);
+}
+
+export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };

package/index.d.ts

@@ -1,6 +1,5 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
-import { EventBus } from '@asaidimu/events';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
@@ -728,6 +727,59 @@ declare const createIndexedDbStore: <T extends Record<string, any>>(config: Stor
 
 declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
+/**
+ * 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.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => 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: (payload: TEventMap[TEventName]) => void) => () => 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.
+     */
+    clear: () => 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 MiddlewareContext {
     collection?: string;
     documentId?: string;
@@ -789,4 +841,51 @@ declare function openCollection<T extends Record<string, any>>({ collection: sch
     validate: boolean;
 }): Promise<Collection<T>>;
 
-export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };
+/**
+ * Error types for Database operations.
+ */
+declare enum DatabaseErrorType {
+    /** The schema does not exist. */
+    SCHEMA_NOT_FOUND = "SCHEMA_NOT_FOUND",
+    /** The schema already exists. */
+    SCHEMA_ALREADY_EXISTS = "SCHEMA_ALREADY_EXISTS",
+    /** The schema name is invalid. */
+    INVALID_SCHEMA_NAME = "INVALID_SCHEMA_NAME",
+    /** The schema definition is invalid. */
+    INVALID_SCHEMA_DEFINITION = "INVALID_SCHEMA_DEFINITION",
+    /** The database subscription failed. */
+    SUBSCRIPTION_FAILED = "SUBSCRIPTION_FAILED",
+    /** The database operation failed due to an internal error. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** Data being entered into a collection does not satisfy its schema definition. */
+    INVALID_DATA = "INVALID_DATA",
+    /** Optimistic Concurrency Control version mismatches */
+    CONFLICT = "CONFLICT",
+    /** For retryable store locks */
+    TRANSIENT_ERROR = "TRANSIENT_ERROR",
+    TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    INVALID_OPERATION = "INVALID_OPERATION"
+}
+/**
+ * Error class for Database operations.
+ */
+declare class DatabaseError extends Error {
+    /**
+     * The type of error that occurred.
+     */
+    type: DatabaseErrorType;
+    /**
+     * The schema associated with the error, if applicable.
+     */
+    schema?: SchemaDefinition;
+    /**
+     * Constructs a new DatabaseErrorClass instance.
+     * @param type - The type of error that occurred.
+     * @param message - A human-readable message describing the error.
+     * @param schema - The schema associated with the error, if applicable.
+     */
+    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown);
+}
+
+export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };