create-phoenixjs 0.1.4 → 0.1.5

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

@@ -0,0 +1,282 @@
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding } from '../query/types';
+
+/**
+ * HasManyThrough Relationship - Retrieves multiple related models through an intermediate model.
+ *
+ * This is useful when you need to access data that is related through another table.
+ *
+ * Example Schema:
+ * - countries table: id, name
+ * - users table: id, country_id, name
+ * - posts table: id, user_id, title, content
+ *
+ * A Country has many Posts through Users.
+ *
+ * Usage:
+ * ```typescript
+ * class Country extends Model {
+ *     posts() {
+ *         return this.hasManyThrough(
+ *             Post,           // Final related model
+ *             User,           // Intermediate model
+ *             'country_id',   // Foreign key on users table (links to countries)
+ *             'user_id',      // Foreign key on posts table (links to users)
+ *             'id',           // Local key on countries table
+ *             'id'            // Local key on users table
+ *         );
+ *     }
+ * }
+ *
+ * const country = await Country.find(1);
+ * const posts = await country.posts().get(); // All posts from users in this country
+ * ```
+ *
+ * @template TRelated - The type of the final related model
+ */
+export class HasManyThrough<TRelated extends Model> extends Relation<TRelated> {
+	/**
+	 * The intermediate ("through") model instance.
+	 */
+	protected throughModel: Model;
+
+	/**
+	 * The foreign key on the intermediate table (referencing parent).
+	 * Example: 'country_id' on users table
+	 */
+	protected firstKey: string;
+
+	/**
+	 * The foreign key on the final related table (referencing intermediate).
+	 * Example: 'user_id' on posts table
+	 */
+	protected secondKey: string;
+
+	/**
+	 * The local key on the parent model.
+	 * Example: 'id' on countries table
+	 */
+	protected localKey: string;
+
+	/**
+	 * The local key on the intermediate model.
+	 * Example: 'id' on users table
+	 */
+	protected secondLocalKey: string;
+
+	/**
+	 * Create a new HasManyThrough relationship instance.
+	 *
+	 * @param parent - The parent model instance (e.g., Country)
+	 * @param related - An instance of the final related model class (e.g., Post)
+	 * @param through - An instance of the intermediate model class (e.g., User)
+	 * @param firstKey - Foreign key on intermediate table referencing parent (e.g., 'country_id')
+	 * @param secondKey - Foreign key on final table referencing intermediate (e.g., 'user_id')
+	 * @param localKey - Primary key on parent model (e.g., 'id')
+	 * @param secondLocalKey - Primary key on intermediate model (e.g., 'id')
+	 */
+	constructor(
+		parent: Model,
+		related: TRelated,
+		through: Model,
+		firstKey: string,
+		secondKey: string,
+		localKey: string,
+		secondLocalKey: string
+	) {
+		super(parent, related);
+
+		this.throughModel = through;
+		this.firstKey = firstKey;
+		this.secondKey = secondKey;
+		this.localKey = localKey;
+		this.secondLocalKey = secondLocalKey;
+
+		// 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.localKey);
+		const throughTable = this.throughModel.getTable();
+		const relatedTable = this.related.getTable();
+
+		// Join the intermediate table to the final table
+		// posts JOIN users ON posts.user_id = users.id
+		this.query.join(
+			throughTable,
+			`${relatedTable}.${this.secondKey}`,
+			'=',
+			`${throughTable}.${this.secondLocalKey}`
+		);
+
+		// Constrain by parent's key through the intermediate table
+		// WHERE users.country_id = {country.id}
+		if (parentKeyValue !== undefined && parentKeyValue !== null) {
+			this.query.where(`${throughTable}.${this.firstKey}`, '=', parentKeyValue as Binding);
+		}
+	}
+
+	/**
+	 * Add the constraints for the HasManyThrough 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 HasManyThrough 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.localKey);
+
+		// If parent doesn't have a key value, return empty array
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			return [];
+		}
+
+		return this.getAll();
+	}
+
+	/**
+	 * Get the intermediate model.
+	 *
+	 * @returns The through model instance
+	 */
+	public getThroughModel(): Model {
+		return this.throughModel;
+	}
+
+	/**
+	 * Get the first key (foreign key on intermediate table).
+	 *
+	 * @returns The first key column name
+	 */
+	public getFirstKeyName(): string {
+		return this.firstKey;
+	}
+
+	/**
+	 * Get the second key (foreign key on final table).
+	 *
+	 * @returns The second key column name
+	 */
+	public getSecondKeyName(): string {
+		return this.secondKey;
+	}
+
+	/**
+	 * Get the qualified first key name.
+	 *
+	 * @returns The qualified column name
+	 */
+	public getQualifiedFirstKeyName(): string {
+		return `${this.throughModel.getTable()}.${this.firstKey}`;
+	}
+
+	/**
+	 * Get the qualified second key name.
+	 *
+	 * @returns The qualified column name
+	 */
+	public getQualifiedSecondKeyName(): string {
+		return `${this.related.getTable()}.${this.secondKey}`;
+	}
+
+	// ==========================================
+	// Eager Loading Methods
+	// ==========================================
+
+	/**
+	 * Initialize the relation for eager loading.
+	 * Creates a fresh query with the through join but without parent-specific constraints.
+	 */
+	public override initializeForEagerLoading(): void {
+		this.query = this.newQuery();
+		const throughTable = this.throughModel.getTable();
+		const relatedTable = this.related.getTable();
+
+		// Explicitly select all columns from related table to preserve them when adding rawSelect
+		this.query.select(`${relatedTable}.*`);
+
+		// Join the intermediate table to the final table (required for HasManyThrough)
+		this.query.join(
+			throughTable,
+			`${relatedTable}.${this.secondKey}`,
+			'=',
+			`${throughTable}.${this.secondLocalKey}`
+		);
+	}
+
+	/**
+	 * Add constraints for eager loading.
+	 * Uses WHERE IN on the through 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.localKey);
+			if (key !== undefined && key !== null) {
+				keys.push(key);
+			}
+		}
+
+		// Remove duplicates
+		const uniqueKeys = [...new Set(keys)];
+
+		// Add WHERE IN constraint on the through table's first key
+		const throughTable = this.throughModel.getTable();
+		if (uniqueKeys.length > 0) {
+			this.query.whereIn(
+				`${throughTable}.${this.firstKey}`,
+				uniqueKeys as (string | number | boolean)[]
+			);
+		}
+
+		// Select the firstKey from through table to enable matching (use selectRaw for proper alias)
+		this.query.selectRaw(`${throughTable}.${this.firstKey} as laravel_through_key`);
+	}
+
+	/**
+	 * Match the eagerly loaded results to their parent models.
+	 * For HasManyThrough, 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: parent key 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 through key from the result (added as laravel_through_key)
+			const throughKeyValue = String(result.getAttribute('laravel_through_key'));
+			if (!dictionary.has(throughKeyValue)) {
+				dictionary.set(throughKeyValue, []);
+			}
+			dictionary.get(throughKeyValue)!.push(result);
+		}
+
+		// Match each parent model with its array of related models
+		for (const model of models) {
+			const localKeyValue = String(model.getAttribute(this.localKey));
+			const matches = dictionary.get(localKeyValue) || [];
+			model.setRelation(relation, matches);
+		}
+	}
+}

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

@@ -0,0 +1,201 @@
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding } from '../query/types';
+
+/**
+ * HasOne Relationship - Represents a one-to-one relationship.
+ *
+ * The foreign key is on the RELATED model's table, referencing the parent.
+ *
+ * Example Schema:
+ * - users table: id, name, email
+ * - profiles table: id, user_id, bio
+ *
+ * The `user_id` column on `profiles` references `users.id`.
+ *
+ * Usage:
+ * ```typescript
+ * class User extends Model {
+ *     profile() {
+ *         return this.hasOne(Profile, 'user_id', 'id');
+ *     }
+ * }
+ *
+ * // Get the user's profile
+ * const user = await User.find(1);
+ * const profile = await user.profile().get();
+ * ```
+ *
+ * @template TRelated - The type of the related model
+ */
+export class HasOne<TRelated extends Model> extends Relation<TRelated> {
+	/**
+	 * The foreign key on the related model's table.
+	 * Example: 'user_id' on profiles table
+	 */
+	protected foreignKey: string;
+
+	/**
+	 * The local key on the parent model's table.
+	 * Example: 'id' on users table
+	 */
+	protected localKey: string;
+
+	/**
+	 * Create a new HasOne 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
+	) {
+		// Initialize keys before calling super
+		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.
+	 * Called after constructor completes key assignment.
+	 */
+	private reinitializeConstraints(): void {
+		// Reset query and add constraints with proper keys
+		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 HasOne 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 HasOne relationship.
+	 *
+	 * Returns a single related model or null if none exists.
+	 * Even though the underlying query might return multiple rows,
+	 * this method only returns the first result.
+	 *
+	 * @returns The related model or null
+	 */
+	public async getResults(): Promise<TRelated | null> {
+		const localKeyValue = this.getParentKeyValue(this.localKey);
+
+		// If parent doesn't have a key value, return null
+		if (localKeyValue === undefined || localKeyValue === null) {
+			return null;
+		}
+
+		return this.first();
+	}
+
+	/**
+	 * 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 HasOne, each parent gets at most one related model.
+	 *
+	 * @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(1) lookup: foreignKey value -> related model
+		const dictionary = new Map<unknown, TRelated>();
+		for (const result of results) {
+			const foreignKeyValue = result.getAttribute(this.foreignKey);
+			// For HasOne, only keep the first match (if duplicates exist)
+			if (!dictionary.has(foreignKeyValue)) {
+				dictionary.set(foreignKeyValue, result);
+			}
+		}
+
+		// Match each parent model with its related model
+		for (const model of models) {
+			const localKeyValue = model.getAttribute(this.localKey);
+			const match = dictionary.get(localKeyValue) || null;
+			model.setRelation(relation, match);
+		}
+	}
+}