create-phoenixjs 0.1.4 → 0.1.5

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

@@ -0,0 +1,342 @@
+import { DB } from '../query/DB';
+import type { Builder } from '../query/Builder';
+import type { Model } from './Model';
+
+/**
+ * Abstract Relation class - Base class for all relationship types.
+ *
+ * This class provides the foundation for defining relationships between models.
+ * It handles query building, constraint application, and result hydration.
+ *
+ * All relationship types (HasOne, HasMany, BelongsTo, etc.) extend this class
+ * and implement their specific logic for retrieving related models.
+ *
+ * @template TRelated - The type of the related model
+ */
+export abstract class Relation<TRelated extends Model> {
+	/**
+	 * The parent model instance.
+	 * This is the model that "owns" the relationship.
+	 */
+	protected parent: Model;
+
+	/**
+	 * The related model instance (used as a prototype for creating new instances).
+	 * This is a fresh instance used for table name inference and hydration.
+	 */
+	protected related: TRelated;
+
+	/**
+	 * The query builder instance for the relationship.
+	 * Used to build and execute queries against the related model's table.
+	 */
+	protected query: Builder;
+
+	/**
+	 * Create a new Relation instance.
+	 *
+	 * @param parent - The parent model that owns this relationship
+	 * @param related - An instance of the related model class
+	 */
+	constructor(parent: Model, related: TRelated) {
+		this.parent = parent;
+		this.related = related;
+		this.query = this.newQuery();
+
+		// Add relationship constraints to the query
+		this.addConstraints();
+	}
+
+	// ==========================================
+	// Abstract Methods (Must be implemented by subclasses)
+	// ==========================================
+
+	/**
+	 * Get the results of the relationship.
+	 * Each relationship type implements this differently:
+	 * - HasOne/BelongsTo: Returns single model or null
+	 * - HasMany/BelongsToMany: Returns array of models
+	 */
+	abstract getResults(): Promise<TRelated | TRelated[] | null>;
+
+	/**
+	 * Add the constraints for the relationship query.
+	 * This is called during construction to set up the WHERE clauses
+	 * that link the parent model to its related models.
+	 */
+	abstract addConstraints(): void;
+
+	/**
+	 * Add constraints for eager loading.
+	 * Called when loading relations for multiple parent models at once.
+	 * Should add a WHERE IN constraint for all parent keys.
+	 *
+	 * @param models - Array of parent models to load relations for
+	 */
+	abstract addEagerConstraints(models: Model[]): void;
+
+	/**
+	 * Match the eagerly loaded results to their parent models.
+	 * This associates the loaded related models with their correct parents.
+	 *
+	 * @param models - Array of parent models
+	 * @param results - Array of related models that were loaded
+	 * @param relation - The name of the relationship being matched
+	 */
+	abstract match(models: Model[], results: TRelated[], relation: string): void;
+
+	/**
+	 * Initialize the relation for eager loading.
+	 * Creates a fresh query without the parent-specific constraints.
+	 */
+	public initializeForEagerLoading(): void {
+		this.query = this.newQuery();
+	}
+
+
+	// ==========================================
+	// Query Building
+	// ==========================================
+
+	/**
+	 * Create a new query builder for the related model's table.
+	 * This provides a fresh Builder instance targeting the related table.
+	 *
+	 * @returns A new Builder instance for the related model's table
+	 */
+	protected newQuery(): Builder {
+		return DB.table(this.related.getTable());
+	}
+
+	/**
+	 * Get the underlying query builder instance.
+	 * Useful for adding additional constraints or debugging.
+	 *
+	 * @returns The Builder instance for this relationship
+	 */
+	public getQuery(): Builder {
+		return this.query;
+	}
+
+	/**
+	 * Get the parent model of the relationship.
+	 *
+	 * @returns The parent model instance
+	 */
+	public getParent(): Model {
+		return this.parent;
+	}
+
+	/**
+	 * Get the related model prototype.
+	 * This is the model instance used for table name inference and hydration.
+	 *
+	 * @returns The related model instance
+	 */
+	public getRelated(): TRelated {
+		return this.related;
+	}
+
+	// ==========================================
+	// Query Execution Methods
+	// ==========================================
+
+	/**
+	 * Execute the relationship query and get the results.
+	 * This is the primary method for retrieving related models.
+	 *
+	 * @returns The related model(s) based on relationship type
+	 */
+	public async get(): Promise<TRelated | TRelated[] | null> {
+		return this.getResults();
+	}
+
+	/**
+	 * Get the first result from the relationship query.
+	 * Useful when you only need one result regardless of relationship type.
+	 *
+	 * @returns The first related model or null
+	 */
+	public async first(): Promise<TRelated | null> {
+		const row = await this.query.first<Record<string, unknown>>();
+
+		if (!row) {
+			return null;
+		}
+
+		return this.hydrateModel(row);
+	}
+
+	/**
+	 * Get all results from the relationship query.
+	 * Always returns an array, even for HasOne/BelongsTo relationships.
+	 *
+	 * @returns Array of related models
+	 */
+	public async getAll(): Promise<TRelated[]> {
+		const rows = await this.query.get<Record<string, unknown>>();
+		return this.hydrateModels(rows);
+	}
+
+	/**
+	 * Check if any related models exist.
+	 *
+	 * @returns True if at least one related model exists
+	 */
+	public async exists(): Promise<boolean> {
+		return this.query.exists();
+	}
+
+	/**
+	 * Get the count of related models.
+	 *
+	 * @returns The number of related models
+	 */
+	public async count(): Promise<number> {
+		return this.query.count();
+	}
+
+	// ==========================================
+	// Query Forwarding Methods
+	// ==========================================
+
+	/**
+	 * Add a WHERE clause to the relationship query.
+	 *
+	 * @param column - The column to filter on
+	 * @param operatorOrValue - The operator or value (if no operator)
+	 * @param value - The value to compare against
+	 * @returns This relation instance for chaining
+	 */
+	public where(
+		column: string,
+		operatorOrValue?: string | number | boolean | null,
+		value?: string | number | boolean | null
+	): this {
+		this.query.where(column, operatorOrValue, value);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE IN clause to the relationship query.
+	 *
+	 * @param column - The column to filter on
+	 * @param values - Array of values to match
+	 * @returns This relation instance for chaining
+	 */
+	public whereIn(column: string, values: (string | number | boolean | null)[]): this {
+		this.query.whereIn(column, values);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NULL clause to the relationship query.
+	 *
+	 * @param column - The column to check for NULL
+	 * @returns This relation instance for chaining
+	 */
+	public whereNull(column: string): this {
+		this.query.whereNull(column);
+		return this;
+	}
+
+	/**
+	 * Add a WHERE NOT NULL clause to the relationship query.
+	 *
+	 * @param column - The column to check for NOT NULL
+	 * @returns This relation instance for chaining
+	 */
+	public whereNotNull(column: string): this {
+		this.query.whereNotNull(column);
+		return this;
+	}
+
+	/**
+	 * Add an ORDER BY clause to the relationship query.
+	 *
+	 * @param column - The column to order by
+	 * @param direction - The sort direction ('asc' or 'desc')
+	 * @returns This relation instance for chaining
+	 */
+	public orderBy(column: string, direction: 'asc' | 'desc' = 'asc'): this {
+		this.query.orderBy(column, direction);
+		return this;
+	}
+
+	/**
+	 * Add a LIMIT clause to the relationship query.
+	 *
+	 * @param value - The maximum number of results
+	 * @returns This relation instance for chaining
+	 */
+	public limit(value: number): this {
+		this.query.limit(value);
+		return this;
+	}
+
+	/**
+	 * Add an OFFSET clause to the relationship query.
+	 *
+	 * @param value - The number of results to skip
+	 * @returns This relation instance for chaining
+	 */
+	public offset(value: number): this {
+		this.query.offset(value);
+		return this;
+	}
+
+	// ==========================================
+	// Model Hydration
+	// ==========================================
+
+	/**
+	 * Create a new model instance from a database row.
+	 * The model is marked as existing and its original attributes are synced.
+	 *
+	 * @param row - The database row to hydrate
+	 * @returns A new model instance with the given attributes
+	 */
+	protected hydrateModel(row: Record<string, unknown>): TRelated {
+		const instance = this.related.newInstance({}, true);
+		instance.forceFill(row);
+		instance.syncOriginal();
+		return instance as TRelated;
+	}
+
+	/**
+	 * Create multiple model instances from database rows.
+	 *
+	 * @param rows - Array of database rows to hydrate
+	 * @returns Array of new model instances
+	 */
+	protected hydrateModels(rows: Record<string, unknown>[]): TRelated[] {
+		return rows.map((row) => this.hydrateModel(row));
+	}
+
+	// ==========================================
+	// Key Helpers
+	// ==========================================
+
+	/**
+	 * Get the fully qualified foreign key name (table.column format).
+	 * Used for JOIN operations to avoid column name ambiguity.
+	 *
+	 * @param table - The table name
+	 * @param column - The column name
+	 * @returns The qualified column name (e.g., "users.id")
+	 */
+	protected qualifyColumn(table: string, column: string): string {
+		return `${table}.${column}`;
+	}
+
+	/**
+	 * Get the value of the parent's local key.
+	 * This is the value used to match related models.
+	 *
+	 * @param key - The key name on the parent model
+	 * @returns The value of the key
+	 */
+	protected getParentKeyValue(key: string): unknown {
+		return this.parent.getAttribute(key);
+	}
+}

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

@@ -0,0 +1,14 @@
+import type { Builder } from '../query/Builder';
+import type { Model } from './Model';
+
+export interface Scope {
+	/**
+	 * Apply the scope to a given Eloquent query builder.
+	 */
+	apply(builder: Builder, model: Model): void;
+
+	/**
+	 * Extend the query builder with scope-specific macros.
+	 */
+	extend?(builder: Builder): void;
+}

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

@@ -0,0 +1,160 @@
+import { Model } from './Model';
+import { SoftDeletingScope } from './scopes/SoftDeletingScope';
+import { Builder } from './Builder';
+
+type Constructor<T = {}> = new (...args: any[]) => T;
+
+export function SoftDeletes<TBase extends Constructor<Model>>(Base: TBase) {
+	return class SoftDeletes extends Base {
+		protected forceDeleting: boolean = false;
+
+		/**
+ * Boot the soft deleting trait for a model.
+ */
+		public static bootSoftDeletes() {
+			(this as any).addGlobalScope(new SoftDeletingScope());
+		}
+
+		/**
+		 * Initialize the soft deleting trait for an instance.
+		 */
+		public initializeSoftDeletes() {
+			// Casts not fully implemented yet in Model, skipping for now
+		}
+
+		/**
+		 * Force a hard delete on a soft deleted model.
+		 */
+		public async forceDelete(): Promise<boolean> {
+			this.forceDeleting = true;
+			const result = await this.delete();
+			this.forceDeleting = false;
+			return result;
+		}
+
+		/**
+		 * Restore a soft-deleted model instance.
+		 */
+		public async restore(): Promise<boolean> {
+			if (!(await this.fireModelEvent('restoring' as any))) {
+				return false;
+			}
+
+			this.setAttribute(this.getDeletedAtColumn(), null);
+			this.exists = true;
+
+			// We handle the update manually to ensure we can find the deleted model
+			const query = this.newQuery().withoutGlobalScope(SoftDeletingScope);
+			const affected = await query
+				.where(this.getKeyName(), '=', this.getKey() as any)
+				.update({ [this.getDeletedAtColumn()]: null });
+
+			this.syncOriginal();
+
+			if (affected > 0) {
+				await this.fireModelEvent('restored' as any);
+				return true;
+			}
+
+			return false;
+		}
+
+		/**
+		 * Get the name of the "deleted at" column.
+		 */
+		public getDeletedAtColumn(): string {
+			return (this.constructor as any).DELETED_AT || 'deleted_at';
+		}
+
+		/**
+		 * Get the fully qualified "deleted at" column.
+		 */
+		public getQualifiedDeletedAtColumn(): string {
+			return this.getTable() + '.' + this.getDeletedAtColumn();
+		}
+
+
+
+		/**
+		 * Perform the actual delete query on this model instance.
+		 * Override the default delete behavior.
+		 */
+		public async delete(): Promise<boolean> {
+			if (!this.exists) {
+				return false;
+			}
+
+			if (!(await this.fireModelEvent('deleting'))) {
+				return false;
+			}
+
+			if (this.forceDeleting) {
+				// Hard delete
+				// We must disable soft deleting scope to be able to delete "deleted" items if they are already soft deleted
+				// (Though forceDelete checks exists using instance, if instance is hydrated it's fine)
+				// But just in case:
+				const query = this.newQuery().withoutGlobalScope(SoftDeletingScope);
+				const affected = await query
+					.where(this.getKeyName(), '=', this.getKey() as any)
+					.delete();
+
+				this.exists = false;
+				await this.fireModelEvent('deleted');
+				return true;
+			} else {
+				// Soft delete
+				const result = await this.runSoftDelete();
+				return result;
+			}
+		}
+
+		/**
+		 * Run the soft delete.
+		 */
+		protected async runSoftDelete(): Promise<boolean> {
+			const query = this.newQuery();
+			const time = this.freshTimestamp();
+			const columns = { [this.getDeletedAtColumn()]: time };
+
+			this.setAttribute(this.getDeletedAtColumn(), time);
+
+			// Update database
+			const affected = await query
+				.where(this.getKeyName(), '=', this.getKey() as any)
+				.update(columns);
+
+			this.syncOriginal();
+			await this.fireModelEvent('deleted');
+
+			return affected > 0;
+		}
+
+		/**
+		 * Check if the model instance has been soft-deleted.
+		 */
+		public trashed(): boolean {
+			return this.getAttribute(this.getDeletedAtColumn()) !== null;
+		}
+
+		/**
+		 * Static methods for query scopes. 
+		 * Since Mixins return a class, we can just add static methods here.
+		 */
+
+		public static withTrashed(withTrashed: boolean = true) {
+			const query = new this().newQuery() as any;
+			return query.withTrashed(withTrashed);
+		}
+
+		public static onlyTrashed() {
+			const query = new this().newQuery() as any;
+			return query.onlyTrashed();
+		}
+
+		public static withoutTrashed() {
+			const query = new this().newQuery() as any;
+			return query.withoutTrashed();
+		}
+
+	};
+}

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

@@ -0,0 +1,54 @@
+/**
+ * PhoenixJS ORM Module
+ *
+ * This module provides a Laravel-style Active Record ORM implementation.
+ *
+ * Core Classes:
+ * - Model: Base class for all models with CRUD operations
+ * - Relation: Abstract base class for relationships
+ *
+ * Relationship Types:
+ * - HasOne: One-to-one (User has one Profile)
+ * - BelongsTo: Inverse (Profile belongs to User)
+ * - HasMany: One-to-many (User has many Posts)
+ * - BelongsToMany: Many-to-many with pivot table (Users <-> Roles)
+ * - HasOneThrough: One through intermediate (Country -> User -> Profile)
+ * - HasManyThrough: Many through intermediate (Country -> Users -> Posts)
+ *
+ * Usage:
+ * ```typescript
+ * import { Model, HasOne, BelongsTo, HasMany, BelongsToMany } from '@framework/database/orm';
+ *
+ * class User extends Model {
+ *     profile() {
+ *         return this.hasOne(Profile, 'user_id', 'id');
+ *     }
+ *
+ *     posts() {
+ *         return this.hasMany(Post, 'user_id', 'id');
+ *     }
+ *
+ *     roles() {
+ *         return this.belongsToMany(Role, 'role_user', 'user_id', 'role_id');
+ *     }
+ * }
+ * ```
+ */
+
+// Core exports
+export { Model, ModelNotFoundException } from './Model';
+export type { ModelEventType, ModelEventCallback } from './Model';
+
+// Relationship base class
+export { Relation } from './Relation';
+
+// Relationship types
+export { HasOne } from './HasOne';
+export { BelongsTo } from './BelongsTo';
+export { HasMany } from './HasMany';
+export { BelongsToMany } from './BelongsToMany';
+export { HasOneThrough } from './HasOneThrough';
+export { HasManyThrough } from './HasManyThrough';
+
+// Eager loading
+export { EagerLoadingBuilder } from './EagerLoadingBuilder';

package/template/framework/database/orm/scopes/SoftDeletingScope.ts

@@ -0,0 +1,58 @@
+import type { Scope } from '../Scope';
+import type { Builder } from '../Builder';
+import type { Model } from '../Model';
+
+export class SoftDeletingScope implements Scope {
+	/**
+	 * Apply the scope to a given Eloquent query builder.
+	 */
+	public apply(builder: Builder, model: Model): void {
+		// We assume the model has 'getQualifiedDeletedAtColumn' from SoftDeletes trait/mixin
+		// Since we can't easily enforce Mixin types on the Model type here without circular deps or complex types,
+		// we'll cast or check.
+		const modelWithSoftDeletes = model as any;
+
+		if (typeof modelWithSoftDeletes.getQualifiedDeletedAtColumn === 'function') {
+			builder.whereNull(modelWithSoftDeletes.getQualifiedDeletedAtColumn());
+		}
+	}
+
+	/**
+	 * Extend the query builder with the needed functions.
+	 */
+	public extend(builder: Builder): void {
+		const anyBuilder = builder as any;
+
+		// Add withTrashed macro
+		anyBuilder.withTrashed = function (this: any, withTrashed: boolean = true) {
+			if (!withTrashed) {
+				return this.withoutTrashed();
+			}
+
+			return this.withoutGlobalScope(SoftDeletingScope);
+		};
+
+		// Add withoutTrashed macro
+		anyBuilder.withoutTrashed = function (this: Builder) {
+			const model = (this as any).getModel(); // We'll need to make sure Builder has reference to Model
+			const scope = new SoftDeletingScope();
+
+			scope.apply(this, model);
+
+			return this;
+		};
+
+		// Add onlyTrashed macro
+		anyBuilder.onlyTrashed = function (this: Builder) {
+			const model = (this as any).getModel();
+
+			// Remove the SoftDeletingScope to allow seeing deleted items
+			this.withoutGlobalScope(SoftDeletingScope);
+
+			// Add whereNotNull condition
+			this.whereNotNull((model as any).getQualifiedDeletedAtColumn());
+
+			return this;
+		};
+	}
+}

package/template/framework/database/pagination/LengthAwarePaginator.ts

@@ -0,0 +1,55 @@
+/**
+ * PhoenixJS ORM - LengthAwarePaginator
+ *
+ * Paginator with total count and last page calculation.
+ */
+
+import { Paginator } from './Paginator';
+
+export class LengthAwarePaginator<T> extends Paginator<T> {
+	/**
+	 * The total number of items.
+	 */
+	public total: number;
+
+	/**
+	 * The last page number.
+	 */
+	public lastPage: number;
+
+	/**
+	 * Create a new LengthAwarePaginator instance.
+	 */
+	constructor(
+		items: T[],
+		total: number,
+		perPage: number,
+		currentPage: number,
+		options: { path?: string; query?: Record<string, string> } = {}
+	) {
+		super(items, perPage, currentPage, options);
+		this.total = total;
+		this.lastPage = Math.max(1, Math.ceil(total / perPage));
+		this.hasMore = this.currentPage < this.lastPage;
+	}
+
+	/**
+	 * Get the URL for the last page.
+	 */
+	public lastPageUrl(): string {
+		return this.url(this.lastPage);
+	}
+
+	/**
+	 * Convert the instance to JSON.
+	 */
+	public override toJSON(): Record<string, unknown> {
+		const baseJson = super.toJSON();
+		return {
+			...baseJson,
+			total: this.total,
+			last_page: this.lastPage,
+			last_page_url: this.lastPageUrl(),
+		};
+	}
+}