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
//! A field's NAME, as a type a value cannot be passed as: [`FieldName`].

use crate::name::borrowed_name;

borrowed_name! {
  /// A field's name — an UNQUOTED identifier, and the one thing on the lowering path that becomes
  /// SQL TEXT rather than a bind.
  ///
  /// # What a `&str` here could not say
  ///
  /// [`ComplexComparison::apply`](crate::ComplexComparison::apply) renders the name it is given
  /// into the statement, because an identifier is not a value and no placeholder stands for one —
  /// the asymmetry [`quote_ident`](crate::comparison::sql::quote_ident) exists to make safe. Every
  /// OPERAND on the same path is text too, so with the name spelled `&str` the two were one type
  /// and the compiler had nothing to check: an operand handed in where a name was meant is quoted
  /// and spliced in as a column nobody declared, and the predicate then compares two columns.
  /// Quoting keeps that from becoming syntax; it cannot keep it from being the wrong question.
  ///
  /// A type rather than a check, because there is no check to write. Every `&str` is a legal name,
  /// so nothing about the string says which of the two roles it was in — only where it came from
  /// does, and a type is what records that.
  ///
  /// # It validates nothing, and its twin does
  ///
  /// `""`, `a"b` and `ключ` are all field names, and refusing them here would be refusing names
  /// that legitimately occur: the name is rendered by a backend that QUOTES it, so a string with
  /// no second meaning available to it is still a column somebody can declare. That is the whole
  /// difference from [`SlotName`](crate::SlotName), which is the same construction over a charset
  /// — an index is a directory or a table, where no quoting exists, so there the same strings are
  /// not names at all. Two policies, therefore two types.
  ///
  /// # It costs nothing
  ///
  /// `#[repr(transparent)]` over `str` and holding nothing else, so `&FieldName` is a `&str` at
  /// the ABI and [`new`](Self::new) is a VIEW rather than a conversion. It is unsized for the
  /// reason `str` is, which is why it carries neither [`Clone`] nor [`Copy`]: what a caller holds
  /// is the borrow. No owned form stands beside it, and none is waiting to — one arrives when a
  /// caller that cannot borrow does.
  ///
  /// # A FIELD, not a column
  ///
  /// The SQL family spells one of these as a column and a document family spells it as a key. The
  /// NAME is what the two share, which is why it lives at the root rather than inside either — the
  /// second backend takes it unchanged rather than restating it under its own word.
  ///
  /// # It states no joining convention
  ///
  /// A column may be several of these — one [`Path`](crate::Path) segment per layer — and what
  /// runs them together is a BACKEND's decision: SQL joins with `_` and brackets the result, where
  /// a document nests them along a real path. This type is ONE segment and performs no joining, so
  /// a family joining differently needs nothing from here and nothing here has to move.
  pub struct FieldName;
}

impl FieldName {
  /// View `name` as a field name.
  ///
  /// `const`, so a name known at compile time can be built in a constant — which is where the
  /// names a schema declares actually are.
  ///
  /// Infallible, and that is the type's content rather than an omission — see the type's note on
  /// what it does not validate.
  #[inline]
  pub const fn new(name: &str) -> &Self {
    Self::view(name)
  }

  /// The string this name views.
  ///
  /// Beside [`Deref`](core::ops::Deref) and [`AsRef`](core::convert::AsRef) rather than instead of
  /// them, and the difference is CONSTNESS: a trait method cannot be `const`, so neither of those
  /// can be called where a name has to be read at compile time. That position is real — a
  /// declaration's relation audit compares a declared field name against the names a record's
  /// emitted evidence carries, and it is a `const` that does the comparing.
  #[inline]
  pub const fn as_str(&self) -> &str {
    &self.0
  }

  /// Whether this name is `other`, compared in a `const`.
  ///
  /// [`PartialEq`] over `str` is not one, and every audit this crate writes over a declared name
  /// runs at compile time: a relation's full form checks a field against the names its source
  /// published, and a table descriptor checks its key columns against the columns it carries. Both
  /// are `const` evaluations, and both used to carry a byte loop of their own.
  ///
  /// It takes a `&str` rather than a second name, because the party that HAS a name is asking about
  /// a party that has a token — `field = "video_id"` is a string a declaration wrote — and viewing
  /// that token as a name first would be a conversion neither side asked for.
  ///
  /// # Examples
  ///
  /// ```
  /// use ingraph::FieldName;
  ///
  /// const _: () = assert!(FieldName::new("media_id").is("media_id"));
  /// const _: () = assert!(!FieldName::new("media_id").is("media"));
  /// ```
  #[inline]
  #[must_use]
  pub const fn is(&self, other: &str) -> bool {
    let (one, other) = (self.as_str().as_bytes(), other.as_bytes());
    if one.len() != other.len() {
      return false;
    }
    let mut at = 0;
    while at < one.len() {
      if one[at] != other[at] {
        return false;
      }
      at += 1;
    }
    true
  }
}

#[cfg(test)]
mod tests;