@an5/adapters 0.2.5 → 0.2.9

package/rust/src/base/dialect.rs

@@ -0,0 +1,172 @@
+//! Dialect detection, identifier quoting and vector math.
+//!
+//! Mirrors the Go `an5adapters/base` package.
+
+/// Supported database engines.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Dialect {
+    Mssql,
+    Postgres,
+    Sqlite,
+}
+
+impl Dialect {
+    /// Detect the dialect from a connection string.
+    pub fn detect(conn_str: &str) -> Self {
+        let l = conn_str.trim().to_lowercase();
+        if l.starts_with("postgres://")
+            || l.starts_with("postgresql://")
+            || l.contains("port=5432")
+        {
+            return Dialect::Postgres;
+        }
+        if l.starts_with("sqlite://")
+            || l.starts_with("sqlite:")
+            || l.starts_with("file:")
+            || l.ends_with(".db")
+            || l.ends_with(".sqlite")
+            || l.ends_with(".sqlite3")
+            || l == ":memory:"
+        {
+            return Dialect::Sqlite;
+        }
+        Dialect::Mssql
+    }
+
+    /// Quote a single identifier (column or table part).
+    pub fn quote_identifier(&self, name: &str) -> String {
+        let raw = strip_wrapping(strip_wrapping(name, "[", "]"), "\"", "\"");
+        match self {
+            Dialect::Postgres | Dialect::Sqlite => {
+                format!("\"{}\"", raw.replace('"', "\"\""))
+            }
+            Dialect::Mssql => format!("[{}]", raw.replace(']', "]]")),
+        }
+    }
+
+    /// Quote a possibly schema-qualified table name (`dbo.users`).
+    pub fn quote_table(&self, table: &str) -> String {
+        let t = table.trim();
+        // Already quoted by the generator: `[dbo].[User]`.
+        if t.starts_with('[') || t.starts_with('"') {
+            return t.to_string();
+        }
+        t.split('.')
+            .map(|p| self.quote_identifier(p))
+            .collect::<Vec<_>>()
+            .join(".")
+    }
+
+    /// Positional placeholder: `$N` for Postgres, `?` otherwise.
+    pub fn placeholder(&self, n: usize) -> String {
+        match self {
+            Dialect::Postgres => format!("${}", n),
+            _ => "?".to_string(),
+        }
+    }
+
+    /// MSSQL read hint used on every SELECT.
+    pub fn nolock(&self) -> &'static str {
+        match self {
+            Dialect::Mssql => " WITH (NOLOCK)",
+            _ => "",
+        }
+    }
+
+    /// Dialects that use `LIMIT` / `OFFSET` instead of `TOP` / `FETCH NEXT`.
+    pub fn supports_limit_offset(&self) -> bool {
+        matches!(self, Dialect::Postgres | Dialect::Sqlite)
+    }
+}
+
+fn strip_wrapping<'a>(name: &'a str, left: &str, right: &str) -> &'a str {
+    if name.starts_with(left) && name.ends_with(right) && name.len() >= left.len() + right.len() {
+        &name[left.len()..name.len() - right.len()]
+    } else {
+        name
+    }
+}
+
+/// Cosine similarity between two vectors (1.0 = identical direction).
+pub fn cosine_similarity(a: &[f64], b: &[f64]) -> f64 {
+    if a.len() != b.len() || a.is_empty() {
+        return 0.0;
+    }
+    let mut dot = 0.0;
+    let mut m1 = 0.0;
+    let mut m2 = 0.0;
+    for i in 0..a.len() {
+        dot += a[i] * b[i];
+        m1 += a[i] * a[i];
+        m2 += b[i] * b[i];
+    }
+    if m1 == 0.0 || m2 == 0.0 {
+        return 0.0;
+    }
+    dot / (m1.sqrt() * m2.sqrt())
+}
+
+/// Euclidean distance between two vectors.
+pub fn euclidean_distance(a: &[f64], b: &[f64]) -> f64 {
+    a.iter()
+        .zip(b.iter())
+        .map(|(x, y)| (x - y) * (x - y))
+        .sum::<f64>()
+        .sqrt()
+}
+
+/// Dot product of two vectors.
+pub fn dot_product(a: &[f64], b: &[f64]) -> f64 {
+    a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
+}
+
+/// Distance honouring the AN5 metric names (`cosine` / `euclidean` / `dot`).
+pub fn vector_distance(a: &[f64], b: &[f64], metric: &str) -> f64 {
+    match metric.to_lowercase().as_str() {
+        "euclidean" => euclidean_distance(a, b),
+        "dot" => -dot_product(a, b),
+        _ => 1.0 - cosine_similarity(a, b),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn detects_dialects() {
+        assert_eq!(
+            Dialect::detect("postgres://localhost/db"),
+            Dialect::Postgres
+        );
+        assert_eq!(Dialect::detect("app.db"), Dialect::Sqlite);
+        assert_eq!(
+            Dialect::detect("Server=localhost;Database=master;"),
+            Dialect::Mssql
+        );
+    }
+
+    #[test]
+    fn quotes_identifiers_per_dialect() {
+        assert_eq!(Dialect::Mssql.quote_identifier("id"), "[id]");
+        assert_eq!(Dialect::Postgres.quote_identifier("id"), "\"id\"");
+    }
+
+    #[test]
+    fn keeps_generator_quoted_table() {
+        assert_eq!(Dialect::Mssql.quote_table("[dbo].[User]"), "[dbo].[User]");
+        assert_eq!(Dialect::Postgres.quote_table("dbo.users"), "\"dbo\".\"users\"");
+    }
+
+    #[test]
+    fn placeholders_per_dialect() {
+        assert_eq!(Dialect::Postgres.placeholder(2), "$2");
+        assert_eq!(Dialect::Mssql.placeholder(2), "?");
+    }
+
+    #[test]
+    fn cosine_identical_is_one() {
+        let v = vec![1.0, 0.0];
+        assert!((cosine_similarity(&v, &v) - 1.0).abs() < 1e-9);
+    }
+}

package/rust/src/base/metadata.rs

@@ -0,0 +1,134 @@
+//! Adapter metadata injected by the generated `an5Client` crate.
+//!
+//! Mirrors the Go `an5adapters/base` metadata store.
+
+use std::collections::HashMap;
+use std::sync::{OnceLock, RwLock};
+
+/// Describes a model relation, used for eager-loading (`include`) support.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RelationDef {
+    pub model_name: String,
+    /// `many` or `one`.
+    pub relation_type: String,
+    pub foreign_key: String,
+    pub local_key: String,
+}
+
+/// Metadata bundle provided by the generated client.
+#[derive(Debug, Clone, Default)]
+pub struct AdapterMetadata {
+    pub model_to_table: HashMap<String, String>,
+    pub model_fields: HashMap<String, serde_json::Value>,
+    pub relation_map: HashMap<String, HashMap<String, RelationDef>>,
+}
+
+static MODEL_TO_TABLE: OnceLock<RwLock<HashMap<String, String>>> = OnceLock::new();
+static MODEL_FIELDS: OnceLock<RwLock<HashMap<String, serde_json::Value>>> = OnceLock::new();
+static RELATION_MAP: OnceLock<RwLock<HashMap<String, HashMap<String, RelationDef>>>> = OnceLock::new();
+static TABLE_OVERRIDES: OnceLock<RwLock<HashMap<String, String>>> = OnceLock::new();
+
+fn table_overrides_store() -> &'static RwLock<HashMap<String, String>> {
+    TABLE_OVERRIDES.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+/// Point a model alias at a different physical table.
+pub fn add_table_override(model: &str, table: &str) {
+    if let Ok(mut store) = table_overrides_store().write() {
+        store.insert(model.to_string(), table.to_string());
+    }
+}
+
+fn model_to_table_store() -> &'static RwLock<HashMap<String, String>> {
+    MODEL_TO_TABLE.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+fn model_fields_store() -> &'static RwLock<HashMap<String, serde_json::Value>> {
+    MODEL_FIELDS.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+fn relation_map_store() -> &'static RwLock<HashMap<String, HashMap<String, RelationDef>>> {
+    RELATION_MAP.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+/// Store metadata provided by the generated client. Call once at startup.
+pub fn set_adapter_metadata(meta: AdapterMetadata) {
+    if let Ok(mut store) = model_to_table_store().write() {
+        *store = meta.model_to_table;
+    }
+    if let Ok(mut store) = model_fields_store().write() {
+        *store = meta.model_fields;
+    }
+    if let Ok(mut store) = relation_map_store().write() {
+        *store = meta.relation_map;
+    }
+}
+
+/// Read-only snapshot of the model-to-table mapping.
+pub fn get_model_to_table() -> HashMap<String, String> {
+    model_to_table_store()
+        .read()
+        .map(|s| s.clone())
+        .unwrap_or_default()
+}
+
+/// Field metadata for a model, if present.
+pub fn get_fields_for_model(model: &str) -> Option<serde_json::Value> {
+    model_fields_store().read().ok().and_then(|s| s.get(model).cloned())
+}
+
+/// Relations declared for a model.
+pub fn get_relations_for_model(model: &str) -> HashMap<String, RelationDef> {
+    relation_map_store()
+        .read()
+        .ok()
+        .and_then(|s| s.get(model).cloned())
+        .unwrap_or_default()
+}
+
+/// Resolve the physical table for a model, honouring overrides, then the
+/// generated mapping, then a case-insensitive match, then the input itself.
+pub fn resolve_table(model: &str) -> String {
+    let lower = model.to_lowercase();
+    // Overrides win over the generated mapping, and both match
+    // case-insensitively so `with_table("User", ..)` also covers `db.table("user")`.
+    if let Ok(store) = table_overrides_store().read() {
+        if let Some(t) = store.get(model) {
+            return t.clone();
+        }
+        for (k, v) in store.iter() {
+            if k.to_lowercase() == lower {
+                return v.clone();
+            }
+        }
+    }
+    if let Ok(store) = model_to_table_store().read() {
+        if let Some(t) = store.get(model) {
+            return t.clone();
+        }
+        for (k, v) in store.iter() {
+            if k.to_lowercase() == lower {
+                return v.clone();
+            }
+        }
+    }
+    model.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolves_table_with_case_fallback() {
+        let mut map = HashMap::new();
+        map.insert("User".to_string(), "[dbo].[Users]".to_string());
+        set_adapter_metadata(AdapterMetadata {
+            model_to_table: map,
+            ..Default::default()
+        });
+        assert_eq!(resolve_table("User"), "[dbo].[Users]");
+        assert_eq!(resolve_table("user"), "[dbo].[Users]");
+        assert_eq!(resolve_table("Missing"), "Missing");
+    }
+}

package/rust/src/base/mod.rs

@@ -0,0 +1,17 @@
+//! Shared building blocks for the AN5 Rust adapter.
+//!
+//! Mirrors the Go `an5adapters/base` package: dialect handling, adapter
+//! metadata and WHERE / ORDER BY construction.
+
+pub mod dialect;
+pub mod metadata;
+pub mod where_builder;
+
+pub use dialect::{
+    cosine_similarity, dot_product, euclidean_distance, vector_distance, Dialect,
+};
+pub use metadata::{
+    add_table_override, get_fields_for_model, get_model_to_table, get_relations_for_model,
+    resolve_table, set_adapter_metadata, AdapterMetadata, RelationDef,
+};
+pub use where_builder::{build_order_by, build_where, SqlArg, Where};