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 THIRD EDGE FACT and the chain that spends it — [`Route::depth`] and [`route_depth`].
//!
//! Beside [`tests`](super::tests) rather than inside it, on the directory-module precedent this crate
//! already uses: one file per thing being proved, and what is proved here is a PRECEDENCE — three
//! tiers, and which of them wins where two are written at once.

use core::num::{NonZeroU32, NonZeroUsize};

use super::{Route, route_depth};

/// A route's interior, standing in for an emitted package.
///
/// Its `ceiling` row RETIRED with the wall law — a protective number never crosses the wire — so
/// what stands here is a knob of the ordinary kind: a preference, which is the family that does
/// travel on a request.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
struct Knobs {
  fold: Option<u8>,
}

fn depth(n: usize) -> NonZeroUsize {
  NonZeroUsize::new(n).expect("the fixture numbers are not zero")
}

fn ceiling(n: u32) -> NonZeroU32 {
  NonZeroU32::new(n).expect("the fixture numbers are not zero")
}

/// **AN UNCONFIGURED EDGE NAMES NO DEPTH.** The third fact joins the two constants without becoming a
/// third constant: there is no number that means *as deep as whatever is below me*, so the seat is
/// empty and the chain is what fills it.
#[test]
fn the_unconfigured_edge_names_no_depth() {
  assert_eq!(Route::<Knobs>::new().depth(), None);
  assert_eq!(Route::<Knobs>::default().depth(), None);
}

/// The builder sets it, and leaves the other three alone — the same composition the older three have.
#[test]
fn the_depth_builder_leaves_the_other_edge_facts_alone() {
  let route = Route::new()
    .with_weight(2.5)
    .with_enabled(false)
    .with_depth(depth(50))
    .with_options(Knobs { fold: Some(3) });

  assert_eq!(route.depth(), Some(depth(50)));
  assert!((route.weight() - 2.5).abs() < f64::EPSILON);
  assert!(!route.enabled());
  assert_eq!(route.options(), Some(&Knobs { fold: Some(3) }));
}

/// **THE IN-PLACE FORM REACHES A ROUTE ALREADY INSIDE A PACKAGE**, and it CLEARS as well as names —
/// which is the half a consuming builder cannot express at all.
#[test]
fn the_in_place_form_both_names_a_depth_and_takes_one_away() {
  let mut route = Route::<Knobs>::new();

  route.set_depth(Some(depth(7)));
  assert_eq!(route.depth(), Some(depth(7)));

  route.set_depth(None);
  assert_eq!(
    route.depth(),
    None,
    "a depth that cannot be withdrawn would make the deferral one-way",
  );
}

/// **THE CEILING BEATS THE EDGE** — the precedence pin, RE-AIMED by the wall law it used to state
/// backwards.
///
/// It read *the edge beats the route's own ceiling*, and the reasoning beside it was that both
/// numbers were the same caller's, written in one request, so the statement about the fold being run
/// was the more specific one. The wire road broke that premise: `depth` is CLIENT-writable, and
/// against a client-writable ask a bound that yields to it is not a bound. A ceiling is protective
/// where a depth is a preference, so it CAPS rather than losing.
///
/// The attack the ruling itself named is the second assertion: a request writing half a million
/// against a wall of a hundred fetches a hundred.
#[test]
fn the_declared_ceiling_caps_the_edge_it_used_to_lose_to() {
  assert_eq!(
    route_depth(Some(depth(50)), Some(&ceiling(20)), depth(10)),
    depth(20),
  );
  assert_eq!(
    route_depth(Some(depth(500_000)), Some(&ceiling(100)), depth(10)),
    depth(100),
  );
}

/// **AN UNDEPTHED ASK IS THE BUDGET, CAPPED BY THE SAME WALL** — the second precedence pin, re-aimed
/// with the first.
///
/// It read *an undepthed edge falls to the ceiling*, which was the ceiling REPLACING the fetch. The
/// word's plain meaning is a cap, so what an absent depth falls to is the caller's own budget, and
/// the wall narrows that exactly as it narrows a written one. Both directions are asserted, because
/// a `min` that only ever fires one way would be indistinguishable from the old replacement.
#[test]
fn an_undepthed_ask_is_the_budget_capped_by_the_wall() {
  assert_eq!(route_depth(None, Some(&ceiling(20)), depth(100)), depth(20));
  assert_eq!(route_depth(None, Some(&ceiling(200)), depth(10)), depth(10));
}

/// **AND WITH NO CEILING, THE ASK RUNS FREE** — the author's INFORMED OPENNESS, which is what an
/// absent wall means rather than a gap the framework fills.
#[test]
fn no_depth_and_no_ceiling_falls_to_the_callers_budget() {
  assert_eq!(route_depth(None, None, depth(10)), depth(10));
}

/// **A DEPTH BELOW THE BUDGET IS LEGAL**, and it is not refused or widened anywhere.
///
/// Every number in this pipeline is a ceiling in the ordinary sense rather than a promise, so a
/// caller cheapening one route while asking for a wide answer is asking for exactly what it asked
/// for. The assertion is that the function hands the number back untouched — no `max`, no clamp up
/// against the budget, and no clamp up against the wall either.
#[test]
fn a_depth_below_the_budget_is_handed_back_untouched() {
  assert_eq!(route_depth(Some(depth(5)), None, depth(10)), depth(5));
  assert_eq!(
    route_depth(Some(depth(5)), Some(&ceiling(20)), depth(10)),
    depth(5),
  );
}

/// **THE CEILING WIDENS INTO THE DOOR'S CURRENCY**, at a value no `u32`-to-`usize` conversion could
/// have been taken for granted at.
///
/// `NonZeroU32` is the width a declaration publishes a ceiling at and `NonZeroUsize` is the door's,
/// and there is no infallible widening between them. The number at the top of the `u32` range is
/// what makes the conversion visible rather than incidental — and under the cap it is the ASK that
/// comes back, a wall that wide narrowing nothing.
#[test]
fn the_declared_ceiling_crosses_into_the_doors_currency_whole() {
  assert_eq!(
    route_depth(None, Some(&ceiling(u32::MAX)), depth(10)),
    depth(10),
  );
  assert_eq!(
    route_depth(
      Some(depth(u32::MAX as usize)),
      Some(&ceiling(u32::MAX)),
      depth(10)
    ),
    depth(u32::MAX as usize),
  );
}

/// THE WIRE HALF — the row rides wherever a [`Route`] crosses, because the crossing is ONE generic
/// impl over the parameter.
#[cfg(feature = "async-graphql")]
mod wire {
  use core::num::NonZeroUsize;

  use async_graphql::{EmptyMutation, EmptySubscription, InputObject, InputType, Object, Schema};

  use super::super::Route;

  /// An emitted package's stand-in, with a wire face of its own.
  ///
  /// Its row is a PREFERENCE, which is the only family that crosses: the `ceiling` that used to
  /// stand here left the request surface with the wall law.
  #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, InputObject)]
  struct TranscriptFulltextOptions {
    fold: Option<u32>,
  }

  struct Query;

  #[Object]
  impl Query {
    /// The one resolver, whose ARGUMENT is what makes the route reachable from the schema root.
    async fn fused(&self, route: Option<Route<TranscriptFulltextOptions>>) -> bool {
      route.is_some_and(|route| route.depth().is_some())
    }
  }

  fn sdl() -> String {
    Schema::build(Query, EmptyMutation, EmptySubscription)
      .finish()
      .sdl()
  }

  /// **THE `depth` ROW IS PUBLISHED, NULLABLE, AND CARRIES NO DEFAULT.**
  ///
  /// All three halves matter. Published, because a knob the wire cannot reach is a knob only a Rust
  /// caller has. Nullable, because absence is the deferral. And DEFAULTLESS, because an SDL default
  /// would be a literal claiming to be a deferral — the two bare fields beside it are exactly the
  /// case where a literal IS the meaning, which is what makes the difference readable in one schema.
  #[test]
  fn the_edge_publishes_a_defaultless_depth_beside_its_two_constants() {
    let sdl = sdl();

    assert!(sdl.contains("depth: Int\n"), "{sdl}");
    assert!(
      !sdl.contains("depth: Int ="),
      "a deferral must not publish a literal: {sdl}",
    );
    assert!(sdl.contains("weight: Float = 1"), "{sdl}");
    assert!(sdl.contains("enabled: Boolean = true"), "{sdl}");
  }

  /// **A WRITTEN DEPTH PARSES, AND AN ABSENT ONE STAYS ABSENT** — the omissibility the de-Option law
  /// needs, read off the parse rather than off the schema.
  #[test]
  fn a_written_depth_parses_and_an_absent_one_defers() {
    let mut object = async_graphql::indexmap::IndexMap::new();
    object.insert(
      async_graphql::Name::new("depth"),
      async_graphql::Value::from(50_u64),
    );

    let named = <Route<TranscriptFulltextOptions> as InputType>::parse(Some(
      async_graphql::Value::Object(object),
    ))
    .expect("one field is a route");
    assert_eq!(named.depth(), NonZeroUsize::new(50));

    let bare = <Route<TranscriptFulltextOptions> as InputType>::parse(Some(
      async_graphql::Value::Object(async_graphql::indexmap::IndexMap::new()),
    ))
    .expect("an empty object is a route");
    assert_eq!(bare.depth(), None);
  }

  /// **A ZERO IS REFUSED AT THE PARSE**, which is where the zero decision belongs once the currency
  /// is a non-zero one.
  ///
  /// The seam declines to represent a zero and the door family no longer takes one, so the wire is
  /// the last place a `0` can arrive — and it arrives as an INPUT ERROR naming the field rather than
  /// as an empty answer nobody asked for.
  #[test]
  fn a_zero_depth_is_an_input_error_rather_than_an_empty_answer() {
    let mut object = async_graphql::indexmap::IndexMap::new();
    object.insert(
      async_graphql::Name::new("depth"),
      async_graphql::Value::from(0_u64),
    );

    let refused = <Route<TranscriptFulltextOptions> as InputType>::parse(Some(
      async_graphql::Value::Object(object),
    ));

    assert!(refused.is_err(), "a zero depth was accepted");
  }
}