ORM-04: Add ModelState #4

Closed
opened 2026-10-13 12:49:38 +01:00 by NoctisWolfshadow · 0 comments
Owner

Depends on: #3

Context

is_dirty() and save() need to know what a model looked like when it was loaded or last saved. Like Eloquent's original attributes, each model carries a hidden state: ModelState field holding a snapshot of its values.

Tasks

  • pub struct ModelState { original: Option<Vec<Value>> } with new(), Default, Debug, Clone, is_persisted(), pub(crate) snapshot(Vec<Value>) and pub(crate) clear().
  • Manual PartialEq that always returns true, so a derived PartialEq on a model ignores state. A loaded model must still equal an identical freshly built one.
  • Required trait methods fn state(&self) -> &ModelState and fn state_mut(&mut self) -> &mut ModelState.
  • Document that the snapshot holds the non-PK values from insert_values().
  • Update the User fixture: add state: ModelState, User::new initialises it, and the struct literal in it_works is updated.

Example

#[derive(Debug, Clone, Default)]
pub struct ModelState {
    original: Option<Vec<Value>>, // None = never loaded or saved
}

impl ModelState {
    pub fn new() -> Self { Self::default() }
    pub fn is_persisted(&self) -> bool { self.original.is_some() }
    pub(crate) fn snapshot(&mut self, values: Vec<Value>) { self.original = Some(values); }
    pub(crate) fn clear(&mut self) { self.original = None; }
}

impl PartialEq for ModelState {
    fn eq(&self, _: &Self) -> bool { true } // state never affects model equality
}
// tests/common/mod.rs
#[derive(Debug, Clone, PartialEq)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: Option<String>,
    pub age: i64,
    pub active: bool,
    state: ModelState,
}

impl Model for User {
    /* ... */
    fn state(&self) -> &ModelState { &self.state }
    fn state_mut(&mut self) -> &mut ModelState { &mut self.state }
}
// unit test in src/state.rs (snapshot is pub(crate))
#[test]
fn state_is_ignored_by_equality() {
    let mut a = ModelState::new();
    let b = ModelState::new();
    a.snapshot(vec![Value::Integer(1)]);
    assert!(a.is_persisted() && !b.is_persisted());
    assert_eq!(a, b);
}

Acceptance criteria

  • A default state is not persisted; after snapshot it is.
  • Two states with different snapshots compare equal.
  • clone keeps the snapshot.
  • Existing tests pass with the updated fixture.

Notes

Because state is a field, struct literals must supply it (ModelState::new()). Prefer constructor functions like User::new(..). A derive macro that hides this is in the backlog.

**Depends on:** #3 ## Context `is_dirty()` and `save()` need to know what a model looked like when it was loaded or last saved. Like Eloquent's original attributes, each model carries a hidden `state: ModelState` field holding a snapshot of its values. ## Tasks - [x] `pub struct ModelState { original: Option<Vec<Value>> }` with `new()`, `Default`, `Debug`, `Clone`, `is_persisted()`, `pub(crate) snapshot(Vec<Value>)` and `pub(crate) clear()`. - [x] Manual `PartialEq` that always returns true, so a derived `PartialEq` on a model ignores state. A loaded model must still equal an identical freshly built one. - [x] Required trait methods `fn state(&self) -> &ModelState` and `fn state_mut(&mut self) -> &mut ModelState`. - [x] Document that the snapshot holds the non-PK values from `insert_values()`. - [x] Update the `User` fixture: add `state: ModelState`, `User::new` initialises it, and the struct literal in `it_works` is updated. ## Example ```rust #[derive(Debug, Clone, Default)] pub struct ModelState { original: Option<Vec<Value>>, // None = never loaded or saved } impl ModelState { pub fn new() -> Self { Self::default() } pub fn is_persisted(&self) -> bool { self.original.is_some() } pub(crate) fn snapshot(&mut self, values: Vec<Value>) { self.original = Some(values); } pub(crate) fn clear(&mut self) { self.original = None; } } impl PartialEq for ModelState { fn eq(&self, _: &Self) -> bool { true } // state never affects model equality } ``` ```rust // tests/common/mod.rs #[derive(Debug, Clone, PartialEq)] pub struct User { pub id: i64, pub name: String, pub email: Option<String>, pub age: i64, pub active: bool, state: ModelState, } impl Model for User { /* ... */ fn state(&self) -> &ModelState { &self.state } fn state_mut(&mut self) -> &mut ModelState { &mut self.state } } ``` ```rust // unit test in src/state.rs (snapshot is pub(crate)) #[test] fn state_is_ignored_by_equality() { let mut a = ModelState::new(); let b = ModelState::new(); a.snapshot(vec![Value::Integer(1)]); assert!(a.is_persisted() && !b.is_persisted()); assert_eq!(a, b); } ``` ## Acceptance criteria - [x] A default state is not persisted; after `snapshot` it is. - [x] Two states with different snapshots compare equal. - [x] `clone` keeps the snapshot. - [x] Existing tests pass with the updated fixture. ## Notes Because `state` is a field, struct literals must supply it (`ModelState::new()`). Prefer constructor functions like `User::new(..)`. A derive macro that hides this is in the backlog.
Sign in to join this conversation.
No description provided.