create-phoenixjs 0.1.4 → 0.1.5

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

@@ -0,0 +1,139 @@
+/**
+ * PhoenixJS ORM - DB Facade
+ *
+ * Static facade for database operations, providing a Laravel-like
+ * DB::table('users') interface for query building.
+ */
+
+import type { Connection } from '../connection/Connection';
+import type { Grammar } from './grammars/Grammar';
+import type { Binding } from './types';
+import { Builder } from './Builder';
+import { RawExpression } from './types';
+import { PostgresGrammar } from './grammars/PostgresGrammar';
+
+/**
+ * DB Facade
+ *
+ * Provides a static interface for database operations.
+ * Must be initialized with a connection before use.
+ */
+export class DB {
+	/** The database connection */
+	private static connection: Connection | null = null;
+
+	/** The grammar instance */
+	private static grammar: Grammar | null = null;
+
+	/**
+	 * Initialize the DB facade with a connection
+	 */
+	static init(connection: Connection, grammar?: Grammar): void {
+		DB.connection = connection;
+		DB.grammar = grammar || new PostgresGrammar();
+	}
+
+	/**
+	 * Set the database connection
+	 */
+	static setConnection(connection: Connection): void {
+		DB.connection = connection;
+	}
+
+	/**
+	 * Set the grammar
+	 */
+	static setGrammar(grammar: Grammar): void {
+		DB.grammar = grammar;
+	}
+
+	/**
+	 * Get the current connection
+	 */
+	static getConnection(): Connection {
+		if (!DB.connection) {
+			throw new Error('DB facade not initialized. Call DB.init(connection) first.');
+		}
+		return DB.connection;
+	}
+
+	/**
+	 * Get the current grammar
+	 */
+	static getGrammar(): Grammar {
+		if (!DB.grammar) {
+			DB.grammar = new PostgresGrammar();
+		}
+		return DB.grammar;
+	}
+
+	/**
+	 * Begin a fluent query against a database table
+	 */
+	static table(name: string, alias?: string): Builder {
+		const connection = DB.getConnection();
+		const grammar = DB.getGrammar();
+		const builder = new Builder(connection, grammar, name);
+
+		if (alias) {
+			builder.table(name, alias);
+		}
+
+		return builder;
+	}
+
+	/**
+	 * Execute a raw SQL query
+	 */
+	static async query<T = Record<string, unknown>>(sql: string, bindings: unknown[] = []): Promise<T[]> {
+		return DB.getConnection().query<T>(sql, bindings);
+	}
+
+	/**
+	 * Execute a raw SQL statement
+	 */
+	static async execute(sql: string, bindings: unknown[] = []): Promise<number> {
+		return DB.getConnection().execute(sql, bindings);
+	}
+
+	/**
+	 * Get a single row from a raw query
+	 */
+	static async get<T = Record<string, unknown>>(sql: string, bindings: unknown[] = []): Promise<T | null> {
+		return DB.getConnection().get<T>(sql, bindings);
+	}
+
+	/**
+	 * Execute operations within a transaction
+	 */
+	static async transaction<T>(callback: (tx: unknown) => Promise<T>): Promise<T> {
+		return DB.getConnection().transaction(callback);
+	}
+
+	/**
+	 * Create a new Builder instance with a custom connection
+	 */
+	static withConnection(connection: Connection): Builder {
+		const grammar = DB.getGrammar();
+		return new Builder(connection, grammar);
+	}
+
+	/**
+	 * Create a raw expression for use in queries
+	 * 
+	 * @example
+	 * DB.table('users').selectRaw('count(*) as user_count')
+	 * DB.table('orders').selectRaw('SUM(total) as total_sales')
+	 */
+	static raw(expression: string, bindings: Binding[] = []): RawExpression {
+		return new RawExpression(expression, bindings);
+	}
+
+	/**
+	 * Reset the DB facade (useful for testing)
+	 */
+	static reset(): void {
+		DB.connection = null;
+		DB.grammar = null;
+	}
+}

package/template/framework/database/query/grammars/Grammar.ts

@@ -0,0 +1,430 @@
+/**
+ * PhoenixJS ORM - Abstract Grammar Class
+ *
+ * Base class for SQL grammar compilation. Defines the contract for all
+ * database-specific grammar implementations. The Grammar is responsible
+ * for converting internal query representations to database-specific SQL syntax.
+ */
+
+import type {
+	QueryComponents,
+	CompiledQuery,
+	InsertValues,
+	UpdateValues,
+	Binding,
+	WhereClause,
+	JoinClause,
+	OrderClause,
+} from '../types';
+
+/**
+ * Abstract Grammar base class
+ *
+ * Subclasses must implement database-specific SQL generation.
+ */
+export abstract class Grammar {
+	/**
+	 * The grammar-specific components for SELECT statements
+	 */
+	protected selectComponents: (keyof QueryComponents)[] = [
+		'aggregate',
+		'columns',
+		'table',
+		'joins',
+		'wheres',
+		'groups',
+		'havings',
+		'orders',
+		'limit',
+		'offset',
+		'lock',
+	];
+
+	/**
+	 * Compile a SELECT query into SQL
+	 */
+	compileSelect(query: QueryComponents): CompiledQuery {
+		const bindings: Binding[] = [];
+		const sql = this.concatenate(this.compileComponents(query, bindings));
+		return { sql: sql.trim(), bindings };
+	}
+
+	/**
+	 * Compile the components of a query
+	 */
+	protected compileComponents(query: QueryComponents, bindings: Binding[]): string[] {
+		const segments: string[] = [];
+
+		for (const component of this.selectComponents) {
+			const value = query[component];
+			if (value !== undefined && value !== null) {
+				const method = `compile${this.capitalize(component)}` as keyof this;
+				if (typeof this[method] === 'function') {
+					const sql = (this[method] as (query: QueryComponents, bindings: Binding[]) => string)(
+						query,
+						bindings
+					);
+					if (sql) {
+						segments.push(sql);
+					}
+				}
+			}
+		}
+
+		return segments;
+	}
+
+	/**
+	 * Compile the "select" portion of the query
+	 */
+	protected compileColumns(query: QueryComponents, bindings: Binding[]): string {
+		// If an aggregate is set, skip columns (aggregate already includes SELECT)
+		if (query.aggregate) {
+			return '';
+		}
+
+		const select = query.distinct ? 'SELECT DISTINCT' : 'SELECT';
+		const columns: string[] = [];
+
+		// Add regular columns
+		if (query.columns.length > 0) {
+			columns.push(this.columnize(query.columns));
+		}
+
+		// Add raw select expressions
+		if (query.rawSelects.length > 0) {
+			for (const raw of query.rawSelects) {
+				columns.push(raw.expression);
+				bindings.push(...raw.bindings);
+			}
+		}
+
+		if (columns.length === 0) {
+			return `${select} *`;
+		}
+
+		return `${select} ${columns.join(', ')}`;
+	}
+
+	/**
+	 * Compile the "from" portion of the query
+	 */
+	protected compileTable(query: QueryComponents, _bindings: Binding[]): string {
+		const table = this.wrapTable(query.table);
+		if (query.alias) {
+			return `FROM ${table} AS ${this.wrap(query.alias)}`;
+		}
+		return `FROM ${table}`;
+	}
+
+	/**
+	 * Compile the aggregate function portion
+	 */
+	protected compileAggregate(query: QueryComponents, _bindings: Binding[]): string {
+		if (!query.aggregate) return '';
+
+		const column =
+			query.aggregate.column === '*' ? '*' : this.wrap(query.aggregate.column);
+		return `SELECT ${query.aggregate.function.toUpperCase()}(${column})`;
+	}
+
+	/**
+	 * Compile the "join" portions of the query
+	 */
+	protected compileJoins(query: QueryComponents, _bindings: Binding[]): string {
+		if (query.joins.length === 0) return '';
+
+		return query.joins.map((join) => this.compileJoin(join)).join(' ');
+	}
+
+	/**
+	 * Compile a single join clause
+	 */
+	protected compileJoin(join: JoinClause): string {
+		const table = this.wrapTable(join.table);
+		const joinType = this.getJoinType(join.type);
+
+		// Cross join doesn't have ON clause
+		if (join.type === 'cross') {
+			return `${joinType} JOIN ${table}`;
+		}
+
+		const first = this.wrap(join.first);
+		const second = this.wrap(join.second);
+
+		return `${joinType} JOIN ${table} ON ${first} ${join.operator} ${second}`;
+	}
+
+	/**
+	 * Get the join type keyword
+	 */
+	protected getJoinType(type: JoinClause['type']): string {
+		switch (type) {
+			case 'inner':
+				return 'INNER';
+			case 'left':
+				return 'LEFT';
+			case 'right':
+				return 'RIGHT';
+			case 'cross':
+				return 'CROSS';
+			default:
+				return 'INNER';
+		}
+	}
+
+	/**
+	 * Compile the "where" portions of the query
+	 */
+	compileWheres(query: QueryComponents, bindings: Binding[]): string {
+		if (query.wheres.length === 0) return '';
+
+		const sql = query.wheres
+			.map((where, index) => {
+				const prefix = index === 0 ? '' : `${where.boolean.toUpperCase()} `;
+				return prefix + this.compileWhere(where, bindings);
+			})
+			.join(' ');
+
+		return `WHERE ${sql}`;
+	}
+
+	/**
+	 * Compile a single where clause
+	 */
+	protected compileWhere(where: WhereClause, bindings: Binding[]): string {
+		switch (where.type) {
+			case 'basic':
+				return this.compileBasicWhere(where, bindings);
+			case 'in':
+				return this.compileInWhere(where, bindings);
+			case 'null':
+				return this.compileNullWhere(where);
+			case 'between':
+				return this.compileBetweenWhere(where, bindings);
+			case 'raw':
+				return this.compileRawWhere(where, bindings);
+			case 'nested':
+				return this.compileNestedWhere(where, bindings);
+			default:
+				throw new Error(`Unknown where type: ${where.type}`);
+		}
+	}
+
+	/**
+	 * Compile a basic where clause
+	 */
+	protected abstract compileBasicWhere(where: WhereClause, bindings: Binding[]): string;
+
+	/**
+	 * Compile a where in clause
+	 */
+	protected abstract compileInWhere(where: WhereClause, bindings: Binding[]): string;
+
+	/**
+	 * Compile a where null clause
+	 */
+	protected compileNullWhere(where: WhereClause): string {
+		const column = this.wrap(where.column!);
+		return where.not ? `${column} IS NOT NULL` : `${column} IS NULL`;
+	}
+
+	/**
+	 * Compile a where between clause
+	 */
+	protected abstract compileBetweenWhere(where: WhereClause, bindings: Binding[]): string;
+
+	/**
+	 * Compile a raw where clause
+	 */
+	protected compileRawWhere(where: WhereClause, bindings: Binding[]): string {
+		if (where.bindings) {
+			bindings.push(...where.bindings);
+		}
+		return where.sql!;
+	}
+
+	/**
+	 * Compile a nested where clause
+	 */
+	protected compileNestedWhere(where: WhereClause, bindings: Binding[]): string {
+		if (!where.nested || where.nested.length === 0) return '';
+
+		const nestedSql = where.nested
+			.map((nested, index) => {
+				const prefix = index === 0 ? '' : `${nested.boolean.toUpperCase()} `;
+				return prefix + this.compileWhere(nested, bindings);
+			})
+			.join(' ');
+
+		return `(${nestedSql})`;
+	}
+
+	/**
+	 * Compile the "group by" portions of the query
+	 */
+	protected compileGroups(query: QueryComponents, bindings: Binding[]): string {
+		const groups: string[] = [];
+
+		// Add regular group by columns
+		if (query.groups.length > 0) {
+			groups.push(this.columnize(query.groups));
+		}
+
+		// Add raw group by expressions
+		if (query.rawGroups.length > 0) {
+			for (const raw of query.rawGroups) {
+				groups.push(raw.expression);
+				bindings.push(...raw.bindings);
+			}
+		}
+
+		if (groups.length === 0) return '';
+
+		return `GROUP BY ${groups.join(', ')}`;
+	}
+
+	/**
+	 * Compile the "having" portions of the query
+	 */
+	protected compileHavings(query: QueryComponents, bindings: Binding[]): string {
+		if (query.havings.length === 0) return '';
+
+		const sql = query.havings
+			.map((having, index) => {
+				const prefix = index === 0 ? '' : `${having.boolean.toUpperCase()} `;
+				return prefix + this.compileWhere(having, bindings);
+			})
+			.join(' ');
+
+		return `HAVING ${sql}`;
+	}
+
+	/**
+	 * Compile the "order by" portions of the query
+	 */
+	protected compileOrders(query: QueryComponents, bindings: Binding[]): string {
+		if (query.orders.length === 0) return '';
+
+		// Add order bindings (for raw order expressions)
+		if (query.orderBindings.length > 0) {
+			bindings.push(...query.orderBindings);
+		}
+
+		return `ORDER BY ${query.orders.map((order) => this.compileOrder(order)).join(', ')}`;
+	}
+
+	/**
+	 * Compile a single order clause
+	 */
+	protected compileOrder(order: OrderClause): string {
+		// Raw order expressions are used as-is
+		if (order.raw) {
+			return order.column;
+		}
+		return `${this.wrap(order.column)} ${order.direction.toUpperCase()}`;
+	}
+
+	/**
+	 * Compile the "limit" portions of the query
+	 */
+	/**
+	 * Compile the "limit" portions of the query
+	 */
+	protected compileLimit(query: QueryComponents, bindings: Binding[]): string {
+		if (query.limit === undefined) return '';
+
+		bindings.push(query.limit);
+		return `LIMIT ${this.parameterize([query.limit], bindings.length)}`;
+	}
+
+	/**
+	 * Compile the "offset" portions of the query
+	 */
+	protected compileOffset(query: QueryComponents, bindings: Binding[]): string {
+		if (query.offset === undefined) return '';
+
+		bindings.push(query.offset);
+		return `OFFSET ${this.parameterize([query.offset], bindings.length)}`;
+	}
+
+	/**
+	 * Compile the lock clause
+	 */
+	protected compileLock(query: QueryComponents, _bindings: Binding[]): string {
+		if (!query.lock) return '';
+		return query.lock.toUpperCase();
+	}
+
+	/**
+	 * Compile an INSERT statement
+	 */
+	abstract compileInsert(query: QueryComponents, values: InsertValues | InsertValues[]): CompiledQuery;
+
+	/**
+	 * Compile an INSERT statement with RETURNING
+	 */
+	abstract compileInsertReturning(
+		query: QueryComponents,
+		values: InsertValues | InsertValues[],
+		returning: string[]
+	): CompiledQuery;
+
+	/**
+	 * Compile an UPDATE statement
+	 */
+	abstract compileUpdate(query: QueryComponents, values: UpdateValues): CompiledQuery;
+
+	/**
+	 * Compile a DELETE statement
+	 */
+	abstract compileDelete(query: QueryComponents): CompiledQuery;
+
+	/**
+	 * Compile a truncate table statement
+	 */
+	abstract compileTruncate(table: string): string;
+
+	/**
+	 * Wrap a table in keyword identifiers
+	 */
+	wrapTable(table: string): string {
+		return this.wrap(table);
+	}
+
+	/**
+	 * Wrap a value in keyword identifiers
+	 */
+	abstract wrap(value: string): string;
+
+	/**
+	 * Convert an array of column names into a delimited string
+	 */
+	columnize(columns: string[]): string {
+		return columns.map((column) => this.wrap(column)).join(', ');
+	}
+
+	/**
+	 * Create query parameter placeholders for values
+	 */
+	abstract parameterize(values: Binding[], startIndex?: number): string;
+
+	/**
+	 * Get the grammar's parameter prefix
+	 */
+	abstract getParameterPrefix(): string;
+
+	/**
+	 * Concatenate an array of segments into a single string
+	 */
+	protected concatenate(segments: string[]): string {
+		return segments.filter((segment) => segment !== '').join(' ');
+	}
+
+	/**
+	 * Capitalize the first letter of a string
+	 */
+	protected capitalize(str: string): string {
+		return str.charAt(0).toUpperCase() + str.slice(1);
+	}
+}