pg-query-sdk 1.0.0 → 1.0.1

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

@@ -1,43 +1,197 @@
 import ConditionBuilder from './ConditionBuilder';
 import QueryExecutor from '../core/QueryExecutor';
 import { Dialect } from '../dialects/Dialect';
+/**
+ * A fluent SQL query builder for constructing and executing database queries.
+ * @template T The expected type of the results.
+ */
 export default class QueryBuilder<T = any> {
     private executor;
     private dialect;
     private cacheTTL?;
+    /**
+     * 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 parameter context for managing query parameters.
+     */
     private ctx;
+    /**
+     * The condition builder for WHERE clauses.
+     */
     private condition;
+    /**
+     * The condition builder for HAVING clauses.
+     */
     private havingCondition;
+    /**
+     * 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.
+     * @param cacheTTL - Optional time-to-live for query caching.
+     */
     constructor(table: string, executor: QueryExecutor, dialect: Dialect, cacheTTL?: number | 0 | undefined);
+    /**
+     * Specifies the fields to select.
+     * @param fields - An array of field names or keys of T.
+     * @returns The current QueryBuilder instance.
+     */
     select(fields: (keyof T | 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;
+    /**
+     * 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: Partial<T>): this;
+    /**
+     * Adds a raw WHERE expression.
+     * @param expression - The raw SQL expression for the WHERE clause.
+     * @returns The current QueryBuilder instance.
+     */
     whereRaw(expression: string): this;
+    /**
+     * Adds an AND group of conditions.
+     * @param cb - A callback function that receives a ConditionBuilder to define conditions within the group.
+     * @returns The current QueryBuilder instance.
+     */
     andGroup(cb: (qb: ConditionBuilder) => void): this;
+    /**
+     * Adds an OR group of conditions.
+     * @param cb - A callback function that receives a ConditionBuilder to define conditions within the group.
+     * @returns The current QueryBuilder instance.
+     */
     orGroup(cb: (qb: ConditionBuilder) => void): this;
+    /**
+     * Specifies fields to group by.
+     * @param fields - A single field name or an array of field names.
+     * @returns The current QueryBuilder instance.
+     */
     groupBy(fields: string | string[]): this;
+    /**
+     * Adds HAVING 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.
+     */
     having(obj: Record<string, any>): this;
+    /**
+     * Adds a raw HAVING expression.
+     * @param expr - The raw SQL expression for the HAVING clause.
+     * @returns The current QueryBuilder instance.
+     */
     havingRaw(expr: string): this;
+    /**
+     * Specifies the order by clause.
+     * @param column - The column to order by.
+     * @param direction - The order direction ('ASC' or 'DESC'). Defaults to 'ASC'.
+     * @returns The current QueryBuilder instance.
+     */
     orderBy(column: string, direction?: 'ASC' | 'DESC'): this;
+    /**
+     * Sets the LIMIT for the query.
+     * @param value - The maximum number of rows to return.
+     * @returns The current QueryBuilder instance.
+     */
     limit(value: number): this;
+    /**
+     * Sets the OFFSET for the query.
+     * @param value - The number of rows to skip.
+     * @returns The current QueryBuilder instance.
+     */
     offset(value: number): this;
+    /**
+     * Adds a Common Table Expression (CTE) to the query.
+     * @param name - The name of the CTE.
+     * @param subQuery - The QueryBuilder instance representing the subquery for the CTE.
+     * @param recursive - Whether the CTE is recursive. Defaults to false.
+     * @returns The current QueryBuilder instance.
+     */
     with(name: string, subQuery: QueryBuilder<any>, recursive?: boolean): 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<any>, alias: string): this;
+    /**
+     * Creates a clone of the current QueryBuilder instance.
+     * @returns A new QueryBuilder instance with the same state.
+     */
     clone(): QueryBuilder<T>;
+    /**
+     * 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[];
     };
+    /**
+     * Executes the built SQL query and returns the results.
+     * @returns A Promise that resolves to an array of results of type T.
+     */
     execute(): Promise<T[]>;
 }

package/dist/cjs/query/QueryBuilder.js

@@ -5,54 +5,139 @@ 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.
+ * @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.
+     * @param cacheTTL - Optional time-to-live for query caching.
+     */
     constructor(table, executor, dialect, cacheTTL) {
         this.executor = executor;
         this.dialect = dialect;
         this.cacheTTL = cacheTTL;
+        /**
+         * 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 = [];
+        /**
+         * Common Table Expressions (CTEs) defined for the query.
+         */
         this.ctes = [];
         this.fromClause = table;
         this.ctx = new ParamContext_1.default(this.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 or keys of T.
+     * @returns The current QueryBuilder instance.
+     */
     select(fields) {
         this.fields = fields.map(String);
         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);
     }
+    /**
+     * 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 raw WHERE expression.
+     * @param expression - The raw SQL expression for the WHERE clause.
+     * @returns The current QueryBuilder instance.
+     */
     whereRaw(expression) {
         this.condition.raw(expression);
         return this;
     }
+    /**
+     * Adds an AND group of conditions.
+     * @param cb - A callback function that receives a ConditionBuilder to define conditions within the group.
+     * @returns The current QueryBuilder instance.
+     */
     andGroup(cb) {
         this.condition.andGroup(cb);
         return this;
     }
+    /**
+     * Adds an OR group of conditions.
+     * @param cb - A callback function that receives a ConditionBuilder to define conditions within the group.
+     * @returns The current QueryBuilder instance.
+     */
     orGroup(cb) {
         this.condition.orGroup(cb);
         return this;
     }
+    /**
+     * Specifies fields to group by.
+     * @param fields - A single field name or an array of field names.
+     * @returns The current QueryBuilder instance.
+     */
     groupBy(fields) {
         if (Array.isArray(fields)) {
             this.groupByFields.push(...fields);
@@ -62,36 +147,79 @@ class QueryBuilder {
         }
         return this;
     }
+    /**
+     * Adds HAVING 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.
+     */
     having(obj) {
         this.havingCondition.where(obj);
         return this;
     }
+    /**
+     * Adds a raw HAVING expression.
+     * @param expr - The raw SQL expression for the HAVING clause.
+     * @returns The current QueryBuilder instance.
+     */
     havingRaw(expr) {
         this.havingCondition.raw(expr);
         return this;
     }
+    /**
+     * Specifies the order by clause.
+     * @param column - The column to order by.
+     * @param direction - The order direction ('ASC' or 'DESC'). Defaults to 'ASC'.
+     * @returns The current QueryBuilder instance.
+     */
     orderBy(column, direction = 'ASC') {
         this.orderByFields.push(`${column} ${direction}`);
         return this;
     }
+    /**
+     * Sets the LIMIT for the query.
+     * @param value - The maximum number of rows to return.
+     * @returns The current QueryBuilder instance.
+     */
     limit(value) {
         this.limitCount = value;
         return this;
     }
+    /**
+     * Sets the OFFSET for the query.
+     * @param value - The number of rows to skip.
+     * @returns The current QueryBuilder instance.
+     */
     offset(value) {
         this.offsetCount = value;
         return this;
     }
+    /**
+     * Adds a Common Table Expression (CTE) to the query.
+     * @param name - The name of the CTE.
+     * @param subQuery - The QueryBuilder instance representing the subquery for the CTE.
+     * @param recursive - Whether the CTE is recursive. Defaults to false.
+     * @returns The current QueryBuilder instance.
+     */
     with(name, subQuery, recursive = false) {
         this.ctes.push({ name, query: subQuery, recursive });
         return 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, alias) {
         const { query, params } = sub.build();
         params.forEach(p => this.ctx.add(p));
         this.fromClause = `(${query}) AS ${alias}`;
         return this;
     }
+    /**
+     * Creates a clone of the current QueryBuilder instance.
+     * @returns A new QueryBuilder instance with the same state.
+     */
     clone() {
         const qb = new QueryBuilder(this.fromClause, this.executor, this.dialect, this.cacheTTL);
         qb.fields = [...this.fields];
@@ -103,6 +231,10 @@ class QueryBuilder {
         qb.ctes = [...this.ctes];
         return qb;
     }
+    /**
+     * 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() {
         let query = '';
         if (this.ctes.length) {
@@ -143,6 +275,10 @@ 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.
+     */
     async execute() {
         const { query, params } = this.build();
         const result = await this.executor.execute(query, params, this.cacheTTL);

package/dist/esm/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/esm/builders/ConditionBuilder.js

@@ -1,8 +1,22 @@
+/**
+ * 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 {
+    /**
+     * 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);
@@ -10,10 +24,20 @@ export default 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);
@@ -23,6 +47,11 @@ export default 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);
@@ -32,6 +61,11 @@ export default 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/esm/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[]>;
 }