pg-query-sdk 1.0.0 → 1.0.2

package/dist/esm/builders/QueryBuilder.js

@@ -1,55 +1,143 @@
 import ParamContext from '../core/ParamContext';
 import ConditionBuilder from './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.
+ */
 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.
+     */
     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(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.
+     * @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(', ')
@@ -70,6 +158,11 @@ 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.
+     * @throws Error if no QueryExecutor is provided.
+     */
     async execute() {
         if (!this.executor) {
             throw new Error('No QueryExecutor provided');

package/dist/esm/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/esm/core/Database.js

@@ -2,16 +2,33 @@ import PostgresDialect from '../dialects/PostgresDialect';
 import QueryExecutor from './QueryExecutor';
 import QueryBuilder from '../query/QueryBuilder';
 import TransactionManager from './TransactionManager';
+/**
+ * Represents a database connection and provides methods for querying and managing transactions.
+ */
 export default class Database {
+    /**
+     * Creates an instance of the Database.
+     * @param options - The options for the database connection.
+     */
     constructor(options) {
         this.dialect = options.dialect ?? new PostgresDialect();
         this.executor = new QueryExecutor(options);
         this.transactionManager = new TransactionManager(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(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(undefined, trxClient);
@@ -24,9 +41,18 @@ export default 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/esm/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/esm/core/ParamContext.js

@@ -1,12 +1,28 @@
+/**
+ * Manages parameters for SQL queries, ensuring proper dialect-specific placeholders.
+ */
 export default 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/esm/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/esm/core/QueryExecutor.js

@@ -1,5 +1,13 @@
 import { Pool } from 'pg';
+/**
+ * Executes database queries using a PostgreSQL pool or client.
+ */
 export default 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;
@@ -13,6 +21,13 @@ export default 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);
@@ -22,12 +37,23 @@ export default 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/esm/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>;
 }

package/dist/esm/core/TransactionManager.js

@@ -1,7 +1,20 @@
+/**
+ * Manages database transactions, providing a method to execute a callback within a transaction.
+ */
 export default class TransactionManager {
+    /**
+     * Creates an instance of TransactionManager.
+     * @param pool - The PostgreSQL connection pool to use for transactions.
+     */
     constructor(pool) {
         this.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.
+     */
     async transaction(callback) {
         const client = await this.pool.connect();
         try {

package/dist/esm/core/UnitOfWork.d.ts

@@ -1,10 +1,29 @@
 import Repository from "../orm/Repository";
+/**
+ * Manages a list of new, dirty, and removed entities for transactional operations.
+ */
 export default class UnitOfWork {
     private newEntities;
     private dirtyEntities;
     private removedEntities;
+    /**
+     * Registers an entity as new, to be inserted on commit.
+     * @param entity - The entity to register.
+     */
     registerNew(entity: any): void;
+    /**
+     * Registers an entity as dirty, to be updated on commit.
+     * @param entity - The entity to register.
+     */
     registerDirty(entity: any): void;
+    /**
+     * Registers an entity as removed, to be deleted on commit.
+     * @param entity - The entity to register.
+     */
     registerRemoved(entity: any): void;
+    /**
+     * Commits all registered changes (insertions, updates, deletions) using the provided repository.
+     * @param repository - The repository to use for committing changes.
+     */
     commit(repository: Repository<any>): Promise<void>;
 }

package/dist/esm/core/UnitOfWork.js

@@ -1,18 +1,37 @@
+/**
+ * Manages a list of new, dirty, and removed entities for transactional operations.
+ */
 export default class UnitOfWork {
     constructor() {
         this.newEntities = [];
         this.dirtyEntities = [];
         this.removedEntities = [];
     }
+    /**
+     * Registers an entity as new, to be inserted on commit.
+     * @param entity - The entity to register.
+     */
     registerNew(entity) {
         this.newEntities.push(entity);
     }
+    /**
+     * Registers an entity as dirty, to be updated on commit.
+     * @param entity - The entity to register.
+     */
     registerDirty(entity) {
         this.dirtyEntities.push(entity);
     }
+    /**
+     * Registers an entity as removed, to be deleted on commit.
+     * @param entity - The entity to register.
+     */
     registerRemoved(entity) {
         this.removedEntities.push(entity);
     }
+    /**
+     * Commits all registered changes (insertions, updates, deletions) using the provided repository.
+     * @param repository - The repository to use for committing changes.
+     */
     async commit(repository) {
         for (const e of this.newEntities)
             await repository.insert(e);

package/dist/esm/dialects/Dialect.d.ts

@@ -1,4 +1,17 @@
+/**
+ * Defines the interface for a database dialect, providing methods for placeholder generation and identifier wrapping.
+ */
 export interface Dialect {
+    /**
+     * Generates a parameter placeholder for the given index.
+     * @param index - The index of the parameter.
+     * @returns The dialect-specific parameter placeholder.
+     */
     placeholder(index: number): string;
+    /**
+     * Wraps an identifier (e.g., table name, column name) with dialect-specific quoting.
+     * @param identifier - The identifier to wrap.
+     * @returns The wrapped identifier.
+     */
     wrapIdentifier(identifier: string): string;
 }

package/dist/esm/dialects/MysqlDialect.d.ts

@@ -1,5 +1,17 @@
 import { Dialect } from "./Dialect";
+/**
+ * Implements the Dialect interface for MySQL, providing MySQL-specific placeholder and identifier wrapping.
+ */
 export default class MysqlDialect implements Dialect {
+    /**
+     * Returns a MySQL-specific parameter placeholder '?'.
+     * @returns The string '?'.
+     */
     placeholder(): string;
+    /**
+     * Wraps a MySQL identifier with backticks.
+     * @param id - The identifier to wrap.
+     * @returns The backtick-wrapped identifier.
+     */
     wrapIdentifier(id: string): string;
 }

package/dist/esm/dialects/MysqlDialect.js

@@ -1,7 +1,19 @@
+/**
+ * Implements the Dialect interface for MySQL, providing MySQL-specific placeholder and identifier wrapping.
+ */
 export default class MysqlDialect {
+    /**
+     * Returns a MySQL-specific parameter placeholder '?'.
+     * @returns The string '?'.
+     */
     placeholder() {
         return '?';
     }
+    /**
+     * Wraps a MySQL identifier with backticks.
+     * @param id - The identifier to wrap.
+     * @returns The backtick-wrapped identifier.
+     */
     wrapIdentifier(id) {
         return `\`${id}\``;
     }

package/dist/esm/dialects/PostgresDialect.d.ts

@@ -1,5 +1,18 @@
 import { Dialect } from "./Dialect";
+/**
+ * Implements the Dialect interface for PostgreSQL, providing PostgreSQL-specific placeholder and identifier wrapping.
+ */
 export default class PostgresDialect implements Dialect {
+    /**
+     * Returns a PostgreSQL-specific parameter placeholder (e.g., '$1', '$2').
+     * @param index - The index of the parameter.
+     * @returns The dollar-prefixed, indexed placeholder.
+     */
     placeholder(index: number): string;
+    /**
+     * Wraps a PostgreSQL identifier with double quotes.
+     * @param id - The identifier to wrap.
+     * @returns The double-quoted identifier.
+     */
     wrapIdentifier(id: string): string;
 }

package/dist/esm/dialects/PostgresDialect.js

@@ -1,7 +1,20 @@
+/**
+ * Implements the Dialect interface for PostgreSQL, providing PostgreSQL-specific placeholder and identifier wrapping.
+ */
 export default class PostgresDialect {
+    /**
+     * Returns a PostgreSQL-specific parameter placeholder (e.g., '$1', '$2').
+     * @param index - The index of the parameter.
+     * @returns The dollar-prefixed, indexed placeholder.
+     */
     placeholder(index) {
         return `$${index}`;
     }
+    /**
+     * Wraps a PostgreSQL identifier with double quotes.
+     * @param id - The identifier to wrap.
+     * @returns The double-quoted identifier.
+     */
     wrapIdentifier(id) {
         return `"${id}"`;
     }

package/dist/esm/index.d.ts

@@ -1,7 +1,35 @@
+/**
+ * Re-exports the QueryExecutor class from the core module.
+ * @module QueryExecutor
+ */
 export { default as QueryExecutor } from './core/QueryExecutor';
+/**
+ * Re-exports the QueryBuilder class from the builders module.
+ * @module QueryBuilder
+ */
 export { default as QueryBuilder } from './builders/QueryBuilder';
+/**
+ * Re-exports the ConditionBuilder class from the builders module.
+ * @module ConditionBuilder
+ */
 export { default as ConditionBuilder } from './builders/ConditionBuilder';
+/**
+ * Re-exports the Database class from the core module.
+ * @module Database
+ */
 export { default as Database } from './core/Database';
+/**
+ * Re-exports the TransactionManager class from the core module.
+ * @module TransactionManager
+ */
 export { default as TransactionManager } from './core/TransactionManager';
+/**
+ * Re-exports the PostgresDialect class from the dialects module.
+ * @module PostgresDialect
+ */
 export { default as PostgresDialect } from './dialects/PostgresDialect';
+/**
+ * Re-exports the Repository class from the orm module.
+ * @module Repository
+ */
 export { default as Repository } from './orm/Repository';

package/dist/esm/index.js

@@ -1,7 +1,35 @@
+/**
+ * Re-exports the QueryExecutor class from the core module.
+ * @module QueryExecutor
+ */
 export { default as QueryExecutor } from './core/QueryExecutor';
+/**
+ * Re-exports the QueryBuilder class from the builders module.
+ * @module QueryBuilder
+ */
 export { default as QueryBuilder } from './builders/QueryBuilder';
+/**
+ * Re-exports the ConditionBuilder class from the builders module.
+ * @module ConditionBuilder
+ */
 export { default as ConditionBuilder } from './builders/ConditionBuilder';
+/**
+ * Re-exports the Database class from the core module.
+ * @module Database
+ */
 export { default as Database } from './core/Database';
+/**
+ * Re-exports the TransactionManager class from the core module.
+ * @module TransactionManager
+ */
 export { default as TransactionManager } from './core/TransactionManager';
+/**
+ * Re-exports the PostgresDialect class from the dialects module.
+ * @module PostgresDialect
+ */
 export { default as PostgresDialect } from './dialects/PostgresDialect';
+/**
+ * Re-exports the Repository class from the orm module.
+ * @module Repository
+ */
 export { default as Repository } from './orm/Repository';