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 direction half of one ordering term.
//!
//! # Why every doc line on the type below is written `#[cfg_attr(doc, doc = "…")]`
//!
//! The emitter's own rule is that **descriptions come from `attrs(desc = …)` and nowhere else** — a
//! source comment is deliberately not published, because what reaches a schema is what a declaration
//! says reaches it. The hand-written filter faces in [`filter`](super::filter) keep it the plain way,
//! by writing `description: None` into the registry entry they build.
//!
//! This type cannot: it is the one wire type here rendered by a DERIVE, and
//! `async-graphql-derive`'s `Enum` calls `get_rustdoc` on the type and on every variant
//! unconditionally, with no attribute to decline it — that library's `desc` word exists on an
//! ARGUMENT and on an interface field's arguments, and on no type and no field. So a plain `///` on
//! this enum ships as its GraphQL description, and this one shipped paragraphs about polarsync and
//! [`crate::Id`] to every schema built on the framework.
//!
//! `cfg_attr(doc, …)` is what closes it, and it closes it under BOTH readings of when a `cfg_attr`
//! is expanded:
//!
//! - stripped before the derive runs — then an ordinary build, where `doc` is off, has no `#[doc]`
//!   left for `get_rustdoc` to find;
//! - passed through to the derive — then `get_rustdoc` sees a `Meta::List` rather than the
//!   `Meta::NameValue` it matches on, and skips it.
//!
//! Either way the description is `None` in every build that serves a schema. `rustdoc` sets `doc`,
//! so the prose is still on this crate's own documentation page, which is what it was always for.
//!
//! The alternative was to hand-write the face the way the filters do, and it was rejected on a
//! measured fact rather than on effort: `OutputType::resolve` has TWO signatures — an `async fn`
//! under async-graphql's `boxed-trait` feature and an `impl Future` return without it — and a
//! feature of that crate is not one this crate can `cfg` on. The derive picks the right one because
//! it runs inside the library; a hand-written impl would compile against whichever half the
//! workspace happened to resolve, and any dependent enabling the other would break a build nobody
//! here could see.
//!
//! **A DECLARED VOCABULARY takes the other road, because it has no derive to reach for.** A derive
//! macro may only APPEND, so the door that equips somebody else's enum cannot attach async-graphql's
//! `Enum` to it — `ingraph-codegen`'s `enumeration::wire` hand-writes the output leg instead, and
//! states the residual wall rather than working around it: under `boxed-trait` that impl is `E0195`
//! at the declaration. This type keeps the derive because it CAN, which is the whole difference
//! between a type this crate declares and a type it equips.

#[cfg_attr(doc, doc = "Which way one ordering term runs.")]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(
  doc,
  doc = "A closed, framework-owned vocabulary: SQL has two directions and a backend that grew a"
)]
#[cfg_attr(
  doc,
  doc = "third would be growing a different clause. So it is a unit enum rather than a seam — the"
)]
#[cfg_attr(
  doc,
  doc = "rule [`crate::Id`] and the comparison kinds already follow, where an OPEN surface is one a"
)]
#[cfg_attr(doc, doc = "downstream crate extends and this is not one.")]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(doc, doc = "# It carries no `Default`, and the absence is the design")]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(
  doc,
  doc = "A generated `*OrderBy` names one column and one direction as ONE value, so `{ title }` is"
)]
#[cfg_attr(
  doc,
  doc = "unspellable on the wire and there is no entry for a default to complete. A `Default` here"
)]
#[cfg_attr(
  doc,
  doc = "would exist only to be reached by a path that cannot arise, and the day one did arise it"
)]
#[cfg_attr(
  doc,
  doc = "would answer silently — which is the failure the pairing was chosen to prevent. polarsync's"
)]
#[cfg_attr(
  doc,
  doc = "ordering pairs two parallel lists by index and fills the short one with"
)]
#[cfg_attr(
  doc,
  doc = "`unwrap_or_default()`, so a length mismatch there is a plausible answer rather than an error."
)]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(doc, doc = "# The wire spelling is `ASC` / `DESC`")]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(
  doc,
  doc = "async-graphql renames enum values to `SCREAMING_SNAKE_CASE`, which is what GraphQL's own"
)]
#[cfg_attr(
  doc,
  doc = "convention asks for, so the Rust `Asc` reaches a client as `ASC`. The TYPE name is spelled"
)]
#[cfg_attr(
  doc,
  doc = "explicitly for the reason [`Score`](crate::Score)'s scalar name is: a wire name is a schema"
)]
#[cfg_attr(doc, doc = "commitment and a Rust rename is not a schema change.")]
#[cfg_attr(doc, doc = "")]
#[cfg_attr(
  doc,
  doc = "Every line of this is behind `cfg_attr(doc, …)` and NONE of it is published — see the"
)]
#[cfg_attr(
  doc,
  doc = "module note for the derive that would otherwise publish it, and for why the guard holds"
)]
#[cfg_attr(doc, doc = "whichever way a `cfg_attr` is expanded.")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "async-graphql", derive(async_graphql::Enum))]
#[cfg_attr(feature = "async-graphql", graphql(name = "OrderDirection"))]
pub enum OrderDirection {
  #[cfg_attr(doc, doc = "Smallest first — `ORDER BY <column> ASC`.")]
  Asc,
  #[cfg_attr(doc, doc = "Largest first — `ORDER BY <column> DESC`.")]
  Desc,
}

impl OrderDirection {
  /// This direction as the flag
  /// [`QueryBuilder::order_by`](crate::comparison::sql::QueryBuilder::order_by) takes.
  ///
  /// The enum is the WIRE face and the `bool` is the builder's parameter, so one of the two has to
  /// give. It is this direction rather than the builder's signature: a `bool` argument at a call
  /// site says nothing about which way `true` runs, and the ordering seam is reached by generated
  /// code that would carry that ambiguity into every emitted lowering. Naming the bridge is what
  /// keeps the ambiguity to one function with two arms.
  ///
  /// An ordinary `///` because the derive does not read an inherent impl: what `get_rustdoc` is
  /// asked for is the ENUM's own attributes and each VARIANT's, and this is neither.
  #[inline]
  #[must_use]
  pub const fn is_descending(self) -> bool {
    matches!(self, Self::Desc)
  }
}

#[cfg(test)]
mod tests;