ensemble 0.0.5

A Laravel-inspired ORM
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

use inflector::Inflector;
use rbs::Value;
use serde::Serialize;
use std::{collections::HashMap, fmt::Debug};

use super::{find_related, Relationship, Status};
use crate::{query::Builder, value::serializing_for_db, Error, Model};

/// ## A Belongs To relationship.
/// A belongs to relationship is used to define relationships where a model is the child to a single models. For example, a website may belong to a user.
///
/// To define this relationship, we will place a user field on the Site model. The comments field should be of type `BelongsTo<Site, User>`.
///
/// ## Example
///
/// ```rust
/// # use ensemble::{Model, relationships::BelongsTo};
/// # #[derive(Debug, Model)]
/// # struct User {
/// #   id: u64,
/// # }
/// #[derive(Debug, Model)]
/// struct Site {
///   id: u64,
///   url: String,
///   user: BelongsTo<Site, User>
/// }
///
/// # async fn call() -> Result<(), ensemble::Error> {
/// let mut site = Site::find(1).await?;
///
/// let user: &User = site.user().await?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Default)]
pub struct BelongsTo<Local: Model, Related: Model> {
	local_key: String,
	relation: Status<Related>,
	_local: std::marker::PhantomData<Local>,
	/// The value of the local model's related key.
	pub value: Related::PrimaryKey,
}

impl<Local: Model, Related: Model> Relationship for BelongsTo<Local, Related> {
	type Value = Related;
	type Key = Related::PrimaryKey;
	type RelatedKey = Option<String>;

	fn build(value: Self::Key, local_key: Self::RelatedKey) -> Self {
		let local_key = local_key.unwrap_or_else(|| Related::PRIMARY_KEY.to_snake_case());

		Self {
			value,
			local_key,
			relation: Status::initial(),
			_local: std::marker::PhantomData,
		}
	}

	fn query(&self) -> Builder {
		Related::query()
			.r#where(
				&format!("{}.{}", Related::TABLE_NAME, self.local_key),
				"=",
				self.value.clone(),
			)
			.limit(1)
	}

	/// Get the related model.
	async fn get(&mut self) -> Result<&mut Self::Value, Error> {
		if self.relation.is_none() {
			let relation = self.query().first().await?.ok_or(Error::NotFound)?;

			self.relation = Status::Fetched(Some(relation));
		}

		Ok(self.relation.as_mut().unwrap())
	}

	fn peek(&self) -> Option<&Self::Value> {
		self.relation.as_ref()
	}

	fn is_loaded(&self) -> bool {
		self.relation.is_loaded()
	}

	fn eager_query(&self, related: Vec<Self::Key>) -> Builder {
		Related::query()
			.r#where(
				&format!("{}.{}", Related::TABLE_NAME, self.local_key),
				"in",
				related,
			)
			.limit(1)
	}

	fn r#match(&mut self, related: &[HashMap<String, Value>]) -> Result<(), Error> {
		let related = find_related(related, &self.local_key, &self.value, true)?;

		self.relation = Status::Fetched(related.into_iter().next());

		Ok(())
	}
}

impl<Local: Model, Related: Model> Debug for BelongsTo<Local, Related> {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		self.relation.fmt(f)
	}
}

impl<Local: Model, Related: Model> Serialize for BelongsTo<Local, Related> {
	fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
		if serializing_for_db::<S>() {
			if self.value == Default::default() {
				return serializer.serialize_none();
			}

			return self.value.serialize(serializer);
		}

		self.relation.serialize(serializer)
	}
}

impl<Local: Model, Related: Model> PartialEq<Related> for BelongsTo<Local, Related> {
	fn eq(&self, other: &Related) -> bool {
		&self.value == other.primary_key()
	}
}

#[cfg(feature = "schema")]
impl<Local: Model, Related: Model + schemars::JsonSchema> schemars::JsonSchema
	for BelongsTo<Local, Related>
{
	fn schema_name() -> String {
		<Option<Related>>::schema_name()
	}

	fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
		gen.subschema_for::<Option<Related>>()
	}
}