@dbcube/query-builder 5.1.5 → 5.1.6

package/dist/index.d.ts

@@ -1,3 +1,22 @@
+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) => void;
 export type DatabaseRecord = Record<string, any>;
 /**
@@ -9,7 +28,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(query: string, params?: any[]): Promise<any>;
+	/**
+	 * 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>;
@@ -66,7 +109,9 @@ export declare class Table {
 	private computedFields;
 	private trigger;
 	private triggers;
-	constructor(instance: any, databaseName: string, tableName: string, engine?: any, computedFields?: any[], triggers?: any[]);
+	private txId;
+	private relations;
+	constructor(instance: any, databaseName: string, tableName: string, engine?: any, computedFields?: any[], triggers?: any[], txId?: string | null);
 	/**
 	 * Specifies the columns to select in a SELECT query.
 	 *
@@ -421,6 +466,126 @@ export declare class Table {
 	 * console.log(result); // { affectedRows: 1 }
 	 */
 	delete(): Promise<any>;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * Adds a HAVING condition (filters grouped results).
+	 *
+	 * @example
+	 * .groupBy('user_id').having('COUNT(*)', '>', 5)
+	 */
+	having(column: string, operator: string, value?: any): Table;
+	/**
+	 * 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>;
+	/**
+	 * 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: DatabaseRecord[], 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?: DatabaseRecord): Promise<any>;
+	/**
+	 * 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>;
+	/**
+	 * 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<any>;
+	/**
+	 * 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: DatabaseRecord[], conflictKeys: string[], updateColumns?: string[]): Promise<any>;
+	/**
+	 * 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;
+	private attachRelations;
 	private getResponse;
 	private clone;
 }