@buenojs/bueno 0.8.4 → 0.8.6

package/src/database/orm/relationships/base.ts

@@ -0,0 +1,146 @@
+// @ts-nocheck - Abstract class generic constraints cause false positives in TypeScript.
+// The implementation is logically correct; see .idea/orm-implementation-status.md
+
+/**
+ * Base Relationship Class
+ *
+ * Abstract base for all relationship types (HasOne, HasMany, etc.)
+ */
+
+import type { Database } from "../../index";
+import { OrmQueryBuilder } from "../builder";
+import type { Model } from "../model";
+import { getModelDatabase } from "../model-registry";
+
+export interface RelationshipOptions {
+	foreignKey?: string;
+	localKey?: string;
+	ownerKey?: string;
+	relatedKey?: string;
+}
+
+/**
+ * Abstract base relationship class
+ */
+export abstract class Relationship<
+	TParent extends Model,
+	TRelated extends Model,
+> {
+	protected query: OrmQueryBuilder<any>;
+	protected db: Database;
+
+	constructor(
+		protected parentModel: TParent,
+		protected relatedClass: { new (): TRelated } & typeof Model,
+		protected foreignKey: string,
+		protected localKey = "id",
+	) {
+		this.db = getModelDatabase(relatedClass.name);
+		this.query = new OrmQueryBuilder(this.db, relatedClass.table as string);
+		// Note: subclasses that use private fields must call initConstraints()
+		// themselves after their field assignments, rather than relying on this call.
+		this.addConstraints();
+	}
+
+	/**
+	 * Initialize constraints — call this in subclass constructors after all
+	 * private fields are assigned, if the subclass needs them in addConstraints().
+	 */
+	protected initConstraints(): void {
+		this.query = new OrmQueryBuilder(
+			this.db,
+			this.relatedClass.table as string,
+		);
+		this.addConstraints();
+	}
+
+	/**
+	 * Add WHERE clause for this relationship
+	 * (override in subclasses)
+	 */
+	abstract addConstraints(): void;
+
+	/**
+	 * Add eager load constraints
+	 * (override in subclasses)
+	 */
+	abstract addEagerConstraints(parents: TParent[]): void;
+
+	/**
+	 * Match eager-loaded results to parent models
+	 * (override in subclasses)
+	 */
+	abstract match(
+		parents: TParent[],
+		results: TRelated[],
+		relation: string,
+	): void;
+
+	/**
+	 * Get the results for this relationship
+	 */
+	abstract getResults(): Promise<TRelated | TRelated[] | null>;
+
+	/**
+	 * Reset the query builder to a fresh state
+	 * Used during eager loading to clear single-model constraints from constructor
+	 */
+	protected resetQuery(): void {
+		this.query = new OrmQueryBuilder(
+			this.db,
+			this.relatedClass.table as string,
+		);
+	}
+
+	// ============= Chainable Methods =============
+
+	where(column: string, operator: unknown, value?: unknown): this {
+		this.query.where(column, operator, value);
+		return this;
+	}
+
+	orWhere(column: string, operator: unknown, value?: unknown): this {
+		this.query.orWhere(column, operator, value);
+		return this;
+	}
+
+	orderBy(column: string, direction?: "ASC" | "DESC"): this {
+		this.query.orderBy(column, direction);
+		return this;
+	}
+
+	limit(n: number): this {
+		this.query.limit(n);
+		return this;
+	}
+
+	// ============= Query Terminals =============
+
+	async get(): Promise<TRelated[]> {
+		const rows = await this.query.get();
+		return this.relatedClass.hydrate(rows) as TRelated[];
+	}
+
+	async first(): Promise<TRelated | null> {
+		const rows = await this.query.limit(1).get();
+		if (rows.length === 0) return null;
+		return this.relatedClass.hydrate([rows[0]])[0] as TRelated;
+	}
+
+	async count(): Promise<number> {
+		return this.query.count();
+	}
+
+	async exists(): Promise<boolean> {
+		return this.query.exists();
+	}
+
+	async create(data: Record<string, unknown>): Promise<TRelated> {
+		// Set the foreign key
+		const model_data = {
+			...data,
+			[this.foreignKey]: this.parentModel.getAttribute(this.localKey as any),
+		};
+		return this.relatedClass.create(model_data);
+	}
+}

package/src/database/orm/relationships/belongs-to-many.ts

@@ -0,0 +1,179 @@
+/**
+ * BelongsToMany Relationship
+ *
+ * Model belongs to many related models through a pivot table (n:m)
+ */
+
+import type { Database } from "../../index";
+import { OrmQueryBuilder } from "../builder";
+import type { Model } from "../model";
+import { getModelDatabase } from "../model-registry";
+import { Relationship } from "./base";
+
+export class BelongsToMany<TRelated extends Model> extends Relationship<
+	any,
+	TRelated
+> {
+	private pivotData: Set<string> = new Set();
+
+	constructor(
+		parentModel: Model,
+		relatedClass: { new (): TRelated } & typeof Model,
+		private pivotTable: string,
+		private foreignPivotKey: string,
+		private relatedPivotKey: string,
+		private parentKey = "id",
+		private relatedKey = "id",
+	) {
+		super(parentModel, relatedClass, foreignPivotKey, parentKey);
+		// Private fields are assigned after super() returns, so we must
+		// re-initialize constraints now that they are available.
+		this.initConstraints();
+	}
+
+	addConstraints(): void {
+		// Guard: if pivotTable hasn't been assigned yet (called from base super()),
+		// do nothing — initConstraints() will call us again after field assignment.
+		if (!this.pivotTable) return;
+		const parentId = this.parentModel.getAttribute(this.parentKey as any);
+
+		this.query.join(
+			this.pivotTable,
+			`${this.pivotTable}.${this.relatedPivotKey} = ${(this.relatedClass as any).table}.${this.relatedKey}`,
+		);
+		this.query.where(`${this.pivotTable}.${this.foreignPivotKey}`, parentId);
+	}
+
+	addEagerConstraints(parents: Model[]): void {
+		const ids = parents.map((p) => p.getAttribute(this.parentKey as any));
+		this.query.whereIn(`${this.pivotTable}.${this.foreignPivotKey}`, ids);
+	}
+
+	match(parents: Model[], results: TRelated[], relation: string): void {
+		const grouped = new Map<unknown, TRelated[]>();
+
+		for (const result of results) {
+			// The JOIN puts the pivot FK column in the result row as a regular attribute
+			const parentId = result.getAttribute(this.foreignPivotKey as any);
+			if (!grouped.has(parentId)) {
+				grouped.set(parentId, []);
+			}
+			grouped.get(parentId)!.push(result);
+		}
+
+		for (const parent of parents) {
+			const key = parent.getAttribute(this.parentKey as any);
+			const related = grouped.get(key) ?? [];
+			(parent as any)._relations.set(relation, related);
+		}
+	}
+
+	/**
+	 * Include specific pivot columns in results
+	 */
+	withPivot(...columns: string[]): this {
+		for (const col of columns) {
+			this.pivotData.add(col);
+		}
+		return this;
+	}
+
+	/**
+	 * Attach related models to the pivot table
+	 */
+	async attach(
+		ids: unknown | unknown[],
+		pivotData?: Record<string, unknown>,
+	): Promise<void> {
+		const idArray = Array.isArray(ids) ? ids : [ids];
+		const parentId = this.parentModel.getAttribute(this.parentKey as any);
+
+		const db = getModelDatabase(this.relatedClass.name);
+
+		for (const id of idArray) {
+			const data = {
+				[this.foreignPivotKey]: parentId,
+				[this.relatedPivotKey]: id,
+				...pivotData,
+			};
+
+			// Use raw insert to avoid OrmQueryBuilder.insert()'s SELECT-by-id fetch-back,
+			// which fails on pivot tables that have no 'id' primary key column.
+			const columns = Object.keys(data).join(", ");
+			const placeholders = Object.keys(data)
+				.map(() => "?")
+				.join(", ");
+			const values = Object.values(data);
+			await db.raw(
+				`INSERT INTO ${this.pivotTable} (${columns}) VALUES (${placeholders})`,
+				values,
+			);
+		}
+	}
+
+	/**
+	 * Detach related models from the pivot table
+	 */
+	async detach(ids?: unknown | unknown[]): Promise<void> {
+		const parentId = this.parentModel.getAttribute(this.parentKey as any);
+
+		const db = getModelDatabase(this.relatedClass.name);
+		let builder = new OrmQueryBuilder(db, this.pivotTable).where(
+			this.foreignPivotKey,
+			parentId,
+		);
+
+		if (ids) {
+			const idArray = Array.isArray(ids) ? ids : [ids];
+			builder = builder.whereIn(this.relatedPivotKey, idArray) as any;
+		}
+
+		await builder.delete();
+	}
+
+	/**
+	 * Sync related models (replace all with given IDs)
+	 */
+	async sync(ids: unknown[], detaching = true): Promise<void> {
+		if (detaching) {
+			await this.detach();
+		}
+		await this.attach(ids);
+	}
+
+	/**
+	 * Toggle related models
+	 */
+	async toggle(ids: unknown | unknown[]): Promise<void> {
+		const idArray = Array.isArray(ids) ? ids : [ids];
+		const attached = await this.get();
+		const attachedIds = attached.map((m) =>
+			m.getAttribute(this.relatedKey as any),
+		);
+
+		const toAttach = idArray.filter((id) => !attachedIds.includes(id));
+		const toDetach = attachedIds.filter((id) => idArray.includes(id));
+
+		await Promise.all([this.attach(toAttach), this.detach(toDetach)]);
+	}
+
+	/**
+	 * Update pivot data
+	 */
+	async updateExistingPivot(
+		id: unknown,
+		data: Record<string, unknown>,
+	): Promise<void> {
+		const parentId = this.parentModel.getAttribute(this.parentKey as any);
+
+		const db = getModelDatabase(this.relatedClass.name);
+		await new OrmQueryBuilder(db, this.pivotTable)
+			.where(this.foreignPivotKey, parentId)
+			.where(this.relatedPivotKey, id)
+			.update(data);
+	}
+
+	async getResults(): Promise<TRelated[]> {
+		return this.get();
+	}
+}

package/src/database/orm/relationships/belongs-to.ts

@@ -0,0 +1,56 @@
+/**
+ * BelongsTo Relationship
+ *
+ * Model belongs to a parent model (reverse of HasOne/HasMany)
+ */
+
+import type { Model } from "../model";
+import { Relationship } from "./base";
+
+export class BelongsTo<TRelated extends Model> extends Relationship<
+	any,
+	TRelated
+> {
+	constructor(
+		parentModel: Model,
+		relatedClass: { new (): TRelated } & typeof Model,
+		foreignKey: string,
+		ownerKey = "id",
+	) {
+		// Pass ownerKey as localKey so addConstraints() (called inside super())
+		// can access it via this.localKey before ownerKey is assigned as a field.
+		super(parentModel, relatedClass, foreignKey, ownerKey);
+	}
+
+	addConstraints(): void {
+		const parentForeignId = this.parentModel.getAttribute(
+			this.foreignKey as any,
+		);
+		// this.localKey holds the ownerKey value (e.g. "id")
+		this.query.where(this.localKey, parentForeignId);
+	}
+
+	addEagerConstraints(parents: Model[]): void {
+		const ids = parents.map((p) => p.getAttribute(this.foreignKey as any));
+		this.query.whereIn(this.localKey, ids);
+	}
+
+	match(parents: Model[], results: TRelated[], relation: string): void {
+		const grouped = new Map<unknown, TRelated>();
+
+		for (const result of results) {
+			const key = result.getAttribute(this.localKey as any);
+			grouped.set(key, result);
+		}
+
+		for (const parent of parents) {
+			const key = parent.getAttribute(this.foreignKey as any);
+			const related = grouped.get(key) ?? null;
+			(parent as any)._relations.set(relation, related);
+		}
+	}
+
+	async getResults(): Promise<TRelated | null> {
+		return this.first();
+	}
+}

package/src/database/orm/relationships/has-many.ts

@@ -0,0 +1,45 @@
+/**
+ * HasMany Relationship
+ *
+ * Model has many related models (1:n)
+ */
+
+import type { Model } from "../model";
+import { Relationship } from "./base";
+
+export class HasMany<TRelated extends Model> extends Relationship<
+	any,
+	TRelated
+> {
+	addConstraints(): void {
+		const parentId = this.parentModel.getAttribute(this.localKey as any);
+		this.query.where(this.foreignKey, parentId);
+	}
+
+	addEagerConstraints(parents: Model[]): void {
+		const ids = parents.map((p) => p.getAttribute(this.localKey as any));
+		this.query.whereIn(this.foreignKey, ids);
+	}
+
+	match(parents: Model[], results: TRelated[], relation: string): void {
+		const grouped = new Map<unknown, TRelated[]>();
+
+		for (const result of results) {
+			const key = result.getAttribute(this.foreignKey as any);
+			if (!grouped.has(key)) {
+				grouped.set(key, []);
+			}
+			grouped.get(key)!.push(result);
+		}
+
+		for (const parent of parents) {
+			const key = parent.getAttribute(this.localKey as any);
+			const related = grouped.get(key) ?? [];
+			(parent as any)._relations.set(relation, related);
+		}
+	}
+
+	async getResults(): Promise<TRelated[]> {
+		return this.get();
+	}
+}

package/src/database/orm/relationships/has-one.ts

@@ -0,0 +1,41 @@
+/**
+ * HasOne Relationship
+ *
+ * Model has one related model (1:1)
+ */
+
+import type { Model } from "../model";
+import { Relationship } from "./base";
+
+export class HasOne<TRelated extends Model> extends Relationship<
+	any,
+	TRelated
+> {
+	addConstraints(): void {
+		const parentId = this.parentModel.getAttribute(this.localKey as any);
+		this.query.where(this.foreignKey, parentId);
+	}
+
+	addEagerConstraints(parents: Model[]): void {
+		const ids = parents.map((p) => p.getAttribute(this.localKey as any));
+		this.query.whereIn(this.foreignKey, ids);
+	}
+
+	match(parents: Model[], results: TRelated[], relation: string): void {
+		const grouped = new Map<unknown, TRelated>();
+		for (const result of results) {
+			const key = result.getAttribute(this.foreignKey as any);
+			grouped.set(key, result);
+		}
+
+		for (const parent of parents) {
+			const key = parent.getAttribute(this.localKey as any);
+			const related = grouped.get(key) ?? null;
+			(parent as any)._relations.set(relation, related);
+		}
+	}
+
+	async getResults(): Promise<TRelated | null> {
+		return this.first();
+	}
+}

package/src/database/orm/relationships/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Relationship Exports
+ */
+
+export { Relationship } from "./base";
+export { HasOne } from "./has-one";
+export { HasMany } from "./has-many";
+export { BelongsTo } from "./belongs-to";
+export { BelongsToMany } from "./belongs-to-many";
+
+export type { RelationshipOptions } from "./base";

package/src/database/orm/scopes/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Model Scopes
+ *
+ * Local scopes (scopeXxx methods) and global scopes (auto-applied to all queries)
+ */
+
+export type ScopeDefinition<M> = (query: any) => any;
+
+export class ScopeRegistry<M> {
+	private globalScopes: Map<string, ScopeDefinition<M>> = new Map();
+
+	/**
+	 * Register a global scope
+	 */
+	addGlobalScope(name: string, scope: ScopeDefinition<M>): void {
+		this.globalScopes.set(name, scope);
+	}
+
+	/**
+	 * Remove a global scope by name
+	 */
+	removeGlobalScope(name: string): void {
+		this.globalScopes.delete(name);
+	}
+
+	/**
+	 * Get all global scopes
+	 */
+	getGlobalScopes(): ScopeDefinition<M>[] {
+		return Array.from(this.globalScopes.values());
+	}
+
+	/**
+	 * Clear all global scopes
+	 */
+	clearGlobalScopes(): void {
+		this.globalScopes.clear();
+	}
+
+	/**
+	 * Check if a global scope exists
+	 */
+	hasGlobalScope(name: string): boolean {
+		return this.globalScopes.has(name);
+	}
+}
+
+/**
+ * Soft delete global scope — automatically added when model has softDeletes = true
+ */
+export class SoftDeleteScope {
+	apply(query: any): void {
+		query.whereNull("deleted_at");
+	}
+}