@dbcube/query-builder 5.1.6 → 5.2.2

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { QueryEngine } from '@dbcube/core';
+
 export interface PaginatedResult<T = DatabaseRecord> {
 	items: T[];
 	page: number;
@@ -17,8 +19,33 @@ export interface RelationOptions {
 	/** 'many' attaches an array (hasMany), 'one' attaches a single record (belongsTo) */
 	type?: "many" | "one";
 }
-export type WhereCallback = (query: Table) => void;
+export type WhereCallback = (query: Table<DatabaseRecord>) => void;
 export type DatabaseRecord = Record<string, any>;
+/** Result row returned by write operations (update/delete/truncate/upsert). */
+export interface MutationInfo {
+	affectedRows?: number;
+	affected_rows?: number;
+	lastInsertId?: number | string;
+	[key: string]: unknown;
+}
+/** A computed-field definition loaded from dbcube_computes_config. */
+export interface ComputedFieldConfig {
+	column: string;
+	type: string;
+	instruction: string;
+	table_ref?: string;
+	database_ref?: string;
+	[key: string]: unknown;
+}
+/** A runtime-trigger definition loaded from dbcube_triggers_config. */
+export interface TriggerConfig {
+	type: string;
+	table_ref: string;
+	database_ref: string;
+	name?: string;
+	description?: string;
+	[key: string]: unknown;
+}
 /**
  * Main class to handle MySQL database connections and queries.
  * Implements the Singleton pattern to ensure a single instance of the connection pool.
@@ -38,7 +65,7 @@ export declare class Database {
 	 * const rows = await db.raw('SELECT * FROM users WHERE age > ?', [25]);
 	 * await db.raw('CREATE INDEX idx_users_email ON users(email)');
 	 */
-	raw(query: string, params?: any[]): Promise<any>;
+	raw<R = DatabaseRecord>(query: string, params?: unknown[]): Promise<R[]>;
 	/**
 	 * Runs a callback inside a database transaction. Everything executed through
 	 * the received connection is committed atomically; any thrown error rolls
@@ -94,15 +121,18 @@ export declare class Database {
 	 * // Access column management
 	 * const columns = await db.table('users').columns().get();
 	 */
-	table(tableName: string): Table;
+	table<T extends DatabaseRecord = DatabaseRecord>(tableName: string): Table<T>;
 	private setComputedFields;
 	private setTriggers;
 }
 /**
  * Class to build and execute SQL queries for a specific table.
  * Supports operations like SELECT, INSERT, UPDATE, DELETE, and more.
+ *
+ * Generic over the row shape: `db.table<User>('users').get()` resolves to
+ * `Promise<User[]>`. Pair it with the interfaces emitted by `dbcube generate`.
  */
-export declare class Table {
+export declare class Table<T extends DatabaseRecord = DatabaseRecord> {
 	private engine;
 	private nextType;
 	private dml;
@@ -111,7 +141,10 @@ export declare class Table {
 	private triggers;
 	private txId;
 	private relations;
-	constructor(instance: any, databaseName: string, tableName: string, engine?: any, computedFields?: any[], triggers?: any[], txId?: string | null);
+	/** Builders de grupo mutan en sitio (ver clone()) */
+	private _mutable;
+	private instance;
+	constructor(instance: Database, databaseName: string, tableName: string, engine: QueryEngine, computedFields?: ComputedFieldConfig[], triggers?: TriggerConfig[], txId?: string | null);
 	/**
 	 * Specifies the columns to select in a SELECT query.
 	 *
@@ -122,7 +155,7 @@ export declare class Table {
 	 * const users = await db.table('users').select(['id', 'name']).get();
 	 * console.log(users); // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
 	 */
-	select(fields?: string[]): Table;
+	select(fields?: string[]): Table<T>;
 	/**
 	 * Adds a WHERE condition to the query.
 	 *
@@ -136,8 +169,8 @@ export declare class Table {
 	 * const nullUsers = await db.table('users').where('email', 'IS NULL').get();
 	 * console.log(users); // [{ id: 1, name: 'John', age: 30 }]
 	 */
-	where(column: string, operator: "IS NULL" | "IS NOT NULL"): Table;
-	where(column: string, operator: "=" | "!=" | "<>" | ">" | "<" | ">=" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN", value: any): Table;
+	where(column: string, operator: "IS NULL" | "IS NOT NULL"): Table<T>;
+	where(column: string, operator: "=" | "!=" | "<>" | ">" | "<" | ">=" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN", value: any): Table<T>;
 	/**
 	 * Adds an OR WHERE condition to the query.
 	 *
@@ -151,8 +184,8 @@ export declare class Table {
 	 * const nullUsers = await db.table('users').where('active', '=', true).orWhere('email', 'IS NULL').get();
 	 * console.log(users); // [{ id: 1, name: 'John', age: 30 }, { id: 2, name: 'Jane', age: 25 }]
 	 */
-	orWhere(column: string, operator: "IS NULL" | "IS NOT NULL"): Table;
-	orWhere(column: string, operator: "=" | "!=" | "<>" | ">" | "<" | ">=" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN", value: any): Table;
+	orWhere(column: string, operator: "IS NULL" | "IS NOT NULL"): Table<T>;
+	orWhere(column: string, operator: "=" | "!=" | "<>" | ">" | "<" | ">=" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN", value: any): Table<T>;
 	/**
 	 * Adds a grouped WHERE condition to the query.
 	 *
@@ -165,9 +198,9 @@ export declare class Table {
 	 * }).get();
 	 * console.log(users); // [{ id: 1, name: 'John', age: 30 }, { id: 2, name: 'Jane', age: 25 }]
 	 */
-	whereGroup(callback: WhereCallback): Table;
-	or(): Table;
-	and(): Table;
+	whereGroup(callback: WhereCallback): Table<T>;
+	or(): Table<T>;
+	and(): Table<T>;
 	/**
 	 * Adds a WHERE BETWEEN condition to the query.
 	 *
@@ -182,7 +215,7 @@ export declare class Table {
 	whereBetween(column: string, values: [
 		any,
 		any
-	]): Table;
+	]): Table<T>;
 	/**
 	 * Adds a WHERE IN condition to the query.
 	 *
@@ -194,7 +227,7 @@ export declare class Table {
 	 * const users = await db.table('users').whereIn('id', [1, 2]).get();
 	 * console.log(users); // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
 	 */
-	whereIn(column: string, values: any[]): Table;
+	whereIn(column: string, values: any[]): Table<T>;
 	/**
 	* Adds a WHERE IS NULL condition to the query.
 	*
@@ -205,7 +238,7 @@ export declare class Table {
 	* const users = await db.table('users').whereNull('email').get();
 	* console.log(users); // [{ id: 3, name: 'Alice', email: null }]
 	*/
-	whereNull(column: string): Table;
+	whereNull(column: string): Table<T>;
 	/**
 	 * Adds a WHERE IS NOT NULL condition to the query.
 	 *
@@ -216,7 +249,7 @@ export declare class Table {
 	 * const users = await db.table('users').whereNotNull('email').get();
 	 * console.log(users); // [{ id: 1, name: 'John', email: 'john@example.com' }]
 	 */
-	whereNotNull(column: string): Table;
+	whereNotNull(column: string): Table<T>;
 	/**
 	 * Adds a JOIN clause to the query.
 	 *
@@ -230,7 +263,7 @@ export declare class Table {
 	 * const users = await db.table('users').join('orders', 'users.id', '=', 'orders.user_id').get();
 	 * console.log(users); // [{ id: 1, name: 'John', order_id: 101 }]
 	 */
-	join(table: string, column1: string, operator: string, column2: string): Table;
+	join(table: string, column1: string, operator: string, column2: string): Table<T>;
 	/**
 	 * Adds a LEFT JOIN clause to the query.
 	 *
@@ -244,7 +277,7 @@ export declare class Table {
 	 * const users = await db.table('users').leftJoin('orders', 'users.id', '=', 'orders.user_id').get();
 	 * console.log(users); // [{ id: 1, name: 'John', order_id: 101 }, { id: 2, name: 'Jane', order_id: null }]
 	 */
-	leftJoin(table: string, column1: string, operator: string, column2: string): Table;
+	leftJoin(table: string, column1: string, operator: string, column2: string): Table<T>;
 	/**
 	 * Adds a RIGHT JOIN clause to the query.
 	 *
@@ -258,7 +291,7 @@ export declare class Table {
 	 * const users = await db.table('users').rightJoin('orders', 'users.id', '=', 'orders.user_id').get();
 	 * console.log(users); // [{ id: 1, name: 'John', order_id: 101 }, { id: null, name: null, order_id: 102 }]
 	 */
-	rightJoin(table: string, column1: string, operator: string, column2: string): Table;
+	rightJoin(table: string, column1: string, operator: string, column2: string): Table<T>;
 	/**
 	 * Adds an ORDER BY clause to the query.
 	 *
@@ -270,7 +303,7 @@ export declare class Table {
 	 * const users = await db.table('users').orderBy('name', 'ASC').get();
 	 * console.log(users); // [{ id: 2, name: 'Jane' }, { id: 1, name: 'John' }]
 	 */
-	orderBy(column: string, direction?: "ASC" | "DESC"): Table;
+	orderBy(column: string, direction?: "ASC" | "DESC"): Table<T>;
 	/**
 	 * Adds a GROUP BY clause to the query.
 	 *
@@ -281,7 +314,7 @@ export declare class Table {
 	 * const users = await db.table('users').groupBy('age').get();
 	 * console.log(users); // [{ age: 30, count: 1 }, { age: 25, count: 1 }]
 	 */
-	groupBy(column: string): Table;
+	groupBy(column: string): Table<T>;
 	/**
 	 * Adds a DISTINCT clause to the query.
 	 *
@@ -291,7 +324,7 @@ export declare class Table {
 	 * const users = await db.table('users').distinct().select(['name']).get();
 	 * console.log(users); // [{ name: 'John' }, { name: 'Jane' }]
 	 */
-	distinct(): Table;
+	distinct(): Table<T>;
 	/**
 	 * Adds a COUNT clause to the query.
 	 *
@@ -302,7 +335,7 @@ export declare class Table {
 	 * const count = await db.table('users').count().first();
 	 * console.log(count); // { count: 2 }
 	 */
-	count(column?: string): Promise<Number>;
+	count(column?: string): Promise<number>;
 	/**
 	 * Adds a SUM clause to the query.
 	 *
@@ -313,7 +346,7 @@ export declare class Table {
 	 * const totalAge = await db.table('users').sum('age').first();
 	 * console.log(totalAge); // { sum: 55 }
 	 */
-	sum(column: string): Promise<Number>;
+	sum(column: string): Promise<number>;
 	/**
 	 * Adds an AVG clause to the query.
 	 *
@@ -324,7 +357,7 @@ export declare class Table {
 	 * const avgAge = await db.table('users').avg('age').first();
 	 * console.log(avgAge); // { avg: 27.5 }
 	 */
-	avg(column: string): Promise<Number>;
+	avg(column: string): Promise<number>;
 	/**
 	 * Adds a MAX clause to the query.
 	 *
@@ -335,7 +368,7 @@ export declare class Table {
 	 * const maxAge = await db.table('users').max('age').first();
 	 * console.log(maxAge); // { max: 30 }
 	 */
-	max(column: string): Promise<Number>;
+	max(column: string): Promise<number>;
 	/**
 	 * Adds a MIN clause to the query.
 	 *
@@ -346,7 +379,7 @@ export declare class Table {
 	 * const minAge = await db.table('users').min('age').first();
 	 * console.log(minAge); // { min: 25 }
 	 */
-	min(column: string): Promise<Number>;
+	min(column: string): Promise<number>;
 	/**
 	 * Gets the column names of the table.
 	 * For SQL databases (MySQL, PostgreSQL, SQLite), returns a simple array of column names.
@@ -385,7 +418,7 @@ export declare class Table {
 	 * const users = await db.table('users').limit(1).get();
 	 * console.log(users); // [{ id: 1, name: 'John', age: 30 }]
 	 */
-	limit(number: number): Table;
+	limit(number: number): Table<T>;
 	/**
 	 * Adds pagination to the query using LIMIT and OFFSET.
 	 *
@@ -396,7 +429,7 @@ export declare class Table {
 	 * const users = await db.table('users').limit(1).page(2).get();
 	 * console.log(users); // [{ id: 2, name: 'Jane', age: 25 }]
 	 */
-	page(number: number): Table;
+	page(number: number): Table<T>;
 	/**
 	* Executes the query and returns all matching rows.
 	*
@@ -406,7 +439,7 @@ export declare class Table {
 	* const users = await db.table('users').get();
 	* console.log(users); // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
 	*/
-	get(): Promise<DatabaseRecord[]>;
+	get(): Promise<T[]>;
 	/**
 	 * Executes the query and returns the first matching row.
 	 *
@@ -416,7 +449,7 @@ export declare class Table {
 	 * const user = await db.table('users').first();
 	 * console.log(user); // { id: 1, name: 'John' }
 	 */
-	first(): Promise<DatabaseRecord | null>;
+	first(): Promise<T | null>;
 	/**
 	 * Finds a row by a specific column value.
 	 *
@@ -428,7 +461,7 @@ export declare class Table {
 	 * const user = await db.table('users').find(1);
 	 * console.log(user); // { id: 1, name: 'John' }
 	 */
-	find(value: any, column?: string): Promise<DatabaseRecord | null>;
+	find(value: string | number, column?: string): Promise<T | null>;
 	/**
 	 * Inserts one or more rows into the table.
 	 *
@@ -442,7 +475,7 @@ export declare class Table {
 	 * ]);
 	 * console.log(newUsers); // [{ id: 3, name: 'Alice', age: 28 }, { id: 4, name: 'Bob', age: 32 }]
 	 */
-	insert(data: DatabaseRecord[]): Promise<DatabaseRecord[]>;
+	insert(data: Partial<T>[]): Promise<T[]>;
 	/**
 	 * Updates rows in the table based on the defined conditions.
 	 *
@@ -455,7 +488,7 @@ export declare class Table {
 	 *     .update({ name: 'John Updated', age: 31 });
 	 * console.log(result); // { affectedRows: 1 }
 	 */
-	update(data: DatabaseRecord): Promise<any>;
+	update(data: Partial<T>): Promise<MutationInfo[]>;
 	/**
 	 * Deletes rows from the table based on the defined conditions.
 	 *
@@ -465,21 +498,21 @@ export declare class Table {
 	 * const result = await db.table('users').where('id', '=', 1).delete();
 	 * console.log(result); // { affectedRows: 1 }
 	 */
-	delete(): Promise<any>;
+	delete(): Promise<MutationInfo[]>;
 	/**
 	 * Adds a WHERE NOT IN condition to the query.
 	 *
 	 * @example
 	 * const users = await db.table('users').whereNotIn('status', ['banned', 'deleted']).get();
 	 */
-	whereNotIn(column: string, values: any[]): Table;
+	whereNotIn(column: string, values: any[]): Table<T>;
 	/**
 	 * Sets an explicit OFFSET for the query (alternative to page()).
 	 *
 	 * @example
 	 * const rows = await db.table('logs').orderBy('id', 'ASC').limit(50).offset(100).get();
 	 */
-	offset(number: number): Table;
+	offset(number: number): Table<T>;
 	/**
 	 * Appends raw expressions to the SELECT list (aggregates, functions, aliases).
 	 * Combine with groupBy() and having() for per-group metrics.
@@ -492,14 +525,14 @@ export declare class Table {
 	 *     .having('order_count', '>', 5)
 	 *     .get();
 	 */
-	selectRaw(expressions: string[]): Table;
+	selectRaw(expressions: string[]): Table<T>;
 	/**
 	 * Adds a HAVING condition (filters grouped results).
 	 *
 	 * @example
 	 * .groupBy('user_id').having('COUNT(*)', '>', 5)
 	 */
-	having(column: string, operator: string, value?: any): Table;
+	having(column: string, operator: string, value?: any): Table<T>;
 	/**
 	 * Checks if at least one row matches the current conditions.
 	 * Cheaper than first(): selects a constant with LIMIT 1.
@@ -518,7 +551,7 @@ export declare class Table {
 	 *     .orderBy('id', 'ASC')
 	 *     .paginate(2, 25);
 	 */
-	paginate(page?: number, perPage?: number): Promise<PaginatedResult>;
+	paginate(page?: number, perPage?: number): Promise<PaginatedResult<T>>;
 	/**
 	 * Processes all matching rows in batches of `size`, keeping memory flat.
 	 * Return `false` from the callback to stop early.
@@ -528,7 +561,7 @@ export declare class Table {
 	 *     await processBatch(rows);
 	 * });
 	 */
-	chunk(size: number, callback: (rows: DatabaseRecord[], page: number) => Promise<void | boolean> | void | boolean): Promise<void>;
+	chunk(size: number, callback: (rows: T[], page: number) => Promise<void | boolean> | void | boolean): Promise<void>;
 	/**
 	 * Atomically increments a numeric column: `SET col = col + amount`.
 	 * Requires at least one WHERE condition. Extra fields can be updated in the same statement.
@@ -537,14 +570,14 @@ export declare class Table {
 	 * await db.table('products').where('id', '=', 5).increment('stock', 3);
 	 * await db.table('posts').where('id', '=', 1).increment('views', 1, { last_viewed_at: new Date().toISOString() });
 	 */
-	increment(column: string, amount?: number, extra?: DatabaseRecord): Promise<any>;
+	increment(column: string, amount?: number, extra?: Partial<T>): Promise<MutationInfo[]>;
 	/**
 	 * Atomically decrements a numeric column: `SET col = col - amount`.
 	 *
 	 * @example
 	 * await db.table('products').where('id', '=', 5).decrement('stock', 1);
 	 */
-	decrement(column: string, amount?: number, extra?: DatabaseRecord): Promise<any>;
+	decrement(column: string, amount?: number, extra?: Partial<T>): Promise<MutationInfo[]>;
 	/**
 	 * Deletes ALL rows from the table. The only write operation allowed
 	 * without a WHERE — the destructive intent is explicit in the name.
@@ -552,7 +585,7 @@ export declare class Table {
 	 * @example
 	 * await db.table('temp_imports').truncate();
 	 */
-	truncate(): Promise<any>;
+	truncate(): Promise<MutationInfo[]>;
 	/**
 	 * Inserts rows, updating them instead when a conflict occurs on the given keys.
 	 * MySQL → ON DUPLICATE KEY UPDATE · PostgreSQL/SQLite → ON CONFLICT ... DO UPDATE.
@@ -567,7 +600,7 @@ export declare class Table {
 	 *     ['key']
 	 * );
 	 */
-	upsert(data: DatabaseRecord[], conflictKeys: string[], updateColumns?: string[]): Promise<any>;
+	upsert(data: Partial<T>[], conflictKeys: string[], updateColumns?: string[]): Promise<MutationInfo[]>;
 	/**
 	 * Declares a relation to eager-load with the results of get().
 	 * Relations are resolved from `foreign` definitions in your .cube files,
@@ -584,7 +617,7 @@ export declare class Table {
 	 *     .with('author', { table: 'users', foreignKey: 'author_id', type: 'one' })
 	 *     .get();
 	 */
-	with(relation: string, options?: RelationOptions): Table;
+	with(relation: string, options?: RelationOptions): Table<T>;
 	private attachRelations;
 	private getResponse;
 	private clone;