reinhardt_db/orm/

model.rs

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Trait for type-safe field selectors
///
/// This trait is automatically implemented for field selector structs generated
/// by the `#[model(...)]` macro (e.g., `UserFields`).
pub trait FieldSelector: Clone {
	/// Set table alias for all fields
	///
	/// This is used for self-joins where the same table appears multiple times
	/// with different aliases.
	fn with_alias(self, alias: &str) -> Self;
}

/// Core trait for database models
/// Uses composition instead of inheritance - models can implement multiple traits
///
/// # Breaking Change (Phase 4)
///
/// A new associated type `Fields` has been added. It provides a type-safe field selector.
/// When using the `#[model(...)]` macro, this implementation is automatically generated.
pub trait Model: Serialize + for<'de> Deserialize<'de> + Send + Sync + Clone {
	/// The primary key type
	type PrimaryKey: Send + Sync + Clone + std::fmt::Display;

	/// Type-safe field selector
	///
	/// This type is automatically generated by the `#[model(...)]` macro as `{Model}Fields`.
	/// It provides compile-time type safety for field references in queries.
	type Fields: FieldSelector;

	/// The manager type returned by `objects()`.
	///
	/// Defaults to [`Manager<Self>`](super::Manager) when no custom manager is
	/// configured. When `#[model(manager = MyManager)]` is specified, the macro
	/// sets this to the custom manager type, so `objects()` returns the custom
	/// manager directly.
	type Objects: super::custom_manager::CustomManager<Model = Self> + Default;

	/// Get the table name
	fn table_name() -> &'static str;

	/// Create a new field selector instance
	///
	/// This method is automatically implemented by the `#[model(...)]` macro.
	/// It returns a new instance of the type-safe field selector.
	fn new_fields() -> Self::Fields;

	/// Get the app label for this model
	///
	/// This is used by the migration system to organize models by application.
	/// Defaults to "default" if not specified.
	fn app_label() -> &'static str {
		"default"
	}

	/// Get the primary key field name
	fn primary_key_field() -> &'static str {
		"id"
	}

	/// Converts a primary key into a query filter value.
	///
	/// Primitive integer primary keys retain numeric bindings, while standard
	/// string primary keys retain exact string bindings. Other hand-written key
	/// types retain the historical numeric-or-string fallback for compatibility;
	/// custom string-like newtypes should override this method for exact binding.
	/// Derived models override this conversion for declared primary-key types with
	/// a dedicated database binding, such as strings, UUIDs, and timestamps.
	fn primary_key_filter_value(pk: Self::PrimaryKey) -> super::query::FilterValue {
		let value = pk.to_string();
		let type_name = std::any::type_name::<Self::PrimaryKey>();

		if [
			std::any::type_name::<i8>(),
			std::any::type_name::<i16>(),
			std::any::type_name::<i32>(),
			std::any::type_name::<i64>(),
			std::any::type_name::<isize>(),
			std::any::type_name::<i128>(),
		]
		.contains(&type_name)
		{
			return value
				.parse::<i128>()
				.map(super::query::FilterValue::from)
				.unwrap_or(super::query::FilterValue::String(value));
		}

		if [
			std::any::type_name::<u8>(),
			std::any::type_name::<u16>(),
			std::any::type_name::<u32>(),
			std::any::type_name::<u64>(),
			std::any::type_name::<usize>(),
			std::any::type_name::<u128>(),
		]
		.contains(&type_name)
		{
			return value
				.parse::<u128>()
				.map(super::query::FilterValue::from)
				.unwrap_or(super::query::FilterValue::String(value));
		}

		if matches!(
			type_name,
			name if name == std::any::type_name::<String>()
				|| name == std::any::type_name::<&str>()
				|| name == std::any::type_name::<std::borrow::Cow<'static, str>>()
		) {
			return super::query::FilterValue::String(value);
		}

		value
			.parse::<i64>()
			.map(super::query::FilterValue::Integer)
			.unwrap_or(super::query::FilterValue::String(value))
	}

	/// Get the primary key value
	///
	/// Returns an owned copy of the primary key. For composite primary keys,
	/// this constructs a new PK value from the component fields.
	fn primary_key(&self) -> Option<Self::PrimaryKey>;

	/// Set the primary key value
	fn set_primary_key(&mut self, value: Self::PrimaryKey);

	/// Get composite primary key definition if this model uses composite PK
	///
	/// Returns None for single primary key models, Some(CompositePrimaryKey) for composite PK models.
	fn composite_primary_key() -> Option<super::composite_pk::CompositePrimaryKey> {
		None
	}

	/// Get composite primary key values for this instance
	///
	/// Only meaningful for models with composite primary keys.
	/// Returns empty HashMap for single primary key models.
	fn get_composite_pk_values(&self) -> HashMap<String, super::composite_pk::PkValue> {
		HashMap::new()
	}

	/// Get field metadata for inspection
	///
	/// This method should be implemented to provide introspection capabilities.
	/// By default, returns an empty vector. Override this in derive macros or
	/// manual implementations to provide actual field metadata.
	///
	/// # Examples
	///
	/// ```ignore
	/// use reinhardt_db::orm::Model;
	///
	/// struct User {
	///     id: i32,
	///     name: String,
	/// }
	///
	/// impl Model for User {
	///     // ... other required methods ...
	///
	///     fn field_metadata() -> Vec<super::inspection::FieldInfo> {
	///         vec![
	///             // Field metadata would be generated here
	///         ]
	///     }
	/// }
	/// ```
	fn field_metadata() -> Vec<super::inspection::FieldInfo> {
		Vec::new()
	}

	/// Get relationship metadata for inspection
	///
	/// This method should be implemented to provide relationship introspection.
	/// By default, returns an empty vector. Override this in derive macros or
	/// manual implementations to provide actual relationship metadata.
	fn relationship_metadata() -> Vec<super::inspection::RelationInfo> {
		Vec::new()
	}

	/// Get index metadata for inspection
	///
	/// This method should be implemented to provide index introspection.
	/// By default, returns an empty vector. Override this in derive macros or
	/// manual implementations to provide actual index metadata.
	fn index_metadata() -> Vec<super::inspection::IndexInfo> {
		Vec::new()
	}

	/// Get constraint metadata for inspection
	///
	/// This method should be implemented to provide constraint introspection.
	/// By default, returns an empty vector. Override this in derive macros or
	/// manual implementations to provide actual constraint metadata.
	fn constraint_metadata() -> Vec<super::inspection::ConstraintInfo> {
		Vec::new()
	}

	/// Django-style objects manager accessor
	///
	/// Returns the configured manager for this model type. When a custom manager
	/// is specified via `#[model(manager = MyManager)]`, this returns the custom
	/// manager; otherwise it returns the default [`Manager<Self>`](super::Manager).
	///
	/// # Examples
	///
	/// ```rust,no_run
	/// use reinhardt_db::orm::Model;
	/// use serde::{Serialize, Deserialize};
	/// # #[derive(Debug, Clone, Serialize, Deserialize)]
	/// # struct MyModel { id: Option<i64> }
	/// # #[derive(Clone)]
	/// # struct MyModelFields;
	/// # impl reinhardt_db::orm::model::FieldSelector for MyModelFields {
	/// #     fn with_alias(self, _alias: &str) -> Self { self }
	/// # }
	/// # impl Model for MyModel {
	/// #     type PrimaryKey = i64;
	/// #     type Fields = MyModelFields;
	/// #     type Objects = reinhardt_db::orm::Manager<Self>;
	/// #     fn app_label() -> &'static str { "app" }
	/// #     fn table_name() -> &'static str { "table" }
	/// #     fn new_fields() -> Self::Fields { MyModelFields }
	/// #     fn primary_key(&self) -> Option<Self::PrimaryKey> { self.id.clone() }
	/// #     fn set_primary_key(&mut self, value: Self::PrimaryKey) { self.id = Some(value); }
	/// #     fn primary_key_field() -> &'static str { "id" }
	/// # }
	///
	/// # #[tokio::main]
	/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
	/// let manager = MyModel::objects();
	/// let all_records = manager.all().all().await?;
	/// # Ok(())
	/// # }
	/// ```
	fn objects() -> Self::Objects
	where
		Self: Sized,
	{
		Self::Objects::default()
	}

	/// Save the model instance to the database with event dispatching
	///
	/// If the primary key is None, performs an INSERT and dispatches before_insert/after_insert events.
	/// If the primary key is Some, performs an UPDATE and dispatches before_update/after_update events.
	///
	/// Event listeners can veto the operation by returning `EventResult::Veto`.
	///
	/// # Examples
	///
	/// ```rust,no_run
	/// use reinhardt_db::orm::Model;
	/// use serde::{Serialize, Deserialize};
	/// # #[derive(Debug, Clone, Serialize, Deserialize)]
	/// # struct User { id: Option<i64>, name: String }
	/// # #[derive(Clone)]
	/// # struct UserFields;
	/// # impl reinhardt_db::orm::model::FieldSelector for UserFields {
	/// #     fn with_alias(self, _alias: &str) -> Self { self }
	/// # }
	/// # impl Model for User {
	/// #     type PrimaryKey = i64;
	/// #     type Fields = UserFields;
	/// #     type Objects = reinhardt_db::orm::Manager<Self>;
	/// #     fn app_label() -> &'static str { "app" }
	/// #     fn table_name() -> &'static str { "users" }
	/// #     fn new_fields() -> Self::Fields { UserFields }
	/// #     fn primary_key(&self) -> Option<Self::PrimaryKey> { self.id.clone() }
	/// #     fn set_primary_key(&mut self, value: Self::PrimaryKey) { self.id = Some(value); }
	/// #     fn primary_key_field() -> &'static str { "id" }
	/// # }
	///
	/// # #[tokio::main]
	/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
	/// let mut user = User { id: None, name: "John".to_string() };
	///
	/// // INSERT - triggers before_insert/after_insert events
	/// user.save().await?;
	///
	/// // UPDATE - triggers before_update/after_update events
	/// user.name = "Jane".to_string();
	/// user.save().await?;
	/// # Ok(())
	/// # }
	/// ```
	fn save(
		&mut self,
	) -> impl std::future::Future<Output = reinhardt_core::exception::Result<()>> + Send
	where
		Self: Sized,
	{
		async move {
			use super::events::{EventResult, get_active_registry};
			use super::manager::get_connection;

			let registry = get_active_registry();
			let conn = get_connection().await?;
			let manager = super::Manager::<Self>::new();

			let json = serde_json::to_value(&*self)
				.map_err(|e| reinhardt_core::exception::Error::Database(e.to_string()))?;

			if self.primary_key().is_none() {
				// INSERT: new record
				let instance_id = format!("{}-new-{}", Self::table_name(), uuid::Uuid::now_v7());

				// Dispatch before_insert event if registry is active
				if let Some(ref reg) = registry {
					let result = reg
						.dispatch_before_insert(Self::table_name(), &instance_id, &json)
						.await;
					if result == EventResult::Veto {
						return Err(reinhardt_core::exception::Error::Database(
							"Insert operation vetoed by event listener".to_string(),
						));
					}
				}

				// Perform the INSERT
				let created = manager.create_with_conn(&conn, self).await?;
				*self = created;

				// Dispatch after_insert event if registry is active
				if let Some(ref reg) = registry {
					let final_id = format!(
						"{}-{}",
						Self::table_name(),
						self.primary_key()
							.map(|pk| pk.to_string())
							.unwrap_or_default()
					);
					reg.dispatch_after_insert(Self::table_name(), &final_id)
						.await;
				}
			} else {
				// UPDATE: existing record
				let instance_id = format!(
					"{}-{}",
					Self::table_name(),
					self.primary_key()
						.map(|pk| pk.to_string())
						.unwrap_or_default()
				);

				// Dispatch before_update event if registry is active
				if let Some(ref reg) = registry {
					let result = reg
						.dispatch_before_update(Self::table_name(), &instance_id, &json)
						.await;
					if result == EventResult::Veto {
						return Err(reinhardt_core::exception::Error::Database(
							"Update operation vetoed by event listener".to_string(),
						));
					}
				}

				// Perform the UPDATE
				let updated = manager.update_with_conn(&conn, self).await?;
				*self = updated;

				// Dispatch after_update event if registry is active
				if let Some(ref reg) = registry {
					reg.dispatch_after_update(Self::table_name(), &instance_id)
						.await;
				}
			}

			Ok(())
		}
	}

	/// Delete the model instance from the database with event dispatching
	///
	/// Dispatches before_delete/after_delete events. Event listeners can veto
	/// the operation by returning `EventResult::Veto`.
	///
	/// # Examples
	///
	/// ```rust,no_run
	/// use reinhardt_db::orm::Model;
	/// use serde::{Serialize, Deserialize};
	/// # #[derive(Debug, Clone, Serialize, Deserialize)]
	/// # struct User { id: Option<i64>, name: String }
	/// # #[derive(Clone)]
	/// # struct UserFields;
	/// # impl reinhardt_db::orm::model::FieldSelector for UserFields {
	/// #     fn with_alias(self, _alias: &str) -> Self { self }
	/// # }
	/// # impl Model for User {
	/// #     type PrimaryKey = i64;
	/// #     type Fields = UserFields;
	/// #     type Objects = reinhardt_db::orm::Manager<Self>;
	/// #     fn app_label() -> &'static str { "app" }
	/// #     fn table_name() -> &'static str { "users" }
	/// #     fn new_fields() -> Self::Fields { UserFields }
	/// #     fn primary_key(&self) -> Option<Self::PrimaryKey> { self.id.clone() }
	/// #     fn set_primary_key(&mut self, value: Self::PrimaryKey) { self.id = Some(value); }
	/// #     fn primary_key_field() -> &'static str { "id" }
	/// # }
	///
	/// # #[tokio::main]
	/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
	/// let mut user = User { id: Some(1), name: "John".to_string() };
	///
	/// // Triggers before_delete/after_delete events
	/// user.delete().await?;
	/// # Ok(())
	/// # }
	/// ```
	fn delete(
		&self,
	) -> impl std::future::Future<Output = reinhardt_core::exception::Result<()>> + Send
	where
		Self: Sized,
	{
		async move {
			use super::events::{EventResult, get_active_registry};
			use super::manager::get_connection;

			let pk = self.primary_key().ok_or_else(|| {
				reinhardt_core::exception::Error::Database(
					"Cannot delete model without primary key".to_string(),
				)
			})?;

			let conn = get_connection().await?;
			let manager = super::Manager::<Self>::new();

			let instance_id = format!("{}-{}", Self::table_name(), pk);

			// Dispatch before_delete event if registry is available
			if let Some(registry) = get_active_registry() {
				let result = registry
					.dispatch_before_delete(Self::table_name(), &instance_id)
					.await;
				if result == EventResult::Veto {
					return Err(reinhardt_core::exception::Error::Database(
						"Delete operation vetoed by event listener".to_string(),
					));
				}
			}

			// Perform the DELETE
			manager.delete_with_conn(&conn, pk.clone()).await?;

			// Dispatch after_delete event if registry is available
			if let Some(registry) = get_active_registry() {
				registry
					.dispatch_after_delete(Self::table_name(), &instance_id)
					.await;
			}

			Ok(())
		}
	}
}

/// Trait for models with timestamps - compose this with Model
/// This follows Rust's composition pattern rather than Django's inheritance
pub trait Timestamped {
	/// Returns the creation timestamp.
	fn created_at(&self) -> chrono::DateTime<chrono::Utc>;
	/// Returns the last update timestamp.
	fn updated_at(&self) -> chrono::DateTime<chrono::Utc>;
	/// Sets the last update timestamp.
	fn set_updated_at(&mut self, time: chrono::DateTime<chrono::Utc>);
}

/// Trait for soft-deletable models
/// Another composition trait instead of inheritance
pub trait SoftDeletable {
	/// Returns the deletion timestamp, or `None` if not deleted.
	fn deleted_at(&self) -> Option<chrono::DateTime<chrono::Utc>>;
	/// Sets the deletion timestamp, or `None` to restore.
	fn set_deleted_at(&mut self, time: Option<chrono::DateTime<chrono::Utc>>);
	/// Returns whether the model has been soft-deleted.
	fn is_deleted(&self) -> bool {
		self.deleted_at().is_some()
	}
}

/// Common timestamp fields that can be composed into structs
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Timestamps {
	/// The created at.
	pub created_at: chrono::DateTime<chrono::Utc>,
	/// The updated at.
	pub updated_at: chrono::DateTime<chrono::Utc>,
}

impl Timestamps {
	/// Creates a new Timestamps instance with current time
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_db::orm::model::Timestamps;
	///
	/// let timestamps = Timestamps::now();
	/// assert!(timestamps.created_at <= chrono::Utc::now());
	/// assert!(timestamps.updated_at <= chrono::Utc::now());
	/// ```
	pub fn now() -> Self {
		let now = chrono::Utc::now();
		Self {
			created_at: now,
			updated_at: now,
		}
	}
	/// Updates the updated_at timestamp to current time
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_db::orm::model::Timestamps;
	/// use chrono::Utc;
	///
	/// let mut timestamps = Timestamps::now();
	/// let old_updated = timestamps.updated_at;
	///
	/// // Wait a small amount to ensure time difference
	/// std::thread::sleep(std::time::Duration::from_millis(1));
	/// timestamps.touch();
	///
	/// assert!(timestamps.updated_at > old_updated);
	/// ```
	pub fn touch(&mut self) {
		self.updated_at = chrono::Utc::now();
	}
}

/// Soft delete field that can be composed into structs
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SoftDelete {
	/// The deleted at.
	pub deleted_at: Option<chrono::DateTime<chrono::Utc>>,
}

impl SoftDelete {
	/// Creates a new SoftDelete instance with no deletion timestamp
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_db::orm::model::SoftDelete;
	///
	/// let soft_delete = SoftDelete::new();
	/// assert!(soft_delete.deleted_at.is_none());
	/// ```
	pub fn new() -> Self {
		Self { deleted_at: None }
	}
	/// Marks the record as deleted by setting the deletion timestamp
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_db::orm::model::SoftDelete;
	///
	/// let mut soft_delete = SoftDelete::new();
	/// assert!(!soft_delete.is_deleted());
	///
	/// soft_delete.delete();
	/// assert!(soft_delete.is_deleted());
	/// assert!(soft_delete.deleted_at.is_some());
	/// ```
	pub fn delete(&mut self) {
		self.deleted_at = Some(chrono::Utc::now());
	}
	/// Restores a soft-deleted record by clearing the deletion timestamp
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_db::orm::model::SoftDelete;
	///
	/// let mut soft_delete = SoftDelete::new();
	/// soft_delete.delete();
	/// assert!(soft_delete.is_deleted());
	///
	/// soft_delete.restore();
	/// assert!(!soft_delete.is_deleted());
	/// assert!(soft_delete.deleted_at.is_none());
	/// ```
	pub fn restore(&mut self) {
		self.deleted_at = None;
	}

	/// Check if the record is soft-deleted
	pub fn is_deleted(&self) -> bool {
		self.deleted_at.is_some()
	}
}

impl Default for SoftDelete {
	fn default() -> Self {
		Self::new()
	}
}