vecstore 1.0.0

//! WASM-compatible vector search backend
//!
//! This module provides a high-performance HNSW vector search implementation for WASM targets.
//! Unlike the native hnsw_rs which requires memory-mapped files, this uses a pure in-memory
//! HNSW implementation that works perfectly in browsers.
//!
//! ## Performance
//!
//! - **Search**: O(log N) complexity, sub-millisecond queries on 100k+ vectors
//! - **Memory**: ~4-8 bytes per edge + vector storage
//! - **Suitable for**: Browser applications with up to millions of vectors
//!
//! For server deployments, the native build automatically uses hnsw_rs with memory-mapped files
//! for even better performance with very large datasets (>10M vectors).

use crate::store::types::{Distance, Id};
use crate::store::wasm_hnsw::WasmHnsw;
use anyhow::Result;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::Path;

/// WASM vector backend using in-memory HNSW
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WasmVectorBackend {
    /// WASM-compatible HNSW index
    hnsw: WasmHnsw,

    /// ID mappings (for compatibility with HNSW backend, not actively used)
    id_to_idx: HashMap<Id, usize>,
    idx_to_id: HashMap<usize, Id>,
    next_idx: usize,
}

impl WasmVectorBackend {
    /// Create a new WASM vector backend with HNSW index
    /// Defaults to Cosine similarity to match native HNSW backend behavior
    pub fn new(dimension: usize) -> Self {
        Self::with_params(dimension, Distance::Cosine, 16, 200)
    }

    /// Create with custom HNSW parameters
    ///
    /// # Arguments
    /// * `dimension` - Vector dimension
    /// * `metric` - Distance metric
    /// * `m` - Number of connections per layer (8-64, default 16)
    /// * `ef_construction` - Construction quality (100-500, default 200)
    pub fn with_params(
        dimension: usize,
        metric: Distance,
        m: usize,
        ef_construction: usize,
    ) -> Self {
        Self {
            hnsw: WasmHnsw::with_params(dimension, metric, m, ef_construction),
            id_to_idx: HashMap::new(),
            idx_to_id: HashMap::new(),
            next_idx: 0,
        }
    }

    /// Insert or update a vector
    pub fn insert(&mut self, id: Id, vector: &[f32]) -> Result<()> {
        self.hnsw.insert(id, vector.to_vec())
    }

    /// Batch insert vectors
    pub fn batch_insert(&mut self, items: Vec<(Id, Vec<f32>)>) -> Result<()> {
        for (id, vector) in items {
            self.insert(id, &vector)?;
        }
        Ok(())
    }

    /// Optimize the index (no-op for WASM HNSW, already optimized during construction)
    pub fn optimize(&mut self, _vectors: &[(Id, Vec<f32>)]) -> Result<usize> {
        Ok(self.hnsw.len())
    }

    /// Delete a vector by ID
    pub fn remove(&mut self, id: &str) -> Result<()> {
        self.hnsw.remove(id)
    }

    /// Search for nearest neighbors
    ///
    /// Uses HNSW graph traversal for efficient O(log N) search
    pub fn search(&self, query: &[f32], k: usize) -> Result<Vec<(Id, f32)>> {
        // Default ef_search = max(k, 50) for good recall
        let ef_search = k.max(50);
        self.search_with_ef(query, k, ef_search)
    }

    /// Search with custom ef parameter for performance/quality tuning
    ///
    /// # Arguments
    /// * `query` - Query vector
    /// * `k` - Number of results to return
    /// * `ef_search` - Search quality parameter (higher = better recall, slower)
    ///
    /// Typical values:
    /// - Fast search: ef_search = k
    /// - Balanced: ef_search = 50-100
    /// - High recall: ef_search = 200-500
    pub fn search_with_ef(
        &self,
        query: &[f32],
        k: usize,
        ef_search: usize,
    ) -> Result<Vec<(Id, f32)>> {
        self.hnsw.search(query, k, ef_search)
    }

    /// Save index to disk (no-op for WASM backend)
    ///
    /// WASM backend doesn't support file I/O. Use VecStore's serialization
    /// methods to persist to browser storage (IndexedDB, localStorage, etc.)
    pub fn save_index(&self, _path: &Path) -> Result<()> {
        Ok(())
    }

    /// Rebuild index from vectors
    pub fn rebuild_from_vectors(&mut self, vectors: &[(Id, Vec<f32>)]) -> Result<()> {
        self.hnsw.clear();
        for (id, vector) in vectors {
            self.insert(id.clone(), vector)?;
        }
        Ok(())
    }

    /// Get ID to index mapping (for compatibility, not used in WASM backend)
    pub fn get_id_to_idx_map(&self) -> &HashMap<Id, usize> {
        &self.id_to_idx
    }

    /// Get index to ID mapping (for compatibility, not used in WASM backend)
    pub fn get_idx_to_id_map(&self) -> &HashMap<usize, Id> {
        &self.idx_to_id
    }

    /// Set ID mappings (for compatibility with native HNSW backend)
    pub fn set_mappings(
        &mut self,
        id_to_idx: HashMap<Id, usize>,
        idx_to_id: HashMap<usize, Id>,
        next_idx: usize,
    ) {
        self.id_to_idx = id_to_idx;
        self.idx_to_id = idx_to_id;
        self.next_idx = next_idx;
    }

    /// Restore backend from saved state
    pub fn restore(
        dimension: usize,
        id_to_idx: HashMap<Id, usize>,
        idx_to_id: HashMap<usize, Id>,
        next_idx: usize,
    ) -> Result<Self> {
        let mut backend = Self::new(dimension);
        backend.set_mappings(id_to_idx, idx_to_id, next_idx);
        Ok(backend)
    }

    /// Get the number of vectors stored
    pub fn len(&self) -> usize {
        self.hnsw.len()
    }

    /// Check if the backend is empty
    pub fn is_empty(&self) -> bool {
        self.hnsw.is_empty()
    }

    /// Get the dimension of vectors
    pub fn dimension(&self) -> usize {
        // Access dimension through hnsw stats
        self.hnsw.stats().num_nodes
    }

    /// Get all vector IDs
    pub fn ids(&self) -> Vec<Id> {
        self.hnsw.ids()
    }

    /// Clear all vectors
    pub fn clear(&mut self) {
        self.hnsw.clear();
    }

    /// Get HNSW index statistics
    pub fn stats(&self) -> String {
        let stats = self.hnsw.stats();
        format!(
            "WASM HNSW Stats:\n\
             - Nodes: {}\n\
             - Edges: {}\n\
             - Max Layer: {}\n\
             - M: {}\n\
             - ef_construction: {}\n\
             - Layer distribution: {:?}",
            stats.num_nodes,
            stats.num_edges,
            stats.max_layer,
            stats.m,
            stats.ef_construction,
            stats.layer_distribution
        )
    }

    /// Create a graph visualizer for the HNSW index
    ///
    /// This allows exporting the graph structure to various formats for visualization.
    ///
    /// # Example
    /// ```no_run
    /// # use vecstore::store::wasm_backend::WasmVectorBackend;
    /// let mut backend = WasmVectorBackend::new(128);
    /// // ... insert vectors ...
    ///
    /// let viz = backend.to_visualizer()?;
    /// let dot = viz.export_dot()?;
    /// std::fs::write("graph.dot", dot)?;
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn to_visualizer(&self) -> Result<crate::graph_viz::HnswVisualizer> {
        Ok(self.hnsw.to_visualizer())
    }
}

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

    #[test]
    fn test_wasm_backend_hnsw() {
        let mut backend = WasmVectorBackend::new(3);

        // Insert vectors
        backend
            .insert("v1".to_string(), &vec![1.0, 0.0, 0.0])
            .unwrap();
        backend
            .insert("v2".to_string(), &vec![0.0, 1.0, 0.0])
            .unwrap();
        backend
            .insert("v3".to_string(), &vec![1.0, 1.0, 0.0])
            .unwrap();
        backend
            .insert("v4".to_string(), &vec![0.5, 0.5, 0.0])
            .unwrap();

        assert_eq!(backend.len(), 4);

        // Search should find nearest neighbor
        let results = backend.search(&[1.0, 0.1, 0.0], 2).unwrap();
        assert_eq!(results.len(), 2);
        assert_eq!(results[0].0, "v1"); // Closest match

        // Stats should show HNSW structure
        println!("{}", backend.stats());
    }

    #[test]
    fn test_wasm_backend_delete() {
        let mut backend = WasmVectorBackend::new(2);

        backend.insert("v1".to_string(), &vec![1.0, 2.0]).unwrap();
        backend.insert("v2".to_string(), &vec![3.0, 4.0]).unwrap();
        backend.insert("v3".to_string(), &vec![5.0, 6.0]).unwrap();

        assert_eq!(backend.len(), 3);

        backend.remove("v1").unwrap();
        assert_eq!(backend.len(), 2);

        let results = backend.search(&[1.0, 2.0], 3).unwrap();
        assert_eq!(results.len(), 2); // Only v2 and v3 remain
    }

    #[test]
    fn test_wasm_backend_batch() {
        let mut backend = WasmVectorBackend::new(4);

        let batch = vec![
            ("v1".to_string(), vec![1.0, 0.0, 0.0, 0.0]),
            ("v2".to_string(), vec![0.0, 1.0, 0.0, 0.0]),
            ("v3".to_string(), vec![0.0, 0.0, 1.0, 0.0]),
            ("v4".to_string(), vec![0.0, 0.0, 0.0, 1.0]),
        ];

        backend.batch_insert(batch).unwrap();
        assert_eq!(backend.len(), 4);

        let results = backend.search(&[1.0, 0.0, 0.0, 0.0], 2).unwrap();
        assert_eq!(results[0].0, "v1");
    }

    #[test]
    fn test_dimension_validation() {
        let mut backend = WasmVectorBackend::new(3);

        // Wrong dimension should fail
        let result = backend.insert("v1".to_string(), &vec![1.0, 2.0]);
        assert!(result.is_err());

        // Correct dimension should work
        let result = backend.insert("v1".to_string(), &vec![1.0, 2.0, 3.0]);
        assert!(result.is_ok());
    }

    #[test]
    fn test_large_scale() {
        use rand::Rng;
        let mut backend = WasmVectorBackend::with_params(128, Distance::Cosine, 16, 200);
        let mut rng = rand::thread_rng();

        // Insert 1000 vectors
        for i in 0..1000 {
            let vector: Vec<f32> = (0..128).map(|_| rng.gen()).collect();
            backend.insert(format!("v{}", i), &vector).unwrap();
        }

        assert_eq!(backend.len(), 1000);

        // Search should be fast and accurate
        let query: Vec<f32> = (0..128).map(|_| rng.gen()).collect();
        let results = backend.search(&query, 10).unwrap();
        assert_eq!(results.len(), 10);

        // Results should be sorted by distance
        for i in 1..results.len() {
            assert!(results[i].1 >= results[i - 1].1);
        }

        println!("{}", backend.stats());
    }
}