vantage_api_client/graphql/

condition.rs

//! `GraphqlCondition` — the structured filter type for the GraphQL adapter.
//!
//! Conditions are kept abstract (field/op/value) and rendered to JSON at
//! request time by the dialect attached to the data source, one of:
//!
//! * [`FilterDialect::Hasura`] — `{ field: { _eq: v }, _and: [...], _or:
//!   [...], _not: {...} }`. Full operator coverage.
//! * [`FilterDialect::Generic`] — flat argument object: `{ field: v }`.
//!   Equality only; non-eq operators error at render time. Used by
//!   hand-rolled schemas like the SpaceX public API.

use serde_json::{Map, Value};
use vantage_core::{Result, error};
use vantage_expressions::{DeferredFn, Expression, Expressive, ExpressiveEnum};

use crate::graphql::types::AnyGraphqlType;

/// How a `GraphqlCondition` is rendered into a GraphQL argument object.
///
/// In YAML (`graphql: { dialect: … }`) it is spelled `generic` or
/// `hasura`; any other value fails to deserialise.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum FilterDialect {
    /// Hasura-style: `{ field: { _eq: v } }`, `_and`/`_or`/`_not`.
    Hasura,
    /// Flat-argument schemas like SpaceX: `{ field: v }`. Equality
    /// only — non-eq operators fail at render time. The default.
    #[default]
    Generic,
}

/// The set of comparison/logical operators a `FieldCondition` can use.
///
/// Whether a given dialect can render a given op is decided at render
/// time — see `GraphqlCondition::render`.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum GraphqlOp {
    /// `field = value`
    Eq,
    /// `field != value`
    Ne,
    /// `field > value`
    Gt,
    /// `field >= value`
    Gte,
    /// `field < value`
    Lt,
    /// `field <= value`
    Lte,
    /// `field` is one of the values in an array.
    In,
    /// `field` is none of the values in an array.
    NotIn,
    /// Case-sensitive pattern match (`%` and `_` wildcards).
    Like,
    /// Case-insensitive pattern match (`%` and `_` wildcards).
    ILike,
    /// `field` is null; the value is ignored.
    IsNull,
    /// `field` is not null; the value is ignored.
    IsNotNull,
}

impl GraphqlOp {
    /// Hasura operator name (`_eq`, `_gt`, …). Returns `None` for ops
    /// Hasura can't express verbatim.
    pub fn hasura_key(&self) -> Option<&'static str> {
        Some(match self {
            Self::Eq => "_eq",
            Self::Ne => "_neq",
            Self::Gt => "_gt",
            Self::Gte => "_gte",
            Self::Lt => "_lt",
            Self::Lte => "_lte",
            Self::In => "_in",
            Self::NotIn => "_nin",
            Self::Like => "_like",
            Self::ILike => "_ilike",
            Self::IsNull => "_is_null",
            Self::IsNotNull => "_is_null",
        })
    }
}

/// A single `field <op> value` clause. Build one with
/// [`FieldCondition::new`].
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct FieldCondition {
    /// The column name the clause tests.
    pub field: String,
    /// The comparison.
    pub op: GraphqlOp,
    /// The operand, already in JSON form.
    pub value: Value,
}

impl FieldCondition {
    /// A `field <op> value` clause.
    pub fn new(field: impl Into<String>, op: GraphqlOp, value: Value) -> Self {
        Self {
            field: field.into(),
            op,
            value,
        }
    }
}

/// Structured filter for GraphQL requests. Built by the operator trait
/// (`GraphqlOperation` in `operation.rs`) and rendered at fetch time.
#[derive(Clone)]
#[non_exhaustive]
pub enum GraphqlCondition {
    /// One `field <op> value` clause.
    Field(FieldCondition),
    /// Like [`Self::Field`] but the value is resolved at fetch time.
    /// Used by relationship traversal — `with_many`/`with_one` builds
    /// one of these when the parent's foreign-key value isn't known
    /// until the parent is fetched. The deferred resolves to a scalar
    /// (the FK value); render-time wraps it in the dialect's `_eq`-
    /// equivalent and merges it into the filter. Build one with
    /// [`GraphqlCondition::deferred_field`].
    #[non_exhaustive]
    DeferredField {
        /// The column name the clause tests.
        field: String,
        /// The comparison.
        op: GraphqlOp,
        /// Produces the operand at fetch time.
        value_fn: DeferredFn<AnyGraphqlType>,
    },
    /// Every part holds.
    And(Vec<GraphqlCondition>),
    /// At least one part holds. Hasura only.
    Or(Vec<GraphqlCondition>),
    /// The inner condition does not hold. Hasura only.
    Not(Box<GraphqlCondition>),
    /// Resolved at fetch time — produces a complete filter sub-object
    /// that already matches the surrounding dialect. Use [`Self::DeferredField`]
    /// instead unless you genuinely need to compute a non-`field op value`
    /// shape dynamically.
    Deferred(DeferredFn<AnyGraphqlType>),
}

impl std::fmt::Debug for GraphqlCondition {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Field(fc) => write!(f, "Field({:?} {:?} {})", fc.field, fc.op, fc.value),
            Self::DeferredField { field, op, .. } => {
                write!(f, "DeferredField({:?} {:?} <pending>)", field, op)
            }
            Self::And(parts) => f.debug_tuple("And").field(parts).finish(),
            Self::Or(parts) => f.debug_tuple("Or").field(parts).finish(),
            Self::Not(inner) => f.debug_tuple("Not").field(inner).finish(),
            Self::Deferred(_) => write!(f, "Deferred(..)"),
        }
    }
}

impl GraphqlCondition {
    /// Build a simple `field = value` condition. Convenience for callers
    /// that have a value already converted to JSON.
    pub fn eq(field: impl Into<String>, value: impl Into<Value>) -> Self {
        Self::Field(FieldCondition::new(field, GraphqlOp::Eq, value.into()))
    }

    /// A `field <op> value` clause whose value `value_fn` produces at fetch
    /// time; see [`Self::DeferredField`].
    pub fn deferred_field(
        field: impl Into<String>,
        op: GraphqlOp,
        value_fn: DeferredFn<AnyGraphqlType>,
    ) -> Self {
        Self::DeferredField {
            field: field.into(),
            op,
            value_fn,
        }
    }

    /// Render this condition as a JSON object suitable for use as a
    /// GraphQL argument (typically the `where:` arg in Hasura, or the
    /// `find:` arg in flat-argument schemas).
    ///
    /// Deferred branches are resolved here. Resolution may make
    /// out-of-band fetches (e.g. for relationship traversal), so the
    /// method is async.
    pub fn render<'a>(
        &'a self,
        dialect: FilterDialect,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Value>> + Send + 'a>> {
        Box::pin(async move {
            match self {
                Self::Field(fc) => render_field(fc, dialect),
                Self::DeferredField {
                    field,
                    op,
                    value_fn,
                } => {
                    let resolved = value_fn.call().await?;
                    let value = match resolved {
                        ExpressiveEnum::Scalar(v) => v.into_value(),
                        other => {
                            return Err(error!(
                                "DeferredField resolved to non-scalar",
                                got = format!("{:?}", other)
                            ));
                        }
                    };
                    let fc = FieldCondition::new(field.clone(), op.clone(), value);
                    render_field(&fc, dialect)
                }
                Self::And(parts) => {
                    let mut rendered = Vec::with_capacity(parts.len());
                    for p in parts {
                        rendered.push(p.render(dialect).await?);
                    }
                    combine_and(rendered, dialect)
                }
                Self::Or(parts) => {
                    if matches!(dialect, FilterDialect::Generic) {
                        return Err(error!(
                            "Generic dialect does not support OR; switch to Hasura"
                        ));
                    }
                    let mut rendered = Vec::with_capacity(parts.len());
                    for p in parts {
                        rendered.push(p.render(dialect).await?);
                    }
                    Ok(Value::Object({
                        let mut m = Map::new();
                        m.insert("_or".into(), Value::Array(rendered));
                        m
                    }))
                }
                Self::Not(inner) => {
                    if matches!(dialect, FilterDialect::Generic) {
                        return Err(error!(
                            "Generic dialect does not support NOT; switch to Hasura"
                        ));
                    }
                    let inner_rendered = inner.render(dialect).await?;
                    Ok(Value::Object({
                        let mut m = Map::new();
                        m.insert("_not".into(), inner_rendered);
                        m
                    }))
                }
                Self::Deferred(deferred) => {
                    let resolved = deferred.call().await?;
                    let inner = match resolved {
                        ExpressiveEnum::Scalar(v) => v.into_value(),
                        other => {
                            return Err(error!(
                                "GraphqlCondition::Deferred resolved to non-scalar",
                                got = format!("{:?}", other)
                            ));
                        }
                    };
                    match inner {
                        Value::Object(_) => Ok(inner),
                        other => Err(error!(
                            "Deferred condition must resolve to a JSON object",
                            got = format!("{:?}", other)
                        )),
                    }
                }
            }
        })
    }

    /// Synchronous counterpart to [`render`](Self::render), for previewing a
    /// query without sending it.
    ///
    /// Every arm matches `render` but one: a deferred value does not exist yet
    /// — it is produced by calling back to the caller at fetch time — so
    /// rendering it here would mean doing the very work a preview exists to
    /// avoid. Those become a `**deferred(...)` marker, which is not valid
    /// GraphQL and is not meant to be: it marks the one place the previewed
    /// document and the sent one differ.
    ///
    /// Literal conditions — most of them, and all the ones written by hand in
    /// YAML — render identically to what gets sent.
    pub fn render_preview(&self, dialect: FilterDialect) -> Result<Value> {
        match self {
            Self::Field(fc) => render_field(fc, dialect),
            Self::DeferredField { field, op, .. } => {
                Ok(Value::String(format!("**deferred({} {:?})", field, op)))
            }
            Self::And(parts) => {
                let rendered = parts
                    .iter()
                    .map(|p| p.render_preview(dialect))
                    .collect::<Result<Vec<Value>>>()?;
                combine_and(rendered, dialect)
            }
            Self::Or(parts) => {
                if matches!(dialect, FilterDialect::Generic) {
                    return Err(error!(
                        "Generic dialect does not support OR; switch to Hasura"
                    ));
                }
                let rendered = parts
                    .iter()
                    .map(|p| p.render_preview(dialect))
                    .collect::<Result<Vec<Value>>>()?;
                Ok(Value::Object({
                    let mut m = Map::new();
                    m.insert("_or".into(), Value::Array(rendered));
                    m
                }))
            }
            Self::Not(inner) => {
                if matches!(dialect, FilterDialect::Generic) {
                    return Err(error!(
                        "Generic dialect does not support NOT; switch to Hasura"
                    ));
                }
                Ok(Value::Object({
                    let mut m = Map::new();
                    m.insert("_not".into(), inner.render_preview(dialect)?);
                    m
                }))
            }
            Self::Deferred(_) => Ok(Value::String("**deferred()".into())),
        }
    }
}

fn render_field(fc: &FieldCondition, dialect: FilterDialect) -> Result<Value> {
    match dialect {
        FilterDialect::Hasura => {
            let mut inner = Map::new();
            let key = fc.op.hasura_key().ok_or_else(|| {
                error!(
                    "Operator not supported in Hasura dialect",
                    op = format!("{:?}", fc.op)
                )
            })?;
            // Hasura's `_is_null` takes a Bool, which is how IsNotNull is spelled.
            let value = match fc.op {
                GraphqlOp::IsNull => Value::Bool(true),
                GraphqlOp::IsNotNull => Value::Bool(false),
                _ => fc.value.clone(),
            };
            inner.insert(key.into(), value);
            let mut outer = Map::new();
            outer.insert(fc.field.clone(), Value::Object(inner));
            Ok(Value::Object(outer))
        }
        FilterDialect::Generic => {
            if fc.op != GraphqlOp::Eq {
                return Err(error!(
                    "Generic dialect supports only equality; got non-eq operator",
                    field = fc.field.clone(),
                    op = format!("{:?}", fc.op)
                ));
            }
            let mut m = Map::new();
            m.insert(fc.field.clone(), fc.value.clone());
            Ok(Value::Object(m))
        }
    }
}

/// AND-combine rendered sub-conditions according to dialect.
fn combine_and(parts: Vec<Value>, dialect: FilterDialect) -> Result<Value> {
    match dialect {
        FilterDialect::Hasura => {
            // Distinct field keys in one object are an implicit AND; `_and`
            // is needed only when two parts share a key.
            let mut merged = Map::new();
            let mut collision = false;
            for p in &parts {
                if let Value::Object(obj) = p {
                    for k in obj.keys() {
                        if merged.contains_key(k) {
                            collision = true;
                            break;
                        }
                    }
                    if collision {
                        break;
                    }
                    if let Value::Object(obj) = p.clone() {
                        for (k, v) in obj {
                            merged.insert(k, v);
                        }
                    }
                }
            }
            if collision {
                Ok(Value::Object({
                    let mut m = Map::new();
                    m.insert("_and".into(), Value::Array(parts));
                    m
                }))
            } else {
                Ok(Value::Object(merged))
            }
        }
        FilterDialect::Generic => {
            // A flat object can't hold two conditions on one field; fail
            // rather than silently keep one.
            let mut merged = Map::new();
            for p in parts {
                if let Value::Object(obj) = p {
                    for (k, v) in obj {
                        if merged.contains_key(&k) {
                            return Err(error!(
                                "Generic dialect can't express two conditions on the same field",
                                field = k
                            ));
                        }
                        merged.insert(k, v);
                    }
                }
            }
            Ok(Value::Object(merged))
        }
    }
}

impl From<FieldCondition> for GraphqlCondition {
    fn from(fc: FieldCondition) -> Self {
        Self::Field(fc)
    }
}

/// `GraphqlCondition` is `Expressive`, which satisfies the blanket bound on
/// [`GraphqlOperation`](crate::GraphqlOperation).
impl Expressive<AnyGraphqlType> for GraphqlCondition {
    fn expr(&self) -> Expression<AnyGraphqlType> {
        Expression::new(format!("{:?}", self), vec![])
    }
}