khive-types 0.2.0

Core type primitives: Id128, Timestamp, Namespace, and the 3 substrate data types (Note, Entity, Event).
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

//! Substrate discriminant — the 3 data types in khive (ADR-004).
//!
//! Full substrate structs live in the sibling modules (`note`, `entity`,
//! `event`). This module provides the discriminant for typed dispatch and
//! persistence.

use core::fmt;
use core::str::FromStr;

/// The 3 substrate types in khive OSS (ADR-004).
///
/// - **Note**: temporal-referential records (observations, insights, decisions)
/// - **Entity**: graph nodes with properties and typed links
/// - **Event**: universal system log — every verb execution produces one
#[repr(u8)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum SubstrateKind {
    Note = 0,
    Entity = 1,
    Event = 2,
}

pub const SUBSTRATE_COUNT: usize = 3;

impl SubstrateKind {
    pub const ALL: [SubstrateKind; SUBSTRATE_COUNT] = [
        SubstrateKind::Note,
        SubstrateKind::Entity,
        SubstrateKind::Event,
    ];

    #[inline]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Note => "note",
            Self::Entity => "entity",
            Self::Event => "event",
        }
    }

    #[inline]
    pub const fn from_u8(v: u8) -> Option<Self> {
        match v {
            0 => Some(Self::Note),
            1 => Some(Self::Entity),
            2 => Some(Self::Event),
            _ => None,
        }
    }
}

impl fmt::Display for SubstrateKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

const SUBSTRATE_KIND_VALID: &[&str] = &["note", "entity", "event"];

impl FromStr for SubstrateKind {
    type Err = crate::error::UnknownVariant;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "note" | "Note" => Ok(Self::Note),
            "entity" | "Entity" => Ok(Self::Entity),
            "event" | "Event" => Ok(Self::Event),
            other => Err(crate::error::UnknownVariant::new(
                "substrate_kind",
                other,
                SUBSTRATE_KIND_VALID,
            )),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn all_variants() {
        assert_eq!(SubstrateKind::ALL.len(), SUBSTRATE_COUNT);
        for (i, &kind) in SubstrateKind::ALL.iter().enumerate() {
            assert_eq!(kind as u8, i as u8);
            assert_eq!(SubstrateKind::from_u8(i as u8), Some(kind));
        }
    }

    #[test]
    fn parse_roundtrip() {
        for kind in SubstrateKind::ALL {
            let parsed: SubstrateKind = kind.name().parse().unwrap();
            assert_eq!(parsed, kind);
        }
    }

    #[test]
    fn out_of_range() {
        assert_eq!(SubstrateKind::from_u8(3), None);
        assert_eq!(SubstrateKind::from_u8(255), None);
    }
}