@decaf-ts/core 0.5.1 → 0.5.2

package/lib/persistence/Dispatch.d.ts

@@ -4,15 +4,128 @@ import { Observable, Observer } from "../interfaces";
 import { Adapter } from "./Adapter";
 import { Logger } from "@decaf-ts/logging";
 import { EventIds } from "./types";
+/**
+ * @description Dispatches database operation events to observers
+ * @summary The Dispatch class implements the Observable interface and is responsible for intercepting
+ * database operations from an Adapter and notifying observers when changes occur. It uses proxies to
+ * wrap the adapter's CRUD methods and automatically trigger observer updates after operations complete.
+ * @template Y - The native database driver type
+ * @param {void} - No constructor parameters
+ * @class Dispatch
+ * @example
+ * ```typescript
+ * // Creating and using a Dispatch instance
+ * const dispatch = new Dispatch<PostgresDriver>();
+ *
+ * // Connect it to an adapter
+ * const adapter = new PostgresAdapter(connection);
+ * dispatch.observe(adapter);
+ *
+ * // Now any CRUD operations on the adapter will automatically
+ * // trigger observer notifications
+ * await adapter.create('users', 123, userModel);
+ * // Observers will be notified about the creation
+ *
+ * // When done, you can disconnect
+ * dispatch.unObserve(adapter);
+ * ```
+ */
 export declare class Dispatch<Y> implements Observable {
+    /**
+     * @description The adapter being observed
+     * @summary Reference to the database adapter whose operations are being monitored
+     */
     protected adapter?: Adapter<Y, any, any, any>;
+    /**
+     * @description The native database driver
+     * @summary Reference to the underlying database driver from the adapter
+     */
     protected native?: Y;
+    /**
+     * @description List of model constructors
+     * @summary Array of model constructors that are registered with the adapter
+     */
     protected models: ModelConstructor<any>[];
+    /**
+     * @description Logger instance
+     * @summary Logger for recording dispatch activities
+     */
     private logger;
+    /**
+     * @description Accessor for the logger
+     * @summary Gets or initializes the logger for this dispatch instance
+     * @return {Logger} The logger instance
+     */
     protected get log(): Logger;
+    /**
+     * @description Creates a new Dispatch instance
+     * @summary Initializes a new Dispatch instance without any adapter
+     */
     constructor();
-    protected initialize(): void;
+    /**
+     * @description Initializes the dispatch by proxying adapter methods
+     * @summary Sets up proxies on the adapter's CRUD methods to intercept operations and notify observers.
+     * This method is called automatically when an adapter is observed.
+     * @return {Promise<void>} A promise that resolves when initialization is complete
+     * @mermaid
+     * sequenceDiagram
+     *   participant Dispatch
+     *   participant Adapter
+     *   participant Proxy
+     *
+     *   Dispatch->>Dispatch: initialize()
+     *   Dispatch->>Dispatch: Check if adapter exists
+     *   alt No adapter
+     *     Dispatch-->>Dispatch: Throw InternalError
+     *   end
+     *
+     *   loop For each CRUD method
+     *     Dispatch->>Adapter: Check if method exists
+     *     alt Method doesn't exist
+     *       Dispatch-->>Dispatch: Throw InternalError
+     *     end
+     *
+     *     Dispatch->>Adapter: Get property descriptor
+     *     loop While descriptor not found
+     *       Dispatch->>Adapter: Check prototype chain
+     *     end
+     *
+     *     alt Descriptor not found or not writable
+     *       Dispatch->>Dispatch: Log error and continue
+     *     else Descriptor found and writable
+     *       Dispatch->>Proxy: Create proxy for method
+     *       Dispatch->>Adapter: Replace method with proxy
+     *     end
+     *   end
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * @description Closes the dispatch
+     * @summary Performs any necessary cleanup when the dispatch is no longer needed
+     * @return {Promise<void>} A promise that resolves when closing is complete
+     */
+    close(): Promise<void>;
+    /**
+     * @description Starts observing an adapter
+     * @summary Connects this dispatch to an adapter to monitor its operations
+     * @param {Adapter<Y, any, any, any>} observer - The adapter to observe
+     * @return {void}
+     */
     observe(observer: Adapter<Y, any, any, any>): void;
+    /**
+     * @description Stops observing an adapter
+     * @summary Disconnects this dispatch from an adapter
+     * @param {Observer} observer - The adapter to stop observing
+     * @return {void}
+     */
     unObserve(observer: Observer): void;
+    /**
+     * @description Updates observers about a database event
+     * @summary Notifies observers about a change in the database
+     * @param {string} table - The name of the table where the change occurred
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of operation that occurred
+     * @param {EventIds} id - The identifier(s) of the affected record(s)
+     * @return {Promise<void>} A promise that resolves when all observers have been notified
+     */
     updateObservers(table: string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds): Promise<void>;
 }

package/lib/persistence/ObserverHandler.cjs

@@ -2,25 +2,120 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObserverHandler = void 0;
 const db_decorators_1 = require("@decaf-ts/db-decorators");
+/**
+ * @description Manages a collection of observers for database events
+ * @summary The ObserverHandler class implements the Observable interface and provides a centralized
+ * way to manage multiple observers. It allows registering observers with optional filters to control
+ * which events they receive notifications for, and handles the process of notifying all relevant
+ * observers when database events occur.
+ * @class ObserverHandler
+ * @example
+ * ```typescript
+ * // Create an observer handler
+ * const handler = new ObserverHandler();
+ *
+ * // Register an observer
+ * const myObserver = {
+ *   refresh: async (table, event, id) => {
+ *     console.log(`Change in ${table}: ${event} for ID ${id}`);
+ *   }
+ * };
+ *
+ * // Add observer with a filter for only user table events
+ * handler.observe(myObserver, (table, event, id) => table === 'users');
+ *
+ * // Notify observers about an event
+ * await handler.updateObservers(logger, 'users', 'CREATE', 123);
+ *
+ * // Remove an observer when no longer needed
+ * handler.unObserve(myObserver);
+ * ```
+ */
 class ObserverHandler {
     constructor() {
+        /**
+         * @description Collection of registered observers
+         * @summary Array of observer objects along with their optional filters
+         */
         this.observers = [];
     }
+    /**
+     * @description Gets the number of registered observers
+     * @summary Returns the count of observers currently registered with this handler
+     * @return {number} The number of registered observers
+     */
     count() {
         return this.observers.length;
     }
+    /**
+     * @description Registers a new observer
+     * @summary Adds an observer to the collection with an optional filter function
+     * @param {Observer} observer - The observer to register
+     * @param {ObserverFilter} [filter] - Optional filter function to determine which events the observer receives
+     * @return {void}
+     */
     observe(observer, filter) {
         const index = this.observers.map((o) => o.observer).indexOf(observer);
         if (index !== -1)
             throw new db_decorators_1.InternalError("Observer already registered");
         this.observers.push({ observer: observer, filter: filter });
     }
+    /**
+     * @description Unregisters an observer
+     * @summary Removes an observer from the collection
+     * @param {Observer} observer - The observer to unregister
+     * @return {void}
+     */
     unObserve(observer) {
         const index = this.observers.map((o) => o.observer).indexOf(observer);
         if (index === -1)
             throw new db_decorators_1.InternalError("Failed to find Observer");
         this.observers.splice(index, 1);
     }
+    /**
+     * @description Notifies all relevant observers about a database event
+     * @summary Filters observers based on their filter functions and calls refresh on each matching observer
+     * @param {Logger} log - Logger for recording notification activities
+     * @param {string} table - The name of the table where the event occurred
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of operation that occurred
+     * @param {EventIds} id - The identifier(s) of the affected record(s)
+     * @param {...any[]} args - Additional arguments to pass to the observers
+     * @return {Promise<void>} A promise that resolves when all observers have been notified
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant ObserverHandler
+     *   participant Observer
+     *
+     *   Client->>ObserverHandler: updateObservers(log, table, event, id, ...args)
+     *
+     *   ObserverHandler->>ObserverHandler: Filter observers
+     *
+     *   loop For each observer with matching filter
+     *     alt Observer has filter
+     *       ObserverHandler->>Observer: Apply filter(table, event, id)
+     *       alt Filter throws error
+     *         ObserverHandler->>Logger: Log error
+     *         ObserverHandler-->>ObserverHandler: Skip observer
+     *       else Filter returns true
+     *         ObserverHandler->>Observer: refresh(table, event, id, ...args)
+     *       else Filter returns false
+     *         ObserverHandler-->>ObserverHandler: Skip observer
+     *       end
+     *     else No filter
+     *       ObserverHandler->>Observer: refresh(table, event, id, ...args)
+     *     end
+     *   end
+     *
+     *   ObserverHandler->>ObserverHandler: Process results
+     *   loop For each result
+     *     alt Result is rejected
+     *       ObserverHandler->>Logger: Log error
+     *     end
+     *   end
+     *
+     *   ObserverHandler-->>Client: Return
+     */
     async updateObservers(log, table, event, id, ...args) {
         const results = await Promise.allSettled(this.observers
             .filter((o) => {
@@ -43,4 +138,4 @@ class ObserverHandler {
     }
 }
 exports.ObserverHandler = ObserverHandler;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiT2JzZXJ2ZXJIYW5kbGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL09ic2VydmVySGFuZGxlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFFQSwyREFJaUM7QUFHakMsTUFBYSxlQUFlO0lBQTVCO1FBQ3FCLGNBQVMsR0FHdEIsRUFBRSxDQUFDO0lBZ0RYLENBQUM7SUE5Q0MsS0FBSztRQUNILE9BQU8sSUFBSSxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUM7SUFDL0IsQ0FBQztJQUVELE9BQU8sQ0FBQyxRQUFrQixFQUFFLE1BQXVCO1FBQ2pELE1BQU0sS0FBSyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3RFLElBQUksS0FBSyxLQUFLLENBQUMsQ0FBQztZQUFFLE1BQU0sSUFBSSw2QkFBYSxDQUFDLDZCQUE2QixDQUFDLENBQUM7UUFDekUsSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsRUFBRSxRQUFRLEVBQUUsUUFBUSxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsQ0FBQyxDQUFDO0lBQzlELENBQUM7SUFFRCxTQUFTLENBQUMsUUFBa0I7UUFDMUIsTUFBTSxLQUFLLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUMsQ0FBQyxPQUFPLENBQUMsUUFBUSxDQUFDLENBQUM7UUFDdEUsSUFBSSxLQUFLLEtBQUssQ0FBQyxDQUFDO1lBQUUsTUFBTSxJQUFJLDZCQUFhLENBQUMseUJBQXlCLENBQUMsQ0FBQztRQUNyRSxJQUFJLENBQUMsU0FBUyxDQUFDLE1BQU0sQ0FBQyxLQUFLLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDbEMsQ0FBQztJQUVELEtBQUssQ0FBQyxlQUFlLENBQ25CLEdBQVcsRUFDWCxLQUFhLEVBQ2IsS0FBcUQsRUFDckQsRUFBWSxFQUNaLEdBQUcsSUFBVztRQUVkLE1BQU0sT0FBTyxHQUFHLE1BQU0sT0FBTyxDQUFDLFVBQVUsQ0FDdEMsSUFBSSxDQUFDLFNBQVM7YUFDWCxNQUFNLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRTtZQUNaLE1BQU0sRUFBRSxNQUFNLEVBQUUsR0FBRyxDQUFDLENBQUM7WUFDckIsSUFBSSxDQUFDLE1BQU07Z0JBQUUsT0FBTyxJQUFJLENBQUM7WUFDekIsSUFBSSxDQUFDO2dCQUNILE9BQU8sTUFBTSxDQUFDLEtBQUssRUFBRSxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUM7WUFDbEMsQ0FBQztZQUFDLE9BQU8sQ0FBVSxFQUFFLENBQUM7Z0JBQ3BCLEdBQUcsQ0FBQyxLQUFLLENBQ1AsNkJBQTZCLENBQUMsQ0FBQyxRQUFRLENBQUMsUUFBUSxFQUFFLEtBQUssQ0FBQyxFQUFFLENBQzNELENBQUM7Z0JBQ0YsT0FBTyxLQUFLLENBQUM7WUFDZixDQUFDO1FBQ0gsQ0FBQyxDQUFDO2FBQ0QsR0FBRyxDQUFDLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsS0FBSyxFQUFFLEVBQUUsRUFBRSxHQUFHLElBQUksQ0FBQyxDQUFDLENBQzdELENBQUM7UUFDRixPQUFPLENBQUMsT0FBTyxDQUFDLENBQUMsTUFBTSxFQUFFLENBQUMsRUFBRSxFQUFFO1lBQzVCLElBQUksTUFBTSxDQUFDLE1BQU0sS0FBSyxVQUFVO2dCQUM5QixHQUFHLENBQUMsS0FBSyxDQUNQLCtCQUErQixJQUFJLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxDQUFDLFFBQVEsRUFBRSxLQUFLLE1BQU0sQ0FBQyxNQUFNLEVBQUUsQ0FDaEYsQ0FBQztRQUNOLENBQUMsQ0FBQyxDQUFDO0lBQ0wsQ0FBQztDQUNGO0FBcERELDBDQW9EQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IE9ic2VydmFibGUsIE9ic2VydmVyIH0gZnJvbSBcIi4uL2ludGVyZmFjZXNcIjtcbmltcG9ydCB7IEV2ZW50SWRzLCBPYnNlcnZlckZpbHRlciB9IGZyb20gXCIuL3R5cGVzXCI7XG5pbXBvcnQge1xuICBCdWxrQ3J1ZE9wZXJhdGlvbktleXMsXG4gIEludGVybmFsRXJyb3IsXG4gIE9wZXJhdGlvbktleXMsXG59IGZyb20gXCJAZGVjYWYtdHMvZGItZGVjb3JhdG9yc1wiO1xuaW1wb3J0IHsgTG9nZ2VyIH0gZnJvbSBcIkBkZWNhZi10cy9sb2dnaW5nXCI7XG5cbmV4cG9ydCBjbGFzcyBPYnNlcnZlckhhbmRsZXIgaW1wbGVtZW50cyBPYnNlcnZhYmxlIHtcbiAgcHJvdGVjdGVkIHJlYWRvbmx5IG9ic2VydmVyczoge1xuICAgIG9ic2VydmVyOiBPYnNlcnZlcjtcbiAgICBmaWx0ZXI/OiBPYnNlcnZlckZpbHRlcjtcbiAgfVtdID0gW107XG5cbiAgY291bnQoKSB7XG4gICAgcmV0dXJuIHRoaXMub2JzZXJ2ZXJzLmxlbmd0aDtcbiAgfVxuXG4gIG9ic2VydmUob2JzZXJ2ZXI6IE9ic2VydmVyLCBmaWx0ZXI/OiBPYnNlcnZlckZpbHRlcik6IHZvaWQge1xuICAgIGNvbnN0IGluZGV4ID0gdGhpcy5vYnNlcnZlcnMubWFwKChvKSA9PiBvLm9ic2VydmVyKS5pbmRleE9mKG9ic2VydmVyKTtcbiAgICBpZiAoaW5kZXggIT09IC0xKSB0aHJvdyBuZXcgSW50ZXJuYWxFcnJvcihcIk9ic2VydmVyIGFscmVhZHkgcmVnaXN0ZXJlZFwiKTtcbiAgICB0aGlzLm9ic2VydmVycy5wdXNoKHsgb2JzZXJ2ZXI6IG9ic2VydmVyLCBmaWx0ZXI6IGZpbHRlciB9KTtcbiAgfVxuXG4gIHVuT2JzZXJ2ZShvYnNlcnZlcjogT2JzZXJ2ZXIpOiB2b2lkIHtcbiAgICBjb25zdCBpbmRleCA9IHRoaXMub2JzZXJ2ZXJzLm1hcCgobykgPT4gby5vYnNlcnZlcikuaW5kZXhPZihvYnNlcnZlcik7XG4gICAgaWYgKGluZGV4ID09PSAtMSkgdGhyb3cgbmV3IEludGVybmFsRXJyb3IoXCJGYWlsZWQgdG8gZmluZCBPYnNlcnZlclwiKTtcbiAgICB0aGlzLm9ic2VydmVycy5zcGxpY2UoaW5kZXgsIDEpO1xuICB9XG5cbiAgYXN5bmMgdXBkYXRlT2JzZXJ2ZXJzKFxuICAgIGxvZzogTG9nZ2VyLFxuICAgIHRhYmxlOiBzdHJpbmcsXG4gICAgZXZlbnQ6IE9wZXJhdGlvbktleXMgfCBCdWxrQ3J1ZE9wZXJhdGlvbktleXMgfCBzdHJpbmcsXG4gICAgaWQ6IEV2ZW50SWRzLFxuICAgIC4uLmFyZ3M6IGFueVtdXG4gICk6IFByb21pc2U8dm9pZD4ge1xuICAgIGNvbnN0IHJlc3VsdHMgPSBhd2FpdCBQcm9taXNlLmFsbFNldHRsZWQoXG4gICAgICB0aGlzLm9ic2VydmVyc1xuICAgICAgICAuZmlsdGVyKChvKSA9PiB7XG4gICAgICAgICAgY29uc3QgeyBmaWx0ZXIgfSA9IG87XG4gICAgICAgICAgaWYgKCFmaWx0ZXIpIHJldHVybiB0cnVlO1xuICAgICAgICAgIHRyeSB7XG4gICAgICAgICAgICByZXR1cm4gZmlsdGVyKHRhYmxlLCBldmVudCwgaWQpO1xuICAgICAgICAgIH0gY2F0Y2ggKGU6IHVua25vd24pIHtcbiAgICAgICAgICAgIGxvZy5lcnJvcihcbiAgICAgICAgICAgICAgYEZhaWxlZCB0byBmaWx0ZXIgb2JzZXJ2ZXIgJHtvLm9ic2VydmVyLnRvU3RyaW5nKCl9OiAke2V9YFxuICAgICAgICAgICAgKTtcbiAgICAgICAgICAgIHJldHVybiBmYWxzZTtcbiAgICAgICAgICB9XG4gICAgICAgIH0pXG4gICAgICAgIC5tYXAoKG8pID0+IG8ub2JzZXJ2ZXIucmVmcmVzaCh0YWJsZSwgZXZlbnQsIGlkLCAuLi5hcmdzKSlcbiAgICApO1xuICAgIHJlc3VsdHMuZm9yRWFjaCgocmVzdWx0LCBpKSA9PiB7XG4gICAgICBpZiAocmVzdWx0LnN0YXR1cyA9PT0gXCJyZWplY3RlZFwiKVxuICAgICAgICBsb2cuZXJyb3IoXG4gICAgICAgICAgYEZhaWxlZCB0byB1cGRhdGUgb2JzZXJ2YWJsZSAke3RoaXMub2JzZXJ2ZXJzW2ldLnRvU3RyaW5nKCl9OiAke3Jlc3VsdC5yZWFzb259YFxuICAgICAgICApO1xuICAgIH0pO1xuICB9XG59XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiT2JzZXJ2ZXJIYW5kbGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL09ic2VydmVySGFuZGxlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFFQSwyREFJaUM7QUFHakM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0E0Qkc7QUFDSCxNQUFhLGVBQWU7SUFBNUI7UUFDRTs7O1dBR0c7UUFDZ0IsY0FBUyxHQUd0QixFQUFFLENBQUM7SUE4R1gsQ0FBQztJQTVHQzs7OztPQUlHO0lBQ0gsS0FBSztRQUNILE9BQU8sSUFBSSxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUM7SUFDL0IsQ0FBQztJQUVEOzs7Ozs7T0FNRztJQUNILE9BQU8sQ0FBQyxRQUFrQixFQUFFLE1BQXVCO1FBQ2pELE1BQU0sS0FBSyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3RFLElBQUksS0FBSyxLQUFLLENBQUMsQ0FBQztZQUFFLE1BQU0sSUFBSSw2QkFBYSxDQUFDLDZCQUE2QixDQUFDLENBQUM7UUFDekUsSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsRUFBRSxRQUFRLEVBQUUsUUFBUSxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsQ0FBQyxDQUFDO0lBQzlELENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILFNBQVMsQ0FBQyxRQUFrQjtRQUMxQixNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQztRQUN0RSxJQUFJLEtBQUssS0FBSyxDQUFDLENBQUM7WUFBRSxNQUFNLElBQUksNkJBQWEsQ0FBQyx5QkFBeUIsQ0FBQyxDQUFDO1FBQ3JFLElBQUksQ0FBQyxTQUFTLENBQUMsTUFBTSxDQUFDLEtBQUssRUFBRSxDQUFDLENBQUMsQ0FBQztJQUNsQyxDQUFDO0lBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0EyQ0c7SUFDSCxLQUFLLENBQUMsZUFBZSxDQUNuQixHQUFXLEVBQ1gsS0FBYSxFQUNiLEtBQXFELEVBQ3JELEVBQVksRUFDWixHQUFHLElBQVc7UUFFZCxNQUFNLE9BQU8sR0FBRyxNQUFNLE9BQU8sQ0FBQyxVQUFVLENBQ3RDLElBQUksQ0FBQyxTQUFTO2FBQ1gsTUFBTSxDQUFDLENBQUMsQ0FBQyxFQUFFLEVBQUU7WUFDWixNQUFNLEVBQUUsTUFBTSxFQUFFLEdBQUcsQ0FBQyxDQUFDO1lBQ3JCLElBQUksQ0FBQyxNQUFNO2dCQUFFLE9BQU8sSUFBSSxDQUFDO1lBQ3pCLElBQUksQ0FBQztnQkFDSCxPQUFPLE1BQU0sQ0FBQyxLQUFLLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQyxDQUFDO1lBQ2xDLENBQUM7WUFBQyxPQUFPLENBQVUsRUFBRSxDQUFDO2dCQUNwQixHQUFHLENBQUMsS0FBSyxDQUNQLDZCQUE2QixDQUFDLENBQUMsUUFBUSxDQUFDLFFBQVEsRUFBRSxLQUFLLENBQUMsRUFBRSxDQUMzRCxDQUFDO2dCQUNGLE9BQU8sS0FBSyxDQUFDO1lBQ2YsQ0FBQztRQUNILENBQUMsQ0FBQzthQUNELEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsS0FBSyxFQUFFLEtBQUssRUFBRSxFQUFFLEVBQUUsR0FBRyxJQUFJLENBQUMsQ0FBQyxDQUM3RCxDQUFDO1FBQ0YsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLEVBQUUsRUFBRTtZQUM1QixJQUFJLE1BQU0sQ0FBQyxNQUFNLEtBQUssVUFBVTtnQkFDOUIsR0FBRyxDQUFDLEtBQUssQ0FDUCwrQkFBK0IsSUFBSSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxRQUFRLEVBQUUsS0FBSyxNQUFNLENBQUMsTUFBTSxFQUFFLENBQ2hGLENBQUM7UUFDTixDQUFDLENBQUMsQ0FBQztJQUNMLENBQUM7Q0FDRjtBQXRIRCwwQ0FzSEMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBPYnNlcnZhYmxlLCBPYnNlcnZlciB9IGZyb20gXCIuLi9pbnRlcmZhY2VzXCI7XG5pbXBvcnQgeyBFdmVudElkcywgT2JzZXJ2ZXJGaWx0ZXIgfSBmcm9tIFwiLi90eXBlc1wiO1xuaW1wb3J0IHtcbiAgQnVsa0NydWRPcGVyYXRpb25LZXlzLFxuICBJbnRlcm5hbEVycm9yLFxuICBPcGVyYXRpb25LZXlzLFxufSBmcm9tIFwiQGRlY2FmLXRzL2RiLWRlY29yYXRvcnNcIjtcbmltcG9ydCB7IExvZ2dlciB9IGZyb20gXCJAZGVjYWYtdHMvbG9nZ2luZ1wiO1xuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBNYW5hZ2VzIGEgY29sbGVjdGlvbiBvZiBvYnNlcnZlcnMgZm9yIGRhdGFiYXNlIGV2ZW50c1xuICogQHN1bW1hcnkgVGhlIE9ic2VydmVySGFuZGxlciBjbGFzcyBpbXBsZW1lbnRzIHRoZSBPYnNlcnZhYmxlIGludGVyZmFjZSBhbmQgcHJvdmlkZXMgYSBjZW50cmFsaXplZFxuICogd2F5IHRvIG1hbmFnZSBtdWx0aXBsZSBvYnNlcnZlcnMuIEl0IGFsbG93cyByZWdpc3RlcmluZyBvYnNlcnZlcnMgd2l0aCBvcHRpb25hbCBmaWx0ZXJzIHRvIGNvbnRyb2xcbiAqIHdoaWNoIGV2ZW50cyB0aGV5IHJlY2VpdmUgbm90aWZpY2F0aW9ucyBmb3IsIGFuZCBoYW5kbGVzIHRoZSBwcm9jZXNzIG9mIG5vdGlmeWluZyBhbGwgcmVsZXZhbnRcbiAqIG9ic2VydmVycyB3aGVuIGRhdGFiYXNlIGV2ZW50cyBvY2N1ci5cbiAqIEBjbGFzcyBPYnNlcnZlckhhbmRsZXJcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiAvLyBDcmVhdGUgYW4gb2JzZXJ2ZXIgaGFuZGxlclxuICogY29uc3QgaGFuZGxlciA9IG5ldyBPYnNlcnZlckhhbmRsZXIoKTtcbiAqIFxuICogLy8gUmVnaXN0ZXIgYW4gb2JzZXJ2ZXJcbiAqIGNvbnN0IG15T2JzZXJ2ZXIgPSB7XG4gKiAgIHJlZnJlc2g6IGFzeW5jICh0YWJsZSwgZXZlbnQsIGlkKSA9PiB7XG4gKiAgICAgY29uc29sZS5sb2coYENoYW5nZSBpbiAke3RhYmxlfTogJHtldmVudH0gZm9yIElEICR7aWR9YCk7XG4gKiAgIH1cbiAqIH07XG4gKiBcbiAqIC8vIEFkZCBvYnNlcnZlciB3aXRoIGEgZmlsdGVyIGZvciBvbmx5IHVzZXIgdGFibGUgZXZlbnRzXG4gKiBoYW5kbGVyLm9ic2VydmUobXlPYnNlcnZlciwgKHRhYmxlLCBldmVudCwgaWQpID0+IHRhYmxlID09PSAndXNlcnMnKTtcbiAqIFxuICogLy8gTm90aWZ5IG9ic2VydmVycyBhYm91dCBhbiBldmVudFxuICogYXdhaXQgaGFuZGxlci51cGRhdGVPYnNlcnZlcnMobG9nZ2VyLCAndXNlcnMnLCAnQ1JFQVRFJywgMTIzKTtcbiAqIFxuICogLy8gUmVtb3ZlIGFuIG9ic2VydmVyIHdoZW4gbm8gbG9uZ2VyIG5lZWRlZFxuICogaGFuZGxlci51bk9ic2VydmUobXlPYnNlcnZlcik7XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGNsYXNzIE9ic2VydmVySGFuZGxlciBpbXBsZW1lbnRzIE9ic2VydmFibGUge1xuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIENvbGxlY3Rpb24gb2YgcmVnaXN0ZXJlZCBvYnNlcnZlcnNcbiAgICogQHN1bW1hcnkgQXJyYXkgb2Ygb2JzZXJ2ZXIgb2JqZWN0cyBhbG9uZyB3aXRoIHRoZWlyIG9wdGlvbmFsIGZpbHRlcnNcbiAgICovXG4gIHByb3RlY3RlZCByZWFkb25seSBvYnNlcnZlcnM6IHtcbiAgICBvYnNlcnZlcjogT2JzZXJ2ZXI7XG4gICAgZmlsdGVyPzogT2JzZXJ2ZXJGaWx0ZXI7XG4gIH1bXSA9IFtdO1xuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gR2V0cyB0aGUgbnVtYmVyIG9mIHJlZ2lzdGVyZWQgb2JzZXJ2ZXJzXG4gICAqIEBzdW1tYXJ5IFJldHVybnMgdGhlIGNvdW50IG9mIG9ic2VydmVycyBjdXJyZW50bHkgcmVnaXN0ZXJlZCB3aXRoIHRoaXMgaGFuZGxlclxuICAgKiBAcmV0dXJuIHtudW1iZXJ9IFRoZSBudW1iZXIgb2YgcmVnaXN0ZXJlZCBvYnNlcnZlcnNcbiAgICovXG4gIGNvdW50KCkge1xuICAgIHJldHVybiB0aGlzLm9ic2VydmVycy5sZW5ndGg7XG4gIH1cblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIFJlZ2lzdGVycyBhIG5ldyBvYnNlcnZlclxuICAgKiBAc3VtbWFyeSBBZGRzIGFuIG9ic2VydmVyIHRvIHRoZSBjb2xsZWN0aW9uIHdpdGggYW4gb3B0aW9uYWwgZmlsdGVyIGZ1bmN0aW9uXG4gICAqIEBwYXJhbSB7T2JzZXJ2ZXJ9IG9ic2VydmVyIC0gVGhlIG9ic2VydmVyIHRvIHJlZ2lzdGVyXG4gICAqIEBwYXJhbSB7T2JzZXJ2ZXJGaWx0ZXJ9IFtmaWx0ZXJdIC0gT3B0aW9uYWwgZmlsdGVyIGZ1bmN0aW9uIHRvIGRldGVybWluZSB3aGljaCBldmVudHMgdGhlIG9ic2VydmVyIHJlY2VpdmVzXG4gICAqIEByZXR1cm4ge3ZvaWR9XG4gICAqL1xuICBvYnNlcnZlKG9ic2VydmVyOiBPYnNlcnZlciwgZmlsdGVyPzogT2JzZXJ2ZXJGaWx0ZXIpOiB2b2lkIHtcbiAgICBjb25zdCBpbmRleCA9IHRoaXMub2JzZXJ2ZXJzLm1hcCgobykgPT4gby5vYnNlcnZlcikuaW5kZXhPZihvYnNlcnZlcik7XG4gICAgaWYgKGluZGV4ICE9PSAtMSkgdGhyb3cgbmV3IEludGVybmFsRXJyb3IoXCJPYnNlcnZlciBhbHJlYWR5IHJlZ2lzdGVyZWRcIik7XG4gICAgdGhpcy5vYnNlcnZlcnMucHVzaCh7IG9ic2VydmVyOiBvYnNlcnZlciwgZmlsdGVyOiBmaWx0ZXIgfSk7XG4gIH1cblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIFVucmVnaXN0ZXJzIGFuIG9ic2VydmVyXG4gICAqIEBzdW1tYXJ5IFJlbW92ZXMgYW4gb2JzZXJ2ZXIgZnJvbSB0aGUgY29sbGVjdGlvblxuICAgKiBAcGFyYW0ge09ic2VydmVyfSBvYnNlcnZlciAtIFRoZSBvYnNlcnZlciB0byB1bnJlZ2lzdGVyXG4gICAqIEByZXR1cm4ge3ZvaWR9XG4gICAqL1xuICB1bk9ic2VydmUob2JzZXJ2ZXI6IE9ic2VydmVyKTogdm9pZCB7XG4gICAgY29uc3QgaW5kZXggPSB0aGlzLm9ic2VydmVycy5tYXAoKG8pID0+IG8ub2JzZXJ2ZXIpLmluZGV4T2Yob2JzZXJ2ZXIpO1xuICAgIGlmIChpbmRleCA9PT0gLTEpIHRocm93IG5ldyBJbnRlcm5hbEVycm9yKFwiRmFpbGVkIHRvIGZpbmQgT2JzZXJ2ZXJcIik7XG4gICAgdGhpcy5vYnNlcnZlcnMuc3BsaWNlKGluZGV4LCAxKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gTm90aWZpZXMgYWxsIHJlbGV2YW50IG9ic2VydmVycyBhYm91dCBhIGRhdGFiYXNlIGV2ZW50XG4gICAqIEBzdW1tYXJ5IEZpbHRlcnMgb2JzZXJ2ZXJzIGJhc2VkIG9uIHRoZWlyIGZpbHRlciBmdW5jdGlvbnMgYW5kIGNhbGxzIHJlZnJlc2ggb24gZWFjaCBtYXRjaGluZyBvYnNlcnZlclxuICAgKiBAcGFyYW0ge0xvZ2dlcn0gbG9nIC0gTG9nZ2VyIGZvciByZWNvcmRpbmcgbm90aWZpY2F0aW9uIGFjdGl2aXRpZXNcbiAgICogQHBhcmFtIHtzdHJpbmd9IHRhYmxlIC0gVGhlIG5hbWUgb2YgdGhlIHRhYmxlIHdoZXJlIHRoZSBldmVudCBvY2N1cnJlZFxuICAgKiBAcGFyYW0ge09wZXJhdGlvbktleXN8QnVsa0NydWRPcGVyYXRpb25LZXlzfHN0cmluZ30gZXZlbnQgLSBUaGUgdHlwZSBvZiBvcGVyYXRpb24gdGhhdCBvY2N1cnJlZFxuICAgKiBAcGFyYW0ge0V2ZW50SWRzfSBpZCAtIFRoZSBpZGVudGlmaWVyKHMpIG9mIHRoZSBhZmZlY3RlZCByZWNvcmQocylcbiAgICogQHBhcmFtIHsuLi5hbnlbXX0gYXJncyAtIEFkZGl0aW9uYWwgYXJndW1lbnRzIHRvIHBhc3MgdG8gdGhlIG9ic2VydmVyc1xuICAgKiBAcmV0dXJuIHtQcm9taXNlPHZvaWQ+fSBBIHByb21pc2UgdGhhdCByZXNvbHZlcyB3aGVuIGFsbCBvYnNlcnZlcnMgaGF2ZSBiZWVuIG5vdGlmaWVkXG4gICAqIEBtZXJtYWlkXG4gICAqIHNlcXVlbmNlRGlhZ3JhbVxuICAgKiAgIHBhcnRpY2lwYW50IENsaWVudFxuICAgKiAgIHBhcnRpY2lwYW50IE9ic2VydmVySGFuZGxlclxuICAgKiAgIHBhcnRpY2lwYW50IE9ic2VydmVyXG4gICAqICAgXG4gICAqICAgQ2xpZW50LT4+T2JzZXJ2ZXJIYW5kbGVyOiB1cGRhdGVPYnNlcnZlcnMobG9nLCB0YWJsZSwgZXZlbnQsIGlkLCAuLi5hcmdzKVxuICAgKiAgIFxuICAgKiAgIE9ic2VydmVySGFuZGxlci0+Pk9ic2VydmVySGFuZGxlcjogRmlsdGVyIG9ic2VydmVyc1xuICAgKiAgIFxuICAgKiAgIGxvb3AgRm9yIGVhY2ggb2JzZXJ2ZXIgd2l0aCBtYXRjaGluZyBmaWx0ZXJcbiAgICogICAgIGFsdCBPYnNlcnZlciBoYXMgZmlsdGVyXG4gICAqICAgICAgIE9ic2VydmVySGFuZGxlci0+Pk9ic2VydmVyOiBBcHBseSBmaWx0ZXIodGFibGUsIGV2ZW50LCBpZClcbiAgICogICAgICAgYWx0IEZpbHRlciB0aHJvd3MgZXJyb3JcbiAgICogICAgICAgICBPYnNlcnZlckhhbmRsZXItPj5Mb2dnZXI6IExvZyBlcnJvclxuICAgKiAgICAgICAgIE9ic2VydmVySGFuZGxlci0tPj5PYnNlcnZlckhhbmRsZXI6IFNraXAgb2JzZXJ2ZXJcbiAgICogICAgICAgZWxzZSBGaWx0ZXIgcmV0dXJucyB0cnVlXG4gICAqICAgICAgICAgT2JzZXJ2ZXJIYW5kbGVyLT4+T2JzZXJ2ZXI6IHJlZnJlc2godGFibGUsIGV2ZW50LCBpZCwgLi4uYXJncylcbiAgICogICAgICAgZWxzZSBGaWx0ZXIgcmV0dXJucyBmYWxzZVxuICAgKiAgICAgICAgIE9ic2VydmVySGFuZGxlci0tPj5PYnNlcnZlckhhbmRsZXI6IFNraXAgb2JzZXJ2ZXJcbiAgICogICAgICAgZW5kXG4gICAqICAgICBlbHNlIE5vIGZpbHRlclxuICAgKiAgICAgICBPYnNlcnZlckhhbmRsZXItPj5PYnNlcnZlcjogcmVmcmVzaCh0YWJsZSwgZXZlbnQsIGlkLCAuLi5hcmdzKVxuICAgKiAgICAgZW5kXG4gICAqICAgZW5kXG4gICAqICAgXG4gICAqICAgT2JzZXJ2ZXJIYW5kbGVyLT4+T2JzZXJ2ZXJIYW5kbGVyOiBQcm9jZXNzIHJlc3VsdHNcbiAgICogICBsb29wIEZvciBlYWNoIHJlc3VsdFxuICAgKiAgICAgYWx0IFJlc3VsdCBpcyByZWplY3RlZFxuICAgKiAgICAgICBPYnNlcnZlckhhbmRsZXItPj5Mb2dnZXI6IExvZyBlcnJvclxuICAgKiAgICAgZW5kXG4gICAqICAgZW5kXG4gICAqICAgXG4gICAqICAgT2JzZXJ2ZXJIYW5kbGVyLS0+PkNsaWVudDogUmV0dXJuXG4gICAqL1xuICBhc3luYyB1cGRhdGVPYnNlcnZlcnMoXG4gICAgbG9nOiBMb2dnZXIsXG4gICAgdGFibGU6IHN0cmluZyxcbiAgICBldmVudDogT3BlcmF0aW9uS2V5cyB8IEJ1bGtDcnVkT3BlcmF0aW9uS2V5cyB8IHN0cmluZyxcbiAgICBpZDogRXZlbnRJZHMsXG4gICAgLi4uYXJnczogYW55W11cbiAgKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3QgcmVzdWx0cyA9IGF3YWl0IFByb21pc2UuYWxsU2V0dGxlZChcbiAgICAgIHRoaXMub2JzZXJ2ZXJzXG4gICAgICAgIC5maWx0ZXIoKG8pID0+IHtcbiAgICAgICAgICBjb25zdCB7IGZpbHRlciB9ID0gbztcbiAgICAgICAgICBpZiAoIWZpbHRlcikgcmV0dXJuIHRydWU7XG4gICAgICAgICAgdHJ5IHtcbiAgICAgICAgICAgIHJldHVybiBmaWx0ZXIodGFibGUsIGV2ZW50LCBpZCk7XG4gICAgICAgICAgfSBjYXRjaCAoZTogdW5rbm93bikge1xuICAgICAgICAgICAgbG9nLmVycm9yKFxuICAgICAgICAgICAgICBgRmFpbGVkIHRvIGZpbHRlciBvYnNlcnZlciAke28ub2JzZXJ2ZXIudG9TdHJpbmcoKX06ICR7ZX1gXG4gICAgICAgICAgICApO1xuICAgICAgICAgICAgcmV0dXJuIGZhbHNlO1xuICAgICAgICAgIH1cbiAgICAgICAgfSlcbiAgICAgICAgLm1hcCgobykgPT4gby5vYnNlcnZlci5yZWZyZXNoKHRhYmxlLCBldmVudCwgaWQsIC4uLmFyZ3MpKVxuICAgICk7XG4gICAgcmVzdWx0cy5mb3JFYWNoKChyZXN1bHQsIGkpID0+IHtcbiAgICAgIGlmIChyZXN1bHQuc3RhdHVzID09PSBcInJlamVjdGVkXCIpXG4gICAgICAgIGxvZy5lcnJvcihcbiAgICAgICAgICBgRmFpbGVkIHRvIHVwZGF0ZSBvYnNlcnZhYmxlICR7dGhpcy5vYnNlcnZlcnNbaV0udG9TdHJpbmcoKX06ICR7cmVzdWx0LnJlYXNvbn1gXG4gICAgICAgICk7XG4gICAgfSk7XG4gIH1cbn1cbiJdfQ==

package/lib/persistence/ObserverHandler.d.ts

@@ -2,13 +2,108 @@ import { Observable, Observer } from "../interfaces";
 import { EventIds, ObserverFilter } from "./types";
 import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
 import { Logger } from "@decaf-ts/logging";
+/**
+ * @description Manages a collection of observers for database events
+ * @summary The ObserverHandler class implements the Observable interface and provides a centralized
+ * way to manage multiple observers. It allows registering observers with optional filters to control
+ * which events they receive notifications for, and handles the process of notifying all relevant
+ * observers when database events occur.
+ * @class ObserverHandler
+ * @example
+ * ```typescript
+ * // Create an observer handler
+ * const handler = new ObserverHandler();
+ *
+ * // Register an observer
+ * const myObserver = {
+ *   refresh: async (table, event, id) => {
+ *     console.log(`Change in ${table}: ${event} for ID ${id}`);
+ *   }
+ * };
+ *
+ * // Add observer with a filter for only user table events
+ * handler.observe(myObserver, (table, event, id) => table === 'users');
+ *
+ * // Notify observers about an event
+ * await handler.updateObservers(logger, 'users', 'CREATE', 123);
+ *
+ * // Remove an observer when no longer needed
+ * handler.unObserve(myObserver);
+ * ```
+ */
 export declare class ObserverHandler implements Observable {
+    /**
+     * @description Collection of registered observers
+     * @summary Array of observer objects along with their optional filters
+     */
     protected readonly observers: {
         observer: Observer;
         filter?: ObserverFilter;
     }[];
+    /**
+     * @description Gets the number of registered observers
+     * @summary Returns the count of observers currently registered with this handler
+     * @return {number} The number of registered observers
+     */
     count(): number;
+    /**
+     * @description Registers a new observer
+     * @summary Adds an observer to the collection with an optional filter function
+     * @param {Observer} observer - The observer to register
+     * @param {ObserverFilter} [filter] - Optional filter function to determine which events the observer receives
+     * @return {void}
+     */
     observe(observer: Observer, filter?: ObserverFilter): void;
+    /**
+     * @description Unregisters an observer
+     * @summary Removes an observer from the collection
+     * @param {Observer} observer - The observer to unregister
+     * @return {void}
+     */
     unObserve(observer: Observer): void;
+    /**
+     * @description Notifies all relevant observers about a database event
+     * @summary Filters observers based on their filter functions and calls refresh on each matching observer
+     * @param {Logger} log - Logger for recording notification activities
+     * @param {string} table - The name of the table where the event occurred
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of operation that occurred
+     * @param {EventIds} id - The identifier(s) of the affected record(s)
+     * @param {...any[]} args - Additional arguments to pass to the observers
+     * @return {Promise<void>} A promise that resolves when all observers have been notified
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant ObserverHandler
+     *   participant Observer
+     *
+     *   Client->>ObserverHandler: updateObservers(log, table, event, id, ...args)
+     *
+     *   ObserverHandler->>ObserverHandler: Filter observers
+     *
+     *   loop For each observer with matching filter
+     *     alt Observer has filter
+     *       ObserverHandler->>Observer: Apply filter(table, event, id)
+     *       alt Filter throws error
+     *         ObserverHandler->>Logger: Log error
+     *         ObserverHandler-->>ObserverHandler: Skip observer
+     *       else Filter returns true
+     *         ObserverHandler->>Observer: refresh(table, event, id, ...args)
+     *       else Filter returns false
+     *         ObserverHandler-->>ObserverHandler: Skip observer
+     *       end
+     *     else No filter
+     *       ObserverHandler->>Observer: refresh(table, event, id, ...args)
+     *     end
+     *   end
+     *
+     *   ObserverHandler->>ObserverHandler: Process results
+     *   loop For each result
+     *     alt Result is rejected
+     *       ObserverHandler->>Logger: Log error
+     *     end
+     *   end
+     *
+     *   ObserverHandler-->>Client: Return
+     */
     updateObservers(log: Logger, table: string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: any[]): Promise<void>;
 }

package/lib/persistence/Sequence.cjs

@@ -4,18 +4,87 @@ exports.Sequence = void 0;
 const utils_1 = require("./../identity/utils.cjs");
 const db_decorators_1 = require("@decaf-ts/db-decorators");
 const logging_1 = require("@decaf-ts/logging");
+/**
+ * @description Abstract base class for sequence generation
+ * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
+ * Implementations of this class handle the specifics of how sequences are stored and incremented in different
+ * database systems.
+ * @param {SequenceOptions} options - Configuration options for the sequence generator
+ * @class Sequence
+ * @example
+ * ```typescript
+ * // Example implementation for a specific database
+ * class PostgresSequence extends Sequence {
+ *   constructor(options: SequenceOptions) {
+ *     super(options);
+ *   }
+ *
+ *   async next(): Promise<number> {
+ *     // Implementation to get next value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].nextval);
+ *   }
+ *
+ *   async current(): Promise<number> {
+ *     // Implementation to get current value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].currval);
+ *   }
+ *
+ *   async range(count: number): Promise<number[]> {
+ *     // Implementation to get a range of values
+ *     const values: number[] = [];
+ *     for (let i = 0; i < count; i++) {
+ *       values.push(await this.next());
+ *     }
+ *     return values;
+ *   }
+ * }
+ *
+ * // Usage
+ * const sequence = new PostgresSequence({
+ *   name: 'user_id_seq',
+ *   executor: dbExecutor
+ * });
+ *
+ * const nextId = await sequence.next();
+ * ```
+ */
 class Sequence {
+    /**
+     * @description Accessor for the logger instance
+     * @summary Gets or initializes the logger for this sequence
+     * @return {Logger} The logger instance
+     */
     get log() {
         if (!this.logger)
             this.logger = logging_1.Logging.for(this);
         return this.logger;
     }
+    /**
+     * @description Creates a new sequence instance
+     * @summary Protected constructor that initializes the sequence with the provided options
+     */
     constructor(options) {
         this.options = options;
     }
+    /**
+     * @description Gets the primary key sequence name for a model
+     * @summary Utility method that returns the standardized sequence name for a model's primary key
+     * @template M - The model type
+     * @param {M|Constructor<M>} model - The model instance or constructor
+     * @return {string} The sequence name for the model's primary key
+     */
     static pk(model) {
         return (0, utils_1.sequenceNameForModel)(model, "pk");
     }
+    /**
+     * @description Parses a sequence value to the appropriate type
+     * @summary Converts a sequence value to the specified type (Number or BigInt)
+     * @param {"Number"|"BigInt"|undefined} type - The target type to convert to
+     * @param {string|number|bigint} value - The value to convert
+     * @return {string|number|bigint} The converted value
+     */
     static parseValue(type, value) {
         switch (type) {
             case "Number":
@@ -32,4 +101,4 @@ class Sequence {
     }
 }
 exports.Sequence = Sequence;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2VxdWVuY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvU2VxdWVuY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQ0EsbURBQXlEO0FBRXpELDJEQUF3RDtBQUN4RCwrQ0FBb0Q7QUFFcEQsTUFBc0IsUUFBUTtJQUc1QixJQUFjLEdBQUc7UUFDZixJQUFJLENBQUMsSUFBSSxDQUFDLE1BQU07WUFBRSxJQUFJLENBQUMsTUFBTSxHQUFHLGlCQUFPLENBQUMsR0FBRyxDQUFDLElBQVcsQ0FBQyxDQUFDO1FBQ3pELE9BQU8sSUFBSSxDQUFDLE1BQU0sQ0FBQztJQUNyQixDQUFDO0lBRUQsWUFBeUMsT0FBd0I7UUFBeEIsWUFBTyxHQUFQLE9BQU8sQ0FBaUI7SUFBRyxDQUFDO0lBTXJFLE1BQU0sQ0FBQyxFQUFFLENBQWtCLEtBQXlCO1FBQ2xELE9BQU8sSUFBQSw0QkFBb0IsRUFBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDM0MsQ0FBQztJQUVELE1BQU0sQ0FBQyxVQUFVLENBQ2YsSUFBcUMsRUFDckMsS0FBK0I7UUFFL0IsUUFBUSxJQUFJLEVBQUUsQ0FBQztZQUNiLEtBQUssUUFBUTtnQkFDWCxPQUFPLE9BQU8sS0FBSyxLQUFLLFFBQVE7b0JBQzlCLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDO29CQUNqQixDQUFDLENBQUMsT0FBTyxLQUFLLEtBQUssUUFBUTt3QkFDekIsQ0FBQyxDQUFDLEtBQUs7d0JBQ1AsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUN0QixLQUFLLFFBQVE7Z0JBQ1gsT0FBTyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7WUFDdkI7Z0JBQ0UsTUFBTSxJQUFJLDZCQUFhLENBQUMscUJBQXFCLENBQUMsQ0FBQztRQUNuRCxDQUFDO0lBQ0gsQ0FBQztDQUNGO0FBbkNELDRCQW1DQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IENvbnN0cnVjdG9yLCBNb2RlbCB9IGZyb20gXCJAZGVjYWYtdHMvZGVjb3JhdG9yLXZhbGlkYXRpb25cIjtcbmltcG9ydCB7IHNlcXVlbmNlTmFtZUZvck1vZGVsIH0gZnJvbSBcIi4uL2lkZW50aXR5L3V0aWxzXCI7XG5pbXBvcnQgeyBTZXF1ZW5jZU9wdGlvbnMgfSBmcm9tIFwiLi4vaW50ZXJmYWNlcy9TZXF1ZW5jZU9wdGlvbnNcIjtcbmltcG9ydCB7IEludGVybmFsRXJyb3IgfSBmcm9tIFwiQGRlY2FmLXRzL2RiLWRlY29yYXRvcnNcIjtcbmltcG9ydCB7IExvZ2dlciwgTG9nZ2luZyB9IGZyb20gXCJAZGVjYWYtdHMvbG9nZ2luZ1wiO1xuXG5leHBvcnQgYWJzdHJhY3QgY2xhc3MgU2VxdWVuY2Uge1xuICBwcml2YXRlIGxvZ2dlciE6IExvZ2dlcjtcblxuICBwcm90ZWN0ZWQgZ2V0IGxvZygpIHtcbiAgICBpZiAoIXRoaXMubG9nZ2VyKSB0aGlzLmxvZ2dlciA9IExvZ2dpbmcuZm9yKHRoaXMgYXMgYW55KTtcbiAgICByZXR1cm4gdGhpcy5sb2dnZXI7XG4gIH1cblxuICBwcm90ZWN0ZWQgY29uc3RydWN0b3IocHJvdGVjdGVkIHJlYWRvbmx5IG9wdGlvbnM6IFNlcXVlbmNlT3B0aW9ucykge31cblxuICBhYnN0cmFjdCBuZXh0KCk6IFByb21pc2U8c3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50PjtcbiAgYWJzdHJhY3QgY3VycmVudCgpOiBQcm9taXNlPHN0cmluZyB8IG51bWJlciB8IGJpZ2ludD47XG4gIGFic3RyYWN0IHJhbmdlKGNvdW50OiBudW1iZXIpOiBQcm9taXNlPChudW1iZXIgfCBzdHJpbmcgfCBiaWdpbnQpW10+O1xuXG4gIHN0YXRpYyBwazxNIGV4dGVuZHMgTW9kZWw+KG1vZGVsOiBNIHwgQ29uc3RydWN0b3I8TT4pIHtcbiAgICByZXR1cm4gc2VxdWVuY2VOYW1lRm9yTW9kZWwobW9kZWwsIFwicGtcIik7XG4gIH1cblxuICBzdGF0aWMgcGFyc2VWYWx1ZShcbiAgICB0eXBlOiBcIk51bWJlclwiIHwgXCJCaWdJbnRcIiB8IHVuZGVmaW5lZCxcbiAgICB2YWx1ZTogc3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50XG4gICk6IHN0cmluZyB8IG51bWJlciB8IGJpZ2ludCB7XG4gICAgc3dpdGNoICh0eXBlKSB7XG4gICAgICBjYXNlIFwiTnVtYmVyXCI6XG4gICAgICAgIHJldHVybiB0eXBlb2YgdmFsdWUgPT09IFwic3RyaW5nXCJcbiAgICAgICAgICA/IHBhcnNlSW50KHZhbHVlKVxuICAgICAgICAgIDogdHlwZW9mIHZhbHVlID09PSBcIm51bWJlclwiXG4gICAgICAgICAgICA/IHZhbHVlXG4gICAgICAgICAgICA6IEJpZ0ludCh2YWx1ZSk7XG4gICAgICBjYXNlIFwiQmlnSW50XCI6XG4gICAgICAgIHJldHVybiBCaWdJbnQodmFsdWUpO1xuICAgICAgZGVmYXVsdDpcbiAgICAgICAgdGhyb3cgbmV3IEludGVybmFsRXJyb3IoXCJTaG91bGQgbmV2ZXIgaGFwcGVuXCIpO1xuICAgIH1cbiAgfVxufVxuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2VxdWVuY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvU2VxdWVuY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQ0EsbURBQXlEO0FBRXpELDJEQUF3RDtBQUN4RCwrQ0FBb0Q7QUFFcEQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQTZDRztBQUNILE1BQXNCLFFBQVE7SUFPNUI7Ozs7T0FJRztJQUNILElBQWMsR0FBRztRQUNmLElBQUksQ0FBQyxJQUFJLENBQUMsTUFBTTtZQUFFLElBQUksQ0FBQyxNQUFNLEdBQUcsaUJBQU8sQ0FBQyxHQUFHLENBQUMsSUFBVyxDQUFDLENBQUM7UUFDekQsT0FBTyxJQUFJLENBQUMsTUFBTSxDQUFDO0lBQ3JCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxZQUF5QyxPQUF3QjtRQUF4QixZQUFPLEdBQVAsT0FBTyxDQUFpQjtJQUFHLENBQUM7SUF3QnJFOzs7Ozs7T0FNRztJQUNILE1BQU0sQ0FBQyxFQUFFLENBQWtCLEtBQXlCO1FBQ2xELE9BQU8sSUFBQSw0QkFBb0IsRUFBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDM0MsQ0FBQztJQUVEOzs7Ozs7T0FNRztJQUNILE1BQU0sQ0FBQyxVQUFVLENBQ2YsSUFBcUMsRUFDckMsS0FBK0I7UUFFL0IsUUFBUSxJQUFJLEVBQUUsQ0FBQztZQUNiLEtBQUssUUFBUTtnQkFDWCxPQUFPLE9BQU8sS0FBSyxLQUFLLFFBQVE7b0JBQzlCLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDO29CQUNqQixDQUFDLENBQUMsT0FBTyxLQUFLLEtBQUssUUFBUTt3QkFDekIsQ0FBQyxDQUFDLEtBQUs7d0JBQ1AsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUN0QixLQUFLLFFBQVE7Z0JBQ1gsT0FBTyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7WUFDdkI7Z0JBQ0UsTUFBTSxJQUFJLDZCQUFhLENBQUMscUJBQXFCLENBQUMsQ0FBQztRQUNuRCxDQUFDO0lBQ0gsQ0FBQztDQUNGO0FBaEZELDRCQWdGQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IENvbnN0cnVjdG9yLCBNb2RlbCB9IGZyb20gXCJAZGVjYWYtdHMvZGVjb3JhdG9yLXZhbGlkYXRpb25cIjtcbmltcG9ydCB7IHNlcXVlbmNlTmFtZUZvck1vZGVsIH0gZnJvbSBcIi4uL2lkZW50aXR5L3V0aWxzXCI7XG5pbXBvcnQgeyBTZXF1ZW5jZU9wdGlvbnMgfSBmcm9tIFwiLi4vaW50ZXJmYWNlcy9TZXF1ZW5jZU9wdGlvbnNcIjtcbmltcG9ydCB7IEludGVybmFsRXJyb3IgfSBmcm9tIFwiQGRlY2FmLXRzL2RiLWRlY29yYXRvcnNcIjtcbmltcG9ydCB7IExvZ2dlciwgTG9nZ2luZyB9IGZyb20gXCJAZGVjYWYtdHMvbG9nZ2luZ1wiO1xuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBBYnN0cmFjdCBiYXNlIGNsYXNzIGZvciBzZXF1ZW5jZSBnZW5lcmF0aW9uXG4gKiBAc3VtbWFyeSBQcm92aWRlcyBhIGZyYW1ld29yayBmb3IgZ2VuZXJhdGluZyBzZXF1ZW50aWFsIHZhbHVlcyAobGlrZSBwcmltYXJ5IGtleXMpIGluIHRoZSBwZXJzaXN0ZW5jZSBsYXllci5cbiAqIEltcGxlbWVudGF0aW9ucyBvZiB0aGlzIGNsYXNzIGhhbmRsZSB0aGUgc3BlY2lmaWNzIG9mIGhvdyBzZXF1ZW5jZXMgYXJlIHN0b3JlZCBhbmQgaW5jcmVtZW50ZWQgaW4gZGlmZmVyZW50XG4gKiBkYXRhYmFzZSBzeXN0ZW1zLlxuICogQHBhcmFtIHtTZXF1ZW5jZU9wdGlvbnN9IG9wdGlvbnMgLSBDb25maWd1cmF0aW9uIG9wdGlvbnMgZm9yIHRoZSBzZXF1ZW5jZSBnZW5lcmF0b3JcbiAqIEBjbGFzcyBTZXF1ZW5jZVxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIC8vIEV4YW1wbGUgaW1wbGVtZW50YXRpb24gZm9yIGEgc3BlY2lmaWMgZGF0YWJhc2VcbiAqIGNsYXNzIFBvc3RncmVzU2VxdWVuY2UgZXh0ZW5kcyBTZXF1ZW5jZSB7XG4gKiAgIGNvbnN0cnVjdG9yKG9wdGlvbnM6IFNlcXVlbmNlT3B0aW9ucykge1xuICogICAgIHN1cGVyKG9wdGlvbnMpO1xuICogICB9XG4gKlxuICogICBhc3luYyBuZXh0KCk6IFByb21pc2U8bnVtYmVyPiB7XG4gKiAgICAgLy8gSW1wbGVtZW50YXRpb24gdG8gZ2V0IG5leHQgdmFsdWUgZnJvbSBQb3N0Z3JlU1FMIHNlcXVlbmNlXG4gKiAgICAgY29uc3QgcmVzdWx0ID0gYXdhaXQgdGhpcy5vcHRpb25zLmV4ZWN1dG9yLnJhdyhgU0VMRUNUIG5leHR2YWwoJyR7dGhpcy5vcHRpb25zLm5hbWV9JylgKTtcbiAqICAgICByZXR1cm4gcGFyc2VJbnQocmVzdWx0LnJvd3NbMF0ubmV4dHZhbCk7XG4gKiAgIH1cbiAqXG4gKiAgIGFzeW5jIGN1cnJlbnQoKTogUHJvbWlzZTxudW1iZXI+IHtcbiAqICAgICAvLyBJbXBsZW1lbnRhdGlvbiB0byBnZXQgY3VycmVudCB2YWx1ZSBmcm9tIFBvc3RncmVTUUwgc2VxdWVuY2VcbiAqICAgICBjb25zdCByZXN1bHQgPSBhd2FpdCB0aGlzLm9wdGlvbnMuZXhlY3V0b3IucmF3KGBTRUxFQ1QgY3VycnZhbCgnJHt0aGlzLm9wdGlvbnMubmFtZX0nKWApO1xuICogICAgIHJldHVybiBwYXJzZUludChyZXN1bHQucm93c1swXS5jdXJydmFsKTtcbiAqICAgfVxuICpcbiAqICAgYXN5bmMgcmFuZ2UoY291bnQ6IG51bWJlcik6IFByb21pc2U8bnVtYmVyW10+IHtcbiAqICAgICAvLyBJbXBsZW1lbnRhdGlvbiB0byBnZXQgYSByYW5nZSBvZiB2YWx1ZXNcbiAqICAgICBjb25zdCB2YWx1ZXM6IG51bWJlcltdID0gW107XG4gKiAgICAgZm9yIChsZXQgaSA9IDA7IGkgPCBjb3VudDsgaSsrKSB7XG4gKiAgICAgICB2YWx1ZXMucHVzaChhd2FpdCB0aGlzLm5leHQoKSk7XG4gKiAgICAgfVxuICogICAgIHJldHVybiB2YWx1ZXM7XG4gKiAgIH1cbiAqIH1cbiAqXG4gKiAvLyBVc2FnZVxuICogY29uc3Qgc2VxdWVuY2UgPSBuZXcgUG9zdGdyZXNTZXF1ZW5jZSh7XG4gKiAgIG5hbWU6ICd1c2VyX2lkX3NlcScsXG4gKiAgIGV4ZWN1dG9yOiBkYkV4ZWN1dG9yXG4gKiB9KTtcbiAqXG4gKiBjb25zdCBuZXh0SWQgPSBhd2FpdCBzZXF1ZW5jZS5uZXh0KCk7XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGFic3RyYWN0IGNsYXNzIFNlcXVlbmNlIHtcbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBMb2dnZXIgaW5zdGFuY2UgZm9yIHRoaXMgc2VxdWVuY2VcbiAgICogQHN1bW1hcnkgTGF6aWx5IGluaXRpYWxpemVkIGxvZ2dlciBmb3IgdGhlIHNlcXVlbmNlIGluc3RhbmNlXG4gICAqL1xuICBwcml2YXRlIGxvZ2dlciE6IExvZ2dlcjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEFjY2Vzc29yIGZvciB0aGUgbG9nZ2VyIGluc3RhbmNlXG4gICAqIEBzdW1tYXJ5IEdldHMgb3IgaW5pdGlhbGl6ZXMgdGhlIGxvZ2dlciBmb3IgdGhpcyBzZXF1ZW5jZVxuICAgKiBAcmV0dXJuIHtMb2dnZXJ9IFRoZSBsb2dnZXIgaW5zdGFuY2VcbiAgICovXG4gIHByb3RlY3RlZCBnZXQgbG9nKCkge1xuICAgIGlmICghdGhpcy5sb2dnZXIpIHRoaXMubG9nZ2VyID0gTG9nZ2luZy5mb3IodGhpcyBhcyBhbnkpO1xuICAgIHJldHVybiB0aGlzLmxvZ2dlcjtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gQ3JlYXRlcyBhIG5ldyBzZXF1ZW5jZSBpbnN0YW5jZVxuICAgKiBAc3VtbWFyeSBQcm90ZWN0ZWQgY29uc3RydWN0b3IgdGhhdCBpbml0aWFsaXplcyB0aGUgc2VxdWVuY2Ugd2l0aCB0aGUgcHJvdmlkZWQgb3B0aW9uc1xuICAgKi9cbiAgcHJvdGVjdGVkIGNvbnN0cnVjdG9yKHByb3RlY3RlZCByZWFkb25seSBvcHRpb25zOiBTZXF1ZW5jZU9wdGlvbnMpIHt9XG5cbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBHZXRzIHRoZSBuZXh0IHZhbHVlIGluIHRoZSBzZXF1ZW5jZVxuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgdGhlIG5leHQgdmFsdWUgZnJvbSB0aGUgc2VxdWVuY2UsIGluY3JlbWVudGluZyBpdCBpbiB0aGUgcHJvY2Vzc1xuICAgKiBAcmV0dXJuIEEgcHJvbWlzZSB0aGF0IHJlc29sdmVzIHRvIHRoZSBuZXh0IHZhbHVlIGluIHRoZSBzZXF1ZW5jZVxuICAgKi9cbiAgYWJzdHJhY3QgbmV4dCgpOiBQcm9taXNlPHN0cmluZyB8IG51bWJlciB8IGJpZ2ludD47XG5cbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBHZXRzIHRoZSBjdXJyZW50IHZhbHVlIG9mIHRoZSBzZXF1ZW5jZVxuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgdGhlIGN1cnJlbnQgdmFsdWUgb2YgdGhlIHNlcXVlbmNlIHdpdGhvdXQgaW5jcmVtZW50aW5nIGl0XG4gICAqIEByZXR1cm4gQSBwcm9taXNlIHRoYXQgcmVzb2x2ZXMgdG8gdGhlIGN1cnJlbnQgdmFsdWUgaW4gdGhlIHNlcXVlbmNlXG4gICAqL1xuICBhYnN0cmFjdCBjdXJyZW50KCk6IFByb21pc2U8c3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50PjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEdldHMgYSByYW5nZSBvZiBzZXF1ZW50aWFsIHZhbHVlc1xuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgbXVsdGlwbGUgc2VxdWVudGlhbCB2YWx1ZXMgYXQgb25jZSwgd2hpY2ggY2FuIGJlIG1vcmUgZWZmaWNpZW50IHRoYW4gY2FsbGluZyBuZXh0KCkgbXVsdGlwbGUgdGltZXNcbiAgICogQHBhcmFtIHtudW1iZXJ9IGNvdW50IC0gVGhlIG51bWJlciBvZiBzZXF1ZW50aWFsIHZhbHVlcyB0byByZXRyaWV2ZVxuICAgKiBAcmV0dXJuIEEgcHJvbWlzZSB0aGF0IHJlc29sdmVzIHRvIGFuIGFycmF5IG9mIHNlcXVlbnRpYWwgdmFsdWVzXG4gICAqL1xuICBhYnN0cmFjdCByYW5nZShjb3VudDogbnVtYmVyKTogUHJvbWlzZTwobnVtYmVyIHwgc3RyaW5nIHwgYmlnaW50KVtdPjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEdldHMgdGhlIHByaW1hcnkga2V5IHNlcXVlbmNlIG5hbWUgZm9yIGEgbW9kZWxcbiAgICogQHN1bW1hcnkgVXRpbGl0eSBtZXRob2QgdGhhdCByZXR1cm5zIHRoZSBzdGFuZGFyZGl6ZWQgc2VxdWVuY2UgbmFtZSBmb3IgYSBtb2RlbCdzIHByaW1hcnkga2V5XG4gICAqIEB0ZW1wbGF0ZSBNIC0gVGhlIG1vZGVsIHR5cGVcbiAgICogQHBhcmFtIHtNfENvbnN0cnVjdG9yPE0+fSBtb2RlbCAtIFRoZSBtb2RlbCBpbnN0YW5jZSBvciBjb25zdHJ1Y3RvclxuICAgKiBAcmV0dXJuIHtzdHJpbmd9IFRoZSBzZXF1ZW5jZSBuYW1lIGZvciB0aGUgbW9kZWwncyBwcmltYXJ5IGtleVxuICAgKi9cbiAgc3RhdGljIHBrPE0gZXh0ZW5kcyBNb2RlbD4obW9kZWw6IE0gfCBDb25zdHJ1Y3RvcjxNPikge1xuICAgIHJldHVybiBzZXF1ZW5jZU5hbWVGb3JNb2RlbChtb2RlbCwgXCJwa1wiKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gUGFyc2VzIGEgc2VxdWVuY2UgdmFsdWUgdG8gdGhlIGFwcHJvcHJpYXRlIHR5cGVcbiAgICogQHN1bW1hcnkgQ29udmVydHMgYSBzZXF1ZW5jZSB2YWx1ZSB0byB0aGUgc3BlY2lmaWVkIHR5cGUgKE51bWJlciBvciBCaWdJbnQpXG4gICAqIEBwYXJhbSB7XCJOdW1iZXJcInxcIkJpZ0ludFwifHVuZGVmaW5lZH0gdHlwZSAtIFRoZSB0YXJnZXQgdHlwZSB0byBjb252ZXJ0IHRvXG4gICAqIEBwYXJhbSB7c3RyaW5nfG51bWJlcnxiaWdpbnR9IHZhbHVlIC0gVGhlIHZhbHVlIHRvIGNvbnZlcnRcbiAgICogQHJldHVybiB7c3RyaW5nfG51bWJlcnxiaWdpbnR9IFRoZSBjb252ZXJ0ZWQgdmFsdWVcbiAgICovXG4gIHN0YXRpYyBwYXJzZVZhbHVlKFxuICAgIHR5cGU6IFwiTnVtYmVyXCIgfCBcIkJpZ0ludFwiIHwgdW5kZWZpbmVkLFxuICAgIHZhbHVlOiBzdHJpbmcgfCBudW1iZXIgfCBiaWdpbnRcbiAgKTogc3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50IHtcbiAgICBzd2l0Y2ggKHR5cGUpIHtcbiAgICAgIGNhc2UgXCJOdW1iZXJcIjpcbiAgICAgICAgcmV0dXJuIHR5cGVvZiB2YWx1ZSA9PT0gXCJzdHJpbmdcIlxuICAgICAgICAgID8gcGFyc2VJbnQodmFsdWUpXG4gICAgICAgICAgOiB0eXBlb2YgdmFsdWUgPT09IFwibnVtYmVyXCJcbiAgICAgICAgICAgID8gdmFsdWVcbiAgICAgICAgICAgIDogQmlnSW50KHZhbHVlKTtcbiAgICAgIGNhc2UgXCJCaWdJbnRcIjpcbiAgICAgICAgcmV0dXJuIEJpZ0ludCh2YWx1ZSk7XG4gICAgICBkZWZhdWx0OlxuICAgICAgICB0aHJvdyBuZXcgSW50ZXJuYWxFcnJvcihcIlNob3VsZCBuZXZlciBoYXBwZW5cIik7XG4gICAgfVxuICB9XG59XG4iXX0=

package/lib/persistence/Sequence.d.ts

@@ -1,14 +1,103 @@
 import { Constructor, Model } from "@decaf-ts/decorator-validation";
 import { SequenceOptions } from "../interfaces/SequenceOptions";
 import { Logger } from "@decaf-ts/logging";
+/**
+ * @description Abstract base class for sequence generation
+ * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
+ * Implementations of this class handle the specifics of how sequences are stored and incremented in different
+ * database systems.
+ * @param {SequenceOptions} options - Configuration options for the sequence generator
+ * @class Sequence
+ * @example
+ * ```typescript
+ * // Example implementation for a specific database
+ * class PostgresSequence extends Sequence {
+ *   constructor(options: SequenceOptions) {
+ *     super(options);
+ *   }
+ *
+ *   async next(): Promise<number> {
+ *     // Implementation to get next value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].nextval);
+ *   }
+ *
+ *   async current(): Promise<number> {
+ *     // Implementation to get current value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].currval);
+ *   }
+ *
+ *   async range(count: number): Promise<number[]> {
+ *     // Implementation to get a range of values
+ *     const values: number[] = [];
+ *     for (let i = 0; i < count; i++) {
+ *       values.push(await this.next());
+ *     }
+ *     return values;
+ *   }
+ * }
+ *
+ * // Usage
+ * const sequence = new PostgresSequence({
+ *   name: 'user_id_seq',
+ *   executor: dbExecutor
+ * });
+ *
+ * const nextId = await sequence.next();
+ * ```
+ */
 export declare abstract class Sequence {
     protected readonly options: SequenceOptions;
+    /**
+     * @description Logger instance for this sequence
+     * @summary Lazily initialized logger for the sequence instance
+     */
     private logger;
+    /**
+     * @description Accessor for the logger instance
+     * @summary Gets or initializes the logger for this sequence
+     * @return {Logger} The logger instance
+     */
     protected get log(): Logger;
+    /**
+     * @description Creates a new sequence instance
+     * @summary Protected constructor that initializes the sequence with the provided options
+     */
     protected constructor(options: SequenceOptions);
+    /**
+     * @description Gets the next value in the sequence
+     * @summary Retrieves the next value from the sequence, incrementing it in the process
+     * @return A promise that resolves to the next value in the sequence
+     */
     abstract next(): Promise<string | number | bigint>;
+    /**
+     * @description Gets the current value of the sequence
+     * @summary Retrieves the current value of the sequence without incrementing it
+     * @return A promise that resolves to the current value in the sequence
+     */
     abstract current(): Promise<string | number | bigint>;
+    /**
+     * @description Gets a range of sequential values
+     * @summary Retrieves multiple sequential values at once, which can be more efficient than calling next() multiple times
+     * @param {number} count - The number of sequential values to retrieve
+     * @return A promise that resolves to an array of sequential values
+     */
     abstract range(count: number): Promise<(number | string | bigint)[]>;
+    /**
+     * @description Gets the primary key sequence name for a model
+     * @summary Utility method that returns the standardized sequence name for a model's primary key
+     * @template M - The model type
+     * @param {M|Constructor<M>} model - The model instance or constructor
+     * @return {string} The sequence name for the model's primary key
+     */
     static pk<M extends Model>(model: M | Constructor<M>): string;
+    /**
+     * @description Parses a sequence value to the appropriate type
+     * @summary Converts a sequence value to the specified type (Number or BigInt)
+     * @param {"Number"|"BigInt"|undefined} type - The target type to convert to
+     * @param {string|number|bigint} value - The value to convert
+     * @return {string|number|bigint} The converted value
+     */
     static parseValue(type: "Number" | "BigInt" | undefined, value: string | number | bigint): string | number | bigint;
 }