arkormx 0.2.10 → 1.0.0

package/dist/index.mjs

@@ -5,6 +5,7 @@ import { str } from "@h3ravel/support";
 import path, { dirname as dirname$1, extname as extname$1, join as join$1, relative } from "path";
 import { copyFileSync, existsSync as existsSync$1, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1, rmSync as rmSync$1, writeFileSync as writeFileSync$1 } from "fs";
 import { fileURLToPath, pathToFileURL } from "url";
+import { AsyncLocalStorage } from "async_hooks";
 import { createRequire } from "module";
 import { Logger } from "@h3ravel/shared";
 import { Command } from "@h3ravel/musket";
@@ -93,17 +94,43 @@ function resolveCast(definition) {
 
 //#endregion
 //#region src/Exceptions/ArkormException.ts
-/**
-* The ArkormException class is a custom error type for handling 
-* exceptions specific to the Arkormˣ.    
-* 
-* @author Legacy (3m1n3nc3)
-* @since 0.1.0
-*/
 var ArkormException = class extends Error {
-	constructor(message) {
-		super(message);
+	code;
+	operation;
+	model;
+	delegate;
+	relation;
+	scope;
+	meta;
+	constructor(message, context = {}) {
+		super(message, context.cause === void 0 ? void 0 : { cause: context.cause });
 		this.name = "ArkormException";
+		this.code = context.code;
+		this.operation = context.operation;
+		this.model = context.model;
+		this.delegate = context.delegate;
+		this.relation = context.relation;
+		this.scope = context.scope;
+		this.meta = context.meta;
+	}
+	getContext() {
+		return {
+			code: this.code,
+			operation: this.operation,
+			model: this.model,
+			delegate: this.delegate,
+			relation: this.relation,
+			scope: this.scope,
+			meta: this.meta,
+			cause: this.cause
+		};
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			...this.getContext()
+		};
 	}
 };
 
@@ -1213,6 +1240,18 @@ const runMigrationWithPrisma = async (migration, options = {}) => {
 	};
 };
 
+//#endregion
+//#region src/Exceptions/UnsupportedAdapterFeatureException.ts
+var UnsupportedAdapterFeatureException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "UNSUPPORTED_ADAPTER_FEATURE",
+			...context
+		});
+		this.name = "UnsupportedAdapterFeatureException";
+	}
+};
+
 //#endregion
 //#region src/helpers/runtime-config.ts
 const resolveDefaultStubsPath = () => {
@@ -1246,6 +1285,8 @@ let runtimeConfigLoaded = false;
 let runtimeConfigLoadingPromise;
 let runtimeClientResolver;
 let runtimePaginationURLDriverFactory;
+let runtimePaginationCurrentPageResolver;
+const transactionClientStorage = new AsyncLocalStorage();
 const mergePathConfig = (paths) => {
 	const defaults = baseConfig.paths ?? {};
 	const current = userConfig.paths ?? {};
@@ -1295,6 +1336,7 @@ const configureArkormRuntime = (prisma, options = {}) => {
 	Object.assign(userConfig, { ...nextConfig });
 	runtimeClientResolver = prisma;
 	runtimePaginationURLDriverFactory = nextConfig.pagination?.urlDriver;
+	runtimePaginationCurrentPageResolver = nextConfig.pagination?.resolveCurrentPage;
 };
 /**
 * Reset the ArkORM runtime configuration. 
@@ -1309,6 +1351,7 @@ const resetArkormRuntimeForTests = () => {
 	runtimeConfigLoadingPromise = void 0;
 	runtimeClientResolver = void 0;
 	runtimePaginationURLDriverFactory = void 0;
+	runtimePaginationCurrentPageResolver = void 0;
 };
 /**
 * Resolve a Prisma client instance from the provided resolver, which can be either
@@ -1411,9 +1454,36 @@ const getDefaultStubsPath = () => {
 * @returns 
 */
 const getRuntimePrismaClient = () => {
+	const activeTransactionClient = transactionClientStorage.getStore();
+	if (activeTransactionClient) return activeTransactionClient;
 	if (!runtimeConfigLoaded) loadRuntimeConfigSync();
 	return resolveClient(runtimeClientResolver);
 };
+const getActiveTransactionClient = () => {
+	return transactionClientStorage.getStore();
+};
+const isTransactionCapableClient = (value) => {
+	if (!value || typeof value !== "object") return false;
+	return typeof value.$transaction === "function";
+};
+const runArkormTransaction = async (callback, options = {}) => {
+	const activeTransactionClient = transactionClientStorage.getStore();
+	if (activeTransactionClient) return await callback(activeTransactionClient);
+	const client = getRuntimePrismaClient();
+	if (!client) throw new ArkormException("Cannot start a transaction without a configured Prisma client.", {
+		code: "CLIENT_NOT_CONFIGURED",
+		operation: "transaction"
+	});
+	if (!isTransactionCapableClient(client)) throw new UnsupportedAdapterFeatureException("Transactions are not supported by the current adapter.", {
+		code: "TRANSACTION_NOT_SUPPORTED",
+		operation: "transaction"
+	});
+	return await client.$transaction(async (transactionClient) => {
+		return await transactionClientStorage.run(transactionClient, async () => {
+			return await callback(transactionClient);
+		});
+	}, options);
+};
 /**
 * Get the configured pagination URL driver factory from runtime config.
 *
@@ -1424,6 +1494,15 @@ const getRuntimePaginationURLDriverFactory = () => {
 	return runtimePaginationURLDriverFactory;
 };
 /**
+* Get the configured current-page resolver from runtime config.
+*
+* @returns
+*/
+const getRuntimePaginationCurrentPageResolver = () => {
+	if (!runtimeConfigLoaded) loadRuntimeConfigSync();
+	return runtimePaginationCurrentPageResolver;
+};
+/**
 * Check if a given value is a Prisma delegate-like object 
 * by verifying the presence of common delegate methods.
 * 
@@ -2760,6 +2839,18 @@ const defineFactory = (model, definition) => {
 	return new InlineFactory(model, definition);
 };
 
+//#endregion
+//#region src/Exceptions/MissingDelegateException.ts
+var MissingDelegateException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "MISSING_DELEGATE",
+			...context
+		});
+		this.name = "MissingDelegateException";
+	}
+};
+
 //#endregion
 //#region src/Exceptions/ModelNotFoundException.ts
 /**
@@ -2771,8 +2862,12 @@ const defineFactory = (model, definition) => {
 */
 var ModelNotFoundException = class extends ArkormException {
 	modelName;
-	constructor(modelName, message = "No query results for the given model.") {
-		super(message);
+	constructor(modelName, message = "No query results for the given model.", context = {}) {
+		super(message, {
+			code: "MODEL_NOT_FOUND",
+			model: modelName,
+			...context
+		});
 		this.name = "ModelNotFoundException";
 		this.modelName = modelName;
 	}
@@ -2781,6 +2876,54 @@ var ModelNotFoundException = class extends ArkormException {
 	}
 };
 
+//#endregion
+//#region src/Exceptions/QueryConstraintException.ts
+var QueryConstraintException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "QUERY_CONSTRAINT",
+			...context
+		});
+		this.name = "QueryConstraintException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/RelationResolutionException.ts
+var RelationResolutionException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "RELATION_RESOLUTION_FAILED",
+			...context
+		});
+		this.name = "RelationResolutionException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/ScopeNotDefinedException.ts
+var ScopeNotDefinedException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "SCOPE_NOT_DEFINED",
+			...context
+		});
+		this.name = "ScopeNotDefinedException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/UniqueConstraintResolutionException.ts
+var UniqueConstraintResolutionException = class extends ArkormException {
+	constructor(message, context = {}) {
+		super(message, {
+			code: "UNIQUE_CONSTRAINT_RESOLUTION_FAILED",
+			...context
+		});
+		this.name = "UniqueConstraintResolutionException";
+	}
+};
+
 //#endregion
 //#region src/helpers/prisma.ts
 /**
@@ -3021,6 +3164,7 @@ var BelongsToManyRelation = class extends Relation {
 	async getResults() {
 		const parentValue = this.parent.getAttribute(this.parentKey);
 		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.foreignPivotKey]: parentValue } })).map((row) => row[this.relatedPivotKey]);
+		if (ids.length === 0) return new ArkormCollection([]);
 		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
 	}
 };
@@ -3107,6 +3251,7 @@ var HasManyThroughRelation = class extends Relation {
 	async getResults() {
 		const localValue = this.parent.getAttribute(this.localKey);
 		const keys = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.firstKey]: localValue } })).map((row) => row[this.secondLocalKey]);
+		if (keys.length === 0) return new ArkormCollection([]);
 		return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: keys } })).get();
 	}
 };
@@ -3264,6 +3409,7 @@ var MorphToManyRelation = class extends Relation {
 			[`${this.morphName}Id`]: parentValue,
 			[`${this.morphName}Type`]: morphType
 		} })).map((row) => row[this.relatedPivotKey]);
+		if (ids.length === 0) return new ArkormCollection([]);
 		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
 	}
 };
@@ -3476,6 +3622,13 @@ var QueryBuilder = class QueryBuilder {
 		this.delegate = delegate;
 		this.model = model;
 	}
+	resolvePaginationPage(page, options) {
+		if (typeof page !== "undefined") return Number.isFinite(page) ? Math.max(1, page) : 1;
+		const pageName = options.pageName ?? "page";
+		const resolvedPage = getRuntimePaginationCurrentPageResolver()?.(pageName, options);
+		if (typeof resolvedPage !== "number" || !Number.isFinite(resolvedPage)) return 1;
+		return Math.max(1, resolvedPage);
+	}
 	/**
 	* Adds a where clause to the query. Multiple calls to where will combine 
 	* the clauses with AND logic.
@@ -4008,7 +4161,11 @@ var QueryBuilder = class QueryBuilder {
 	scope(name, ...args) {
 		const methodName = `scope${name.charAt(0).toUpperCase()}${name.slice(1)}`;
 		const scope = this.model.prototype?.[methodName];
-		if (typeof scope !== "function") throw new ArkormException(`Scope [${name}] is not defined.`);
+		if (typeof scope !== "function") throw new ScopeNotDefinedException(`Scope [${name}] is not defined.`, {
+			operation: "scope",
+			model: this.model.name,
+			scope: name
+		});
 		const scoped = scope.call(void 0, this, ...args);
 		if (scoped && scoped !== this) return scoped;
 		return this;
@@ -4130,7 +4287,7 @@ var QueryBuilder = class QueryBuilder {
 		const relationCache = /* @__PURE__ */ new WeakMap();
 		const rows = await this.delegate.findMany(this.buildFindArgs());
 		const normalizedRows = this.randomOrderEnabled ? this.shuffleRows(rows) : rows;
-		const models = this.model.hydrateMany(normalizedRows);
+		const models = await this.model.hydrateManyRetrieved(normalizedRows);
 		let filteredModels = models;
 		if (this.hasRelationFilters()) if (this.hasOrRelationFilters() && this.args.where) {
 			const baseIds = new Set(models.map((model) => this.getModelId(model)).filter((id) => id != null));
@@ -4160,13 +4317,13 @@ var QueryBuilder = class QueryBuilder {
 			if (rows.length === 0) return null;
 			const row = this.shuffleRows(rows)[0];
 			if (!row) return null;
-			const model = this.model.hydrate(row);
+			const model = await this.model.hydrateRetrieved(row);
 			await model.load(this.eagerLoads);
 			return model;
 		}
 		const row = await this.delegate.findFirst(this.buildFindArgs());
 		if (!row) return null;
-		const model = this.model.hydrate(row);
+		const model = await this.model.hydrateRetrieved(row);
 		await model.load(this.eagerLoads);
 		return model;
 	}
@@ -4186,7 +4343,10 @@ var QueryBuilder = class QueryBuilder {
 	async findOr(value, keyOrCallback, maybeCallback) {
 		const key = typeof keyOrCallback === "string" ? keyOrCallback : "id";
 		const callback = typeof keyOrCallback === "function" ? keyOrCallback : maybeCallback;
-		if (!callback) throw new ArkormException("findOr requires a fallback callback.");
+		if (!callback) throw new QueryConstraintException("findOr requires a fallback callback.", {
+			operation: "findOr",
+			model: this.model.name
+		});
 		const found = await this.find(value, key);
 		if (found) return found;
 		return callback();
@@ -4300,7 +4460,11 @@ var QueryBuilder = class QueryBuilder {
 	async insertGetId(values, sequence) {
 		const created = await this.delegate.create({ data: values });
 		const key = sequence ?? "id";
-		if (!(key in created)) throw new ArkormException(`Inserted record does not contain key [${key}].`);
+		if (!(key in created)) throw new UniqueConstraintResolutionException(`Inserted record does not contain key [${key}].`, {
+			operation: "insertGetId",
+			model: this.model.name,
+			meta: { key }
+		});
 		return created[key];
 	}
 	/**
@@ -4337,7 +4501,10 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async update(data) {
 		const where = this.buildWhere();
-		if (!where) throw new ArkormException("Update requires a where clause.");
+		if (!where) throw new QueryConstraintException("Update requires a where clause.", {
+			operation: "update",
+			model: this.model.name
+		});
 		const uniqueWhere = await this.resolveUniqueWhere(where);
 		const updated = await this.delegate.update({
 			where: uniqueWhere,
@@ -4353,7 +4520,10 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async updateFrom(data) {
 		const where = this.buildWhere();
-		if (!where) throw new ArkormException("Update requires a where clause.");
+		if (!where) throw new QueryConstraintException("Update requires a where clause.", {
+			operation: "updateFrom",
+			model: this.model.name
+		});
 		const delegate = this.delegate;
 		if (typeof delegate.updateMany === "function") {
 			const result = await delegate.updateMany({
@@ -4418,7 +4588,10 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async delete() {
 		const where = this.buildWhere();
-		if (!where) throw new ArkormException("Delete requires a where clause.");
+		if (!where) throw new QueryConstraintException("Delete requires a where clause.", {
+			operation: "delete",
+			model: this.model.name
+		});
 		const uniqueWhere = await this.resolveUniqueWhere(where);
 		const deleted = await this.delegate.delete({ where: uniqueWhere });
 		return this.model.hydrate(deleted);
@@ -4484,7 +4657,10 @@ var QueryBuilder = class QueryBuilder {
 			if (Array.isArray(source)) return source;
 		}
 		if (Array.isArray(source)) return source;
-		throw new ArkormException("insertUsing expects a query builder, array of records, or async resolver.");
+		throw new QueryConstraintException("insertUsing expects a query builder, array of records, or async resolver.", {
+			operation: "insertUsing",
+			model: this.model.name
+		});
 	}
 	/**
 	* Execute callback when no records exist.
@@ -4568,7 +4744,11 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	whereRaw(sql, bindings = []) {
 		const delegate = this.delegate;
-		if (typeof delegate.applyRawWhere !== "function") throw new ArkormException("Raw where clauses are not supported by the current adapter.");
+		if (typeof delegate.applyRawWhere !== "function") throw new UnsupportedAdapterFeatureException("Raw where clauses are not supported by the current adapter.", {
+			operation: "whereRaw",
+			model: this.model.name,
+			meta: { feature: "rawWhere" }
+		});
 		this.args.where = delegate.applyRawWhere(this.buildWhere(), sql, bindings);
 		return this;
 	}
@@ -4581,7 +4761,11 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	orWhereRaw(sql, bindings = []) {
 		const delegate = this.delegate;
-		if (typeof delegate.applyRawWhere !== "function") throw new ArkormException("Raw where clauses are not supported by the current adapter.");
+		if (typeof delegate.applyRawWhere !== "function") throw new UnsupportedAdapterFeatureException("Raw where clauses are not supported by the current adapter.", {
+			operation: "orWhereRaw",
+			model: this.model.name,
+			meta: { feature: "rawWhere" }
+		});
 		const rawWhere = delegate.applyRawWhere(void 0, sql, bindings);
 		return this.orWhere(rawWhere);
 	}
@@ -4594,15 +4778,14 @@ var QueryBuilder = class QueryBuilder {
 	* @param options
 	* @returns 
 	*/
-	async paginate(page = 1, perPage = 15, options = {}) {
+	async paginate(perPage = 15, page = void 0, options = {}) {
+		const currentPage = this.resolvePaginationPage(page, options);
 		if (this.hasRelationFilters() || this.hasRelationAggregates()) {
-			const currentPage = Math.max(1, page);
 			const pageSize = Math.max(1, perPage);
 			const rows = (await this.get()).all();
 			const start = (currentPage - 1) * pageSize;
 			return new LengthAwarePaginator(new ArkormCollection(rows.slice(start, start + pageSize)), rows.length, pageSize, currentPage, options);
 		}
-		const currentPage = Math.max(1, page);
 		const pageSize = Math.max(1, perPage);
 		const total = await this.count();
 		return new LengthAwarePaginator(await this.clone().skip((currentPage - 1) * pageSize).take(pageSize).get(), total, pageSize, currentPage, options);
@@ -4614,9 +4797,9 @@ var QueryBuilder = class QueryBuilder {
 	* @param page
 	* @returns
 	*/
-	async simplePaginate(perPage = 15, page = 1, options = {}) {
+	async simplePaginate(perPage = 15, page = void 0, options = {}) {
+		const currentPage = this.resolvePaginationPage(page, options);
 		if (this.hasRelationFilters() || this.hasRelationAggregates()) {
-			const currentPage = Math.max(1, page);
 			const pageSize = Math.max(1, perPage);
 			const rows = (await this.get()).all();
 			const start = (currentPage - 1) * pageSize;
@@ -4624,7 +4807,6 @@ var QueryBuilder = class QueryBuilder {
 			const hasMorePages = start + pageSize < rows.length;
 			return new Paginator(new ArkormCollection(pageRows), pageSize, currentPage, hasMorePages, options);
 		}
-		const currentPage = Math.max(1, page);
 		const pageSize = Math.max(1, perPage);
 		const items = await this.clone().skip((currentPage - 1) * pageSize).take(pageSize + 1).get();
 		const hasMorePages = items.all().length > pageSize;
@@ -4705,9 +4887,16 @@ var QueryBuilder = class QueryBuilder {
 	async resolveUniqueWhere(where) {
 		if (this.isUniqueWhere(where)) return where;
 		const row = await this.delegate.findFirst({ where });
-		if (!row) throw new ArkormException("Record not found for update/delete operation.");
+		if (!row) throw new ModelNotFoundException(this.model.name, "Record not found for update/delete operation.", {
+			operation: "resolveUniqueWhere",
+			meta: { where }
+		});
 		const record = row;
-		if (!Object.prototype.hasOwnProperty.call(record, "id")) throw new ArkormException("Unable to resolve a unique identifier for update/delete operation. Include an id in the query constraints.");
+		if (!Object.prototype.hasOwnProperty.call(record, "id")) throw new UniqueConstraintResolutionException("Unable to resolve a unique identifier for update/delete operation. Include an id in the query constraints.", {
+			operation: "resolveUniqueWhere",
+			model: this.model.name,
+			meta: { where }
+		});
 		return { id: record.id };
 	}
 	/**
@@ -4830,7 +5019,11 @@ var QueryBuilder = class QueryBuilder {
 		if (cached) return await cached;
 		const resolver = (async () => {
 			const relationMethod = model[relation];
-			if (typeof relationMethod !== "function") throw new ArkormException(`Relation [${relation}] is not defined on the model.`);
+			if (typeof relationMethod !== "function") throw new RelationResolutionException(`Relation [${relation}] is not defined on the model.`, {
+				operation: "resolveRelatedResults",
+				model: this.model.name,
+				relation
+			});
 			const relationInstance = relationMethod.call(model);
 			if (callback && typeof relationInstance.constrain === "function") relationInstance.constrain((query) => {
 				return callback(query) ?? query;
@@ -4845,7 +5038,11 @@ var QueryBuilder = class QueryBuilder {
 				if (results instanceof ArkormCollection) return results.all();
 				return results;
 			}
-			throw new ArkormException(`Relation [${relation}] does not support result resolution.`);
+			throw new RelationResolutionException(`Relation [${relation}] does not support result resolution.`, {
+				operation: "resolveRelatedResults",
+				model: this.model.name,
+				relation
+			});
 		})();
 		callbackMap.set(callbackCacheKey, resolver);
 		return await resolver;
@@ -4886,6 +5083,8 @@ var QueryBuilder = class QueryBuilder {
 * @since 0.1.0
 */
 var Model = class Model {
+	static lifecycleStates = /* @__PURE__ */ new WeakMap();
+	static eventsSuppressed = 0;
 	static factoryClass;
 	static client;
 	static delegate;
@@ -4893,6 +5092,7 @@ var Model = class Model {
 	static deletedAtColumn = "deletedAt";
 	static globalScopes = {};
 	static eventListeners = {};
+	static dispatchesEvents = {};
 	casts = {};
 	hidden = [];
 	visible = [];
@@ -4930,7 +5130,11 @@ var Model = class Model {
 	}
 	static factory(count) {
 		const factoryClass = this.factoryClass;
-		if (!factoryClass) throw new ArkormException(`Factory is not configured for model [${this.name}].`);
+		if (!factoryClass) throw new ArkormException(`Factory is not configured for model [${this.name}].`, {
+			code: "FACTORY_NOT_CONFIGURED",
+			operation: "factory",
+			model: this.name
+		});
 		const factory = new factoryClass();
 		if (typeof count === "number") factory.count(count);
 		return factory;
@@ -4946,6 +5150,21 @@ var Model = class Model {
 		this.globalScopes[name] = scope;
 	}
 	/**
+	* Execute a callback without applying global scopes for the current model class.
+	*
+	* @param callback
+	* @returns
+	*/
+	static async withoutGlobalScopes(callback) {
+		const state = Model.getLifecycleState(this);
+		state.globalScopesSuppressed += 1;
+		try {
+			return await callback();
+		} finally {
+			state.globalScopesSuppressed = Math.max(0, state.globalScopesSuppressed - 1);
+		}
+	}
+	/**
 	* Remove a global scope by name.
 	*
 	* @param name
@@ -4967,11 +5186,60 @@ var Model = class Model {
 	* @param listener
 	*/
 	static on(event, listener) {
+		Model.ensureModelBooted(this);
 		this.ensureOwnEventListeners();
 		if (!this.eventListeners[event]) this.eventListeners[event] = [];
 		this.eventListeners[event]?.push(listener);
 	}
 	/**
+	* Register a model lifecycle callback listener.
+	*
+	* @param event
+	* @param listener
+	*/
+	static event(event, listener) {
+		this.on(event, listener);
+	}
+	static retrieved(listener) {
+		this.event("retrieved", listener);
+	}
+	static saving(listener) {
+		this.event("saving", listener);
+	}
+	static saved(listener) {
+		this.event("saved", listener);
+	}
+	static creating(listener) {
+		this.event("creating", listener);
+	}
+	static created(listener) {
+		this.event("created", listener);
+	}
+	static updating(listener) {
+		this.event("updating", listener);
+	}
+	static updated(listener) {
+		this.event("updated", listener);
+	}
+	static deleting(listener) {
+		this.event("deleting", listener);
+	}
+	static deleted(listener) {
+		this.event("deleted", listener);
+	}
+	static restoring(listener) {
+		this.event("restoring", listener);
+	}
+	static restored(listener) {
+		this.event("restored", listener);
+	}
+	static forceDeleting(listener) {
+		this.event("forceDeleting", listener);
+	}
+	static forceDeleted(listener) {
+		this.event("forceDeleted", listener);
+	}
+	/**
 	* Remove listeners for an event. If listener is omitted, all listeners for that event are removed.
 	*
 	* @param event
@@ -4992,6 +5260,34 @@ var Model = class Model {
 		this.eventListeners = {};
 	}
 	/**
+	* Execute a callback while suppressing lifecycle events for all models.
+	*
+	* @param callback
+	* @returns
+	*/
+	static async withoutEvents(callback) {
+		Model.eventsSuppressed += 1;
+		try {
+			return await callback();
+		} finally {
+			Model.eventsSuppressed = Math.max(0, Model.eventsSuppressed - 1);
+		}
+	}
+	/**
+	* Execute a callback within a transaction scope.
+	* Nested calls reuse the active transaction client.
+	*
+	* @param callback
+	* @param options
+	* @returns
+	*/
+	static async transaction(callback, options = {}) {
+		ensureArkormConfigLoading();
+		return await runArkormTransaction(async (client) => {
+			return await callback(client);
+		}, options);
+	}
+	/**
 	* Get the Prisma delegate for the model. 
 	* If a delegate name is provided, it will attempt to resolve that delegate. 
 	* Otherwise, it will attempt to resolve a delegate based on the model's name or 
@@ -5009,9 +5305,20 @@ var Model = class Model {
 			`${str(key).singular()}`,
 			`${str(key).camel().singular()}`
 		];
+		const activeTransactionClient = getActiveTransactionClient();
 		const runtimeClient = getRuntimePrismaClient();
-		const resolved = candidates.map((name) => this.client?.[name] ?? runtimeClient?.[name]).find((candidate) => isDelegateLike(candidate));
-		if (!resolved) throw new ArkormException(`Database delegate [${key}] is not configured.`);
+		const sources = activeTransactionClient ? [
+			activeTransactionClient,
+			this.client,
+			runtimeClient
+		] : [this.client, runtimeClient];
+		const resolved = candidates.flatMap((name) => sources.map((source) => source?.[name])).find((candidate) => isDelegateLike(candidate));
+		if (!resolved) throw new MissingDelegateException(`Database delegate [${key}] is not configured.`, {
+			operation: "getDelegate",
+			model: this.name,
+			delegate: key,
+			meta: { candidates }
+		});
 		return resolved;
 	}
 	/**
@@ -5021,16 +5328,27 @@ var Model = class Model {
 	* @returns 
 	*/
 	static query() {
+		Model.ensureModelBooted(this);
 		let builder = new QueryBuilder(this.getDelegate(), this);
 		const modelClass = this;
-		modelClass.ensureOwnGlobalScopes();
-		Object.values(modelClass.globalScopes).forEach((scope) => {
-			const scoped = scope(builder);
-			if (scoped && scoped !== builder) builder = scoped;
-		});
+		if (!Model.areGlobalScopesSuppressed(modelClass)) {
+			modelClass.ensureOwnGlobalScopes();
+			Object.values(modelClass.globalScopes).forEach((scope) => {
+				const scoped = scope(builder);
+				if (scoped && scoped !== builder) builder = scoped;
+			});
+		}
 		return builder;
 	}
 	/**
+	* Boot hook for subclasses to register scopes or perform one-time setup.
+	*/
+	static boot() {}
+	/**
+	* Booted hook for subclasses to register callbacks after boot logic runs.
+	*/
+	static booted() {}
+	/**
 	* Get a query builder instance that includes soft-deleted records.
 	* 
 	* @param this 
@@ -5093,6 +5411,36 @@ var Model = class Model {
 	static hydrateMany(attributes) {
 		return attributes.map((attribute) => new this(attribute));
 	}
+	/**
+	* Hydrate a model instance and dispatch the retrieved lifecycle event.
+	*
+	* @param this
+	* @param attributes
+	* @returns
+	*/
+	static async hydrateRetrieved(attributes) {
+		Model.ensureModelBooted(this);
+		if (!Model.hasEventListeners(this, "retrieved")) return this.hydrate(attributes);
+		const model = this.hydrate(attributes);
+		await Model.dispatchEvent(this, "retrieved", model);
+		return model;
+	}
+	/**
+	* Hydrate multiple model instances and dispatch the retrieved lifecycle event for each.
+	*
+	* @param this
+	* @param attributes
+	* @returns
+	*/
+	static async hydrateManyRetrieved(attributes) {
+		Model.ensureModelBooted(this);
+		if (!Model.hasEventListeners(this, "retrieved")) return this.hydrateMany(attributes);
+		const models = this.hydrateMany(attributes);
+		await Promise.all(models.map(async (model) => {
+			await Model.dispatchEvent(this, "retrieved", model);
+		}));
+		return models;
+	}
 	fill(attributes) {
 		Object.entries(attributes).forEach(([key, value]) => {
 			this.setAttribute(key, value);
@@ -5149,6 +5497,14 @@ var Model = class Model {
 		return this;
 	}
 	/**
+	* Save the model without dispatching lifecycle events.
+	*
+	* @returns
+	*/
+	async saveQuietly() {
+		return await Model.withoutEvents(() => this.save());
+	}
+	/**
 	* Delete the model from the database. 
 	* If soft deletes are enabled, it will perform a soft delete by 
 	* setting the deleted at column to the current date. 
@@ -5174,6 +5530,14 @@ var Model = class Model {
 		return this;
 	}
 	/**
+	* Delete the model without dispatching lifecycle events.
+	*
+	* @returns
+	*/
+	async deleteQuietly() {
+		return await Model.withoutEvents(() => this.delete());
+	}
+	/**
 	* Permanently delete the model from the database, regardless of whether soft 
 	* deletes are enabled.
 	* 
@@ -5192,6 +5556,14 @@ var Model = class Model {
 		return this;
 	}
 	/**
+	* Force delete the model without dispatching lifecycle events.
+	*
+	* @returns
+	*/
+	async forceDeleteQuietly() {
+		return await Model.withoutEvents(() => this.forceDelete());
+	}
+	/**
 	* Restore a soft-deleted model by setting the deleted at column to null.
 	* 
 	* @returns 
@@ -5209,6 +5581,14 @@ var Model = class Model {
 		return this;
 	}
 	/**
+	* Restore the model without dispatching lifecycle events.
+	*
+	* @returns
+	*/
+	async restoreQuietly() {
+		return await Model.withoutEvents(() => this.restore());
+	}
+	/**
 	* Load related models onto the current model instance.
 	* 
 	* @param relations 
@@ -5261,6 +5641,47 @@ var Model = class Model {
 		return this.toObject();
 	}
 	/**
+	* Determine if another model represents the same persisted record.
+	*
+	* @param model
+	* @returns
+	*/
+	is(model) {
+		if (!(model instanceof Model)) return false;
+		if (this.constructor !== model.constructor) return false;
+		const identifier = this.getAttribute("id");
+		const otherIdentifier = model.getAttribute("id");
+		if (identifier == null || otherIdentifier == null) return false;
+		return identifier === otherIdentifier;
+	}
+	/**
+	* Determine if another model does not represent the same persisted record.
+	*
+	* @param model
+	* @returns
+	*/
+	isNot(model) {
+		return !this.is(model);
+	}
+	/**
+	* Determine if another model is the same in-memory instance.
+	*
+	* @param model
+	* @returns
+	*/
+	isSame(model) {
+		return this === model;
+	}
+	/**
+	* Determine if another model is not the same in-memory instance.
+	*
+	* @param model
+	* @returns
+	*/
+	isNotSame(model) {
+		return !this.isSame(model);
+	}
+	/**
 	* Define a has one relationship.
 	* 
 	* @param related 
@@ -5424,6 +5845,84 @@ var Model = class Model {
 		if (!Object.prototype.hasOwnProperty.call(this, "eventListeners")) this.eventListeners = { ...this.eventListeners || {} };
 	}
 	/**
+	* Resolve lifecycle state for the provided model class.
+	*
+	* @param modelClass
+	* @returns
+	*/
+	static getLifecycleState(modelClass) {
+		const existing = Model.lifecycleStates.get(modelClass);
+		if (existing) return existing;
+		const state = {
+			booted: false,
+			booting: false,
+			globalScopesSuppressed: 0
+		};
+		Model.lifecycleStates.set(modelClass, state);
+		return state;
+	}
+	/**
+	* Ensure the target model class has executed its boot lifecycle.
+	*
+	* @param modelClass
+	*/
+	static ensureModelBooted(modelClass) {
+		const state = Model.getLifecycleState(modelClass);
+		if (state.booted || state.booting) return;
+		state.booting = true;
+		try {
+			const boot = modelClass.boot;
+			if (boot !== Model.boot) boot.call(modelClass);
+			const booted = modelClass.booted;
+			if (booted !== Model.booted) booted.call(modelClass);
+			state.booted = true;
+		} finally {
+			state.booting = false;
+		}
+	}
+	/**
+	* Determine if global scopes are currently suppressed for the model class.
+	*
+	* @param modelClass
+	* @returns
+	*/
+	static areGlobalScopesSuppressed(modelClass) {
+		return Model.getLifecycleState(modelClass).globalScopesSuppressed > 0;
+	}
+	/**
+	* Resolve configured class-based event handlers for a lifecycle event.
+	*
+	* @param modelClass
+	* @param event
+	* @returns
+	*/
+	static resolveDispatchedEventListeners(modelClass, event) {
+		const configured = modelClass.dispatchesEvents[event];
+		if (!configured) return [];
+		return (Array.isArray(configured) ? configured : [configured]).map((entry) => {
+			const handler = typeof entry === "function" ? new entry() : entry;
+			if (!handler || typeof handler.handle !== "function") throw new ArkormException(`Invalid event handler configured for [${modelClass.name}.${event}].`);
+			return async (model) => {
+				await handler.handle(model);
+			};
+		});
+	}
+	/**
+	* Determine whether a lifecycle event has any registered listeners.
+	*
+	* @param modelClass
+	* @param event
+	* @returns
+	*/
+	static hasEventListeners(modelClass, event) {
+		if (Model.eventsSuppressed > 0) return false;
+		modelClass.ensureOwnEventListeners();
+		if ((modelClass.eventListeners[event] || []).length > 0) return true;
+		const configuredDispatchers = modelClass.dispatchesEvents[event];
+		if (!configuredDispatchers) return false;
+		return Array.isArray(configuredDispatchers) ? configuredDispatchers.length > 0 : true;
+	}
+	/**
 	* Dispatches lifecycle events to registered listeners.
 	*
 	* @param modelClass
@@ -5431,8 +5930,9 @@ var Model = class Model {
 	* @param model
 	*/
 	static async dispatchEvent(modelClass, event, model) {
-		modelClass.ensureOwnEventListeners();
-		const listeners = modelClass.eventListeners[event] || [];
+		Model.ensureModelBooted(modelClass);
+		if (!Model.hasEventListeners(modelClass, event)) return;
+		const listeners = [...Model.resolveDispatchedEventListeners(modelClass, event), ...modelClass.eventListeners[event] || []];
 		for (const listener of listeners) await listener(model);
 	}
 	/**
@@ -5452,4 +5952,4 @@ var Model = class Model {
 };
 
 //#endregion
-export { ArkormCollection, ArkormException, Attribute, CliApp, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, QueryBuilder, SEEDER_BRAND, SchemaBuilder, SeedCommand, Seeder, TableBuilder, URLDriver, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findModelBlock, formatDefaultValue, formatRelationAction, generateMigrationFile, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };
+export { ArkormCollection, ArkormException, Attribute, CliApp, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, MissingDelegateException, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, QueryBuilder, QueryConstraintException, RelationResolutionException, SEEDER_BRAND, SchemaBuilder, ScopeNotDefinedException, SeedCommand, Seeder, TableBuilder, URLDriver, UniqueConstraintResolutionException, UnsupportedAdapterFeatureException, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findModelBlock, formatDefaultValue, formatRelationAction, generateMigrationFile, getActiveTransactionClient, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, isTransactionCapableClient, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runArkormTransaction, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };