vsdb 17.0.15

//!
//! A `HashMap`-like structure that stores data on disk.
//!
//! `Mapx` provides a key-value store where both keys and values are encoded
//! using `serde`-like methods before being persisted. This allows for storing
//! complex data types while maintaining a familiar `HashMap` interface.
//!
//! # Examples
//!
//! ```
//! use vsdb::{Mapx, VsdbOptions, vsdb_configure, vsdb_get_base_dir};
//! use std::fs;
//!
//! // It's recommended to use a temporary directory for testing
//! let dir = format!("/tmp/vsdb_testing/{}", rand::random::<u128>());
//! vsdb_configure(VsdbOptions::new(&dir)).unwrap();
//!
//! let mut m: Mapx<i32, String> = Mapx::new();
//!
//! // Insert key-value pairs
//! m.insert(&1, &"hello".to_string());
//! m.insert(&2, &"world".to_string());
//!
//! // Retrieve a value
//! assert_eq!(m.get(&1), Some("hello".to_string()));
//!
//! // Iterate over the map
//! for (k, v) in m.iter() {
//!     println!("key: {}, val: {}", k, v);
//! }
//!
//! // Remove a key-value pair
//! m.remove(&2);
//!
//! // Clear the entire map
//! m.clear();
//!
//! // Clean up the directory
//! fs::remove_dir_all(vsdb_get_base_dir()).unwrap();
//! ```
//!

#[cfg(test)]
mod test;

use crate::{
    basic::{
        mapx_ord::{Entry, MapxOrdValues, MapxOrdValuesMut},
        mapx_ord_rawkey::{
            self, MapxOrdRawKey, MapxOrdRawKeyBatch, MapxOrdRawKeyIter,
            MapxOrdRawKeyIterMut, ValueMut,
        },
    },
    common::{
        RawBytes,
        ende::{KeyEnDe, KeyRef, ValueEnDe},
        error::Result,
        macros::define_map_wrapper,
    },
};
use std::{
    borrow::Borrow,
    marker::PhantomData,
    ops::{Deref, DerefMut},
};

define_map_wrapper! {
    #[doc = "A disk-based, `HashMap`-like data structure with typed keys and values."]
    #[doc = ""]
    #[doc = "`Mapx` stores key-value pairs on disk, encoding both keys and values"]
    #[doc = "for type safety and persistence."]
    #[doc = ""]
    #[doc = "# Key determinism"]
    #[doc = ""]
    #[doc = "`K` must encode deterministically. Do not use `HashMap`, `HashSet`,"]
    #[doc = "or wrappers containing them as keys; their randomized iteration order"]
    #[doc = "can produce different storage bytes for logically equal keys."]
    pub struct Mapx<K, V> {
        inner: MapxOrdRawKey<V>,
        _p: PhantomData<K>,
    }
    where K: KeyEnDe, V: ValueEnDe
}

impl<K, V> Mapx<K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    /// Retrieves a value from the map for a given key.
    ///
    /// Supports `&str` for `String` keys and `&[u8]` for `Vec<u8>`,
    /// `Box<[u8]>`, or `[u8; N]` keys. Array queries must have length `N`;
    /// other lengths miss. Other borrowed forms must satisfy [`KeyRef`]'s
    /// encoding contract.
    #[inline(always)]
    pub fn get<Q>(&self, key: &Q) -> Option<V>
    where
        K: Borrow<Q>,
        Q: KeyRef + ?Sized,
    {
        self.inner.get(Self::query_bytes(key)?)
    }

    /// Retrieves a mutable reference to a value in the map (borrowed key
    /// forms as in [`get`](Self::get)).
    #[inline(always)]
    pub fn get_mut<Q>(&mut self, key: &Q) -> Option<ValueMut<'_, V>>
    where
        K: Borrow<Q>,
        Q: KeyRef + ?Sized,
    {
        self.inner.get_mut(Self::query_bytes(key)?)
    }

    /// Checks if the map contains a value for the specified key (borrowed
    /// key forms as in [`get`](Self::get)).
    #[inline(always)]
    pub fn contains_key<Q>(&self, key: &Q) -> bool
    where
        K: Borrow<Q>,
        Q: KeyRef + ?Sized,
    {
        Self::query_bytes(key).is_some_and(|bytes| self.inner.contains_key(bytes))
    }

    /// Inserts a key-value pair into the map.
    ///
    /// Does not return the old value for performance reasons.
    #[inline(always)]
    pub fn insert(&mut self, key: &K, value: &V) {
        self.inner.insert(key.encode(), value)
    }

    /// Gets an entry for a given key, allowing for in-place modification.
    #[inline(always)]
    pub fn entry(&mut self, key: &K) -> Entry<'_, V> {
        Entry {
            key: key.encode(),
            hdr: &mut self.inner,
        }
    }

    /// Returns an iterator over the map's entries.
    #[inline(always)]
    pub fn iter(&self) -> MapxIter<'_, K, V> {
        MapxIter {
            iter: self.inner.iter(),
            _p: PhantomData,
        }
    }

    /// Returns a mutable iterator over the map's entries.
    #[inline(always)]
    pub fn iter_mut(&mut self) -> MapxIterMut<'_, K, V> {
        MapxIterMut {
            inner: self.inner.iter_mut(),
            _p: PhantomData,
        }
    }

    /// Returns an iterator over the map's values.
    #[inline(always)]
    pub fn values(&self) -> MapxValues<'_, V> {
        MapxValues {
            inner: self.inner.iter(),
        }
    }

    /// Returns a mutable iterator over the map's values.
    #[inline(always)]
    pub fn values_mut(&mut self) -> MapxValuesMut<'_, V> {
        MapxValuesMut {
            inner: self.inner.iter_mut(),
            _p: PhantomData,
        }
    }

    /// Removes a key from the map (borrowed key forms as in
    /// [`get`](Self::get)).
    ///
    /// Does not return the old value for performance reasons.
    #[inline(always)]
    pub fn remove<Q>(&mut self, key: &Q)
    where
        K: Borrow<Q>,
        Q: KeyRef + ?Sized,
    {
        if let Some(bytes) = Self::query_bytes(key) {
            self.inner.remove(bytes);
        }
    }

    fn query_bytes<Q>(key: &Q) -> Option<RawBytes>
    where
        K: Borrow<Q>,
        Q: KeyRef + ?Sized,
    {
        let Some(slice) = key.as_byte_slice() else {
            return Some(key.key_bytes());
        };
        // Borrow alone does not imply identical encodings: arrays encode
        // as tuples, while Vec/Box slices encode with a length prefix.
        // Resolve through K and verify its borrowed contents before any
        // storage access. Decoders may accept trailing bytes, so successful
        // decoding alone cannot establish that this is the requested key.
        let matches = |owned: &K| owned.borrow().as_byte_slice() == Some(slice);
        if let Ok(owned) = K::decode(slice)
            && matches(&owned)
        {
            return Some(owned.encode());
        }
        let owned = K::decode(&key.key_bytes()).ok()?;
        matches(&owned).then(|| owned.encode())
    }

    /// Start a batch operation.
    ///
    /// This method allows you to perform multiple insert/remove operations
    /// and commit them atomically.
    ///
    /// A failed [`commit`](MapxBatch::commit) consumes
    /// the buffered operations. Preflight rejections leave them unapplied;
    /// persistence errors can be ambiguous after recovery and must not be
    /// retried automatically.
    ///
    /// # Examples
    ///
    /// ```
    /// use vsdb::{Mapx, VsdbOptions, vsdb_configure};
    ///
    /// let dir = std::env::temp_dir()
    ///     .join(format!("vsdb_mapx_batch_{}", rand::random::<u128>()));
    /// vsdb_configure(VsdbOptions::new(&dir)).unwrap();
    /// let mut map = Mapx::new();
    ///
    /// let mut batch = map.batch();
    /// batch.insert(&1, &"one".to_string());
    /// batch.insert(&2, &"two".to_string());
    /// batch.commit().unwrap();
    ///
    /// assert_eq!(map.get(&1), Some("one".to_string()));
    /// assert_eq!(map.get(&2), Some("two".to_string()));
    /// # std::fs::remove_dir_all(dir).unwrap();
    /// ```
    #[inline(always)]
    pub fn batch(&mut self) -> MapxBatch<'_, K, V> {
        MapxBatch {
            inner: self.inner.batch(),
            _marker: PhantomData,
        }
    }

    /// Returns an iterator over the map's keys.
    ///
    /// Decodes only `K` — unlike `iter().map(|(k, _)| k)`, the value
    /// bytes are never decoded and discarded (see
    /// `MapxOrdRawKey::keys`'s doc comment for why this matters for
    /// nested-VSDB-collection value types).
    #[inline(always)]
    pub fn keys(&self) -> impl DoubleEndedIterator<Item = K> + '_ {
        self.inner.keys().map(|k| K::decode(&k).unwrap())
    }
}

impl<'a, K, V> IntoIterator for &'a Mapx<K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    type Item = (K, V);
    type IntoIter = MapxIter<'a, K, V>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////

// Hand-written rather than `#[derive(PartialEq, Eq)]`: a derive would
// compare the *encoded* bytes of both `K` and `V` (postcard encoding is
// not injective on decoded value in general — e.g. `0.0_f64` and
// `-0.0_f64` encode to different bytes despite comparing equal, while
// distinct NaN bit patterns can compare unequal despite identical
// bytes), silently diverging from `K`/`V`'s own logical `PartialEq`.
// Comparing through `self.inner` (raw key bytes + *decoded* `V`)
// side-steps needing `K: PartialEq` at all — `K`'s encoding is already
// required to be deterministic and injective for the map's basic
// correctness, so byte-identical keys are logically identical keys —
// while still fixing the decoded-value comparison for `V`.
impl<K, V> PartialEq for Mapx<K, V>
where
    K: KeyEnDe,
    V: ValueEnDe + PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        self.inner.iter().eq(other.inner.iter())
    }
}

impl<K, V> Eq for Mapx<K, V>
where
    K: KeyEnDe,
    V: ValueEnDe + Eq,
{
}

////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////

impl<'a, K, V> IntoIterator for &'a mut Mapx<K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    type Item = (K, ValueIterMut<'a, V>);
    type IntoIter = MapxIterMut<'a, K, V>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter_mut()
    }
}

/// A batch entry for `Mapx`.
pub struct MapxBatch<'a, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    inner: MapxOrdRawKeyBatch<'a, V>,
    _marker: PhantomData<K>,
}

impl<'a, K, V> MapxBatch<'a, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    /// Insert a key-value pair into the batch.
    pub fn insert(&mut self, key: &K, value: &V) {
        self.inner.insert(key.encode(), value);
    }

    /// Remove a key in the batch.
    pub fn remove(&mut self, key: &K) {
        self.inner.remove(key.encode());
    }

    /// Commit the batch.
    pub fn commit(self) -> Result<()> {
        self.inner.commit()
    }

    /// Atomically publishes the batch after synchronizing its shard WAL.
    /// An empty batch does not fence earlier writes. Persistence failures can
    /// be ambiguous after recovery; they must not be retried automatically.
    pub fn commit_sync(self) -> Result<()> {
        self.inner.commit_sync()
    }
}

/////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////

/// An iterator over the entries of a `Mapx`.
pub struct MapxIter<'a, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    iter: MapxOrdRawKeyIter<'a, V>,
    _p: PhantomData<K>,
}

impl<K, V> Iterator for MapxIter<'_, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    type Item = (K, V);
    fn next(&mut self) -> Option<Self::Item> {
        self.iter
            .next()
            .map(|(k, v)| (<K as KeyEnDe>::decode(&k).unwrap(), v))
    }
}

impl<K, V> DoubleEndedIterator for MapxIter<'_, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    fn next_back(&mut self) -> Option<Self::Item> {
        self.iter
            .next_back()
            .map(|(k, v)| (<K as KeyEnDe>::decode(&k).unwrap(), v))
    }
}

/////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////

/// A mutable iterator over the entries of a `Mapx`.
pub struct MapxIterMut<'a, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    inner: MapxOrdRawKeyIterMut<'a, V>,
    _p: PhantomData<K>,
}

impl<'a, K, V> Iterator for MapxIterMut<'a, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    type Item = (K, ValueIterMut<'a, V>);
    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next().map(|(k, v)| {
            (
                <K as KeyEnDe>::decode(&k).unwrap(),
                ValueIterMut { inner: v },
            )
        })
    }
}

impl<K, V> DoubleEndedIterator for MapxIterMut<'_, K, V>
where
    K: KeyEnDe,
    V: ValueEnDe,
{
    fn next_back(&mut self) -> Option<Self::Item> {
        self.inner.next_back().map(|(k, v)| {
            (
                <K as KeyEnDe>::decode(&k).unwrap(),
                ValueIterMut { inner: v },
            )
        })
    }
}

/////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////

type MapxValues<'a, V> = MapxOrdValues<'a, V>;
type MapxValuesMut<'a, V> = MapxOrdValuesMut<'a, V>;

/// A mutable reference to a value in a `Mapx` iterator.
#[derive(Debug)]
pub struct ValueIterMut<'a, V>
where
    V: ValueEnDe,
{
    /// The inner mutable reference to the value.
    pub(crate) inner: mapx_ord_rawkey::ValueIterMut<'a, V>,
}

impl<V> Deref for ValueIterMut<'_, V>
where
    V: ValueEnDe,
{
    type Target = V;
    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl<V> DerefMut for ValueIterMut<'_, V>
where
    V: ValueEnDe,
{
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.inner
    }
}