@decaf-ts/core 0.5.0 → 0.5.2

package/lib/esm/query/Paginator.d.ts

@@ -1,8 +1,66 @@
-import { Statement } from "./Statement";
-export declare abstract class Paginator<V, Q> {
-    protected stat: Statement<Q>;
+import { Adapter } from "../persistence";
+import { Constructor, Model } from "@decaf-ts/decorator-validation";
+/**
+ * @description Handles pagination for database queries
+ * @summary Provides functionality for navigating through paginated query results
+ *
+ * This abstract class manages the state and navigation of paginated database query results.
+ * It tracks the current page, total pages, and record count, and provides methods for
+ * moving between pages.
+ *
+ * @template M - The model type this paginator operates on
+ * @template R - The return type of the paginated query (defaults to M[])
+ * @template Q - The query type (defaults to any)
+ * @param {Adapter<any, Q, any, any>} adapter - The database adapter to use for executing queries
+ * @param {Q} query - The query to paginate
+ * @param {number} size - The number of records per page
+ * @param {Constructor<M>} clazz - The constructor for the model type
+ * @class Paginator
+ * @example
+ * // Create a paginator for a user query
+ * const userQuery = db.select().from(User);
+ * const paginator = await userQuery.paginate(10); // 10 users per page
+ *
+ * // Get the first page of results
+ * const firstPage = await paginator.page(1);
+ *
+ * // Navigate to the next page
+ * const secondPage = await paginator.next();
+ *
+ * // Get information about the pagination
+ * console.log(`Page ${paginator.current} of ${paginator.total}, ${paginator.count} total records`);
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Paginator
+ *   participant Adapter
+ *   participant Database
+ *
+ *   Client->>Paginator: new Paginator(adapter, query, size, clazz)
+ *   Client->>Paginator: page(1)
+ *   Paginator->>Paginator: validatePage(1)
+ *   Paginator->>Paginator: prepare(query)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ *
+ *   Client->>Paginator: next()
+ *   Paginator->>Paginator: page(current + 1)
+ *   Paginator->>Paginator: validatePage(current + 1)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ */
+export declare abstract class Paginator<M extends Model, R = M[], Q = any> {
+    protected readonly adapter: Adapter<any, Q, any, any>;
+    protected readonly query: Q;
     readonly size: number;
-    protected readonly _rawStatement: Q;
+    protected readonly clazz: Constructor<M>;
     protected _currentPage: number;
     protected _totalPages: number;
     protected _recordCount: number;
@@ -11,12 +69,11 @@ export declare abstract class Paginator<V, Q> {
     get current(): number;
     get total(): number;
     get count(): number;
-    get statement(): Q;
-    protected get adapter(): import("..").Adapter<any, Q, any, any>;
-    protected constructor(stat: Statement<Q>, size: number, _rawStatement: Q);
+    protected get statement(): Q;
+    protected constructor(adapter: Adapter<any, Q, any, any>, query: Q, size: number, clazz: Constructor<M>);
     protected abstract prepare(rawStatement: Q): Q;
-    next(): Promise<V[]>;
-    previous(): Promise<V[]>;
+    next(): Promise<R[]>;
+    previous(): Promise<R[]>;
     protected validatePage(page: number): number;
-    abstract page(page?: number, ...args: any[]): Promise<V[]>;
+    abstract page(page?: number): Promise<R[]>;
 }

package/lib/esm/query/Paginator.js

@@ -1,4 +1,60 @@
 import { PagingError } from "./errors";
+/**
+ * @description Handles pagination for database queries
+ * @summary Provides functionality for navigating through paginated query results
+ *
+ * This abstract class manages the state and navigation of paginated database query results.
+ * It tracks the current page, total pages, and record count, and provides methods for
+ * moving between pages.
+ *
+ * @template M - The model type this paginator operates on
+ * @template R - The return type of the paginated query (defaults to M[])
+ * @template Q - The query type (defaults to any)
+ * @param {Adapter<any, Q, any, any>} adapter - The database adapter to use for executing queries
+ * @param {Q} query - The query to paginate
+ * @param {number} size - The number of records per page
+ * @param {Constructor<M>} clazz - The constructor for the model type
+ * @class Paginator
+ * @example
+ * // Create a paginator for a user query
+ * const userQuery = db.select().from(User);
+ * const paginator = await userQuery.paginate(10); // 10 users per page
+ *
+ * // Get the first page of results
+ * const firstPage = await paginator.page(1);
+ *
+ * // Navigate to the next page
+ * const secondPage = await paginator.next();
+ *
+ * // Get information about the pagination
+ * console.log(`Page ${paginator.current} of ${paginator.total}, ${paginator.count} total records`);
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Paginator
+ *   participant Adapter
+ *   participant Database
+ *
+ *   Client->>Paginator: new Paginator(adapter, query, size, clazz)
+ *   Client->>Paginator: page(1)
+ *   Paginator->>Paginator: validatePage(1)
+ *   Paginator->>Paginator: prepare(query)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ *
+ *   Client->>Paginator: next()
+ *   Paginator->>Paginator: page(current + 1)
+ *   Paginator->>Paginator: validatePage(current + 1)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ */
 export class Paginator {
     get current() {
         return this._currentPage;
@@ -11,16 +67,14 @@ export class Paginator {
     }
     get statement() {
         if (!this._statement)
-            this._statement = this.prepare(this._rawStatement);
+            this._statement = this.prepare(this.query);
         return this._statement;
     }
-    get adapter() {
-        return this.stat.getAdapter();
-    }
-    constructor(stat, size, _rawStatement) {
-        this.stat = stat;
+    constructor(adapter, query, size, clazz) {
+        this.adapter = adapter;
+        this.query = query;
         this.size = size;
-        this._rawStatement = _rawStatement;
+        this.clazz = clazz;
     }
     async next() {
         return this.page(this.current + 1);
@@ -30,10 +84,10 @@ export class Paginator {
     }
     validatePage(page) {
         if (page < 1 || !Number.isInteger(page))
-            throw new PagingError("page number cannot be under 1 and must be an integer");
+            throw new PagingError("Page number cannot be under 1 and must be an integer");
         if (typeof this._totalPages !== "undefined" && page > this._totalPages)
-            throw new PagingError(`Requested more pages than available. Total pages: ${this._totalPages}`);
+            throw new PagingError(`Only ${this._totalPages} are available. Cannot go to page ${page}`);
         return page;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUGFnaW5hdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3F1ZXJ5L1BhZ2luYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sVUFBVSxDQUFDO0FBR3ZDLE1BQU0sT0FBZ0IsU0FBUztJQVE3QixJQUFJLE9BQU87UUFDVCxPQUFPLElBQUksQ0FBQyxZQUFZLENBQUM7SUFDM0IsQ0FBQztJQUVELElBQUksS0FBSztRQUNQLE9BQU8sSUFBSSxDQUFDLFdBQVcsQ0FBQztJQUMxQixDQUFDO0lBRUQsSUFBSSxLQUFLO1FBQ1AsT0FBTyxJQUFJLENBQUMsWUFBWSxDQUFDO0lBQzNCLENBQUM7SUFFRCxJQUFJLFNBQVM7UUFDWCxJQUFJLENBQUMsSUFBSSxDQUFDLFVBQVU7WUFBRSxJQUFJLENBQUMsVUFBVSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxDQUFDO1FBQ3pFLE9BQU8sSUFBSSxDQUFDLFVBQVUsQ0FBQztJQUN6QixDQUFDO0lBRUQsSUFBYyxPQUFPO1FBQ25CLE9BQU8sSUFBSSxDQUFDLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztJQUNoQyxDQUFDO0lBRUQsWUFDWSxJQUFrQixFQUNuQixJQUFZLEVBQ0YsYUFBZ0I7UUFGekIsU0FBSSxHQUFKLElBQUksQ0FBYztRQUNuQixTQUFJLEdBQUosSUFBSSxDQUFRO1FBQ0Ysa0JBQWEsR0FBYixhQUFhLENBQUc7SUFDbEMsQ0FBQztJQUlKLEtBQUssQ0FBQyxJQUFJO1FBQ1IsT0FBTyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVELEtBQUssQ0FBQyxRQUFRO1FBQ1osT0FBTyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVTLFlBQVksQ0FBQyxJQUFZO1FBQ2pDLElBQUksSUFBSSxHQUFHLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDO1lBQ3JDLE1BQU0sSUFBSSxXQUFXLENBQ25CLHNEQUFzRCxDQUN2RCxDQUFDO1FBQ0osSUFBSSxPQUFPLElBQUksQ0FBQyxXQUFXLEtBQUssV0FBVyxJQUFJLElBQUksR0FBRyxJQUFJLENBQUMsV0FBVztZQUNwRSxNQUFNLElBQUksV0FBVyxDQUNuQixxREFBcUQsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUN4RSxDQUFDO1FBQ0osT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0NBR0YiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBQYWdpbmdFcnJvciB9IGZyb20gXCIuL2Vycm9yc1wiO1xuaW1wb3J0IHsgU3RhdGVtZW50IH0gZnJvbSBcIi4vU3RhdGVtZW50XCI7XG5cbmV4cG9ydCBhYnN0cmFjdCBjbGFzcyBQYWdpbmF0b3I8ViwgUT4ge1xuICBwcm90ZWN0ZWQgX2N1cnJlbnRQYWdlITogbnVtYmVyO1xuICBwcm90ZWN0ZWQgX3RvdGFsUGFnZXMhOiBudW1iZXI7XG4gIHByb3RlY3RlZCBfcmVjb3JkQ291bnQhOiBudW1iZXI7XG4gIHByb3RlY3RlZCBsaW1pdCE6IG51bWJlcjtcblxuICBwcml2YXRlIF9zdGF0ZW1lbnQ/OiBRO1xuXG4gIGdldCBjdXJyZW50KCkge1xuICAgIHJldHVybiB0aGlzLl9jdXJyZW50UGFnZTtcbiAgfVxuXG4gIGdldCB0b3RhbCgpIHtcbiAgICByZXR1cm4gdGhpcy5fdG90YWxQYWdlcztcbiAgfVxuXG4gIGdldCBjb3VudCgpOiBudW1iZXIge1xuICAgIHJldHVybiB0aGlzLl9yZWNvcmRDb3VudDtcbiAgfVxuXG4gIGdldCBzdGF0ZW1lbnQoKSB7XG4gICAgaWYgKCF0aGlzLl9zdGF0ZW1lbnQpIHRoaXMuX3N0YXRlbWVudCA9IHRoaXMucHJlcGFyZSh0aGlzLl9yYXdTdGF0ZW1lbnQpO1xuICAgIHJldHVybiB0aGlzLl9zdGF0ZW1lbnQ7XG4gIH1cblxuICBwcm90ZWN0ZWQgZ2V0IGFkYXB0ZXIoKSB7XG4gICAgcmV0dXJuIHRoaXMuc3RhdC5nZXRBZGFwdGVyKCk7XG4gIH1cblxuICBwcm90ZWN0ZWQgY29uc3RydWN0b3IoXG4gICAgcHJvdGVjdGVkIHN0YXQ6IFN0YXRlbWVudDxRPixcbiAgICByZWFkb25seSBzaXplOiBudW1iZXIsXG4gICAgcHJvdGVjdGVkIHJlYWRvbmx5IF9yYXdTdGF0ZW1lbnQ6IFFcbiAgKSB7fVxuXG4gIHByb3RlY3RlZCBhYnN0cmFjdCBwcmVwYXJlKHJhd1N0YXRlbWVudDogUSk6IFE7XG5cbiAgYXN5bmMgbmV4dCgpIHtcbiAgICByZXR1cm4gdGhpcy5wYWdlKHRoaXMuY3VycmVudCArIDEpO1xuICB9XG5cbiAgYXN5bmMgcHJldmlvdXMoKSB7XG4gICAgcmV0dXJuIHRoaXMucGFnZSh0aGlzLmN1cnJlbnQgLSAxKTtcbiAgfVxuXG4gIHByb3RlY3RlZCB2YWxpZGF0ZVBhZ2UocGFnZTogbnVtYmVyKSB7XG4gICAgaWYgKHBhZ2UgPCAxIHx8ICFOdW1iZXIuaXNJbnRlZ2VyKHBhZ2UpKVxuICAgICAgdGhyb3cgbmV3IFBhZ2luZ0Vycm9yKFxuICAgICAgICBcInBhZ2UgbnVtYmVyIGNhbm5vdCBiZSB1bmRlciAxIGFuZCBtdXN0IGJlIGFuIGludGVnZXJcIlxuICAgICAgKTtcbiAgICBpZiAodHlwZW9mIHRoaXMuX3RvdGFsUGFnZXMgIT09IFwidW5kZWZpbmVkXCIgJiYgcGFnZSA+IHRoaXMuX3RvdGFsUGFnZXMpXG4gICAgICB0aHJvdyBuZXcgUGFnaW5nRXJyb3IoXG4gICAgICAgIGBSZXF1ZXN0ZWQgbW9yZSBwYWdlcyB0aGFuIGF2YWlsYWJsZS4gVG90YWwgcGFnZXM6ICR7dGhpcy5fdG90YWxQYWdlc31gXG4gICAgICApO1xuICAgIHJldHVybiBwYWdlO1xuICB9XG5cbiAgYWJzdHJhY3QgcGFnZShwYWdlPzogbnVtYmVyLCAuLi5hcmdzOiBhbnlbXSk6IFByb21pc2U8VltdPjtcbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUGFnaW5hdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3F1ZXJ5L1BhZ2luYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sVUFBVSxDQUFDO0FBSXZDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBdURHO0FBQ0gsTUFBTSxPQUFnQixTQUFTO0lBUTdCLElBQUksT0FBTztRQUNULE9BQU8sSUFBSSxDQUFDLFlBQVksQ0FBQztJQUMzQixDQUFDO0lBRUQsSUFBSSxLQUFLO1FBQ1AsT0FBTyxJQUFJLENBQUMsV0FBVyxDQUFDO0lBQzFCLENBQUM7SUFFRCxJQUFJLEtBQUs7UUFDUCxPQUFPLElBQUksQ0FBQyxZQUFZLENBQUM7SUFDM0IsQ0FBQztJQUVELElBQWMsU0FBUztRQUNyQixJQUFJLENBQUMsSUFBSSxDQUFDLFVBQVU7WUFBRSxJQUFJLENBQUMsVUFBVSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQ2pFLE9BQU8sSUFBSSxDQUFDLFVBQVUsQ0FBQztJQUN6QixDQUFDO0lBRUQsWUFDcUIsT0FBa0MsRUFDbEMsS0FBUSxFQUNsQixJQUFZLEVBQ0YsS0FBcUI7UUFIckIsWUFBTyxHQUFQLE9BQU8sQ0FBMkI7UUFDbEMsVUFBSyxHQUFMLEtBQUssQ0FBRztRQUNsQixTQUFJLEdBQUosSUFBSSxDQUFRO1FBQ0YsVUFBSyxHQUFMLEtBQUssQ0FBZ0I7SUFDdkMsQ0FBQztJQUlKLEtBQUssQ0FBQyxJQUFJO1FBQ1IsT0FBTyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVELEtBQUssQ0FBQyxRQUFRO1FBQ1osT0FBTyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVTLFlBQVksQ0FBQyxJQUFZO1FBQ2pDLElBQUksSUFBSSxHQUFHLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDO1lBQ3JDLE1BQU0sSUFBSSxXQUFXLENBQ25CLHNEQUFzRCxDQUN2RCxDQUFDO1FBQ0osSUFBSSxPQUFPLElBQUksQ0FBQyxXQUFXLEtBQUssV0FBVyxJQUFJLElBQUksR0FBRyxJQUFJLENBQUMsV0FBVztZQUNwRSxNQUFNLElBQUksV0FBVyxDQUNuQixRQUFRLElBQUksQ0FBQyxXQUFXLHFDQUFxQyxJQUFJLEVBQUUsQ0FDcEUsQ0FBQztRQUNKLE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztDQUdGIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgUGFnaW5nRXJyb3IgfSBmcm9tIFwiLi9lcnJvcnNcIjtcbmltcG9ydCB7IEFkYXB0ZXIgfSBmcm9tIFwiLi4vcGVyc2lzdGVuY2VcIjtcbmltcG9ydCB7IENvbnN0cnVjdG9yLCBNb2RlbCB9IGZyb20gXCJAZGVjYWYtdHMvZGVjb3JhdG9yLXZhbGlkYXRpb25cIjtcblxuLyoqXG4gKiBAZGVzY3JpcHRpb24gSGFuZGxlcyBwYWdpbmF0aW9uIGZvciBkYXRhYmFzZSBxdWVyaWVzXG4gKiBAc3VtbWFyeSBQcm92aWRlcyBmdW5jdGlvbmFsaXR5IGZvciBuYXZpZ2F0aW5nIHRocm91Z2ggcGFnaW5hdGVkIHF1ZXJ5IHJlc3VsdHNcbiAqIFxuICogVGhpcyBhYnN0cmFjdCBjbGFzcyBtYW5hZ2VzIHRoZSBzdGF0ZSBhbmQgbmF2aWdhdGlvbiBvZiBwYWdpbmF0ZWQgZGF0YWJhc2UgcXVlcnkgcmVzdWx0cy5cbiAqIEl0IHRyYWNrcyB0aGUgY3VycmVudCBwYWdlLCB0b3RhbCBwYWdlcywgYW5kIHJlY29yZCBjb3VudCwgYW5kIHByb3ZpZGVzIG1ldGhvZHMgZm9yXG4gKiBtb3ZpbmcgYmV0d2VlbiBwYWdlcy5cbiAqIFxuICogQHRlbXBsYXRlIE0gLSBUaGUgbW9kZWwgdHlwZSB0aGlzIHBhZ2luYXRvciBvcGVyYXRlcyBvblxuICogQHRlbXBsYXRlIFIgLSBUaGUgcmV0dXJuIHR5cGUgb2YgdGhlIHBhZ2luYXRlZCBxdWVyeSAoZGVmYXVsdHMgdG8gTVtdKVxuICogQHRlbXBsYXRlIFEgLSBUaGUgcXVlcnkgdHlwZSAoZGVmYXVsdHMgdG8gYW55KVxuICogQHBhcmFtIHtBZGFwdGVyPGFueSwgUSwgYW55LCBhbnk+fSBhZGFwdGVyIC0gVGhlIGRhdGFiYXNlIGFkYXB0ZXIgdG8gdXNlIGZvciBleGVjdXRpbmcgcXVlcmllc1xuICogQHBhcmFtIHtRfSBxdWVyeSAtIFRoZSBxdWVyeSB0byBwYWdpbmF0ZVxuICogQHBhcmFtIHtudW1iZXJ9IHNpemUgLSBUaGUgbnVtYmVyIG9mIHJlY29yZHMgcGVyIHBhZ2VcbiAqIEBwYXJhbSB7Q29uc3RydWN0b3I8TT59IGNsYXp6IC0gVGhlIGNvbnN0cnVjdG9yIGZvciB0aGUgbW9kZWwgdHlwZVxuICogQGNsYXNzIFBhZ2luYXRvclxuICogQGV4YW1wbGVcbiAqIC8vIENyZWF0ZSBhIHBhZ2luYXRvciBmb3IgYSB1c2VyIHF1ZXJ5XG4gKiBjb25zdCB1c2VyUXVlcnkgPSBkYi5zZWxlY3QoKS5mcm9tKFVzZXIpO1xuICogY29uc3QgcGFnaW5hdG9yID0gYXdhaXQgdXNlclF1ZXJ5LnBhZ2luYXRlKDEwKTsgLy8gMTAgdXNlcnMgcGVyIHBhZ2VcbiAqIFxuICogLy8gR2V0IHRoZSBmaXJzdCBwYWdlIG9mIHJlc3VsdHNcbiAqIGNvbnN0IGZpcnN0UGFnZSA9IGF3YWl0IHBhZ2luYXRvci5wYWdlKDEpO1xuICogXG4gKiAvLyBOYXZpZ2F0ZSB0byB0aGUgbmV4dCBwYWdlXG4gKiBjb25zdCBzZWNvbmRQYWdlID0gYXdhaXQgcGFnaW5hdG9yLm5leHQoKTtcbiAqIFxuICogLy8gR2V0IGluZm9ybWF0aW9uIGFib3V0IHRoZSBwYWdpbmF0aW9uXG4gKiBjb25zb2xlLmxvZyhgUGFnZSAke3BhZ2luYXRvci5jdXJyZW50fSBvZiAke3BhZ2luYXRvci50b3RhbH0sICR7cGFnaW5hdG9yLmNvdW50fSB0b3RhbCByZWNvcmRzYCk7XG4gKiBcbiAqIEBtZXJtYWlkXG4gKiBzZXF1ZW5jZURpYWdyYW1cbiAqICAgcGFydGljaXBhbnQgQ2xpZW50XG4gKiAgIHBhcnRpY2lwYW50IFBhZ2luYXRvclxuICogICBwYXJ0aWNpcGFudCBBZGFwdGVyXG4gKiAgIHBhcnRpY2lwYW50IERhdGFiYXNlXG4gKiAgIFxuICogICBDbGllbnQtPj5QYWdpbmF0b3I6IG5ldyBQYWdpbmF0b3IoYWRhcHRlciwgcXVlcnksIHNpemUsIGNsYXp6KVxuICogICBDbGllbnQtPj5QYWdpbmF0b3I6IHBhZ2UoMSlcbiAqICAgUGFnaW5hdG9yLT4+UGFnaW5hdG9yOiB2YWxpZGF0ZVBhZ2UoMSlcbiAqICAgUGFnaW5hdG9yLT4+UGFnaW5hdG9yOiBwcmVwYXJlKHF1ZXJ5KVxuICogICBQYWdpbmF0b3ItPj5BZGFwdGVyOiBleGVjdXRlIHF1ZXJ5IHdpdGggcGFnaW5hdGlvblxuICogICBBZGFwdGVyLT4+RGF0YWJhc2U6IGV4ZWN1dGUgcXVlcnlcbiAqICAgRGF0YWJhc2UtLT4+QWRhcHRlcjogcmV0dXJuIHJlc3VsdHNcbiAqICAgQWRhcHRlci0tPj5QYWdpbmF0b3I6IHJldHVybiByZXN1bHRzXG4gKiAgIFBhZ2luYXRvci0tPj5DbGllbnQ6IHJldHVybiBwYWdlIHJlc3VsdHNcbiAqICAgXG4gKiAgIENsaWVudC0+PlBhZ2luYXRvcjogbmV4dCgpXG4gKiAgIFBhZ2luYXRvci0+PlBhZ2luYXRvcjogcGFnZShjdXJyZW50ICsgMSlcbiAqICAgUGFnaW5hdG9yLT4+UGFnaW5hdG9yOiB2YWxpZGF0ZVBhZ2UoY3VycmVudCArIDEpXG4gKiAgIFBhZ2luYXRvci0+PkFkYXB0ZXI6IGV4ZWN1dGUgcXVlcnkgd2l0aCBwYWdpbmF0aW9uXG4gKiAgIEFkYXB0ZXItPj5EYXRhYmFzZTogZXhlY3V0ZSBxdWVyeVxuICogICBEYXRhYmFzZS0tPj5BZGFwdGVyOiByZXR1cm4gcmVzdWx0c1xuICogICBBZGFwdGVyLS0+PlBhZ2luYXRvcjogcmV0dXJuIHJlc3VsdHNcbiAqICAgUGFnaW5hdG9yLS0+PkNsaWVudDogcmV0dXJuIHBhZ2UgcmVzdWx0c1xuICovXG5leHBvcnQgYWJzdHJhY3QgY2xhc3MgUGFnaW5hdG9yPE0gZXh0ZW5kcyBNb2RlbCwgUiA9IE1bXSwgUSA9IGFueT4ge1xuICBwcm90ZWN0ZWQgX2N1cnJlbnRQYWdlITogbnVtYmVyO1xuICBwcm90ZWN0ZWQgX3RvdGFsUGFnZXMhOiBudW1iZXI7XG4gIHByb3RlY3RlZCBfcmVjb3JkQ291bnQhOiBudW1iZXI7XG4gIHByb3RlY3RlZCBsaW1pdCE6IG51bWJlcjtcblxuICBwcml2YXRlIF9zdGF0ZW1lbnQ/OiBRO1xuXG4gIGdldCBjdXJyZW50KCkge1xuICAgIHJldHVybiB0aGlzLl9jdXJyZW50UGFnZTtcbiAgfVxuXG4gIGdldCB0b3RhbCgpIHtcbiAgICByZXR1cm4gdGhpcy5fdG90YWxQYWdlcztcbiAgfVxuXG4gIGdldCBjb3VudCgpOiBudW1iZXIge1xuICAgIHJldHVybiB0aGlzLl9yZWNvcmRDb3VudDtcbiAgfVxuXG4gIHByb3RlY3RlZCBnZXQgc3RhdGVtZW50KCkge1xuICAgIGlmICghdGhpcy5fc3RhdGVtZW50KSB0aGlzLl9zdGF0ZW1lbnQgPSB0aGlzLnByZXBhcmUodGhpcy5xdWVyeSk7XG4gICAgcmV0dXJuIHRoaXMuX3N0YXRlbWVudDtcbiAgfVxuXG4gIHByb3RlY3RlZCBjb25zdHJ1Y3RvcihcbiAgICBwcm90ZWN0ZWQgcmVhZG9ubHkgYWRhcHRlcjogQWRhcHRlcjxhbnksIFEsIGFueSwgYW55PixcbiAgICBwcm90ZWN0ZWQgcmVhZG9ubHkgcXVlcnk6IFEsXG4gICAgcmVhZG9ubHkgc2l6ZTogbnVtYmVyLFxuICAgIHByb3RlY3RlZCByZWFkb25seSBjbGF6ejogQ29uc3RydWN0b3I8TT5cbiAgKSB7fVxuXG4gIHByb3RlY3RlZCBhYnN0cmFjdCBwcmVwYXJlKHJhd1N0YXRlbWVudDogUSk6IFE7XG5cbiAgYXN5bmMgbmV4dCgpIHtcbiAgICByZXR1cm4gdGhpcy5wYWdlKHRoaXMuY3VycmVudCArIDEpO1xuICB9XG5cbiAgYXN5bmMgcHJldmlvdXMoKSB7XG4gICAgcmV0dXJuIHRoaXMucGFnZSh0aGlzLmN1cnJlbnQgLSAxKTtcbiAgfVxuXG4gIHByb3RlY3RlZCB2YWxpZGF0ZVBhZ2UocGFnZTogbnVtYmVyKSB7XG4gICAgaWYgKHBhZ2UgPCAxIHx8ICFOdW1iZXIuaXNJbnRlZ2VyKHBhZ2UpKVxuICAgICAgdGhyb3cgbmV3IFBhZ2luZ0Vycm9yKFxuICAgICAgICBcIlBhZ2UgbnVtYmVyIGNhbm5vdCBiZSB1bmRlciAxIGFuZCBtdXN0IGJlIGFuIGludGVnZXJcIlxuICAgICAgKTtcbiAgICBpZiAodHlwZW9mIHRoaXMuX3RvdGFsUGFnZXMgIT09IFwidW5kZWZpbmVkXCIgJiYgcGFnZSA+IHRoaXMuX3RvdGFsUGFnZXMpXG4gICAgICB0aHJvdyBuZXcgUGFnaW5nRXJyb3IoXG4gICAgICAgIGBPbmx5ICR7dGhpcy5fdG90YWxQYWdlc30gYXJlIGF2YWlsYWJsZS4gQ2Fubm90IGdvIHRvIHBhZ2UgJHtwYWdlfWBcbiAgICAgICk7XG4gICAgcmV0dXJuIHBhZ2U7XG4gIH1cblxuICBhYnN0cmFjdCBwYWdlKHBhZ2U/OiBudW1iZXIpOiBQcm9taXNlPFJbXT47XG59XG4iXX0=

package/lib/esm/query/Statement.d.ts

@@ -1,56 +1,91 @@
-import type { Constructor } from "@decaf-ts/decorator-validation";
-import { Model, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
-import { Executor, RawExecutor } from "../interfaces";
-import { StatementType } from "./constants";
-import { Clause } from "./Clause";
-import { Adapter } from "../persistence";
+import { type Constructor, Model } from "@decaf-ts/decorator-validation";
+import type { Executor, RawExecutor } from "../interfaces";
+import type { FromSelector, GroupBySelector, OrderBySelector, SelectSelector } from "./selectors";
+import { Condition } from "./Condition";
+import type { CountOption, DistinctOption, LimitOption, MaxOption, MinOption, OffsetOption, OrderAndGroupOption, SelectOption, WhereOption } from "./options";
+import { Paginatable } from "../interfaces/Paginatable";
 import { Paginator } from "./Paginator";
+import { Adapter } from "../persistence";
 /**
- * @summary Statement Class
- * @description holds all the clauses until they can be processed
+ * @description Base class for database query statements
+ * @summary Provides a foundation for building and executing database queries
  *
- * @param {ModelArg} [statement]
+ * This abstract class implements the query builder pattern for constructing
+ * database queries. It supports various query operations like select, from,
+ * where, orderBy, groupBy, limit, and offset. It also provides methods for
+ * executing queries and handling pagination.
  *
+ * @template Q - The query type specific to the database adapter
+ * @template M - The model type this statement operates on
+ * @template R - The return type of the query
+ * @param {Adapter<any, Q, any, any>} adapter - The database adapter to use for executing queries
  * @class Statement
- * @extends Model
- * @implements Executor
- * @implements RawExecutor
+ * @example
+ * // Create a statement to query users
+ * const statement = new SQLStatement(adapter);
+ * const users = await statement
+ *   .select()
+ *   .from(User)
+ *   .where(Condition.attribute("status").eq("active"))
+ *   .orderBy(["createdAt", "DESC"])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Use pagination
+ * const paginator = await statement
+ *   .select()
+ *   .from(User)
+ *   .paginate(20); // 20 users per page
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Statement
+ *   participant Adapter
+ *   participant Database
  *
- * @category Query
+ *   Client->>Statement: select()
+ *   Client->>Statement: from(Model)
+ *   Client->>Statement: where(condition)
+ *   Client->>Statement: orderBy([field, direction])
+ *   Client->>Statement: limit(value)
+ *   Client->>Statement: execute()
+ *   Statement->>Statement: build()
+ *   Statement->>Adapter: raw(query)
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Statement: return processed results
+ *   Statement-->>Client: return final results
  */
-export declare abstract class Statement<Q> extends Model implements Executor, RawExecutor<Q> {
-    protected clauses?: Clause<any>[];
+export declare abstract class Statement<Q, M extends Model, R> implements Executor<R>, RawExecutor<Q>, Paginatable<M, R, Q> {
     protected adapter: Adapter<any, Q, any, any>;
-    protected target?: Constructor<any>;
-    protected fullRecord: boolean;
-    protected type?: string;
-    protected constructor(db: Adapter<any, Q, any, any>);
-    protected build(): Q;
-    /**
-     * @inheritDoc
-     */
-    execute<Y>(): Promise<Y>;
-    /**
-     * @inheritDoc
-     */
-    abstract paginate<Y>(size: number): Promise<Paginator<Y, Q>>;
-    raw<R>(rawInput: Q, ...args: any[]): Promise<R>;
-    /**
-     * @inheritDoc
-     */
-    hasErrors(...exceptions: string[]): ModelErrorDefinition | undefined;
-    /**
-     * @summary Adds a clause to the Statement
-     * @param {Clause} clause
-     */
-    addClause(clause: Clause<Q>): void;
-    getAdapter(): Adapter<any, Q, any, any>;
-    /**
-     * @summary Defines the output class (when existing)
-     * @param {Constructor} clazz
-     */
-    setTarget(clazz: Constructor<any>): void;
-    getTarget(): Constructor<any>;
-    setFullRecord(): void;
-    setMode(type: StatementType): void;
+    protected readonly selectSelector?: SelectSelector<M>[];
+    protected distinctSelector?: SelectSelector<M>;
+    protected maxSelector?: SelectSelector<M>;
+    protected minSelector?: SelectSelector<M>;
+    protected countSelector?: SelectSelector<M>;
+    protected fromSelector: Constructor<M>;
+    protected whereCondition?: Condition<M>;
+    protected orderBySelector?: OrderBySelector<M>;
+    protected groupBySelector?: GroupBySelector<M>;
+    protected limitSelector?: number;
+    protected offsetSelector?: number;
+    protected constructor(adapter: Adapter<any, Q, any, any>);
+    select<S extends readonly SelectSelector<M>[]>(): SelectOption<M, M[]>;
+    select<S extends readonly SelectSelector<M>[]>(selector: readonly [...S]): SelectOption<M, Pick<M, S[number]>[]>;
+    distinct<S extends SelectSelector<M>>(selector: S): DistinctOption<M, M[S][]>;
+    max<S extends SelectSelector<M>>(selector: S): MaxOption<M, M[S]>;
+    min<S extends SelectSelector<M>>(selector: S): MinOption<M, M[S]>;
+    count<S extends SelectSelector<M>>(selector?: S): CountOption<M, number>;
+    from(selector: FromSelector<M>): WhereOption<M, R>;
+    where(condition: Condition<M>): OrderAndGroupOption<M, R>;
+    orderBy(selector: OrderBySelector<M>): LimitOption<M, R> & OffsetOption<R>;
+    groupBy(selector: GroupBySelector<M>): LimitOption<M, R>;
+    limit(value: number): OffsetOption<R>;
+    offset(value: number): Executor<R>;
+    execute(): Promise<R>;
+    raw<R>(rawInput: Q): Promise<R>;
+    protected abstract build(): Q;
+    protected abstract parseCondition(condition: Condition<M>): Q;
+    abstract paginate(size: number): Promise<Paginator<M, R, Q>>;
 }