create-phoenixjs 0.1.4 → 0.1.5

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

@@ -0,0 +1,324 @@
+import type { Builder } from '../query/Builder';
+import type { Model } from './Model';
+import type { Relation } from './Relation';
+
+/**
+ * EagerLoadingBuilder - A wrapper around the query builder that supports eager loading.
+ *
+ * This class wraps the standard query builder and adds eager loading capabilities.
+ * It intercepts query results and loads the specified relationships.
+ *
+ * Usage:
+ * ```typescript
+ * // Load users with their posts eagerly loaded
+ * const users = await User.with('posts').get();
+ *
+ * // Load users with multiple relationships
+ * const users = await User.with('posts', 'profile').get();
+ *
+ * // Access eagerly loaded relations
+ * for (const user of users) {
+ *     const posts = user.getRelation('posts'); // Already loaded, no additional query
+ * }
+ * ```
+ *
+ * @template T - The model type being queried
+ */
+export class EagerLoadingBuilder<T extends Model> {
+	/**
+	 * The underlying query builder.
+	 */
+	protected builder: Builder;
+
+	/**
+	 * The model class constructor.
+	 */
+	protected modelClass: new (attrs?: Record<string, unknown>) => T;
+
+	/**
+	 * The relationships to eager load.
+	 */
+	protected eagerLoad: string[] = [];
+
+	/**
+	 * A prototype model instance for hydration and relation methods.
+	 */
+	protected modelInstance: T;
+
+	/**
+	 * Create a new EagerLoadingBuilder instance.
+	 *
+	 * @param modelClass - The model class constructor
+	 * @param builder - The underlying query builder
+	 * @param relations - Array of relationship names to eager load
+	 */
+	constructor(
+		modelClass: new (attrs?: Record<string, unknown>) => T,
+		builder: Builder,
+		relations: string[]
+	) {
+		this.modelClass = modelClass;
+		this.builder = builder;
+		this.eagerLoad = relations;
+		this.modelInstance = new modelClass();
+	}
+
+	// ==========================================
+	// Query Execution with Eager Loading
+	// ==========================================
+
+	/**
+	 * Execute the query and get all results with eager loaded relationships.
+	 *
+	 * @returns Array of models with relationships loaded
+	 */
+	public async get(): Promise<T[]> {
+		// Execute the query
+		const results = await this.builder.get<any>();
+
+		let models: T[];
+
+		// Check if results are already models (if builder is Eloquent Builder)
+		if (results.length > 0 && results[0] instanceof this.modelClass) {
+			models = results as T[];
+		} else {
+			// Hydrate the models
+			models = results.map((row) => this.hydrateModel(row));
+		}
+
+		// If no results, return empty array
+		if (models.length === 0) {
+			return models;
+		}
+
+		// Eager load the relationships
+		await this.eagerLoadRelations(models, this.eagerLoad);
+
+		return models;
+	}
+
+	/**
+	 * Execute the query and get the first result with eager loaded relationships.
+	 *
+	 * @returns The first model or null
+	 */
+	public async first(): Promise<T | null> {
+		// Execute the query
+		const result = await this.builder.first<any>();
+
+		if (!result) {
+			return null;
+		}
+
+		let model: T;
+
+		// Check if result is already a model
+		if (result instanceof this.modelClass) {
+			model = result as T;
+		} else {
+			// Hydrate the model
+			model = this.hydrateModel(result);
+		}
+
+		// Eager load the relationships for single model
+		await this.eagerLoadRelations([model], this.eagerLoad);
+
+		return model;
+	}
+
+	/**
+	 * Find a model by its primary key with eager loaded relationships.
+	 *
+	 * @param id - The primary key value
+	 * @returns The model or null
+	 */
+	public async find(id: number | string): Promise<T | null> {
+		const keyName = this.modelInstance.getKeyName();
+		this.builder.where(keyName, '=', id as string | number | boolean | null);
+		return this.first();
+	}
+
+	// ==========================================
+	// Eager Loading Logic
+	// ==========================================
+
+	/**
+	 * Eager load relationships for a collection of models.
+	 *
+	 * @param models - Array of models to load relations for
+	 * @param relations - Array of relationship names
+	 */
+	protected async eagerLoadRelations(models: T[], relations: string[]): Promise<void> {
+		for (const relationName of relations) {
+			// Parse nested relations (e.g., 'posts.comments' -> 'posts', 'comments')
+			const segments = relationName.split('.');
+			const baseRelation = segments[0];
+			const nestedRelation = segments.slice(1).join('.');
+
+			// Load the base relation
+			await this.loadRelation(models, baseRelation, nestedRelation);
+		}
+	}
+
+	/**
+	 * Load a single relationship for the models.
+	 *
+	 * @param models - Array of parent models
+	 * @param relationName - The name of the relationship method
+	 * @param nestedRelation - Any nested relations to load after this one
+	 */
+	protected async loadRelation(
+		models: T[],
+		relationName: string,
+		nestedRelation: string
+	): Promise<void> {
+		if (models.length === 0) {
+			return;
+		}
+
+		// Get the relationship definition from the first model
+		const firstModel = models[0];
+
+		// Check if the relationship method exists
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const relationMethodDescriptor = (firstModel as any)[relationName];
+		if (typeof relationMethodDescriptor !== 'function') {
+			throw new Error(
+				`Relation method [${relationName}] not found on model [${firstModel.constructor.name}]`
+			);
+		}
+
+		// Get the relation instance from the first model
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const relation: Relation<Model> = (firstModel as any)[relationName]();
+
+		// Initialize for eager loading (removes parent-specific constraints)
+		relation.initializeForEagerLoading();
+
+		// Add constraints for all parent models
+		relation.addEagerConstraints(models);
+
+		// Execute the query to get all related models
+		const results = await relation.getAll();
+
+		// Match the results to their parent models
+		relation.match(models, results, relationName);
+
+		// If there are nested relations, recursively load them
+		if (nestedRelation && results.length > 0) {
+			// Create an EagerLoadingBuilder for the related models
+			const relatedClass = relation.getRelated().constructor as new (
+				attrs?: Record<string, unknown>
+			) => Model;
+			const nestedBuilder = new EagerLoadingBuilder(
+				relatedClass,
+				relation.getQuery(),
+				[nestedRelation]
+			);
+			// Load the nested relations on the results
+			await nestedBuilder.eagerLoadRelations(results, [nestedRelation]);
+		}
+	}
+
+	// ==========================================
+	// Model Hydration
+	// ==========================================
+
+	/**
+	 * Create a model instance from a database row.
+	 *
+	 * @param row - The database row
+	 * @returns A new model instance
+	 */
+	protected hydrateModel(row: Record<string, unknown>): T {
+		const model = new this.modelClass();
+		model.forceFill(row);
+		model.exists = true;
+		model.syncOriginal();
+		return model;
+	}
+
+	// ==========================================
+	// Query Builder Forwarding Methods
+	// ==========================================
+
+	/**
+	 * Add a WHERE clause to the query.
+	 */
+	public where(
+		column: string,
+		operatorOrValue?: string | number | boolean | null,
+		value?: string | number | boolean | null
+	): this {
+		this.builder.where(column, operatorOrValue, value);
+		return this;
+	}
+
+	/**
+	 * Add an OR WHERE clause to the query.
+	 */
+	public orWhere(
+		column: string,
+		operatorOrValue?: string | number | boolean | null,
+		value?: string | number | boolean | null
+	): this {
+		this.builder.orWhere(column, operatorOrValue, value);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IN clause to the query.
+	 */
+	public whereIn(column: string, values: (string | number | boolean | null)[]): this {
+		this.builder.whereIn(column, values);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NULL clause to the query.
+	 */
+	public whereNull(column: string): this {
+		this.builder.whereNull(column);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NOT NULL clause to the query.
+	 */
+	public whereNotNull(column: string): this {
+		this.builder.whereNotNull(column);
+		return this;
+	}
+
+	/**
+	 * Add an ORDER BY clause to the query.
+	 */
+	public orderBy(column: string, direction: 'asc' | 'desc' = 'asc'): this {
+		this.builder.orderBy(column, direction);
+		return this;
+	}
+
+	/**
+	 * Add a LIMIT clause to the query.
+	 */
+	public limit(value: number): this {
+		this.builder.limit(value);
+		return this;
+	}
+
+	/**
+	 * Add an OFFSET clause to the query.
+	 */
+	public offset(value: number): this {
+		this.builder.offset(value);
+		return this;
+	}
+
+	/**
+	 * Add additional relationships to eager load.
+	 */
+	public with(...relations: string[]): this {
+		this.eagerLoad.push(...relations);
+		return this;
+	}
+}

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

@@ -0,0 +1,303 @@
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding } from '../query/types';
+
+/**
+ * HasMany Relationship - Represents a one-to-many relationship.
+ *
+ * The foreign key is on the RELATED model's table, referencing the parent.
+ *
+ * Example Schema:
+ * - users table: id, name, email
+ * - posts table: id, user_id, title, content
+ *
+ * The `user_id` column on `posts` references `users.id`.
+ * User "has many" Posts.
+ *
+ * Usage:
+ * ```typescript
+ * class User extends Model {
+ *     posts() {
+ *         return this.hasMany(Post, 'user_id', 'id');
+ *     }
+ * }
+ *
+ * // Get all user's posts
+ * const user = await User.find(1);
+ * const posts = await user.posts().get(); // Returns Post[]
+ *
+ * // Filter posts
+ * const recentPosts = await user.posts()
+ *     .where('published', true)
+ *     .orderBy('created_at', 'desc')
+ *     .limit(5)
+ *     .get();
+ * ```
+ *
+ * @template TRelated - The type of the related model
+ */
+export class HasMany<TRelated extends Model> extends Relation<TRelated> {
+	/**
+	 * The foreign key on the related model's table.
+	 * Example: 'user_id' on posts table
+	 */
+	protected foreignKey: string;
+
+	/**
+	 * The local key on the parent model's table.
+	 * Example: 'id' on users table
+	 */
+	protected localKey: string;
+
+	/**
+	 * Create a new HasMany relationship instance.
+	 *
+	 * @param parent - The parent model instance
+	 * @param related - An instance of the related model class
+	 * @param foreignKey - The foreign key column on the related model (e.g., 'user_id')
+	 * @param localKey - The local key column on the parent model (e.g., 'id')
+	 */
+	constructor(
+		parent: Model,
+		related: TRelated,
+		foreignKey: string,
+		localKey: string
+	) {
+		super(parent, related);
+
+		this.foreignKey = foreignKey;
+		this.localKey = localKey;
+
+		// 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 localKeyValue = this.getParentKeyValue(this.localKey);
+
+		if (localKeyValue !== undefined && localKeyValue !== null) {
+			this.query.where(this.foreignKey, '=', localKeyValue as Binding);
+		}
+	}
+
+	/**
+	 * Add the constraints for the HasMany 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 HasMany 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 localKeyValue = this.getParentKeyValue(this.localKey);
+
+		// If parent doesn't have a key value, return empty array
+		if (localKeyValue === undefined || localKeyValue === null) {
+			return [];
+		}
+
+		return this.getAll();
+	}
+
+	/**
+	 * Create a new related model and associate it with the parent.
+	 *
+	 * This creates a new related model with the given attributes,
+	 * automatically sets the foreign key, and saves it to the database.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const user = await User.find(1);
+	 * const post = await user.posts().create({
+	 *     title: 'My New Post',
+	 *     content: 'Hello World!'
+	 * });
+	 * ```
+	 *
+	 * @param attributes - The attributes for the new model
+	 * @returns The newly created and saved model
+	 */
+	public async create(attributes: Record<string, unknown>): Promise<TRelated> {
+		// Add the foreign key to the attributes
+		const localKeyValue = this.getParentKeyValue(this.localKey);
+		const createAttributes = {
+			...attributes,
+			[this.foreignKey]: localKeyValue
+		};
+
+		// Create and save the model
+		// Use true for exists (second arg) to bypass mass assignment protection via newInstance fix
+		// OR ensure newInstance handles this. 
+		// Actually, simpler to just instantiate and then forceFill to ensure attributes are set.
+
+		const instance = this.related.newInstance({}, false);
+		instance.forceFill(createAttributes);
+		await instance.save();
+
+		return instance;
+	}
+
+	/**
+	 * Save an existing model and associate it with the parent.
+	 *
+	 * This sets the foreign key on the model and saves it to the database.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const user = await User.find(1);
+	 * const post = new Post({ title: 'My New Post' });
+	 * await user.posts().save(post);
+	 * ```
+	 *
+	 * @param model - The model to save
+	 * @returns The saved model
+	 */
+	public async save(model: TRelated): Promise<TRelated> {
+		// Set the foreign key using forceFill to bypass potential guarding
+		const localKeyValue = this.getParentKeyValue(this.localKey);
+		model.forceFill({
+			[this.foreignKey]: localKeyValue
+		});
+
+		// Save the model
+		await model.save();
+
+		return model;
+	}
+
+	/**
+	 * Save multiple models and associate them with the parent.
+	 *
+	 * @param models - Array of models to save
+	 * @returns Array of saved models
+	 */
+	public async saveMany(models: TRelated[]): Promise<TRelated[]> {
+		const savedModels: TRelated[] = [];
+
+		for (const model of models) {
+			savedModels.push(await this.save(model));
+		}
+
+		return savedModels;
+	}
+
+	/**
+	 * Create multiple related models and associate them with the parent.
+	 *
+	 * @param records - Array of attribute objects for new models
+	 * @returns Array of newly created models
+	 */
+	public async createMany(records: Record<string, unknown>[]): Promise<TRelated[]> {
+		const createdModels: TRelated[] = [];
+
+		for (const attributes of records) {
+			createdModels.push(await this.create(attributes));
+		}
+
+		return createdModels;
+	}
+
+	/**
+	 * Get the foreign key column name.
+	 *
+	 * @returns The foreign key column name
+	 */
+	public getForeignKeyName(): string {
+		return this.foreignKey;
+	}
+
+	/**
+	 * Get the fully qualified foreign key name (table.column).
+	 *
+	 * @returns The qualified foreign key name
+	 */
+	public getQualifiedForeignKeyName(): string {
+		return this.qualifyColumn(this.related.getTable(), this.foreignKey);
+	}
+
+	/**
+	 * Get the local key column name.
+	 *
+	 * @returns The local key column name
+	 */
+	public getLocalKeyName(): string {
+		return this.localKey;
+	}
+
+	/**
+	 * Get the value of the parent's local key.
+	 *
+	 * @returns The local key value
+	 */
+	public getParentKey(): unknown {
+		return this.getParentKeyValue(this.localKey);
+	}
+
+	// ==========================================
+	// Eager Loading Methods
+	// ==========================================
+
+	/**
+	 * Add constraints for eager loading.
+	 * Uses WHERE IN 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.localKey);
+			if (key !== undefined && key !== null) {
+				keys.push(key);
+			}
+		}
+
+		// Remove duplicates
+		const uniqueKeys = [...new Set(keys)];
+
+		// Add WHERE IN constraint
+		if (uniqueKeys.length > 0) {
+			this.query.whereIn(this.foreignKey, uniqueKeys as (string | number | boolean)[]);
+		}
+	}
+
+	/**
+	 * Match the eagerly loaded results to their parent models.
+	 * For HasMany, 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: foreignKey value -> array of related models
+		const dictionary = new Map<unknown, TRelated[]>();
+		for (const result of results) {
+			const foreignKeyValue = result.getAttribute(this.foreignKey);
+			if (!dictionary.has(foreignKeyValue)) {
+				dictionary.set(foreignKeyValue, []);
+			}
+			dictionary.get(foreignKeyValue)!.push(result);
+		}
+
+		// Match each parent model with its array of related models
+		for (const model of models) {
+			const localKeyValue = model.getAttribute(this.localKey);
+			const matches = dictionary.get(localKeyValue) || [];
+			model.setRelation(relation, matches);
+		}
+	}
+}