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 MongoDB engine: the PACKAGE a query renders into, the DOCUMENT a write stores, what a stored
//! document answers a query with, and — where the driver is compiled in — the lane that runs either.
//!
//! # Two layers, and the lower one is a public escape hatch
//!
//! The lower layer is this module under the `mongo` feature: it builds a [`MongoPipeline`] — a
//! collection, the aggregation stages, and the collections those stages READ — and, through
//! [`MongoWrite`], the documents the four write commands take. It executes nothing. A caller holding
//! their own `mongodb::Database` can take either and run it however they like, which is what makes
//! the rendering usable without this crate owning the driver.
//!
//! The upper layer is [`lane`](self::lane) under the `mongodb` feature: it takes a database handle
//! once and runs the package, so the ordinary path writes no glue at all. The split is the same one
//! the SQL family makes between `comparison::sql` (render) and [`query::sql`](super::sql)
//! (execute) — except that there the driver arrives with the family root, and here it is a second
//! feature, because `mongodb` brings a whole tokio runtime with it and a build that only renders
//! must not pay for one. See the crate manifest's `mongodb` entry for the measurement.
//!
//! # The WRITE half is [`write`](self::write), and it answers the read half's four verbs
//!
//! `insert` / `upsert` / `delete` / `delete_where`, mirroring the SQL write lane's grammar seat for
//! seat — and shorter than it by three whole sections, because a record is ONE DOCUMENT here: no edge
//! statements, no provenance statements, no transaction bracket. That module's note carries the
//! argument, the embedded-array cascade among it.
//!
//! # The lane is ALWAYS an AGGREGATION, and `find` is not used at all
//!
//! Every lane renders a pipeline: a flat query is `[$match, $sort, $limit]` rather than a `find`
//! with a sort and a limit beside it. Two reasons, and the second is why it is a RULING rather than
//! a convenience:
//!
//! - **`$lookup` has no `find` spelling.** A relation predicate is a join, which MongoDB answers in
//!   a pipeline and nowhere else — see
//!   [`MongoRefComparison`](crate::comparison::mongo::MongoRefComparison), whose family answered a
//!   blanket refusal until this lane gave the stage a position. A lane that spoke `find` for the flat
//!   case and pipelines for the joined one would be two engines with two paging stories.
//! - **One shape means one place to be wrong.** The `$match` a flat query renders is the same
//!   document the joined one renders, and the `$sort`/`$limit` after it are the same stages — so a
//!   page's boundary behaviour is decided once whatever the filter turned out to be.
//!
//! What it costs is a `$sort` on a query that could have been a bare `find`, which the server plans
//! identically once the sort is index-covered — and the framework's page always writes an order
//! anyway, because a cursor is a position in one.
//!
//! # `id` on the wire, `_id` in the document
//!
//! A record's id is STORED as `_id`: it is the field MongoDB indexes uniquely without being asked,
//! and a document carrying both an `_id` the server minted and an `id` the declaration wrote would
//! be one row with two identities. The declaration and the wire face still say `id`, so the mapping
//! lives in exactly two places — the extraction, which reads `_id` into the row's id field, and the
//! FIELD-PATH renderer, which is where a filter, a sort and a keyset all reach a column name. See
//! [`write_field_path`](crate::comparison::mongo::write_field_path) for the renderer's half.
//!
//! # What is measured here, and what is not
//!
//! The tests beside this module assert on the PACKAGE, because building one is what this module
//! does: a pipeline is a `bson::Document` list, so a golden is an exact value rather than a string
//! comparison. Whether a page WALKS correctly is not visible in the pipeline — a keyset that skips
//! a row is a perfectly good aggregation that answers without an error — so that half is measured
//! against a real server and recorded where it was measured; see [`MongoKeyset`] for the walk this
//! lane inherits from the SQL family's, and [`lane`](self::lane) for the live posture.

mod error;
mod extract;
mod keyset;
mod order;
mod package;
mod subject;
mod write;

// The DERIVED document's road through this module's two tables — public, because what names it is a
// `#[serde(with = "…")]` string an emitted row carries, and a path serde resolves in the DECLARER's
// crate has to be reachable from there.
//
// It rides `serde` on top of this module's own `mongo`, and the pair is the honest predicate: the
// functions read `MongoCarrier`/`MongoExtract`, which are bson's tier, and they are named by a
// derive, which is serde's. A build carrying one without the other has no emitted document that
// could name this module — the row derives serde's pair through the same shelf.
#[cfg(feature = "serde")]
pub mod via;

pub use error::{MongoExtractionError, MongoQueryError, MongoTypeError, MongoWriteError};
/// The BSON type-alias namer, crate-internal and reached by name rather than by widening the
/// private `extract` module it lives in — see [`alias`](extract::alias)'s own doc for the argument.
///
/// [`Count`](crate::Count) is not among the callers: its row lives IN `query::mongo::extract`
/// itself, beside `alias`, so its refusal already reaches the function through the module-private
/// `mismatch` helper and needs nothing re-exported.
///
/// # It carried `#[cfg(feature = "derive")]`, and the day that note predicted has ARRIVED
///
/// The gate followed the language family, which rides `derive` — *a build with `mongo` and no
/// `derive` has no builtin outside this module implementing [`MongoExtract`] at all* — and it said
/// what would move it: *a future non-derive builtin that joins the vocabulary from outside
/// `query::mongo` widens this gate to match*.
///
/// One landed and the gate did not move with it. `primitives::time_range`'s module is UNGATED and its
/// [`MongoExtract`] row is `#[cfg(feature = "mongo")]`, so a build carrying `mongo` and not `derive`
/// names a function that is configured out — `E0425`, in the crate's own source, which is exactly
/// what `ci/test-matrix.sh`'s `runtime,mongo` and `runtime,mongodb` lanes compile. So the gate is
/// `mongo`'s now, which is unconditional inside this module: the predicate is *does this build have
/// the backend*, and every party that can implement the vocabulary is under it.
pub(crate) use extract::alias;
pub use extract::{MongoExtract, field};
pub use keyset::MongoKeyset;
pub use order::{MongoOrder, MongoSortError};
pub use package::{MongoPipeline, address, ordered, ordered_with, scan};
pub use subject::{MongoFields, MongoHop, MongoNesting, MongoSubjects, sort_alias};
pub use write::{MongoWrite, removal, removal_where, replacement, stored};

#[cfg(feature = "mongodb")]
mod lane;
#[cfg(feature = "mongodb")]
mod options;

#[cfg(feature = "mongodb")]
pub use lane::{
  delete, delete_in, delete_where, delete_where_in, documents, documents_in, find, find_in, get,
  get_in, insert, insert_in, upsert, upsert_in,
};
#[cfg(feature = "mongodb")]
pub use options::{DEFAULT_SPANNING_CONCERN, MongoOptions};

use bson::{Bson, Document};

use super::CrossingError;
use crate::{
  ComplexComparison, CursorValue, FieldName, Identifiable, OrderTerm, Record, RecordAddress,
  Transformer,
  comparison::mongo::{Mongo, MongoCarrier},
};

/// One MongoDB document, as the engine queries the record it stores.
///
/// # The binding is on the ROW, exactly as [`SqlQuery`](super::sql::SqlQuery)'s is
///
/// A declaration storing a record in MongoDB and in SQLite emits two row types, and everything a
/// query needs that varies — the field names, the stored types, the collection — varies with
/// exactly that. So this is implemented on the emitted document and names the record it stores.
///
/// What it does NOT carry is a dialect parameter. There is one MongoDB, one wire format and one
/// query vocabulary, which is the same absence [`comparison::mongo`](crate::comparison::mongo)
/// records one layer down: where the SQL family has a table of (kind × dialect) this family has a
/// list of kinds, and where a SQL query binding is generic in `Db` this one is a plain impl.
pub trait MongoQuery: Sized + 'static {
  /// The record this document stores.
  ///
  /// TWO vocabularies, and the engine reads one projection out of each — the arrangement
  /// [`SqlQuery::Record`](super::sql::SqlQuery::Record) states and the reason it states it:
  /// [`Identifiable`] gives the address `get` takes, and [`Record<Mongo>`](Record) gives the
  /// predicate a client's filter crosses into.
  type Record: Transformer + Record<Mongo, Comparison: ComplexComparison<Mongo>>;

  /// The collection this document is stored in, and the field identifying one of them.
  ///
  /// The key column is the declaration's own id — spelled `id` here, and rendered `_id` by every
  /// party that writes a field path. See the module note for why the two differ.
  const ADDRESS: RecordAddress;

  /// Every field a nested join may land this collection's documents in, indexed by the depth of the
  /// scope that opened it.
  ///
  /// ```text
  /// ALIASES == ["__ig_scene_0__", "__ig_scene_1__", …, "__ig_scene_7__"]
  /// ```
  ///
  /// # It is the SQL family's mint under a different job
  ///
  /// The names are the same shape and come from the same `ingraph-codegen` mint — a pure function of
  /// the collection's name and a depth, so nothing is built while a pipeline is assembled. What they
  /// NAME differs: there an alias stands for a row source in a `FROM`, and here it is the `as` field
  /// a `$lookup` writes its results into. That is why this is a second item rather than a shared
  /// one, and why [`SqlQuery::ALIASES`](crate::query::sql::SqlQuery::ALIASES) could not be read from
  /// here in any case — its binding's parameter is an `sqlx::Database`, and a build carrying this
  /// backend need not carry sqlx at all.
  ///
  /// # `ALIASES[0]` is minted like the rest and is never WORN
  ///
  /// A document at depth zero is the one the pipeline runs over, so it lands in no join field. The
  /// entry exists so that the array is indexed by depth directly: a table starting at depth one
  /// would need every use site to subtract, which is an arithmetic step each of them could get wrong
  /// and none could be caught at.
  ///
  /// # A SLICE, so the depth is this document's rather than the framework's
  ///
  /// [`DEPTH_CEILING`](crate::query::DEPTH_CEILING) is what an expansion mints when the declaration
  /// names no number, and `mongo(alias(depth = 16))` is a collection saying its joins nest
  /// deeper. The same block's `prefix` moves the family off `__ig`. See
  /// [`SqlQuery::ALIASES`](crate::query::sql::SqlQuery::ALIASES), which took the shape first and for
  /// the same reasons.
  ///
  /// # Past the last entry a lowering REFUSES
  ///
  /// A relation nesting past the last name answers
  /// [`MongoLoweringError::RelationDepth`](crate::comparison::mongo::MongoLoweringError::RelationDepth)
  /// — carrying THIS slice's length — rather than reusing a name. Reuse is the silent case: a join
  /// field is a KEY of the document being joined onto, so a repeat is written twice and the second
  /// `$lookup` overwrites the first.
  const ALIASES: &'static [&'static str];

  /// Every field this document carries, in the order the extraction reads them.
  ///
  /// The DOCUMENT's rather than the record's: a partial document holds the fields it holds, and the
  /// extraction reads each by name, so the two cannot disagree about which fields were asked for.
  ///
  /// Unlike the SQL family's `COLUMNS` this is not a `SELECT` list — an aggregation returns the
  /// whole document unless a `$project` says otherwise, and this lane writes none. It is here
  /// because a `$project` is what a partial document will need and because a reader of a package
  /// should be able to see what the extraction expects.
  const FIELDS: &'static [&'static FieldName];

  /// Every collection a query over this document READS — the fact a package carries and the
  /// execution lane's read concern is chosen from.
  ///
  /// # It DEFAULTS to the one collection, which is the whole of a flat query
  ///
  /// A query with no join reads the collection it runs against and nothing else, so the default is
  /// derived from [`ADDRESS`](Self::ADDRESS) and no binding states it. A join adds the collections
  /// it looks into, and it is the party that ADDED the stage that names them — which is what keeps
  /// the read-concern policy from being a guess made at execution time.
  ///
  /// It defaults for the same reason `SqlQuery::COLLECTIONS` does: the case that pays should be the
  /// one that asked, and a second trait every document had to implement would make the flat case
  /// pay for the joined one.
  const READS: &'static [&'static FieldName] = &[Self::ADDRESS.table()];

  /// The record's id as this database stores it.
  ///
  /// # Errors
  ///
  /// Whatever the declaration's own column conversion refuses with: an address holds the record's
  /// domain value and the predicate matches this database's stored one, so a declared `try_from`
  /// converter is on this path and may say no.
  fn id(id: &<Self::Record as Identifiable>::Id) -> Result<Bson, CrossingError>;

  /// This document, read out of the BSON the server returned.
  ///
  /// The bson twin of [`sqlx::FromRow`], and it is an item of this trait rather than a trait of its
  /// own because there is no vendored decode to borrow: sqlx supplies `FromRow` and bson supplies
  /// `Deserialize`, and the second was refused — see
  /// [`MongoExtractionError`] for why a serde decode cannot carry this
  /// framework's typed refusal.
  ///
  /// # Errors
  ///
  /// [`MongoExtractionError`], naming the field that would not read.
  fn from_document(document: &Document) -> Result<Self, MongoExtractionError>;

  /// The record this document holds.
  ///
  /// # Errors
  ///
  /// Whatever the declaration's own conversions refuse with — see [`CrossingError`].
  fn record(self) -> Result<Self::Record, CrossingError>;
}

/// A document that can be ORDERED, and therefore paged.
///
/// A second trait for [`SqlOrdering`](super::sql::SqlOrdering)'s reason, and it buys the same
/// thing: a record with no order-by type has nothing to write a term with, so `.order(…)` is a
/// method that does not resolve rather than a refusal at runtime.
///
/// # Four functions, and one list drives every reading of a page
///
/// [`complete`](Self::complete) turns a client's written terms into the total order the page runs
/// in; [`term`](Self::term) renders one of those into the [`OrderTerm`] this database spells;
/// [`subjects`](Self::subjects) says which of them read ANOTHER COLLECTION and how; and
/// [`value`](Self::value) reads the document at that same term. So the `$sort`, the keyset
/// `$match`, the stages that materialize a nested value and the cursor are four readings of ONE
/// list — [`SqlOrdering`](super::sql::SqlOrdering)'s own arrangement, and it keeps the same thing
/// from going wrong.
pub trait MongoOrdering: MongoQuery {
  /// One ordering term a client may write: which field, and which way it runs.
  ///
  /// `Clone` rather than `Copy` for the reason
  /// [`SqlOrdering::Order`](super::sql::SqlOrdering::Order) records: a term over a neighbour
  /// carries the neighbour's whole order-by, which is a type containing itself unless the nesting
  /// goes behind a pointer.
  type Order: Clone;

  /// One slot of a cursor over this database's stored values.
  ///
  /// [`MongoCarrier`] rather than the SQL family's `Carrier`, which is the whole of what makes a
  /// cursor value per BACKEND rather than per record: the bytes a cursor carries are
  /// [`CursorValue`]'s and are shared, and what a slot BINDS as is the backend's.
  type Value: MongoCarrier + CursorValue;

  /// What each term of a completed order SORTS BY — see [`MongoSubjects`].
  ///
  /// [`MongoFields`] is the answer for every order whose terms are all fields of the document, and
  /// it is what a document with no nested ordering term states. It is not a DEFAULT: an associated
  /// type has none on stable, and the full-set law this crate follows would refuse one anyway — a
  /// document that said nothing about its subjects would be one nobody could ask.
  ///
  /// It exists here rather than being built by the engine because a document is the only party that
  /// knows which of its own terms reach into another collection: the engine holds [`OrderTerm`]s,
  /// which carry a field name whatever produced them.
  type Subjects: MongoSubjects;

  /// The written order completed into a TOTAL one: the client's terms, then the id, ascending.
  ///
  /// The tail is not an option a caller may leave out. Sort values REPEAT, and a cursor that cannot
  /// break the tie skips or repeats rows at the page boundary — so completing the client's own
  /// order is what makes the client's page correct. A term that already names the id MOVES it
  /// rather than repeating it.
  fn complete(written: &[Self::Order]) -> Vec<Self::Order>;

  /// One term as this database renders it: its rename-proof identity, the field this database
  /// spells it, the direction it runs in, and whether that field can hold `null`.
  fn term(order: Self::Order) -> OrderTerm;

  /// What `order`'s terms sort by, in the sequence they run.
  ///
  /// ONE value, built once per query and spent in three positions — the stages that materialize a
  /// nested term's value, the `$sort`, and the resume predicate. Three readings of one plan rather
  /// than three parties that agree, which is the same standard [`MongoOrder`] holds one layer down.
  ///
  /// It is handed the COMPLETED order rather than the client's, because that is the list every one
  /// of those three positions walks.
  fn subjects(order: &[Self::Order]) -> Self::Subjects;

  /// The value this document holds at `order`'s term, or [`None`] where it holds `null` or holds
  /// nothing at all.
  ///
  /// The two absences are ONE answer here, which is the ruled reading of a document store: a field
  /// written as `null` and a field never written are indistinguishable to `$eq: null`, so a cursor
  /// that told them apart would compare against a distinction the query language does not have.
  ///
  /// # The RETURNED document arrives with it, and most terms never read one
  ///
  /// A term over a field of this document reads `self`, where the extraction already put the value.
  /// A NESTED term has no such field: its value rode the pipeline under the name the ENGINE
  /// materialized it as — [`sort_alias`] — so the raw document and that name are handed over rather
  /// than rebuilt, exactly as the SQL family hands its own alias to the same seam. The two are here
  /// for every term whether or not the term reads either.
  ///
  /// # It freezes the BOUNDARY, and that is a ruling rather than an implementation detail
  ///
  /// What the cursor carries is the value this page STOPPED AT, never the id of whom it stopped
  /// beside. A cursor that re-derived a nested sort value through the reference would compare
  /// against whatever the target document holds NOW: a rename between two pages silently empties or
  /// duplicates the next one, with no error anywhere. The reasoning is
  /// [`SqlOrdering::value`](super::sql::SqlOrdering::value)'s and does not change with the backend.
  ///
  /// # Errors
  ///
  /// [`MongoTypeError`] where the materialized value is not the type this cursor slot holds. It
  /// carries no FIELD, which is [`MongoExtract`]'s own standing: the alias is the engine's, so
  /// naming it is the engine's too — the same split [`field`] exists for one layer down.
  ///
  /// A term over a field of this document refuses nothing: it is reading a value the extraction
  /// already crossed.
  fn value(
    &self,
    order: Self::Order,
    raw: &Document,
    alias: &str,
  ) -> Result<Option<Self::Value>, MongoTypeError>;
}

/// The `$eq`-shaped operand a keyset arm and an address predicate both bind — one function so that
/// a stored value reaches a filter document by exactly one route.
///
/// [`None`] is `null`, which is MongoDB's own conflation of *written as null* and *never written*:
/// `{f: {$eq: null}}` matches both. The framework does not narrow it, because the query language
/// offers nothing to narrow it WITH — `$type: "null"` would separate them and would then make a
/// keyset's equality leg disagree with its own `$sort`, which reads a missing field as `null`.
///
/// The encoding itself is [`MongoCarrier`]'s own row over [`Option`] rather than a match written
/// here, so the value a keyset compares against and the value a stored document holds cannot be two
/// answers. This function is what remains of the shape: an `Option<&V>` where the row takes
/// `&Option<V>`, which is the borrow a keyset already holds.
fn operand<V: MongoCarrier>(value: Option<&V>) -> Bson {
  value.to_bson()
}

#[cfg(test)]
mod tests;