@buenojs/bueno 0.8.3 → 0.8.5

package/src/database/orm/model.ts

@@ -0,0 +1,821 @@
+// @ts-nocheck - Abstract class generic constraints cause false positives in TypeScript.
+// The implementation is logically correct; see .idea/orm-implementation-status.md
+
+/**
+ * Model Base Class
+ *
+ * Active Record pattern implementation inspired by Laravel Eloquent.
+ * Provides model lifecycle, attributes, persistence, and relationships.
+ */
+
+import type { Database } from "../index";
+import { OrmQueryBuilder } from "./builder";
+import { type CastDefinition, CastRegistry } from "./casts";
+import {
+	HookRunner,
+	type ModelHookCallback,
+	type ModelHookName,
+} from "./hooks";
+import { getModelDatabase, registerModelDatabase } from "./model-registry";
+import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relationships";
+import type { ScopeDefinition, ScopeRegistry } from "./scopes";
+
+export class ModelNotFoundError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ModelNotFoundError";
+	}
+}
+
+export class ModelOperationAbortedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ModelOperationAbortedError";
+	}
+}
+
+/**
+ * Base Model class
+ *
+ * Generic over TAttributes (the shape of model attributes)
+ */
+export abstract class Model<
+	TAttributes extends Record<string, unknown> = Record<string, unknown>,
+> {
+	// ============= Static Configuration =============
+
+	static readonly table: string;
+	static readonly primaryKey: string = "id";
+	static readonly timestamps: boolean = true;
+	static readonly createdAtColumn: string = "created_at";
+	static readonly updatedAtColumn: string = "updated_at";
+	static readonly softDeletes: boolean = false;
+	static readonly deletedAtColumn: string = "deleted_at";
+	static readonly fillable: string[] = [];
+	static readonly guarded: string[] = [];
+	static readonly casts: Record<string, CastDefinition> = {};
+
+	private static scopeRegistry = new Map<string, ScopeRegistry<any>>();
+	private static hookRegistry = new Map<
+		string,
+		Map<ModelHookName, ModelHookCallback<any>[]>
+	>();
+
+	// ============= Instance State =============
+
+	protected _attributes: TAttributes = {} as TAttributes;
+	protected _original: TAttributes = {} as TAttributes;
+	protected _relations: Map<string, unknown> = new Map();
+	protected _exists = false;
+	protected _isDirty = false;
+
+	// ============= Constructor / Initialization =============
+
+	constructor(attributes?: Partial<TAttributes>) {
+		if (attributes) {
+			this.fill(attributes);
+		}
+
+		// Return a Proxy to intercept property access
+		return new Proxy(this, {
+			get: (target, prop: string) => {
+				// Internal properties first
+				if (prop.startsWith("_")) {
+					return (target as any)[prop];
+				}
+				// Check if relation is loaded (from eager loading or lazy access)
+				// This must come before checking if it's a function, so eager-loaded
+				// relations take precedence over the relationship methods
+				if ((target as any)._relations.has(prop)) {
+					return (target as any)._relations.get(prop);
+				}
+				// Then check if it's a method
+				if (typeof (target as any)[prop] === "function") {
+					return (target as any)[prop];
+				}
+				// Finally try to get as attribute
+				return target.getAttribute(prop as keyof TAttributes);
+			},
+			set: (target, prop: string, value) => {
+				// Internal properties and methods
+				if (prop.startsWith("_") || prop in Object.getPrototypeOf(target)) {
+					(target as any)[prop] = value;
+					return true;
+				}
+				// Set as attribute
+				target.setAttribute(prop as keyof TAttributes, value as any);
+				return true;
+			},
+			has: (target, prop: string) => {
+				// Check internal properties
+				if (prop.startsWith("_") || prop in Object.getPrototypeOf(target)) {
+					return true;
+				}
+				// Check relations
+				if ((target as any)._relations.has(prop)) {
+					return true;
+				}
+				// Check attributes
+				return (target as any)._attributes.hasOwnProperty(prop);
+			},
+		});
+	}
+
+	// ============= Static Query API =============
+
+	/**
+	 * Create a query builder for this model
+	 */
+	static query<M extends Model>(
+		this: { new (): M } & typeof Model,
+	): ModelQueryBuilder<M> {
+		return new ModelQueryBuilder<M>(this);
+	}
+
+	/**
+	 * Find a model by ID
+	 */
+	static async find<M extends Model>(
+		this: { new (): M } & typeof Model,
+		id: unknown,
+	): Promise<M | null> {
+		return this.query().where("id", id).first();
+	}
+
+	/**
+	 * Find a model by ID or throw
+	 */
+	static async findOrFail<M extends Model>(
+		this: { new (): M } & typeof Model,
+		id: unknown,
+	): Promise<M> {
+		const result = await this.find(id);
+		if (!result) {
+			throw new ModelNotFoundError(`${this.name} with id ${id} not found`);
+		}
+		return result;
+	}
+
+	/**
+	 * Create a where clause
+	 */
+	static where<M extends Model>(
+		this: { new (): M } & typeof Model,
+		column: string,
+		operator: unknown,
+		value?: unknown,
+	): ModelQueryBuilder<M> {
+		return this.query().where(column, operator, value);
+	}
+
+	/**
+	 * Get all records
+	 */
+	static async all<M extends Model>(
+		this: { new (): M } & typeof Model,
+	): Promise<M[]> {
+		return this.query().get();
+	}
+
+	/**
+	 * Create and persist a new model
+	 */
+	static async create<M extends Model>(
+		this: { new (): M } & typeof Model,
+		data: Record<string, unknown>,
+	): Promise<M> {
+		// @ts-expect-error - Abstract class instantiation is valid here; this is the concrete subclass
+		const instance = new this();
+		instance.fill(data);
+		await instance.save();
+		return instance;
+	}
+
+	/**
+	 * First or create — get or create based on conditions
+	 */
+	static async firstOrCreate<M extends Model>(
+		this: { new (): M } & typeof Model,
+		conditions: Partial<TAttributes>,
+		values?: Partial<TAttributes>,
+	): Promise<M> {
+		let instance = await this.query();
+		for (const [key, value] of Object.entries(conditions)) {
+			instance = instance.where(key, value) as any;
+		}
+		const found = await instance.first();
+		if (found) return found;
+
+		const create_data = { ...conditions, ...values };
+		return this.create(create_data as Record<string, unknown>);
+	}
+
+	/**
+	 * Update or create — update or create based on conditions
+	 */
+	static async updateOrCreate<M extends Model>(
+		this: { new (): M } & typeof Model,
+		conditions: Partial<TAttributes>,
+		values: Partial<TAttributes>,
+	): Promise<M> {
+		let query = this.query();
+		for (const [key, value] of Object.entries(conditions)) {
+			query = query.where(key, value) as any;
+		}
+		const found = await query.first();
+
+		if (found) {
+			await found.fill(values).save();
+			return found;
+		}
+
+		return this.create({ ...conditions, ...values } as Record<string, unknown>);
+	}
+
+	// ============= Attribute Access =============
+
+	/**
+	 * Get an attribute value
+	 */
+	getAttribute<K extends keyof TAttributes>(key: K): TAttributes[K] {
+		return this._attributes[key];
+	}
+
+	/**
+	 * Set an attribute value
+	 */
+	setAttribute<K extends keyof TAttributes>(
+		key: K,
+		value: TAttributes[K],
+	): void {
+		this._attributes[key] = value;
+		this._isDirty = true;
+	}
+
+	/**
+	 * Fill attributes from data (respects fillable/guarded)
+	 */
+	fill(data: Partial<TAttributes>): this {
+		const guarded = (this.constructor as typeof Model).guarded;
+		const fillable = (this.constructor as typeof Model).fillable;
+
+		for (const [key, value] of Object.entries(data)) {
+			if (guarded.includes("*")) break;
+			if (guarded.includes(key)) continue;
+			if (fillable.length > 0 && !fillable.includes(key)) continue;
+
+			this.setAttribute(
+				key as keyof TAttributes,
+				value as TAttributes[keyof TAttributes],
+			);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Force fill (bypass fillable/guarded)
+	 */
+	forceFill(data: Partial<TAttributes>): this {
+		for (const [key, value] of Object.entries(data)) {
+			this.setAttribute(
+				key as keyof TAttributes,
+				value as TAttributes[keyof TAttributes],
+			);
+		}
+		return this;
+	}
+
+	/**
+	 * Convert to JSON
+	 */
+	toJSON(): TAttributes {
+		return { ...this._attributes };
+	}
+
+	/**
+	 * Convert to plain object
+	 */
+	toObject(): TAttributes {
+		return { ...this._attributes };
+	}
+
+	// ============= Dirty Tracking =============
+
+	/**
+	 * Check if model or specific attribute is dirty
+	 */
+	isDirty(key?: string): boolean {
+		if (key) {
+			return (
+				this._attributes[key as keyof TAttributes] !==
+				this._original[key as keyof TAttributes]
+			);
+		}
+		return this._isDirty;
+	}
+
+	/**
+	 * Check if model or specific attribute is clean
+	 */
+	isClean(key?: string): boolean {
+		return !this.isDirty(key);
+	}
+
+	/**
+	 * Get dirty attributes
+	 */
+	getDirty(): Partial<TAttributes> {
+		const dirty: Partial<TAttributes> = {};
+		for (const [key, value] of Object.entries(this._attributes)) {
+			if (value !== this._original[key as keyof TAttributes]) {
+				dirty[key as keyof TAttributes] =
+					value as TAttributes[keyof TAttributes];
+			}
+		}
+		return dirty;
+	}
+
+	/**
+	 * Get original attribute values
+	 */
+	getOriginal<K extends keyof TAttributes>(
+		key?: K,
+	): TAttributes[K] | Partial<TAttributes> {
+		if (key) {
+			return this._original[key];
+		}
+		return { ...this._original };
+	}
+
+	// ============= Persistence =============
+
+	/**
+	 * Save the model (create or update)
+	 */
+	async save(): Promise<void> {
+		const modelClass = this.constructor as typeof Model;
+		const db = getModelDatabase(modelClass.name);
+
+		if (this._exists) {
+			// UPDATE
+			if (!this.isDirty()) return;
+
+			const dirty = this.getDirty();
+			if (modelClass.timestamps) {
+				const now = new Date().toISOString();
+				dirty[modelClass.updatedAtColumn as keyof TAttributes] =
+					now as TAttributes[keyof TAttributes];
+				// Also update the in-memory attribute so model.updated_at reflects the new value
+				this._attributes[modelClass.updatedAtColumn as keyof TAttributes] =
+					now as TAttributes[keyof TAttributes];
+			}
+
+			const builder = new OrmQueryBuilder(db, modelClass.table);
+			builder.where(
+				modelClass.primaryKey,
+				this.getAttribute(modelClass.primaryKey as keyof TAttributes),
+			);
+			await builder.update(dirty);
+
+			this._original = { ...this._attributes };
+			this._isDirty = false;
+		} else {
+			// INSERT
+			const data = { ...this._attributes };
+
+			if (modelClass.timestamps) {
+				const now = new Date().toISOString();
+				data[modelClass.createdAtColumn as keyof TAttributes] =
+					now as TAttributes[keyof TAttributes];
+				data[modelClass.updatedAtColumn as keyof TAttributes] =
+					now as TAttributes[keyof TAttributes];
+			}
+
+			const builder = new OrmQueryBuilder<TAttributes>(db, modelClass.table);
+			const result = await builder.insert(data);
+
+			this._attributes = result;
+			this._original = { ...result };
+			this._exists = true;
+			this._isDirty = false;
+		}
+	}
+
+	/**
+	 * Delete the model (soft or hard)
+	 */
+	async delete(): Promise<void> {
+		const modelClass = this.constructor as typeof Model;
+		const db = getModelDatabase(modelClass.name);
+
+		if (modelClass.softDeletes) {
+			// Soft delete: set deleted_at
+			this.setAttribute(
+				modelClass.deletedAtColumn as keyof TAttributes,
+				new Date().toISOString() as TAttributes[keyof TAttributes],
+			);
+			await this.save();
+		} else {
+			// Hard delete
+			const builder = new OrmQueryBuilder(db, modelClass.table);
+			builder.where(
+				modelClass.primaryKey,
+				this.getAttribute(modelClass.primaryKey as keyof TAttributes),
+			);
+			await builder.delete();
+		}
+	}
+
+	/**
+	 * Restore a soft-deleted model
+	 */
+	async restore(): Promise<void> {
+		const modelClass = this.constructor as typeof Model;
+		if (!modelClass.softDeletes) {
+			throw new Error(`Model ${modelClass.name} does not use soft deletes`);
+		}
+
+		this.setAttribute(
+			modelClass.deletedAtColumn as keyof TAttributes,
+			null as TAttributes[keyof TAttributes],
+		);
+		await this.save();
+	}
+
+	/**
+	 * Refresh the model from the database
+	 */
+	async refresh(): Promise<void> {
+		const modelClass = this.constructor as typeof Model;
+		const id = this.getAttribute(modelClass.primaryKey as keyof TAttributes);
+		const fresh = await (modelClass.query() as any).find(id);
+
+		if (fresh) {
+			this._attributes = fresh._attributes;
+			this._original = { ...fresh._attributes };
+		}
+	}
+
+	/**
+	 * Get a fresh instance of this model
+	 */
+	async fresh(): Promise<this> {
+		const modelClass = this.constructor as typeof Model;
+		const id = this.getAttribute(modelClass.primaryKey as keyof TAttributes);
+		return (modelClass.query() as any).find(id);
+	}
+
+	// ============= Relationships =============
+
+	/**
+	 * Define a one-to-one relationship
+	 */
+	hasOne<TRelated extends Model>(
+		relatedClass: { new (): TRelated } & typeof Model,
+		foreignKey: string,
+		localKey?: string,
+	): HasOne<TRelated> {
+		return new HasOne(this as any, relatedClass, foreignKey, localKey ?? "id");
+	}
+
+	/**
+	 * Define a one-to-many relationship
+	 */
+	hasMany<TRelated extends Model>(
+		relatedClass: { new (): TRelated } & typeof Model,
+		foreignKey: string,
+		localKey?: string,
+	): HasMany<TRelated> {
+		return new HasMany(this as any, relatedClass, foreignKey, localKey ?? "id");
+	}
+
+	/**
+	 * Define the inverse of a one-to-one or one-to-many relationship
+	 */
+	belongsTo<TRelated extends Model>(
+		relatedClass: { new (): TRelated } & typeof Model,
+		foreignKey: string,
+		ownerKey?: string,
+	): BelongsTo<TRelated> {
+		return new BelongsTo(
+			this as any,
+			relatedClass,
+			foreignKey,
+			ownerKey ?? "id",
+		);
+	}
+
+	/**
+	 * Define a many-to-many relationship
+	 */
+	belongsToMany<TRelated extends Model>(
+		relatedClass: { new (): TRelated } & typeof Model,
+		pivotTable: string,
+		foreignPivotKey: string,
+		relatedPivotKey: string,
+		parentKey?: string,
+		relatedKey?: string,
+	): BelongsToMany<TRelated> {
+		return new BelongsToMany(
+			this as any,
+			relatedClass,
+			pivotTable,
+			foreignPivotKey,
+			relatedPivotKey,
+			parentKey ?? "id",
+			relatedKey ?? "id",
+		);
+	}
+
+	// ============= Hydration =============
+
+	/**
+	 * Create model instances from database rows
+	 */
+	static hydrate<M extends Model>(
+		this: { new (): M } & typeof Model,
+		rows: Record<string, unknown>[],
+	): M[] {
+		return rows.map((row) => {
+			const instance = new this();
+			instance._attributes = {} as any;
+
+			for (const [key, value] of Object.entries(row)) {
+				const castDef = this.casts[key];
+				instance._attributes[key as keyof any] = castDef
+					? CastRegistry.deserialize(castDef, value)
+					: value;
+			}
+
+			instance._original = { ...instance._attributes };
+			instance._exists = true;
+			return instance;
+		});
+	}
+
+	// ============= Hook Management =============
+
+	/**
+	 * Register a hook callback
+	 */
+	static on<M extends Model>(
+		this: { new (): M } & typeof Model,
+		hookName: ModelHookName,
+		callback: ModelHookCallback<M>,
+	): void {
+		if (!Model.hookRegistry.has(this.name)) {
+			Model.hookRegistry.set(this.name, new Map());
+		}
+		const registry = Model.hookRegistry.get(this.name)!;
+		if (!registry.has(hookName)) {
+			registry.set(hookName, []);
+		}
+		registry.get(hookName)!.push(callback as any);
+	}
+
+	/**
+	 * Get all callbacks for a hook
+	 */
+	static getHookCallbacks<M extends Model>(
+		this: { new (): M } & typeof Model,
+		hookName: ModelHookName,
+	): ModelHookCallback<M>[] {
+		const registry = Model.hookRegistry.get(this.name);
+		return (registry?.get(hookName) ?? []) as any;
+	}
+
+	/**
+	 * Called when model class is first used (for static initialization)
+	 */
+	static booting(): void {
+		// Override in subclass
+	}
+}
+
+/**
+ * ModelQueryBuilder — extended OrmQueryBuilder with Model-specific features
+ */
+export class ModelQueryBuilder<M extends Model> extends OrmQueryBuilder<any> {
+	private modelClass: { new (): M } & typeof Model;
+	private eagerLoads: Map<string, ((q: OrmQueryBuilder<any>) => void) | null> =
+		new Map();
+
+	constructor(modelClass: { new (): M } & typeof Model) {
+		const db = getModelDatabase(modelClass.name);
+		super(db, modelClass.table as string);
+		this.modelClass = modelClass;
+	}
+
+	/**
+	 * Eager load a relationship
+	 */
+	with(relation: string, callback?: (q: OrmQueryBuilder<any>) => void): this {
+		this.eagerLoads.set(relation, callback ?? null);
+		return this;
+	}
+
+	/**
+	 * Override get() to hydrate Model instances
+	 */
+	override async get(): Promise<M[]> {
+		const rows = await super.get();
+		const models = this.modelClass.hydrate(rows);
+
+		// Load eager relationships
+		for (const [relation, callback] of this.eagerLoads) {
+			await this.loadRelation(models, relation, callback);
+		}
+
+		return models;
+	}
+
+	/**
+	 * Override first() to hydrate Model instance
+	 * Note: We must fetch raw data directly to avoid double-hydration
+	 * (since get() is overridden to already hydrate)
+	 */
+	override async first(): Promise<M | null> {
+		// Get raw row from parent OrmQueryBuilder.get() bypassing our override
+		const rows = await OrmQueryBuilder.prototype.get.call(this);
+		if (rows.length === 0) return null;
+
+		const row = rows[0];
+		const models = this.modelClass.hydrate([row]);
+
+		// Load eager relationships
+		for (const [relation, callback] of this.eagerLoads) {
+			await this.loadRelation(models, relation, callback ?? undefined);
+		}
+
+		return models[0] ?? null;
+	}
+
+	/**
+	 * Override paginate() to return hydrated Model instances
+	 * Note: super.paginate() calls get() which already hydrates,
+	 * so we just need to return the result as-is
+	 */
+	override async paginate(page: number, limit: number) {
+		const offset = (page - 1) * limit;
+		const [data, total] = await Promise.all([
+			this.clone().offset(offset).limit(limit).get(),
+			this.clone().count(),
+		]);
+
+		return {
+			data,
+			total,
+			page,
+			limit,
+			totalPages: Math.ceil(total / limit),
+		};
+	}
+
+	/**
+	 * Find first or create — find by conditions or create with values
+	 */
+	async firstOrCreate(
+		conditions: Record<string, unknown>,
+		values?: Record<string, unknown>,
+	): Promise<M> {
+		// Build a fresh query with conditions
+		const query = new ModelQueryBuilder(this.modelClass);
+		for (const [key, value] of Object.entries(conditions)) {
+			query.where(key, value);
+		}
+
+		// Try to find existing
+		const found = await query.first();
+		if (found) return found;
+
+		// Create if not found
+		const createData = { ...conditions, ...values };
+		return this.modelClass.create(createData as Record<string, unknown>);
+	}
+
+	/**
+	 * Update or create — update if exists or create if not
+	 */
+	async updateOrCreate(
+		conditions: Record<string, unknown>,
+		values: Record<string, unknown>,
+	): Promise<M> {
+		// Build a fresh query with conditions
+		const query = new ModelQueryBuilder(this.modelClass);
+		for (const [key, value] of Object.entries(conditions)) {
+			query.where(key, value);
+		}
+
+		// Try to find existing
+		const found = await query.first();
+		if (found) {
+			// Update if found
+			found.fill(values);
+			await found.save();
+			return found;
+		}
+
+		// Create if not found
+		const createData = { ...conditions, ...values };
+		return this.modelClass.create(createData as Record<string, unknown>);
+	}
+
+	/**
+	 * Load eager relationships
+	 * Supports nested dot-notation like "posts.comments"
+	 */
+	private async loadRelation(
+		models: M[],
+		relation: string,
+		callback?: (q: OrmQueryBuilder<any>) => void,
+	): Promise<void> {
+		// Return early if no models
+		if (models.length === 0) return;
+
+		// Handle nested dot-notation relations (e.g., "posts.comments")
+		const dotIndex = relation.indexOf(".");
+		if (dotIndex !== -1) {
+			const head = relation.substring(0, dotIndex);
+			const tail = relation.substring(dotIndex + 1);
+
+			// Load the first relation recursively without a callback
+			await this.loadRelation(models, head, undefined);
+
+			// Collect intermediate models from _relations
+			const intermediates = models.flatMap(
+				(m) => (m as any)._relations.get(head) ?? [],
+			);
+
+			if (intermediates.length === 0) return;
+
+			// Load nested relation on intermediate models
+			const intermediateModelClass = intermediates[0]
+				.constructor as typeof Model;
+			const intermediateBuilder = new ModelQueryBuilder(intermediateModelClass);
+			await intermediateBuilder.loadRelation(intermediates, tail, callback);
+			return;
+		}
+
+		// Get a representative model to call the relationship method
+		const representative = models[0];
+		const relationMethod = (representative as any)[relation];
+
+		if (!relationMethod || typeof relationMethod !== "function") {
+			throw new Error(
+				`Relation "${relation}" not found on ${this.modelClass.name}`,
+			);
+		}
+
+		// Call the relationship method to get a relationship instance
+		const relationship = relationMethod.call(representative);
+
+		// Reset the query from single-model WHERE to clean state
+		(relationship as any).resetQuery();
+
+		// Apply eager constraints to load all parents at once
+		(relationship as any).addEagerConstraints(models);
+
+		// Apply optional callback to constrain the query
+		if (callback) {
+			callback(relationship.query);
+		}
+
+		// Execute the query and get raw rows
+		const rawRows = await relationship.query.get();
+
+		// Hydrate raw rows into model instances
+		const related = (relationship.relatedClass as typeof Model).hydrate(
+			rawRows,
+		);
+
+		// Match relationship results back to parent models
+		relationship.match(models, related, relation);
+	}
+
+	/**
+	 * Support local scopes via Proxy
+	 */
+	static createScoped<M extends Model>(
+		modelClass: { new (): M } & typeof Model,
+	): ModelQueryBuilder<M> {
+		const builder = new ModelQueryBuilder(modelClass);
+
+		return new Proxy(builder, {
+			get: (target, prop: string) => {
+				// Check for scope method
+				if (typeof prop === "string" && prop.startsWith("scope")) {
+					const methodName = `scope${prop.charAt(5).toUpperCase()}${prop.slice(6)}`;
+					if (typeof (modelClass as any)[methodName] === "function") {
+						return (...args: any[]) => {
+							return (modelClass as any)[methodName](target, ...args);
+						};
+					}
+				}
+
+				// Regular property access
+				return (target as any)[prop];
+			},
+		}) as ModelQueryBuilder<M>;
+	}
+}