aimx/functions/

function_registry.rs

//! Function registry and value conversion utilities.
//!
//! Provides the global registry for AIMX functions/methods and helpers
//! used by registration macros to convert between [`Value`] and native types.
//! The registry is initialized once with built-ins via [`functions::register_all_functions`]
//! and accessed through a thread-safe [`RwLock`].
use crate::{aim::ContextLike, functions, literals::Literal, values::Value};
use anyhow::{Result, anyhow};
use jiff::civil::DateTime;
use std::collections::HashMap;
use std::sync::OnceLock;
use std::sync::{Arc, RwLock};

/// Global registry mapping function names to handlers used during expression evaluation.
/// Supports both standalone calls and method-style calls on [`Value`] receivers.
pub struct FunctionRegistry {
    handlers: HashMap<Arc<str>, Box<dyn FunctionHandler>>,
}

/// Handler invoked for a registered function or method.
pub trait FunctionHandler: Send + Sync {
    /// Call the function with the provided arguments.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context for closures
    /// * `args` - A slice of [`Value`] arguments passed to the function
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the function result or an error
    /// if the function execution fails.
    ///
    /// # Note
    ///
    /// For method calls, the first argument is typically the value the method
    /// is being called on, followed by any additional arguments.
    fn call(&self, context: &mut dyn ContextLike, args: Vec<Arc<Value>>) -> Result<Value>;
}

impl FunctionRegistry {
    /// Get the global singleton instance of the function registry.
    ///
    /// This method uses [`OnceLock`] to ensure thread-safe one-time initialization
    /// of the function registry with all built-in functions registered.
    /// Uses [`RwLock`] to allow multiple concurrent readers while ensuring
    /// exclusive access during writes.
    ///
    /// # Returns
    ///
    /// Returns a reference to the RwLock-protected singleton function registry.
    pub fn get_instance() -> &'static RwLock<Self> {
        static INSTANCE: OnceLock<RwLock<FunctionRegistry>> = OnceLock::new();

        INSTANCE.get_or_init(|| {
            let mut registry = Self::new();
            functions::register_all_functions(&mut registry);
            RwLock::new(registry)
        })
    }

    /// Get a read lock on the function registry for function calls.
    ///
    /// This is a convenience method that returns a read guard, allowing
    /// multiple concurrent function calls without blocking each other.
    ///
    /// # Returns
    ///
    /// Returns a `Result` containing the read guard or an error if the lock is poisoned.
    pub fn read_lock() -> Result<std::sync::RwLockReadGuard<'static, Self>> {
        Self::get_instance()
            .read()
            .map_err(|_| anyhow!("Function registry lock is poisoned"))
    }

    /// Get a write lock on the function registry for registration.
    ///
    /// This is a convenience method that returns a write guard, providing
    /// exclusive access for registering new functions.
    ///
    /// # Returns
    ///
    /// Returns a `Result` containing the write guard or an error if the lock is poisoned.
    pub fn write_lock() -> Result<std::sync::RwLockWriteGuard<'static, Self>> {
        Self::get_instance()
            .write()
            .map_err(|_| anyhow!("Function registry lock is poisoned"))
    }

    /// Create a new, empty function registry.
    ///
    /// This is primarily used internally during initialization.
    fn new() -> Self {
        Self {
            handlers: HashMap::new(),
        }
    }

    /// Register a function handler with the given name.
    ///
    /// # Arguments
    ///
    /// * `name` - The name to register the function under
    /// * `handler` - The function handler implementation
    ///
    pub fn register<F>(&mut self, name: Arc<str>, handler: F)
    where
        F: FunctionHandler + 'static,
    {
        self.handlers.insert(name, Box::new(handler));
    }

    /// Call with a read lock on the global registry. Flattens `Array` args.

    pub fn function_call(
        &self,
        context: &mut dyn ContextLike,
        name: Arc<str>,
        arg: Arc<Value>,
    ) -> Result<Arc<Value>> {
        let mut args: Vec<Arc<Value>> = Vec::new();
        match &*arg {
            Value::Literal(_) => args.push(arg),
            Value::Array(array) => {
                for value in array.iter() {
                    args.push(value.clone());
                }
            }
            _ => {}
        };
        let result = self.handlers
            .get(&name)
            .ok_or_else(|| anyhow!("Function '{}' not found~{}", name, name))?
            .call(context, args)?;
        Ok(Arc::new(result))
    }

    /// Call a method handler with `value` prepended to args. Flattens `Array` args.

    pub fn method_call(
        &self,
        context: &mut dyn ContextLike,
        name: Arc<str>,
        value: Arc<Value>,
        arg: Arc<Value>,
    ) -> Result<Arc<Value>> {
        let mut args: Vec<Arc<Value>> = Vec::new();
        args.push(value);
        match &*arg {
            Value::Literal(_) => {
                args.push(arg);
            }
            Value::Array(array) => {
                for value in array.iter() {
                    args.push(value.clone());
                }
            }
            _ => {}
        };
        let result = self.handlers
            .get(&name)
            .ok_or_else(|| anyhow!("Method '{}' not found~{}", name, name))?
            .call(context, args)?;
        Ok(Arc::new(result))
    }

    /// Returns `true` if a handler with `name` is registered.

    pub fn handler_exists(&self, name: Arc<str>) -> bool {
        self.handlers.contains_key(&name)
    }
}

/// Convert a [`Value`] to `T` via [`ValueConverter`].
pub fn convert_value_to_type<T>(value: Arc<Value>) -> Result<T>
where
    T: ValueConverter,
{
    T::from_value(value)
}

/// Convert any `T: Into<Value>` to [`Arc<Value>`].
pub fn convert_result_to_value<T>(result: T) -> Result<Arc<Value>>
where
    T: Into<Value>,
{
    Ok(Arc::new(result.into()))
}

/// Convert [`Value`] to native types used by functions.

pub trait ValueConverter: Sized {
    /// Convert a Value to this native type.
    ///
    /// # Arguments
    ///
    /// * `value` - The value to convert
    ///
    /// # Returns
    ///
    /// Returns a `Result<Self>` containing the converted value or an error
    /// if conversion fails.
    fn from_value(value: Arc<Value>) -> Result<Self>;
}

// Implementations for common types
impl ValueConverter for f64 {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        value.to_number()
    }
}

impl ValueConverter for Arc<str> {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        Ok(value.to_arc_str())
    }
}

impl ValueConverter for bool {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        match &*value {
            Value::Literal(literal) => Ok(literal.to_bool()),
            Value::Array(array) => Ok(!array.is_empty()),
            _ => Ok(false),
        }
    }
}

impl ValueConverter for DateTime {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        match &*value {
            Value::Literal(Literal::Date(dt)) => Ok(*dt),
            Value::Literal(literal) => {
                // Try to convert the literal to a date
                literal
                    .clone()
                    .as_date()
                    .and_then(|date_literal| match date_literal {
                        Literal::Date(dt) => Ok(dt),
                        _ => Err(anyhow!("Failed to convert to DateTime")),
                    })
            }
            _ => Err(anyhow!(
                "Cannot convert {} to DateTime",
                value.type_as_string()
            )),
        }
    }
}

impl<T: ValueConverter> ValueConverter for Vec<Arc<T>> {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        match &*value {
            Value::Array(array) => {
                // For arrays, we need to convert each Arc<Value> to Arc<T>
                // This is a complex conversion that requires creating new T instances
                array
                    .iter()
                    .map(|value| {
                        T::from_value(value.clone()).map(Arc::new)
                    })
                    .collect()
            }
            _ => {
                // For single values, create a single-element vector
                T::from_value(value).map(|t| vec![Arc::new(t)])
            }
        }
    }
}

impl ValueConverter for Vec<Arc<str>> {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        match &*value {
            Value::Array(array) => {
                // Convert each Arc<Value> to Arc<str>
                array
                    .iter()
                    .map(|value| {
                        Ok(value.to_arc_str())
                    })
                    .collect()
            }
            _ => {
                // For single values, create a single-element vector
                Ok(vec![value.to_arc_str()])
            }
        }
    }
}

impl ValueConverter for Vec<f64> {
    fn from_value(value: Arc<Value>) -> Result<Self> {
        match &*value {
            Value::Array(array) => {
                // Convert each Arc<Value> to f64
                array
                    .iter()
                    .map(|value| {
                        f64::from_value(value.clone())
                    })
                    .collect()
            }
            _ => {
                // For single values, create a single-element vector
                f64::from_value(value).map(|n| vec![n])
            }
        }
    }
}