@decaf-ts/core 0.5.0 → 0.5.2

package/lib/persistence/Sequence.cjs

@@ -2,13 +2,103 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 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":
+                return typeof value === "string"
+                    ? parseInt(value)
+                    : typeof value === "number"
+                        ? value
+                        : BigInt(value);
+            case "BigInt":
+                return BigInt(value);
+            default:
+                throw new db_decorators_1.InternalError("Should never happen");
+        }
+    }
 }
 exports.Sequence = Sequence;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2VxdWVuY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvU2VxdWVuY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBUUEsbURBQXlEO0FBR3pELE1BQXNCLFFBQVE7SUFDNUIsWUFBeUMsT0FBd0I7UUFBeEIsWUFBTyxHQUFQLE9BQU8sQ0FBaUI7SUFBRyxDQUFDO0lBV3JFLE1BQU0sQ0FBQyxFQUFFLENBQWtCLEtBQXlCO1FBQ2xELE9BQU8sSUFBQSw0QkFBb0IsRUFBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDM0MsQ0FBQztDQUNGO0FBZkQsNEJBZUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIEBzdW1tYXJ5IFNlcXVlbmNlXG4gKlxuICogQGludGVyZmFjZSBTZXF1ZW5jZVxuICpcbiAqIEBjYXRlZ29yeSBTZXF1ZW5jZXNcbiAqL1xuaW1wb3J0IHsgQ29uc3RydWN0b3IsIE1vZGVsIH0gZnJvbSBcIkBkZWNhZi10cy9kZWNvcmF0b3ItdmFsaWRhdGlvblwiO1xuaW1wb3J0IHsgc2VxdWVuY2VOYW1lRm9yTW9kZWwgfSBmcm9tIFwiLi4vaWRlbnRpdHkvdXRpbHNcIjtcbmltcG9ydCB7IFNlcXVlbmNlT3B0aW9ucyB9IGZyb20gXCIuLi9pbnRlcmZhY2VzL1NlcXVlbmNlT3B0aW9uc1wiO1xuXG5leHBvcnQgYWJzdHJhY3QgY2xhc3MgU2VxdWVuY2Uge1xuICBwcm90ZWN0ZWQgY29uc3RydWN0b3IocHJvdGVjdGVkIHJlYWRvbmx5IG9wdGlvbnM6IFNlcXVlbmNlT3B0aW9ucykge31cblxuICAvKipcbiAgICogQHN1bW1hcnkgZ2VuZXJhdGVzIHRoZSBuZXh0IHZhbHVlIGluIHRoZSBzZXF1ZW5jZVxuICAgKlxuICAgKiBAbWV0aG9kXG4gICAqL1xuICBhYnN0cmFjdCBuZXh0KCk6IFByb21pc2U8c3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50PjtcbiAgYWJzdHJhY3QgY3VycmVudCgpOiBQcm9taXNlPHN0cmluZyB8IG51bWJlciB8IGJpZ2ludD47XG4gIGFic3RyYWN0IHJhbmdlKGNvdW50OiBudW1iZXIpOiBQcm9taXNlPChudW1iZXIgfCBzdHJpbmcgfCBiaWdpbnQpW10+O1xuXG4gIHN0YXRpYyBwazxNIGV4dGVuZHMgTW9kZWw+KG1vZGVsOiBNIHwgQ29uc3RydWN0b3I8TT4pIHtcbiAgICByZXR1cm4gc2VxdWVuY2VOYW1lRm9yTW9kZWwobW9kZWwsIFwicGtcIik7XG4gIH1cbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2VxdWVuY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvU2VxdWVuY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQ0EsbURBQXlEO0FBRXpELDJEQUF3RDtBQUN4RCwrQ0FBb0Q7QUFFcEQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQTZDRztBQUNILE1BQXNCLFFBQVE7SUFPNUI7Ozs7T0FJRztJQUNILElBQWMsR0FBRztRQUNmLElBQUksQ0FBQyxJQUFJLENBQUMsTUFBTTtZQUFFLElBQUksQ0FBQyxNQUFNLEdBQUcsaUJBQU8sQ0FBQyxHQUFHLENBQUMsSUFBVyxDQUFDLENBQUM7UUFDekQsT0FBTyxJQUFJLENBQUMsTUFBTSxDQUFDO0lBQ3JCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxZQUF5QyxPQUF3QjtRQUF4QixZQUFPLEdBQVAsT0FBTyxDQUFpQjtJQUFHLENBQUM7SUF3QnJFOzs7Ozs7T0FNRztJQUNILE1BQU0sQ0FBQyxFQUFFLENBQWtCLEtBQXlCO1FBQ2xELE9BQU8sSUFBQSw0QkFBb0IsRUFBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDM0MsQ0FBQztJQUVEOzs7Ozs7T0FNRztJQUNILE1BQU0sQ0FBQyxVQUFVLENBQ2YsSUFBcUMsRUFDckMsS0FBK0I7UUFFL0IsUUFBUSxJQUFJLEVBQUUsQ0FBQztZQUNiLEtBQUssUUFBUTtnQkFDWCxPQUFPLE9BQU8sS0FBSyxLQUFLLFFBQVE7b0JBQzlCLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDO29CQUNqQixDQUFDLENBQUMsT0FBTyxLQUFLLEtBQUssUUFBUTt3QkFDekIsQ0FBQyxDQUFDLEtBQUs7d0JBQ1AsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUN0QixLQUFLLFFBQVE7Z0JBQ1gsT0FBTyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7WUFDdkI7Z0JBQ0UsTUFBTSxJQUFJLDZCQUFhLENBQUMscUJBQXFCLENBQUMsQ0FBQztRQUNuRCxDQUFDO0lBQ0gsQ0FBQztDQUNGO0FBaEZELDRCQWdGQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IENvbnN0cnVjdG9yLCBNb2RlbCB9IGZyb20gXCJAZGVjYWYtdHMvZGVjb3JhdG9yLXZhbGlkYXRpb25cIjtcbmltcG9ydCB7IHNlcXVlbmNlTmFtZUZvck1vZGVsIH0gZnJvbSBcIi4uL2lkZW50aXR5L3V0aWxzXCI7XG5pbXBvcnQgeyBTZXF1ZW5jZU9wdGlvbnMgfSBmcm9tIFwiLi4vaW50ZXJmYWNlcy9TZXF1ZW5jZU9wdGlvbnNcIjtcbmltcG9ydCB7IEludGVybmFsRXJyb3IgfSBmcm9tIFwiQGRlY2FmLXRzL2RiLWRlY29yYXRvcnNcIjtcbmltcG9ydCB7IExvZ2dlciwgTG9nZ2luZyB9IGZyb20gXCJAZGVjYWYtdHMvbG9nZ2luZ1wiO1xuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBBYnN0cmFjdCBiYXNlIGNsYXNzIGZvciBzZXF1ZW5jZSBnZW5lcmF0aW9uXG4gKiBAc3VtbWFyeSBQcm92aWRlcyBhIGZyYW1ld29yayBmb3IgZ2VuZXJhdGluZyBzZXF1ZW50aWFsIHZhbHVlcyAobGlrZSBwcmltYXJ5IGtleXMpIGluIHRoZSBwZXJzaXN0ZW5jZSBsYXllci5cbiAqIEltcGxlbWVudGF0aW9ucyBvZiB0aGlzIGNsYXNzIGhhbmRsZSB0aGUgc3BlY2lmaWNzIG9mIGhvdyBzZXF1ZW5jZXMgYXJlIHN0b3JlZCBhbmQgaW5jcmVtZW50ZWQgaW4gZGlmZmVyZW50XG4gKiBkYXRhYmFzZSBzeXN0ZW1zLlxuICogQHBhcmFtIHtTZXF1ZW5jZU9wdGlvbnN9IG9wdGlvbnMgLSBDb25maWd1cmF0aW9uIG9wdGlvbnMgZm9yIHRoZSBzZXF1ZW5jZSBnZW5lcmF0b3JcbiAqIEBjbGFzcyBTZXF1ZW5jZVxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIC8vIEV4YW1wbGUgaW1wbGVtZW50YXRpb24gZm9yIGEgc3BlY2lmaWMgZGF0YWJhc2VcbiAqIGNsYXNzIFBvc3RncmVzU2VxdWVuY2UgZXh0ZW5kcyBTZXF1ZW5jZSB7XG4gKiAgIGNvbnN0cnVjdG9yKG9wdGlvbnM6IFNlcXVlbmNlT3B0aW9ucykge1xuICogICAgIHN1cGVyKG9wdGlvbnMpO1xuICogICB9XG4gKlxuICogICBhc3luYyBuZXh0KCk6IFByb21pc2U8bnVtYmVyPiB7XG4gKiAgICAgLy8gSW1wbGVtZW50YXRpb24gdG8gZ2V0IG5leHQgdmFsdWUgZnJvbSBQb3N0Z3JlU1FMIHNlcXVlbmNlXG4gKiAgICAgY29uc3QgcmVzdWx0ID0gYXdhaXQgdGhpcy5vcHRpb25zLmV4ZWN1dG9yLnJhdyhgU0VMRUNUIG5leHR2YWwoJyR7dGhpcy5vcHRpb25zLm5hbWV9JylgKTtcbiAqICAgICByZXR1cm4gcGFyc2VJbnQocmVzdWx0LnJvd3NbMF0ubmV4dHZhbCk7XG4gKiAgIH1cbiAqXG4gKiAgIGFzeW5jIGN1cnJlbnQoKTogUHJvbWlzZTxudW1iZXI+IHtcbiAqICAgICAvLyBJbXBsZW1lbnRhdGlvbiB0byBnZXQgY3VycmVudCB2YWx1ZSBmcm9tIFBvc3RncmVTUUwgc2VxdWVuY2VcbiAqICAgICBjb25zdCByZXN1bHQgPSBhd2FpdCB0aGlzLm9wdGlvbnMuZXhlY3V0b3IucmF3KGBTRUxFQ1QgY3VycnZhbCgnJHt0aGlzLm9wdGlvbnMubmFtZX0nKWApO1xuICogICAgIHJldHVybiBwYXJzZUludChyZXN1bHQucm93c1swXS5jdXJydmFsKTtcbiAqICAgfVxuICpcbiAqICAgYXN5bmMgcmFuZ2UoY291bnQ6IG51bWJlcik6IFByb21pc2U8bnVtYmVyW10+IHtcbiAqICAgICAvLyBJbXBsZW1lbnRhdGlvbiB0byBnZXQgYSByYW5nZSBvZiB2YWx1ZXNcbiAqICAgICBjb25zdCB2YWx1ZXM6IG51bWJlcltdID0gW107XG4gKiAgICAgZm9yIChsZXQgaSA9IDA7IGkgPCBjb3VudDsgaSsrKSB7XG4gKiAgICAgICB2YWx1ZXMucHVzaChhd2FpdCB0aGlzLm5leHQoKSk7XG4gKiAgICAgfVxuICogICAgIHJldHVybiB2YWx1ZXM7XG4gKiAgIH1cbiAqIH1cbiAqXG4gKiAvLyBVc2FnZVxuICogY29uc3Qgc2VxdWVuY2UgPSBuZXcgUG9zdGdyZXNTZXF1ZW5jZSh7XG4gKiAgIG5hbWU6ICd1c2VyX2lkX3NlcScsXG4gKiAgIGV4ZWN1dG9yOiBkYkV4ZWN1dG9yXG4gKiB9KTtcbiAqXG4gKiBjb25zdCBuZXh0SWQgPSBhd2FpdCBzZXF1ZW5jZS5uZXh0KCk7XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGFic3RyYWN0IGNsYXNzIFNlcXVlbmNlIHtcbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBMb2dnZXIgaW5zdGFuY2UgZm9yIHRoaXMgc2VxdWVuY2VcbiAgICogQHN1bW1hcnkgTGF6aWx5IGluaXRpYWxpemVkIGxvZ2dlciBmb3IgdGhlIHNlcXVlbmNlIGluc3RhbmNlXG4gICAqL1xuICBwcml2YXRlIGxvZ2dlciE6IExvZ2dlcjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEFjY2Vzc29yIGZvciB0aGUgbG9nZ2VyIGluc3RhbmNlXG4gICAqIEBzdW1tYXJ5IEdldHMgb3IgaW5pdGlhbGl6ZXMgdGhlIGxvZ2dlciBmb3IgdGhpcyBzZXF1ZW5jZVxuICAgKiBAcmV0dXJuIHtMb2dnZXJ9IFRoZSBsb2dnZXIgaW5zdGFuY2VcbiAgICovXG4gIHByb3RlY3RlZCBnZXQgbG9nKCkge1xuICAgIGlmICghdGhpcy5sb2dnZXIpIHRoaXMubG9nZ2VyID0gTG9nZ2luZy5mb3IodGhpcyBhcyBhbnkpO1xuICAgIHJldHVybiB0aGlzLmxvZ2dlcjtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gQ3JlYXRlcyBhIG5ldyBzZXF1ZW5jZSBpbnN0YW5jZVxuICAgKiBAc3VtbWFyeSBQcm90ZWN0ZWQgY29uc3RydWN0b3IgdGhhdCBpbml0aWFsaXplcyB0aGUgc2VxdWVuY2Ugd2l0aCB0aGUgcHJvdmlkZWQgb3B0aW9uc1xuICAgKi9cbiAgcHJvdGVjdGVkIGNvbnN0cnVjdG9yKHByb3RlY3RlZCByZWFkb25seSBvcHRpb25zOiBTZXF1ZW5jZU9wdGlvbnMpIHt9XG5cbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBHZXRzIHRoZSBuZXh0IHZhbHVlIGluIHRoZSBzZXF1ZW5jZVxuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgdGhlIG5leHQgdmFsdWUgZnJvbSB0aGUgc2VxdWVuY2UsIGluY3JlbWVudGluZyBpdCBpbiB0aGUgcHJvY2Vzc1xuICAgKiBAcmV0dXJuIEEgcHJvbWlzZSB0aGF0IHJlc29sdmVzIHRvIHRoZSBuZXh0IHZhbHVlIGluIHRoZSBzZXF1ZW5jZVxuICAgKi9cbiAgYWJzdHJhY3QgbmV4dCgpOiBQcm9taXNlPHN0cmluZyB8IG51bWJlciB8IGJpZ2ludD47XG5cbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBHZXRzIHRoZSBjdXJyZW50IHZhbHVlIG9mIHRoZSBzZXF1ZW5jZVxuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgdGhlIGN1cnJlbnQgdmFsdWUgb2YgdGhlIHNlcXVlbmNlIHdpdGhvdXQgaW5jcmVtZW50aW5nIGl0XG4gICAqIEByZXR1cm4gQSBwcm9taXNlIHRoYXQgcmVzb2x2ZXMgdG8gdGhlIGN1cnJlbnQgdmFsdWUgaW4gdGhlIHNlcXVlbmNlXG4gICAqL1xuICBhYnN0cmFjdCBjdXJyZW50KCk6IFByb21pc2U8c3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50PjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEdldHMgYSByYW5nZSBvZiBzZXF1ZW50aWFsIHZhbHVlc1xuICAgKiBAc3VtbWFyeSBSZXRyaWV2ZXMgbXVsdGlwbGUgc2VxdWVudGlhbCB2YWx1ZXMgYXQgb25jZSwgd2hpY2ggY2FuIGJlIG1vcmUgZWZmaWNpZW50IHRoYW4gY2FsbGluZyBuZXh0KCkgbXVsdGlwbGUgdGltZXNcbiAgICogQHBhcmFtIHtudW1iZXJ9IGNvdW50IC0gVGhlIG51bWJlciBvZiBzZXF1ZW50aWFsIHZhbHVlcyB0byByZXRyaWV2ZVxuICAgKiBAcmV0dXJuIEEgcHJvbWlzZSB0aGF0IHJlc29sdmVzIHRvIGFuIGFycmF5IG9mIHNlcXVlbnRpYWwgdmFsdWVzXG4gICAqL1xuICBhYnN0cmFjdCByYW5nZShjb3VudDogbnVtYmVyKTogUHJvbWlzZTwobnVtYmVyIHwgc3RyaW5nIHwgYmlnaW50KVtdPjtcblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIEdldHMgdGhlIHByaW1hcnkga2V5IHNlcXVlbmNlIG5hbWUgZm9yIGEgbW9kZWxcbiAgICogQHN1bW1hcnkgVXRpbGl0eSBtZXRob2QgdGhhdCByZXR1cm5zIHRoZSBzdGFuZGFyZGl6ZWQgc2VxdWVuY2UgbmFtZSBmb3IgYSBtb2RlbCdzIHByaW1hcnkga2V5XG4gICAqIEB0ZW1wbGF0ZSBNIC0gVGhlIG1vZGVsIHR5cGVcbiAgICogQHBhcmFtIHtNfENvbnN0cnVjdG9yPE0+fSBtb2RlbCAtIFRoZSBtb2RlbCBpbnN0YW5jZSBvciBjb25zdHJ1Y3RvclxuICAgKiBAcmV0dXJuIHtzdHJpbmd9IFRoZSBzZXF1ZW5jZSBuYW1lIGZvciB0aGUgbW9kZWwncyBwcmltYXJ5IGtleVxuICAgKi9cbiAgc3RhdGljIHBrPE0gZXh0ZW5kcyBNb2RlbD4obW9kZWw6IE0gfCBDb25zdHJ1Y3RvcjxNPikge1xuICAgIHJldHVybiBzZXF1ZW5jZU5hbWVGb3JNb2RlbChtb2RlbCwgXCJwa1wiKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gUGFyc2VzIGEgc2VxdWVuY2UgdmFsdWUgdG8gdGhlIGFwcHJvcHJpYXRlIHR5cGVcbiAgICogQHN1bW1hcnkgQ29udmVydHMgYSBzZXF1ZW5jZSB2YWx1ZSB0byB0aGUgc3BlY2lmaWVkIHR5cGUgKE51bWJlciBvciBCaWdJbnQpXG4gICAqIEBwYXJhbSB7XCJOdW1iZXJcInxcIkJpZ0ludFwifHVuZGVmaW5lZH0gdHlwZSAtIFRoZSB0YXJnZXQgdHlwZSB0byBjb252ZXJ0IHRvXG4gICAqIEBwYXJhbSB7c3RyaW5nfG51bWJlcnxiaWdpbnR9IHZhbHVlIC0gVGhlIHZhbHVlIHRvIGNvbnZlcnRcbiAgICogQHJldHVybiB7c3RyaW5nfG51bWJlcnxiaWdpbnR9IFRoZSBjb252ZXJ0ZWQgdmFsdWVcbiAgICovXG4gIHN0YXRpYyBwYXJzZVZhbHVlKFxuICAgIHR5cGU6IFwiTnVtYmVyXCIgfCBcIkJpZ0ludFwiIHwgdW5kZWZpbmVkLFxuICAgIHZhbHVlOiBzdHJpbmcgfCBudW1iZXIgfCBiaWdpbnRcbiAgKTogc3RyaW5nIHwgbnVtYmVyIHwgYmlnaW50IHtcbiAgICBzd2l0Y2ggKHR5cGUpIHtcbiAgICAgIGNhc2UgXCJOdW1iZXJcIjpcbiAgICAgICAgcmV0dXJuIHR5cGVvZiB2YWx1ZSA9PT0gXCJzdHJpbmdcIlxuICAgICAgICAgID8gcGFyc2VJbnQodmFsdWUpXG4gICAgICAgICAgOiB0eXBlb2YgdmFsdWUgPT09IFwibnVtYmVyXCJcbiAgICAgICAgICAgID8gdmFsdWVcbiAgICAgICAgICAgIDogQmlnSW50KHZhbHVlKTtcbiAgICAgIGNhc2UgXCJCaWdJbnRcIjpcbiAgICAgICAgcmV0dXJuIEJpZ0ludCh2YWx1ZSk7XG4gICAgICBkZWZhdWx0OlxuICAgICAgICB0aHJvdyBuZXcgSW50ZXJuYWxFcnJvcihcIlNob3VsZCBuZXZlciBoYXBwZW5cIik7XG4gICAgfVxuICB9XG59XG4iXX0=

package/lib/persistence/Sequence.d.ts

@@ -1,22 +1,103 @@
+import { Constructor, Model } from "@decaf-ts/decorator-validation";
+import { SequenceOptions } from "../interfaces/SequenceOptions";
+import { Logger } from "@decaf-ts/logging";
 /**
- * @summary Sequence
+ * @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);
+ *   }
  *
- * @interface Sequence
+ *   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);
+ *   }
  *
- * @category Sequences
+ *   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();
+ * ```
  */
-import { Constructor, Model } from "@decaf-ts/decorator-validation";
-import { SequenceOptions } from "../interfaces/SequenceOptions";
 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);
     /**
-     * @summary generates the next value in the sequence
-     *
-     * @method
+     * @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;
 }

package/lib/persistence/constants.cjs

@@ -1,30 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Roles = exports.PersistenceKeys = void 0;
+exports.PersistenceKeys = void 0;
+/**
+ * @description Persistence-related constant keys
+ * @summary Enum containing string constants used throughout the persistence layer for metadata, relations, and other persistence-related operations
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
 var PersistenceKeys;
 (function (PersistenceKeys) {
+    /** @description Key for index metadata */
     PersistenceKeys["INDEX"] = "index";
+    /** @description Key for unique constraint metadata */
     PersistenceKeys["UNIQUE"] = "unique";
+    /** @description Key for adapter metadata */
     PersistenceKeys["ADAPTER"] = "adapter";
+    /** @description Template for injectable adapter names */
     PersistenceKeys["INJECTABLE"] = "decaf_{0}_adapter_for_{1}";
+    /** @description Key for table name metadata */
     PersistenceKeys["TABLE"] = "table";
+    /** @description Key for column name metadata */
     PersistenceKeys["COLUMN"] = "column";
+    /** @description Key for general metadata storage */
     PersistenceKeys["METADATA"] = "__metadata";
+    /** @description Key for relations metadata storage */
     PersistenceKeys["RELATIONS"] = "__relations";
+    /** @description Key for clause sequence metadata */
     PersistenceKeys["CLAUSE_SEQUENCE"] = "clause-sequence";
     // Ownership
+    /** @description Key for created-by ownership metadata */
     PersistenceKeys["CREATED_BY"] = "ownership.created-by";
+    /** @description Key for updated-by ownership metadata */
     PersistenceKeys["UPDATED_BY"] = "ownership.updated-by";
     // Relations
+    /** @description Key for one-to-one relation metadata */
     PersistenceKeys["ONE_TO_ONE"] = "relations.one-to-one";
+    /** @description Key for one-to-many relation metadata */
     PersistenceKeys["ONE_TO_MANY"] = "relations.one-to-many";
+    /** @description Key for many-to-one relation metadata */
     PersistenceKeys["MANY_TO_ONE"] = "relations.many-to-one";
+    /** @description Key for populate metadata */
     PersistenceKeys["POPULATE"] = "populate";
 })(PersistenceKeys || (exports.PersistenceKeys = PersistenceKeys = {}));
-var Roles;
-(function (Roles) {
-    Roles["ADMIN"] = "admin";
-    Roles["WRITER"] = "writer";
-    Roles["READER"] = "reader";
-})(Roles || (exports.Roles = Roles = {}));
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSxJQUFZLGVBa0JYO0FBbEJELFdBQVksZUFBZTtJQUN6QixrQ0FBZSxDQUFBO0lBQ2Ysb0NBQWlCLENBQUE7SUFDakIsc0NBQW1CLENBQUE7SUFDbkIsMkRBQXdDLENBQUE7SUFDeEMsa0NBQWUsQ0FBQTtJQUNmLG9DQUFpQixDQUFBO0lBQ2pCLDBDQUF1QixDQUFBO0lBQ3ZCLDRDQUF5QixDQUFBO0lBQ3pCLHNEQUFtQyxDQUFBO0lBQ25DLFlBQVk7SUFDWixzREFBbUMsQ0FBQTtJQUNuQyxzREFBbUMsQ0FBQTtJQUNuQyxZQUFZO0lBQ1osc0RBQW1DLENBQUE7SUFDbkMsd0RBQXFDLENBQUE7SUFDckMsd0RBQXFDLENBQUE7SUFDckMsd0NBQXFCLENBQUE7QUFDdkIsQ0FBQyxFQWxCVyxlQUFlLCtCQUFmLGVBQWUsUUFrQjFCO0FBRUQsSUFBWSxLQUlYO0FBSkQsV0FBWSxLQUFLO0lBQ2Ysd0JBQWUsQ0FBQTtJQUNmLDBCQUFpQixDQUFBO0lBQ2pCLDBCQUFpQixDQUFBO0FBQ25CLENBQUMsRUFKVyxLQUFLLHFCQUFMLEtBQUssUUFJaEIiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgZW51bSBQZXJzaXN0ZW5jZUtleXMge1xuICBJTkRFWCA9IFwiaW5kZXhcIixcbiAgVU5JUVVFID0gXCJ1bmlxdWVcIixcbiAgQURBUFRFUiA9IFwiYWRhcHRlclwiLFxuICBJTkpFQ1RBQkxFID0gXCJkZWNhZl97MH1fYWRhcHRlcl9mb3JfezF9XCIsXG4gIFRBQkxFID0gXCJ0YWJsZVwiLFxuICBDT0xVTU4gPSBcImNvbHVtblwiLFxuICBNRVRBREFUQSA9IFwiX19tZXRhZGF0YVwiLFxuICBSRUxBVElPTlMgPSBcIl9fcmVsYXRpb25zXCIsXG4gIENMQVVTRV9TRVFVRU5DRSA9IFwiY2xhdXNlLXNlcXVlbmNlXCIsXG4gIC8vIE93bmVyc2hpcFxuICBDUkVBVEVEX0JZID0gXCJvd25lcnNoaXAuY3JlYXRlZC1ieVwiLFxuICBVUERBVEVEX0JZID0gXCJvd25lcnNoaXAudXBkYXRlZC1ieVwiLFxuICAvLyBSZWxhdGlvbnNcbiAgT05FX1RPX09ORSA9IFwicmVsYXRpb25zLm9uZS10by1vbmVcIixcbiAgT05FX1RPX01BTlkgPSBcInJlbGF0aW9ucy5vbmUtdG8tbWFueVwiLFxuICBNQU5ZX1RPX09ORSA9IFwicmVsYXRpb25zLm1hbnktdG8tb25lXCIsXG4gIFBPUFVMQVRFID0gXCJwb3B1bGF0ZVwiLFxufVxuXG5leHBvcnQgZW51bSBSb2xlcyB7XG4gIEFETUlOID0gXCJhZG1pblwiLFxuICBXUklURVIgPSBcIndyaXRlclwiLFxuICBSRUFERVIgPSBcInJlYWRlclwiLFxufVxuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7Ozs7O0dBTUc7QUFDSCxJQUFZLGVBK0NYO0FBL0NELFdBQVksZUFBZTtJQUN6QiwwQ0FBMEM7SUFDMUMsa0NBQWUsQ0FBQTtJQUVmLHNEQUFzRDtJQUN0RCxvQ0FBaUIsQ0FBQTtJQUVqQiw0Q0FBNEM7SUFDNUMsc0NBQW1CLENBQUE7SUFFbkIseURBQXlEO0lBQ3pELDJEQUF3QyxDQUFBO0lBRXhDLCtDQUErQztJQUMvQyxrQ0FBZSxDQUFBO0lBRWYsZ0RBQWdEO0lBQ2hELG9DQUFpQixDQUFBO0lBRWpCLG9EQUFvRDtJQUNwRCwwQ0FBdUIsQ0FBQTtJQUV2QixzREFBc0Q7SUFDdEQsNENBQXlCLENBQUE7SUFFekIsb0RBQW9EO0lBQ3BELHNEQUFtQyxDQUFBO0lBRW5DLFlBQVk7SUFDWix5REFBeUQ7SUFDekQsc0RBQW1DLENBQUE7SUFFbkMseURBQXlEO0lBQ3pELHNEQUFtQyxDQUFBO0lBRW5DLFlBQVk7SUFDWix3REFBd0Q7SUFDeEQsc0RBQW1DLENBQUE7SUFFbkMseURBQXlEO0lBQ3pELHdEQUFxQyxDQUFBO0lBRXJDLHlEQUF5RDtJQUN6RCx3REFBcUMsQ0FBQTtJQUVyQyw2Q0FBNkM7SUFDN0Msd0NBQXFCLENBQUE7QUFDdkIsQ0FBQyxFQS9DVyxlQUFlLCtCQUFmLGVBQWUsUUErQzFCIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBAZGVzY3JpcHRpb24gUGVyc2lzdGVuY2UtcmVsYXRlZCBjb25zdGFudCBrZXlzXG4gKiBAc3VtbWFyeSBFbnVtIGNvbnRhaW5pbmcgc3RyaW5nIGNvbnN0YW50cyB1c2VkIHRocm91Z2hvdXQgdGhlIHBlcnNpc3RlbmNlIGxheWVyIGZvciBtZXRhZGF0YSwgcmVsYXRpb25zLCBhbmQgb3RoZXIgcGVyc2lzdGVuY2UtcmVsYXRlZCBvcGVyYXRpb25zXG4gKiBAZW51bSB7c3RyaW5nfVxuICogQHJlYWRvbmx5XG4gKiBAbWVtYmVyT2YgbW9kdWxlOmNvcmVcbiAqL1xuZXhwb3J0IGVudW0gUGVyc2lzdGVuY2VLZXlzIHtcbiAgLyoqIEBkZXNjcmlwdGlvbiBLZXkgZm9yIGluZGV4IG1ldGFkYXRhICovXG4gIElOREVYID0gXCJpbmRleFwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciB1bmlxdWUgY29uc3RyYWludCBtZXRhZGF0YSAqL1xuICBVTklRVUUgPSBcInVuaXF1ZVwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBhZGFwdGVyIG1ldGFkYXRhICovXG4gIEFEQVBURVIgPSBcImFkYXB0ZXJcIixcblxuICAvKiogQGRlc2NyaXB0aW9uIFRlbXBsYXRlIGZvciBpbmplY3RhYmxlIGFkYXB0ZXIgbmFtZXMgKi9cbiAgSU5KRUNUQUJMRSA9IFwiZGVjYWZfezB9X2FkYXB0ZXJfZm9yX3sxfVwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciB0YWJsZSBuYW1lIG1ldGFkYXRhICovXG4gIFRBQkxFID0gXCJ0YWJsZVwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBjb2x1bW4gbmFtZSBtZXRhZGF0YSAqL1xuICBDT0xVTU4gPSBcImNvbHVtblwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBnZW5lcmFsIG1ldGFkYXRhIHN0b3JhZ2UgKi9cbiAgTUVUQURBVEEgPSBcIl9fbWV0YWRhdGFcIixcblxuICAvKiogQGRlc2NyaXB0aW9uIEtleSBmb3IgcmVsYXRpb25zIG1ldGFkYXRhIHN0b3JhZ2UgKi9cbiAgUkVMQVRJT05TID0gXCJfX3JlbGF0aW9uc1wiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBjbGF1c2Ugc2VxdWVuY2UgbWV0YWRhdGEgKi9cbiAgQ0xBVVNFX1NFUVVFTkNFID0gXCJjbGF1c2Utc2VxdWVuY2VcIixcblxuICAvLyBPd25lcnNoaXBcbiAgLyoqIEBkZXNjcmlwdGlvbiBLZXkgZm9yIGNyZWF0ZWQtYnkgb3duZXJzaGlwIG1ldGFkYXRhICovXG4gIENSRUFURURfQlkgPSBcIm93bmVyc2hpcC5jcmVhdGVkLWJ5XCIsXG5cbiAgLyoqIEBkZXNjcmlwdGlvbiBLZXkgZm9yIHVwZGF0ZWQtYnkgb3duZXJzaGlwIG1ldGFkYXRhICovXG4gIFVQREFURURfQlkgPSBcIm93bmVyc2hpcC51cGRhdGVkLWJ5XCIsXG5cbiAgLy8gUmVsYXRpb25zXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBvbmUtdG8tb25lIHJlbGF0aW9uIG1ldGFkYXRhICovXG4gIE9ORV9UT19PTkUgPSBcInJlbGF0aW9ucy5vbmUtdG8tb25lXCIsXG5cbiAgLyoqIEBkZXNjcmlwdGlvbiBLZXkgZm9yIG9uZS10by1tYW55IHJlbGF0aW9uIG1ldGFkYXRhICovXG4gIE9ORV9UT19NQU5ZID0gXCJyZWxhdGlvbnMub25lLXRvLW1hbnlcIixcblxuICAvKiogQGRlc2NyaXB0aW9uIEtleSBmb3IgbWFueS10by1vbmUgcmVsYXRpb24gbWV0YWRhdGEgKi9cbiAgTUFOWV9UT19PTkUgPSBcInJlbGF0aW9ucy5tYW55LXRvLW9uZVwiLFxuXG4gIC8qKiBAZGVzY3JpcHRpb24gS2V5IGZvciBwb3B1bGF0ZSBtZXRhZGF0YSAqL1xuICBQT1BVTEFURSA9IFwicG9wdWxhdGVcIixcbn1cbiJdfQ==

package/lib/persistence/constants.d.ts

@@ -1,22 +1,39 @@
+/**
+ * @description Persistence-related constant keys
+ * @summary Enum containing string constants used throughout the persistence layer for metadata, relations, and other persistence-related operations
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
 export declare enum PersistenceKeys {
+    /** @description Key for index metadata */
     INDEX = "index",
+    /** @description Key for unique constraint metadata */
     UNIQUE = "unique",
+    /** @description Key for adapter metadata */
     ADAPTER = "adapter",
+    /** @description Template for injectable adapter names */
     INJECTABLE = "decaf_{0}_adapter_for_{1}",
+    /** @description Key for table name metadata */
     TABLE = "table",
+    /** @description Key for column name metadata */
     COLUMN = "column",
+    /** @description Key for general metadata storage */
     METADATA = "__metadata",
+    /** @description Key for relations metadata storage */
     RELATIONS = "__relations",
+    /** @description Key for clause sequence metadata */
     CLAUSE_SEQUENCE = "clause-sequence",
+    /** @description Key for created-by ownership metadata */
     CREATED_BY = "ownership.created-by",
+    /** @description Key for updated-by ownership metadata */
     UPDATED_BY = "ownership.updated-by",
+    /** @description Key for one-to-one relation metadata */
     ONE_TO_ONE = "relations.one-to-one",
+    /** @description Key for one-to-many relation metadata */
     ONE_TO_MANY = "relations.one-to-many",
+    /** @description Key for many-to-one relation metadata */
     MANY_TO_ONE = "relations.many-to-one",
+    /** @description Key for populate metadata */
     POPULATE = "populate"
 }
-export declare enum Roles {
-    ADMIN = "admin",
-    WRITER = "writer",
-    READER = "reader"
-}

package/lib/persistence/decorators.cjs

@@ -4,7 +4,17 @@ exports.uses = uses;
 const reflection_1 = require("@decaf-ts/reflection");
 const constants_1 = require("./constants.cjs");
 const Adapter_1 = require("./Adapter.cjs");
+/**
+ * @description Specifies which persistence adapter flavor a model should use
+ * @summary This decorator applies metadata to a model class to indicate which persistence adapter flavor
+ * should be used when performing database operations on instances of the model. The flavor is a string
+ * identifier that corresponds to a registered adapter configuration.
+ * @param {string} flavour - The identifier of the adapter flavor to use
+ * @return {Function} A decorator function that can be applied to a model class
+ * @function uses
+ * @category Class Decorators
+ */
 function uses(flavour) {
     return (0, reflection_1.apply)((0, reflection_1.metadata)(Adapter_1.Adapter.key(constants_1.PersistenceKeys.ADAPTER), flavour));
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVjb3JhdG9ycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9wZXJzaXN0ZW5jZS9kZWNvcmF0b3JzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBSUEsb0JBRUM7QUFORCxxREFBdUQ7QUFDdkQsK0NBQThDO0FBQzlDLDJDQUFvQztBQUVwQyxTQUFnQixJQUFJLENBQUMsT0FBZTtJQUNsQyxPQUFPLElBQUEsa0JBQUssRUFBQyxJQUFBLHFCQUFRLEVBQUMsaUJBQU8sQ0FBQyxHQUFHLENBQUMsMkJBQWUsQ0FBQyxPQUFPLENBQUMsRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDO0FBQ3hFLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBhcHBseSwgbWV0YWRhdGEgfSBmcm9tIFwiQGRlY2FmLXRzL3JlZmxlY3Rpb25cIjtcbmltcG9ydCB7IFBlcnNpc3RlbmNlS2V5cyB9IGZyb20gXCIuL2NvbnN0YW50c1wiO1xuaW1wb3J0IHsgQWRhcHRlciB9IGZyb20gXCIuL0FkYXB0ZXJcIjtcblxuZXhwb3J0IGZ1bmN0aW9uIHVzZXMoZmxhdm91cjogc3RyaW5nKSB7XG4gIHJldHVybiBhcHBseShtZXRhZGF0YShBZGFwdGVyLmtleShQZXJzaXN0ZW5jZUtleXMuQURBUFRFUiksIGZsYXZvdXIpKTtcbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVjb3JhdG9ycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9wZXJzaXN0ZW5jZS9kZWNvcmF0b3JzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBY0Esb0JBRUM7QUFoQkQscURBQXVEO0FBQ3ZELCtDQUE4QztBQUM5QywyQ0FBb0M7QUFFcEM7Ozs7Ozs7OztHQVNHO0FBQ0gsU0FBZ0IsSUFBSSxDQUFDLE9BQWU7SUFDbEMsT0FBTyxJQUFBLGtCQUFLLEVBQUMsSUFBQSxxQkFBUSxFQUFDLGlCQUFPLENBQUMsR0FBRyxDQUFDLDJCQUFlLENBQUMsT0FBTyxDQUFDLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQztBQUN4RSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgYXBwbHksIG1ldGFkYXRhIH0gZnJvbSBcIkBkZWNhZi10cy9yZWZsZWN0aW9uXCI7XG5pbXBvcnQgeyBQZXJzaXN0ZW5jZUtleXMgfSBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmltcG9ydCB7IEFkYXB0ZXIgfSBmcm9tIFwiLi9BZGFwdGVyXCI7XG5cbi8qKlxuICogQGRlc2NyaXB0aW9uIFNwZWNpZmllcyB3aGljaCBwZXJzaXN0ZW5jZSBhZGFwdGVyIGZsYXZvciBhIG1vZGVsIHNob3VsZCB1c2VcbiAqIEBzdW1tYXJ5IFRoaXMgZGVjb3JhdG9yIGFwcGxpZXMgbWV0YWRhdGEgdG8gYSBtb2RlbCBjbGFzcyB0byBpbmRpY2F0ZSB3aGljaCBwZXJzaXN0ZW5jZSBhZGFwdGVyIGZsYXZvclxuICogc2hvdWxkIGJlIHVzZWQgd2hlbiBwZXJmb3JtaW5nIGRhdGFiYXNlIG9wZXJhdGlvbnMgb24gaW5zdGFuY2VzIG9mIHRoZSBtb2RlbC4gVGhlIGZsYXZvciBpcyBhIHN0cmluZ1xuICogaWRlbnRpZmllciB0aGF0IGNvcnJlc3BvbmRzIHRvIGEgcmVnaXN0ZXJlZCBhZGFwdGVyIGNvbmZpZ3VyYXRpb24uXG4gKiBAcGFyYW0ge3N0cmluZ30gZmxhdm91ciAtIFRoZSBpZGVudGlmaWVyIG9mIHRoZSBhZGFwdGVyIGZsYXZvciB0byB1c2VcbiAqIEByZXR1cm4ge0Z1bmN0aW9ufSBBIGRlY29yYXRvciBmdW5jdGlvbiB0aGF0IGNhbiBiZSBhcHBsaWVkIHRvIGEgbW9kZWwgY2xhc3NcbiAqIEBmdW5jdGlvbiB1c2VzXG4gKiBAY2F0ZWdvcnkgQ2xhc3MgRGVjb3JhdG9yc1xuICovXG5leHBvcnQgZnVuY3Rpb24gdXNlcyhmbGF2b3VyOiBzdHJpbmcpIHtcbiAgcmV0dXJuIGFwcGx5KG1ldGFkYXRhKEFkYXB0ZXIua2V5KFBlcnNpc3RlbmNlS2V5cy5BREFQVEVSKSwgZmxhdm91cikpO1xufVxuIl19

package/lib/persistence/decorators.d.ts

@@ -1 +1,11 @@
+/**
+ * @description Specifies which persistence adapter flavor a model should use
+ * @summary This decorator applies metadata to a model class to indicate which persistence adapter flavor
+ * should be used when performing database operations on instances of the model. The flavor is a string
+ * identifier that corresponds to a registered adapter configuration.
+ * @param {string} flavour - The identifier of the adapter flavor to use
+ * @return {Function} A decorator function that can be applied to a model class
+ * @function uses
+ * @category Class Decorators
+ */
 export declare function uses(flavour: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;

package/lib/persistence/errors.cjs

@@ -1,17 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedError = exports.ConnectionError = void 0;
+exports.UnsupportedError = void 0;
 const db_decorators_1 = require("@decaf-ts/db-decorators");
-class ConnectionError extends db_decorators_1.BaseError {
-    constructor(msg) {
-        super(ConnectionError.name, msg);
-    }
-}
-exports.ConnectionError = ConnectionError;
+/**
+ * @description Error thrown when an unsupported operation is attempted
+ * @summary This error is thrown when an operation is requested that is not supported by the current
+ * persistence adapter or configuration. It extends the BaseError class and sets a 500 status code.
+ * @param {string|Error} msg - The error message or an Error object to wrap
+ * @class UnsupportedError
+ * @example
+ * ```typescript
+ * // Throwing an UnsupportedError
+ * if (!adapter.supportsTransactions()) {
+ *   throw new UnsupportedError('Transactions are not supported by this adapter');
+ * }
+ *
+ * // Catching an UnsupportedError
+ * try {
+ *   await adapter.beginTransaction();
+ * } catch (error) {
+ *   if (error instanceof UnsupportedError) {
+ *     console.error('Operation not supported:', error.message);
+ *   }
+ * }
+ * ```
+ */
 class UnsupportedError extends db_decorators_1.BaseError {
     constructor(msg) {
-        super(UnsupportedError.name, msg);
+        super(UnsupportedError.name, msg, 500);
     }
 }
 exports.UnsupportedError = UnsupportedError;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSwyREFBb0Q7QUFFcEQsTUFBYSxlQUFnQixTQUFRLHlCQUFTO0lBQzVDLFlBQVksR0FBbUI7UUFDN0IsS0FBSyxDQUFDLGVBQWUsQ0FBQyxJQUFJLEVBQUUsR0FBRyxDQUFDLENBQUM7SUFDbkMsQ0FBQztDQUNGO0FBSkQsMENBSUM7QUFFRCxNQUFhLGdCQUFpQixTQUFRLHlCQUFTO0lBQzdDLFlBQVksR0FBbUI7UUFDN0IsS0FBSyxDQUFDLGdCQUFnQixDQUFDLElBQUksRUFBRSxHQUFHLENBQUMsQ0FBQztJQUNwQyxDQUFDO0NBQ0Y7QUFKRCw0Q0FJQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IEJhc2VFcnJvciB9IGZyb20gXCJAZGVjYWYtdHMvZGItZGVjb3JhdG9yc1wiO1xuXG5leHBvcnQgY2xhc3MgQ29ubmVjdGlvbkVycm9yIGV4dGVuZHMgQmFzZUVycm9yIHtcbiAgY29uc3RydWN0b3IobXNnOiBzdHJpbmcgfCBFcnJvcikge1xuICAgIHN1cGVyKENvbm5lY3Rpb25FcnJvci5uYW1lLCBtc2cpO1xuICB9XG59XG5cbmV4cG9ydCBjbGFzcyBVbnN1cHBvcnRlZEVycm9yIGV4dGVuZHMgQmFzZUVycm9yIHtcbiAgY29uc3RydWN0b3IobXNnOiBzdHJpbmcgfCBFcnJvcikge1xuICAgIHN1cGVyKFVuc3VwcG9ydGVkRXJyb3IubmFtZSwgbXNnKTtcbiAgfVxufVxuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3BlcnNpc3RlbmNlL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSwyREFBb0Q7QUFFcEQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FzQkc7QUFDSCxNQUFhLGdCQUFpQixTQUFRLHlCQUFTO0lBQzdDLFlBQVksR0FBbUI7UUFDN0IsS0FBSyxDQUFDLGdCQUFnQixDQUFDLElBQUksRUFBRSxHQUFHLEVBQUUsR0FBRyxDQUFDLENBQUM7SUFDekMsQ0FBQztDQUNGO0FBSkQsNENBSUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBCYXNlRXJyb3IgfSBmcm9tIFwiQGRlY2FmLXRzL2RiLWRlY29yYXRvcnNcIjtcblxuLyoqXG4gKiBAZGVzY3JpcHRpb24gRXJyb3IgdGhyb3duIHdoZW4gYW4gdW5zdXBwb3J0ZWQgb3BlcmF0aW9uIGlzIGF0dGVtcHRlZFxuICogQHN1bW1hcnkgVGhpcyBlcnJvciBpcyB0aHJvd24gd2hlbiBhbiBvcGVyYXRpb24gaXMgcmVxdWVzdGVkIHRoYXQgaXMgbm90IHN1cHBvcnRlZCBieSB0aGUgY3VycmVudFxuICogcGVyc2lzdGVuY2UgYWRhcHRlciBvciBjb25maWd1cmF0aW9uLiBJdCBleHRlbmRzIHRoZSBCYXNlRXJyb3IgY2xhc3MgYW5kIHNldHMgYSA1MDAgc3RhdHVzIGNvZGUuXG4gKiBAcGFyYW0ge3N0cmluZ3xFcnJvcn0gbXNnIC0gVGhlIGVycm9yIG1lc3NhZ2Ugb3IgYW4gRXJyb3Igb2JqZWN0IHRvIHdyYXBcbiAqIEBjbGFzcyBVbnN1cHBvcnRlZEVycm9yXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogLy8gVGhyb3dpbmcgYW4gVW5zdXBwb3J0ZWRFcnJvclxuICogaWYgKCFhZGFwdGVyLnN1cHBvcnRzVHJhbnNhY3Rpb25zKCkpIHtcbiAqICAgdGhyb3cgbmV3IFVuc3VwcG9ydGVkRXJyb3IoJ1RyYW5zYWN0aW9ucyBhcmUgbm90IHN1cHBvcnRlZCBieSB0aGlzIGFkYXB0ZXInKTtcbiAqIH1cbiAqIFxuICogLy8gQ2F0Y2hpbmcgYW4gVW5zdXBwb3J0ZWRFcnJvclxuICogdHJ5IHtcbiAqICAgYXdhaXQgYWRhcHRlci5iZWdpblRyYW5zYWN0aW9uKCk7XG4gKiB9IGNhdGNoIChlcnJvcikge1xuICogICBpZiAoZXJyb3IgaW5zdGFuY2VvZiBVbnN1cHBvcnRlZEVycm9yKSB7XG4gKiAgICAgY29uc29sZS5lcnJvcignT3BlcmF0aW9uIG5vdCBzdXBwb3J0ZWQ6JywgZXJyb3IubWVzc2FnZSk7XG4gKiAgIH1cbiAqIH1cbiAqIGBgYFxuICovXG5leHBvcnQgY2xhc3MgVW5zdXBwb3J0ZWRFcnJvciBleHRlbmRzIEJhc2VFcnJvciB7XG4gIGNvbnN0cnVjdG9yKG1zZzogc3RyaW5nIHwgRXJyb3IpIHtcbiAgICBzdXBlcihVbnN1cHBvcnRlZEVycm9yLm5hbWUsIG1zZywgNTAwKTtcbiAgfVxufVxuIl19

package/lib/persistence/errors.d.ts

@@ -1,7 +1,27 @@
 import { BaseError } from "@decaf-ts/db-decorators";
-export declare class ConnectionError extends BaseError {
-    constructor(msg: string | Error);
-}
+/**
+ * @description Error thrown when an unsupported operation is attempted
+ * @summary This error is thrown when an operation is requested that is not supported by the current
+ * persistence adapter or configuration. It extends the BaseError class and sets a 500 status code.
+ * @param {string|Error} msg - The error message or an Error object to wrap
+ * @class UnsupportedError
+ * @example
+ * ```typescript
+ * // Throwing an UnsupportedError
+ * if (!adapter.supportsTransactions()) {
+ *   throw new UnsupportedError('Transactions are not supported by this adapter');
+ * }
+ *
+ * // Catching an UnsupportedError
+ * try {
+ *   await adapter.beginTransaction();
+ * } catch (error) {
+ *   if (error instanceof UnsupportedError) {
+ *     console.error('Operation not supported:', error.message);
+ *   }
+ * }
+ * ```
+ */
 export declare class UnsupportedError extends BaseError {
     constructor(msg: string | Error);
 }

package/lib/persistence/index.cjs

@@ -17,6 +17,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Adapter.cjs"), exports);
 __exportStar(require("./constants.cjs"), exports);
 __exportStar(require("./decorators.cjs"), exports);
+__exportStar(require("./Dispatch.cjs"), exports);
 __exportStar(require("./errors.cjs"), exports);
+__exportStar(require("./ObserverHandler.cjs"), exports);
 __exportStar(require("./Sequence.cjs"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLGdEQUEwQjtBQUMxQixrREFBNEI7QUFDNUIsbURBQTZCO0FBQzdCLCtDQUF5QjtBQUN6QixpREFBMkIiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi9BZGFwdGVyXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL2RlY29yYXRvcnNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL2Vycm9yc1wiO1xuZXhwb3J0ICogZnJvbSBcIi4vU2VxdWVuY2VcIjtcbiJdfQ==
+__exportStar(require("./types.cjs"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLGdEQUEwQjtBQUMxQixrREFBNEI7QUFDNUIsbURBQTZCO0FBQzdCLGlEQUEyQjtBQUMzQiwrQ0FBeUI7QUFDekIsd0RBQWtDO0FBQ2xDLGlEQUEyQjtBQUMzQiw4Q0FBd0IiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi9BZGFwdGVyXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL2RlY29yYXRvcnNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL0Rpc3BhdGNoXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9lcnJvcnNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL09ic2VydmVySGFuZGxlclwiO1xuZXhwb3J0ICogZnJvbSBcIi4vU2VxdWVuY2VcIjtcbmV4cG9ydCAqIGZyb20gXCIuL3R5cGVzXCI7XG4iXX0=

package/lib/persistence/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./Adapter";
 export * from "./constants";
 export * from "./decorators";
+export * from "./Dispatch";
 export * from "./errors";
+export * from "./ObserverHandler";
 export * from "./Sequence";
+export * from "./types";

package/lib/persistence/types.cjs

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcGVyc2lzdGVuY2UvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IEJ1bGtDcnVkT3BlcmF0aW9uS2V5cywgT3BlcmF0aW9uS2V5cyB9IGZyb20gXCJAZGVjYWYtdHMvZGItZGVjb3JhdG9yc1wiO1xuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBUeXBlIHJlcHJlc2VudGluZyBwb3NzaWJsZSBJRCBmb3JtYXRzIGZvciBkYXRhYmFzZSBldmVudHNcbiAqIEBzdW1tYXJ5IEEgdW5pb24gdHlwZSB0aGF0IGRlZmluZXMgdGhlIHBvc3NpYmxlIGZvcm1hdHMgZm9yIGV2ZW50IGlkZW50aWZpZXJzIGluIHRoZSBwZXJzaXN0ZW5jZSBsYXllci5cbiAqIFRoZXNlIGNhbiBiZSBzaW5nbGUgdmFsdWVzIChzdHJpbmcsIG51bWJlciwgYmlnaW50KSBvciBhcnJheXMgb2YgdGhlc2UgdHlwZXMuXG4gKiBAdHlwZWRlZiB7KHN0cmluZ3xudW1iZXJ8YmlnaW50fHN0cmluZ1tdfG51bWJlcltdfGJpZ2ludFtdKX0gRXZlbnRJZHNcbiAqIEBtZW1iZXJPZiBtb2R1bGU6Y29yZVxuICovXG5leHBvcnQgdHlwZSBFdmVudElkcyA9XG4gIHwgc3RyaW5nXG4gIHwgbnVtYmVyXG4gIHwgYmlnaW50XG4gIHwgc3RyaW5nW11cbiAgfCBudW1iZXJbXVxuICB8IGJpZ2ludFtdO1xuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBGdW5jdGlvbiB0eXBlIGZvciBmaWx0ZXJpbmcgb2JzZXJ2ZXIgbm90aWZpY2F0aW9uc1xuICogQHN1bW1hcnkgQSBmdW5jdGlvbiB0eXBlIHRoYXQgZGVmaW5lcyBhIHByZWRpY2F0ZSB1c2VkIHRvIGRldGVybWluZSB3aGV0aGVyIGFuIG9ic2VydmVyIHNob3VsZCBiZSBub3RpZmllZFxuICogYWJvdXQgYSBzcGVjaWZpYyBkYXRhYmFzZSBldmVudC4gVGhlIGZpbHRlciBleGFtaW5lcyB0aGUgdGFibGUgbmFtZSwgZXZlbnQgdHlwZSwgYW5kIGFmZmVjdGVkIElEcy5cbiAqIEBwYXJhbSB7c3RyaW5nfSB0YWJsZSAtIFRoZSBuYW1lIG9mIHRoZSBkYXRhYmFzZSB0YWJsZSB3aGVyZSB0aGUgZXZlbnQgb2NjdXJyZWRcbiAqIEBwYXJhbSB7KE9wZXJhdGlvbktleXN8QnVsa0NydWRPcGVyYXRpb25LZXlzfHN0cmluZyl9IGV2ZW50IC0gVGhlIHR5cGUgb2Ygb3BlcmF0aW9uIHRoYXQgdHJpZ2dlcmVkIHRoZSBldmVudFxuICogQHBhcmFtIHtFdmVudElkc30gaWQgLSBUaGUgaWRlbnRpZmllcihzKSBvZiB0aGUgYWZmZWN0ZWQgcmVjb3JkKHMpXG4gKiBAcmV0dXJuIHtib29sZWFufSBUcnVlIGlmIHRoZSBvYnNlcnZlciBzaG91bGQgYmUgbm90aWZpZWQsIGZhbHNlIG90aGVyd2lzZVxuICogQHR5cGVkZWYge0Z1bmN0aW9ufSBPYnNlcnZlckZpbHRlclxuICogQG1lbWJlck9mIG1vZHVsZTpjb3JlXG4gKi9cbmV4cG9ydCB0eXBlIE9ic2VydmVyRmlsdGVyID0gKFxuICB0YWJsZTogc3RyaW5nLFxuICBldmVudDogT3BlcmF0aW9uS2V5cyB8IEJ1bGtDcnVkT3BlcmF0aW9uS2V5cyB8IHN0cmluZyxcbiAgaWQ6IEV2ZW50SWRzXG4pID0+IGJvb2xlYW47XG4iXX0=

package/lib/persistence/types.d.ts

@@ -0,0 +1,21 @@
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+/**
+ * @description Type representing possible ID formats for database events
+ * @summary A union type that defines the possible formats for event identifiers in the persistence layer.
+ * These can be single values (string, number, bigint) or arrays of these types.
+ * @typedef {(string|number|bigint|string[]|number[]|bigint[])} EventIds
+ * @memberOf module:core
+ */
+export type EventIds = string | number | bigint | string[] | number[] | bigint[];
+/**
+ * @description Function type for filtering observer notifications
+ * @summary A function type that defines a predicate used to determine whether an observer should be notified
+ * about a specific database event. The filter examines the table name, event type, and affected IDs.
+ * @param {string} table - The name of the database table where the event occurred
+ * @param {(OperationKeys|BulkCrudOperationKeys|string)} event - The type of operation that triggered the event
+ * @param {EventIds} id - The identifier(s) of the affected record(s)
+ * @return {boolean} True if the observer should be notified, false otherwise
+ * @typedef {Function} ObserverFilter
+ * @memberOf module:core
+ */
+export type ObserverFilter = (table: string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds) => boolean;