arkormx 0.2.11 → 1.1.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 = () => {
@@ -1247,6 +1286,7 @@ let runtimeConfigLoadingPromise;
 let runtimeClientResolver;
 let runtimePaginationURLDriverFactory;
 let runtimePaginationCurrentPageResolver;
+const transactionClientStorage = new AsyncLocalStorage();
 const mergePathConfig = (paths) => {
 	const defaults = baseConfig.paths ?? {};
 	const current = userConfig.paths ?? {};
@@ -1414,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.
 *
@@ -2772,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
 /**
@@ -2783,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;
 	}
@@ -2793,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
 /**
@@ -3033,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();
 	}
 };
@@ -3119,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();
 	}
 };
@@ -3276,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();
 	}
 };
@@ -4027,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;
@@ -4149,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));
@@ -4179,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;
 	}
@@ -4205,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();
@@ -4319,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];
 	}
 	/**
@@ -4356,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,
@@ -4372,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({
@@ -4437,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);
@@ -4503,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.
@@ -4587,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;
 	}
@@ -4600,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);
 	}
@@ -4722,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 };
 	}
 	/**
@@ -4847,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;
@@ -4862,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;
@@ -4903,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;
@@ -4910,13 +5092,20 @@ var Model = class Model {
 	static deletedAtColumn = "deletedAt";
 	static globalScopes = {};
 	static eventListeners = {};
+	static dispatchesEvents = {};
 	casts = {};
 	hidden = [];
 	visible = [];
 	appends = [];
 	attributes;
+	original;
+	changes;
+	touchedAttributes;
 	constructor(attributes = {}) {
 		this.attributes = {};
+		this.original = {};
+		this.changes = {};
+		this.touchedAttributes = /* @__PURE__ */ new Set();
 		this.fill(attributes);
 		return new Proxy(this, {
 			get: (target, key, receiver) => {
@@ -4947,7 +5136,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;
@@ -4963,6 +5156,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
@@ -4984,11 +5192,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
@@ -5009,6 +5266,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 
@@ -5026,9 +5311,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;
 	}
 	/**
@@ -5038,16 +5334,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 
@@ -5098,7 +5405,10 @@ var Model = class Model {
 	* @returns 
 	*/
 	static hydrate(attributes) {
-		return new this(attributes);
+		const model = new this(attributes);
+		model.syncOriginal();
+		model.syncChanges({});
+		return model;
 	}
 	/**
 	* Hydrate multiple model instances from an array of plain objects of attributes.
@@ -5110,6 +5420,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);
@@ -5135,6 +5475,7 @@ var Model = class Model {
 		else if (mutator) resolved = mutator.call(this, resolved);
 		if (cast) resolved = resolveCast(cast).set(resolved);
 		this.attributes[key] = resolved;
+		this.touchedAttributes.add(key);
 		return this;
 	}
 	/**
@@ -5147,12 +5488,15 @@ var Model = class Model {
 	async save() {
 		const identifier = this.getAttribute("id");
 		const payload = this.getRawAttributes();
+		const previousOriginal = this.getOriginal();
 		const constructor = this.constructor;
 		if (identifier == null) {
 			await Model.dispatchEvent(constructor, "saving", this);
 			await Model.dispatchEvent(constructor, "creating", this);
 			const model = await constructor.query().create(payload);
 			this.fill(model.getRawAttributes());
+			this.syncChanges(previousOriginal);
+			this.syncOriginal();
 			await Model.dispatchEvent(constructor, "created", this);
 			await Model.dispatchEvent(constructor, "saved", this);
 			return this;
@@ -5161,11 +5505,21 @@ var Model = class Model {
 		await Model.dispatchEvent(constructor, "updating", this);
 		const model = await constructor.query().where({ id: identifier }).update(payload);
 		this.fill(model.getRawAttributes());
+		this.syncChanges(previousOriginal);
+		this.syncOriginal();
 		await Model.dispatchEvent(constructor, "updated", this);
 		await Model.dispatchEvent(constructor, "saved", this);
 		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. 
@@ -5176,21 +5530,34 @@ var Model = class Model {
 	async delete() {
 		const identifier = this.getAttribute("id");
 		if (identifier == null) throw new ArkormException("Cannot delete a model without an id.");
+		const previousOriginal = this.getOriginal();
 		const constructor = this.constructor;
 		await Model.dispatchEvent(constructor, "deleting", this);
 		const softDeleteConfig = constructor.getSoftDeleteConfig();
 		if (softDeleteConfig.enabled) {
 			const model = await constructor.query().where({ id: identifier }).update({ [softDeleteConfig.column]: /* @__PURE__ */ new Date() });
 			this.fill(model.getRawAttributes());
+			this.syncChanges(previousOriginal);
+			this.syncOriginal();
 			await Model.dispatchEvent(constructor, "deleted", this);
 			return this;
 		}
 		const deleted = await constructor.query().where({ id: identifier }).delete();
 		this.fill(deleted.getRawAttributes());
+		this.syncChanges(previousOriginal);
+		this.syncOriginal();
 		await Model.dispatchEvent(constructor, "deleted", this);
 		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.
 	* 
@@ -5199,16 +5566,27 @@ var Model = class Model {
 	async forceDelete() {
 		const identifier = this.getAttribute("id");
 		if (identifier == null) throw new ArkormException("Cannot force delete a model without an id.");
+		const previousOriginal = this.getOriginal();
 		const constructor = this.constructor;
 		await Model.dispatchEvent(constructor, "forceDeleting", this);
 		await Model.dispatchEvent(constructor, "deleting", this);
 		const deleted = await constructor.query().withTrashed().where({ id: identifier }).delete();
 		this.fill(deleted.getRawAttributes());
+		this.syncChanges(previousOriginal);
+		this.syncOriginal();
 		await Model.dispatchEvent(constructor, "deleted", this);
 		await Model.dispatchEvent(constructor, "forceDeleted", this);
 		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 
@@ -5219,13 +5597,24 @@ var Model = class Model {
 		const constructor = this.constructor;
 		const softDeleteConfig = constructor.getSoftDeleteConfig();
 		if (!softDeleteConfig.enabled) return this;
+		const previousOriginal = this.getOriginal();
 		await Model.dispatchEvent(constructor, "restoring", this);
 		const model = await constructor.query().withTrashed().where({ id: identifier }).update({ [softDeleteConfig.column]: null });
 		this.fill(model.getRawAttributes());
+		this.syncChanges(previousOriginal);
+		this.syncOriginal();
 		await Model.dispatchEvent(constructor, "restored", this);
 		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 
@@ -5251,6 +5640,42 @@ var Model = class Model {
 	getRawAttributes() {
 		return { ...this.attributes };
 	}
+	getOriginal(key) {
+		if (typeof key === "string") return Model.cloneAttributeValue(this.original[key]);
+		return Object.entries(this.original).reduce((all, [originalKey, value]) => {
+			all[originalKey] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+	}
+	/**
+	* Determine whether the model has unsaved attribute changes.
+	*
+	* @param keys
+	* @returns
+	*/
+	isDirty(keys) {
+		return Object.keys(this.getDirtyAttributes(keys)).length > 0;
+	}
+	/**
+	* Determine whether the model has no unsaved attribute changes.
+	*
+	* @param keys
+	* @returns
+	*/
+	isClean(keys) {
+		return !this.isDirty(keys);
+	}
+	/**
+	* Determine whether the model changed during the last successful persistence operation.
+	*
+	* @param keys
+	* @returns
+	*/
+	wasChanged(keys) {
+		const keyList = this.normalizeAttributeKeys(keys);
+		if (keyList.length === 0) return Object.keys(this.changes).length > 0;
+		return keyList.some((key) => Object.prototype.hasOwnProperty.call(this.changes, key));
+	}
 	/**
 	* Convert the model instance to a plain object, applying visibility 
 	* rules, appends, and mutators.
@@ -5278,6 +5703,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 
@@ -5400,6 +5866,34 @@ var Model = class Model {
 		return typeof method === "function" ? method : null;
 	}
 	/**
+	* Build a map of dirty attributes, optionally limited to specific keys.
+	*
+	* @param keys
+	* @returns
+	*/
+	getDirtyAttributes(keys) {
+		const requestedKeys = this.normalizeAttributeKeys(keys);
+		return (requestedKeys.length > 0 ? requestedKeys : Array.from(new Set([...Object.keys(this.original), ...this.touchedAttributes]))).reduce((dirty, key) => {
+			const currentValue = this.attributes[key];
+			const originalValue = this.original[key];
+			const hasCurrent = Object.prototype.hasOwnProperty.call(this.attributes, key);
+			const hasOriginal = Object.prototype.hasOwnProperty.call(this.original, key);
+			if (!hasCurrent && !hasOriginal) return dirty;
+			if (hasCurrent !== hasOriginal || !Model.areAttributeValuesEqual(currentValue, originalValue)) dirty[key] = Model.cloneAttributeValue(currentValue);
+			return dirty;
+		}, {});
+	}
+	/**
+	* Normalize a key or key list for dirty/change lookups.
+	*
+	* @param keys
+	* @returns
+	*/
+	normalizeAttributeKeys(keys) {
+		if (typeof keys === "undefined") return [];
+		return Array.isArray(keys) ? keys : [keys];
+	}
+	/**
 	* Resolve an Attribute object mutator method for a given key, if it exists.
 	*
 	* @param key
@@ -5441,6 +5935,144 @@ var Model = class Model {
 		if (!Object.prototype.hasOwnProperty.call(this, "eventListeners")) this.eventListeners = { ...this.eventListeners || {} };
 	}
 	/**
+	* Clone an attribute value to keep snapshot state isolated from live mutations.
+	*
+	* @param value
+	* @returns
+	*/
+	static cloneAttributeValue(value) {
+		if (value instanceof Date) return new Date(value.getTime());
+		if (Array.isArray(value)) return value.map((item) => Model.cloneAttributeValue(item));
+		if (value && typeof value === "object") return Object.entries(value).reduce((all, [key, nestedValue]) => {
+			all[key] = Model.cloneAttributeValue(nestedValue);
+			return all;
+		}, {});
+		return value;
+	}
+	/**
+	* Compare attribute values for dirty/change detection.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static areAttributeValuesEqual(left, right) {
+		if (left === right) return true;
+		if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+		if (Array.isArray(left) && Array.isArray(right)) {
+			if (left.length !== right.length) return false;
+			return left.every((value, index) => Model.areAttributeValuesEqual(value, right[index]));
+		}
+		if (left && right && typeof left === "object" && typeof right === "object") {
+			const leftEntries = Object.entries(left);
+			const rightEntries = Object.entries(right);
+			if (leftEntries.length !== rightEntries.length) return false;
+			return leftEntries.every(([key, value]) => {
+				return Object.prototype.hasOwnProperty.call(right, key) && Model.areAttributeValuesEqual(value, right[key]);
+			});
+		}
+		return false;
+	}
+	/**
+	* Sync the original snapshot to the model's current raw attributes.
+	*/
+	syncOriginal() {
+		this.original = Object.entries(this.attributes).reduce((all, [key, value]) => {
+			all[key] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+		this.touchedAttributes.clear();
+	}
+	/**
+	* Sync the last-changed snapshot from a previous original state.
+	*
+	* @param previousOriginal
+	*/
+	syncChanges(previousOriginal) {
+		this.changes = Object.entries(this.getDirtyAttributes()).reduce((all, [key, value]) => {
+			if (!Object.prototype.hasOwnProperty.call(previousOriginal, key) || !Model.areAttributeValuesEqual(value, previousOriginal[key])) all[key] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+	}
+	/**
+	* 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
@@ -5448,8 +6080,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);
 	}
 	/**
@@ -5469,4 +6102,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, getRuntimePaginationCurrentPageResolver, 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 };