create-phoenixjs 0.1.3 → 0.1.5

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

@@ -0,0 +1,224 @@
+/**
+ * PhoenixJS ORM - PostgreSQL Grammar
+ *
+ * PostgreSQL-specific grammar implementation for query compilation.
+ * Handles PostgreSQL parameter binding syntax ($1, $2, $3...) and
+ * PostgreSQL-specific SQL generation.
+ */
+
+import { Grammar } from './Grammar';
+import type {
+	QueryComponents,
+	CompiledQuery,
+	InsertValues,
+	UpdateValues,
+	Binding,
+	WhereClause,
+} from '../types';
+
+/**
+ * PostgreSQL Grammar implementation
+ *
+ * Compiles query builder representations into PostgreSQL-compatible SQL.
+ */
+export class PostgresGrammar extends Grammar {
+	/**
+	 * Wrap a value in PostgreSQL keyword identifiers (double quotes)
+	 */
+	wrap(value: string): string {
+		// Handle * without wrapping
+		if (value === '*') {
+			return value;
+		}
+
+		// Handle table.column format
+		if (value.includes('.')) {
+			return value
+				.split('.')
+				.map((segment) => (segment === '*' ? '*' : `"${segment}"`))
+				.join('.');
+		}
+
+		// Handle column aliases (column AS alias)
+		if (value.toLowerCase().includes(' as ')) {
+			const parts = value.split(/\s+as\s+/i);
+			return `${this.wrap(parts[0])} AS ${this.wrap(parts[1])}`;
+		}
+
+		// Handle raw expressions wrapped in parentheses
+		if (value.startsWith('(') && value.endsWith(')')) {
+			return value;
+		}
+
+		return `"${value}"`;
+	}
+
+	/**
+	 * Get the grammar's parameter prefix
+	 */
+	getParameterPrefix(): string {
+		return '$';
+	}
+
+	/**
+	 * Create query parameter placeholders for PostgreSQL ($1, $2, $3...)
+	 */
+	parameterize(values: Binding[], startIndex: number = 1): string {
+		return values.map((_, index) => `$${startIndex + index}`).join(', ');
+	}
+
+	/**
+	 * Compile a basic where clause
+	 */
+	protected compileBasicWhere(where: WhereClause, bindings: Binding[]): string {
+		const column = this.wrap(where.column!);
+		bindings.push(where.value as Binding);
+		const paramIndex = bindings.length;
+		return `${column} ${where.operator} $${paramIndex}`;
+	}
+
+	/**
+	 * Compile a where in clause
+	 */
+	protected compileInWhere(where: WhereClause, bindings: Binding[]): string {
+		const column = this.wrap(where.column!);
+		const values = where.value as Binding[];
+		const startIndex = bindings.length + 1;
+
+		values.forEach((val) => bindings.push(val));
+
+		const placeholders = values.map((_, i) => `$${startIndex + i}`).join(', ');
+		const operator = where.not ? 'NOT IN' : 'IN';
+
+		return `${column} ${operator} (${placeholders})`;
+	}
+
+	/**
+	 * Compile a where between clause
+	 */
+	protected compileBetweenWhere(where: WhereClause, bindings: Binding[]): string {
+		const column = this.wrap(where.column!);
+		const values = where.values!;
+
+		bindings.push(values[0], values[1]);
+		const param1 = bindings.length - 1;
+		const param2 = bindings.length;
+
+		const operator = where.not ? 'NOT BETWEEN' : 'BETWEEN';
+		return `${column} ${operator} $${param1} AND $${param2}`;
+	}
+
+	/**
+	 * Compile an INSERT statement
+	 */
+	compileInsert(query: QueryComponents, values: InsertValues | InsertValues[]): CompiledQuery {
+		const table = this.wrapTable(query.table);
+		const valueArray = Array.isArray(values) ? values : [values];
+
+		if (valueArray.length === 0) {
+			return { sql: `INSERT INTO ${table} DEFAULT VALUES`, bindings: [] };
+		}
+
+		const columns = Object.keys(valueArray[0]);
+		const columnList = this.columnize(columns);
+
+		const bindings: Binding[] = [];
+		const valueSets = valueArray.map((row) => {
+			const placeholders = columns.map((col) => {
+				bindings.push(row[col]);
+				return `$${bindings.length}`;
+			});
+			return `(${placeholders.join(', ')})`;
+		});
+
+		const sql = `INSERT INTO ${table} (${columnList}) VALUES ${valueSets.join(', ')}`;
+		return { sql, bindings };
+	}
+
+	/**
+	 * Compile an INSERT statement with RETURNING clause
+	 */
+	compileInsertReturning(
+		query: QueryComponents,
+		values: InsertValues | InsertValues[],
+		returning: string[]
+	): CompiledQuery {
+		const { sql, bindings } = this.compileInsert(query, values);
+		const returningColumns = returning.length === 0 ? '*' : this.columnize(returning);
+		return { sql: `${sql} RETURNING ${returningColumns}`, bindings };
+	}
+
+	/**
+	 * Compile an UPDATE statement
+	 */
+	compileUpdate(query: QueryComponents, values: UpdateValues): CompiledQuery {
+		const table = this.wrapTable(query.table);
+		const bindings: Binding[] = [];
+
+		// Compile SET clause
+		const setClause = Object.entries(values)
+			.map(([column, value]) => {
+				bindings.push(value);
+				return `${this.wrap(column)} = $${bindings.length}`;
+			})
+			.join(', ');
+
+		// Compile WHERE clause
+		const whereClause = this.compileWheres(query, bindings);
+
+		const sql = `UPDATE ${table} SET ${setClause}${whereClause ? ` ${whereClause}` : ''}`;
+		return { sql, bindings };
+	}
+
+	/**
+	 * Compile a DELETE statement
+	 */
+	compileDelete(query: QueryComponents): CompiledQuery {
+		const table = this.wrapTable(query.table);
+		const bindings: Binding[] = [];
+
+		// Compile WHERE clause
+		const whereClause = this.compileWheres(query, bindings);
+
+		const sql = `DELETE FROM ${table}${whereClause ? ` ${whereClause}` : ''}`;
+		return { sql, bindings };
+	}
+
+	/**
+	 * Compile a TRUNCATE TABLE statement
+	 */
+	compileTruncate(table: string): string {
+		return `TRUNCATE TABLE ${this.wrapTable(table)} RESTART IDENTITY CASCADE`;
+	}
+
+	/**
+	 * Compile an upsert (INSERT ... ON CONFLICT) statement
+	 */
+	compileUpsert(
+		query: QueryComponents,
+		values: InsertValues | InsertValues[],
+		uniqueColumns: string[],
+		updateColumns?: string[]
+	): CompiledQuery {
+		const { sql, bindings } = this.compileInsert(query, values);
+
+		const conflictColumns = this.columnize(uniqueColumns);
+		const valueArray = Array.isArray(values) ? values : [values];
+		const allColumns = Object.keys(valueArray[0]);
+		const columnsToUpdate = updateColumns ?? allColumns.filter((col) => !uniqueColumns.includes(col));
+
+		const updateClause = columnsToUpdate
+			.map((col) => `${this.wrap(col)} = EXCLUDED.${this.wrap(col)}`)
+			.join(', ');
+
+		const upsertSql = `${sql} ON CONFLICT (${conflictColumns}) DO UPDATE SET ${updateClause}`;
+		return { sql: upsertSql, bindings };
+	}
+
+	/**
+	 * Compile a raw expression
+	 */
+	raw(expression: string): string {
+		return expression;
+	}
+}

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

@@ -0,0 +1,6 @@
+/**
+ * PhoenixJS ORM - Grammar Exports
+ */
+
+export { Grammar } from './Grammar';
+export { PostgresGrammar } from './PostgresGrammar';

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

@@ -0,0 +1,8 @@
+/**
+ * PhoenixJS ORM - Query Exports
+ */
+
+export * from './types';
+export * from './grammars';
+export { Builder } from './Builder';
+export { DB } from './DB';

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

@@ -0,0 +1,196 @@
+/**
+ * PhoenixJS ORM - Query Builder Types
+ *
+ * Type definitions for the query builder internals that the Grammar compiles.
+ */
+
+/**
+ * Supported WHERE clause operators
+ */
+export type WhereOperator =
+	| '='
+	| '!='
+	| '<>'
+	| '<'
+	| '<='
+	| '>'
+	| '>='
+	| 'LIKE'
+	| 'NOT LIKE'
+	| 'ILIKE'
+	| 'NOT ILIKE'
+	| 'IN'
+	| 'NOT IN'
+	| 'BETWEEN'
+	| 'NOT BETWEEN'
+	| 'IS NULL'
+	| 'IS NOT NULL';
+
+/**
+ * Binding value type - values that can be bound to query parameters
+ */
+export type Binding = string | number | boolean | null | Date;
+
+/**
+ * WHERE clause representation
+ */
+export interface WhereClause {
+	type: 'basic' | 'in' | 'null' | 'between' | 'raw' | 'nested';
+	column?: string;
+	operator?: WhereOperator | string;
+	value?: Binding | Binding[];
+	values?: Binding[]; // For BETWEEN
+	boolean: 'and' | 'or';
+	not?: boolean;
+	sql?: string; // For raw WHERE
+	bindings?: Binding[]; // For raw WHERE
+	nested?: WhereClause[]; // For nested WHERE
+}
+
+/**
+ * JOIN clause types
+ */
+export type JoinType = 'inner' | 'left' | 'right' | 'cross';
+
+/**
+ * JOIN clause representation
+ */
+export interface JoinClause {
+	type: JoinType;
+	table: string;
+	first: string; // First column (from main table)
+	operator: string;
+	second: string; // Second column (from joined table)
+}
+
+/**
+ * ORDER BY direction
+ */
+export type OrderDirection = 'asc' | 'desc';
+
+/**
+ * Raw SQL expression with bindings
+ * Used for selectRaw, orderByRaw, etc.
+ */
+export class RawExpression {
+	constructor(
+		public readonly expression: string,
+		public readonly bindings: Binding[] = []
+	) { }
+
+	toString(): string {
+		return this.expression;
+	}
+}
+
+/**
+ * ORDER BY clause representation
+ */
+export interface OrderClause {
+	column: string;
+	direction: OrderDirection;
+	raw?: boolean; // If true, column is a raw SQL expression
+}
+
+/**
+ * Aggregate function types
+ */
+export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+/**
+ * Aggregate representation
+ */
+export interface AggregateClause {
+	function: AggregateFunction;
+	column: string;
+}
+
+/**
+ * Full query state object representing all components of a query
+ */
+export interface QueryComponents {
+	/** Table name */
+	table: string;
+
+	/** Table alias */
+	alias?: string;
+
+	/** SELECT columns - empty means SELECT * */
+	columns: string[];
+
+	/** Raw SELECT expressions */
+	rawSelects: { expression: string; bindings: Binding[] }[];
+
+	/** DISTINCT flag */
+	distinct: boolean;
+
+	/** WHERE clauses */
+	wheres: WhereClause[];
+
+	/** JOIN clauses */
+	joins: JoinClause[];
+
+	/** ORDER BY clauses */
+	orders: OrderClause[];
+
+	/** GROUP BY columns */
+	groups: string[];
+
+	/** Raw GROUP BY expressions */
+	rawGroups: { expression: string; bindings: Binding[] }[];
+
+	/** ORDER BY bindings (for raw order expressions) */
+	orderBindings: Binding[];
+
+	/** HAVING conditions (similar to WHERE) */
+	havings: WhereClause[];
+
+	/** LIMIT value */
+	limit?: number;
+
+	/** OFFSET value */
+	offset?: number;
+
+	/** Aggregate function */
+	aggregate?: AggregateClause;
+
+	/** LOCK mode */
+	lock?: 'for update' | 'for share';
+}
+
+/**
+ * Result of compiling a query - SQL string and bindings
+ */
+export interface CompiledQuery {
+	sql: string;
+	bindings: Binding[];
+}
+
+/**
+ * Insert values - each key is a column name
+ */
+export type InsertValues = Record<string, Binding>;
+
+/**
+ * Update values - each key is a column name
+ */
+export type UpdateValues = Record<string, Binding>;
+
+/**
+ * Create empty query components with defaults
+ */
+export function createQueryComponents(table: string): QueryComponents {
+	return {
+		table,
+		columns: [],
+		rawSelects: [],
+		distinct: false,
+		wheres: [],
+		joins: [],
+		orders: [],
+		groups: [],
+		rawGroups: [],
+		orderBindings: [],
+		havings: [],
+	};
+}