index.nct

//! Durable local byte storage with explicit commit and bounded recovery.

use /iter.LendingIterator

see ./journal.nct

see ./journal_format.nct

see ./mutations.nct

see ./store.nct

see ./state.nct

see ./state_index.nct

see ./iteration.nct

see ./tests.nct

/// Resource limits applied before retained state is allocated or published.
pub copy struct StoreLimits

construct StoreLimits {
    /// Returns the ordinary bounded local-store policy.
    pub noalloc func standard(): Self

    /// Constructs an explicit policy or rejects internally inconsistent limits.
    pub noalloc func bounded(
        maximum_key_bytes: usize,
        maximum_value_bytes: usize,
        maximum_entries: usize,
        maximum_snapshot_bytes: usize,
        maximum_journal_bytes: usize,
        maximum_journal_records: usize,
    ): Self!
}

/// One process-exclusive byte-keyed local store.
pub struct Store

/// One borrowed key/value entry yielded from a Store traversal.
pub copy struct StoreEntryRef

instance StoreEntryRef {
    /// Borrows the entry key.
    pub noalloc method &self.key(): &[u8] from self

    /// Borrows the entry value.
    pub noalloc method &self.value(): &[u8] from self
}

/// A lending cursor over Store entries in deterministic insertion order.
pub struct StoreEntries

instance StoreEntries {
    impl LendingIterator { .Item = StoreEntryRef }

    /// Returns the exact number of entries not yet yielded.
    pub noalloc method &self.remaining_len(): usize
}

construct Store {
    /// Opens or creates a store, acquires exclusive ownership, and replays committed state.
    pub async func open(path: &str): Self!

    /// Opens or creates an exclusively owned store with explicit limits.
    pub async func open_with_limits(path: &str, limits: StoreLimits): Self!
}

instance Store {
    /// Returns the number of current key/value entries.
    pub noalloc method &self.len(): usize

    /// Returns whether no current entry exists.
    pub noalloc method &self.is_empty(): bool

    /// Returns the current value for an exact byte key.
    pub noalloc method &self.get(key: &[u8]): &[u8]? from self

    /// Borrows every retained entry in deterministic insertion order without copying.
    pub noalloc method &self.entries(): StoreEntries from self

    /// Copies a key and value into current state without committing it.
    pub method &+self.set(key: &[u8], value: &[u8]): void!

    /// Removes an exact byte key from current state without committing it.
    pub method &+self.remove(key: &[u8]): bool!

    /// Returns whether current state differs from the last successful commit.
    pub noalloc method &self.has_uncommitted_changes(): bool

    /// Returns the last recovered or successfully committed sequence, or zero for none.
    pub noalloc method &self.committed_sequence(): u64

    /// Atomically publishes the bounded staged mutations when state has changed.
    pub async method &+self.commit(): u64!

    /// Replaces committed history with its latest complete snapshot.
    pub async method &+self.compact(): void!

    /// Makes this owner terminal and waits for its journal descriptor retirement.
    pub async method &+self.close(): void!
}