@asaidimu/utils-database 3.0.0 → 3.1.1

package/README.md

@@ -83,7 +83,7 @@ const db = await DatabaseConnection(
     enableTelemetry: true,
     predicates: {}, // custom validation predicates (optional)
   },
-  createIndexedDbStore
+  createIndexedDbStore,
 );
 ```
 
@@ -171,7 +171,7 @@ await db.migrateCollection(
     },
     description: "Add active flag",
   },
-  100 // batch size (optional)
+  100, // batch size (optional)
 );
 ```
 
@@ -199,7 +199,9 @@ const unsubDoc = doc.subscribe("document:update", (event) => {
 
 // Telemetry (when enableTelemetry: true)
 db.subscribe("telemetry", (event) => {
-  console.log(`${event.method} took ${event.metadata.performance.durationMs}ms`);
+  console.log(
+    `${event.method} took ${event.metadata.performance.durationMs}ms`,
+  );
 });
 ```
 
@@ -291,10 +293,10 @@ For migrations: `migrateCollection` streams documents from the store, passes the
 
 ### Available Scripts
 
-| Command           | Description                                        |
-| ----------------- | -------------------------------------------------- |
-| `npm test`        | Run tests once (Vitest)                           |
-| `npm run test:watch` | Run tests in watch mode                       |
+| Command                | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `npm test`             | Run tests once (Vitest)                           |
+| `npm run test:watch`   | Run tests in watch mode                           |
 | `npm run test:browser` | Run tests in a real browser (Vitest browser mode) |
 
 ### Testing
@@ -323,12 +325,12 @@ Use the [GitHub issue tracker](https://github.com/asaidimu/erp-utils/issues) to
 
 ### Troubleshooting
 
-| Error                             | Likely cause & solution                                   |
-| --------------------------------- | --------------------------------------------------------- |
-| `SCHEMA_NOT_FOUND`                | The collection was not created. Call `createCollection` first. |
-| `CONFLICT`                        | Another operation updated the document. Re‑fetch and retry. |
-| `TRANSACTION_FAILED`              | One of the batched writes failed. Check individual operations. |
-| `INVALID_DATA`                    | The document does not match the schema. Review validation errors. |
+| Error                | Likely cause & solution                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| `SCHEMA_NOT_FOUND`   | The collection was not created. Call `createCollection` first.    |
+| `CONFLICT`           | Another operation updated the document. Re‑fetch and retry.       |
+| `TRANSACTION_FAILED` | One of the batched writes failed. Check individual operations.    |
+| `INVALID_DATA`       | The document does not match the schema. Review validation errors. |
 
 ### FAQ
 
@@ -355,6 +357,7 @@ This project is licensed under the **MIT License**. See the [LICENSE](https://gi
 ### Acknowledgments
 
 Built with ❤️ using:
+
 - [`@asaidimu/anansi`](https://github.com/asaidimu/anansi) – schema validation and migrations.
 - [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) – Standard Schema interoperability.
 - [`uuid`](https://github.com/uuidjs/uuid) – for v7 UUIDs.

package/index.d.mts

@@ -1,5 +1,6 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
+import { EventBus } from '@core/events';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
@@ -740,6 +741,23 @@ 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 MiddlewareContext {
+    collection?: string;
+    documentId?: string;
+    operation: string;
+    args: any[];
+    eventBus?: EventBus<any>;
+}
+type MaybePromise<T> = T | Promise<T>;
+type MiddlewareNext = () => MaybePromise<any>;
+type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => MaybePromise<any>;
+declare class Pipeline {
+    private middlewares;
+    use(middleware: Middleware): void;
+    execute(ctx: MiddlewareContext, finalOperation: () => MaybePromise<any>): MaybePromise<any>;
+    wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
+}
+
 interface MutexOptions {
     /**
      * Maximum number of pending requests allowed in the queue.
@@ -807,76 +825,6 @@ declare class Mutex {
     pending(): number;
 }
 
-/**
- * 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;
-    operation: string;
-    args: any[];
-    eventBus?: EventBus<any>;
-}
-type MaybePromise<T> = T | Promise<T>;
-type MiddlewareNext = () => MaybePromise<any>;
-type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => MaybePromise<any>;
-declare class Pipeline {
-    private middlewares;
-    use(middleware: Middleware): void;
-    execute(ctx: MiddlewareContext, finalOperation: () => MaybePromise<any>): MaybePromise<any>;
-    wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
-}
-
 interface DocumentOptions<T extends Record<string, any>> {
     /**
      * The already-persisted initial state of the document.

package/index.d.ts

@@ -1,5 +1,6 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
+import { EventBus } from '@core/events';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
@@ -740,6 +741,23 @@ 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 MiddlewareContext {
+    collection?: string;
+    documentId?: string;
+    operation: string;
+    args: any[];
+    eventBus?: EventBus<any>;
+}
+type MaybePromise<T> = T | Promise<T>;
+type MiddlewareNext = () => MaybePromise<any>;
+type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => MaybePromise<any>;
+declare class Pipeline {
+    private middlewares;
+    use(middleware: Middleware): void;
+    execute(ctx: MiddlewareContext, finalOperation: () => MaybePromise<any>): MaybePromise<any>;
+    wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
+}
+
 interface MutexOptions {
     /**
      * Maximum number of pending requests allowed in the queue.
@@ -807,76 +825,6 @@ declare class Mutex {
     pending(): number;
 }
 
-/**
- * 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;
-    operation: string;
-    args: any[];
-    eventBus?: EventBus<any>;
-}
-type MaybePromise<T> = T | Promise<T>;
-type MiddlewareNext = () => MaybePromise<any>;
-type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => MaybePromise<any>;
-declare class Pipeline {
-    private middlewares;
-    use(middleware: Middleware): void;
-    execute(ctx: MiddlewareContext, finalOperation: () => MaybePromise<any>): MaybePromise<any>;
-    wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
-}
-
 interface DocumentOptions<T extends Record<string, any>> {
     /**
      * The already-persisted initial state of the document.