pg-query-sdk 1.0.0 → 1.0.2

package/dist/cjs/builders/ConditionBuilder.d.ts

@@ -1,11 +1,45 @@
 import ParamContext from "../core/ParamContext";
+/**
+ * A builder for constructing SQL WHERE and HAVING clauses.
+ * This builder is specifically designed for the `builders` directory and might have a different scope or feature set
+ * compared to other ConditionBuilder implementations in the project.
+ */
 export default class ConditionBuilder {
     private ctx;
     private conditions;
+    /**
+     * Creates an instance of ConditionBuilder.
+     * @param ctx - The ParamContext to manage query parameters.
+     */
     constructor(ctx: ParamContext);
+    /**
+     * Adds one or more WHERE conditions based on an object.
+     * @param obj - An object where keys are column names and values are the desired values.
+     * @returns The current ConditionBuilder instance.
+     */
     where(obj: Record<string, any>): this;
+    /**
+     * Adds a raw SQL expression to the conditions.
+     * @param expression - The raw SQL expression.
+     * @returns The current ConditionBuilder instance.
+     */
     raw(expression: string): this;
+    /**
+     * Adds a group of conditions connected by AND.
+     * @param callback - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     andGroup(callback: (qb: ConditionBuilder) => void): this;
+    /**
+     * Adds a group of conditions connected by OR.
+     * @param callback - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     orGroup(callback: (qb: ConditionBuilder) => void): this;
+    /**
+     * Builds the SQL condition string.
+     * @param prefix - The prefix for the condition (e.g., 'WHERE', 'HAVING'). Defaults to 'WHERE'.
+     * @returns The built SQL condition string, or an empty string if no conditions were added.
+     */
     build(prefix?: string): string;
 }

package/dist/cjs/builders/ConditionBuilder.js

@@ -1,10 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A builder for constructing SQL WHERE and HAVING clauses.
+ * This builder is specifically designed for the `builders` directory and might have a different scope or feature set
+ * compared to other ConditionBuilder implementations in the project.
+ */
 class ConditionBuilder {
+    /**
+     * Creates an instance of ConditionBuilder.
+     * @param ctx - The ParamContext to manage query parameters.
+     */
     constructor(ctx) {
         this.ctx = ctx;
         this.conditions = [];
     }
+    /**
+     * Adds one or more WHERE conditions based on an object.
+     * @param obj - An object where keys are column names and values are the desired values.
+     * @returns The current ConditionBuilder instance.
+     */
     where(obj) {
         Object.entries(obj).forEach(([key, value]) => {
             const placeholder = this.ctx.add(value);
@@ -12,10 +26,20 @@ class ConditionBuilder {
         });
         return this;
     }
+    /**
+     * Adds a raw SQL expression to the conditions.
+     * @param expression - The raw SQL expression.
+     * @returns The current ConditionBuilder instance.
+     */
     raw(expression) {
         this.conditions.push(expression);
         return this;
     }
+    /**
+     * Adds a group of conditions connected by AND.
+     * @param callback - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     andGroup(callback) {
         const nested = new ConditionBuilder(this.ctx);
         callback(nested);
@@ -25,6 +49,11 @@ class ConditionBuilder {
         }
         return this;
     }
+    /**
+     * Adds a group of conditions connected by OR.
+     * @param callback - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     orGroup(callback) {
         const nested = new ConditionBuilder(this.ctx);
         callback(nested);
@@ -34,6 +63,11 @@ class ConditionBuilder {
         }
         return this;
     }
+    /**
+     * Builds the SQL condition string.
+     * @param prefix - The prefix for the condition (e.g., 'WHERE', 'HAVING'). Defaults to 'WHERE'.
+     * @returns The built SQL condition string, or an empty string if no conditions were added.
+     */
     build(prefix = 'WHERE') {
         if (!this.conditions.length)
             return '';

package/dist/cjs/builders/QueryBuilder.d.ts

@@ -1,31 +1,142 @@
 import QueryExecutor from '../core/QueryExecutor';
 import { Dialect } from "../dialects/Dialect";
+/**
+ * A fluent SQL query builder for constructing and executing database queries.
+ * This builder is specifically designed for the `builders` directory and might have a different scope or feature set
+ * compared to other QueryBuilder implementations in the project.
+ * @template T The expected type of the results.
+ */
 export default class QueryBuilder<T = any> {
     private executor;
+    /**
+     * The fields to be selected in the query.
+     */
     private fields;
+    /**
+     * The join clauses for the query.
+     */
     private joins;
+    /**
+     * The fields to group by.
+     */
     private groupByFields;
+    /**
+     * The fields to order by.
+     */
     private orderByFields;
+    /**
+     * The maximum number of rows to return.
+     */
     private limitCount?;
+    /**
+     * The number of rows to skip.
+     */
     private offsetCount?;
+    /**
+     * Common Table Expressions (CTEs) defined for the query.
+     */
     private ctes;
+    /**
+     * The FROM clause of the query.
+     */
     private fromClause;
+    /**
+     * The condition builder for WHERE clauses.
+     */
     private condition;
+    /**
+     * The condition builder for HAVING clauses.
+     */
     private havingCondition;
+    /**
+     * The parameter context for managing query parameters.
+     */
     private ctx;
+    /**
+     * Creates an instance of QueryBuilder.
+     * @param table - The name of the table to query from.
+     * @param executor - The query executor to use.
+     * @param dialect - The database dialect to use.
+     */
     constructor(table: string, executor: QueryExecutor, dialect: Dialect);
+    /**
+     * Specifies the fields to select.
+     * @param fields - An array of field names.
+     * @returns The current QueryBuilder instance.
+     */
     select(fields: string[]): this;
+    /**
+     * Adds a join clause to the query.
+     * @param type - The type of join (INNER, LEFT, RIGHT).
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     private addJoin;
+    /**
+     * Adds an INNER JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     join(table: string, localKey: string, foreignKey: string): this;
+    /**
+     * Adds a LEFT JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     leftJoin(table: string, localKey: string, foreignKey: string): this;
+    /**
+     * Adds a RIGHT JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     rightJoin(table: string, localKey: string, foreignKey: string): this;
+    /**
+     * Sets the FROM clause to a subquery.
+     * @param sub - The QueryBuilder instance representing the subquery.
+     * @param alias - The alias for the subquery.
+     * @returns The current QueryBuilder instance.
+     */
     fromSubquery(sub: QueryBuilder, alias: string): this;
+    /**
+     * Adds WHERE conditions based on an object.
+     * @param obj - An object where keys are column names and values are the desired values.
+     * @returns The current QueryBuilder instance.
+     */
     where(obj: Record<string, any>): this;
+    /**
+     * Adds a WHERE condition with a subquery.
+     * @param column - The column to apply the condition to.
+     * @param operator - The operator ('IN' or 'NOT IN').
+     * @param sub - The QueryBuilder instance representing the subquery.
+     * @returns The current QueryBuilder instance.
+     */
     whereSub(column: string, operator: 'IN' | 'NOT IN', sub: QueryBuilder): this;
+    /**
+     * Sets the LIMIT for the query.
+     * @param limit - The maximum number of rows to return.
+     * @returns The current QueryBuilder instance.
+     */
     limit(limit: number): this;
+    /**
+     * Builds the SQL query string and its parameters without executing it.
+     * @returns An object containing the SQL query string and an array of parameters.
+     */
     build(): {
         query: string;
         params: any[];
     };
-    execute(): Promise<any[]>;
+    /**
+     * Executes the built SQL query and returns the results.
+     * @returns A Promise that resolves to an array of results of type T.
+     * @throws Error if no QueryExecutor is provided.
+     */
+    execute(): Promise<T[]>;
 }

package/dist/cjs/builders/QueryBuilder.js

@@ -5,56 +5,144 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const ParamContext_1 = __importDefault(require("../core/ParamContext"));
 const ConditionBuilder_1 = __importDefault(require("./ConditionBuilder"));
+/**
+ * A fluent SQL query builder for constructing and executing database queries.
+ * This builder is specifically designed for the `builders` directory and might have a different scope or feature set
+ * compared to other QueryBuilder implementations in the project.
+ * @template T The expected type of the results.
+ */
 class QueryBuilder {
+    /**
+     * Creates an instance of QueryBuilder.
+     * @param table - The name of the table to query from.
+     * @param executor - The query executor to use.
+     * @param dialect - The database dialect to use.
+     */
     constructor(table, executor, dialect) {
         this.executor = executor;
+        /**
+         * The fields to be selected in the query.
+         */
         this.fields = [];
+        /**
+         * The join clauses for the query.
+         */
         this.joins = [];
+        /**
+         * The fields to group by.
+         */
         this.groupByFields = [];
+        /**
+         * The fields to order by.
+         */
         this.orderByFields = [];
-        this.ctes = [];
+        /**
+         * Common Table Expressions (CTEs) defined for the query.
+         */
+        this.ctes = []; // TODO: Define a proper type for CTEs
         this.fromClause = table;
         this.ctx = new ParamContext_1.default(dialect);
         this.condition = new ConditionBuilder_1.default(this.ctx);
         this.havingCondition = new ConditionBuilder_1.default(this.ctx);
     }
+    /**
+     * Specifies the fields to select.
+     * @param fields - An array of field names.
+     * @returns The current QueryBuilder instance.
+     */
     select(fields) {
         this.fields = fields;
         return this;
     }
+    /**
+     * Adds a join clause to the query.
+     * @param type - The type of join (INNER, LEFT, RIGHT).
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     addJoin(type, table, localKey, foreignKey) {
         this.joins.push(`${type} JOIN ${table} ON ${localKey} = ${foreignKey}`);
         return this;
     }
+    /**
+     * Adds an INNER JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     join(table, localKey, foreignKey) {
         return this.addJoin('INNER', table, localKey, foreignKey);
     }
+    /**
+     * Adds a LEFT JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     leftJoin(table, localKey, foreignKey) {
         return this.addJoin('LEFT', table, localKey, foreignKey);
     }
+    /**
+     * Adds a RIGHT JOIN clause.
+     * @param table - The table to join.
+     * @param localKey - The local key for the join condition.
+     * @param foreignKey - The foreign key for the join condition.
+     * @returns The current QueryBuilder instance.
+     */
     rightJoin(table, localKey, foreignKey) {
         return this.addJoin('RIGHT', table, localKey, foreignKey);
     }
+    /**
+     * Sets the FROM clause to a subquery.
+     * @param sub - The QueryBuilder instance representing the subquery.
+     * @param alias - The alias for the subquery.
+     * @returns The current QueryBuilder instance.
+     */
     fromSubquery(sub, alias) {
         const { query, params } = sub.build();
         params.forEach(p => this.ctx.add(p));
         this.fromClause = `(${query}) AS ${alias}`;
         return this;
     }
+    /**
+     * Adds WHERE conditions based on an object.
+     * @param obj - An object where keys are column names and values are the desired values.
+     * @returns The current QueryBuilder instance.
+     */
     where(obj) {
         this.condition.where(obj);
         return this;
     }
+    /**
+     * Adds a WHERE condition with a subquery.
+     * @param column - The column to apply the condition to.
+     * @param operator - The operator ('IN' or 'NOT IN').
+     * @param sub - The QueryBuilder instance representing the subquery.
+     * @returns The current QueryBuilder instance.
+     */
     whereSub(column, operator, sub) {
         const { query, params } = sub.build();
         params.forEach(p => this.ctx.add(p));
         this.condition.raw(`${column} ${operator} (${query})`);
         return this;
     }
+    /**
+     * Sets the LIMIT for the query.
+     * @param limit - The maximum number of rows to return.
+     * @returns The current QueryBuilder instance.
+     */
     limit(limit) {
         this.limitCount = limit;
         return this;
     }
+    /**
+     * Builds the SQL query string and its parameters without executing it.
+     * @returns An object containing the SQL query string and an array of parameters.
+     */
     build() {
         const select = this.fields.length
             ? this.fields.join(', ')
@@ -75,6 +163,11 @@ class QueryBuilder {
             params: this.ctx.getParams()
         };
     }
+    /**
+     * Executes the built SQL query and returns the results.
+     * @returns A Promise that resolves to an array of results of type T.
+     * @throws Error if no QueryExecutor is provided.
+     */
     async execute() {
         if (!this.executor) {
             throw new Error('No QueryExecutor provided');

package/dist/cjs/core/Database.d.ts

@@ -6,15 +6,41 @@ interface DatabaseOptions {
     dialect?: Dialect;
     defaultCacheTTL?: number;
 }
+/**
+ * Represents a database connection and provides methods for querying and managing transactions.
+ */
 export default class Database {
     private executor;
     private dialect;
     private transactionManager;
     private defaultCacheTTL?;
+    /**
+     * Creates an instance of the Database.
+     * @param options - The options for the database connection.
+     */
     constructor(options: DatabaseOptions);
+    /**
+     * Creates a QueryBuilder for a specific table.
+     * @param name - The name of the table.
+     * @returns A QueryBuilder instance.
+     */
     table<T = any>(name: string): QueryBuilder<T>;
+    /**
+     * Executes a transaction.
+     * @param callback - The function to execute within the transaction. It receives a transactional Database instance.
+     * @returns The result of the callback function.
+     */
     transaction<T>(callback: (trxDb: Database) => Promise<T>): Promise<T>;
+    /**
+     * Sets the query executor.
+     * @param executor - The QueryExecutor instance to set.
+     */
     setExecutor(executor: QueryExecutor): void;
+    /**
+     * Creates a repository instance.
+     * @param RepoClass - The constructor of the repository class.
+     * @returns An instance of the repository.
+     */
     repository<R>(RepoClass: new (executor: QueryExecutor, dialect: Dialect) => R): R;
 }
 export {};

package/dist/cjs/core/Database.js

@@ -7,16 +7,33 @@ const PostgresDialect_1 = __importDefault(require("../dialects/PostgresDialect")
 const QueryExecutor_1 = __importDefault(require("./QueryExecutor"));
 const QueryBuilder_1 = __importDefault(require("../query/QueryBuilder"));
 const TransactionManager_1 = __importDefault(require("./TransactionManager"));
+/**
+ * Represents a database connection and provides methods for querying and managing transactions.
+ */
 class Database {
+    /**
+     * Creates an instance of the Database.
+     * @param options - The options for the database connection.
+     */
     constructor(options) {
         this.dialect = options.dialect ?? new PostgresDialect_1.default();
         this.executor = new QueryExecutor_1.default(options);
         this.transactionManager = new TransactionManager_1.default(this.executor.getPool());
         this.defaultCacheTTL = options.defaultCacheTTL;
     }
+    /**
+     * Creates a QueryBuilder for a specific table.
+     * @param name - The name of the table.
+     * @returns A QueryBuilder instance.
+     */
     table(name) {
         return new QueryBuilder_1.default(name, this.executor, this.dialect, this.defaultCacheTTL);
     }
+    /**
+     * Executes a transaction.
+     * @param callback - The function to execute within the transaction. It receives a transactional Database instance.
+     * @returns The result of the callback function.
+     */
     async transaction(callback) {
         return this.transactionManager.transaction(async (trxClient) => {
             const trxExecutor = new QueryExecutor_1.default(undefined, trxClient);
@@ -29,9 +46,18 @@ class Database {
             return callback(trxDb);
         });
     }
+    /**
+     * Sets the query executor.
+     * @param executor - The QueryExecutor instance to set.
+     */
     setExecutor(executor) {
         this.executor = executor;
     }
+    /**
+     * Creates a repository instance.
+     * @param RepoClass - The constructor of the repository class.
+     * @returns An instance of the repository.
+     */
     repository(RepoClass) {
         return new RepoClass(this.executor, this.dialect);
     }

package/dist/cjs/core/ParamContext.d.ts

@@ -1,8 +1,24 @@
 import { Dialect } from "../dialects/Dialect";
+/**
+ * Manages parameters for SQL queries, ensuring proper dialect-specific placeholders.
+ */
 export default class ParamContext {
     private dialect;
     private params;
+    /**
+     * Creates an instance of ParamContext.
+     * @param dialect - The dialect to use for generating parameter placeholders.
+     */
     constructor(dialect: Dialect);
+    /**
+     * Adds a value to the parameter list and returns its dialect-specific placeholder.
+     * @param value - The value to add.
+     * @returns The placeholder string for the added parameter.
+     */
     add(value: any): string;
+    /**
+     * Retrieves the list of accumulated parameters.
+     * @returns An array of parameters.
+     */
     getParams(): any[];
 }

package/dist/cjs/core/ParamContext.js

@@ -1,14 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Manages parameters for SQL queries, ensuring proper dialect-specific placeholders.
+ */
 class ParamContext {
+    /**
+     * Creates an instance of ParamContext.
+     * @param dialect - The dialect to use for generating parameter placeholders.
+     */
     constructor(dialect) {
         this.dialect = dialect;
         this.params = [];
     }
+    /**
+     * Adds a value to the parameter list and returns its dialect-specific placeholder.
+     * @param value - The value to add.
+     * @returns The placeholder string for the added parameter.
+     */
     add(value) {
         this.params.push(value);
         return this.dialect.placeholder(this.params.length);
     }
+    /**
+     * Retrieves the list of accumulated parameters.
+     * @returns An array of parameters.
+     */
     getParams() {
         return this.params;
     }

package/dist/cjs/core/QueryExecutor.d.ts

@@ -2,13 +2,39 @@ import { Pool, PoolClient, QueryResult } from 'pg';
 interface ExecutorOptions {
     connectionString: string;
 }
+/**
+ * Executes database queries using a PostgreSQL pool or client.
+ */
 export default class QueryExecutor {
     private pool?;
     private client?;
+    /**
+     * Creates an instance of QueryExecutor.
+     * @param options - Options for the executor, including the connection string.
+     * @param client - An optional PoolClient to use for queries (for transactions).
+     */
     constructor(options?: ExecutorOptions, client?: PoolClient);
+    /**
+     * Executes a SQL query.
+     * @param query - The SQL query string.
+     * @param params - An array of parameters for the query.
+     * @param cacheTTL - Time-to-live for caching (not currently used in this implementation).
+     * @returns A Promise that resolves to the QueryResult.
+     */
     execute(query: string, params: any[] | undefined, cacheTTL: number | undefined): Promise<QueryResult>;
+    /**
+     * Returns the underlying PostgreSQL Pool instance.
+     * @returns The Pool instance or undefined if not initialized with a connection string.
+     */
     getPool(): Pool | undefined;
+    /**
+     * Returns the underlying PostgreSQL PoolClient instance.
+     * @returns The PoolClient instance or undefined if not initialized with a client.
+     */
     getClient(): PoolClient | undefined;
+    /**
+     * Closes the database connection pool.
+     */
     close(): Promise<void>;
 }
 export {};

package/dist/cjs/core/QueryExecutor.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const pg_1 = require("pg");
+/**
+ * Executes database queries using a PostgreSQL pool or client.
+ */
 class QueryExecutor {
+    /**
+     * Creates an instance of QueryExecutor.
+     * @param options - Options for the executor, including the connection string.
+     * @param client - An optional PoolClient to use for queries (for transactions).
+     */
     constructor(options, client) {
         if (client) {
             this.client = client;
@@ -15,6 +23,13 @@ class QueryExecutor {
         }
         throw new Error('Invalid QueryExecutor initialization');
     }
+    /**
+     * Executes a SQL query.
+     * @param query - The SQL query string.
+     * @param params - An array of parameters for the query.
+     * @param cacheTTL - Time-to-live for caching (not currently used in this implementation).
+     * @returns A Promise that resolves to the QueryResult.
+     */
     async execute(query, params = [], cacheTTL) {
         if (this.client) {
             return this.client.query(query, params);
@@ -24,12 +39,23 @@ class QueryExecutor {
         }
         throw new Error('Executor not initialized');
     }
+    /**
+     * Returns the underlying PostgreSQL Pool instance.
+     * @returns The Pool instance or undefined if not initialized with a connection string.
+     */
     getPool() {
         return this.pool;
     }
+    /**
+     * Returns the underlying PostgreSQL PoolClient instance.
+     * @returns The PoolClient instance or undefined if not initialized with a client.
+     */
     getClient() {
         return this.client;
     }
+    /**
+     * Closes the database connection pool.
+     */
     async close() {
         if (this.pool) {
             await this.pool.end();

package/dist/cjs/core/TransactionManager.d.ts

@@ -1,6 +1,19 @@
 import { Pool, PoolClient } from 'pg';
+/**
+ * Manages database transactions, providing a method to execute a callback within a transaction.
+ */
 export default class TransactionManager {
     private pool;
+    /**
+     * Creates an instance of TransactionManager.
+     * @param pool - The PostgreSQL connection pool to use for transactions.
+     */
     constructor(pool: Pool);
+    /**
+     * Executes a given callback function within a database transaction.
+     * The transaction is committed if the callback succeeds, and rolled back if an error occurs.
+     * @param callback - The function to execute within the transaction. It receives a PoolClient instance.
+     * @returns A Promise that resolves to the result of the callback function.
+     */
     transaction<T>(callback: (trxClient: PoolClient) => Promise<T>): Promise<T>;
 }