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 GraphQL binding: the built-in filter types, the contracts a queryable field answers to — the
//! map from an interpretation to the filter that guards it, and the emptiness question every filter
//! answers alike — and, behind the `async-graphql` feature, the WIRE FACE each registered filter
//! renders as.
//!
//! The map is keyed on an INTERPRETATION rather than on a field's Rust type because a type does not
//! determine its own reading: `Vec<u8>` is a byte string or a list of small integers, and a trait
//! keyed on the type answers once, for the declarer. The interpretations themselves are
//! [`crate::marker`]'s — one level up, because what a column means is asked by every consumer of a
//! declaration while what it resolves to is one axis's answer — and [`lower`] is where this axis
//! answers, one row per marker. It is one trait per FAMILY rather than one trait over all of them,
//! which is what lets a family REFUSE a reading its types do not answer.
//!
//! The default build names no GraphQL library, and that is a feature boundary rather than a
//! principle: the filter types, the maps and the emptiness contract are all library-neutral, and the
//! `async-graphql` feature adds the `InputType` pair that turns one filter instantiation into a
//! GraphQL input object. A second library would arrive the same way, beside it, over the same
//! filters.
//!
//! async-graphql's own `boxed-trait` feature is UNSUPPORTED here and permanently so: it rewrites
//! every resolver into a boxed `async_trait` future, which is a relic of the era before Rust's
//! native async-fn-in-trait and which the plain-async shape this crate's emission is written against
//! superseded — so a build that turns it on is a compile error rather than a silently different
//! expansion, and no seat is kept for it.
//!
//! [`OrderDirection`] is the other wire vocabulary here, and it is a vocabulary rather than a
//! filter: a query says which columns to sort by and which way each runs, and the WAY is the half
//! that is the same for every column of every record. The generated `*OrderBy` supplies the other
//! half — one entry naming one column and one direction — so the framework owns the closed part and
//! the emitter writes the per-record part.
//!
//! [`connection`] is the PAGE's wire face — the relay connection a list field answers with, and the
//! four pagination arguments a client asks for one with. It is where the query lane's *a page needs
//! a written order* stops being a missing method and becomes a sentence, GraphQL having no
//! cross-argument constraint to state it with. Behind the binding whole, the connection type being
//! async-graphql's own.
//!
//! [`door`] is where a resolver's read gets its CONNECTION, and it is here rather than in
//! [`query::sql`](crate::query::sql) because the wall it answers is the wire's: a resolver future is
//! `Send`, a borrowed sqlx connection is not `Acquire` under that bound, and `&Pool` is the surface
//! that is. A pure Rust reader hands the engine its connection directly and needs none of it. Behind
//! the binding AND the SQL family, neither of which alone has the wall.
//!
//! [`load`] is the BATCHING seam beside it — where N asks of one table become one statement — and it
//! is here for the door's reason and gated for the opposite one. The N+1 it closes is a GraphQL
//! shape: several root fields of one document each addressing one row. But the seam itself names no
//! wire library at all, so [`AsyncBatchLoad`], [`BatchError`], [`Batched`] and [`BatchDoor`] are
//! unconditional — an emitted resolver looks for a door in EVERY build — and only the async-graphql
//! `DataLoader` BINDING rides a feature, its own, independent of the binding feature above.
//!
//! [`code`] is the wire's ERROR contract, and it is neither a filter nor a map either: a refusal
//! reaches a client as a sentence and a WORD, and the word is the only half a client may match on.
//! Its vocabulary is unconditional for [`ordering`]'s reason — an expansion cannot spell a feature
//! of this crate — while the two attachments that name async-graphql's error types ride the
//! binding.
//!
//! [`ordering`] is where a LIST of those entries is decoded, and it is the third thing here that is
//! neither a filter nor a map: the schema shows an array, the decode holds a map keyed by the
//! subject each term names, and a client naming one subject twice is refused at that term. Its
//! subject vocabulary is unconditional because an expansion names it; only the decode itself rides
//! the `async-graphql` feature.
//!
//! Almost no filter for a FOREIGN type is defined here. Such a filter belongs with the type it
//! guards, and for a foreign type that is the crate which newtypes it — the same crate that owes the
//! newtype its wire face. The framework owns the contract and the kinds it can name a type for; the
//! declarer owns the rest. The orphan rule enforces the same split from the other side:
//! `async_graphql::InputType` is foreign here, so a wire face can be written only for a filter type
//! this crate declares.
//!
//! [`output`] is the OTHER position's map, and it is the map this module's two input-side ones are
//! measured against: [`ToGraphqlOutput`] says what a domain type becomes where a wire face RETURNS
//! it, with the `Vec` half delegated to the element exactly as
//! [`DefaultVecMarker`](crate::DefaultVecMarker)'s is. One map
//! rather than two, and the asymmetry is the positions': a filter is keyed on an INTERPRETATION
//! because a type does not determine its own reading, while a return is not a reading — what a
//! client receives back is the value the row holds. Behind the binding, the forms being
//! async-graphql's.
//!
//! [`crossed`] is that map's HOLDING adapter, and it is the one thing here that is neither a map nor
//! a filter but a POSITION: async-graphql renders from `&self`, so a face that returns a value it
//! just MADE has nothing for a borrowing arm to point at. [`Crossed`] moves the value into the return
//! type and projects out of its own field at resolve time, delegating every name to the projection —
//! so a column crosses to the same SDL form whether the face borrowed it out of storage or computed
//! it. Behind the binding, the contract it satisfies being async-graphql's.
//!
//! [`carrier`] is the AXIS both positions turn on, and it is what makes the two maps above reach a
//! type this crate has never heard of. [`TextWire`] says which carrier a text operand crosses on and
//! under which schema NAME, keyed on a marker so that a declaring crate answers on a type it owns;
//! [`ToGraphqlInput`] says the same for one ELEMENT of a collection, keyed on the type, and is the
//! bound the two collection faces ask instead of `InputType` — which is what lets a `Vec<u128>`
//! column reach a schema at all and stops a `Vec<Vec<u8>>` one from reaching a schema that lies.
//!
//! [`roster`] is the NAMING CONSTITUTION — the three laws that decide what every wire name in this
//! framework looks like, and the authority table the scalar names and their derived filter names
//! both come out of. It carries no types a schema sees: what it holds is the law, and the inventory
//! the emission-consistency test reads the law back out of.
//!
//! [`scalar`] is where the exceptions to that live, and each of them is the orphan rule read from
//! the OTHER side: an operand whose Rust type may not carry `ScalarType` in any crate but
//! async-graphql's, and which async-graphql declines to carry. A `u128` column reached no schema
//! anywhere for that reason, and a `Vec<u8>` column reached one that answered a different question.
//! What that module ships is a local newtype per operand, carrying the scalar — the arrangement
//! [`DurationFilter`] already proved — so the filter's slot holds the domain value while the wire
//! form is text. The carriers are public because an OUTPUT position returns one.
//!
//! [`DurationFilter`] is the exception the whole KIND was minted for, and it is one because of that
//! same rule rather than in spite of it. Its operand is [`jiff::SignedDuration`], which no
//! downstream crate may give a wire face
//! (`E0117` — the type and the trait are both foreign to it) and which the two crates that COULD
//! have have not: sqlx ships no jiff integration at all, and async-graphql's `jiff` feature stops at
//! the five scalars for `Date`, `Time`, `Timestamp`, `Zoned` and `Span`. The filter type is therefore
//! declared HERE so that the `InputType` impl has somewhere coherent to live, and its whole existence
//! is gated on the feature that supplies the operand.

mod blob;
pub(crate) mod carrier;
mod code;
#[cfg(feature = "async-graphql")]
mod connection;
#[cfg(feature = "async-graphql")]
mod crossed;
mod direction;
#[cfg(all(feature = "async-graphql", feature = "sqlx"))]
mod door;
pub mod filter;
/// The two SEATS a flags vocabulary takes on the wire — the operand scalar and the object face.
#[cfg(feature = "flags")]
mod flags;
// FIVE modules here ride a TIER on top of whatever binding gate they already carried, and the cut
// running THROUGH this module rather than around it is the module's own shape rather than an
// untidiness. What lives here is two things under one name: the filter and scalar VOCABULARY, which
// is core and which a build with no query road still spells every word of, and the WIRE FACES over
// other layers' types. A face is only as portable as what it faces — `fold`, `folded_matches`,
// `matches` and `recipe` each name a `retrieve` type, and `search` names a `resource` — so each of
// the five takes the tier that declares what it renders.
#[cfg(feature = "engine")]
mod fold;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
mod folded_matches;
mod load;
mod lower;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
mod matches;
mod ordering;
// Opened to the crate for ONE item beside the trait: `composed_tail`, which every primitive house
// publishing a GENERIC holder calls, so the raise a composed name takes is one expression rather
// than one per house. The trait itself is re-exported below as every other public name here is.
pub(crate) mod output;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
mod recipe;
#[cfg(feature = "async-graphql")]
mod registry;
pub(crate) mod roster;
pub(crate) mod scalar;
#[cfg(feature = "async-graphql")]
mod score;
// GATED WHOLE, where it used to be half: what lived here unconditionally was `SearchDoor`, a
// citizen an application installed and this crate could describe without a wire binding. The
// resource axis retired it, so everything left is a resolver's own lookup — and the citizen it
// looks up is a `Shared<R>`, which is why the second gate here is `runtime` and not `engine`.
#[cfg(all(feature = "async-graphql", feature = "runtime"))]
mod search;
// THE SIXTH FACE UNDER THE TIER RULE ABOVE: a tower door carries an assembled `retrieve` road, so it
// takes the tier that declares what it holds. Only `install` and the lookup name async-graphql, and
// both are gated inside the module.
#[cfg(feature = "engine")]
mod tower;

/// The two SDL-NAME hooks a record's page is named through, re-exported so an emitted marker names
/// the SHELF rather than the library — the rule every framework path in an expansion follows, and
/// the reason a declaring crate never needs async-graphql as a direct dependency.
///
/// EVERY paged record spends them, not only a renamed one: the ruled default is the record's PLURAL
/// and the library's own default renders the singular, so `emit::queries` resolves the word at
/// expansion time and hands it back through these two traits in every case.
#[cfg(feature = "async-graphql")]
pub use async_graphql::connection::{ConnectionNameType, EdgeNameType};
pub use blob::{BlobDoor, BlobSource};
#[cfg(feature = "async-graphql")]
pub use blob::{
  UnwrittenArtifact, artifact_store, locate_artifact, locate_signed_artifact, read_artifact,
  read_signed_artifact,
};
pub use carrier::{
  Builtin, BytesWire, InputCrossing, OutsideTheInterval, ScalarWire, Std, TextWire, ToGraphqlInput,
  WrongByteWidth, ZeroOperand,
};
pub use code::{ErrorCode, ToErrorCode};
#[cfg(feature = "async-graphql")]
pub use code::{
  refused, refused_address, refused_exchange, refused_filter, refused_input, refused_row,
};
#[cfg(feature = "async-graphql")]
pub use connection::{Connection, PageArgument, PageError, PageRequest, UnraisedPage};
#[cfg(feature = "async-graphql")]
pub use crossed::Crossed;
pub use direction::OrderDirection;
// The flags kind's two wire seats, and the helpers a face is assembled from. Ungated on the
// binding for the reason every filter type here is: the TYPE is what a crossing row names, and only
// its `InputType`/`OutputType` impls ride `async-graphql`.
#[cfg(all(feature = "async-graphql", feature = "sqlx"))]
pub use door::{SqlDoor, SqlSource};
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub use filter::JiffDuration;
pub use filter::{
  BooleanFilter, BytesFilter, ConfidenceFilter, ConfidenceOperand, ConfidenceOperandError,
  ConfidenceWire, EnumFilter, EqualsFilter, FilterSlot, FixedBytesFilter, GraphqlFilter,
  ListFilter, ManyOperands, NestedFilter, Nullable, OneOperand, QuantifiedFilter, RefFilter,
  RelatedFilter, ScalarFilter, ScoreKind, SetFilter, TextFilter, TryMapFilter,
  UnrepresentableConfidence,
};
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub use filter::{DurationFilter, DurationOutOfRange};
#[cfg(feature = "async-graphql")]
pub use filter::{FlattenFace, NullableFace, Sent, SlotFace, sent};
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub use filter::{JiffCivilDateTime, JiffZoneOffset};
#[cfg(feature = "flags")]
pub use flags::{
  FlagsInput, FlagsView, OPERAND, SELF_RETURNING, SYMMETRIC_DIFFERENCE, derive, fixed_fields,
  input_description, input_name, is_self_returning, predicate,
};
// The flags filter, beside the two wire seats above it. One word per feature, so a build taking
// the kind takes the whole of it and a build declining it names none of the three.
#[cfg(feature = "flags")]
pub use filter::FlagsFilter;
#[cfg(feature = "engine")]
pub use fold::FoldDoor;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
pub use fold::installed_fold;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
pub use folded_matches::{FoldedMatch, StreamSighting, folded_matches};
#[cfg(all(feature = "dataloader", feature = "async-graphql"))]
pub use load::AsLoader;
#[cfg(all(feature = "async-graphql", feature = "sqlx"))]
pub use load::SqlRows;
pub use load::{AsyncBatchLoad, BatchAnswer, BatchDoor, BatchError, Batched};
pub use lower::{ToGraphqlFilter, ToGraphqlOrderBy};
#[cfg(all(feature = "async-graphql", feature = "engine"))]
pub use matches::{Match, matches};
#[cfg(feature = "async-graphql")]
pub use ordering::{Orderings, RepeatedSubject};
pub use ordering::{SubjectPath, ToSubjectPath};
pub use output::{OutputCrossing, ToGraphqlOutput};
#[cfg(all(feature = "async-graphql", feature = "engine"))]
pub use recipe::{FusedCitizen, FusedEngine, WireRoot};
#[cfg(feature = "async-graphql")]
pub use registry::{
  RegistryCountsView, RegistryEntry, RegistryFamily, RegistryMutationRoot, RegistryOptionsView,
  RegistryOrigin, RegistryQueryRoot, RegistryState,
};
/// The THIRTEENTH width, and the only carrier here whose OPERAND is somebody else's type —
/// which is why it alone rides a vocabulary feature. See the `half` row in this crate's manifest.
#[cfg(feature = "half")]
pub use scalar::F16;
/// The WIDEST float row, and the only carrier whose operand is a stand-in: `f128` is the roster's
/// name and `rust_decimal::Decimal` is what holds the seat until Rust's own `f128` is stable. See
/// the `rust_decimal` row in this crate's manifest.
#[cfg(feature = "rust_decimal")]
pub use scalar::F128;
/// The COMPILED PATTERN's carrier — the second here whose operand is somebody else's type, and the
/// first whose crossing is a compile. See the `regex` row in this crate's manifest.
#[cfg(feature = "regex")]
pub use scalar::RegexPattern;
pub use scalar::{
  F32, F64, FixedU8Array, HexBytes, HyphenatedUuid, I8, I16, I32, I64, I128, NetIpAddr,
  NetIpv4Addr, NetIpv6Addr, NetSocketAddr, NetSocketAddrV4, NetSocketAddrV6, SmolBytes, U8,
  U8Vector, U16, U32, U64, U128,
};
#[cfg(feature = "async-graphql")]
pub use score::WireScore;
#[cfg(all(feature = "async-graphql", feature = "runtime"))]
pub use search::{search_slot, vector_slot};
#[cfg(feature = "engine")]
pub use tower::TowerDoor;
#[cfg(all(feature = "async-graphql", feature = "engine"))]
pub use tower::{InstalledRoad, installed_road};
// The DRESSED recipe's one demand of a bound tower's request face, ungated by `engine`: it is a
// sentence over `InputType` and names no query-layer type at all.
#[cfg(feature = "async-graphql")]
pub use tower::SearchOptionsFace;

#[cfg(test)]
mod tests;