Crate noxu_persist 

Internal component of the noxu database.

This crate is published only so the noxu umbrella crate can depend on it. Use noxu (noxu = "3") in applications; depend on this crate directly only if you are extending the engine internals. Its API may change without a major version bump.

Note on derive macros: #[derive(Entity)], #[derive(PrimaryKey)], and #[derive(SecondaryKey)] emit ::noxu::persist:: paths in generated code by default, so the noxu umbrella crate must be present. Users who depend on noxu-persist directly (without the umbrella) can add #[entity(crate = "noxu_persist")] to each struct to redirect generated code to ::noxu_persist::… instead — see the crate-path escape hatch section below.

Derive-macro-based entity persistence for Noxu DB.

Direct Persistence Layer — provides trait-based entity-to-database mapping with a proc-macro derive shortcut.

Umbrella usage (recommended)

Most users depend on the noxu umbrella crate and use noxu::persist as their import path. The derive macros default to emitting ::noxu::persist::… paths, which works automatically:

use noxu::persist::{Entity, SecondaryKey};

#[derive(Clone, Debug, Entity, SecondaryKey)]
struct User {
    #[primary_key]
    id: u64,
    #[secondary_key(name = "by_email", relate = OneToOne)]
    email: String,
}

Crate-path escape hatch

Users who add noxu-persist as a direct dependency (without the noxu umbrella) can add #[entity(crate = "noxu_persist")] to each annotated struct. Generated code then uses ::noxu_persist::… paths instead, and the umbrella crate is not required.

// Cargo.toml: noxu-persist = "3"  (no noxu umbrella)
use noxu_persist::{Entity, SecondaryKey};

#[derive(Clone, Debug, Entity, SecondaryKey)]
#[entity(crate = "noxu_persist")]
struct Widget {
    #[primary_key]
    id: u64,
    #[secondary_key(name = "by_kind", relate = ManyToOne)]
    kind: String,
}

The same #[entity(crate = "…")] attribute is recognised by all three derives: Entity, PrimaryKey, and SecondaryKey. Any valid Rust module path is accepted; a malformed path produces a descriptive compile error.

Overview

The persistence layer provides typed access to database records through:

• Entity - Trait marking a type as storable
• PrimaryKey - Trait for primary key types
• EntitySerializer - Trait for custom serialization strategies
• PrimaryIndex - Typed CRUD operations on entities by primary key
• EntityStore - Manages databases for entity types
• StoreConfig - Configuration for entity stores

Example

use noxu_persist::*;
use noxu_db::{Environment, EnvironmentConfig};

// Define an entity
struct User { id: u64, name: String }

impl Entity for User {
    type PrimaryKey = u64;
    fn primary_key(&self) -> &u64 { &self.id }
    fn entity_name() -> &'static str { "User" }
}

// Define a serializer
struct UserSerializer;
impl EntitySerializer<User> for UserSerializer {
    fn serialize(&self, user: &User) -> error::Result<Vec<u8>> { /* ... */ }
    fn deserialize(&self, bytes: &[u8]) -> error::Result<User> { /* ... */ }
}

// Use the store
let config = StoreConfig::new("my_store").with_allow_create(true);
// let mut store = EntityStore::open(&env, config)?;
// let index: PrimaryIndex<u64, User> = store.get_primary_index()?;
// index.put(&UserSerializer, &User { id: 1, name: "Alice".into() })?;

Re-exports

pub use entity::Entity;

pub use entity::PrimaryKey;

pub use entity_serializer::EntitySerializer;

pub use entity_store::EntityStore;

pub use error::PersistError;

pub use error::Result;

pub use primary_index::EntityIterator;

pub use primary_index::KeyIterator;

pub use primary_index::PrimaryIndex;

pub use secondary_index::SecondaryIndex;

pub use secondary_spec::DeleteAction;

pub use secondary_spec::Relate;

pub use secondary_spec::SecondarySpec;

pub use sequence::MemorySequence;

pub use sequence::Sequence;

pub use simple_serializer::FieldDecoder;

pub use simple_serializer::FieldEncoder;

pub use simple_serializer::SimpleSerializer;

pub use store_config::StoreConfig;

pub use evolve::CatalogEntry;

pub use evolve::ClassCatalog;

pub use evolve::ClassMutations;

pub use evolve::ConversionFn;

pub use evolve::Converter;

pub use evolve::DecodedRecord;

pub use evolve::Deleter;

pub use evolve::EvolveConfig;

pub use evolve::EvolveListener;

pub use evolve::EvolveStats;

pub use evolve::MAX_CLASS_TAG_LEN;

pub use evolve::MutationKey;

pub use evolve::Mutations;

pub use evolve::Renamer;

pub use evolve::catalog_db_name;

Modules

entity

Entity and key traits for the persistence layer.

entity_serializer

Entity serialization traits.

entity_store

Entity store for managing databases of typed entities.

error

Error types for the persistence layer.

evolve

Schema evolution support for the persistence layer.

primary_index

Primary index for typed entity access.

secondary_index

Secondary index for typed entity access by a non-primary key.

secondary_spec

Compile-time metadata for secondary indexes declared via the #[derive(SecondaryKey)] proc-macro.

sequence

Auto-incrementing sequences for entity ID generation.

simple_serializer

Simple binary serializer for entity persistence.

store_config

Entity store configuration.

Derive Macros

Entity

Derive noxu_persist::Entity for a struct.

PrimaryKey

Derive noxu_persist::PrimaryKey for a custom key struct.

SecondaryKey

Derive secondary-index helpers for fields annotated with #[secondary_key(...)].