create-phoenixjs 0.1.3 → 0.1.5

package/template/framework/database/orm/BelongsToMany.ts

@@ -0,0 +1,570 @@
+import { DB } from '../query/DB';
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding, InsertValues, UpdateValues } from '../query/types';
+
+/**
+ * BelongsToMany Relationship - Represents a many-to-many relationship with a pivot table.
+ *
+ * Uses an intermediate (pivot) table to connect two models.
+ *
+ * Example Schema:
+ * - users table: id, name, email
+ * - roles table: id, name
+ * - role_user table (pivot): user_id, role_id, assigned_at (optional extra column)
+ *
+ * Usage:
+ * ```typescript
+ * class User extends Model {
+ *     roles() {
+ *         return this.belongsToMany(Role, 'role_user', 'user_id', 'role_id');
+ *     }
+ * }
+ *
+ * class Role extends Model {
+ *     users() {
+ *         return this.belongsToMany(User, 'role_user', 'role_id', 'user_id');
+ *     }
+ * }
+ *
+ * // Get user's roles
+ * const user = await User.find(1);
+ * const roles = await user.roles().get();
+ *
+ * // Attach a role
+ * await user.roles().attach(1);
+ * await user.roles().attach([1, 2, 3]);
+ *
+ * // Detach a role
+ * await user.roles().detach(1);
+ * await user.roles().detach(); // Detach all
+ *
+ * // Sync roles (attach new, detach missing)
+ * await user.roles().sync([1, 2, 3]);
+ * ```
+ *
+ * @template TRelated - The type of the related model
+ */
+export class BelongsToMany<TRelated extends Model> extends Relation<TRelated> {
+	/**
+	 * The pivot table name.
+	 * Example: 'role_user'
+	 */
+	protected table: string;
+
+	/**
+	 * The foreign key of the parent model on the pivot table.
+	 * Example: 'user_id' on role_user table
+	 */
+	protected foreignPivotKey: string;
+
+	/**
+	 * The foreign key of the related model on the pivot table.
+	 * Example: 'role_id' on role_user table
+	 */
+	protected relatedPivotKey: string;
+
+	/**
+	 * The primary key on the parent model.
+	 * Example: 'id' on users table
+	 */
+	protected parentKey: string;
+
+	/**
+	 * The primary key on the related model.
+	 * Example: 'id' on roles table
+	 */
+	protected relatedKey: string;
+
+	/**
+	 * Extra pivot columns to include in results.
+	 */
+	protected pivotColumns: string[] = [];
+
+	/**
+	 * Create a new BelongsToMany relationship instance.
+	 *
+	 * @param parent - The parent model instance
+	 * @param related - An instance of the related model class
+	 * @param table - The pivot table name (e.g., 'role_user')
+	 * @param foreignPivotKey - The foreign key for the parent on the pivot table (e.g., 'user_id')
+	 * @param relatedPivotKey - The foreign key for the related model on the pivot table (e.g., 'role_id')
+	 * @param parentKey - The primary key on the parent model (e.g., 'id')
+	 * @param relatedKey - The primary key on the related model (e.g., 'id')
+	 */
+	constructor(
+		parent: Model,
+		related: TRelated,
+		table: string,
+		foreignPivotKey: string,
+		relatedPivotKey: string,
+		parentKey: string,
+		relatedKey: string
+	) {
+		super(parent, related);
+
+		this.table = table;
+		this.foreignPivotKey = foreignPivotKey;
+		this.relatedPivotKey = relatedPivotKey;
+		this.parentKey = parentKey;
+		this.relatedKey = relatedKey;
+
+		// Re-add constraints now that keys are set
+		this.reinitializeConstraints();
+	}
+
+	/**
+	 * Re-initialize constraints after keys are set.
+	 */
+	private reinitializeConstraints(): void {
+		this.query = this.newQuery();
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		const relatedTable = this.related.getTable();
+
+		// Add the join to the pivot table
+		this.query.join(
+			this.table,
+			`${relatedTable}.${this.relatedKey}`,
+			'=',
+			`${this.table}.${this.relatedPivotKey}`
+		);
+
+		// Constrain by parent's key
+		if (parentKeyValue !== undefined && parentKeyValue !== null) {
+			this.query.where(`${this.table}.${this.foreignPivotKey}`, '=', parentKeyValue as Binding);
+		}
+	}
+
+	/**
+	 * Add the constraints for the BelongsToMany relationship.
+	 * Called by parent constructor - keys may not be set yet.
+	 */
+	public addConstraints(): void {
+		// Constraints are added in reinitializeConstraints after keys are set
+	}
+
+	/**
+	 * Get the results of the BelongsToMany relationship.
+	 *
+	 * Returns an array of related models. If no related models exist,
+	 * returns an empty array (never null).
+	 *
+	 * @returns Array of related models
+	 */
+	public async getResults(): Promise<TRelated[]> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+
+		// If parent doesn't have a key value, return empty array
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			return [];
+		}
+
+		return this.getAll();
+	}
+
+	/**
+	 * Include extra pivot columns in the results.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const roles = await user.roles().withPivot('assigned_at', 'created_by').get();
+	 * // Each role will have role.pivot.assigned_at available
+	 * ```
+	 *
+	 * @param columns - Column names to include from the pivot table
+	 * @returns This relation for chaining
+	 */
+	public withPivot(...columns: string[]): this {
+		this.pivotColumns.push(...columns);
+
+		// Add pivot columns to select
+		for (const column of columns) {
+			this.query.addSelect(`${this.table}.${column}`);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Add a WHERE clause on a pivot table column.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const activeRoles = await user.roles()
+	 *     .wherePivot('active', true)
+	 *     .get();
+	 * ```
+	 *
+	 * @param column - The pivot column to filter on
+	 * @param operatorOrValue - The operator or value
+	 * @param value - The value if operator provided
+	 * @returns This relation for chaining
+	 */
+	public wherePivot(
+		column: string,
+		operatorOrValue: string | number | boolean | null,
+		value?: string | number | boolean | null
+	): this {
+		const qualifiedColumn = `${this.table}.${column}`;
+		this.query.where(qualifiedColumn, operatorOrValue, value);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IN clause on a pivot table column.
+	 *
+	 * @param column - The pivot column to filter on
+	 * @param values - Array of values to match
+	 * @returns This relation for chaining
+	 */
+	public wherePivotIn(column: string, values: (string | number | boolean | null)[]): this {
+		const qualifiedColumn = `${this.table}.${column}`;
+		this.query.whereIn(qualifiedColumn, values);
+		return this;
+	}
+
+	/**
+	 * Attach one or more related models by their IDs.
+	 *
+	 * This creates records in the pivot table linking the parent to the related models.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * // Attach a single role
+	 * await user.roles().attach(1);
+	 *
+	 * // Attach multiple roles
+	 * await user.roles().attach([1, 2, 3]);
+	 *
+	 * // Attach with extra pivot data
+	 * await user.roles().attach(1, { assigned_at: new Date() });
+	 * await user.roles().attach([1, 2], { assigned_by: 'admin' });
+	 * ```
+	 *
+	 * @param ids - A single ID or array of IDs to attach
+	 * @param attributes - Optional extra attributes for the pivot record
+	 */
+	public async attach(
+		ids: number | string | (number | string)[],
+		attributes: Record<string, Binding> = {}
+	): Promise<void> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			throw new Error('Cannot attach: parent model has no primary key value');
+		}
+
+		const idsArray = Array.isArray(ids) ? ids : [ids];
+
+		if (idsArray.length === 0) {
+			return;
+		}
+
+		// Create pivot records
+		const records: InsertValues[] = idsArray.map((id) => ({
+			[this.foreignPivotKey]: parentKeyValue as Binding,
+			[this.relatedPivotKey]: id as Binding,
+			...attributes
+		}));
+
+		await DB.table(this.table).insert(records);
+	}
+
+	/**
+	 * Detach one or more related models by their IDs.
+	 *
+	 * This removes records from the pivot table.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * // Detach a single role
+	 * await user.roles().detach(1);
+	 *
+	 * // Detach multiple roles
+	 * await user.roles().detach([1, 2, 3]);
+	 *
+	 * // Detach all roles
+	 * await user.roles().detach();
+	 * ```
+	 *
+	 * @param ids - Optional ID or array of IDs to detach. If not provided, detaches all.
+	 * @returns The number of detached records
+	 */
+	public async detach(ids?: number | string | (number | string)[]): Promise<number> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			throw new Error('Cannot detach: parent model has no primary key value');
+		}
+
+		let query = DB.table(this.table)
+			.where(this.foreignPivotKey, '=', parentKeyValue as Binding);
+
+		if (ids !== undefined) {
+			const idsArray = Array.isArray(ids) ? ids : [ids];
+			if (idsArray.length > 0) {
+				query = query.whereIn(this.relatedPivotKey, idsArray);
+			}
+		}
+
+		return query.delete();
+	}
+
+	/**
+	 * Sync the relationship with the given IDs.
+	 *
+	 * This will attach any IDs that are not currently attached,
+	 * and detach any IDs that are not in the given list.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * // After this, user will have exactly roles 1, 2, 3
+	 * await user.roles().sync([1, 2, 3]);
+	 * ```
+	 *
+	 * @param ids - Array of IDs that should be attached
+	 * @returns Object with attached and detached IDs
+	 */
+	public async sync(ids: (number | string)[]): Promise<{
+		attached: (number | string)[];
+		detached: (number | string)[];
+	}> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			throw new Error('Cannot sync: parent model has no primary key value');
+		}
+
+		// Get currently attached IDs
+		const currentPivotRecords = await DB.table(this.table)
+			.where(this.foreignPivotKey, '=', parentKeyValue as Binding)
+			.get<Record<string, unknown>>();
+
+		const currentIds = currentPivotRecords.map(
+			(record) => record[this.relatedPivotKey] as number | string
+		);
+
+		// Determine what to attach and detach
+		const toAttach = ids.filter((id) => !currentIds.includes(id));
+		const toDetach = currentIds.filter((id) => !ids.includes(id));
+
+		// Perform operations
+		if (toAttach.length > 0) {
+			await this.attach(toAttach);
+		}
+
+		if (toDetach.length > 0) {
+			await this.detach(toDetach);
+		}
+
+		return {
+			attached: toAttach,
+			detached: toDetach
+		};
+	}
+
+	/**
+	 * Toggle the attachment of the given IDs.
+	 *
+	 * If an ID is currently attached, it will be detached.
+	 * If an ID is not attached, it will be attached.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * await user.roles().toggle([1, 2, 3]);
+	 * ```
+	 *
+	 * @param ids - Array of IDs to toggle
+	 * @returns Object with attached and detached IDs
+	 */
+	public async toggle(ids: (number | string)[]): Promise<{
+		attached: (number | string)[];
+		detached: (number | string)[];
+	}> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			throw new Error('Cannot toggle: parent model has no primary key value');
+		}
+
+		// Get currently attached IDs
+		const currentPivotRecords = await DB.table(this.table)
+			.where(this.foreignPivotKey, '=', parentKeyValue as Binding)
+			.get<Record<string, unknown>>();
+
+		const currentIds = currentPivotRecords.map(
+			(record) => record[this.relatedPivotKey] as number | string
+		);
+
+		// Determine what to attach and detach
+		const toAttach = ids.filter((id) => !currentIds.includes(id));
+		const toDetach = ids.filter((id) => currentIds.includes(id));
+
+		// Perform operations
+		if (toAttach.length > 0) {
+			await this.attach(toAttach);
+		}
+
+		if (toDetach.length > 0) {
+			await this.detach(toDetach);
+		}
+
+		return {
+			attached: toAttach,
+			detached: toDetach
+		};
+	}
+
+	/**
+	 * Update an existing pivot record.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * await user.roles().updateExistingPivot(1, { active: false });
+	 * ```
+	 *
+	 * @param id - The related model's ID
+	 * @param attributes - Attributes to update on the pivot record
+	 * @returns Number of affected rows
+	 */
+	public async updateExistingPivot(
+		id: number | string,
+		attributes: UpdateValues
+	): Promise<number> {
+		const parentKeyValue = this.parent.getAttribute(this.parentKey);
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			throw new Error('Cannot update pivot: parent model has no primary key value');
+		}
+
+		return DB.table(this.table)
+			.where(this.foreignPivotKey, '=', parentKeyValue as Binding)
+			.where(this.relatedPivotKey, '=', id as Binding)
+			.update(attributes);
+	}
+
+	/**
+	 * Get the pivot table name.
+	 *
+	 * @returns The pivot table name
+	 */
+	public getPivotTable(): string {
+		return this.table;
+	}
+
+	/**
+	 * Get the foreign pivot key name.
+	 *
+	 * @returns The foreign pivot key column name
+	 */
+	public getForeignPivotKeyName(): string {
+		return this.foreignPivotKey;
+	}
+
+	/**
+	 * Get the related pivot key name.
+	 *
+	 * @returns The related pivot key column name
+	 */
+	public getRelatedPivotKeyName(): string {
+		return this.relatedPivotKey;
+	}
+
+	/**
+	 * Get the fully qualified foreign pivot key name.
+	 *
+	 * @returns The qualified column name
+	 */
+	public getQualifiedForeignPivotKeyName(): string {
+		return `${this.table}.${this.foreignPivotKey}`;
+	}
+
+	/**
+	 * Get the fully qualified related pivot key name.
+	 *
+	 * @returns The qualified column name
+	 */
+	public getQualifiedRelatedPivotKeyName(): string {
+		return `${this.table}.${this.relatedPivotKey}`;
+	}
+
+	// ==========================================
+	// Eager Loading Methods
+	// ==========================================
+
+	/**
+	 * Initialize the relation for eager loading.
+	 * Creates a fresh query with the pivot join but without parent-specific constraints.
+	 */
+	public override initializeForEagerLoading(): void {
+		this.query = this.newQuery();
+		const relatedTable = this.related.getTable();
+
+		// Explicitly select all columns from related table to preserve them when adding rawSelect
+		this.query.select(`${relatedTable}.*`);
+
+		// Add the join to the pivot table (required for BelongsToMany)
+		this.query.join(
+			this.table,
+			`${relatedTable}.${this.relatedKey}`,
+			'=',
+			`${this.table}.${this.relatedPivotKey}`
+		);
+	}
+
+	/**
+	 * Add constraints for eager loading.
+	 * Uses WHERE IN on the pivot table to fetch all related models for multiple parents at once.
+	 *
+	 * @param models - Array of parent models to load relations for
+	 */
+	public addEagerConstraints(models: Model[]): void {
+		// Collect all parent key values
+		const keys: unknown[] = [];
+		for (const model of models) {
+			const key = model.getAttribute(this.parentKey);
+			if (key !== undefined && key !== null) {
+				keys.push(key);
+			}
+		}
+
+		// Remove duplicates
+		const uniqueKeys = [...new Set(keys)];
+
+		// Add WHERE IN constraint on pivot table's foreign key
+		if (uniqueKeys.length > 0) {
+			this.query.whereIn(
+				`${this.table}.${this.foreignPivotKey}`,
+				uniqueKeys as (string | number | boolean)[]
+			);
+		}
+
+		// Also select the foreign pivot key to enable matching (use selectRaw for proper alias)
+		this.query.selectRaw(`${this.table}.${this.foreignPivotKey} as pivot_foreign_key`);
+	}
+
+	/**
+	 * Match the eagerly loaded results to their parent models.
+	 * For BelongsToMany, each parent gets an array of related models.
+	 *
+	 * @param models - Array of parent models
+	 * @param results - Array of related models that were loaded
+	 * @param relation - The name of the relationship being matched
+	 */
+	public match(models: Model[], results: TRelated[], relation: string): void {
+		// Build a dictionary for O(n) grouping: parentKey value -> array of related models
+		// Use String conversion for consistent key comparison across types
+		const dictionary = new Map<string, TRelated[]>();
+		for (const result of results) {
+			// Get the foreign pivot key from the result (added as pivot_foreign_key)
+			const pivotForeignKeyValue = String(result.getAttribute('pivot_foreign_key'));
+			if (!dictionary.has(pivotForeignKeyValue)) {
+				dictionary.set(pivotForeignKeyValue, []);
+			}
+			dictionary.get(pivotForeignKeyValue)!.push(result);
+		}
+
+		// Match each parent model with its array of related models
+		for (const model of models) {
+			const parentKeyValue = String(model.getAttribute(this.parentKey));
+			const matches = dictionary.get(parentKeyValue) || [];
+			model.setRelation(relation, matches);
+		}
+	}
+}
+

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

@@ -0,0 +1,160 @@
+import { Builder as QueryBuilder } from '../query/Builder';
+import { Model } from './Model';
+import { Scope } from './Scope';
+
+/**
+ * Eloquent Builder
+ * 
+ * Extends the basic Query Builder to add ORM-specific features
+ * like Scopes, Model hydration, and Soft Deletes support.
+ */
+export class Builder<T extends Model = Model> extends QueryBuilder {
+	/**
+	 * The model being queried.
+	 */
+	protected model!: T;
+
+	/**
+	 * The applied global scopes.
+	 */
+	protected scopes: Map<string, Scope> = new Map();
+
+	/**
+	 * The scopes that should be removed.
+	 */
+	protected removedScopes: string[] = [];
+
+	/**
+	 * Create a new Eloquent Builder instance.
+	 */
+	constructor(query: QueryBuilder) {
+		super(query['connection'], query['grammar'], query['query'].table);
+		// Copy query state
+		this.query = query['query'];
+	}
+
+	/**
+	 * Set the model instance for the builder.
+	 */
+	public setModel(model: T): this {
+		this.model = model;
+		return this;
+	}
+
+	/**
+	 * Get the model instance.
+	 */
+	public getModel(): T {
+		return this.model;
+	}
+
+	/**
+	 * Register a new global scope.
+	 */
+	public withGlobalScope(identifier: string, scope: Scope): this {
+		this.scopes.set(identifier, scope);
+		if (scope.extend) {
+			scope.extend(this);
+		}
+		return this;
+	}
+
+	/**
+	 * Register a custom macro.
+	 */
+	public macro(name: string, callback: Function): void {
+		(this as any)[name] = callback;
+	}
+
+	/**
+	 * Remove a registered global scope.
+	 */
+	public withoutGlobalScope(scope: Scope | string | Function): this {
+		if (typeof scope === 'string') {
+			this.removedScopes.push(scope);
+			this.scopes.delete(scope);
+		} else if (typeof scope === 'function') {
+			// Find by constructor
+			for (const [key, s] of this.scopes.entries()) {
+				if (s.constructor === scope) {
+					this.removedScopes.push(key);
+					this.scopes.delete(key);
+					break;
+				}
+			}
+		} else {
+			// Find by instance
+			for (const [key, s] of this.scopes.entries()) {
+				if (s.constructor.name === scope.constructor.name) {
+					this.removedScopes.push(key);
+					this.scopes.delete(key);
+					break;
+				}
+			}
+		}
+
+		return this;
+	}
+
+	/**
+	 * Remove all or passed global scopes.
+	 */
+	public withoutGlobalScopes(scopes: string[] | null = null): this {
+		if (!scopes) {
+			this.scopes.clear();
+		} else {
+			for (const scope of scopes) {
+				this.withoutGlobalScope(scope);
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Apply the scopes to the query builder instance.
+	 */
+	public applyScopes(): this {
+		if (this.scopes.size === 0) {
+			return this;
+		}
+
+		for (const [identifier, scope] of this.scopes.entries()) {
+			if (!this.removedScopes.includes(identifier)) {
+				scope.apply(this, this.model);
+			}
+		}
+
+		return this;
+	}
+
+	/**
+	 * execute the query as a "select" statement.
+	 * Overridden to hydrate models.
+	 */
+	public async get<R = any>(): Promise<R[]> {
+		const builder = this.applyScopes();
+
+		const results = await super.get();
+
+		if (results.length > 0) {
+			return this.model['hydrateModels'](results) as unknown as R[];
+		}
+
+		return results as R[];
+	}
+
+	/**
+	 * Execute the query and return the first result.
+	 * Overridden to hydrate model.
+	 */
+	public async first<R = any>(): Promise<R | null> {
+		const builder = this.applyScopes();
+		const result = await super.first();
+
+		if (result) {
+			return this.model['hydrateModel'](result) as unknown as R;
+		}
+
+		return null;
+	}
+}