arkormx 1.0.0 → 1.2.0

package/dist/index.mjs

@@ -209,6 +209,95 @@ var ForeignKeyBuilder = class {
 
 //#endregion
 //#region src/database/TableBuilder.ts
+const PRISMA_ENUM_MEMBER_REGEX$1 = /^[A-Za-z][A-Za-z0-9_]*$/;
+const normalizeEnumMember = (columnName, value) => {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`Enum column [${columnName}] must define only non-empty values.`);
+	if (!PRISMA_ENUM_MEMBER_REGEX$1.test(normalized)) throw new Error(`Enum column [${columnName}] contains invalid Prisma enum value [${normalized}].`);
+	return normalized;
+};
+const normalizeEnumMembers = (columnName, values) => {
+	const normalizedValues = values.map((value) => normalizeEnumMember(columnName, value));
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of normalizedValues) {
+		if (seen.has(value)) throw new Error(`Enum column [${columnName}] contains duplicate enum value [${value}].`);
+		seen.add(value);
+	}
+	return normalizedValues;
+};
+/**
+* The EnumBuilder class provides a fluent interface for configuring enum columns
+* after they are defined on a table.
+*
+* @author Legacy (3m1n3nc3)
+* @since 0.2.3
+*/
+var EnumBuilder = class {
+	tableBuilder;
+	columnName;
+	constructor(tableBuilder, columnName) {
+		this.tableBuilder = tableBuilder;
+		this.columnName = columnName;
+	}
+	/**
+	* Defines the Prisma enum name for this column.
+	*
+	* @param name
+	* @returns
+	*/
+	enumName(name) {
+		this.tableBuilder.enumName(name, this.columnName);
+		return this;
+	}
+	/**
+	* Marks the enum column as nullable.
+	*
+	* @returns
+	*/
+	nullable() {
+		this.tableBuilder.nullable(this.columnName);
+		return this;
+	}
+	/**
+	* Marks the enum column as unique.
+	*
+	* @returns
+	*/
+	unique() {
+		this.tableBuilder.unique(this.columnName);
+		return this;
+	}
+	/**
+	* Sets a default value for the enum column.
+	*
+	* @param value
+	* @returns
+	*/
+	default(value) {
+		this.tableBuilder.default(value, this.columnName);
+		return this;
+	}
+	/**
+	* Positions the enum column after another column when supported.
+	*
+	* @param referenceColumn
+	* @returns
+	*/
+	after(referenceColumn) {
+		this.tableBuilder.after(referenceColumn, this.columnName);
+		return this;
+	}
+	/**
+	* Maps the enum column to a custom database column name.
+	*
+	* @param name
+	* @returns
+	*/
+	map(name) {
+		this.tableBuilder.map(name, this.columnName);
+		return this;
+	}
+};
 /**
 * The TableBuilder class provides a fluent interface for defining 
 * the structure of a database table in a migration, including columns to add or drop.
@@ -261,6 +350,27 @@ var TableBuilder = class {
 		return this.column(name, "uuid", options);
 	}
 	/**
+	* Defines an enum column in the table.
+	*
+	* @param name      The name of the enum column.
+	* @param values    Either an array of string values for the enum or the name of an existing enum to reuse.
+	* @param options   Additional options for the enum column.
+	* @returns
+	*/
+	enum(name, valuesOrEnumName, options = {}) {
+		const isEnumReuse = typeof valuesOrEnumName === "string";
+		if (!isEnumReuse && valuesOrEnumName.length === 0) throw new Error(`Enum column [${name}] must define at least one value.`);
+		const normalizedEnumValues = isEnumReuse ? void 0 : normalizeEnumMembers(name, valuesOrEnumName);
+		const enumName = isEnumReuse ? valuesOrEnumName.trim() : options.enumName?.trim();
+		if (isEnumReuse && !enumName) throw new Error(`Enum column [${name}] must define an enum name.`);
+		this.column(name, "enum", {
+			...options,
+			enumName,
+			enumValues: normalizedEnumValues
+		});
+		return new EnumBuilder(this, name);
+	}
+	/**
 	* Defines a string column in the table.
 	* 
 	* @param name      The name of the string column.
@@ -430,6 +540,21 @@ var TableBuilder = class {
 		return this;
 	}
 	/**
+	* Sets the Prisma enum name for an enum column.
+	*
+	* @param name       The enum name to assign.
+	* @param columnName Optional explicit target column name. When omitted, applies to the latest defined column.
+	* @returns          The current TableBuilder instance for chaining.
+	*/
+	enumName(name, columnName) {
+		const column = this.resolveColumn(columnName);
+		if (column.type !== "enum") throw new Error(`Column [${column.name}] is not an enum column.`);
+		const enumName = name.trim();
+		if (!enumName) throw new Error(`Enum column [${column.name}] must define an enum name.`);
+		column.enumName = enumName;
+		return this;
+	}
+	/**
 	* Sets a default value for a column.
 	*
 	* @param value      The default scalar value or Prisma expression (e.g. 'now()').
@@ -512,7 +637,10 @@ var TableBuilder = class {
 	* @returns 
 	*/
 	getColumns() {
-		return this.columns.map((column) => ({ ...column }));
+		return this.columns.map((column) => ({
+			...column,
+			enumValues: column.enumValues ? [...column.enumValues] : void 0
+		}));
 	}
 	/**
 	* Returns a copy of the defined column names to be dropped from the table.
@@ -553,6 +681,8 @@ var TableBuilder = class {
 		this.columns.push({
 			name,
 			type,
+			enumName: options.enumName,
+			enumValues: options.enumValues ? [...options.enumValues] : void 0,
 			map: options.map,
 			nullable: options.nullable,
 			unique: options.unique,
@@ -652,7 +782,10 @@ var SchemaBuilder = class {
 		return this.operations.map((operation) => {
 			if (operation.type === "createTable") return {
 				...operation,
-				columns: operation.columns.map((column) => ({ ...column })),
+				columns: operation.columns.map((column) => ({
+					...column,
+					enumValues: column.enumValues ? [...column.enumValues] : void 0
+				})),
 				indexes: operation.indexes.map((index) => ({
 					...index,
 					columns: [...index.columns]
@@ -661,7 +794,10 @@ var SchemaBuilder = class {
 			};
 			if (operation.type === "alterTable") return {
 				...operation,
-				addColumns: operation.addColumns.map((column) => ({ ...column })),
+				addColumns: operation.addColumns.map((column) => ({
+					...column,
+					enumValues: column.enumValues ? [...column.enumValues] : void 0
+				})),
 				dropColumns: [...operation.dropColumns],
 				addIndexes: operation.addIndexes.map((index) => ({
 					...index,
@@ -677,6 +813,8 @@ var SchemaBuilder = class {
 //#endregion
 //#region src/helpers/migrations.ts
 const PRISMA_MODEL_REGEX = /model\s+(\w+)\s*\{[\s\S]*?\n\}/g;
+const PRISMA_ENUM_REGEX = /enum\s+(\w+)\s*\{[\s\S]*?\n\}/g;
+const PRISMA_ENUM_MEMBER_REGEX = /^[A-Za-z][A-Za-z0-9_]*$/;
 /**
 * Convert a table name to a PascalCase model name, with basic singularization.
 * 
@@ -704,6 +842,7 @@ const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 */
 const resolvePrismaType = (column) => {
 	if (column.type === "id") return "Int";
+	if (column.type === "enum") return resolveEnumName(column);
 	if (column.type === "uuid") return "String";
 	if (column.type === "string" || column.type === "text") return "String";
 	if (column.type === "integer") return "Int";
@@ -713,6 +852,11 @@ const resolvePrismaType = (column) => {
 	if (column.type === "json") return "Json";
 	return "DateTime";
 };
+const resolveEnumName = (column) => {
+	if (column.type !== "enum") throw new ArkormException(`Column [${column.name}] is not an enum column.`);
+	if (column.enumName && column.enumName.trim().length > 0) return column.enumName.trim();
+	throw new ArkormException(`Enum column [${column.name}] must define an enum name.`);
+};
 /** 
 * Format a default value for inclusion in a Prisma schema field definition, based on its type.
 * 
@@ -727,6 +871,61 @@ const formatDefaultValue = (value) => {
 	if (typeof value === "boolean") return `@default(${value ? "true" : "false"})`;
 };
 /**
+* Format a default value for an enum column as a Prisma @default attribute, validating that it is a non-empty string.
+* 
+* @param value 
+* @returns 
+*/
+const formatEnumDefaultValue = (value) => {
+	if (value == null) return void 0;
+	if (typeof value !== "string" || value.trim().length === 0) throw new ArkormException("Enum default values must be provided as non-empty strings.");
+	return `@default(${value.trim()})`;
+};
+/**
+* Normalize an enum value by ensuring it is a non-empty string and trimming whitespace.
+* 
+* @param value 
+* @returns 
+*/
+const normalizeEnumValue = (value) => {
+	if (typeof value !== "string" || value.trim().length === 0) throw new ArkormException("Enum values must be provided as non-empty strings.");
+	const normalized = value.trim();
+	if (!PRISMA_ENUM_MEMBER_REGEX.test(normalized)) throw new ArkormException(`Enum value [${normalized}] is not a valid Prisma enum member name.`);
+	return normalized;
+};
+/**
+* Extract the enum values from a Prisma enum block string.
+* 
+* @param block 
+* @returns 
+*/
+const extractEnumBlockValues = (block) => {
+	return block.split("\n").slice(1, -1).map((line) => line.trim()).filter(Boolean);
+};
+const validateEnumValues = (column, enumName, enumValues) => {
+	const normalizedValues = enumValues.map(normalizeEnumValue);
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of normalizedValues) {
+		if (seen.has(value)) throw new ArkormException(`Prisma enum [${enumName}] for column [${column.name}] contains duplicate value [${value}].`);
+		seen.add(value);
+	}
+	return normalizedValues;
+};
+/**
+* Validate that a default value for an enum column is included in the defined enum values.
+* 
+* @param column 
+* @param enumName 
+* @param enumValues 
+* @returns 
+*/
+const validateEnumDefaultValue = (column, enumName, enumValues) => {
+	if (column.default == null) return;
+	const normalizedDefault = normalizeEnumValue(column.default);
+	if (enumValues.includes(normalizedDefault)) return;
+	throw new ArkormException(`Enum default value [${normalizedDefault}] is not defined in Prisma enum [${enumName}] for column [${column.name}].`);
+};
+/**
 * Build a single line of a Prisma model field definition based on a SchemaColumn, including type and modifiers.
 * 
 * @param column 
@@ -747,11 +946,82 @@ const buildFieldLine = (column) => {
 	const primary = column.primary ? " @id" : "";
 	const mapped = typeof column.map === "string" && column.map.trim().length > 0 ? ` @map("${column.map.replace(/"/g, "\\\"")}")` : "";
 	const updatedAt = column.updatedAt ? " @updatedAt" : "";
-	const defaultValue = formatDefaultValue(column.default) ?? (column.type === "uuid" && column.primary ? "@default(uuid())" : void 0);
+	const defaultValue = column.type === "enum" ? formatEnumDefaultValue(column.default) : formatDefaultValue(column.default) ?? (column.type === "uuid" && column.primary ? "@default(uuid())" : void 0);
 	const defaultSuffix = defaultValue ? ` ${defaultValue}` : "";
 	return `  ${column.name} ${scalar}${nullable}${primary}${unique}${defaultSuffix}${updatedAt}${mapped}`;
 };
 /**
+* Build a Prisma enum block string based on an enum name and its values, validating that 
+* at least one value is provided.
+* 
+* @param enumName      The name of the enum to create.
+* @param values        The array of values for the enum.
+* @returns             The Prisma enum block string.
+*/
+const buildEnumBlock = (enumName, values) => {
+	if (values.length === 0) throw new ArkormException(`Enum [${enumName}] must define at least one value.`);
+	return `enum ${enumName} {\n${values.map((value) => `  ${value}`).join("\n")}\n}`;
+};
+/**
+* Find the Prisma enum block in a schema string that corresponds to a given enum 
+* name, returning its details if found.
+* 
+* @param schema        The Prisma schema string to search for the enum block.
+* @param enumName      The name of the enum to find in the schema.
+* @returns 
+*/
+const findEnumBlock = (schema, enumName) => {
+	const candidates = [...schema.matchAll(PRISMA_ENUM_REGEX)];
+	for (const match of candidates) {
+		const block = match[0];
+		const matchedEnumName = match[1];
+		const start = match.index ?? 0;
+		const end = start + block.length;
+		if (matchedEnumName === enumName) return {
+			enumName: matchedEnumName,
+			block,
+			start,
+			end
+		};
+	}
+	return null;
+};
+/**
+* Ensure that Prisma enum blocks exist in the schema for any enum columns defined in a 
+* create or alter table operation, adding them if necessary and validating against 
+* existing blocks.
+* 
+* @param schema    The current Prisma schema string to check and modify.
+* @param columns   The array of schema column definitions to check for enum types and ensure corresponding blocks exist for.
+* @returns 
+*/
+const ensureEnumBlocks = (schema, columns) => {
+	let nextSchema = schema;
+	for (const column of columns) {
+		if (column.type !== "enum") continue;
+		const enumName = resolveEnumName(column);
+		const enumValues = column.enumValues ?? [];
+		const existing = findEnumBlock(nextSchema, enumName);
+		if (existing) {
+			const existingValues = validateEnumValues(column, enumName, extractEnumBlockValues(existing.block));
+			if (enumValues.length === 0) {
+				validateEnumDefaultValue(column, enumName, existingValues);
+				continue;
+			}
+			const normalizedEnumValues = validateEnumValues(column, enumName, enumValues);
+			if (existingValues.join("|") !== normalizedEnumValues.join("|")) throw new ArkormException(`Prisma enum [${enumName}] already exists with different values.`);
+			validateEnumDefaultValue(column, enumName, existingValues);
+			continue;
+		}
+		if (enumValues.length === 0) throw new ArkormException(`Prisma enum [${enumName}] was not found for column [${column.name}].`);
+		const normalizedEnumValues = validateEnumValues(column, enumName, enumValues);
+		validateEnumDefaultValue(column, enumName, normalizedEnumValues);
+		const block = buildEnumBlock(enumName, normalizedEnumValues);
+		nextSchema = `${nextSchema.trimEnd()}\n\n${block}\n`;
+	}
+	return nextSchema;
+};
+/**
 * Build a Prisma model-level @@index definition line.
 * 
 * @param index     The schema index definition to convert to a Prisma \@\@index line.
@@ -953,8 +1223,9 @@ const findModelBlock = (schema, table) => {
 */
 const applyCreateTableOperation = (schema, operation) => {
 	if (findModelBlock(schema, operation.table)) throw new ArkormException(`Prisma model for table [${operation.table}] already exists.`);
+	const schemaWithEnums = ensureEnumBlocks(schema, operation.columns);
 	const block = buildModelBlock(operation);
-	return applyInverseRelations(`${schema.trimEnd()}\n\n${block}\n`, toModelName(operation.table), operation.foreignKeys ?? []);
+	return applyInverseRelations(`${schemaWithEnums.trimEnd()}\n\n${block}\n`, toModelName(operation.table), operation.foreignKeys ?? []);
 };
 /**
 * Apply an alter table operation to a Prisma schema string, modifying the model 
@@ -967,7 +1238,10 @@ const applyCreateTableOperation = (schema, operation) => {
 const applyAlterTableOperation = (schema, operation) => {
 	const model = findModelBlock(schema, operation.table);
 	if (!model) throw new ArkormException(`Prisma model for table [${operation.table}] was not found.`);
-	let block = model.block;
+	const schemaWithEnums = ensureEnumBlocks(schema, operation.addColumns);
+	const refreshedModel = findModelBlock(schemaWithEnums, operation.table);
+	if (!refreshedModel) throw new ArkormException(`Prisma model for table [${operation.table}] was not found.`);
+	let block = refreshedModel.block;
 	const bodyLines = block.split("\n");
 	operation.dropColumns.forEach((column) => {
 		const columnRegex = new RegExp(`^\\s*${escapeRegex(column)}\\s+`);
@@ -997,7 +1271,7 @@ const applyAlterTableOperation = (schema, operation) => {
 		injectLineIntoModelBody(bodyLines, relationLine, (line) => relationRegex.test(line));
 	}
 	block = bodyLines.join("\n");
-	return applyInverseRelations(`${schema.slice(0, model.start)}${block}${schema.slice(model.end)}`, model.modelName, operation.addForeignKeys ?? []);
+	return applyInverseRelations(`${schemaWithEnums.slice(0, refreshedModel.start)}${block}${schemaWithEnums.slice(refreshedModel.end)}`, model.modelName, operation.addForeignKeys ?? []);
 };
 /**
 * Apply a drop table operation to a Prisma schema string, removing the model block
@@ -5098,8 +5372,14 @@ var Model = class Model {
 	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) => {
@@ -5399,7 +5679,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.
@@ -5466,6 +5749,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;
 	}
 	/**
@@ -5478,12 +5762,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;
@@ -5492,6 +5779,8 @@ 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;
@@ -5515,17 +5804,22 @@ 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;
 	}
@@ -5546,11 +5840,14 @@ 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;
@@ -5574,9 +5871,12 @@ 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;
 	}
@@ -5614,6 +5914,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.
@@ -5804,6 +6140,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
@@ -5845,6 +6209,66 @@ 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
@@ -5952,4 +6376,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, 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 };
+export { ArkormCollection, ArkormException, Attribute, CliApp, EnumBuilder, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, MissingDelegateException, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_ENUM_MEMBER_REGEX, PRISMA_ENUM_REGEX, PRISMA_MODEL_REGEX, Paginator, QueryBuilder, QueryConstraintException, RelationResolutionException, SEEDER_BRAND, SchemaBuilder, ScopeNotDefinedException, SeedCommand, Seeder, TableBuilder, URLDriver, UniqueConstraintResolutionException, UnsupportedAdapterFeatureException, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildEnumBlock, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findEnumBlock, findModelBlock, formatDefaultValue, formatEnumDefaultValue, formatRelationAction, generateMigrationFile, getActiveTransactionClient, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, isTransactionCapableClient, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveEnumName, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runArkormTransaction, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkormx",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Modern TypeScript-first ORM for Node.js.",
   "keywords": [
     "orm",