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
//! The construction every one of this crate's borrowed names is: [`borrowed_name`].
//!
//! [`FieldName`](crate::FieldName) names a column, [`SlotName`](crate::SlotName) names an index and
//! [`ReasonName`](crate::ReasonName) names a refusal. The three are one construction three times —
//! a `#[repr(transparent)]` view of a `str`, plus the borrow trio that makes a name and the string
//! it views interchangeable as a map key — and they stay separate types, because the construction
//! is the only thing they share: a slot name's whole content is that it passed a charset, while the
//! other two are deliberately unchecked and are apart from each other for what they are ABOUT. A
//! single type any of them could be built from would have to hold one policy and answer to every
//! role, so what they share is a macro.
//!
//! # The five that name a VARIANT, and why they are the same construction
//!
//! [`SqliteName`](crate::SqliteName) and its four siblings name the word one namespace spells a
//! vocabulary's member as. A vocabulary has as many of those words as it has faces, and they are not
//! one word: a variant may be stored as `lo` in Postgres, shown as `LOW` on the wire, and be `Low`
//! in Rust. Every one of them is a `str`, so a conversion taking one is a conversion taking all of
//! them — `impl TryFrom<&str> for Grade` can exist ONCE, and it would have to pick a namespace and
//! be wrong for the rest.
//!
//! So the namespace is the TYPE, and the conversion family is one impl per namespace with no
//! coherence collision between them. That is [`FieldName`](crate::FieldName)'s own argument applied
//! one level in: every `&str` is a legal name in every namespace, so nothing about the string says
//! which face it came from — only where it came from does, and a type is what records that. And
//! since it is that argument, it is that construction: a view of a `str` costing nothing, not a
//! wrapper of its own.
//!
//! # The conversion family takes a BORROW, and that is measured
//!
//! [`TryFrom`](core::convert::TryFrom)'s type parameter carries an implicit [`Sized`] bound, so
//! `impl TryFrom<SqliteName> for Grade` over a view does not compile: `E0277`, *the size for values
//! of type `str` cannot be known at compilation time … required by an implicit `Sized` requirement
//! on this type parameter in `TryFrom`* — reported twice, once at the `impl` header and once at
//! `try_from`'s own signature, since a function argument is sized too.
//!
//! The family is therefore spelled over the borrow — `impl TryFrom<&SqliteName> for Grade` — which
//! is what every reader of one of these already holds: [`new`](crate::SqliteName::new) hands back a
//! `&Self`, and a vocabulary's accessor hands back a `&'static Self`. Nothing is passed by value
//! anywhere on the path, so the reference in the bound is the reference that was already there.
//!
//! # [`borrowed_name`] emits the DECLARATION, not only the impls
//!
//! The `unsafe` view rests on one claim: the type is `#[repr(transparent)]` over `str` and holds
//! nothing besides it. Emitting the struct is what makes that claim the macro's OWN rather than a
//! precondition each caller has to remember — there is no way to reach the view through a
//! declaration the safety argument does not already cover.
//!
//! `Eq`, `Ord` and `Hash` travel with it for the second half of the same reason. They forward to
//! the inner `str` only because they are DERIVED on a single-field struct, and that forwarding is
//! exactly what the [`Borrow`](core::borrow::Borrow) impl below promises — so the promise and the
//! thing that makes it true are written in one place.
//!
//! # …and the FOLD, which is about a word rather than about a type
//!
//! [`folds_to`] and [`folded`] are here for what they are ABOUT: the words a vocabulary's faces
//! spell, read the way an OPEN vocabulary has to read them. They carry no name type and are reached
//! by emitted code alone — see [`fold`] for the relation and for why there is exactly one of it.

/// Declare a borrowed name type: a `#[repr(transparent)]` view of a `str`, its unchecked view
/// constructor, and its borrow trio.
///
/// The caller writes the documentation, the visibility, the name, and the type's own public
/// constructor — which is where a name type says what it refuses. What a name type cannot differ
/// in is here.
macro_rules! borrowed_name {
  ($(#[$doc:meta])* $vis:vis struct $ty:ident;) => {
    $(#[$doc])*
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    #[repr(transparent)]
    $vis struct $ty(str);

    impl $ty {
      /// View `name` as this type, checking nothing.
      ///
      /// Private, because it is the half of a constructor that CANNOT refuse: a name type's public
      /// door decides for itself whether there is something to refuse before reaching this.
      #[inline]
      const fn view(name: &str) -> &Self {
        // SAFETY: this macro declares `$ty` itself, `#[repr(transparent)]` over `str` and holding
        // nothing besides it, so the two have identical layout and identical validity — every
        // `str` is a valid `$ty`. Both references are fat pointers of the same width, so the
        // LENGTH metadata crosses unchanged, and the elided lifetimes tie the result to `name`, so
        // the borrow stays the caller's. This is the shape `Path::new` uses over `OsStr`.
        //
        // `transmute` rather than a `*const str as *const $ty` cast. Both are `const` as far back
        // as this crate's own MSRV, measured, so the choice is not about what compiles — it is
        // about which one the compiler RECHECKS. The cast keeps compiling if the declared type
        // ever stops being unsized, because a fat-to-thin pointer cast silently DROPS the
        // metadata; the transmute is `E0512` at that moment, *cannot transmute between types of
        // different sizes*.
        unsafe { core::mem::transmute::<&str, &$ty>(name) }
      }
    }

    impl core::ops::Deref for $ty {
      type Target = str;

      #[inline]
      fn deref(&self) -> &str {
        &self.0
      }
    }

    /// Beside [`Deref`](core::ops::Deref) rather than instead of it: a coercion site takes the
    /// deref, and a generic `impl AsRef<str>` bound takes this — a name has to satisfy both, and
    /// neither implies the other.
    impl core::convert::AsRef<str> for $ty {
      #[inline]
      fn as_ref(&self) -> &str {
        &self.0
      }
    }

    /// The face a keyed lookup goes through, and the contract the derived
    /// [`Eq`](core::cmp::Eq), [`Ord`](core::cmp::Ord) and [`Hash`](core::hash::Hash) make good:
    /// each forwards to this same `str`, so a name and its borrowed form compare equal, order
    /// together and hash alike.
    ///
    /// That is [`Borrow`](core::borrow::Borrow)'s contract rather than a convenience: a map keyed
    /// by one and probed with the other has to reach the same bucket, and an implementation
    /// answering with anything else would break it silently.
    impl core::borrow::Borrow<str> for $ty {
      #[inline]
      fn borrow(&self) -> &str {
        &self.0
      }
    }
  };
}

/// Declare a VARIANT-name type: [`borrowed_name`]'s construction, plus the one constructor every
/// namespace spells identically.
///
/// The five differ in nothing but which face they name, so their doors are written once here rather
/// than five times — which is [`borrowed_name`]'s own argument taken one step: what a group of names
/// shares is a macro. It is [`FieldName`](crate::FieldName)'s door verbatim, an infallible `const`
/// view, because a variant's word is in exactly that position.
macro_rules! variant_name {
  ($(#[$doc:meta])* $vis:vis struct $ty:ident;) => {
    borrowed_name! {
      $(#[$doc])*
      $vis struct $ty;
    }

    impl $ty {
      /// View `name` as this namespace's word for a variant.
      ///
      /// `const`, so a word known at compile time can be built in a constant — which is where the
      /// words a vocabulary's expansion writes actually are, an accessor handing back a
      /// `&'static Self`.
      ///
      /// 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)
      }
    }
  };
}

variant_name! {
  /// A variant's word as SQLite spells it — the value a column of the vocabulary holds there.
  ///
  /// # It validates nothing, and the two reasons are [`FieldName`](crate::FieldName)'s
  ///
  /// A stored word is a VALUE, bound as a parameter and never spliced into a statement, so there is
  /// no character here that acquires a second meaning — the situation that puts a charset on
  /// [`SlotName`](crate::SlotName) and leaves both of these unchecked. And every `&str` is a legal
  /// word in every one of these namespaces, so nothing about the string says which face it came
  /// from; only where it came from does, and the type is what records that.
  ///
  /// # It exists whatever this build compiled, and what the FORM decides instead
  ///
  /// The type is a word, and a word names no driver. What a build's FEATURES decide is which
  /// per-backend impls a vocabulary's expansion carries; what the declared FORM decides is whether
  /// this namespace has a face at all — a backend storing the discriminant has no text for one of
  /// these to view, so a vocabulary at that form emits neither the accessor nor the conversion, and
  /// asking for one is `E0277` at the ask.
  ///
  /// # It costs nothing
  ///
  /// `#[repr(transparent)]` over `str` and holding nothing else, so `&SqliteName` is a `&str` at
  /// the ABI and [`new`](Self::new) is a VIEW rather than a conversion.
  pub struct SqliteName;
}

variant_name! {
  /// A variant's word as PostgreSQL spells it, on [`SqliteName`]'s terms.
  pub struct PostgresName;
}

variant_name! {
  /// A variant's word as MySQL spells it, on [`SqliteName`]'s terms.
  pub struct MysqlName;
}

variant_name! {
  /// A variant's word as MongoDB spells it, on [`SqliteName`]'s terms.
  pub struct MongoName;
}

variant_name! {
  /// A variant's word on the WIRE — the member a GraphQL enum exposes.
  ///
  /// Apart from the four database namespaces for what it is ABOUT rather than for how it is
  /// carried: those are values in somebody's rows, and this is a name in somebody's schema. The
  /// grammar differs with them — a stored word may be anything, and a wire word is held to
  /// GraphQL's own Name production at the DECLARATION that spells it, which is where a refusal can
  /// still point at the token that broke it.
  pub struct GraphqlName;
}

mod fold;

pub use fold::{folded, folds_to};

pub(crate) use borrowed_name;

#[cfg(test)]
mod tests;