create-phoenixjs 0.1.3 → 0.1.5

package/template/framework/database/query/Builder.ts

@@ -0,0 +1,918 @@
+/**
+ * PhoenixJS ORM - Query Builder
+ *
+ * Fluent interface for building and executing SQL queries.
+ * Inspired by Laravel's Query Builder with full TypeScript support.
+ */
+
+import type { Connection } from '../connection/Connection';
+import type { Grammar } from './grammars/Grammar';
+import type {
+	QueryComponents,
+	WhereClause,
+	OrderClause,
+	JoinClause,
+	JoinType,
+	Binding,
+	WhereOperator,
+	OrderDirection,
+	AggregateFunction,
+	InsertValues,
+	UpdateValues,
+} from './types';
+import { createQueryComponents } from './types';
+import { Paginator } from '../pagination/Paginator';
+import { LengthAwarePaginator } from '../pagination/LengthAwarePaginator';
+
+/**
+ * Query Builder
+ *
+ * Provides a fluent interface for building SQL queries.
+ * Works with any Grammar implementation for database-specific SQL generation.
+ */
+export class Builder {
+	/** Query state components */
+	protected query: QueryComponents;
+
+	/** The database connection */
+	protected connection: Connection;
+
+	/** The grammar for compiling queries */
+	protected grammar: Grammar;
+
+	constructor(connection: Connection, grammar: Grammar, table?: string) {
+		this.connection = connection;
+		this.grammar = grammar;
+		this.query = createQueryComponents(table || '');
+	}
+
+	// ==========================================
+	// Table & Column Selection
+	// ==========================================
+
+	/**
+	 * Set the table the query is targeting
+	 */
+	table(name: string, alias?: string): this {
+		this.query.table = name;
+		if (alias) {
+			this.query.alias = alias;
+		}
+		return this;
+	}
+
+	/**
+	 * Alias for table()
+	 */
+	from(name: string, alias?: string): this {
+		return this.table(name, alias);
+	}
+
+	/**
+	 * Set the columns to be selected
+	 */
+	select(...columns: string[]): this {
+		this.query.columns = columns.length > 0 ? columns : ['*'];
+		return this;
+	}
+
+	/**
+	 * Add a column to the select list
+	 */
+	addSelect(...columns: string[]): this {
+		this.query.columns.push(...columns);
+		return this;
+	}
+
+	/**
+	 * Force the query to use DISTINCT
+	 */
+	distinct(): this {
+		this.query.distinct = true;
+		return this;
+	}
+
+	/**
+	 * Add a raw expression to the select clause
+	 */
+	selectRaw(expression: string, bindings: Binding[] = []): this {
+		this.query.rawSelects.push({ expression, bindings });
+		return this;
+	}
+
+	// ==========================================
+	// JOIN Clauses
+	// ==========================================
+
+	/**
+	 * Add an inner join clause
+	 */
+	join(table: string, first: string, operator: string, second: string): this {
+		return this.addJoin('inner', table, first, operator, second);
+	}
+
+	/**
+	 * Add a left join clause
+	 */
+	leftJoin(table: string, first: string, operator: string, second: string): this {
+		return this.addJoin('left', table, first, operator, second);
+	}
+
+	/**
+	 * Add a right join clause
+	 */
+	rightJoin(table: string, first: string, operator: string, second: string): this {
+		return this.addJoin('right', table, first, operator, second);
+	}
+
+	/**
+	 * Add a cross join clause (no ON clause)
+	 */
+	crossJoin(table: string): this {
+		// Cross join doesn't have ON clause, use empty strings for first/second
+		const joinClause: JoinClause = {
+			type: 'cross',
+			table,
+			first: '',
+			operator: '',
+			second: '',
+		};
+		this.query.joins.push(joinClause);
+		return this;
+	}
+
+	/**
+	 * Internal method to add a join clause
+	 */
+	protected addJoin(
+		type: JoinType,
+		table: string,
+		first: string,
+		operator: string,
+		second: string
+	): this {
+		const joinClause: JoinClause = {
+			type,
+			table,
+			first,
+			operator,
+			second,
+		};
+		this.query.joins.push(joinClause);
+		return this;
+	}
+
+	// ==========================================
+	// WHERE Clauses
+	// ==========================================
+
+	/**
+	 * Add a basic WHERE clause
+	 */
+	where(column: string, operatorOrValue?: WhereOperator | string | Binding, value?: Binding): this {
+		return this.addWhere(column, operatorOrValue, value, 'and');
+	}
+
+	/**
+	 * Add an OR WHERE clause
+	 */
+	orWhere(column: string, operatorOrValue?: WhereOperator | string | Binding, value?: Binding): this {
+		return this.addWhere(column, operatorOrValue, value, 'or');
+	}
+
+	/**
+	 * Internal method to add a WHERE clause
+	 */
+	protected addWhere(
+		column: string,
+		operatorOrValue?: WhereOperator | string | Binding,
+		value?: Binding,
+		boolean: 'and' | 'or' = 'and'
+	): this {
+		// Handle (column, value) syntax - default to '=' operator
+		let operator: WhereOperator | string = '=';
+		let finalValue: Binding;
+
+		if (value === undefined) {
+			finalValue = operatorOrValue as Binding;
+		} else {
+			operator = operatorOrValue as WhereOperator | string;
+			finalValue = value;
+		}
+
+		const whereClause: WhereClause = {
+			type: 'basic',
+			column,
+			operator,
+			value: finalValue,
+			boolean,
+		};
+
+		this.query.wheres.push(whereClause);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IN clause
+	 */
+	whereIn(column: string, values: Binding[]): this {
+		this.query.wheres.push({
+			type: 'in',
+			column,
+			value: values,
+			boolean: 'and',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE IN clause
+	 */
+	orWhereIn(column: string, values: Binding[]): this {
+		this.query.wheres.push({
+			type: 'in',
+			column,
+			value: values,
+			boolean: 'or',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NOT IN clause
+	 */
+	whereNotIn(column: string, values: Binding[]): this {
+		this.query.wheres.push({
+			type: 'in',
+			column,
+			value: values,
+			boolean: 'and',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE NOT IN clause
+	 */
+	orWhereNotIn(column: string, values: Binding[]): this {
+		this.query.wheres.push({
+			type: 'in',
+			column,
+			value: values,
+			boolean: 'or',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IS NULL clause
+	 */
+	whereNull(column: string): this {
+		this.query.wheres.push({
+			type: 'null',
+			column,
+			boolean: 'and',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE IS NULL clause
+	 */
+	orWhereNull(column: string): this {
+		this.query.wheres.push({
+			type: 'null',
+			column,
+			boolean: 'or',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IS NOT NULL clause
+	 */
+	whereNotNull(column: string): this {
+		this.query.wheres.push({
+			type: 'null',
+			column,
+			boolean: 'and',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE IS NOT NULL clause
+	 */
+	orWhereNotNull(column: string): this {
+		this.query.wheres.push({
+			type: 'null',
+			column,
+			boolean: 'or',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a WHERE BETWEEN clause
+	 */
+	whereBetween(column: string, values: [Binding, Binding]): this {
+		this.query.wheres.push({
+			type: 'between',
+			column,
+			values,
+			boolean: 'and',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE BETWEEN clause
+	 */
+	orWhereBetween(column: string, values: [Binding, Binding]): this {
+		this.query.wheres.push({
+			type: 'between',
+			column,
+			values,
+			boolean: 'or',
+			not: false,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NOT BETWEEN clause
+	 */
+	whereNotBetween(column: string, values: [Binding, Binding]): this {
+		this.query.wheres.push({
+			type: 'between',
+			column,
+			values,
+			boolean: 'and',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE NOT BETWEEN clause
+	 */
+	orWhereNotBetween(column: string, values: [Binding, Binding]): this {
+		this.query.wheres.push({
+			type: 'between',
+			column,
+			values,
+			boolean: 'or',
+			not: true,
+		});
+		return this;
+	}
+
+	/**
+	 * Add a raw WHERE clause
+	 */
+	whereRaw(sql: string, bindings: Binding[] = []): this {
+		this.query.wheres.push({
+			type: 'raw',
+			sql,
+			bindings,
+			boolean: 'and',
+		});
+		return this;
+	}
+
+	/**
+	 * Add a raw OR WHERE clause
+	 */
+	orWhereRaw(sql: string, bindings: Binding[] = []): this {
+		this.query.wheres.push({
+			type: 'raw',
+			sql,
+			bindings,
+			boolean: 'or',
+		});
+		return this;
+	}
+
+	// ==========================================
+	// Ordering, Grouping, Limit & Offset
+	// ==========================================
+
+	/**
+	 * Add an ORDER BY clause
+	 */
+	orderBy(column: string, direction: OrderDirection = 'asc'): this {
+		const order: OrderClause = {
+			column,
+			direction: direction.toLowerCase() as OrderDirection,
+		};
+		this.query.orders.push(order);
+		return this;
+	}
+
+	/**
+	 * Add a descending ORDER BY clause
+	 */
+	orderByDesc(column: string): this {
+		return this.orderBy(column, 'desc');
+	}
+
+	/**
+	 * Order by latest (created_at DESC)
+	 */
+	latest(column: string = 'created_at'): this {
+		return this.orderBy(column, 'desc');
+	}
+
+	/**
+	 * Order by oldest (created_at ASC)
+	 */
+	oldest(column: string = 'created_at'): this {
+		return this.orderBy(column, 'asc');
+	}
+
+	/**
+	 * Add a raw ORDER BY expression
+	 */
+	orderByRaw(expression: string, bindings: Binding[] = []): this {
+		const order: OrderClause = {
+			column: expression,
+			direction: 'asc', // Direction is ignored for raw expressions
+			raw: true,
+		};
+		this.query.orders.push(order);
+		this.query.orderBindings.push(...bindings);
+		return this;
+	}
+
+	// ==========================================
+	// GROUP BY & HAVING Clauses
+	// ==========================================
+
+	/**
+	 * Add GROUP BY columns
+	 */
+	groupBy(...columns: string[]): this {
+		this.query.groups.push(...columns);
+		return this;
+	}
+
+	/**
+	 * Add a raw GROUP BY expression
+	 */
+	groupByRaw(expression: string, bindings: Binding[] = []): this {
+		this.query.rawGroups.push({ expression, bindings });
+		return this;
+	}
+
+	/**
+	 * Add a HAVING clause
+	 */
+	having(column: string, operatorOrValue: string | Binding, value?: Binding): this {
+		return this.addHaving(column, operatorOrValue, value, 'and');
+	}
+
+	/**
+	 * Add an OR HAVING clause
+	 */
+	orHaving(column: string, operatorOrValue: string | Binding, value?: Binding): this {
+		return this.addHaving(column, operatorOrValue, value, 'or');
+	}
+
+	/**
+	 * Add a raw HAVING clause
+	 */
+	havingRaw(sql: string, bindings: Binding[] = []): this {
+		this.query.havings.push({
+			type: 'raw',
+			sql,
+			bindings,
+			boolean: 'and',
+		});
+		return this;
+	}
+
+	/**
+	 * Add a raw OR HAVING clause
+	 */
+	orHavingRaw(sql: string, bindings: Binding[] = []): this {
+		this.query.havings.push({
+			type: 'raw',
+			sql,
+			bindings,
+			boolean: 'or',
+		});
+		return this;
+	}
+
+	/**
+	 * Internal method to add a HAVING clause
+	 */
+	protected addHaving(
+		column: string,
+		operatorOrValue: string | Binding,
+		value: Binding | undefined,
+		boolean: 'and' | 'or'
+	): this {
+		// Handle (column, value) syntax - default to '=' operator
+		let operator: string = '=';
+		let finalValue: Binding;
+
+		if (value === undefined) {
+			finalValue = operatorOrValue as Binding;
+		} else {
+			operator = operatorOrValue as string;
+			finalValue = value;
+		}
+
+		const havingClause: WhereClause = {
+			type: 'basic',
+			column,
+			operator,
+			value: finalValue,
+			boolean,
+		};
+
+		this.query.havings.push(havingClause);
+		return this;
+	}
+
+	// ==========================================
+	// Limit & Offset
+	// ==========================================
+
+	/**
+	 * Set the LIMIT value
+	 */
+	limit(value: number): this {
+		this.query.limit = Math.max(0, parseInt(String(value), 10));
+		return this;
+	}
+
+	/**
+	 * Alias for limit()
+	 */
+	take(value: number): this {
+		return this.limit(value);
+	}
+
+	/**
+	 * Set the OFFSET value
+	 */
+	offset(value: number): this {
+		this.query.offset = Math.max(0, parseInt(String(value), 10));
+		return this;
+	}
+
+	/**
+	 * Alias for offset()
+	 */
+	skip(value: number): this {
+		return this.offset(value);
+	}
+
+	/**
+	 * Set limit and offset for pagination
+	 */
+	forPage(page: number, perPage: number = 15): this {
+		const safePage = Math.max(1, parseInt(String(page), 10));
+		const safePerPage = Math.max(1, parseInt(String(perPage), 10));
+		return this.offset((safePage - 1) * safePerPage).limit(safePerPage);
+	}
+
+	/**
+	 * Paginate the given query.
+	 */
+	async paginate<T = Record<string, unknown>>(
+		perPage: number = 15,
+		columns: string[] = ['*'],
+		pageName: string = 'page',
+		page?: number
+	): Promise<LengthAwarePaginator<T>> {
+		// Determine current page
+		// In a real app, this would come from the request.
+		// For now, we rely on the passed 'page' argument or default to 1.
+		const currentPage = page || 1;
+
+		// Get total count
+		// const total = await this.count(); // Removed incorrect call
+
+		// Get items
+		// We clone the builder to avoid modifying the original query for the count 
+		const countBuilder = this.clone();
+		// Remove orders and limits for count
+		countBuilder.query.orders = [];
+		countBuilder.query.limit = undefined;
+		countBuilder.query.offset = undefined;
+
+		const totalCount = await countBuilder.count();
+
+		// Get items
+		this.forPage(currentPage, perPage);
+		this.query.columns = columns.length > 0 ? columns : ['*'];
+		const results = await this.get<T>();
+
+		return new LengthAwarePaginator<T>(results, totalCount, perPage, currentPage, {
+			path: '/', // TODO: Get from request
+			query: {}, // TODO: Get from request
+		});
+	}
+
+	/**
+	 * Paginate the given query into a simple paginator.
+	 */
+	async simplePaginate<T = Record<string, unknown>>(
+		perPage: number = 15,
+		columns: string[] = ['*'],
+		pageName: string = 'page',
+		page?: number
+	): Promise<Paginator<T>> {
+		const currentPage = page || 1;
+
+		// We request one more item to check if there are more pages
+		this.offset((currentPage - 1) * perPage).limit(perPage + 1);
+		this.query.columns = columns.length > 0 ? columns : ['*'];
+
+		const results = await this.get<T>();
+
+		// Check if we have more items
+		const hasMore = results.length > perPage;
+
+		// Remove the extra item
+		if (hasMore) {
+			results.pop();
+		}
+
+		return new Paginator<T>(results, perPage, currentPage, {
+			path: '/', // TODO: Get from request
+			query: {}, // TODO: Get from request
+			hasMore,
+		});
+	}
+
+	// ==========================================
+	// Execution Methods
+	// ==========================================
+
+	/**
+	 * Execute the query and return all results
+	 */
+	async get<T = Record<string, unknown>>(): Promise<T[]> {
+		const { sql, bindings } = this.grammar.compileSelect(this.query);
+		return this.connection.query<T>(sql, bindings);
+	}
+
+	/**
+	 * Execute the query and return the first result
+	 */
+	async first<T = Record<string, unknown>>(): Promise<T | null> {
+		this.limit(1);
+		const { sql, bindings } = this.grammar.compileSelect(this.query);
+		return this.connection.get<T>(sql, bindings);
+	}
+
+	/**
+	 * Find a record by its primary key
+	 */
+	async find<T = Record<string, unknown>>(id: number | string, primaryKey: string = 'id'): Promise<T | null> {
+		return this.where(primaryKey, '=', id).first<T>();
+	}
+
+	/**
+	 * Get the value of a single column from the first result
+	 */
+	async value<T = Binding>(column: string): Promise<T | null> {
+		this.select(column);
+		const result = await this.first<Record<string, T>>();
+		return result ? result[column] : null;
+	}
+
+	/**
+	 * Get an array of values from a single column
+	 */
+	async pluck<T = Binding>(column: string): Promise<T[]> {
+		this.select(column);
+		const results = await this.get<Record<string, T>>();
+		return results.map((row) => row[column]);
+	}
+
+	/**
+	 * Check if any records exist
+	 */
+	async exists(): Promise<boolean> {
+		const result = await this.limit(1).get();
+		return result.length > 0;
+	}
+
+	/**
+	 * Check if no records exist
+	 */
+	async doesntExist(): Promise<boolean> {
+		return !(await this.exists());
+	}
+
+	// ==========================================
+	// Aggregate Functions
+	// ==========================================
+
+	/**
+	 * Get the count of records
+	 */
+	async count(column: string = '*'): Promise<number> {
+		return this.aggregate('count', column);
+	}
+
+	/**
+	 * Get the sum of a column
+	 */
+	async sum(column: string): Promise<number> {
+		return this.aggregate('sum', column);
+	}
+
+	/**
+	 * Get the average of a column
+	 */
+	async avg(column: string): Promise<number> {
+		return this.aggregate('avg', column);
+	}
+
+	/**
+	 * Get the minimum value of a column
+	 */
+	async min(column: string): Promise<number> {
+		return this.aggregate('min', column);
+	}
+
+	/**
+	 * Get the maximum value of a column
+	 */
+	async max(column: string): Promise<number> {
+		return this.aggregate('max', column);
+	}
+
+	/**
+	 * Execute an aggregate function
+	 */
+	protected async aggregate(fn: AggregateFunction, column: string): Promise<number> {
+		this.query.aggregate = { function: fn, column };
+		const { sql, bindings } = this.grammar.compileSelect(this.query);
+		const result = await this.connection.get<Record<string, number | string | null>>(sql, bindings);
+
+		// Reset aggregate for potential reuse
+		this.query.aggregate = undefined;
+
+		if (!result) return 0;
+
+		// PostgreSQL returns the aggregate in the first column
+		const value = Object.values(result)[0];
+		return value !== null ? Number(value) : 0;
+	}
+
+	// ==========================================
+	// Insert Operations
+	// ==========================================
+
+	/**
+	 * Insert a new record
+	 */
+	async insert(values: InsertValues | InsertValues[]): Promise<boolean> {
+		const { sql, bindings } = this.grammar.compileInsert(this.query, values);
+		const affected = await this.connection.execute(sql, bindings);
+		return affected > 0;
+	}
+
+	/**
+	 * Insert a record and get the ID
+	 */
+	async insertGetId(values: InsertValues, primaryKey: string = 'id'): Promise<number | null> {
+		const { sql, bindings } = this.grammar.compileInsertReturning(this.query, values, [primaryKey]);
+		const result = await this.connection.query<Record<string, number>>(sql, bindings);
+		return result.length > 0 ? result[0][primaryKey] : null;
+	}
+
+	/**
+	 * Insert a record and return the inserted row
+	 */
+	async insertReturning<T = Record<string, unknown>>(
+		values: InsertValues,
+		returning: string[] = []
+	): Promise<T | null> {
+		const { sql, bindings } = this.grammar.compileInsertReturning(this.query, values, returning);
+		const result = await this.connection.query<T>(sql, bindings);
+		return result.length > 0 ? result[0] : null;
+	}
+
+	// ==========================================
+	// Update Operations
+	// ==========================================
+
+	/**
+	 * Update records
+	 */
+	async update(values: UpdateValues): Promise<number> {
+		const { sql, bindings } = this.grammar.compileUpdate(this.query, values);
+		return this.connection.execute(sql, bindings);
+	}
+
+	/**
+	 * Increment a column value
+	 */
+	async increment(column: string, amount: number = 1, extra: UpdateValues = {}): Promise<number> {
+		// For increment, we need raw SQL
+		const updateValues: UpdateValues = { ...extra };
+		// Use raw expression for increment
+		const incrementSql = `${this.grammar.wrap(column)} + ${amount}`;
+
+		// Build update manually with raw increment
+		const table = this.grammar.wrapTable(this.query.table);
+		const bindings: Binding[] = [];
+
+		// Extra values first
+		const setClauses: string[] = [];
+		for (const [key, value] of Object.entries(extra)) {
+			bindings.push(value);
+			setClauses.push(`${this.grammar.wrap(key)} = $${bindings.length}`);
+		}
+
+		// Add increment column
+		setClauses.push(`${this.grammar.wrap(column)} = ${incrementSql}`);
+
+		// Compile where clause
+		const { sql: whereSql, bindings: whereBindings } = this.compileWhereClause();
+		bindings.push(...whereBindings);
+
+		const sql = `UPDATE ${table} SET ${setClauses.join(', ')}${whereSql ? ` ${whereSql}` : ''}`;
+		return this.connection.execute(sql, bindings);
+	}
+
+	/**
+	 * Decrement a column value
+	 */
+	async decrement(column: string, amount: number = 1, extra: UpdateValues = {}): Promise<number> {
+		return this.increment(column, -amount, extra);
+	}
+
+	// ==========================================
+	// Delete Operations
+	// ==========================================
+
+	/**
+	 * Delete records
+	 */
+	async delete(): Promise<number> {
+		const { sql, bindings } = this.grammar.compileDelete(this.query);
+		return this.connection.execute(sql, bindings);
+	}
+
+	/**
+	 * Truncate the table
+	 */
+	async truncate(): Promise<void> {
+		const sql = this.grammar.compileTruncate(this.query.table);
+		await this.connection.execute(sql);
+	}
+
+	// ==========================================
+	// Utility Methods
+	// ==========================================
+
+	/**
+	 * Get the raw query components
+	 */
+	getQuery(): QueryComponents {
+		return this.query;
+	}
+
+	/**
+	 * Get the compiled SQL and bindings
+	 */
+	toSql(): { sql: string; bindings: Binding[] } {
+		return this.grammar.compileSelect(this.query);
+	}
+
+	/**
+	 * Clone the builder
+	 */
+	clone(): Builder {
+		const cloned = new Builder(this.connection, this.grammar, this.query.table);
+		cloned.query = JSON.parse(JSON.stringify(this.query));
+		return cloned;
+	}
+
+	/**
+	 * Compile just the WHERE clause
+	 */
+	protected compileWhereClause(): { sql: string; bindings: Binding[] } {
+		const bindings: Binding[] = [];
+		const sql = this.grammar.compileWheres(this.query, bindings);
+		return { sql, bindings };
+	}
+}