create-phoenixjs 0.1.3 → 0.1.5

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

@@ -0,0 +1,281 @@
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding } from '../query/types';
+
+/**
+ * HasOneThrough Relationship - Retrieves a single related model 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
+ * - profiles table: id, user_id, bio
+ *
+ * A Country has one Profile through User.
+ *
+ * Usage:
+ * ```typescript
+ * class Country extends Model {
+ *     userProfile() {
+ *         return this.hasOneThrough(
+ *             Profile,        // Final related model
+ *             User,           // Intermediate model
+ *             'country_id',   // Foreign key on users table (links to countries)
+ *             'user_id',      // Foreign key on profiles table (links to users)
+ *             'id',           // Local key on countries table
+ *             'id'            // Local key on users table
+ *         );
+ *     }
+ * }
+ *
+ * const country = await Country.find(1);
+ * const profile = await country.userProfile().get();
+ * ```
+ *
+ * @template TRelated - The type of the final related model
+ */
+export class HasOneThrough<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 profiles 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 HasOneThrough relationship instance.
+	 *
+	 * @param parent - The parent model instance (e.g., Country)
+	 * @param related - An instance of the final related model class (e.g., Profile)
+	 * @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
+		// profiles JOIN users ON profiles.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 HasOneThrough 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 HasOneThrough relationship.
+	 *
+	 * Returns a single related model or null if the chain is broken.
+	 *
+	 * @returns The related model or null
+	 */
+	public async getResults(): Promise<TRelated | null> {
+		const parentKeyValue = this.parent.getAttribute(this.localKey);
+
+		// If parent doesn't have a key value, return null
+		if (parentKeyValue === undefined || parentKeyValue === null) {
+			return null;
+		}
+
+		return this.first();
+	}
+
+	/**
+	 * 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 HasOneThrough)
+		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 HasOneThrough, 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: parent key value -> related model
+		// 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'));
+			// For HasOneThrough, only keep the first match (if duplicates exist)
+			if (!dictionary.has(throughKeyValue)) {
+				dictionary.set(throughKeyValue, result);
+			}
+		}
+
+		// Match each parent model with its related model
+		for (const model of models) {
+			const localKeyValue = String(model.getAttribute(this.localKey));
+			const match = dictionary.get(localKeyValue) || null;
+			model.setRelation(relation, match);
+		}
+	}
+}