pg-query-sdk 1.0.0 → 1.0.2

package/dist/esm/orm/Repository.d.ts

@@ -1,13 +1,47 @@
 import { QueryBuilder, QueryExecutor } from "../index";
 import { Dialect } from "../dialects/Dialect";
+/**
+ * Abstract base class for repositories, providing common database operations.
+ * @template T The type of the entity managed by the repository.
+ */
 export default abstract class Repository<T> {
     protected table: string;
     protected executor: QueryExecutor;
     protected dialect: Dialect;
+    /**
+     * Creates an instance of Repository.
+     * @param table - The name of the database table associated with this repository.
+     * @param executor - The QueryExecutor instance for executing queries.
+     * @param dialect - The Dialect instance for database-specific syntax.
+     */
     constructor(table: string, executor: QueryExecutor, dialect: Dialect);
+    /**
+     * Returns a new QueryBuilder instance for the repository's table.
+     * @returns A QueryBuilder instance.
+     */
     qb(): QueryBuilder<T>;
+    /**
+     * Finds an entity by its ID.
+     * @param id - The ID of the entity to find.
+     * @returns A Promise that resolves to the found entity or null if not found.
+     */
     findById(id: number): Promise<T | null>;
+    /**
+     * Inserts a new entity into the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to insert.
+     */
     insert(data: Partial<T>): Promise<void>;
+    /**
+     * Updates an existing entity in the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to update.
+     */
     update(data: Partial<T>): Promise<void>;
+    /**
+     * Deletes an entity from the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to delete (e.g., containing the ID).
+     */
     delete(data: Partial<T>): Promise<void>;
 }

package/dist/esm/orm/Repository.js

@@ -1,13 +1,32 @@
 import { QueryBuilder } from "../index";
+/**
+ * Abstract base class for repositories, providing common database operations.
+ * @template T The type of the entity managed by the repository.
+ */
 export default class Repository {
+    /**
+     * Creates an instance of Repository.
+     * @param table - The name of the database table associated with this repository.
+     * @param executor - The QueryExecutor instance for executing queries.
+     * @param dialect - The Dialect instance for database-specific syntax.
+     */
     constructor(table, executor, dialect) {
         this.table = table;
         this.executor = executor;
         this.dialect = dialect;
     }
+    /**
+     * Returns a new QueryBuilder instance for the repository's table.
+     * @returns A QueryBuilder instance.
+     */
     qb() {
         return new QueryBuilder(this.table, this.executor, this.dialect);
     }
+    /**
+     * Finds an entity by its ID.
+     * @param id - The ID of the entity to find.
+     * @returns A Promise that resolves to the found entity or null if not found.
+     */
     async findById(id) {
         const rows = await this.qb()
             .where({ id })
@@ -15,12 +34,27 @@ export default class Repository {
             .execute();
         return rows[0] ?? null;
     }
+    /**
+     * Inserts a new entity into the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to insert.
+     */
     async insert(data) {
         // implementação insert segura
     }
+    /**
+     * Updates an existing entity in the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to update.
+     */
     async update(data) {
         // implementação update segura
     }
+    /**
+     * Deletes an entity from the database.
+     * This method should be implemented by concrete repository classes.
+     * @param data - The partial entity data to delete (e.g., containing the ID).
+     */
     async delete(data) {
         // soft delete opcional
     }

package/dist/esm/query/ConditionBuilder.d.ts

@@ -1,11 +1,44 @@
 import ParamContext from '../core/ParamContext';
+/**
+ * A builder for constructing SQL WHERE and HAVING clauses.
+ */
 export default class ConditionBuilder {
     private ctx;
     private parts;
+    /**
+     * 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.
+     * Supports direct equality, `null` checks, and custom operators.
+     * @param obj - An object where keys are column names and values are the desired values or an object with `op` and `value`.
+     * @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 cb - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     andGroup(cb: (qb: ConditionBuilder) => void): this;
+    /**
+     * Adds a group of conditions connected by OR.
+     * @param cb - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     orGroup(cb: (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/query/ConditionBuilder.js

@@ -1,8 +1,21 @@
+/**
+ * A builder for constructing SQL WHERE and HAVING clauses.
+ */
 export default class ConditionBuilder {
+    /**
+     * Creates an instance of ConditionBuilder.
+     * @param ctx - The ParamContext to manage query parameters.
+     */
     constructor(ctx) {
         this.ctx = ctx;
         this.parts = [];
     }
+    /**
+     * Adds one or more WHERE conditions based on an object.
+     * Supports direct equality, `null` checks, and custom operators.
+     * @param obj - An object where keys are column names and values are the desired values or an object with `op` and `value`.
+     * @returns The current ConditionBuilder instance.
+     */
     where(obj) {
         Object.entries(obj).forEach(([key, value]) => {
             if (value === null) {
@@ -20,10 +33,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.parts.push(expression);
         return this;
     }
+    /**
+     * Adds a group of conditions connected by AND.
+     * @param cb - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     andGroup(cb) {
         const nested = new ConditionBuilder(this.ctx);
         cb(nested);
@@ -33,6 +56,11 @@ export default class ConditionBuilder {
         }
         return this;
     }
+    /**
+     * Adds a group of conditions connected by OR.
+     * @param cb - A callback function that receives a nested ConditionBuilder to define conditions within the group.
+     * @returns The current ConditionBuilder instance.
+     */
     orGroup(cb) {
         const nested = new ConditionBuilder(this.ctx);
         cb(nested);
@@ -43,6 +71,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.parts.length)
             return '';

package/dist/esm/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/esm/query/QueryBuilder.js

@@ -1,53 +1,138 @@
 import ParamContext from '../core/ParamContext';
 import ConditionBuilder from './ConditionBuilder';
+/**
+ * A fluent SQL query builder for constructing and executing database queries.
+ * @template T The expected type of the results.
+ */
 export default 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(this.dialect);
         this.condition = new ConditionBuilder(this.ctx);
         this.havingCondition = new ConditionBuilder(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);
@@ -57,36 +142,79 @@ export default 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];
@@ -98,6 +226,10 @@ export default 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) {
@@ -138,6 +270,10 @@ export default 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-query-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "PostgreSQL SDK with Query Builder and Executor",
   "main": "dist/cjs/index.js",
   "types": "dist/esm/index.d.ts",