blendsdk 5.33.0

package/dist/dbcore/query-dataservice.d.ts

@@ -0,0 +1,144 @@
+import { QueryBuilder } from '../expression/index.js';
+import { Database } from './database.js';
+import { DataServiceBase } from './dataservice-base.js';
+/**
+ * Function type for building query expressions with type-safe column references.
+ * Accepts a QueryBuilder instance and configures the query conditions.
+ *
+ * @template T - The type representing the table/relation structure for type-safe column access
+ * @export
+ */
+export type ExpressionBuilder<T = any> = (q: QueryBuilder<T>) => void;
+/**
+ * Promise type alias for a set of partial records from a relation.
+ * Used as the return type for query methods that return multiple records.
+ *
+ * @template RecordType - The type of records in the result set
+ * @export
+ */
+export type PromiseOfRecordSet<RecordType> = Promise<Partial<RecordType>[]>;
+/**
+ * Promise type alias for a single partial record from a relation.
+ * Used as the return type for query methods that return a single record.
+ *
+ * @template RecordType - The type of the record to return
+ * @export
+ */
+export type PromiseOfRecord<RecordType> = Promise<Partial<RecordType>>;
+/**
+ * Abstract base class for read-only data services that query a single database relation.
+ * Provides common query patterns like findById, findByExpression, and findAll.
+ *
+ * Uses the expression builder from @blendsdk/expression for type-safe query construction
+ * and delegates execution to the FromStatement builder.
+ *
+ * To create a concrete data service, either extend this class or use the
+ * `createQueryService()` factory function.
+ *
+ * @export
+ * @abstract
+ * @class QueryDataService
+ * @extends {DataServiceBase}
+ * @template RelationType - The type representing the database relation/table structure
+ *
+ * @example
+ * // Using the factory function
+ * const UserService = createQueryService<User>('users', 'id');
+ * const service = new UserService(db);
+ * const user = await service.findById(123);
+ *
+ * @example
+ * // Extending the class
+ * class UserService extends QueryDataService<User> {
+ *   constructor(db: Database) {
+ *     super('users', 'id', db);
+ *   }
+ * }
+ */
+export declare abstract class QueryDataService<RelationType> extends DataServiceBase {
+    /**
+     * The name of the database relation (table or view) this service queries.
+     *
+     * @type {string}
+     * @memberof QueryDataService
+     */
+    relation: string;
+    /**
+     * The name of the primary key column used for findById queries.
+     *
+     * @type {string}
+     * @memberof QueryDataService
+     */
+    idColumn: string;
+    /**
+     * Creates an instance of QueryDataService.
+     *
+     * @param {string} relation - The name of the database relation (table/view) to query
+     * @param {string} idColumn - The name of the primary key column
+     * @param {Database} db - The database instance to execute queries against
+     * @memberof QueryDataService
+     */
+    constructor(relation: string, idColumn: string, db: Database);
+    /**
+     * Finds a single record by its primary key value.
+     * Constructs a WHERE clause matching the idColumn to the provided value.
+     *
+     * @template IdType - The type of the primary key value
+     * @param {IdType} id - The primary key value to search for
+     * @returns {PromiseOfRecord<RelationType | null>} The matching record, or null if not found
+     * @memberof QueryDataService
+     */
+    findById<IdType>(id: IdType): PromiseOfRecord<RelationType | null>;
+    /**
+     * Finds a single record matching a custom expression.
+     * Returns the first matching record, or null if no records match.
+     *
+     * @param {ExpressionBuilder<RelationType>} builder - Expression builder function to construct the WHERE clause
+     * @returns {PromiseOfRecord<RelationType | null>} The first matching record, or null if not found
+     * @memberof QueryDataService
+     *
+     * @example
+     * const user = await service.findByExpression(q =>
+     *   q.where('email').equals('alice@example.com')
+     * );
+     */
+    findByExpression(builder: ExpressionBuilder<RelationType>): PromiseOfRecord<RelationType | null>;
+    /**
+     * Finds all records matching a custom expression.
+     * Returns an empty array if no records match.
+     *
+     * @param {ExpressionBuilder<RelationType>} builder - Expression builder function to construct the WHERE clause
+     * @returns {PromiseOfRecordSet<RelationType>} Array of matching records
+     * @memberof QueryDataService
+     *
+     * @example
+     * const activeUsers = await service.findAllByExpression(q =>
+     *   q.where('active').equals(true)
+     * );
+     */
+    findAllByExpression(builder: ExpressionBuilder<RelationType>): PromiseOfRecordSet<RelationType>;
+    /**
+     * Finds all records in the relation without any filtering.
+     * Returns an empty array if the relation is empty.
+     *
+     * @returns {PromiseOfRecordSet<RelationType>} Array of all records in the relation
+     * @memberof QueryDataService
+     */
+    findAll(): PromiseOfRecordSet<RelationType>;
+}
+/**
+ * Factory function that creates a concrete QueryDataService class for a specific relation.
+ * The returned class can be instantiated with just a Database instance.
+ *
+ * @template RelationType - The type representing the relation/table structure
+ * @param {string} relationName - The name of the relation/table
+ * @param {string} idColumn - The name of the primary key column
+ * @returns A concrete QueryDataService class bound to the specified relation
+ *
+ * @example
+ * const UserService = createQueryService<User>('users', 'id');
+ * const service = new UserService(db);
+ * const user = await service.findById(123);
+ */
+export declare function createQueryService<RelationType>(relationName: string, idColumn: string): new (db: Database) => QueryDataService<RelationType>;
+//# sourceMappingURL=query-dataservice.d.ts.map

package/dist/dbcore/query-dataservice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-dataservice.d.ts","sourceRoot":"","sources":["../src/query-dataservice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,gBAAgB,CAAC,YAAY,CAAE,SAAQ,eAAe;IAC1E;;;;;OAKG;IACI,QAAQ,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACI,QAAQ,EAAE,MAAM,CAAC;IAExB;;;;;;;OAOG;gBACS,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ;IAM5D;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,CAAC,YAAY,GAAG,IAAI,CAAC;IAMlE;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,GAAG,eAAe,CAAC,YAAY,GAAG,IAAI,CAAC;IAMhG;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,GAAG,kBAAkB,CAAC,YAAY,CAAC;IAM/F;;;;;;OAMG;IACH,OAAO,IAAI,kBAAkB,CAAC,YAAY,CAAC;CAG5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAC7C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,KAAK,EAAE,EAAE,QAAQ,KAAK,gBAAgB,CAAC,YAAY,CAAC,CAOtD"}

package/dist/dbcore/query-dataservice.js

@@ -0,0 +1,144 @@
+import { query } from '../expression/index.js';
+import { DataServiceBase } from './dataservice-base.js';
+/**
+ * Abstract base class for read-only data services that query a single database relation.
+ * Provides common query patterns like findById, findByExpression, and findAll.
+ *
+ * Uses the expression builder from @blendsdk/expression for type-safe query construction
+ * and delegates execution to the FromStatement builder.
+ *
+ * To create a concrete data service, either extend this class or use the
+ * `createQueryService()` factory function.
+ *
+ * @export
+ * @abstract
+ * @class QueryDataService
+ * @extends {DataServiceBase}
+ * @template RelationType - The type representing the database relation/table structure
+ *
+ * @example
+ * // Using the factory function
+ * const UserService = createQueryService<User>('users', 'id');
+ * const service = new UserService(db);
+ * const user = await service.findById(123);
+ *
+ * @example
+ * // Extending the class
+ * class UserService extends QueryDataService<User> {
+ *   constructor(db: Database) {
+ *     super('users', 'id', db);
+ *   }
+ * }
+ */
+export class QueryDataService extends DataServiceBase {
+    /**
+     * The name of the database relation (table or view) this service queries.
+     *
+     * @type {string}
+     * @memberof QueryDataService
+     */
+    relation;
+    /**
+     * The name of the primary key column used for findById queries.
+     *
+     * @type {string}
+     * @memberof QueryDataService
+     */
+    idColumn;
+    /**
+     * Creates an instance of QueryDataService.
+     *
+     * @param {string} relation - The name of the database relation (table/view) to query
+     * @param {string} idColumn - The name of the primary key column
+     * @param {Database} db - The database instance to execute queries against
+     * @memberof QueryDataService
+     */
+    constructor(relation, idColumn, db) {
+        super(db);
+        this.relation = relation;
+        this.idColumn = idColumn;
+    }
+    /**
+     * Finds a single record by its primary key value.
+     * Constructs a WHERE clause matching the idColumn to the provided value.
+     *
+     * @template IdType - The type of the primary key value
+     * @param {IdType} id - The primary key value to search for
+     * @returns {PromiseOfRecord<RelationType | null>} The matching record, or null if not found
+     * @memberof QueryDataService
+     */
+    findById(id) {
+        const qb = query();
+        qb.where(this.idColumn).equals(id);
+        return this.db.from(this.relation).select().byExpression(qb.compile()).executeReturnSingle();
+    }
+    /**
+     * Finds a single record matching a custom expression.
+     * Returns the first matching record, or null if no records match.
+     *
+     * @param {ExpressionBuilder<RelationType>} builder - Expression builder function to construct the WHERE clause
+     * @returns {PromiseOfRecord<RelationType | null>} The first matching record, or null if not found
+     * @memberof QueryDataService
+     *
+     * @example
+     * const user = await service.findByExpression(q =>
+     *   q.where('email').equals('alice@example.com')
+     * );
+     */
+    findByExpression(builder) {
+        const qb = query();
+        builder(qb);
+        return this.db.from(this.relation).select().byExpression(qb.compile()).executeReturnSingle();
+    }
+    /**
+     * Finds all records matching a custom expression.
+     * Returns an empty array if no records match.
+     *
+     * @param {ExpressionBuilder<RelationType>} builder - Expression builder function to construct the WHERE clause
+     * @returns {PromiseOfRecordSet<RelationType>} Array of matching records
+     * @memberof QueryDataService
+     *
+     * @example
+     * const activeUsers = await service.findAllByExpression(q =>
+     *   q.where('active').equals(true)
+     * );
+     */
+    findAllByExpression(builder) {
+        const qb = query();
+        builder(qb);
+        return this.db.from(this.relation).select().byExpression(qb.compile()).executeReturnAll();
+    }
+    /**
+     * Finds all records in the relation without any filtering.
+     * Returns an empty array if the relation is empty.
+     *
+     * @returns {PromiseOfRecordSet<RelationType>} Array of all records in the relation
+     * @memberof QueryDataService
+     */
+    findAll() {
+        return this.db.from(this.relation).select().executeReturnAll();
+    }
+}
+/**
+ * Factory function that creates a concrete QueryDataService class for a specific relation.
+ * The returned class can be instantiated with just a Database instance.
+ *
+ * @template RelationType - The type representing the relation/table structure
+ * @param {string} relationName - The name of the relation/table
+ * @param {string} idColumn - The name of the primary key column
+ * @returns A concrete QueryDataService class bound to the specified relation
+ *
+ * @example
+ * const UserService = createQueryService<User>('users', 'id');
+ * const service = new UserService(db);
+ * const user = await service.findById(123);
+ */
+export function createQueryService(relationName, idColumn) {
+    class ConcreteQueryDataService extends QueryDataService {
+        constructor(db) {
+            super(relationName, idColumn, db);
+        }
+    }
+    return ConcreteQueryDataService;
+}
+//# sourceMappingURL=query-dataservice.js.map

package/dist/dbcore/query-dataservice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-dataservice.js","sourceRoot":"","sources":["../src/query-dataservice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgB,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA6BxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAgB,gBAA+B,SAAQ,eAAe;IAC1E;;;;;OAKG;IACI,QAAQ,CAAS;IAExB;;;;;OAKG;IACI,QAAQ,CAAS;IAExB;;;;;;;OAOG;IACH,YAAY,QAAgB,EAAE,QAAgB,EAAE,EAAY;QAC1D,KAAK,CAAC,EAAE,CAAC,CAAC;QACV,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAS,EAAU;QACzB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;QACnB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC;IAC/F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,OAAwC;QACvD,MAAM,EAAE,GAAG,KAAK,EAAgB,CAAC;QACjC,OAAO,CAAC,EAAE,CAAC,CAAC;QACZ,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC;IAC/F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,OAAwC;QAC1D,MAAM,EAAE,GAAG,KAAK,EAAgB,CAAC;QACjC,OAAO,CAAC,EAAE,CAAC,CAAC;QACZ,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC;IAC5F,CAAC;IAED;;;;;;OAMG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,CAAe,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,gBAAgB,EAAE,CAAC;IAC/E,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAoB,EACpB,QAAgB;IAEhB,MAAM,wBAAyB,SAAQ,gBAA8B;QACnE,YAAY,EAAY;YACtB,KAAK,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;KACF;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC"}

package/dist/dbcore/statement.d.ts

@@ -0,0 +1,133 @@
+import { Database, QueryResult } from './database.js';
+/**
+ * Abstract base class for all SQL statement builders.
+ * Provides common functionality for building and executing database queries,
+ * including parameter handling, query execution, and result processing.
+ *
+ * This class implements the builder pattern, allowing for fluent method chaining
+ * when constructing database queries. Concrete implementations must provide
+ * the specific query building logic for their statement type.
+ *
+ * @export
+ * @abstract
+ * @class Statement
+ * @template TableType - The type representing the table structure this statement operates on
+ */
+export declare abstract class Statement<TableType = any> {
+    protected db: Database;
+    /**
+     * Handler function to transform parameters before query execution.
+     * Set via the beforeQuery() method to enable parameter preprocessing.
+     *
+     * @protected
+     * @type {((params: any) => any) | null}
+     * @memberof Statement
+     */
+    protected _beforeQuery: ((params: any) => any) | null;
+    /**
+     * Handler function to transform result rows after query execution.
+     * Set via the afterQuery() method to enable result postprocessing
+     * (e.g., data transformation, filtering, or augmenting returned records).
+     *
+     * @protected
+     * @type {((rows: any) => any) | null}
+     * @memberof Statement
+     */
+    protected _afterQuery: ((rows: any) => any) | null;
+    /**
+     * Creates an instance of Statement.
+     * Initializes the statement with a database connection and sets up
+     * parameter transformation handlers to null.
+     *
+     * @param {Database} db - The database instance to execute queries against
+     * @memberof Statement
+     */
+    constructor(db: Database);
+    /**
+     * Builds the SQL query string for this statement.
+     * Must be implemented by concrete statement classes to generate
+     * the appropriate SQL syntax for their operation type.
+     *
+     * @protected
+     * @abstract
+     * @return {string} The SQL query string
+     * @memberof Statement
+     */
+    protected abstract buildQuery(): string;
+    /**
+     * Builds the parameter object for this statement's query.
+     * Must be implemented by concrete statement classes to provide
+     * the parameters needed for their specific query.
+     *
+     * @protected
+     * @abstract
+     * @return {any} The parameters object for the query
+     * @memberof Statement
+     */
+    protected abstract buildParameters(): any;
+    /**
+     * Executes the statement and returns the query result.
+     * Builds the query and parameters, applies any registered parameter handlers,
+     * and executes the query through the database connection.
+     *
+     * @template R - The type of QueryResult expected, defaults to QueryResult<any>
+     * @return {Promise<R | null>} Promise resolving to the query result or null
+     * @memberof Statement
+     */
+    execute<R extends QueryResult<any> = QueryResult<any>>(): Promise<R | null>;
+    /**
+     * Executes the statement and returns the first record from the result.
+     * Useful for queries expected to return a single row, such as SELECT with LIMIT 1
+     * or queries filtering by unique identifiers.
+     *
+     * @return {Promise<Partial<TableType> | null>} Promise resolving to the first record or null if no records found
+     * @memberof Statement
+     */
+    executeReturnSingle(): Promise<Partial<TableType> | null>;
+    /**
+     * Executes the statement and returns all records from the result.
+     * Returns an empty array if no records are found.
+     *
+     * @return {Promise<Partial<TableType>[]>} Promise resolving to an array of all records
+     * @memberof Statement
+     */
+    executeReturnAll(): Promise<Partial<TableType>[]>;
+    /**
+     * Executes the statement and returns the number of affected rows.
+     * Useful for INSERT, UPDATE, and DELETE operations where you need to know
+     * how many rows were modified.
+     *
+     * @return {Promise<number>} Promise resolving to the count of affected rows
+     * @memberof Statement
+     */
+    executeReturnCount(): Promise<number>;
+    /**
+     * Registers a handler to transform parameters before query execution.
+     * The handler receives the parameters object and must return a transformed version.
+     * Useful for parameter validation, sanitization, or transformation before the query runs.
+     *
+     * @template T - The type of the parameters object
+     * @param {(params: T) => T} handler - The transformation function to apply before query execution
+     * @return {this} The statement instance for method chaining
+     * @memberof Statement
+     */
+    beforeQuery<T>(handler: (params: T) => T): this;
+    /**
+     * Registers a handler to transform result rows after query execution.
+     * The handler receives the query result rows array and must return a transformed version.
+     * Useful for data transformation, field mapping, or post-processing of returned records.
+     *
+     * @template T - The type of the result rows array
+     * @param {(rows: T) => T} handler - The transformation function to apply to result rows
+     * @return {this} The statement instance for method chaining
+     * @memberof Statement
+     *
+     * @example
+     * // Convert all date strings to Date objects
+     * statement.afterQuery((rows) =>
+     *   rows.map(row => ({ ...row, created_at: new Date(row.created_at) }))
+     * )
+     */
+    afterQuery<T>(handler: (rows: T) => T): this;
+}
+//# sourceMappingURL=statement.d.ts.map

package/dist/dbcore/statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.d.ts","sourceRoot":"","sources":["../src/statement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuB,WAAW,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,8BAAsB,SAAS,CAAC,SAAS,GAAG,GAAG;IA8BjC,SAAS,CAAC,EAAE,EAAE,QAAQ;IA7BlC;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IAEtD;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IAEnD;;;;;;;OAOG;gBACmB,EAAE,EAAE,QAAQ;IAKlC;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,MAAM;IAEvC;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,GAAG;IAEzC;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,SAAS,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgB3E;;;;;;;OAOG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;IAKvD;;;;;;;OAOG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAK3C;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI;IAK/C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI;CAI7C"}

package/dist/dbcore/statement.js

@@ -0,0 +1,138 @@
+/**
+ * Abstract base class for all SQL statement builders.
+ * Provides common functionality for building and executing database queries,
+ * including parameter handling, query execution, and result processing.
+ *
+ * This class implements the builder pattern, allowing for fluent method chaining
+ * when constructing database queries. Concrete implementations must provide
+ * the specific query building logic for their statement type.
+ *
+ * @export
+ * @abstract
+ * @class Statement
+ * @template TableType - The type representing the table structure this statement operates on
+ */
+export class Statement {
+    db;
+    /**
+     * Handler function to transform parameters before query execution.
+     * Set via the beforeQuery() method to enable parameter preprocessing.
+     *
+     * @protected
+     * @type {((params: any) => any) | null}
+     * @memberof Statement
+     */
+    _beforeQuery;
+    /**
+     * Handler function to transform result rows after query execution.
+     * Set via the afterQuery() method to enable result postprocessing
+     * (e.g., data transformation, filtering, or augmenting returned records).
+     *
+     * @protected
+     * @type {((rows: any) => any) | null}
+     * @memberof Statement
+     */
+    _afterQuery;
+    /**
+     * Creates an instance of Statement.
+     * Initializes the statement with a database connection and sets up
+     * parameter transformation handlers to null.
+     *
+     * @param {Database} db - The database instance to execute queries against
+     * @memberof Statement
+     */
+    constructor(db) {
+        this.db = db;
+        this._beforeQuery = null;
+        this._afterQuery = null;
+    }
+    /**
+     * Executes the statement and returns the query result.
+     * Builds the query and parameters, applies any registered parameter handlers,
+     * and executes the query through the database connection.
+     *
+     * @template R - The type of QueryResult expected, defaults to QueryResult<any>
+     * @return {Promise<R | null>} Promise resolving to the query result or null
+     * @memberof Statement
+     */
+    execute() {
+        const options = {};
+        if (this._beforeQuery) {
+            options.beforeQuery = this._beforeQuery;
+        }
+        if (this._afterQuery) {
+            options.afterQuery = this._afterQuery;
+        }
+        return this.db.executeQuery(this.buildQuery(), this.buildParameters(), options);
+    }
+    /**
+     * Executes the statement and returns the first record from the result.
+     * Useful for queries expected to return a single row, such as SELECT with LIMIT 1
+     * or queries filtering by unique identifiers.
+     *
+     * @return {Promise<Partial<TableType> | null>} Promise resolving to the first record or null if no records found
+     * @memberof Statement
+     */
+    async executeReturnSingle() {
+        const result = await this.execute();
+        return result?.records[0] || null;
+    }
+    /**
+     * Executes the statement and returns all records from the result.
+     * Returns an empty array if no records are found.
+     *
+     * @return {Promise<Partial<TableType>[]>} Promise resolving to an array of all records
+     * @memberof Statement
+     */
+    async executeReturnAll() {
+        const result = await this.execute();
+        return (result?.records || []);
+    }
+    /**
+     * Executes the statement and returns the number of affected rows.
+     * Useful for INSERT, UPDATE, and DELETE operations where you need to know
+     * how many rows were modified.
+     *
+     * @return {Promise<number>} Promise resolving to the count of affected rows
+     * @memberof Statement
+     */
+    async executeReturnCount() {
+        const result = await this.execute();
+        return result?.rowCount || 0;
+    }
+    /**
+     * Registers a handler to transform parameters before query execution.
+     * The handler receives the parameters object and must return a transformed version.
+     * Useful for parameter validation, sanitization, or transformation before the query runs.
+     *
+     * @template T - The type of the parameters object
+     * @param {(params: T) => T} handler - The transformation function to apply before query execution
+     * @return {this} The statement instance for method chaining
+     * @memberof Statement
+     */
+    beforeQuery(handler) {
+        this._beforeQuery = handler;
+        return this;
+    }
+    /**
+     * Registers a handler to transform result rows after query execution.
+     * The handler receives the query result rows array and must return a transformed version.
+     * Useful for data transformation, field mapping, or post-processing of returned records.
+     *
+     * @template T - The type of the result rows array
+     * @param {(rows: T) => T} handler - The transformation function to apply to result rows
+     * @return {this} The statement instance for method chaining
+     * @memberof Statement
+     *
+     * @example
+     * // Convert all date strings to Date objects
+     * statement.afterQuery((rows) =>
+     *   rows.map(row => ({ ...row, created_at: new Date(row.created_at) }))
+     * )
+     */
+    afterQuery(handler) {
+        this._afterQuery = handler;
+        return this;
+    }
+}
+//# sourceMappingURL=statement.js.map

package/dist/dbcore/statement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.js","sourceRoot":"","sources":["../src/statement.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,SAAS;IA8BP;IA7BtB;;;;;;;OAOG;IACO,YAAY,CAAgC;IAEtD;;;;;;;;OAQG;IACO,WAAW,CAA8B;IAEnD;;;;;;;OAOG;IACH,YAAsB,EAAY;QAAZ,OAAE,GAAF,EAAE,CAAU;QAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IA0BD;;;;;;;;OAQG;IACH,OAAO;QACL,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QAC1C,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC;QACxC,CAAC;QAED,OAAO,IAAI,CAAC,EAAE,CAAC,YAAY,CACzB,IAAI,CAAC,UAAU,EAAE,EACjB,IAAI,CAAC,eAAe,EAAE,EACtB,OAAO,CACa,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,mBAAmB;QACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,OAAO,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACpC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,gBAAgB;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAyB,CAAC;IACzD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,OAAO,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CAAI,OAAyB;QACtC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAI,OAAuB;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/dbcore/update-statement.d.ts

@@ -0,0 +1,48 @@
+import { FilterableStatement } from './filterable-statement.js';
+import { Database } from './database.js';
+/**
+ * Abstract statement builder for UPDATE operations.
+ * Extends FilterableStatement to provide functionality for updating existing records in database tables.
+ * Concrete database implementations must extend this class to provide database-specific
+ * UPDATE query construction and parameter handling.
+ *
+ * This class provides a fluent interface for building UPDATE statements with support
+ * for filtering which records to update and RETURNING clauses to retrieve updated data.
+ *
+ * @export
+ * @abstract
+ * @class UpdateStatement
+ * @extends {FilterableStatement<TableType, FilterType>}
+ * @template TableType - The type representing the table structure for updates
+ * @template FilterType - The type representing the filter criteria structure
+ */
+export declare abstract class UpdateStatement<TableType, FilterType> extends FilterableStatement<TableType, FilterType> {
+    /**
+     * Creates an instance of UpdateStatement.
+     * Initializes the statement with a table name and database connection.
+     *
+     * @param {string} tableName - The name of the table to update
+     * @param {Database} db - The database instance to execute queries against
+     * @memberof UpdateStatement
+     */
+    constructor(tableName: string, db: Database);
+    /**
+     * Sets the values to be updated in the table.
+     * Accepts a partial object where keys represent column names and values
+     * represent the new data. Only the specified columns will be updated.
+     *
+     * @param {Partial<TableType>} values - Object containing column names and new values
+     * @return {this} The statement instance for method chaining
+     * @memberof UpdateStatement
+     *
+     * @example
+     * // Update user fields
+     * statement.values({
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com',
+     *   updated_at: new Date()
+     * })
+     */
+    values(values: Partial<TableType>): this;
+}
+//# sourceMappingURL=update-statement.d.ts.map

package/dist/dbcore/update-statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-statement.d.ts","sourceRoot":"","sources":["../src/update-statement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,8BAAsB,eAAe,CAAC,SAAS,EAAE,UAAU,CAAE,SAAQ,mBAAmB,CACtF,SAAS,EACT,UAAU,CACX;IACC;;;;;;;OAOG;gBACS,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ;IAI3C;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI;CAIzC"}