create-phoenixjs 0.1.4 → 0.1.6

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

@@ -0,0 +1,246 @@
+import { Relation } from './Relation';
+import type { Model } from './Model';
+import type { Binding } from '../query/types';
+
+/**
+ * BelongsTo Relationship - Represents the inverse of a one-to-one or one-to-many.
+ *
+ * The foreign key is on the CURRENT 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`.
+ * Profile "belongs to" User.
+ *
+ * Usage:
+ * ```typescript
+ * class Profile extends Model {
+ *     user() {
+ *         return this.belongsTo(User, 'user_id', 'id');
+ *     }
+ * }
+ *
+ * // Get the profile's user
+ * const profile = await Profile.find(1);
+ * const user = await profile.user().get();
+ * ```
+ *
+ * Also used for the inverse of HasMany:
+ * ```typescript
+ * class Post extends Model {
+ *     author() {
+ *         return this.belongsTo(User, 'user_id', 'id');
+ *     }
+ * }
+ * ```
+ *
+ * @template TRelated - The type of the related (parent) model
+ */
+export class BelongsTo<TRelated extends Model> extends Relation<TRelated> {
+	/**
+	 * The foreign key on the child (current) model's table.
+	 * Example: 'user_id' on profiles/posts table
+	 */
+	protected foreignKey: string;
+
+	/**
+	 * The owner (primary) key on the parent model's table.
+	 * Example: 'id' on users table
+	 */
+	protected ownerKey: string;
+
+	/**
+	 * Create a new BelongsTo relationship instance.
+	 *
+	 * @param parent - The child model instance (the one with the foreign key)
+	 * @param related - An instance of the parent model class
+	 * @param foreignKey - The foreign key column on the child model (e.g., 'user_id')
+	 * @param ownerKey - The owner key column on the parent model (e.g., 'id')
+	 */
+	constructor(
+		parent: Model,
+		related: TRelated,
+		foreignKey: string,
+		ownerKey: string
+	) {
+		super(parent, related);
+
+		this.foreignKey = foreignKey;
+		this.ownerKey = ownerKey;
+
+		// 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 foreignKeyValue = this.parent.getAttribute(this.foreignKey);
+
+		if (foreignKeyValue !== undefined && foreignKeyValue !== null) {
+			this.query.where(this.ownerKey, '=', foreignKeyValue as Binding);
+		}
+	}
+
+	/**
+	 * Add the constraints for the BelongsTo 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 BelongsTo relationship.
+	 *
+	 * Returns the parent model or null if none exists.
+	 *
+	 * @returns The parent model or null
+	 */
+	public async getResults(): Promise<TRelated | null> {
+		const foreignKeyValue = this.parent.getAttribute(this.foreignKey);
+
+		// If child doesn't have a foreign key value, return null
+		if (foreignKeyValue === undefined || foreignKeyValue === null) {
+			return null;
+		}
+
+		return this.first();
+	}
+
+	/**
+	 * Associate a parent model with this child model.
+	 *
+	 * This sets the foreign key on the child model to the parent's primary key.
+	 * Note: This does NOT save the child model - you must call save() yourself.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const profile = new Profile({ bio: 'Hello' });
+	 * const user = await User.find(1);
+	 * profile.user().associate(user);
+	 * await profile.save();
+	 * ```
+	 *
+	 * @param model - The parent model to associate
+	 * @returns The child model for chaining
+	 */
+	public associate(model: TRelated): Model {
+		const ownerKeyValue = model.getAttribute(this.ownerKey);
+		this.parent.setAttribute(this.foreignKey, ownerKeyValue);
+		return this.parent;
+	}
+
+	/**
+	 * Dissociate the parent model from this child model.
+	 *
+	 * This sets the foreign key on the child model to null.
+	 * Note: This does NOT save the child model - you must call save() yourself.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const profile = await Profile.find(1);
+	 * profile.user().dissociate();
+	 * await profile.save();
+	 * ```
+	 *
+	 * @returns The child model for chaining
+	 */
+	public dissociate(): Model {
+		this.parent.setAttribute(this.foreignKey, null);
+		return this.parent;
+	}
+
+	/**
+	 * 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.parent.getTable(), this.foreignKey);
+	}
+
+	/**
+	 * Get the owner key column name.
+	 *
+	 * @returns The owner key column name
+	 */
+	public getOwnerKeyName(): string {
+		return this.ownerKey;
+	}
+
+	/**
+	 * Get the value of the child's foreign key.
+	 *
+	 * @returns The foreign key value
+	 */
+	public getForeignKeyValue(): unknown {
+		return this.parent.getAttribute(this.foreignKey);
+	}
+
+	// ==========================================
+	// Eager Loading Methods
+	// ==========================================
+
+	/**
+	 * Add constraints for eager loading.
+	 * Uses WHERE IN to fetch all parent models for multiple children at once.
+	 *
+	 * @param models - Array of child models to load parents for
+	 */
+	public addEagerConstraints(models: Model[]): void {
+		// Collect all foreign key values from child models
+		const keys: unknown[] = [];
+		for (const model of models) {
+			const key = model.getAttribute(this.foreignKey);
+			if (key !== undefined && key !== null) {
+				keys.push(key);
+			}
+		}
+
+		// Remove duplicates
+		const uniqueKeys = [...new Set(keys)];
+
+		// Add WHERE IN constraint on the owner key
+		if (uniqueKeys.length > 0) {
+			this.query.whereIn(this.ownerKey, uniqueKeys as (string | number | boolean)[]);
+		}
+	}
+
+	/**
+	 * Match the eagerly loaded results to their child models.
+	 * For BelongsTo, each child gets at most one parent model.
+	 *
+	 * @param models - Array of child models
+	 * @param results - Array of parent 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: ownerKey value -> parent model
+		const dictionary = new Map<unknown, TRelated>();
+		for (const result of results) {
+			const ownerKeyValue = result.getAttribute(this.ownerKey);
+			dictionary.set(ownerKeyValue, result);
+		}
+
+		// Match each child model with its parent model
+		for (const model of models) {
+			const foreignKeyValue = model.getAttribute(this.foreignKey);
+			const match = dictionary.get(foreignKeyValue) || null;
+			model.setRelation(relation, match);
+		}
+	}
+}