@buenojs/bueno 0.8.4 → 0.8.5

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

@@ -0,0 +1,130 @@
+/**
+ * Cast Registry and Built-in Casts
+ */
+
+import type { CastDefinition, CastObject } from "./types";
+
+export type { CastDefinition, CastObject, BuiltInCastName } from "./types";
+
+const builtInCasts: Record<string, CastObject> = {
+	json: {
+		get(value: unknown): unknown {
+			if (typeof value === "string") {
+				try {
+					return JSON.parse(value);
+				} catch {
+					return value;
+				}
+			}
+			return value;
+		},
+		set(value: unknown): unknown {
+			if (typeof value === "string") return value;
+			return JSON.stringify(value);
+		},
+	},
+
+	boolean: {
+		get(value: unknown): boolean | null {
+			if (value === null || value === undefined) return null;
+			if (typeof value === "boolean") return value;
+			if (typeof value === "number") return value !== 0;
+			if (typeof value === "string") return value !== "0" && value !== "false";
+			return Boolean(value);
+		},
+		set(value: unknown): number {
+			return value ? 1 : 0;
+		},
+	},
+
+	integer: {
+		get(value: unknown): number {
+			return Number(value);
+		},
+		set(value: unknown): number {
+			return Number(value);
+		},
+	},
+
+	float: {
+		get(value: unknown): number {
+			return Number(value);
+		},
+		set(value: unknown): number {
+			return Number(value);
+		},
+	},
+
+	date: {
+		get(value: unknown): Date | null {
+			if (!value) return null;
+			if (value instanceof Date) return value;
+			return new Date(String(value));
+		},
+		set(value: unknown): string {
+			if (value instanceof Date) {
+				return value.toISOString().split("T")[0];
+			}
+			return String(value);
+		},
+	},
+
+	datetime: {
+		get(value: unknown): Date | null {
+			if (!value) return null;
+			if (value instanceof Date) return value;
+			return new Date(String(value));
+		},
+		set(value: unknown): string {
+			if (value instanceof Date) {
+				return value.toISOString();
+			}
+			return String(value);
+		},
+	},
+
+	timestamp: {
+		get(value: unknown): Date | null {
+			if (!value) return null;
+			if (value instanceof Date) return value;
+			if (typeof value === "number") return new Date(value);
+			return new Date(Number(value));
+		},
+		set(value: unknown): number {
+			if (value instanceof Date) {
+				return value.getTime();
+			}
+			return Number(value);
+		},
+	},
+};
+
+export class CastRegistry {
+	/**
+	 * Deserialize a value from database using a cast definition
+	 */
+	static deserialize(castDef: CastDefinition, value: unknown): unknown {
+		if (typeof castDef === "string") {
+			const castObj = builtInCasts[castDef];
+			if (!castObj) {
+				throw new Error(`Unknown cast: ${castDef}`);
+			}
+			return castObj.get(value);
+		}
+		return castDef.get(value);
+	}
+
+	/**
+	 * Serialize a value to database using a cast definition
+	 */
+	static serialize(castDef: CastDefinition, value: unknown): unknown {
+		if (typeof castDef === "string") {
+			const castObj = builtInCasts[castDef];
+			if (!castObj) {
+				throw new Error(`Unknown cast: ${castDef}`);
+			}
+			return castObj.set(value);
+		}
+		return castDef.set(value);
+	}
+}

package/src/database/orm/casts/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Cast Type Definitions
+ */
+
+export type BuiltInCastName =
+	| "json"
+	| "boolean"
+	| "integer"
+	| "float"
+	| "date"
+	| "datetime"
+	| "timestamp";
+
+export interface CastObject {
+	/**
+	 * Transform value from database to model attribute
+	 */
+	get(value: unknown): unknown;
+	/**
+	 * Transform value from model attribute to database
+	 */
+	set(value: unknown): unknown;
+}
+
+export type CastDefinition = BuiltInCastName | CastObject;

package/src/database/orm/compiler.ts

@@ -0,0 +1,304 @@
+/**
+ * SQL Query Compiler
+ *
+ * Converts a QueryState into SQL strings and parameters,
+ * handling driver differences (PostgreSQL $1 vs SQLite/MySQL ?)
+ */
+
+export type SqlDialect = "postgresql" | "mysql" | "sqlite";
+
+export interface CompiledQuery {
+	sql: string;
+	params: unknown[];
+}
+
+export interface WhereClause {
+	type: "and" | "or";
+	column?: string;
+	operator?: string;
+	value?: unknown;
+	raw?: string;
+	rawParams?: unknown[];
+	nested?: WhereClause[];
+}
+
+export interface OrderClause {
+	column: string;
+	direction: "ASC" | "DESC";
+}
+
+export interface JoinClause {
+	type: "INNER" | "LEFT" | "RIGHT" | "CROSS";
+	table: string;
+	on: string;
+}
+
+export interface QueryState {
+	table: string;
+	alias?: string;
+	selects: string[];
+	wheres: WhereClause[];
+	orders: OrderClause[];
+	joins: JoinClause[];
+	limitVal?: number;
+	offsetVal?: number;
+	groupBys: string[];
+	havings: string[];
+	distinct: boolean;
+	lockMode?: "share" | "update";
+}
+
+export class QueryCompiler {
+	private paramIndex = 0;
+	private params: unknown[] = [];
+
+	constructor(private dialect: SqlDialect) {}
+
+	/**
+	 * Reset state for a new compilation
+	 */
+	private reset(): void {
+		this.paramIndex = 0;
+		this.params = [];
+	}
+
+	/**
+	 * Add a parameter and return the placeholder for this dialect
+	 */
+	private addParam(value: unknown): string {
+		this.params.push(value);
+		if (this.dialect === "postgresql") {
+			return `$${++this.paramIndex}`;
+		}
+		this.paramIndex++;
+		return "?";
+	}
+
+	/**
+	 * Compile a SELECT query
+	 */
+	compileSelect(state: QueryState): CompiledQuery {
+		this.reset();
+		const parts: string[] = [];
+
+		// SELECT
+		const cols = state.selects.length > 0 ? state.selects.join(", ") : "*";
+		const distinct = state.distinct ? "DISTINCT " : "";
+		parts.push(`SELECT ${distinct}${cols}`);
+
+		// FROM
+		const alias = state.alias ? ` AS ${state.alias}` : "";
+		parts.push(`FROM ${state.table}${alias}`);
+
+		// JOINs
+		for (const j of state.joins) {
+			parts.push(`${j.type} JOIN ${j.table} ON ${j.on}`);
+		}
+
+		// WHERE
+		if (state.wheres.length > 0) {
+			parts.push(`WHERE ${this.compileWheres(state.wheres)}`);
+		}
+
+		// GROUP BY
+		if (state.groupBys.length > 0) {
+			parts.push(`GROUP BY ${state.groupBys.join(", ")}`);
+		}
+
+		// HAVING
+		if (state.havings.length > 0) {
+			parts.push(`HAVING ${state.havings.join(" AND ")}`);
+		}
+
+		// ORDER BY
+		if (state.orders.length > 0) {
+			const orderStr = state.orders
+				.map((o) => `${o.column} ${o.direction}`)
+				.join(", ");
+			parts.push(`ORDER BY ${orderStr}`);
+		}
+
+		// LIMIT / OFFSET
+		if (state.limitVal !== undefined) {
+			parts.push(`LIMIT ${this.addParam(state.limitVal)}`);
+		}
+		if (state.offsetVal !== undefined) {
+			parts.push(`OFFSET ${this.addParam(state.offsetVal)}`);
+		}
+
+		// Locking
+		if (state.lockMode === "update") parts.push("FOR UPDATE");
+		if (state.lockMode === "share") parts.push("FOR SHARE");
+
+		return { sql: parts.join(" "), params: [...this.params] };
+	}
+
+	/**
+	 * Compile WHERE clauses into SQL
+	 */
+	private compileWheres(wheres: WhereClause[]): string {
+		return wheres
+			.map((w, i) => {
+				const prefix = i === 0 ? "" : `${w.type.toUpperCase()} `;
+
+				if (w.raw !== undefined) {
+					if (w.rawParams) {
+						for (const p of w.rawParams) {
+							this.params.push(p);
+						}
+					}
+					return `${prefix}(${w.raw})`;
+				}
+
+				if (w.nested) {
+					return `${prefix}(${this.compileWheres(w.nested)})`;
+				}
+
+				if (w.operator === "IN" && Array.isArray(w.value)) {
+					const placeholders = w.value.map((v) => this.addParam(v)).join(", ");
+					return `${prefix}${w.column} IN (${placeholders})`;
+				}
+
+				if (w.operator === "NOT IN" && Array.isArray(w.value)) {
+					const placeholders = w.value.map((v) => this.addParam(v)).join(", ");
+					return `${prefix}${w.column} NOT IN (${placeholders})`;
+				}
+
+				if (w.operator === "IS NULL") {
+					return `${prefix}${w.column} IS NULL`;
+				}
+
+				if (w.operator === "IS NOT NULL") {
+					return `${prefix}${w.column} IS NOT NULL`;
+				}
+
+				if (w.operator === "BETWEEN") {
+					const [min, max] = w.value as [unknown, unknown];
+					return `${prefix}${w.column} BETWEEN ${this.addParam(min)} AND ${this.addParam(max)}`;
+				}
+
+				return `${prefix}${w.column} ${w.operator} ${this.addParam(w.value)}`;
+			})
+			.join(" ");
+	}
+
+	/**
+	 * Compile an INSERT query
+	 */
+	compileInsert(table: string, data: Record<string, unknown>): CompiledQuery {
+		this.reset();
+		const keys = Object.keys(data);
+		const columns = keys.join(", ");
+		const placeholders = keys.map((k) => this.addParam(data[k])).join(", ");
+
+		const returning = this.dialect === "postgresql" ? " RETURNING *" : "";
+		return {
+			sql: `INSERT INTO ${table} (${columns}) VALUES (${placeholders})${returning}`,
+			params: [...this.params],
+		};
+	}
+
+	/**
+	 * Compile a batch INSERT query
+	 */
+	compileBatchInsert(
+		table: string,
+		rows: Record<string, unknown>[],
+	): CompiledQuery {
+		this.reset();
+
+		if (rows.length === 0) {
+			return { sql: "", params: [] };
+		}
+
+		const keys = Object.keys(rows[0]);
+		const columns = keys.join(", ");
+
+		const valueRows = rows.map((row) => {
+			const placeholders = keys.map((k) => this.addParam(row[k])).join(", ");
+			return `(${placeholders})`;
+		});
+
+		const returning = this.dialect === "postgresql" ? " RETURNING *" : "";
+		return {
+			sql: `INSERT INTO ${table} (${columns}) VALUES ${valueRows.join(", ")}${returning}`,
+			params: [...this.params],
+		};
+	}
+
+	/**
+	 * Compile an UPDATE query
+	 */
+	compileUpdate(
+		state: QueryState,
+		data: Record<string, unknown>,
+	): CompiledQuery {
+		this.reset();
+		const sets = Object.entries(data)
+			.map(([col, val]) => `${col} = ${this.addParam(val)}`)
+			.join(", ");
+
+		const whereStr =
+			state.wheres.length > 0
+				? ` WHERE ${this.compileWheres(state.wheres)}`
+				: "";
+
+		const returning = this.dialect === "postgresql" ? " RETURNING *" : "";
+		return {
+			sql: `UPDATE ${state.table} SET ${sets}${whereStr}${returning}`,
+			params: [...this.params],
+		};
+	}
+
+	/**
+	 * Compile a DELETE query
+	 */
+	compileDelete(state: QueryState): CompiledQuery {
+		this.reset();
+		const whereStr =
+			state.wheres.length > 0
+				? ` WHERE ${this.compileWheres(state.wheres)}`
+				: "";
+		return {
+			sql: `DELETE FROM ${state.table}${whereStr}`,
+			params: [...this.params],
+		};
+	}
+
+	/**
+	 * Compile a COUNT query
+	 */
+	compileCount(state: QueryState, column = "*"): CompiledQuery {
+		this.reset();
+		const countCol = column === "*" ? "COUNT(*)" : `COUNT(${column})`;
+		const parts: string[] = [`SELECT ${countCol} AS count`];
+
+		const alias = state.alias ? ` AS ${state.alias}` : "";
+		parts.push(`FROM ${state.table}${alias}`);
+
+		for (const j of state.joins) {
+			parts.push(`${j.type} JOIN ${j.table} ON ${j.on}`);
+		}
+
+		if (state.wheres.length > 0) {
+			parts.push(`WHERE ${this.compileWheres(state.wheres)}`);
+		}
+
+		return { sql: parts.join(" "), params: [...this.params] };
+	}
+
+	/**
+	 * Compile an EXISTS query
+	 */
+	compileExists(state: QueryState): CompiledQuery {
+		const selectCompiled = this.compileSelect({
+			...state,
+			selects: ["1"],
+			limitVal: 1,
+		});
+		return {
+			sql: `SELECT EXISTS(${selectCompiled.sql}) as exists`,
+			params: selectCompiled.params,
+		};
+	}
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Model Hooks / Lifecycle Events
+ *
+ * Provides lifecycle callbacks for model events:
+ * creating, created, updating, updated, saving, saved,
+ * deleting, deleted, restoring, restored
+ */
+
+export type ModelHookName =
+	| "creating"
+	| "created"
+	| "updating"
+	| "updated"
+	| "saving"
+	| "saved"
+	| "deleting"
+	| "deleted"
+	| "restoring"
+	| "restored";
+
+export type ModelHookCallback<M> = (
+	model: M,
+) => void | Promise<void> | boolean | Promise<boolean>;
+
+/**
+ * Model hook registry for a specific model class
+ */
+export class HookRunner<M> {
+	private hooks: Map<ModelHookName, ModelHookCallback<M>[]> = new Map();
+
+	constructor(private modelClass: typeof Model) {
+		this.initializeHooks();
+	}
+
+	/**
+	 * Initialize hooks from model class static definitions
+	 */
+	private initializeHooks(): void {
+		// Hooks are registered statically on the model class
+		// They're accessed via Model.on() / Model.once() methods
+	}
+
+	/**
+	 * Register a hook callback
+	 */
+	on(hookName: ModelHookName, callback: ModelHookCallback<M>): void {
+		if (!this.hooks.has(hookName)) {
+			this.hooks.set(hookName, []);
+		}
+		this.hooks.get(hookName)!.push(callback);
+	}
+
+	/**
+	 * Run all callbacks for a hook
+	 * Returns false if any callback explicitly returns false (to abort operation)
+	 */
+	async run(hookName: ModelHookName, model: M): Promise<boolean> {
+		const callbacks = this.hooks.get(hookName) ?? [];
+
+		for (const callback of callbacks) {
+			const result = await callback(model);
+			if (result === false) {
+				return false; // Abort
+			}
+		}
+
+		return true; // Continue
+	}
+}
+
+/**
+ * Placeholder to avoid circular dependency issues
+ */
+export abstract class Model {
+	private static hookRegistry = new Map<string, Map<string, Function[]>>();
+
+	/**
+	 * Get or create the hook registry for this model class
+	 */
+	private static getHookRegistry(
+		modelName: string,
+	): Map<ModelHookName, Function[]> {
+		if (!Model.hookRegistry.has(modelName)) {
+			Model.hookRegistry.set(modelName, new Map<ModelHookName, Function[]>());
+		}
+		return Model.hookRegistry.get(modelName)! as Map<ModelHookName, Function[]>;
+	}
+
+	/**
+	 * Register a hook callback on the model class
+	 */
+	static on<M extends Model>(
+		this: { new (): M } & typeof Model,
+		hookName: ModelHookName,
+		callback: ModelHookCallback<M>,
+	): void {
+		const registry = Model.getHookRegistry(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.getHookRegistry(this.name);
+		return (registry.get(hookName) ?? []) as any;
+	}
+}

package/src/database/orm/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Bueno ORM
+ *
+ * Eloquent-inspired ORM for the Bueno framework.
+ * Provides Model, QueryBuilder, relationships, and lifecycle management.
+ */
+
+// ============= Query Builder =============
+export { OrmQueryBuilder, query } from "./builder";
+export type { PaginationResult } from "./builder";
+
+// ============= Model =============
+export {
+	Model,
+	ModelNotFoundError,
+	ModelOperationAbortedError,
+	ModelQueryBuilder,
+} from "./model";
+
+// ============= Registry =============
+export {
+	setDefaultDatabase,
+	getDefaultDatabase,
+	registerModelDatabase,
+	getModelDatabase,
+	clearModelDatabaseRegistry,
+	clearDefaultDatabase,
+} from "./model-registry";
+
+// ============= Relationships =============
+export {
+	Relationship,
+	HasOne,
+	HasMany,
+	BelongsTo,
+	BelongsToMany,
+} from "./relationships";
+export type { RelationshipOptions } from "./relationships/base";
+
+// ============= Casts =============
+export { CastRegistry } from "./casts";
+export type { CastDefinition, CastObject, BuiltInCastName } from "./casts";
+
+// ============= Scopes =============
+export { ScopeRegistry, SoftDeleteScope } from "./scopes";
+export type { ScopeDefinition } from "./scopes";
+
+// ============= Hooks =============
+export { HookRunner } from "./hooks";
+export type { ModelHookName, ModelHookCallback } from "./hooks";
+
+// ============= Compiler (advanced usage) =============
+export { QueryCompiler } from "./compiler";
+export type {
+	SqlDialect,
+	CompiledQuery,
+	WhereClause,
+	OrderClause,
+	JoinClause,
+	QueryState,
+} from "./compiler";

package/src/database/orm/model-registry.ts

@@ -0,0 +1,59 @@
+/**
+ * Model Registry
+ *
+ * Global registry mapping model names to their Database instances.
+ * Allows per-model connection selection and a default connection fallback.
+ */
+
+import type { Database } from "../index";
+
+const registry = new Map<string, Database>();
+let defaultDb: Database | null = null;
+
+/**
+ * Set the default database for all models
+ */
+export function setDefaultDatabase(db: Database): void {
+	defaultDb = db;
+}
+
+/**
+ * Get the default database
+ */
+export function getDefaultDatabase(): Database {
+	if (!defaultDb) {
+		throw new Error(
+			"No default database configured. Call setDefaultDatabase() before using models.",
+		);
+	}
+	return defaultDb;
+}
+
+/**
+ * Register a database connection for a specific model by name
+ */
+export function registerModelDatabase(modelName: string, db: Database): void {
+	registry.set(modelName, db);
+}
+
+/**
+ * Get the database for a model by name
+ * Falls back to default database if model-specific one not registered
+ */
+export function getModelDatabase(modelName: string): Database {
+	return registry.get(modelName) ?? getDefaultDatabase();
+}
+
+/**
+ * Clear all model database registrations (mainly for testing)
+ */
+export function clearModelDatabaseRegistry(): void {
+	registry.clear();
+}
+
+/**
+ * Clear the default database (mainly for testing)
+ */
+export function clearDefaultDatabase(): void {
+	defaultDb = null;
+}