create-phoenixjs 0.1.4 → 0.1.6

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

@@ -0,0 +1,1802 @@
+import { DB } from '../query/DB';
+import { Builder } from './Builder';
+import type { Binding, InsertValues, UpdateValues } from '../query/types';
+
+// Relationship imports
+import { HasOne } from './HasOne';
+import { BelongsTo } from './BelongsTo';
+import { HasMany } from './HasMany';
+import { BelongsToMany } from './BelongsToMany';
+import { HasOneThrough } from './HasOneThrough';
+import { HasManyThrough } from './HasManyThrough';
+
+// Eager loading import
+import { EagerLoadingBuilder } from './EagerLoadingBuilder';
+
+// Pagination imports
+import { Paginator } from '../pagination/Paginator';
+import { LengthAwarePaginator } from '../pagination/LengthAwarePaginator';
+
+
+/**
+ * ModelNotFoundException - Thrown when a model is not found.
+ */
+export class ModelNotFoundException extends Error {
+	constructor(model: string, id: string | number) {
+		super(`No query results for model [${model}] with ID [${id}]`);
+		this.name = 'ModelNotFoundException';
+	}
+}
+
+/**
+ * Model event types for lifecycle hooks.
+ */
+export type ModelEventType =
+	| 'saving'
+	| 'saved'
+	| 'creating'
+	| 'created'
+	| 'updating'
+	| 'updated'
+	| 'deleting'
+	| 'deleted';
+
+/**
+ * Event callback function type.
+ */
+export type ModelEventCallback<T extends Model = Model> = (model: T) => void | boolean | Promise<void | boolean>;
+
+/**
+ * Base Model class for Active Record pattern.
+ * Provides CRUD operations and query building capabilities.
+ */
+export abstract class Model {
+	/**
+	 * The table associated with the model.
+	 */
+	protected table?: string;
+
+	/**
+	 * The primary key for the model.
+	 */
+	protected primaryKey: string = 'id';
+
+	/**
+	 * The model's attributes.
+	 */
+	protected attributes: Record<string, unknown> = {};
+
+	/**
+	 * The model's original attributes (for dirty checking).
+	 */
+	protected original: Record<string, unknown> = {};
+
+	/**
+	 * The attributes that are mass assignable.
+	 * Child classes should override this with their fillable fields.
+	 *
+	 * @var string[]
+	 */
+	protected fillable: string[] = [];
+
+	/**
+	 * The attributes that aren't mass assignable.
+	 * Default to guarding everything for security.
+	 *
+	 * @var string[]
+	 */
+	protected guarded: string[] = ['*'];
+
+	/**
+	 * Get the fillable fields for this model.
+	 * This method properly handles inheritance by checking instance and prototype.
+	 * Due to JS class initialization order, we need to check the prototype chain
+	 * when called from the parent constructor before child properties are initialized.
+	 */
+	public getFillableFields(): string[] {
+		// First check if 'this' has its own fillable property (already initialized)
+		if (Object.prototype.hasOwnProperty.call(this, 'fillable') &&
+			Array.isArray(this.fillable) && this.fillable.length > 0) {
+			return this.fillable;
+		}
+
+		// Walk up the prototype chain looking for fillable definition
+		let proto = Object.getPrototypeOf(this);
+		while (proto && proto.constructor.name !== 'Model' && proto.constructor.name !== 'Object') {
+			const descriptor = Object.getOwnPropertyDescriptor(proto, 'fillable');
+			if (descriptor && descriptor.value && Array.isArray(descriptor.value)) {
+				return descriptor.value;
+			}
+			proto = Object.getPrototypeOf(proto);
+		}
+
+		// Default to the instance property
+		return this.fillable;
+	}
+
+	/**
+	 * Get the guarded fields for this model.
+	 * This method properly handles inheritance by checking instance and prototype.
+	 * Due to JS class initialization order, we need to check the prototype chain
+	 * when called from the parent constructor before child properties are initialized.
+	 */
+	public getGuardedFields(): string[] {
+		// First check if 'this' has its own guarded property (already initialized)
+		// We need to detect if the child class set a different value
+		if (Object.prototype.hasOwnProperty.call(this, 'guarded')) {
+			return this.guarded;
+		}
+
+		// Walk up the prototype chain looking for guarded definition
+		let proto = Object.getPrototypeOf(this);
+		while (proto && proto.constructor.name !== 'Model' && proto.constructor.name !== 'Object') {
+			const descriptor = Object.getOwnPropertyDescriptor(proto, 'guarded');
+			if (descriptor && descriptor.value && Array.isArray(descriptor.value)) {
+				return descriptor.value;
+			}
+			proto = Object.getPrototypeOf(proto);
+		}
+
+		// Default to the instance property (will be ['*'] from Model base)
+		return this.guarded;
+	}
+
+	/**
+	 * Indicates if the model is totally guarded.
+	 *
+	 * @var boolean
+	 */
+	protected static totallyGuarded: boolean = false;
+
+	/**
+	 * Indicates if the model exists in the database.
+	 */
+	public exists: boolean = false;
+
+	/**
+	 * Indicates if the model should be timestamped.
+	 */
+	protected timestamps: boolean = true;
+
+	/**
+	 * The name of the "created at" column.
+	 */
+	protected static CREATED_AT: string = 'created_at';
+
+	/**
+	 * The name of the "updated at" column.
+	 */
+	protected static UPDATED_AT: string = 'updated_at';
+
+	/**
+	 * The event listeners for the model.
+	 * Stored per model class to avoid cross-contamination.
+	 */
+	protected static eventListeners: Map<string, Map<ModelEventType, ModelEventCallback[]>> = new Map();
+
+	/**
+	 * The loaded relationships for this model.
+	 * Used for eager loading to store pre-loaded relationships.
+	 */
+	protected relations: Map<string, Model | Model[] | null> = new Map();
+
+	/**
+	 * Global scopes for the model.
+	 */
+	protected static globalScopes: Map<string, any> = new Map();
+
+	/**
+	 * Booted models.
+	 */
+	protected static booted: Map<string, boolean> = new Map();
+
+	/**
+	 * The attributes that should be cast to native types.
+	 */
+	protected casts: Record<string, string> = {};
+
+	/**
+	 * The attributes that should be hidden for arrays.
+	 */
+	protected hidden: string[] = [];
+
+	/**
+	 * The attributes that should be visible in arrays.
+	 */
+	protected visible: string[] = [];
+
+	/**
+	 * The set of traits callbacks.
+	 */
+	protected static traitInitializers: Map<string, any[]> = new Map();
+
+	/**
+	 * Boot the model.
+	 */
+	public static boot(): void {
+		if (this.booted.has(this.name)) {
+			return;
+		}
+
+		this.booted.set(this.name, true);
+
+		// Boot traits
+		this.bootTraits();
+	}
+
+	/**
+	 * Boot all of the bootable traits on the model.
+	 */
+	protected static bootTraits(): void {
+		const booted = new Set<string>();
+		let current = this;
+
+		while (current && current.name !== 'Model') {
+			const keys = Object.getOwnPropertyNames(current);
+			for (const key of keys) {
+				if (key.startsWith('boot') && key !== 'boot' && key !== 'bootTraits') {
+					if (!booted.has(key) && typeof (this as any)[key] === 'function') {
+						(this as any)[key]();
+						booted.add(key);
+					}
+				}
+			}
+			current = Object.getPrototypeOf(current);
+		}
+	}
+
+	/**
+	 * Register a new global scope on the model.
+	 */
+	public static addGlobalScope(scope: any, implementation?: any): void {
+		if (typeof scope === 'string' && implementation) {
+			this.globalScopes.set(scope, implementation);
+		} else if (scope.constructor) {
+			this.globalScopes.set(scope.constructor.name, scope);
+		}
+	}
+
+
+	/**
+	 * Create a new model instance.
+	 * 
+	 * Note: We use forceFill in the constructor because constructor arguments
+	 * are trusted (not external user input). Mass assignment protection is
+	 * meant for external input like HTTP request bodies, not constructor init.
+	 */
+	constructor(attributes: Record<string, unknown> = {}) {
+		this.forceFill(attributes);
+
+		// Return a proxy to handle attribute access directly on the model instance
+		return new Proxy(this, {
+			get: (target, prop: string | symbol, receiver) => {
+				// Return class properties/methods first
+				if (prop in target) {
+					return Reflect.get(target, prop, receiver);
+				}
+
+				// Then try attributes
+				if (typeof prop === 'string') {
+					// console.log(`Proxy get attribute: ${prop}`);
+					return target.getAttribute(prop);
+				}
+
+				return undefined;
+			},
+			set: (target, prop: string | symbol, value, receiver) => {
+				// If property exists on class, set it
+				if (prop in target) {
+					return Reflect.set(target, prop, value, receiver);
+				}
+
+				// Otherwise set attribute
+				if (typeof prop === 'string') {
+					if (prop === 'table' || prop === 'primaryKey' || prop === 'forceDeleting') {
+						Object.defineProperty(target, prop, { value, writable: true, configurable: true, enumerable: true });
+						return true;
+					}
+					target.setAttribute(prop, value);
+					return true;
+				}
+
+				return false;
+			}
+		});
+	}
+
+	// ==========================================
+	// Attribute Handling
+	// ==========================================
+
+	/**
+	 * Fill the model with an array of attributes.
+	 *
+	 * @throws Error if mass assignment protection is violated (optional, traditionally just ignored)
+	 */
+	public fill(attributes: Record<string, unknown>): this {
+		for (const key in attributes) {
+			if (this.isFillable(key)) {
+				this.setAttribute(key, attributes[key]);
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Force fill the model with an array of attributes.
+	 * This bypasses mass assignment protection.
+	 */
+	public forceFill(attributes: Record<string, unknown>): this {
+		for (const key in attributes) {
+			this.setAttribute(key, attributes[key]);
+		}
+		return this;
+	}
+
+	/**
+	 * Determine if the given attribute may be mass assigned.
+	 */
+	public isFillable(key: string): boolean {
+		const fillableFields = this.getFillableFields();
+		const guardedFields = this.getGuardedFields();
+
+		// If the key is in the fillable array, it can be filled
+		if (fillableFields.includes(key)) {
+			return true;
+		}
+
+		// If the model is totally guarded (guarded = ['*']), return false
+		if (guardedFields.length === 1 && guardedFields[0] === '*') {
+			return false;
+		}
+
+		// If the key is not in the guarded array, it can be filled
+		if (!guardedFields.includes(key) && !guardedFields.includes('*')) {
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Get an attribute from the model.
+	 */
+	public getAttribute(key: string): unknown {
+		if (!key) {
+			return;
+		}
+
+		// If the attribute has an accessor, we will call that to get the value
+		if (this.hasGetMutator(key)) {
+			return this.mutateAttribute(key, this.attributes[key]);
+		}
+
+		// If the attribute exists in the attributes array or has a "get" mutator
+		if (key in this.attributes) {
+			return this.getAttributeValue(key);
+		}
+
+		// If the attribute is a relation
+		if (this.relations.has(key)) {
+			return this.relations.get(key);
+		}
+
+		// Check if it's a method on the model (e.g., relationship method)
+		if (key in this && typeof (this as any)[key] === 'function') {
+			return (this as any)[key];
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Get a plain attribute (not a relationship).
+	 */
+	public getAttributeValue(key: string): unknown {
+		const value = this.attributes[key];
+
+		if (this.hasCast(key)) {
+			return this.castAttribute(key, value);
+		}
+
+		return value;
+	}
+
+	/**
+	 * Set a given attribute on the model.
+	 */
+	public setAttribute(key: string, value: unknown): this {
+		// First check for a mutator
+		if (this.hasSetMutator(key)) {
+			this.setMutatedAttributeValue(key, value);
+			return this;
+		}
+
+		// If the attribute is JSON, we might want to cast it before setting,
+		// but usually we cast on read. However, if it's explicitly 'json',
+		// we might want to ensure it's stored correctly if the driver doesn't handle object->json automatically.
+		// For postgres.js, objects are usually handled, but let's be safe.
+		// Actually, standard Eloquent casts on read mostly, but for setting 'json', it ensures it's an object if passed as string?
+		// or vice versa?
+		// In strict casting, we might want to serialize objects to string if the DB column expects string.
+		// But postgres.js handles JSONB columns with objects directly.
+		// So we will stick to simple assignment unless specific logic is needed.
+
+		this.attributes[key] = value;
+		return this;
+	}
+
+	/**
+	 * Get all attributes.
+	 */
+	public getAttributes(): Record<string, unknown> {
+		return { ...this.attributes };
+	}
+
+	/**
+	 * Get the original attributes.
+	 */
+	public getOriginal(): Record<string, unknown> {
+		return { ...this.original };
+	}
+
+	/**
+	 * Sync the original attributes with the current attributes.
+	 */
+	public syncOriginal(): this {
+		this.original = { ...this.attributes };
+		return this;
+	}
+
+	/**
+	 * Get the attributes that have been changed.
+	 */
+	public getDirty(): Record<string, unknown> {
+		const dirty: Record<string, unknown> = {};
+		for (const key in this.attributes) {
+			if (this.attributes[key] !== this.original[key]) {
+				dirty[key] = this.attributes[key];
+			}
+		}
+		return dirty;
+	}
+
+	/**
+	 * Check if the model or a given attribute has been modified.
+	 */
+	public isDirty(attribute?: string): boolean {
+		if (attribute) {
+			return this.attributes[attribute] !== this.original[attribute];
+		}
+		return Object.keys(this.getDirty()).length > 0;
+	}
+
+	// ==========================================
+	// Eager Loading / Relation Storage
+	// ==========================================
+
+	/**
+	 * Set a loaded relationship on the model.
+	 * Used internally by eager loading to store pre-loaded relationships.
+	 *
+	 * @param relation - The name of the relationship
+	 * @param value - The loaded model(s) or null
+	 */
+	public setRelation(relation: string, value: Model | Model[] | null): this {
+		this.relations.set(relation, value);
+		return this;
+	}
+
+	/**
+	 * Get a loaded relationship from the model.
+	 * Returns undefined if the relationship hasn't been loaded.
+	 *
+	 * @param relation - The name of the relationship
+	 * @returns The loaded relationship value or undefined
+	 */
+	public getRelation(relation: string): Model | Model[] | null | undefined {
+		return this.relations.get(relation);
+	}
+
+	/**
+	 * Check if a relationship has been loaded.
+	 *
+	 * @param relation - The name of the relationship
+	 * @returns True if the relationship has been loaded
+	 */
+	public relationLoaded(relation: string): boolean {
+		return this.relations.has(relation);
+	}
+
+	/**
+	 * Get all loaded relationships.
+	 *
+	 * @returns Map of all loaded relationships
+	 */
+	public getRelations(): Map<string, Model | Model[] | null> {
+		return new Map(this.relations);
+	}
+
+	/**
+	 * Set multiple relationships at once.
+	 *
+	 * @param relations - Map of relationship names to values
+	 */
+	public setRelations(relations: Map<string, Model | Model[] | null>): this {
+		for (const [name, value] of relations) {
+			this.relations.set(name, value);
+		}
+		return this;
+	}
+
+	// ==========================================
+	// Table & Key Information
+	// ==========================================
+
+
+	/**
+	 * Get the table associated with the model.
+	 */
+	public getTable(): string {
+		if (!this.table) {
+			this.table = this.inferTableName();
+		}
+		return this.table;
+	}
+
+	/**
+	 * Get the primary key for the model.
+	 */
+	public getKeyName(): string {
+		return this.primaryKey;
+	}
+
+	/**
+	 * Get the value of the model's primary key.
+	 */
+	public getKey(): unknown {
+		return this.getAttribute(this.getKeyName());
+	}
+
+	/**
+	 * Get the default foreign key name for the model.
+	 */
+	public getForeignKey(): string {
+		return this.constructor.name.toLowerCase() + '_id';
+	}
+
+	/**
+	 * Convert the model instance to JSON.
+	 */
+	public toJSON(): Record<string, unknown> {
+		return this.toArray();
+	}
+
+	/**
+	 * Convert the model instance to an array.
+	 */
+	public toArray(): Record<string, unknown> {
+		return {
+			...this.attributesToArray(),
+			...this.relationsToArray(),
+		};
+	}
+
+	/**
+	 * Convert the model's attributes to an array.
+	 */
+	public attributesToArray(): Record<string, unknown> {
+		const attributes: Record<string, unknown> = {};
+
+		// Get all attributes, processing accessors
+		const keys = Object.keys(this.attributes);
+
+		// Also look for accessors that don't have matching attributes
+		const prototype = Object.getPrototypeOf(this);
+		const methodNames = Object.getOwnPropertyNames(prototype);
+		for (const name of methodNames) {
+			if (name.startsWith('get') && name.endsWith('Attribute') && name !== 'getAttribute') {
+				const key = this.snakeCase(name.slice(3, -9));
+				if (!keys.includes(key)) {
+					keys.push(key);
+				}
+			}
+		}
+
+		for (const key of keys) {
+			if (!this.isVisible(key)) {
+				continue;
+			}
+			attributes[key] = this.getAttribute(key);
+		}
+
+		return attributes;
+	}
+
+	/**
+	 * Get the model's relationships in array form.
+	 */
+	public relationsToArray(): Record<string, unknown> {
+		const attributes: Record<string, unknown> = {};
+
+		for (const [key, value] of this.relations) {
+			if (!this.isVisible(key)) {
+				continue;
+			}
+
+			if (value instanceof Model) {
+				attributes[key] = value.toArray();
+			} else if (Array.isArray(value)) {
+				attributes[key] = value.map((model) => model instanceof Model ? model.toArray() : model);
+			} else {
+				attributes[key] = value;
+			}
+		}
+
+		return attributes;
+	}
+
+	/**
+	 * Determine if an attribute should be visible.
+	 */
+	protected isVisible(key: string): boolean {
+		if (this.visible.length > 0) {
+			return this.visible.includes(key);
+		}
+
+		if (this.hidden.length > 0) {
+			return !this.hidden.includes(key);
+		}
+
+		return true;
+	}
+
+	/**
+	 * Infer the table name from the class name.
+	 */
+	protected inferTableName(): string {
+		return this.snakeCase(this.constructor.name) + 's';
+	}
+
+	/**
+	 * Convert a string to snake case.
+	 */
+	protected snakeCase(str: string): string {
+		return str.replace(/[A-Z]/g, (letter, index) => {
+			return index === 0 ? letter.toLowerCase() : '_' + letter.toLowerCase();
+		});
+	}
+
+	// ==========================================
+	// Casting & Mutators
+	// ==========================================
+
+	/**
+	 * Determine if an attribute has a cast.
+	 */
+	public hasCast(key: string): boolean {
+		return key in this.casts;
+	}
+
+	/**
+	 * Cast an attribute to a native PHP type.
+	 */
+	protected castAttribute(key: string, value: unknown): unknown {
+		if (value === null || value === undefined) {
+			return value;
+		}
+
+		const type = this.casts[key].trim().toLowerCase();
+
+		switch (type) {
+			case 'int':
+			case 'integer':
+				return typeof value === 'string' ? parseInt(value, 10) : Math.floor(value as number);
+			case 'real':
+			case 'float':
+			case 'double':
+				return typeof value === 'string' ? parseFloat(value) : value;
+			case 'string':
+				return String(value);
+			case 'bool':
+			case 'boolean':
+				return Boolean(value);
+			case 'object':
+			case 'json':
+				if (typeof value === 'string') {
+					try {
+						return JSON.parse(value);
+					} catch (e) {
+						return value;
+					}
+				}
+				return value;
+			case 'date':
+			case 'datetime':
+				if (value instanceof Date) {
+					return value;
+				}
+				return new Date(value as string | number);
+			default:
+				return value;
+		}
+	}
+
+	/**
+	 * Determine if a get mutator exists for an attribute.
+	 */
+	public hasGetMutator(key: string): boolean {
+		return typeof (this as any)[this.getMutatorMethodName(key)] === 'function';
+	}
+
+	/**
+	 * Determine if a set mutator exists for an attribute.
+	 */
+	public hasSetMutator(key: string): boolean {
+		return typeof (this as any)[this.setMutatorMethodName(key)] === 'function';
+	}
+
+	/**
+	 * Get the value of an attribute using its mutator.
+	 */
+	protected mutateAttribute(key: string, value: unknown): unknown {
+		return (this as any)[this.getMutatorMethodName(key)](value);
+	}
+
+	/**
+	 * Set the value of an attribute using its mutator.
+	 */
+	protected setMutatedAttributeValue(key: string, value: unknown): void {
+		(this as any)[this.setMutatorMethodName(key)](value);
+	}
+
+	/**
+	 * Get the mutator method name for a "get" mutator.
+	 */
+	protected getMutatorMethodName(key: string): string {
+		const pascalKey = key
+			.split('_')
+			.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+			.join('');
+		return `get${pascalKey}Attribute`;
+	}
+
+	/**
+	 * Get the mutator method name for a "set" mutator.
+	 */
+	protected setMutatorMethodName(key: string): string {
+		const pascalKey = key
+			.split('_')
+			.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+			.join('');
+		return `set${pascalKey}Attribute`;
+	}
+
+	// ==========================================
+	// Timestamps
+	// ==========================================
+
+	/**
+	 * Get a fresh timestamp for the model.
+	 */
+	public freshTimestamp(): Date {
+		return new Date();
+	}
+
+	/**
+	 * Get a fresh timestamp string for the model.
+	 */
+	public freshTimestampString(): string {
+		return this.freshTimestamp().toISOString();
+	}
+
+	/**
+	 * Get the name of the "created at" column.
+	 */
+	public getCreatedAtColumn(): string {
+		return (this.constructor as typeof Model).CREATED_AT;
+	}
+
+	/**
+	 * Get the name of the "updated at" column.
+	 */
+	public getUpdatedAtColumn(): string {
+		return (this.constructor as typeof Model).UPDATED_AT;
+	}
+
+	/**
+	 * Determine if the model uses timestamps.
+	 */
+	public usesTimestamps(): boolean {
+		return this.timestamps;
+	}
+
+	/**
+	 * Set the timestamps for a create operation.
+	 */
+	protected setCreatedAt(): this {
+		if (!this.usesTimestamps()) {
+			return this;
+		}
+
+		const timestamp = this.freshTimestamp();
+		this.setAttribute(this.getCreatedAtColumn(), timestamp);
+		return this;
+	}
+
+	/**
+	 * Set the timestamps for an update operation.
+	 */
+	protected setUpdatedAt(): this {
+		if (!this.usesTimestamps()) {
+			return this;
+		}
+
+		const timestamp = this.freshTimestamp();
+		this.setAttribute(this.getUpdatedAtColumn(), timestamp);
+		return this;
+	}
+
+	// ==========================================
+	// Model Events
+	// ==========================================
+
+	/**
+	 * Get the event listeners for the model class.
+	 */
+	protected static getModelListeners(modelName: string): Map<ModelEventType, ModelEventCallback[]> {
+		if (!this.eventListeners.has(modelName)) {
+			this.eventListeners.set(modelName, new Map());
+		}
+		return this.eventListeners.get(modelName)!;
+	}
+
+	/**
+	 * Register a model event callback.
+	 */
+	protected static registerModelEvent(event: ModelEventType, callback: ModelEventCallback): void {
+		const listeners = this.getModelListeners(this.name);
+		if (!listeners.has(event)) {
+			listeners.set(event, []);
+		}
+		listeners.get(event)!.push(callback);
+	}
+
+	/**
+	 * Fire the given model event.
+	 * Returns false if any listener returned false to halt the action.
+	 */
+	protected async fireModelEvent(event: ModelEventType): Promise<boolean> {
+		const modelName = this.constructor.name;
+		const listeners = (this.constructor as typeof Model).getModelListeners(modelName);
+		const eventListeners = listeners.get(event) || [];
+
+		for (const callback of eventListeners) {
+			const result = await callback(this);
+			// If callback returns false, halt the action
+			if (result === false) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	/**
+	 * Register a saving event listener.
+	 */
+	static saving<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('saving', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register a saved event listener.
+	 */
+	static saved<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('saved', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register a creating event listener.
+	 */
+	static creating<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('creating', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register a created event listener.
+	 */
+	static created<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('created', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register an updating event listener.
+	 */
+	static updating<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('updating', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register an updated event listener.
+	 */
+	static updated<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('updated', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register a deleting event listener.
+	 */
+	static deleting<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('deleting', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Register a deleted event listener.
+	 */
+	static deleted<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		callback: ModelEventCallback<T>
+	): void {
+		(this as unknown as typeof Model).registerModelEvent('deleted', callback as ModelEventCallback);
+	}
+
+	/**
+	 * Clear all event listeners for this model class.
+	 */
+	static clearEventListeners<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T
+	): void {
+		const modelClass = this as unknown as typeof Model;
+		modelClass.eventListeners.delete(modelClass.name);
+	}
+
+	// ==========================================
+	// CRUD Operations (Instance Methods)
+	// ==========================================
+
+	/**
+	 * Save the model to the database.
+	 * If the model exists, it updates; otherwise, it inserts.
+	 */
+	public async save(): Promise<boolean> {
+		// Fire 'saving' event
+		if (!(await this.fireModelEvent('saving'))) {
+			return false;
+		}
+
+		let result: boolean;
+
+		if (this.exists) {
+			result = await this.performUpdate();
+		} else {
+			result = await this.performInsert();
+		}
+
+		if (result) {
+			// Fire 'saved' event
+			await this.fireModelEvent('saved');
+		}
+
+		return result;
+	}
+
+	/**
+	 * Perform an INSERT operation for a new model.
+	 */
+	protected async performInsert(): Promise<boolean> {
+		// Fire 'creating' event
+		if (!(await this.fireModelEvent('creating'))) {
+			return false;
+		}
+
+		// Set timestamps
+		this.setCreatedAt();
+		this.setUpdatedAt();
+
+		const query = this.newQuery();
+
+		// Insert and get the ID back
+		const result = await query.insertReturning<Record<string, unknown>>(
+			this.attributes as InsertValues,
+			['*'] // Return all columns
+		);
+
+		if (result) {
+			// Update model with returned values (including generated ID)
+			this.fill(result);
+			this.exists = true;
+			this.syncOriginal();
+
+			// Fire 'created' event
+			await this.fireModelEvent('created');
+
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Perform an UPDATE operation for an existing model.
+	 */
+	protected async performUpdate(): Promise<boolean> {
+		// Fire 'updating' event
+		if (!(await this.fireModelEvent('updating'))) {
+			return false;
+		}
+
+		// Set updated_at timestamp
+		this.setUpdatedAt();
+
+		const dirty = this.getDirty();
+
+		// Nothing to update (even after setting updated_at)
+		if (Object.keys(dirty).length === 0) {
+			return true;
+		}
+
+		const query = this.newQuery();
+		const affected = await query
+			.where(this.getKeyName(), '=', this.getKey() as Binding)
+			.update(dirty as UpdateValues);
+
+		if (affected > 0) {
+			this.syncOriginal();
+
+			// Fire 'updated' event
+			await this.fireModelEvent('updated');
+
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Update the model in the database.
+	 */
+	public async update(attributes: Record<string, unknown>): Promise<boolean> {
+		if (!this.exists) {
+			return false;
+		}
+
+		this.fill(attributes);
+		return this.save();
+	}
+
+	/**
+	 * Delete the model from the database.
+	 */
+	public async delete(): Promise<boolean> {
+		if (!this.exists) {
+			return false;
+		}
+
+		// Fire 'deleting' event
+		if (!(await this.fireModelEvent('deleting'))) {
+			return false;
+		}
+
+		const query = this.newQuery();
+		const affected = await query
+			.where(this.getKeyName(), '=', this.getKey() as Binding)
+			.delete();
+
+		if (affected > 0) {
+			this.exists = false;
+
+			// Fire 'deleted' event
+			await this.fireModelEvent('deleted');
+
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Refresh the model from the database.
+	 */
+	public async refresh(): Promise<this | null> {
+		if (!this.exists) {
+			return null;
+		}
+
+		const fresh = await this.newQuery()
+			.where(this.getKeyName(), '=', this.getKey() as Binding)
+			.first();
+
+		if (fresh) {
+			this.fill(fresh.getAttributes());
+			this.syncOriginal();
+			return this;
+		}
+
+		return null;
+	}
+
+	// ==========================================
+	// Query Builder Integration
+	// ==========================================
+
+
+
+	/**
+	 * Get a new query builder for the model's table.
+	 */
+	public newQuery(): Builder<this> {
+		const query = DB.table(this.getTable());
+		const builder = new Builder<this>(query);
+
+		builder.setModel(this);
+
+		// Apply global scopes
+		const scopes = (this.constructor as typeof Model).globalScopes;
+		if (scopes.size > 0) {
+			for (const [name, scope] of scopes.entries()) {
+				builder.withGlobalScope(name, scope);
+			}
+		}
+
+		return builder;
+	}
+
+	/**
+	 * Create a new instance of the model with the given attributes.
+	 */
+	public newInstance(
+		attributes: Record<string, unknown> = {},
+		exists: boolean = false
+	): this {
+		const ModelClass = this.constructor as new (attrs?: Record<string, unknown>) => this;
+
+		// If hydrating (exists=true), bypass constructor assignment to avoid mass assignment protection
+		// and use forceFill() instead.
+		const instance = new ModelClass(exists ? {} : attributes);
+
+		if (exists) {
+			instance.forceFill(attributes);
+			instance.exists = true;
+			instance.syncOriginal();
+		}
+
+		return instance;
+	}
+
+	/**
+	 * Convert a database row to a model instance.
+	 */
+	protected hydrateModel(row: Record<string, unknown>): this {
+		return this.newInstance(row, true);
+	}
+
+	/**
+	 * Convert multiple database rows to model instances.
+	 */
+	protected hydrateModels(rows: Record<string, unknown>[]): this[] {
+		return rows.map((row) => this.hydrateModel(row));
+	}
+
+	// ==========================================
+	// Static CRUD Methods
+	// ==========================================
+
+	/**
+	 * Create a new model and persist it to the database.
+	 */
+	static async create<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		attributes: Record<string, unknown>
+	): Promise<T> {
+		const instance = new this(attributes);
+		// Ensure boot is called
+		(this as unknown as typeof Model).boot();
+
+		await instance.save();
+		return instance;
+	}
+
+	/**
+	 * Insert multiple records into the database.
+	 */
+	static async insert<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		records: InsertValues[]
+	): Promise<boolean> {
+		const instance = new this();
+		return instance.newQuery().insert(records);
+	}
+
+	/**
+	 * Find a model by its primary key.
+	 */
+	static async find<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		id: number | string
+	): Promise<T | null> {
+		const instance = new this();
+		return instance.newQuery()
+			.where(instance.getKeyName(), '=', id)
+			.first();
+	}
+
+	/**
+	 * Find a model by its primary key or throw an exception.
+	 */
+	static async findOrFail<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		id: number | string
+	): Promise<T> {
+		const result = await (this as unknown as typeof Model).find.call(this, id);
+
+		if (!result) {
+			throw new ModelNotFoundException(this.name, id);
+		}
+
+		return result as T;
+	}
+
+	/**
+	 * Get all models from the database.
+	 */
+	static async all<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T
+	): Promise<T[]> {
+		const instance = new this();
+		return instance.newQuery().get();
+	}
+
+	/**
+	 * Get the first model from the database.
+	 */
+	static async first<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T
+	): Promise<T | null> {
+		const instance = new this();
+		return instance.newQuery().first();
+	}
+
+	/**
+	 * Destroy model(s) by primary key.
+	 */
+	static async destroy<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		ids: number | string | (number | string)[]
+	): Promise<number> {
+		const instance = new this();
+		const idArray = Array.isArray(ids) ? ids : [ids];
+
+		if (idArray.length === 0) {
+			return 0;
+		}
+
+		return instance.newQuery()
+			.whereIn(instance.getKeyName(), idArray)
+			.delete();
+	}
+
+	/**
+	 * Get a fresh query builder for the model.
+	 */
+	static query<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T
+	): Builder {
+		const instance = new this();
+		return instance.newQuery();
+	}
+
+	/**
+	 * Add a WHERE clause and return the query builder.
+	 */
+	static where<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		column: string,
+		operatorOrValue?: string | number | boolean | null,
+		value?: string | number | boolean | null
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().where(column, operatorOrValue, value);
+	}
+
+	/**
+	 * Add a WHERE IN clause and return the query builder.
+	 */
+	static whereIn<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		column: string,
+		values: (string | number | boolean | null)[]
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().whereIn(column, values);
+	}
+
+	/**
+	 * Add a WHERE NULL clause and return the query builder.
+	 */
+	static whereNull<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		column: string
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().whereNull(column);
+	}
+
+	/**
+	 * Add a WHERE NOT NULL clause and return the query builder.
+	 */
+	static whereNotNull<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		column: string
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().whereNotNull(column);
+	}
+
+	/**
+	 * Add an ORDER BY clause and return the query builder.
+	 */
+	static orderBy<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		column: string,
+		direction: 'asc' | 'desc' = 'asc'
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().orderBy(column, direction);
+	}
+
+	/**
+	 * Add a LIMIT clause and return the query builder.
+	 */
+	static limit<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		value: number
+	): Builder {
+		const instance = new this();
+		return instance.newQuery().limit(value);
+	}
+
+	// ==========================================
+	// Eager Loading
+	// ==========================================
+
+	/**
+	 * Begin a query with eager loading for the specified relationships.
+	 *
+	 * This solves the N+1 query problem by loading all related models in bulk
+	 * rather than executing a separate query for each parent model.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * // Load users with their posts
+	 * const users = await User.with('posts').get();
+	 *
+	 * // Load users with multiple relationships
+	 * const users = await User.with('posts', 'profile').get();
+	 *
+	 * // Load users with nested relationships (posts and their comments)
+	 * const users = await User.with('posts.comments').get();
+	 *
+	 * // Chain with query constraints
+	 * const users = await User.with('posts')
+	 *     .where('active', true)
+	 *     .orderBy('created_at', 'desc')
+	 *     .limit(10)
+	 *     .get();
+	 *
+	 * // Access eagerly loaded relations
+	 * for (const user of users) {
+	 *     const posts = user.getRelation('posts'); // Already loaded, no query
+	 *     console.log(posts);
+	 * }
+	 * ```
+	 *
+	 * @param relations - The relationship names to eager load (can be nested with dots)
+	 * @returns An EagerLoadingBuilder for chaining
+	 */
+	static with<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		...relations: string[]
+	): EagerLoadingBuilder<T> {
+		const instance = new this();
+		const builder = instance.newQuery();
+		return new EagerLoadingBuilder<T>(this, builder, relations);
+	}
+
+	// ==========================================
+	// Relationship Methods
+	// ==========================================
+
+
+	/**
+	 * Define a one-to-one relationship.
+	 *
+	 * The foreign key is on the RELATED model's table, referencing this model.
+	 *
+	 * Example: User has one Profile (profiles.user_id references users.id)
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class User extends Model {
+	 *     profile() {
+	 *         return this.hasOne(Profile, 'user_id', 'id');
+	 *     }
+	 * }
+	 *
+	 * const user = await User.find(1);
+	 * const profile = await user.profile().get();
+	 * ```
+	 *
+	 * @param RelatedClass - The related model class constructor
+	 * @param foreignKey - The foreign key column on the related model (defaults to {thisModel}_id)
+	 * @param localKey - The local key column on this model (defaults to 'id')
+	 * @returns A HasOne relationship instance
+	 */
+	protected hasOne<TRelated extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		foreignKey?: string,
+		localKey?: string
+	): HasOne<TRelated> {
+		const relatedInstance = new RelatedClass();
+
+		// Default foreign key: user_id (for User model)
+		const fk = foreignKey || this.getForeignKey();
+
+		// Default local key: id
+		const lk = localKey || this.getKeyName();
+
+		return new HasOne<TRelated>(this, relatedInstance, fk, lk);
+	}
+
+	/**
+	 * Define a belongs-to relationship (inverse of hasOne or hasMany).
+	 *
+	 * The foreign key is on THIS model's table, referencing the parent.
+	 *
+	 * Example: Profile belongs to User (profiles.user_id references users.id)
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class Profile extends Model {
+	 *     user() {
+	 *         return this.belongsTo(User, 'user_id', 'id');
+	 *     }
+	 * }
+	 *
+	 * const profile = await Profile.find(1);
+	 * const user = await profile.user().get();
+	 * ```
+	 *
+	 * @param RelatedClass - The parent model class constructor
+	 * @param foreignKey - The foreign key column on this model (defaults to {parent}_id)
+	 * @param ownerKey - The owner key column on the parent model (defaults to 'id')
+	 * @returns A BelongsTo relationship instance
+	 */
+	protected belongsTo<TRelated extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		foreignKey?: string,
+		ownerKey?: string
+	): BelongsTo<TRelated> {
+		const relatedInstance = new RelatedClass();
+
+		// Default foreign key: user_id (for User parent model)
+		const fk = foreignKey || relatedInstance.getForeignKey();
+
+		// Default owner key: id
+		const ok = ownerKey || relatedInstance.getKeyName();
+
+		return new BelongsTo<TRelated>(this, relatedInstance, fk, ok);
+	}
+
+	/**
+	 * Define a one-to-many relationship.
+	 *
+	 * The foreign key is on the RELATED model's table, referencing this model.
+	 *
+	 * Example: User has many Posts (posts.user_id references users.id)
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class User extends Model {
+	 *     posts() {
+	 *         return this.hasMany(Post, 'user_id', 'id');
+	 *     }
+	 * }
+	 *
+	 * const user = await User.find(1);
+	 * const posts = await user.posts().get();           // Get all posts
+	 * const recentPosts = await user.posts()
+	 *     .where('published', true)
+	 *     .orderBy('created_at', 'desc')
+	 *     .limit(5)
+	 *     .get();
+	 * ```
+	 *
+	 * @param RelatedClass - The related model class constructor
+	 * @param foreignKey - The foreign key column on the related model (defaults to {thisModel}_id)
+	 * @param localKey - The local key column on this model (defaults to 'id')
+	 * @returns A HasMany relationship instance
+	 */
+	protected hasMany<TRelated extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		foreignKey?: string,
+		localKey?: string
+	): HasMany<TRelated> {
+		const relatedInstance = new RelatedClass();
+
+		// Default foreign key: user_id (for User model)
+		const fk = foreignKey || this.getForeignKey();
+
+		// Default local key: id
+		const lk = localKey || this.getKeyName();
+
+		return new HasMany<TRelated>(this, relatedInstance, fk, lk);
+	}
+
+	/**
+	 * Define a many-to-many relationship with a pivot table.
+	 *
+	 * Uses an intermediate (pivot) table to connect two models.
+	 *
+	 * Example: Users belong to many Roles through role_user pivot table
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class User extends Model {
+	 *     roles() {
+	 *         return this.belongsToMany(Role, 'role_user', 'user_id', 'role_id');
+	 *     }
+	 * }
+	 *
+	 * const user = await User.find(1);
+	 * const roles = await user.roles().get();           // Get all roles
+	 * await user.roles().attach(1);                      // Attach a role
+	 * await user.roles().detach([1, 2]);                 // Detach roles
+	 * await user.roles().sync([1, 2, 3]);                // Sync roles
+	 * ```
+	 *
+	 * @param RelatedClass - The related model class constructor
+	 * @param table - The pivot table name (defaults to alphabetically sorted model names: role_user)
+	 * @param foreignPivotKey - The foreign key for this model on the pivot table (defaults to {thisModel}_id)
+	 * @param relatedPivotKey - The foreign key for the related model on the pivot table (defaults to {related}_id)
+	 * @param parentKey - The primary key on this model (defaults to 'id')
+	 * @param relatedKey - The primary key on the related model (defaults to 'id')
+	 * @returns A BelongsToMany relationship instance
+	 */
+	protected belongsToMany<TRelated extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		table?: string,
+		foreignPivotKey?: string,
+		relatedPivotKey?: string,
+		parentKey?: string,
+		relatedKey?: string
+	): BelongsToMany<TRelated> {
+		const relatedInstance = new RelatedClass();
+
+		// Generate default pivot table name (alphabetically sorted, e.g., role_user)
+		const thisTable = this.inferTableName().replace(/s$/, ''); // Remove trailing 's'
+		const relatedTable = relatedInstance.getTable().replace(/s$/, '');
+		const defaultTable = [thisTable, relatedTable].sort().join('_');
+
+		const pivotTable = table || defaultTable;
+		const fpk = foreignPivotKey || this.getForeignKey();
+		const rpk = relatedPivotKey || relatedInstance.getForeignKey();
+		const pk = parentKey || this.getKeyName();
+		const rk = relatedKey || relatedInstance.getKeyName();
+
+		return new BelongsToMany<TRelated>(
+			this,
+			relatedInstance,
+			pivotTable,
+			fpk,
+			rpk,
+			pk,
+			rk
+		);
+	}
+
+	/**
+	 * Define a has-one-through relationship.
+	 *
+	 * Retrieves a single related model through an intermediate model.
+	 *
+	 * Example: Country has one Profile through User
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class Country extends Model {
+	 *     userProfile() {
+	 *         return this.hasOneThrough(
+	 *             Profile,        // Final model
+	 *             User,           // Intermediate model
+	 *             'country_id',   // Foreign key on users (links to countries)
+	 *             'user_id',      // Foreign key on profiles (links to users)
+	 *             'id',           // Local key on countries
+	 *             'id'            // Local key on users
+	 *         );
+	 *     }
+	 * }
+	 *
+	 * const country = await Country.find(1);
+	 * const profile = await country.userProfile().get();
+	 * ```
+	 *
+	 * @param RelatedClass - The final related model class constructor
+	 * @param ThroughClass - The intermediate model class constructor
+	 * @param firstKey - The foreign key on the intermediate table referencing this model
+	 * @param secondKey - The foreign key on the final table referencing the intermediate model
+	 * @param localKey - The primary key on this model (defaults to 'id')
+	 * @param secondLocalKey - The primary key on the intermediate model (defaults to 'id')
+	 * @returns A HasOneThrough relationship instance
+	 */
+	protected hasOneThrough<TRelated extends Model, TThrough extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		ThroughClass: new (attrs?: Record<string, unknown>) => TThrough,
+		firstKey?: string,
+		secondKey?: string,
+		localKey?: string,
+		secondLocalKey?: string
+	): HasOneThrough<TRelated> {
+		const relatedInstance = new RelatedClass();
+		const throughInstance = new ThroughClass();
+
+		// Default keys
+		const fk = firstKey || this.getForeignKey();
+		const sk = secondKey || throughInstance.getForeignKey();
+		const lk = localKey || this.getKeyName();
+		const slk = secondLocalKey || throughInstance.getKeyName();
+
+		return new HasOneThrough<TRelated>(
+			this,
+			relatedInstance,
+			throughInstance,
+			fk,
+			sk,
+			lk,
+			slk
+		);
+	}
+
+	/**
+	 * Define a has-many-through relationship.
+	 *
+	 * Retrieves multiple related models through an intermediate model.
+	 *
+	 * Example: Country has many Posts through Users
+	 *
+	 * Usage:
+	 * ```typescript
+	 * class Country extends Model {
+	 *     posts() {
+	 *         return this.hasManyThrough(
+	 *             Post,           // Final model
+	 *             User,           // Intermediate model
+	 *             'country_id',   // Foreign key on users (links to countries)
+	 *             'user_id',      // Foreign key on posts (links to users)
+	 *             'id',           // Local key on countries
+	 *             'id'            // Local key on users
+	 *         );
+	 *     }
+	 * }
+	 *
+	 * const country = await Country.find(1);
+	 * const posts = await country.posts().get(); // All posts from users in this country
+	 * ```
+	 *
+	 * @param RelatedClass - The final related model class constructor
+	 * @param ThroughClass - The intermediate model class constructor
+	 * @param firstKey - The foreign key on the intermediate table referencing this model
+	 * @param secondKey - The foreign key on the final table referencing the intermediate model
+	 * @param localKey - The primary key on this model (defaults to 'id')
+	 * @param secondLocalKey - The primary key on the intermediate model (defaults to 'id')
+	 * @returns A HasManyThrough relationship instance
+	 */
+	protected hasManyThrough<TRelated extends Model, TThrough extends Model>(
+		RelatedClass: new (attrs?: Record<string, unknown>) => TRelated,
+		ThroughClass: new (attrs?: Record<string, unknown>) => TThrough,
+		firstKey?: string,
+		secondKey?: string,
+		localKey?: string,
+		secondLocalKey?: string
+	): HasManyThrough<TRelated> {
+		const relatedInstance = new RelatedClass();
+		const throughInstance = new ThroughClass();
+
+		// Default keys
+		const fk = firstKey || this.getForeignKey();
+		const sk = secondKey || throughInstance.getForeignKey();
+		const lk = localKey || this.getKeyName();
+		const slk = secondLocalKey || throughInstance.getKeyName();
+
+		return new HasManyThrough<TRelated>(
+			this,
+			relatedInstance,
+			throughInstance,
+			fk,
+			sk,
+			lk,
+			slk
+		);
+	}
+
+	/**
+	 * Paginate the model query.
+	 */
+	static async paginate<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		perPage: number = 15,
+		columns: string[] = ['*'],
+		pageName: string = 'page',
+		page?: number
+	): Promise<LengthAwarePaginator<T>> {
+		const instance = new this();
+		const paginator = await instance.newQuery().paginate<Record<string, unknown>>(
+			perPage,
+			columns,
+			pageName,
+			page
+		);
+
+		return new LengthAwarePaginator<T>(
+			paginator.items as unknown as T[],
+			paginator.total,
+			paginator.perPage,
+			paginator.currentPage,
+			{
+				path: paginator.path,
+				query: paginator.query,
+			}
+		);
+	}
+
+	/**
+	 * Simple pagination for the model query.
+	 */
+	static async simplePaginate<T extends Model>(
+		this: new (attrs?: Record<string, unknown>) => T,
+		perPage: number = 15,
+		columns: string[] = ['*'],
+		pageName: string = 'page',
+		page?: number
+	): Promise<Paginator<T>> {
+		const instance = new this();
+		const paginator = await instance.newQuery().simplePaginate<Record<string, unknown>>(
+			perPage,
+			columns,
+			pageName,
+			page
+		);
+
+		return new Paginator<T>(
+			paginator.items as unknown as T[],
+			paginator.perPage,
+			paginator.currentPage,
+			{
+				path: paginator.path,
+				query: paginator.query,
+				hasMore: paginator.hasMore,
+			}
+		);
+	}
+}