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 stages a nested order adds, asserted as the exact BSON a caller would run.
//!
//! A golden here is a VALUE, which is what the second backend buys over the first: the SQL family's
//! nested-order goldens compare a string, so a whitespace change is a diff and a structural one may
//! not be. These compare documents, and key order is part of what is asserted, because a `$lookup`
//! spec read in another sequence is the same join and a pipeline read in another sequence is not.

use std::sync::Arc;

use bson::{Document, doc};

use super::{MongoFields, joins, sort_alias, sort_key};
use crate::{
  FieldName, OrderDirection, RecordAddress,
  comparison::mongo::MongoLoweringError,
  query::{
    DEPTH_CEILING,
    mongo::{
      MongoOrdering, MongoQuery, MongoSubjects,
      tests::{
        DeepSubjects, KeyframeOrder, ShotMongo, ShotOrder, StripOrder, by_cover_strip_label,
        by_cover_title, subjects, terms,
      },
    },
  },
};

/// The address every stage below is built against — the fixture's, so `id` maps to `_id` exactly as
/// it does in a real package.
const ADDRESS: RecordAddress = <ShotMongo as MongoQuery>::ADDRESS;

/// The stages one written order produces.
fn stages(written: &[ShotOrder]) -> Vec<Document> {
  joins(&ADDRESS, &terms(written), &subjects(written))
    .expect("this nesting is inside the ceiling")
    .into_stages()
}

/// **ONE HOP, verbatim.** `$lookup` in the concise form, `$first` because a forward reference is
/// to-one, and the join array dropped the moment its value has been taken off it.
///
/// The `as` field wears the reserved namespace and the (level, hop) pair; the materialized field
/// wears the term's position in the completed order, so a reader can see which term each stage is
/// for without counting stages.
#[test]
fn one_hop_is_a_lookup_an_add_fields_and_a_project() {
  assert_eq!(
    stages(&by_cover_title()),
    [
      doc! { "$lookup": {
        "from": "keyframe",
        "localField": "cover_id",
        "foreignField": "_id",
        "as": "__ig_keyframe_1__",
      } },
      doc! { "$addFields": { "__ig_ord0__": { "$first": "$__ig_keyframe_1__.title" } } },
      doc! { "$project": { "__ig_keyframe_1__": 0 } },
    ]
  );
}

/// **TWO HOPS, verbatim.** The chain, and the one line that makes it a chain: the second
/// `localField` reaches THROUGH the first hop's array, which `$lookup` matches element by element.
///
/// No sub-pipeline and no intermediate field: a dotted `localField` over an array is what the
/// concise form already does, and the array holds at most one element because the hop before it was
/// to-one as well.
#[test]
fn two_hops_chain_the_second_lookup_through_the_firsts_array() {
  assert_eq!(
    stages(&by_cover_strip_label()),
    [
      doc! { "$lookup": {
        "from": "keyframe",
        "localField": "cover_id",
        "foreignField": "_id",
        "as": "__ig_keyframe_1__",
      } },
      doc! { "$lookup": {
        "from": "strip",
        "localField": "__ig_keyframe_1__.strip_id",
        "foreignField": "_id",
        "as": "__ig_strip_2__",
      } },
      doc! { "$addFields": { "__ig_ord0__": { "$first": "$__ig_strip_2__.label" } } },
      doc! { "$project": { "__ig_keyframe_1__": 0, "__ig_strip_2__": 0 } },
    ]
  );
}

/// A FLAT order adds nothing at all, which is what keeps the ordinary pipeline the one it always
/// was: three stages nobody asked for would be three the planner has to walk past.
#[test]
fn a_flat_order_adds_no_stages() {
  assert!(stages(&[ShotOrder::Title(OrderDirection::Asc)]).is_empty());
}

/// **The MIXED order**, which is the one a nested term actually produces: some levels are fields
/// and some are not, and the subjects party answers for its own while the rest sort by their own
/// key.
///
/// The alias carries the TERM's position and not a count of the nested ones, which is what keeps the
/// `$addFields`, the `$sort` and the decode reading one index: the nested term is second here, so it
/// is `__ig_ord1__` and there is no `__ig_ord0__` in the pipeline at all.
#[test]
fn a_mixed_order_aliases_by_position_and_leaves_its_plain_levels_alone() {
  let written = [
    ShotOrder::Title(OrderDirection::Asc),
    ShotOrder::Cover(Arc::new(KeyframeOrder::Title(OrderDirection::Asc))),
  ];
  let terms = terms(&written);
  let subjects = subjects(&written);

  assert_eq!(
    stages(&written),
    [
      doc! { "$lookup": {
        "from": "keyframe",
        "localField": "cover_id",
        "foreignField": "_id",
        "as": "__ig_keyframe_1__",
      } },
      doc! { "$addFields": { "__ig_ord1__": { "$first": "$__ig_keyframe_1__.title" } } },
      doc! { "$project": { "__ig_keyframe_1__": 0 } },
    ]
  );
  assert_eq!(sort_key(&ADDRESS, &terms, 0, &subjects), "title");
  assert_eq!(sort_key(&ADDRESS, &terms, 1, &subjects), "__ig_ord1__");
  assert_eq!(sort_key(&ADDRESS, &terms, 2, &subjects), "_id");
}

/// **Two terms reaching one collection mint ONE name and are still two joins**, and consuming the
/// field per level is the whole of why that is safe.
///
/// A pipeline has no scopes — every `$lookup` writes into the same document — so `cover.title` and
/// `cover.strip.label` both take `keyframe`'s join field at depth one. Held open, the second
/// `$lookup` would overwrite the first and `__ig_ord0__` would be computed from the wrong array,
/// with no error anywhere. Each run drops its own fields before the next opens, which is the RELATION
/// family's arrangement verbatim and buys the same thing.
#[test]
fn two_terms_reaching_one_collection_share_a_name_and_consume_it() {
  let written = [
    ShotOrder::Cover(Arc::new(KeyframeOrder::Title(OrderDirection::Asc))),
    ShotOrder::Cover(Arc::new(KeyframeOrder::Strip(Arc::new(StripOrder::Label(
      OrderDirection::Asc,
    ))))),
  ];

  assert_eq!(
    stages(&written),
    [
      doc! { "$lookup": {
        "from": "keyframe",
        "localField": "cover_id",
        "foreignField": "_id",
        "as": "__ig_keyframe_1__",
      } },
      doc! { "$addFields": { "__ig_ord0__": { "$first": "$__ig_keyframe_1__.title" } } },
      doc! { "$project": { "__ig_keyframe_1__": 0 } },
      doc! { "$lookup": {
        "from": "keyframe",
        "localField": "cover_id",
        "foreignField": "_id",
        "as": "__ig_keyframe_1__",
      } },
      doc! { "$lookup": {
        "from": "strip",
        "localField": "__ig_keyframe_1__.strip_id",
        "foreignField": "_id",
        "as": "__ig_strip_2__",
      } },
      doc! { "$addFields": { "__ig_ord1__": { "$first": "$__ig_strip_2__.label" } } },
      doc! { "$project": { "__ig_keyframe_1__": 0, "__ig_strip_2__": 0 } },
    ]
  );
}

/// The materialized field is the ENGINE's name, handed to the decode rather than rebuilt — so both
/// ends of the pair spell one index the same way, including past nine.
#[test]
fn the_sort_alias_carries_the_terms_position() {
  assert_eq!(sort_alias(0), "__ig_ord0__");
  assert_eq!(sort_alias(12), "__ig_ord12__");
}

/// **THE INJECTIVITY LAW, mechanised.** A minted WORD's body — what sits between `__ig_` and the
/// closing `__` — carries no `_`, and a JOIN FRAME's body always splits at one into a name and a run
/// of digits. So no join this framework can open, over any collection at any depth, spells a sort
/// field.
///
/// The digits are what make this worth asserting rather than reading: `__ig_ord_0__` would be the
/// join a collection called `ord` opens at depth zero, and one underscore is the whole difference.
#[test]
fn a_minted_word_can_be_no_instance_of_the_join_frame() {
  for level in [0, 1, 9, 10, 512] {
    let alias = sort_alias(level);
    let body = alias
      .strip_prefix("__ig_")
      .and_then(|body| body.strip_suffix("__"))
      .expect("a minted word wears the prefix and the terminator");

    assert!(
      !body.contains('_'),
      "`{alias}` has a body a `<name>_<depth>` split could reach"
    );
  }
}

/// A field spelled `__ord` and a digit is a column a declaration may legitimately own, and the
/// pipeline no longer touches one — which is the whole of what moving the name into the reserved
/// namespace bought.
///
/// Asserted over the RENDERED stages rather than over the constant, because what a declaration cares
/// about is whether anything writes its key.
#[test]
fn a_user_column_spelled_the_old_way_is_never_written() {
  let rendered = format!("{:?}", stages(&by_cover_title()));

  assert!(
    !rendered.contains("__ord_"),
    "the mint no longer claims a name outside the fence: {rendered}"
  );
}

/// A term that sorts by a field of the document itself takes its own key, and the id takes `_id` —
/// which is [`field_key`](crate::comparison::mongo::field_key)'s mapping reaching the ordering
/// through the one authority the keyset reads too.
#[test]
fn a_plain_term_sorts_by_its_own_key() {
  let terms = terms(&[ShotOrder::Score(OrderDirection::Desc)]);

  assert_eq!(sort_key(&ADDRESS, &terms, 0, &MongoFields), "score");
  assert_eq!(sort_key(&ADDRESS, &terms, 1, &MongoFields), "_id");
}

/// **The CEILING.** Past the last join field the target's expansion minted, the hop refuses — and
/// the refusal is the RELATION family's own, naming the same collection with the same two numbers a
/// relation nested that deep would get.
///
/// A ninth field nothing reserved is the alternative, and it is silent twice over: the name would
/// be one the mint never wrote, and a repeat inside one run would have the second `$lookup`
/// overwrite the first.
#[test]
fn a_nesting_past_the_ceiling_is_refused_by_name() {
  let terms = terms(&by_cover_title());
  let refused = joins(&ADDRESS, &terms, &DeepSubjects::crossing(DEPTH_CEILING))
    .err()
    .expect("the eighth hop has no name left");

  assert!(matches!(
    refused,
    MongoLoweringError::RelationDepth(depth)
      if depth.table() == FieldName::new("shot")
        && depth.depth() == DEPTH_CEILING
        && depth.ceiling() == DEPTH_CEILING
  ));
}

/// A nesting at the LAST name minted still renders, so the ceiling is read off the alias table
/// rather than written here — `[0]` is never worn, which is what makes the usable depth one below
/// the table's length in both families.
#[test]
fn a_nesting_at_the_last_minted_name_still_renders() {
  let terms = terms(&by_cover_title());
  let stages = joins(&ADDRESS, &terms, &DeepSubjects::crossing(DEPTH_CEILING - 1))
    .expect("seven hops have seven names")
    .into_stages();

  assert_eq!(
    stages.len(),
    DEPTH_CEILING + 1,
    "one per hop, plus the two the run finishes with"
  );
}

/// The subjects a document states are the ones the engine reads: `ShotSubjects` answers for the
/// nested level and defers the rest, which is what a generated provider does.
#[test]
fn a_documents_own_subjects_answer_for_its_nested_levels() {
  let written = by_cover_title();
  let terms = terms(&written);
  let subjects =
    <ShotMongo as MongoOrdering>::subjects(&<ShotMongo as MongoOrdering>::complete(&written));

  assert!(subjects.nesting(&terms, 0).is_some());
  assert!(subjects.nesting(&terms, 1).is_none());
}