edgevec 0.9.0

High-performance embedded vector database for Browser, Node, and Edge
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! Error types for sparse vector operations.

use thiserror::Error;

/// Errors that can occur during sparse vector operations.
#[derive(Error, Debug, Clone, PartialEq)]
pub enum SparseError {
    /// Indices are not sorted in ascending order.
    #[error("indices must be sorted in ascending order")]
    UnsortedIndices,

    /// Duplicate index found at the specified position.
    #[error("duplicate index at position {0}")]
    DuplicateIndex(usize),

    /// Index exceeds the vector dimension.
    #[error("index {index} exceeds dimension {dim}")]
    IndexOutOfBounds {
        /// The invalid index value.
        index: u32,
        /// The maximum allowed dimension.
        dim: u32,
    },

    /// Value at index is NaN or Infinity.
    #[error("value at index {0} is NaN or Infinity")]
    InvalidValue(usize),

    /// Sparse vector must have at least one element.
    #[error("sparse vector must have at least one element")]
    EmptyVector,

    /// Indices and values arrays have different lengths.
    #[error("indices and values length mismatch: {indices} vs {values}")]
    LengthMismatch {
        /// Length of indices array.
        indices: usize,
        /// Length of values array.
        values: usize,
    },

    /// Sparse ID not found in storage.
    #[error("sparse ID {0} not found")]
    IdNotFound(u64),

    /// Cannot normalize a zero vector.
    #[error("cannot normalize zero vector")]
    ZeroNorm,

    /// IO error during save/load operations.
    #[error("IO error: {0}")]
    Io(String),

    /// Invalid magic number in file header.
    #[error("invalid magic number: expected {expected:?}, found {found:?}")]
    InvalidMagic {
        /// Expected magic bytes.
        expected: [u8; 4],
        /// Found magic bytes.
        found: [u8; 4],
    },

    /// Unsupported format version.
    #[error("unsupported format version: expected {expected}, found {found}")]
    UnsupportedVersion {
        /// Expected version number.
        expected: u32,
        /// Found version number.
        found: u32,
    },

    /// Data corruption detected during load.
    #[error("corrupted data: {0}")]
    CorruptedData(String),

    /// ID counter overflow (u64::MAX reached).
    #[error("ID counter overflow: cannot assign more IDs (u64::MAX reached)")]
    IdOverflow,
}

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

    #[test]
    fn test_error_display_unsorted() {
        let err = SparseError::UnsortedIndices;
        assert!(err.to_string().contains("sorted"));
    }

    #[test]
    fn test_error_display_duplicate() {
        let err = SparseError::DuplicateIndex(5);
        assert!(err.to_string().contains('5'));
    }

    #[test]
    fn test_error_display_out_of_bounds() {
        let err = SparseError::IndexOutOfBounds {
            index: 100,
            dim: 50,
        };
        assert!(err.to_string().contains("100"));
        assert!(err.to_string().contains("50"));
    }

    #[test]
    fn test_error_display_invalid_value() {
        let err = SparseError::InvalidValue(3);
        assert!(err.to_string().contains('3'));
    }

    #[test]
    fn test_error_display_empty() {
        let err = SparseError::EmptyVector;
        assert!(err.to_string().contains("at least one"));
    }

    #[test]
    fn test_error_display_length_mismatch() {
        let err = SparseError::LengthMismatch {
            indices: 5,
            values: 3,
        };
        assert!(err.to_string().contains('5'));
        assert!(err.to_string().contains('3'));
    }

    #[test]
    fn test_error_display_id_not_found() {
        let err = SparseError::IdNotFound(42);
        assert!(err.to_string().contains("42"));
    }

    #[test]
    fn test_error_display_zero_norm() {
        let err = SparseError::ZeroNorm;
        assert!(err.to_string().contains("zero"));
    }

    #[test]
    fn test_error_display_id_overflow() {
        let err = SparseError::IdOverflow;
        assert!(err.to_string().contains("overflow"));
    }
}