@dbcube/query-builder 5.1.5 → 5.2.1

package/dist/index.d.mts

@@ -1,5 +1,51 @@
-export type WhereCallback = (query: Table) => void;
+import { QueryEngine } from '@dbcube/core';
+
+export interface PaginatedResult<T = DatabaseRecord> {
+	items: T[];
+	page: number;
+	perPage: number;
+	total: number;
+	totalPages: number;
+	hasNext: boolean;
+	hasPrev: boolean;
+}
+export interface RelationOptions {
+	/** Child/related table name (defaults to the relation name) */
+	table?: string;
+	/** FK column on the related table (hasMany) or on this table (belongsTo) */
+	foreignKey?: string;
+	/** Key on the parent table (defaults to 'id') */
+	localKey?: string;
+	/** 'many' attaches an array (hasMany), 'one' attaches a single record (belongsTo) */
+	type?: "many" | "one";
+}
+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.
@@ -9,7 +55,31 @@ export declare class Database {
 	private engine;
 	private computedFields;
 	private triggers;
+	private txId;
 	constructor(name: string);
+	/**
+	 * Executes raw SQL (MySQL/PostgreSQL/SQLite) or a raw command document (MongoDB)
+	 * with bound parameters. The escape hatch for anything the builder doesn't cover.
+	 *
+	 * @example
+	 * const rows = await db.raw('SELECT * FROM users WHERE age > ?', [25]);
+	 * await db.raw('CREATE INDEX idx_users_email ON users(email)');
+	 */
+	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
+	 * the whole transaction back.
+	 *
+	 * Requires daemon mode (enabled by default with an up-to-date query-engine).
+	 *
+	 * @example
+	 * await db.transaction(async (trx) => {
+	 *     await trx.table('accounts').where('id', '=', 1).update({ balance: 50 });
+	 *     await trx.table('accounts').where('id', '=', 2).update({ balance: 150 });
+	 * });
+	 */
+	transaction<T>(callback: (trx: Database) => Promise<T>): Promise<T>;
 	useComputes(): Promise<Database>;
 	useTriggers(): Promise<Database>;
 	connect(): Promise<void>;
@@ -51,22 +121,30 @@ 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;
 	private computedFields;
 	private trigger;
 	private triggers;
-	constructor(instance: any, databaseName: string, tableName: string, engine?: any, computedFields?: any[], triggers?: any[]);
+	private txId;
+	private relations;
+	/** 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.
 	 *
@@ -77,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.
 	 *
@@ -91,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.
 	 *
@@ -106,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.
 	 *
@@ -120,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.
 	 *
@@ -137,7 +215,7 @@ export declare class Table {
 	whereBetween(column: string, values: [
 		any,
 		any
-	]): Table;
+	]): Table<T>;
 	/**
 	 * Adds a WHERE IN condition to the query.
 	 *
@@ -149,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.
 	*
@@ -160,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.
 	 *
@@ -171,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.
 	 *
@@ -185,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.
 	 *
@@ -199,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.
 	 *
@@ -213,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.
 	 *
@@ -225,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.
 	 *
@@ -236,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.
 	 *
@@ -246,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.
 	 *
@@ -257,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.
 	 *
@@ -268,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.
 	 *
@@ -279,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.
 	 *
@@ -290,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.
 	 *
@@ -301,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.
@@ -340,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.
 	 *
@@ -351,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.
 	*
@@ -361,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.
 	 *
@@ -371,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.
 	 *
@@ -383,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.
 	 *
@@ -397,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.
 	 *
@@ -410,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.
 	 *
@@ -420,7 +498,127 @@ 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<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<T>;
+	/**
+	 * Appends raw expressions to the SELECT list (aggregates, functions, aliases).
+	 * Combine with groupBy() and having() for per-group metrics.
+	 *
+	 * @example
+	 * const stats = await db.table('orders')
+	 *     .select(['user_id'])
+	 *     .selectRaw(['COUNT(*) AS order_count', 'SUM(amount) AS total'])
+	 *     .groupBy('user_id')
+	 *     .having('order_count', '>', 5)
+	 *     .get();
+	 */
+	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<T>;
+	/**
+	 * Checks if at least one row matches the current conditions.
+	 * Cheaper than first(): selects a constant with LIMIT 1.
+	 *
+	 * @example
+	 * const taken = await db.table('users').where('email', '=', email).exists();
+	 */
+	exists(): Promise<boolean>;
+	/**
+	 * Fetches one page of results plus pagination metadata in a single call.
+	 * Runs the page query and the total count with the same conditions.
+	 *
+	 * @example
+	 * const { items, total, totalPages, hasNext } = await db.table('products')
+	 *     .where('published', '=', true)
+	 *     .orderBy('id', 'ASC')
+	 *     .paginate(2, 25);
+	 */
+	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.
+	 *
+	 * @example
+	 * await db.table('logs').orderBy('id', 'ASC').chunk(500, async (rows) => {
+	 *     await processBatch(rows);
+	 * });
+	 */
+	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.
+	 *
+	 * @example
+	 * 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?: 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?: 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.
+	 *
+	 * @example
+	 * await db.table('temp_imports').truncate();
+	 */
+	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.
+	 *
+	 * @param data Rows to insert.
+	 * @param conflictKeys Column(s) with the UNIQUE/PK constraint that triggers the update.
+	 * @param updateColumns Columns to overwrite on conflict (defaults to every non-conflict column).
+	 *
+	 * @example
+	 * await db.table('settings').upsert(
+	 *     [{ key: 'theme', value: 'dark' }],
+	 *     ['key']
+	 * );
+	 */
+	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,
+	 * or explicitly via options. Loads each relation with ONE batched query
+	 * (whereIn) — no N+1.
+	 *
+	 * @example
+	 * // hasMany: orders.user_id → users.id (auto-detected from orders.table.cube)
+	 * const users = await db.table('users').with('orders').get();
+	 * // users[0].orders === [{...}, {...}]
+	 *
+	 * // belongsTo: posts.author_id → users.id, attached as a single object
+	 * const posts = await db.table('posts')
+	 *     .with('author', { table: 'users', foreignKey: 'author_id', type: 'one' })
+	 *     .get();
+	 */
+	with(relation: string, options?: RelationOptions): Table<T>;
+	private attachRelations;
 	private getResponse;
 	private clone;
 }