ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! [`FusionOptions`] — the per-tier ALGORITHM knob, and the wire shape a new fusion flavour arrives
//! as.

use super::Fusion;

/// WHICH fold a tier runs, and the numbers that fold takes — the wire and configuration face of
/// [`Fusion`].
///
/// # It is a `@oneOf` and not a struct of optional blocks, and the difference is a schema fact
///
/// A tier runs ONE fold. A struct carrying `rrf: Option<…>` beside a future `bordaCount: Option<…>`
/// would let a client name both, and the type would then have to refuse at run time what the schema
/// had already accepted. `@oneOf` moves that refusal into the parse: exactly one non-null member, or
/// the request never reaches this crate. It is the shape the order-by face already takes, for the
/// same reason and by the same mechanism.
///
/// # Why it is not [`Fusion`] itself
///
/// [`Fusion`] is the FOLD — a value the fold reads, with every parameter resolved. This is the
/// REQUEST, where every parameter is still optional because a client that names the flavour and
/// nothing else means *that flavour, at the ruled constants*. The two are one
/// [`fusion`](Self::fusion) call apart, and keeping them apart is what lets `Fusion::RRF_K` stay a
/// law rather than becoming a value every client has to restate.
///
/// # One variant today, and the shape is what makes the second one cheap
///
/// [`Fusion`]'s own argument, inherited whole: a second flavour is one variant here, one arm in
/// [`fusion`](Self::fusion), and one more member of the `@oneOf` on the wire — additive at every
/// site, with no client's existing document changed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "async-graphql", derive(async_graphql::OneofObject))]
pub enum FusionOptions {
  #[cfg_attr(doc, doc = "Reciprocal rank fusion — see [`Fusion::Rrf`].")]
  Rrf(RrfOptions),
}

impl FusionOptions {
  /// Reciprocal rank fusion at the ruled constant — what a tier that named the flavour and no number
  /// asked for.
  #[inline]
  #[must_use]
  pub const fn rrf() -> Self {
    Self::Rrf(RrfOptions::new())
  }

  /// The FOLD this request resolves to, every parameter filled from the ruled constants where the
  /// request left it open.
  ///
  /// The one translation point between the request vocabulary and the fold vocabulary. Written here
  /// rather than at each caller so a flavour's defaults are stated once — the same division the
  /// declared-fold resolution takes, where the query beats the declaration beats the shipped
  /// citizen.
  #[inline]
  #[must_use]
  pub const fn fusion(&self) -> Fusion {
    match self {
      Self::Rrf(rrf) => Fusion::Rrf { k: rrf.damping() },
    }
  }
}

/// The fold a tier runs when its options say nothing.
impl Default for FusionOptions {
  #[inline]
  fn default() -> Self {
    Self::rrf()
  }
}

/// RECIPROCAL RANK FUSION's own parameters — one number, and it is optional.
///
/// # `k` is [`Option`] here and bare in [`Fusion`], and that is the de-Option law rather than a
/// mismatch
///
/// Absence here DEFERS: a client that wrote `{ rrf: {} }` asked for reciprocal rank fusion at
/// whatever this framework's ruling says, and [`Fusion::RRF_K`] is what answers. A resolved
/// [`Fusion`] has no chain left to defer to, so its `k` is a number. The two spellings are the two
/// ends of one resolution, and collapsing them would either put a default in a law's place or make
/// every client restate the law.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[cfg_attr(feature = "async-graphql", derive(async_graphql::InputObject))]
pub struct RrfOptions {
  #[cfg_attr(
    doc,
    doc = "The damping constant, or `Fusion::RRF_K` where the request names none."
  )]
  k: Option<u32>,
}

impl RrfOptions {
  /// The flavour named, and no number with it.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self { k: None }
  }

  /// The same request at a named damping constant.
  #[inline]
  #[must_use]
  pub const fn with_damping(mut self, k: u32) -> Self {
    self.k = Some(k);
    self
  }

  /// The damping constant the request named, if it named one.
  #[inline]
  #[must_use]
  pub const fn named_damping(&self) -> Option<u32> {
    self.k
  }

  /// The damping constant this request RESOLVES to — the named one, or the ruled constant.
  #[inline]
  #[must_use]
  pub const fn damping(&self) -> u32 {
    match self.k {
      Some(k) => k,
      None => Fusion::RRF_K,
    }
  }
}

#[cfg(test)]
mod tests;