flusso_query/handles/

sort.rs

//! Sort keys: [`SortOrder`], [`SortMode`], and the [`Sort`] builder produced by
//! `.asc()` / `.desc()` on a sortable handle (or `Geo::distance_sort`,
//! [`Sort::score`], [`Sort::script`]).
//!
//! A [`Sort`] carries the key it sorts on (a field path, `_score`,
//! `_geo_distance`, or `_script`) plus its options (`missing`, `mode`,
//! `unmapped_type`, …); `.missing_first()` / `.mode(..)` chain onto it, and it
//! renders to one entry in the `sort` array. The typed handle is always the
//! entry point — there is no public string-path sort.

use serde_json::{Map, Value};

use super::{Geo, GeoPoint, NumericType, ScriptSortType};
use crate::query::AsQuery;
use crate::{FlussoDocument, nested_boundaries};

/// Sort direction.
#[derive(Debug, Clone, Copy)]
pub enum SortOrder {
    /// Ascending.
    Asc,
    /// Descending.
    Desc,
}

impl SortOrder {
    pub(crate) fn as_str(self) -> &'static str {
        match self {
            SortOrder::Asc => "asc",
            SortOrder::Desc => "desc",
        }
    }
}

/// How a multi-valued field collapses to one sort value.
#[derive(Debug, Clone, Copy)]
pub enum SortMode {
    /// Smallest value.
    Min,
    /// Largest value.
    Max,
    /// Arithmetic mean (numeric fields).
    Avg,
    /// Sum (numeric fields).
    Sum,
    /// Median (numeric fields).
    Median,
}

impl SortMode {
    fn as_str(self) -> &'static str {
        match self {
            SortMode::Min => "min",
            SortMode::Max => "max",
            SortMode::Avg => "avg",
            SortMode::Sum => "sum",
            SortMode::Median => "median",
        }
    }
}

/// A single sort key. Produced by `.asc()` / `.desc()` on a sortable handle, by
/// [`Sort::score`] / [`Sort::script`], or by `Geo::distance_sort`; chain the
/// option setters (`missing_first`, `mode`, `unmapped_type`, …) onto it.
#[derive(Debug, Clone)]
pub struct Sort {
    key: String,
    body: Map<String, Value>,
}

impl Sort {
    /// A field/order sort: `{ "<field>": { "order": "asc"|"desc" } }`.
    pub(crate) fn new(field: &str, order: SortOrder) -> Self {
        let mut body = Map::new();
        body.insert(
            "order".to_string(),
            Value::String(order.as_str().to_string()),
        );
        Self {
            key: field.to_string(),
            body,
        }
    }

    /// Sort by relevance `_score` (descending by default).
    #[must_use]
    pub fn score() -> Self {
        let mut sort = Self {
            key: "_score".to_string(),
            body: Map::new(),
        };
        sort.body
            .insert("order".to_string(), Value::String("desc".to_string()));
        sort
    }

    /// Sort by a computed script value. `script_type` is the emitted value type
    /// ([`ScriptSortType::Number`] / [`ScriptSortType::String`]); `source` is
    /// the painless expression.
    #[must_use]
    pub fn script(
        script_type: ScriptSortType,
        source: impl Into<String>,
        order: SortOrder,
    ) -> Self {
        let mut script = Map::new();
        script.insert("source".to_string(), Value::String(source.into()));
        let mut body = Map::new();
        body.insert(
            "type".to_string(),
            Value::String(script_type.as_str().to_string()),
        );
        body.insert("script".to_string(), Value::Object(script));
        body.insert(
            "order".to_string(),
            Value::String(order.as_str().to_string()),
        );
        Self {
            key: "_script".to_string(),
            body,
        }
    }

    /// A pre-built sort clause (e.g. `_geo_distance`).
    pub(crate) fn from_parts(key: String, body: Map<String, Value>) -> Self {
        Self { key, body }
    }

    /// A field sort that is **nesting-aware**: it reads the scope `S`'s path and,
    /// when the field sits inside one or more `nested` arrays, wraps the sort in
    /// the matching `nested` chain (and defaults `mode` from the direction —
    /// `asc → min`, `desc → max`). A root or flattened-object field (empty path)
    /// renders a plain sort. Backs every [`Sortable`] handle.
    pub(crate) fn field<S: FlussoDocument>(path: &str, order: SortOrder) -> Self {
        let mut sort = Sort::new(path, order);
        let boundaries = nested_boundaries(S::PATH);
        if let Some(nested) = nested_clause(&boundaries) {
            sort.body.insert("nested".to_string(), nested);
            sort.body.insert(
                "mode".to_string(),
                Value::String(default_mode(order).to_string()),
            );
        }
        sort
    }

    /// Sort ascending.
    #[must_use]
    pub fn asc(mut self) -> Self {
        self.body
            .insert("order".to_string(), Value::String("asc".to_string()));
        self
    }

    /// Sort descending.
    #[must_use]
    pub fn desc(mut self) -> Self {
        self.body
            .insert("order".to_string(), Value::String("desc".to_string()));
        self
    }

    /// Place documents missing this field first.
    #[must_use]
    pub fn missing_first(mut self) -> Self {
        self.body
            .insert("missing".to_string(), Value::String("_first".to_string()));
        self
    }

    /// Place documents missing this field last.
    #[must_use]
    pub fn missing_last(mut self) -> Self {
        self.body
            .insert("missing".to_string(), Value::String("_last".to_string()));
        self
    }

    /// Substitute a literal value for documents missing this field.
    #[must_use]
    pub fn missing(mut self, value: impl Into<Value>) -> Self {
        self.body.insert("missing".to_string(), value.into());
        self
    }

    /// How a multi-valued field reduces to one sort value.
    #[must_use]
    pub fn mode(mut self, mode: SortMode) -> Self {
        self.body
            .insert("mode".to_string(), Value::String(mode.as_str().to_string()));
        self
    }

    /// Type to assume when the field is unmapped on some shard (instead of
    /// failing the search), e.g. `"long"`.
    #[must_use]
    pub fn unmapped_type(mut self, unmapped_type: impl Into<String>) -> Self {
        self.body.insert(
            "unmapped_type".to_string(),
            Value::String(unmapped_type.into()),
        );
        self
    }

    /// Numeric type to sort as ([`NumericType`]), for cross-index type coercion.
    #[must_use]
    pub fn numeric_type(mut self, numeric_type: NumericType) -> Self {
        self.body.insert(
            "numeric_type".to_string(),
            Value::String(numeric_type.as_str().to_string()),
        );
        self
    }

    /// Date `format` for a `date` field sort.
    #[must_use]
    pub fn format(mut self, format: impl Into<String>) -> Self {
        self.body
            .insert("format".to_string(), Value::String(format.into()));
        self
    }

    /// Sort by a field inside a `nested` array scoped to `path`, considering
    /// only elements matching `filter`. An escape hatch for the rare
    /// filter-scoped nested sort; ordinary nested sorts come from a
    /// [`Sortable`] handle, which derives the (possibly multi-level) `nested`
    /// chain from the field's scope automatically.
    #[must_use]
    pub fn nested_filtered<S>(mut self, path: impl Into<String>, filter: impl AsQuery<S>) -> Self {
        let mut nested = Map::new();
        nested.insert("path".to_string(), Value::String(path.into()));
        if let Some(query) = filter.into_query() {
            nested.insert("filter".to_string(), query.to_value());
        }
        self.body
            .insert("nested".to_string(), Value::Object(nested));
        self
    }

    pub(crate) fn to_value(&self) -> Value {
        let mut outer = Map::new();
        outer.insert(self.key.clone(), Value::Object(self.body.clone()));
        Value::Object(outer)
    }

    /// The key this sort orders on (a field path, `_score`, `_geo_distance`, or
    /// `_script`) — what [`SortBuilder`] dedups on.
    pub(crate) fn key(&self) -> &str {
        &self.key
    }

    /// Drop the `nested` chain (and its companion `mode`) for use inside
    /// `inner_hits`: there the sort already runs within the nested document, so
    /// the field path is relative and no wrapper applies. A plain or `_score`
    /// sort is unchanged.
    pub(crate) fn without_nested_context(mut self) -> Self {
        if self.body.remove("nested").is_some() {
            self.body.remove("mode");
        }
        self
    }
}

/// Wrap a plain sort in the `nested` chain for `boundaries` (cumulative dotted
/// paths, outermost first). `None` when there is no nesting.
fn nested_clause(boundaries: &[String]) -> Option<Value> {
    let (path, rest) = boundaries.split_first()?;
    let mut clause = Map::new();
    clause.insert("path".to_string(), Value::String(path.clone()));
    if let Some(inner) = nested_clause(rest) {
        clause.insert("nested".to_string(), inner);
    }
    Some(Value::Object(clause))
}

/// The `mode` a nested sort defaults to for `order`: the smallest element value
/// when ascending, the largest when descending (so the chosen element is the one
/// that sorts the parent extremally).
fn default_mode(order: SortOrder) -> &'static str {
    match order {
        SortOrder::Asc => "min",
        SortOrder::Desc => "max",
    }
}

/// A handle that can produce a field [`Sort`]. The compile-time gate for
/// [`SortBuilder::by`] / [`tiebreak`](SortBuilder::tiebreak): implemented for the
/// orderable leaf handles (`Keyword`, `Text`, `Number<K>`, `Date`, `Bool`) and
/// **not** for `Geo` / `Object` / map handles, so `by(geo_handle, …)` fails to
/// compile (geo sorts go through [`SortBuilder::near`] / [`raw`](SortBuilder::raw)).
///
/// `.asc()` / `.desc()` are nesting-aware: a field inside one or more `nested`
/// arrays renders the matching `nested` chain automatically, from the handle's
/// scope.
pub trait Sortable {
    /// Sort ascending.
    fn asc(&self) -> Sort;
    /// Sort descending.
    fn desc(&self) -> Sort;
}

/// Where to place documents missing the sorted field (a field-sort `missing`).
#[derive(Debug, Clone)]
pub enum Missing {
    /// Missing values sort first (`_first`).
    First,
    /// Missing values sort last (`_last`).
    Last,
    /// Missing values take this substitute value.
    Value(Value),
}

/// A field sort minus the field — a direction plus the field-sort modifiers,
/// ready to attach to whatever handle [`SortBuilder::by`] is given.
///
/// This is what a consumer converts its own request enum into, once
/// (`impl From<MyDir> for OrderBy`). It carries full parity with [`Sort`]'s
/// field-sort options; everything but the direction defaults to unset.
#[derive(Debug, Clone)]
pub struct OrderBy {
    order: SortOrder,
    missing: Option<Missing>,
    mode: Option<SortMode>,
    numeric_type: Option<NumericType>,
    unmapped_type: Option<String>,
    format: Option<String>,
}

impl OrderBy {
    /// Ascending, no modifiers.
    #[must_use]
    pub fn asc() -> Self {
        Self::new(SortOrder::Asc)
    }

    /// Descending, no modifiers.
    #[must_use]
    pub fn desc() -> Self {
        Self::new(SortOrder::Desc)
    }

    fn new(order: SortOrder) -> Self {
        Self {
            order,
            missing: None,
            mode: None,
            numeric_type: None,
            unmapped_type: None,
            format: None,
        }
    }

    /// Place documents missing this field first.
    #[must_use]
    pub fn missing_first(mut self) -> Self {
        self.missing = Some(Missing::First);
        self
    }

    /// Place documents missing this field last.
    #[must_use]
    pub fn missing_last(mut self) -> Self {
        self.missing = Some(Missing::Last);
        self
    }

    /// Substitute a literal value for documents missing this field.
    #[must_use]
    pub fn missing(mut self, value: impl Into<Value>) -> Self {
        self.missing = Some(Missing::Value(value.into()));
        self
    }

    /// How a multi-valued field reduces to one sort value.
    #[must_use]
    pub fn mode(mut self, mode: SortMode) -> Self {
        self.mode = Some(mode);
        self
    }

    /// Numeric type to sort as, for cross-index type coercion.
    #[must_use]
    pub fn numeric_type(mut self, numeric_type: NumericType) -> Self {
        self.numeric_type = Some(numeric_type);
        self
    }

    /// Type to assume when the field is unmapped on some shard.
    #[must_use]
    pub fn unmapped_type(mut self, unmapped_type: impl Into<String>) -> Self {
        self.unmapped_type = Some(unmapped_type.into());
        self
    }

    /// Date `format` for a `date` field sort.
    #[must_use]
    pub fn format(mut self, format: impl Into<String>) -> Self {
        self.format = Some(format.into());
        self
    }

    /// Build the field [`Sort`] for `handle`, in this order with these modifiers.
    fn into_sort<H: Sortable>(self, handle: &H) -> Sort {
        let mut sort = match self.order {
            SortOrder::Asc => handle.asc(),
            SortOrder::Desc => handle.desc(),
        };
        sort = match self.missing {
            Some(Missing::First) => sort.missing_first(),
            Some(Missing::Last) => sort.missing_last(),
            Some(Missing::Value(value)) => sort.missing(value),
            None => sort,
        };
        if let Some(mode) = self.mode {
            sort = sort.mode(mode);
        }
        if let Some(numeric_type) = self.numeric_type {
            sort = sort.numeric_type(numeric_type);
        }
        if let Some(unmapped_type) = self.unmapped_type {
            sort = sort.unmapped_type(unmapped_type);
        }
        if let Some(format) = self.format {
            sort = sort.format(format);
        }
        sort
    }
}

impl From<SortOrder> for OrderBy {
    fn from(order: SortOrder) -> Self {
        Self::new(order)
    }
}

/// The optionality carrier for [`SortBuilder::by`]: an absent order skips the
/// field. A local newtype because coherence forbids `impl From<…> for Option<_>`.
///
/// `SortOrder`, `OrderBy`, and — via the umbrella impl — `Option<T: Into<OrderBy>>`
/// all flow in, so a consumer's `Option<MyDir>` self-skips on `None` after one
/// `impl From<MyDir> for OrderBy`.
#[derive(Debug, Clone)]
pub struct MaybeOrderBy(Option<OrderBy>);

impl From<OrderBy> for MaybeOrderBy {
    fn from(order: OrderBy) -> Self {
        Self(Some(order))
    }
}

impl From<SortOrder> for MaybeOrderBy {
    fn from(order: SortOrder) -> Self {
        Self(Some(order.into()))
    }
}

impl<T: Into<OrderBy>> From<Option<T>> for MaybeOrderBy {
    fn from(order: Option<T>) -> Self {
        Self(order.map(Into::into))
    }
}

/// Builds the `sort` array, one fluent verb per concern — each absorbing its own
/// optionality so a request maps straight through with no per-field `if let`.
///
/// `by`/`near`/`tiebreak`/`or_default` **dedup** by sort key (first wins), so a
/// field added twice — or an explicit sort that a tiebreak/default would repeat —
/// appears once; `raw` is exempt. `or_default` only contributes when the builder
/// would otherwise be empty.
///
/// ```
/// use flusso_query::{SortBuilder, SortOrder, OrderBy};
/// # use flusso_query::{Keyword, Number, kind, Root};
/// # fn keyword(p: &str) -> Keyword<Root> { Keyword::at(p) }
/// # fn count() -> Number<kind::Long, Root> { Number::at("orderCount") }
/// let sorts = SortBuilder::new()
///     .score_if(true)
///     .by(count(), SortOrder::Desc)
///     .by(keyword("city"), None::<OrderBy>)   // skipped
///     .tiebreak(keyword("id"))
///     .build();
/// assert_eq!(sorts.len(), 3);                 // _score, orderCount, id
/// ```
#[derive(Debug, Default)]
pub struct SortBuilder {
    sorts: Vec<Sort>,
    fallback: Option<Sort>,
}

impl SortBuilder {
    /// An empty builder.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Push `sort` unless its key is already present (first wins).
    fn push_unique(&mut self, sort: Sort) {
        if !self
            .sorts
            .iter()
            .any(|existing| existing.key() == sort.key())
        {
            self.sorts.push(sort);
        }
    }

    /// Sort by a field. `dir` accepts a [`SortOrder`], an [`OrderBy`], or an
    /// `Option` of either (a `None` skips the field) — so a request's
    /// `Option<dir>` flows straight in. Nesting-aware: a field inside `nested`
    /// arrays renders the right `nested` chain from its scope.
    #[must_use]
    pub fn by<H: Sortable>(mut self, handle: H, dir: impl Into<MaybeOrderBy>) -> Self {
        if let Some(order) = dir.into().0 {
            self.push_unique(order.into_sort(&handle));
        }
        self
    }

    /// Sort by distance from `center` (`_geo_distance`, nearest first). A `None`
    /// center skips it. Pass a unit / script geo sort through [`raw`](Self::raw).
    #[must_use]
    pub fn near<S>(mut self, handle: Geo<S>, center: impl Into<Option<GeoPoint>>) -> Self {
        if let Some(center) = center.into() {
            self.push_unique(handle.distance_from(center));
        }
        self
    }

    /// Sort by relevance `_score` (descending).
    #[must_use]
    pub fn score(mut self) -> Self {
        self.push_unique(Sort::score());
        self
    }

    /// Sort by `_score` only when `cond` holds (e.g. a free-text query is present).
    #[must_use]
    pub fn score_if(self, cond: bool) -> Self {
        if cond { self.score() } else { self }
    }

    /// Append a pre-built [`Sort`] verbatim — the escape hatch for sorts the
    /// typed verbs don't cover (`_script`, a geo sort with options). A `None`
    /// adds nothing. **Not** deduped.
    #[must_use]
    pub fn raw(mut self, sort: impl Into<Option<Sort>>) -> Self {
        if let Some(sort) = sort.into() {
            self.sorts.push(sort);
        }
        self
    }

    /// A stable final sort key (ascending) — append a unique field so equal
    /// leading keys still page deterministically.
    #[must_use]
    pub fn tiebreak<H: Sortable>(mut self, handle: H) -> Self {
        self.push_unique(handle.asc());
        self
    }

    /// A fallback used only if nothing else lands in the builder.
    #[must_use]
    pub fn or_default(mut self, sort: impl Into<Sort>) -> Self {
        if self.fallback.is_none() {
            self.fallback = Some(sort.into());
        }
        self
    }

    /// Finish: the `sort` array (the fallback, if set, when otherwise empty).
    #[must_use]
    pub fn build(mut self) -> Vec<Sort> {
        if self.sorts.is_empty()
            && let Some(fallback) = self.fallback
        {
            self.sorts.push(fallback);
        }
        self.sorts
    }
}

impl IntoIterator for SortBuilder {
    type Item = Sort;
    type IntoIter = std::vec::IntoIter<Sort>;

    fn into_iter(self) -> Self::IntoIter {
        self.build().into_iter()
    }
}