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 three recipe seams, exercised as a THIRD PARTY writes them — one member and one key, neither
//! of them generated, both reaching a recipe's wire road with nothing but impls.
//!
//! What only this file can say is that the three traits are SPELLABLE by hand: every one of them
//! carries a lifetime, a GAT or an `impl Future`, and a seam nobody outside this crate can write an
//! impl of would be a closed surface wearing an open one's clothes.

use core::{convert::Infallible, future::Future, num::NonZeroUsize};

use super::{FusedCitizen, FusedEngine, WireRoot};
use crate::{AsyncFusedRead, Fusable, Rooted};

/// A third-party member: a fusion package, a read, and the two wire rows — and nothing else.
struct Shots;

/// The engine it is asked through, which a resolver has to be able to spell.
struct Toy;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct Key(u32);

impl Fusable for Shots {
  type Options = ();
  type Question = String;
}

impl AsyncFusedRead<Toy> for Shots {
  type Root = Key;
  type Evidence = f32;
  type Error = Infallible;
  type Ctx<'a>
    = &'a str
  where
    Toy: 'a;

  fn keys<'a>(
    ctx: Self::Ctx<'a>,
    _options: Option<&Self::Options>,
    _question: &Self::Question,
    _limit: NonZeroUsize,
  ) -> impl Future<Output = Result<Vec<Rooted<Self::Root, Self::Evidence>>, Self::Error>> {
    let ranked = vec![Rooted::new(Key(ctx.len() as u32), 1, 0.5)];
    core::future::ready(Ok(ranked))
  }
}

impl FusedEngine for Shots {
  type Engine = Toy;
}

impl FusedCitizen<Toy> for Shots {
  fn ranked<'a>(
    _ctx: &'a async_graphql::Context<'_>,
    options: Option<&'a Self::Options>,
    question: &'a Self::Question,
    limit: NonZeroUsize,
  ) -> core::pin::Pin<
    Box<dyn Future<Output = async_graphql::Result<Vec<Rooted<Key, f32>>>> + Send + 'a>,
  > {
    // THE SHIPPED SHAPE, in miniature: mint what the read owns out of the schema, then spend it on
    // this member's OWN `keys`.
    Box::pin(async move {
      let mut held = String::from("mounted");
      let ranked =
        <Shots as AsyncFusedRead<Toy>>::keys(held.as_mut_str(), options, question, limit)
          .await
          .map_err(|refusal| async_graphql::Error::new(refusal.to_string()))?;
      Ok(ranked)
    })
  }
}

impl WireRoot for Key {
  type Address = u32;
  type Entity = u32;

  fn address(self) -> Self::Address {
    self.0
  }

  fn hydrate<'a>(
    _ctx: &'a async_graphql::Context<'_>,
    keys: Vec<Self>,
  ) -> core::pin::Pin<
    Box<dyn Future<Output = async_graphql::Result<Vec<Option<Self::Entity>>>> + Send + 'a>,
  > {
    let rows: Vec<Option<u32>> = keys.into_iter().map(|key| Some(key.0)).collect();
    Box::pin(core::future::ready(Ok(rows)))
  }
}

/// **THE ENGINE CROSSES AS A PROJECTION**, which is the whole of what a recipe's expansion does with
/// it: the recipe never names `Toy`, it names the row the member wrote.
#[test]
fn a_members_wire_engine_is_reached_by_projection() {
  fn asked_through<M: FusedEngine>() -> &'static str {
    core::any::type_name::<<M as FusedEngine>::Engine>()
  }
  assert!(
    asked_through::<Shots>().ends_with("Toy"),
    "{}",
    asked_through::<Shots>()
  );
}

/// **THE SCHEMA-SIDE READ ANSWERS THE READ SEAM'S OWN ROWS**, inherited rather than restated — so a
/// recipe folding both roads' answers cannot be handed two shapes of one thing.
///
/// Asserted as a COMPILE, because a mismatch here is a type error and never a value: the generic
/// body names `AsyncFusedRead`'s own `Root` and `Evidence` in the answer position and the `const`
/// pins it at a concrete member.
const _: () = {
  #[expect(
    clippy::type_complexity,
    reason = "the SIGNATURE is the assertion — this fn is never called, and a shape written through \
              an alias would stop being the seam's own line"
  )]
  fn rows<'a, M>(
    ctx: &'a async_graphql::Context<'_>,
    options: Option<&'a <M as Fusable>::Options>,
    question: &'a <M as Fusable>::Question,
    limit: NonZeroUsize,
  ) -> core::pin::Pin<
    Box<
      dyn Future<
          Output = async_graphql::Result<
            Vec<Rooted<<M as AsyncFusedRead<Toy>>::Root, <M as AsyncFusedRead<Toy>>::Evidence>>,
          >,
        > + Send
        + 'a,
    >,
  >
  where
    M: FusedCitizen<Toy>,
  {
    <M as FusedCitizen<Toy>>::ranked(ctx, options, question, limit)
  }
  let _ = rows::<Shots>;
};

/// **BOTH TIERS ARE THE ROOT'S OWN ANSWER**, reached by projection exactly as the engine is — so a
/// recipe that publishes an answer pair names neither the address type nor the entity type.
///
/// The ORDER law the trait states is run where a `Context` exists, in
/// `ingraph/tests/search_wire_road.rs`; a context cannot be built outside a running schema, so this
/// half asserts what a token-free reader can: that both rows are there and both are output types.
#[test]
fn both_tiers_of_a_root_are_reached_by_projection() {
  fn published<K: WireRoot>() -> (
    ::std::borrow::Cow<'static, str>,
    ::std::borrow::Cow<'static, str>,
  ) {
    (
      <<K as WireRoot>::Address as async_graphql::OutputType>::type_name(),
      <<K as WireRoot>::Entity as async_graphql::OutputType>::type_name(),
    )
  }
  assert_eq!(published::<Key>(), ("Int".into(), "Int".into()));
  assert_eq!(Key(7).address(), 7);
}