create-phoenixjs 0.1.4 → 0.1.5

package/template/framework/database/schema/Blueprint.ts

@@ -0,0 +1,478 @@
+/**
+ * PhoenixJS ORM - Blueprint
+ *
+ * Defines the structure of a database table. Used to create or modify
+ * table schemas via the Schema Builder.
+ */
+
+/**
+ * Column definition representing a single column in the blueprint
+ */
+export interface ColumnDefinition {
+	name: string;
+	type: string;
+	length?: number;
+	precision?: number;
+	scale?: number;
+	nullable: boolean;
+	primary: boolean;
+	unique: boolean;
+	autoIncrement: boolean;
+	defaultValue?: string | number | boolean | null;
+	references?: {
+		column: string;
+		table: string;
+		onDelete?: string;
+		onUpdate?: string;
+	};
+}
+
+/**
+ * Index definition
+ */
+export interface IndexDefinition {
+	name: string;
+	columns: string[];
+	unique: boolean;
+}
+
+/**
+ * Foreign key definition
+ */
+export interface ForeignKeyDefinition {
+	columns: string[];
+	references: string[];
+	on: string;
+	onDelete?: string;
+	onUpdate?: string;
+}
+
+/**
+ * Column builder for fluent column configuration
+ */
+export class ColumnBuilder {
+	constructor(private column: ColumnDefinition) { }
+
+	/**
+	 * Allow NULL values for this column
+	 */
+	nullable(): this {
+		this.column.nullable = true;
+		return this;
+	}
+
+	/**
+	 * Add UNIQUE constraint to this column
+	 */
+	unique(): this {
+		this.column.unique = true;
+		return this;
+	}
+
+	/**
+	 * Set this column as PRIMARY KEY
+	 */
+	primary(): this {
+		this.column.primary = true;
+		return this;
+	}
+
+	/**
+	 * Set a default value for this column
+	 */
+	default(value: string | number | boolean | null): this {
+		this.column.defaultValue = value;
+		return this;
+	}
+
+	/**
+	 * Set foreign key reference
+	 */
+	references(column: string): this & { on(table: string): this } {
+		this.column.references = { column, table: '' };
+		const self = this;
+		return Object.assign(this, {
+			on(table: string): ColumnBuilder {
+				self.column.references!.table = table;
+				return self;
+			},
+		});
+	}
+
+	/**
+	 * Set ON DELETE action for foreign key
+	 */
+	onDelete(action: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'): this {
+		if (this.column.references) {
+			this.column.references.onDelete = action;
+		}
+		return this;
+	}
+
+	/**
+	 * Set ON UPDATE action for foreign key
+	 */
+	onUpdate(action: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'): this {
+		if (this.column.references) {
+			this.column.references.onUpdate = action;
+		}
+		return this;
+	}
+
+	/**
+	 * Get the column definition
+	 */
+	getColumn(): ColumnDefinition {
+		return this.column;
+	}
+}
+
+/**
+ * Blueprint for defining table structure
+ */
+export class Blueprint {
+	private columns: ColumnDefinition[] = [];
+	private indexes: IndexDefinition[] = [];
+	private foreignKeys: ForeignKeyDefinition[] = [];
+	private droppedColumns: string[] = [];
+	private droppedIndexes: string[] = [];
+
+	constructor(private tableName: string) { }
+
+	/**
+	 * Create a new column with base definition
+	 */
+	private addColumn(name: string, type: string, options: Partial<ColumnDefinition> = {}): ColumnBuilder {
+		const column: ColumnDefinition = {
+			name,
+			type,
+			nullable: false,
+			primary: false,
+			unique: false,
+			autoIncrement: false,
+			...options,
+		};
+		this.columns.push(column);
+		return new ColumnBuilder(column);
+	}
+
+	// ============================================
+	// Primary Key / ID Columns
+	// ============================================
+
+	/**
+	 * Auto-incrementing SERIAL primary key
+	 */
+	id(column: string = 'id'): ColumnBuilder {
+		return this.addColumn(column, 'SERIAL', { primary: true, autoIncrement: true });
+	}
+
+	/**
+	 * Auto-incrementing BIGSERIAL primary key
+	 */
+	bigId(column: string = 'id'): ColumnBuilder {
+		return this.addColumn(column, 'BIGSERIAL', { primary: true, autoIncrement: true });
+	}
+
+	/**
+	 * UUID primary key
+	 */
+	uuid(column: string = 'id'): ColumnBuilder {
+		return this.addColumn(column, 'UUID', { primary: true });
+	}
+
+	// ============================================
+	// String Columns
+	// ============================================
+
+	/**
+	 * VARCHAR column with optional length
+	 */
+	string(column: string, length: number = 255): ColumnBuilder {
+		return this.addColumn(column, 'VARCHAR', { length });
+	}
+
+	/**
+	 * CHAR column with fixed length
+	 */
+	char(column: string, length: number = 255): ColumnBuilder {
+		return this.addColumn(column, 'CHAR', { length });
+	}
+
+	/**
+	 * TEXT column for long strings
+	 */
+	text(column: string): ColumnBuilder {
+		return this.addColumn(column, 'TEXT');
+	}
+
+	// ============================================
+	// Numeric Columns
+	// ============================================
+
+	/**
+	 * INTEGER column
+	 */
+	integer(column: string): ColumnBuilder {
+		return this.addColumn(column, 'INTEGER');
+	}
+
+	/**
+	 * SMALLINT column
+	 */
+	smallInteger(column: string): ColumnBuilder {
+		return this.addColumn(column, 'SMALLINT');
+	}
+
+	/**
+	 * BIGINT column
+	 */
+	bigInteger(column: string): ColumnBuilder {
+		return this.addColumn(column, 'BIGINT');
+	}
+
+	/**
+	 * REAL/FLOAT column
+	 */
+	float(column: string, precision?: number): ColumnBuilder {
+		return this.addColumn(column, 'REAL', { precision });
+	}
+
+	/**
+	 * DOUBLE PRECISION column
+	 */
+	double(column: string): ColumnBuilder {
+		return this.addColumn(column, 'DOUBLE PRECISION');
+	}
+
+	/**
+	 * NUMERIC/DECIMAL column
+	 */
+	decimal(column: string, precision: number = 8, scale: number = 2): ColumnBuilder {
+		return this.addColumn(column, 'NUMERIC', { precision, scale });
+	}
+
+	// ============================================
+	// Boolean Column
+	// ============================================
+
+	/**
+	 * BOOLEAN column
+	 */
+	boolean(column: string): ColumnBuilder {
+		return this.addColumn(column, 'BOOLEAN');
+	}
+
+	// ============================================
+	// Date/Time Columns
+	// ============================================
+
+	/**
+	 * DATE column
+	 */
+	date(column: string): ColumnBuilder {
+		return this.addColumn(column, 'DATE');
+	}
+
+	/**
+	 * TIME column
+	 */
+	time(column: string): ColumnBuilder {
+		return this.addColumn(column, 'TIME');
+	}
+
+	/**
+	 * TIMESTAMP column
+	 */
+	timestamp(column: string): ColumnBuilder {
+		return this.addColumn(column, 'TIMESTAMP');
+	}
+
+	/**
+	 * TIMESTAMP WITH TIME ZONE column
+	 */
+	timestampTz(column: string): ColumnBuilder {
+		return this.addColumn(column, 'TIMESTAMPTZ');
+	}
+
+	/**
+	 * Add created_at and updated_at TIMESTAMP columns
+	 */
+	timestamps(): void {
+		this.timestamp('created_at').nullable().default('CURRENT_TIMESTAMP');
+		this.timestamp('updated_at').nullable().default('CURRENT_TIMESTAMP');
+	}
+
+	/**
+	 * Add soft delete deleted_at column
+	 */
+	softDeletes(column: string = 'deleted_at'): ColumnBuilder {
+		return this.timestamp(column).nullable();
+	}
+
+	// ============================================
+	// JSON Columns
+	// ============================================
+
+	/**
+	 * JSONB column (PostgreSQL optimized JSON)
+	 */
+	json(column: string): ColumnBuilder {
+		return this.addColumn(column, 'JSONB');
+	}
+
+	/**
+	 * JSON column (plain JSON storage)
+	 */
+	jsonPlain(column: string): ColumnBuilder {
+		return this.addColumn(column, 'JSON');
+	}
+
+	// ============================================
+	// Binary Columns
+	// ============================================
+
+	/**
+	 * BYTEA column for binary data
+	 */
+	binary(column: string): ColumnBuilder {
+		return this.addColumn(column, 'BYTEA');
+	}
+
+	// ============================================
+	// Special Columns
+	// ============================================
+
+	/**
+	 * INET column for IP addresses
+	 */
+	ipAddress(column: string = 'ip_address'): ColumnBuilder {
+		return this.addColumn(column, 'INET');
+	}
+
+	/**
+	 * MACADDR column for MAC addresses
+	 */
+	macAddress(column: string = 'mac_address'): ColumnBuilder {
+		return this.addColumn(column, 'MACADDR');
+	}
+
+	// ============================================
+	// Indexes
+	// ============================================
+
+	/**
+	 * Add an index on columns
+	 */
+	index(columns: string | string[], name?: string): void {
+		const cols = Array.isArray(columns) ? columns : [columns];
+		const indexName = name || `${this.tableName}_${cols.join('_')}_index`;
+		this.indexes.push({ name: indexName, columns: cols, unique: false });
+	}
+
+	/**
+	 * Add a unique index
+	 */
+	uniqueIndex(columns: string | string[], name?: string): void {
+		const cols = Array.isArray(columns) ? columns : [columns];
+		const indexName = name || `${this.tableName}_${cols.join('_')}_unique`;
+		this.indexes.push({ name: indexName, columns: cols, unique: true });
+	}
+
+	// ============================================
+	// Foreign Keys
+	// ============================================
+
+	/**
+	 * Add a foreign key constraint
+	 */
+	foreign(columns: string | string[]): {
+		references: (refs: string | string[]) => {
+			on: (table: string) => {
+				onDelete: (action: string) => void;
+				onUpdate: (action: string) => void;
+			};
+		};
+	} {
+		const cols = Array.isArray(columns) ? columns : [columns];
+		const fk: ForeignKeyDefinition = {
+			columns: cols,
+			references: [],
+			on: '',
+		};
+
+		return {
+			references: (refs: string | string[]) => {
+				fk.references = Array.isArray(refs) ? refs : [refs];
+				return {
+					on: (table: string) => {
+						fk.on = table;
+						this.foreignKeys.push(fk);
+						return {
+							onDelete: (action: string) => {
+								fk.onDelete = action;
+							},
+							onUpdate: (action: string) => {
+								fk.onUpdate = action;
+							},
+						};
+					},
+				};
+			},
+		};
+	}
+
+	// ============================================
+	// Drop Operations (for alter table)
+	// ============================================
+
+	/**
+	 * Drop a column
+	 */
+	dropColumn(column: string | string[]): void {
+		const cols = Array.isArray(column) ? column : [column];
+		this.droppedColumns.push(...cols);
+	}
+
+	/**
+	 * Drop an index
+	 */
+	dropIndex(name: string): void {
+		this.droppedIndexes.push(name);
+	}
+
+	// ============================================
+	// Getters
+	// ============================================
+
+	getTableName(): string {
+		return this.tableName;
+	}
+
+	getColumns(): ColumnDefinition[] {
+		return this.columns;
+	}
+
+	getIndexes(): IndexDefinition[] {
+		return this.indexes;
+	}
+
+	getForeignKeys(): ForeignKeyDefinition[] {
+		return this.foreignKeys;
+	}
+
+	getDroppedColumns(): string[] {
+		return this.droppedColumns;
+	}
+
+	getDroppedIndexes(): string[] {
+		return this.droppedIndexes;
+	}
+
+	/**
+	 * Check if this is a create table operation
+	 */
+	isCreating(): boolean {
+		return this.columns.length > 0 && this.droppedColumns.length === 0;
+	}
+}

package/template/framework/database/schema/Schema.ts

@@ -0,0 +1,149 @@
+/**
+ * PhoenixJS ORM - Schema Facade
+ *
+ * Static facade for schema operations, providing a simple API for
+ * creating and modifying database tables.
+ */
+
+import type { Connection } from '../connection/Connection';
+import { Blueprint } from './Blueprint';
+import { SchemaBuilder } from './SchemaBuilder';
+import { PostgresSchemaGrammar } from './grammars/PostgresSchemaGrammar';
+
+/**
+ * Schema - Static facade for database schema operations
+ *
+ * @example
+ * ```typescript
+ * Schema.init(connection);
+ *
+ * await Schema.create('users', (table) => {
+ *   table.id();
+ *   table.string('name');
+ *   table.string('email').unique();
+ *   table.timestamps();
+ * });
+ *
+ * await Schema.dropIfExists('users');
+ * ```
+ */
+export class Schema {
+	private static builder: SchemaBuilder | null = null;
+
+	/**
+	 * Initialize the Schema facade with a connection
+	 */
+	static init(connection: Connection, grammar?: PostgresSchemaGrammar): void {
+		Schema.builder = new SchemaBuilder(connection, grammar);
+	}
+
+	/**
+	 * Get the schema builder instance
+	 */
+	static getBuilder(): SchemaBuilder {
+		if (!Schema.builder) {
+			throw new Error('Schema not initialized. Call Schema.init(connection) first.');
+		}
+		return Schema.builder;
+	}
+
+	/**
+	 * Create a new table
+	 */
+	static async create(table: string, callback: (blueprint: Blueprint) => void): Promise<void> {
+		return Schema.getBuilder().create(table, callback);
+	}
+
+	/**
+	 * Modify an existing table
+	 */
+	static async table(table: string, callback: (blueprint: Blueprint) => void): Promise<void> {
+		return Schema.getBuilder().table(table, callback);
+	}
+
+	/**
+	 * Drop a table
+	 */
+	static async drop(table: string): Promise<void> {
+		return Schema.getBuilder().drop(table);
+	}
+
+	/**
+	 * Drop a table if it exists
+	 */
+	static async dropIfExists(table: string): Promise<void> {
+		return Schema.getBuilder().dropIfExists(table);
+	}
+
+	/**
+	 * Rename a table
+	 */
+	static async rename(from: string, to: string): Promise<void> {
+		return Schema.getBuilder().rename(from, to);
+	}
+
+	/**
+	 * Check if a table exists
+	 */
+	static async hasTable(table: string): Promise<boolean> {
+		return Schema.getBuilder().hasTable(table);
+	}
+
+	/**
+	 * Check if a column exists in a table
+	 */
+	static async hasColumn(table: string, column: string): Promise<boolean> {
+		return Schema.getBuilder().hasColumn(table, column);
+	}
+
+	/**
+	 * Get all tables in the database
+	 */
+	static async getTables(): Promise<string[]> {
+		return Schema.getBuilder().getTables();
+	}
+
+	/**
+	 * Get all columns for a table
+	 */
+	static async getColumns(
+		table: string
+	): Promise<
+		{
+			column_name: string;
+			data_type: string;
+			is_nullable: string;
+			column_default: string | null;
+		}[]
+	> {
+		return Schema.getBuilder().getColumns(table);
+	}
+
+	/**
+	 * Truncate a table
+	 */
+	static async truncate(table: string): Promise<void> {
+		return Schema.getBuilder().truncate(table);
+	}
+
+	/**
+	 * Drop all tables (use with caution!)
+	 */
+	static async dropAllTables(): Promise<void> {
+		return Schema.getBuilder().dropAllTables();
+	}
+
+	/**
+	 * Create a new SchemaBuilder instance without using the facade
+	 */
+	static connection(connection: Connection, grammar?: PostgresSchemaGrammar): SchemaBuilder {
+		return new SchemaBuilder(connection, grammar);
+	}
+
+	/**
+	 * Reset the facade (useful for testing)
+	 */
+	static reset(): void {
+		Schema.builder = null;
+	}
+}