reactive_graph_graph/instances/entities/
entity_instance.rs

1use std::borrow::Cow;
2use std::cmp::Ordering;
3use std::fmt::Display;
4use std::fmt::Formatter;
5use std::hash::Hash;
6use std::hash::Hasher;
7use std::ops::Deref;
8use std::ops::DerefMut;
9
10use const_format::formatcp;
11use dashmap::DashMap;
12use dashmap::iter::OwningIter;
13use schemars::JsonSchema;
14use schemars::Schema;
15use schemars::SchemaGenerator;
16use schemars::json_schema;
17use serde::Deserialize;
18use serde::Deserializer;
19use serde::Serialize;
20use serde::Serializer;
21use serde_json::Map;
22use serde_json::Value;
23use typed_builder::TypedBuilder;
24use uuid::Uuid;
25
26use crate::AddExtensionError;
27use crate::ComponentTypeId;
28use crate::ComponentTypeIdContainer;
29use crate::ComponentTypeIds;
30use crate::EntityTypeId;
31use crate::EntityTypeIds;
32use crate::Extension;
33use crate::ExtensionContainer;
34use crate::ExtensionTypeId;
35use crate::Extensions;
36use crate::JSON_SCHEMA_ID_URI_PREFIX;
37use crate::MutablePropertyInstanceSetter;
38use crate::NamedInstanceContainer;
39use crate::NamespaceSegment;
40use crate::NamespacedType;
41use crate::NamespacedTypeGetter;
42use crate::PropertyInstanceGetter;
43use crate::PropertyInstances;
44use crate::RemoveExtensionError;
45use crate::TypeDefinition;
46use crate::TypeDefinitionGetter;
47use crate::TypeIdType;
48use crate::UpdateExtensionError;
49use crate::namespace::NAMESPACE_SEPARATOR;
50use crate::namespace::Namespace;
51
52#[cfg(any(test, feature = "test"))]
53use crate::EntityType;
54#[cfg(any(test, feature = "test"))]
55use crate::NamespacedTypeError;
56#[cfg(any(test, feature = "test"))]
57use crate::RandomInstance;
58#[cfg(any(test, feature = "test"))]
59use crate::RandomInstances;
60#[cfg(any(test, feature = "test"))]
61use crate::RandomNamespacedTypeId;
62#[cfg(any(test, feature = "test"))]
63use crate::RandomNamespacedTypes;
64#[cfg(any(test, feature = "test"))]
65use crate::test_utils::default_from::DefaultFrom;
66#[cfg(any(test, feature = "test"))]
67use default_test::DefaultTest;
68#[cfg(any(test, feature = "test"))]
69use rand::Rng;
70#[cfg(any(test, feature = "test"))]
71use reactive_graph_utils_test::DefaultTryFrom;
72#[cfg(any(test, feature = "test"))]
73use reactive_graph_utils_test::r_string;
74
75pub const JSON_SCHEMA_ID_ENTITY_INSTANCE: &str = formatcp!("{}/entity-instance.schema.json", JSON_SCHEMA_ID_URI_PREFIX);
76
77/// Entity instances represents an typed object which contains properties.
78///
79/// The entity type defines the properties (name, data type and socket type).
80///
81/// In contrast to the entity type the entity instance stores values in its
82/// properties.
83#[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize, JsonSchema, TypedBuilder)]
84#[serde(tag = "$id", rename = "https://schema.reactive-graph.io/schema/json/entity-instance.schema.json")]
85#[schemars(
86    title = "EntityInstance",
87    rename = "EntityInstance",
88    deny_unknown_fields,
89    extend("$id" = JSON_SCHEMA_ID_ENTITY_INSTANCE),
90    transform = add_json_schema_id_property
91)]
92pub struct EntityInstance {
93    /// The type definition of the entity type.
94    #[serde(rename = "type")]
95    #[builder(setter(into))]
96    pub ty: EntityTypeId,
97
98    /// The unique identifier of the entity instance.
99    #[builder(default=Uuid::new_v4())]
100    pub id: Uuid,
101
102    /// The name of the entity instance.
103    #[serde(default = "String::new")]
104    #[builder(default, setter(into))]
105    pub name: String,
106
107    /// The description of the entity instance.
108    #[serde(default = "String::new")]
109    #[builder(default, setter(into))]
110    pub description: String,
111
112    /// The properties of the entity instance.
113    ///
114    /// Each property is represented by its name (String) and it's value. The value is
115    /// a representation of a JSON. Therefore, the value can be boolean, number, string,
116    /// array or an object. For more information about the data types please look at
117    /// <https://docs.serde.rs/serde_json/value/enum.Value.html>
118    #[serde(default = "PropertyInstances::new")]
119    #[builder(default, setter(into))]
120    pub properties: PropertyInstances,
121
122    /// The components of the entity instance.
123    #[serde(default = "ComponentTypeIds::new")]
124    #[builder(default, setter(into))]
125    pub components: ComponentTypeIds,
126
127    //
128    // TODO: behaviours?
129    //
130    /// Entity instance specific extensions.
131    #[serde(default = "Extensions::new")]
132    #[builder(default, setter(into))]
133    pub extensions: Extensions,
134}
135
136impl EntityInstance {
137    /// Constructs a new entity instance with the given type.
138    pub fn new<T: Into<EntityTypeId>, P: Into<PropertyInstances>>(ty: T, id: Uuid, properties: P) -> EntityInstance {
139        EntityInstance {
140            ty: ty.into(),
141            id,
142            name: String::new(),
143            description: String::new(),
144            properties: properties.into(),
145            components: ComponentTypeIds::new(),
146            extensions: Extensions::new(),
147        }
148    }
149
150    /// Constructs a new entity instance with the given type and id but without properties.
151    pub fn new_without_properties<T: Into<EntityTypeId>>(ty: T, id: Uuid) -> EntityInstance {
152        EntityInstance {
153            ty: ty.into(),
154            id,
155            name: String::new(),
156            description: String::new(),
157            properties: PropertyInstances::new(),
158            components: ComponentTypeIds::new(),
159            extensions: Extensions::new(),
160        }
161    }
162}
163
164impl NamedInstanceContainer for EntityInstance {
165    fn name(&self) -> String {
166        self.name.clone()
167    }
168
169    fn description(&self) -> String {
170        self.description.clone()
171    }
172}
173
174impl PropertyInstanceGetter for EntityInstance {
175    fn get(&self, property_name: &str) -> Option<Value> {
176        self.properties.get(property_name.into())
177    }
178
179    fn as_bool(&self, property_name: &str) -> Option<bool> {
180        self.properties.as_bool(property_name.into())
181    }
182
183    fn as_u64(&self, property_name: &str) -> Option<u64> {
184        self.properties.as_u64(property_name.into())
185    }
186
187    fn as_i64(&self, property_name: &str) -> Option<i64> {
188        self.properties.as_i64(property_name.into())
189    }
190
191    fn as_f64(&self, property_name: &str) -> Option<f64> {
192        self.properties.as_f64(property_name.into())
193    }
194
195    fn as_string(&self, property_name: &str) -> Option<String> {
196        self.properties.as_string(property_name.into())
197    }
198
199    fn as_array(&self, property_name: &str) -> Option<Vec<Value>> {
200        self.properties.as_array(property_name.into())
201    }
202
203    fn as_object(&self, property_name: &str) -> Option<Map<String, Value>> {
204        self.properties.as_object(property_name.into())
205    }
206}
207
208impl MutablePropertyInstanceSetter for EntityInstance {
209    fn set<S: Into<String>>(&mut self, property_name: S, value: Value) {
210        self.properties.set(property_name.into(), value);
211    }
212}
213
214impl ComponentTypeIdContainer for EntityInstance {
215    fn is_a(&self, ty: &ComponentTypeId) -> bool {
216        self.components.is_a(ty)
217    }
218
219    fn add_component<C: Into<ComponentTypeId>>(&self, ty: C) -> bool {
220        self.components.add_component(ty)
221    }
222
223    fn add_components<C: Into<ComponentTypeIds>>(&mut self, components_to_add: C) {
224        self.components.add_components(components_to_add)
225    }
226
227    fn remove_component(&self, ty: &ComponentTypeId) -> Option<ComponentTypeId> {
228        self.components.remove_component(ty)
229    }
230
231    fn remove_components<C: Into<ComponentTypeIds>>(&mut self, components_to_remove: C) {
232        self.components.remove_components(components_to_remove)
233    }
234
235    fn get_components_cloned(&self) -> ComponentTypeIds {
236        self.components.clone()
237    }
238}
239
240impl ExtensionContainer for EntityInstance {
241    fn has_own_extension(&self, ty: &ExtensionTypeId) -> bool {
242        self.extensions.has_own_extension(ty)
243    }
244
245    fn get_own_extension(&self, ty: &ExtensionTypeId) -> Option<Extension> {
246        self.extensions.get_own_extension(ty)
247    }
248
249    fn add_extension<E: Into<Extension>>(&self, extension: E) -> Result<ExtensionTypeId, AddExtensionError> {
250        self.extensions.add_extension(extension)
251    }
252
253    fn update_extension<T: Into<ExtensionTypeId>, E: Into<Extension>>(&self, ty: T, extension: E) -> Result<Extension, UpdateExtensionError> {
254        self.extensions.update_extension(ty, extension)
255    }
256
257    fn remove_extension<T: Into<ExtensionTypeId>>(&self, ty: T) -> Result<Extension, RemoveExtensionError> {
258        self.extensions.remove_extension(ty)
259    }
260
261    fn merge_extensions<E: Into<Extensions>>(&mut self, extensions_to_merge: E) {
262        self.extensions.merge_extensions(extensions_to_merge)
263    }
264
265    fn get_own_extensions_cloned(&self) -> Extensions {
266        self.extensions.clone()
267    }
268}
269
270impl NamespacedTypeGetter for EntityInstance {
271    fn namespaced_type(&self) -> NamespacedType {
272        self.ty.namespaced_type()
273    }
274
275    fn namespace(&self) -> Namespace {
276        self.ty.namespace()
277    }
278
279    fn path(&self) -> Namespace {
280        self.ty.path()
281    }
282
283    fn type_name(&self) -> NamespaceSegment {
284        self.ty.type_name()
285    }
286}
287
288impl TypeDefinitionGetter for EntityInstance {
289    fn type_definition(&self) -> TypeDefinition {
290        self.ty.type_definition()
291    }
292
293    fn type_id_type() -> TypeIdType {
294        TypeIdType::EntityType
295    }
296}
297
298impl PartialEq<Uuid> for EntityInstance {
299    fn eq(&self, id: &Uuid) -> bool {
300        self.id == *id
301    }
302}
303
304impl PartialOrd<Self> for EntityInstance {
305    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
306        Some(self.cmp(other))
307    }
308}
309
310impl Ord for EntityInstance {
311    fn cmp(&self, other: &Self) -> Ordering {
312        self.id.cmp(&other.id)
313    }
314}
315
316impl Display for EntityInstance {
317    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
318        write!(f, "{}{}{}", &self.ty, NAMESPACE_SEPARATOR, self.id)
319    }
320}
321
322#[derive(Clone, Debug, Default)]
323pub struct EntityInstances(DashMap<Uuid, EntityInstance>);
324
325impl EntityInstances {
326    pub fn new() -> Self {
327        EntityInstances(DashMap::new())
328    }
329
330    pub fn new_with_instance<E: Into<EntityInstance>>(entity_instance: E) -> Self {
331        let entity_instances = EntityInstances::new();
332        entity_instances.push(entity_instance.into());
333        entity_instances
334    }
335
336    pub fn push<E: Into<EntityInstance>>(&self, entity_instance: E) {
337        let entity_instance = entity_instance.into();
338        self.0.insert(entity_instance.id, entity_instance);
339    }
340
341    pub fn to_vec(&self) -> Vec<EntityInstance> {
342        let mut items: Vec<_> = self.iter().map(|item| item.value().clone()).collect();
343        items.sort();
344        items
345    }
346
347    pub fn get_type_ids(&self) -> EntityTypeIds {
348        self.iter().map(|entity_instance| entity_instance.ty.clone()).collect()
349    }
350}
351
352impl Deref for EntityInstances {
353    type Target = DashMap<Uuid, EntityInstance>;
354
355    fn deref(&self) -> &Self::Target {
356        &self.0
357    }
358}
359
360impl DerefMut for EntityInstances {
361    fn deref_mut(&mut self) -> &mut Self::Target {
362        &mut self.0
363    }
364}
365
366impl IntoIterator for EntityInstances {
367    type Item = (Uuid, EntityInstance);
368    type IntoIter = OwningIter<Uuid, EntityInstance>;
369
370    fn into_iter(self) -> Self::IntoIter {
371        self.0.into_iter()
372    }
373}
374
375impl PartialEq for EntityInstances {
376    fn eq(&self, other: &Self) -> bool {
377        self.0.iter().all(|self_entity_instance| other.contains_key(&self_entity_instance.id))
378            && other.iter().all(|other_entity_instance| self.contains_key(&other_entity_instance.id))
379    }
380}
381
382impl Eq for EntityInstances {}
383
384impl Hash for EntityInstances {
385    fn hash<H: Hasher>(&self, state: &mut H) {
386        self.to_vec().hash(state);
387    }
388}
389
390impl Serialize for EntityInstances {
391    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
392    where
393        S: Serializer,
394    {
395        serializer.collect_seq(self.iter())
396    }
397}
398
399impl<'de> Deserialize<'de> for EntityInstances {
400    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
401    where
402        D: Deserializer<'de>,
403    {
404        Ok(Vec::<EntityInstance>::deserialize(deserializer)?.into())
405    }
406}
407
408impl JsonSchema for EntityInstances {
409    fn schema_name() -> Cow<'static, str> {
410        "EntityInstances".into()
411    }
412
413    fn json_schema(schema_generator: &mut SchemaGenerator) -> Schema {
414        let sub_schema: Schema = schema_generator.subschema_for::<EntityInstance>();
415        json_schema!({
416            "type": "array",
417            "items": sub_schema,
418            "description": "Entity Instances",
419        })
420    }
421}
422
423impl From<Vec<EntityInstance>> for EntityInstances {
424    fn from(entity_instances: Vec<EntityInstance>) -> Self {
425        Self(
426            entity_instances
427                .into_iter()
428                .map(|entity_instance| (entity_instance.id, entity_instance))
429                .collect(),
430        )
431    }
432}
433
434impl From<EntityInstances> for Vec<EntityInstance> {
435    fn from(entity_instances: EntityInstances) -> Self {
436        entity_instances.to_vec()
437    }
438}
439
440impl From<&EntityInstances> for Vec<EntityInstance> {
441    fn from(entity_instances: &EntityInstances) -> Self {
442        entity_instances.0.iter().map(|entity_instance| entity_instance.clone()).collect()
443    }
444}
445
446impl From<DashMap<Uuid, EntityInstance>> for EntityInstances {
447    fn from(entity_instances: DashMap<Uuid, EntityInstance>) -> Self {
448        Self(entity_instances)
449    }
450}
451
452impl From<&DashMap<Uuid, EntityInstance>> for EntityInstances {
453    fn from(entity_instances: &DashMap<Uuid, EntityInstance>) -> Self {
454        Self(entity_instances.clone())
455    }
456}
457
458impl From<EntityInstances> for DashMap<Uuid, EntityInstance> {
459    fn from(entity_instances: EntityInstances) -> Self {
460        entity_instances.0
461    }
462}
463
464impl FromIterator<EntityInstance> for EntityInstances {
465    fn from_iter<I: IntoIterator<Item = EntityInstance>>(iter: I) -> Self {
466        let entity_instances = Self::new();
467        for entity_instance in iter {
468            entity_instances.insert(entity_instance.id, entity_instance);
469        }
470        entity_instances
471    }
472}
473
474#[cfg(any(test, feature = "test"))]
475impl RandomInstance for EntityInstance {
476    type Error = NamespacedTypeError;
477    type TypeId = EntityTypeId;
478
479    fn random_instance() -> Result<Self, NamespacedTypeError> {
480        Ok(EntityInstance::builder()
481            .ty(EntityTypeId::random_type_id()?)
482            .name(r_string())
483            .description(r_string())
484            .properties(PropertyInstances::default_test())
485            .extensions(Extensions::random_types(0..10)?)
486            .build())
487    }
488
489    fn random_instance_with_id(ty: &EntityTypeId) -> Result<Self, Self::Error> {
490        Ok(EntityInstance::builder()
491            .ty(ty)
492            .name(r_string())
493            .description(r_string())
494            .properties(PropertyInstances::default_test())
495            .extensions(Extensions::random_types(0..10)?)
496            .build())
497    }
498}
499
500#[cfg(any(test, feature = "test"))]
501impl DefaultTryFrom<&EntityType> for EntityInstance {
502    type Error = NamespacedTypeError;
503
504    fn default_try_from(entity_type: &EntityType) -> Result<Self, Self::Error> {
505        let properties = PropertyInstances::default_from(&entity_type.properties);
506        Ok(EntityInstance::builder()
507            .ty(&entity_type.ty)
508            .name(r_string())
509            .description(&entity_type.description)
510            .properties(properties)
511            .extensions(Extensions::random_types(0..10)?)
512            .build())
513    }
514}
515
516#[cfg(any(test, feature = "test"))]
517impl RandomInstances for EntityInstances {
518    type Error = NamespacedTypeError;
519
520    fn random_instances() -> Result<Self, NamespacedTypeError> {
521        let instances = Self::new();
522        let mut rng = rand::rng();
523        for _ in 0..rng.random_range(0..10) {
524            instances.push(EntityInstance::random_instance()?);
525        }
526        Ok(instances)
527    }
528}
529
530fn add_json_schema_id_property(schema: &mut Schema) {
531    crate::json_schema::add_json_schema_id_property(schema, JSON_SCHEMA_ID_ENTITY_INSTANCE);
532}
533
534#[cfg(test)]
535pub mod entity_instance_tests {
536    use schemars::schema_for;
537    use serde_json::json;
538    use std::ops::Index;
539    use std::str::FromStr;
540    use uuid::Uuid;
541
542    use crate::ComponentTypeId;
543    use crate::ComponentTypeIdContainer;
544    use crate::ComponentTypeIds;
545    use crate::EntityInstance;
546    use crate::EntityTypeId;
547    use crate::Extension;
548    use crate::ExtensionContainer;
549    use crate::ExtensionTypeId;
550    use crate::Extensions;
551    use crate::MutablePropertyInstanceSetter;
552    use crate::PropertyInstanceGetter;
553    use crate::PropertyInstances;
554    use crate::RandomInstance;
555    use crate::RandomNamespacedType;
556    use crate::RandomNamespacedTypeId;
557    use reactive_graph_utils_test::r_string;
558
559    #[test]
560    pub fn build_entity_instance() {
561        let ty = EntityTypeId::random_type_id().unwrap();
562        let name = r_string();
563        let description = r_string();
564        let property_name = r_string();
565        let property_value = json!(r_string());
566        let component_ty = ComponentTypeId::random_type_id().unwrap();
567        let components = ComponentTypeIds::new().component(&component_ty);
568        let properties = PropertyInstances::new().property(property_name.clone(), property_value.clone());
569        let extension = Extension::random_type().unwrap();
570        let extensions = Extensions::new().extension(extension.clone());
571        let entity_instance = EntityInstance::builder()
572            .ty(&ty)
573            .name(&name)
574            .description(&description)
575            .components(components.clone())
576            .properties(properties.clone())
577            .extensions(extensions.clone())
578            .build();
579        assert_eq!(ty, entity_instance.ty);
580        assert_eq!(name, entity_instance.name);
581        assert_eq!(description, entity_instance.description);
582        assert_eq!(components, entity_instance.components);
583        assert!(entity_instance.is_a(&component_ty));
584        assert_eq!(properties, entity_instance.properties);
585        assert_eq!(property_value, entity_instance.properties.get(&property_name).unwrap());
586        assert_eq!(extensions, entity_instance.extensions);
587        assert!(entity_instance.has_own_extension(&extension.ty));
588        assert_eq!(extension, entity_instance.get_own_extension(&extension.ty).unwrap());
589    }
590
591    #[test]
592    pub fn create_entity_instance() {
593        let ty = EntityTypeId::random_type_id().unwrap();
594        let property_name = r_string();
595        let property_value = json!(r_string());
596        let properties = PropertyInstances::new().property(property_name.clone(), property_value.clone());
597        let entity_instance = EntityInstance::new(&ty, Uuid::new_v4(), properties.clone());
598        assert_eq!(ty, entity_instance.ty);
599        assert_eq!(properties, entity_instance.properties);
600        assert_eq!(property_value, entity_instance.properties.get(&property_name).unwrap());
601    }
602
603    #[test]
604    fn entity_instance_typed_getter_test() {
605        let property_name = r_string();
606        let properties = PropertyInstances::new().property(&property_name, json!(false));
607        let mut i = EntityInstance::new(EntityTypeId::random_type_id().unwrap(), Uuid::new_v4(), properties);
608        i.set(property_name.clone(), json!(true));
609        assert!(i.as_bool(&property_name).unwrap());
610        i.set(property_name.clone(), json!(false));
611        assert!(!i.as_bool(&property_name).unwrap());
612        i.set(property_name.clone(), json!(123));
613        assert_eq!(123, i.as_u64(&property_name).unwrap());
614        i.set(property_name.clone(), json!(-123));
615        assert_eq!(-123, i.as_i64(&property_name).unwrap());
616        i.set(property_name.clone(), json!(1.23));
617        assert_eq!(1.23, i.as_f64(&property_name).unwrap());
618        let s = r_string();
619        i.set(property_name.clone(), json!(s.clone()));
620        assert_eq!(s, i.as_string(&property_name).unwrap());
621        let a = json!([1, 2, 3]);
622        i.set(property_name.clone(), a.clone());
623        assert_eq!(json!(1), i.as_array(&property_name).unwrap().index(0).clone());
624        assert_eq!(json!(2), i.as_array(&property_name).unwrap().index(1).clone());
625        assert_eq!(json!(3), i.as_array(&property_name).unwrap().index(2).clone());
626        let o = json!({
627            "k": "v"
628        });
629        i.set(property_name.clone(), o.clone());
630        assert_eq!(json!("v"), i.as_object(&property_name).unwrap().index("k").clone());
631    }
632
633    #[test]
634    fn entity_instance_deserialize_fully_valid_test() {
635        let id = Uuid::from_str("f3ef93a4-a384-40de-8075-83b92287fcba").unwrap();
636        let ty = EntityTypeId::from_str("fully::qualified::namespace::EntityType").unwrap();
637        let component_ty = ComponentTypeId::from_str("fully::qualified::namespace::Component").unwrap();
638        let extension_ty = ExtensionTypeId::from_str("fully::qualified::namespace::Extension").unwrap();
639        let entity_instance = serde_json::from_str::<EntityInstance>(
640            r#"{
641          "type": "fully::qualified::namespace::EntityType",
642          "id": "f3ef93a4-a384-40de-8075-83b92287fcba",
643          "description": "d",
644          "components": [
645            "fully::qualified::namespace::Component"
646          ],
647          "properties": {
648            "property_name": "property_value"
649          },
650          "extensions": [
651            {
652              "type": "fully::qualified::namespace::Extension",
653              "extension": ""
654            }
655          ]
656        }"#,
657        )
658        .expect("Failed to deserialize entity instance");
659        assert_eq!(ty, entity_instance.ty);
660        assert_eq!(id, entity_instance.id);
661        assert_eq!("d", entity_instance.description);
662        assert_eq!(1, entity_instance.components.len());
663        assert!(entity_instance.is_a(&component_ty));
664        assert_eq!(1, entity_instance.properties.len());
665        assert_eq!("property_value", entity_instance.get("property_name").unwrap());
666        assert_eq!(1, entity_instance.extensions.len());
667        assert!(entity_instance.get_own_extension(&extension_ty).is_some());
668    }
669
670    #[test]
671    fn entity_instance_ser_test() {
672        let entity_instance = EntityInstance::random_instance().unwrap();
673        println!("{}", serde_json::to_string_pretty(&entity_instance).expect("Failed to serialize entity instance"));
674    }
675
676    #[test]
677    fn entity_instance_json_schema() {
678        let schema = schema_for!(EntityInstance);
679        println!("{}", serde_json::to_string_pretty(&schema).unwrap());
680    }
681}