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
//! What the two states render, and the corpus every rendering here was measured against.
//!
//! # The corpus
//!
//! Nine documents on MongoDB 8.2.12, `{_id, v}`, chosen so that every way a field can fail to be a
//! plain value is present at once:
//!
//! | `_id` | `v` |
//! |---|---|
//! | 1 | `5` |
//! | 2 | `null` |
//! | 3 | *(no `v` at all)* |
//! | 4 | `[]` |
//! | 5 | `[1, 2]` |
//! | 6 | `[null]` |
//! | 7 | `[1, null, 3]` |
//! | 8 | `"text"` |
//! | 9 | `{a: 1}` |
//!
//! Loading it is three lines of `mongosh`, and the tables below are what it answered:
//!
//! ```text
//! db.corpus.insertMany([
//!   {_id: 1, v: 5}, {_id: 2, v: null}, {_id: 3}, {_id: 4, v: []}, {_id: 5, v: [1, 2]},
//!   {_id: 6, v: [null]}, {_id: 7, v: [1, null, 3]}, {_id: 8, v: "text"}, {_id: 9, v: {a: 1}},
//! ])
//! ```
//!
//! Documents 6 and 7 are the array-member reading [`MongoNullable`] records: their cells hold
//! values, and a field operator applies to an array's members as well as to the array.
//!
//! # The corpus is what chose the keys, so the tests read it rather than restate it
//!
//! The two measured tables below are the whole argument for `$eq`/`$ne` over the spellings that
//! also exist, and the tests LOOK THE RENDERED KEY UP in them rather than asserting a literal
//! beside a comment. A rendering changed to another spelling therefore fails on the corpus fact
//! that spelling gets wrong — the missing document, or the explicit null — rather than on a
//! string mismatch that says nothing about why.

use bson::{Bson, Document, doc};

use super::MongoNullable;
use crate::{
  At, ComplexComparison, FieldName, ListFilter, Mongo, Nullable, RecordAddress, ScalarFilter,
  SetFilter, ToDatabaseComparison, TryFromFilter,
  comparison::mongo::{
    MongoConjunction, MongoListComparison, MongoScalarComparison, MongoSetComparison,
  },
};

/// The row every address below names. Nothing here is correlated, so no test reads it.
const ROW: RecordAddress = RecordAddress::new(FieldName::new("media"), &[FieldName::new("id")]);

/// The document with no `v` at all, which MongoDB's convention reads as null.
const MISSING: i32 = 3;

/// The document whose `v` was written as an explicit null.
const EXPLICIT_NULL: i32 = 2;

/// Every document in the corpus.
const ALL: [i32; 9] = [1, 2, 3, 4, 5, 6, 7, 8, 9];

/// Each spelling of *this field is null* that was measured, and the documents it returned.
///
/// The three differ by exactly the state this crate does not treat as its own: `$eq` answers for
/// the MISSING field and the other two do not agree about it. That is why the row this crate writes
/// is the first — MongoDB reads a missing field as null, and `$eq` is the spelling that follows the
/// server's own reading.
fn measured_null_tests() -> Vec<(Document, Vec<i32>)> {
  vec![
    (doc! { "$eq": Bson::Null }, vec![2, 3, 6, 7]),
    (doc! { "$type": "null" }, vec![2, 6, 7]),
    (doc! { "$exists": false }, vec![3]),
  ]
}

/// Each spelling of *this field holds a value* that was measured, and the documents it returned.
///
/// The first and the third are the SAME five documents, which is what makes the `$exists` redundant
/// rather than load-bearing; the second is what a presence test alone would answer, and it keeps the
/// explicit null.
fn measured_value_tests() -> Vec<(Document, Vec<i32>)> {
  vec![
    (doc! { "$ne": Bson::Null }, vec![1, 4, 5, 8, 9]),
    (
      doc! { "$exists": true, "$ne": Bson::Null },
      vec![1, 4, 5, 8, 9],
    ),
    (doc! { "$exists": true }, vec![1, 2, 4, 5, 6, 7, 8, 9]),
  ]
}

/// Lower one comparison at one column of [`ROW`] and finish the filter.
fn rendered<C: ComplexComparison<Mongo>>(comparison: &C, column: &str) -> Document {
  let frame = At::new(&ROW).frame(FieldName::new(column));
  comparison
    .apply(frame.at(), MongoConjunction::new())
    .expect("this lowering cannot refuse")
    .into_document()
}

/// The wrapper over a scalar, with the null test set as given.
fn scalar(null: Option<bool>) -> MongoNullable<MongoScalarComparison<i64>> {
  let filter = Nullable::new(ScalarFilter::<i64>::new()).maybe_null(null);
  MongoNullable::try_from_filter(filter).expect("the identity crossing cannot fail")
}

/// The operator document a lone null test writes at `v`, which is what the measured tables are keyed
/// by.
fn null_test_key(null: bool) -> Document {
  rendered(&scalar(Some(null)), "v")
    .get_document("v")
    .expect("the null test writes one field key")
    .clone()
}

/// The documents `key` was measured to return, or a failure naming the spelling that has no row.
fn measured(table: Vec<(Document, Vec<i32>)>, key: &Document) -> Vec<i32> {
  table
    .into_iter()
    .find(|(candidate, _)| candidate == key)
    .unwrap_or_else(|| panic!("no measurement for the rendered key {key:?}"))
    .1
}

/// Each state is ONE key, and each is MongoDB's own spelling of the question — no `$type` and no
/// `$exists`, because the convention this wrapper follows is the server's.
#[test]
fn the_two_states_render_the_two_native_keys() {
  assert_eq!(
    rendered(&scalar(Some(true)), "v"),
    doc! { "v": { "$eq": Bson::Null } }
  );
  assert_eq!(
    rendered(&scalar(Some(false)), "v"),
    doc! { "v": { "$ne": Bson::Null } }
  );
}

/// **The convention, as the corpus states it.** A missing field reads as null, so the null test has
/// to answer for the document that has no `v` at all — and `$eq` is the spelling that does.
///
/// `$type: "null"` is the spelling that does not, and it is the one this test refuses: it is the
/// narrower question *the field is there and is null*, which is a distinction MongoDB's own query
/// vocabulary does not draw and this layer therefore does not either.
#[test]
fn the_null_test_answers_for_the_missing_field() {
  let matched = measured(measured_null_tests(), &null_test_key(true));

  assert!(
    matched.contains(&MISSING),
    "a missing field reads as null, so document {MISSING} answers the null test"
  );
  assert!(
    matched.contains(&EXPLICIT_NULL),
    "an explicit null answers it too"
  );
}

/// The value test excludes BOTH states the null test holds, which is what makes the two a partition
/// rather than a pair of overlapping questions.
///
/// A bare presence test is the mutation it refuses: `$exists: true` keeps the explicit null, so a
/// column asked for a value would answer with cells that have none.
#[test]
fn the_value_test_excludes_the_null_and_the_missing_field() {
  let matched = measured(measured_value_tests(), &null_test_key(false));

  assert!(
    !matched.contains(&EXPLICIT_NULL),
    "document {EXPLICIT_NULL} holds an explicit null and is not a value"
  );
  assert!(
    !matched.contains(&MISSING),
    "document {MISSING} has no field and is not a value"
  );
}

/// The `$exists` beside `$ne` is REDUNDANT, measured rather than reasoned: the two return the same
/// five documents, so writing it would add a key and no question.
#[test]
fn the_presence_test_beside_the_value_test_adds_nothing() {
  let table = measured_value_tests();
  let bare = measured(table.clone(), &doc! { "$ne": Bson::Null });
  let guarded = measured(table, &doc! { "$exists": true, "$ne": Bson::Null });

  assert_eq!(bare, guarded);
}

/// **The two-cell partition.** Every document in the corpus answers exactly one of the two states —
/// their union is all nine and their intersection is empty — which is the property a two-valued
/// question is supposed to have.
#[test]
fn the_two_states_partition_the_corpus() {
  let null = measured(measured_null_tests(), &null_test_key(true));
  let value = measured(measured_value_tests(), &null_test_key(false));

  let mut union = [null.clone(), value.clone()].concat();
  union.sort_unstable();
  assert_eq!(union, ALL);

  assert!(
    !null.iter().any(|id| value.contains(id)),
    "no document is in both cells"
  );
}

/// An unset null test renders nothing at all, and the wrapper is then exactly its inner.
#[test]
fn an_unset_null_test_renders_nothing() {
  assert_eq!(rendered(&scalar(None), "v"), Document::new());
  assert_eq!(scalar(None).conjuncts(), 0);
  assert!(ComplexComparison::<Mongo>::is_empty(&scalar(None)));

  // Set but empty inside is still one conjunct: the question was asked.
  assert_eq!(scalar(Some(true)).conjuncts(), 1);
  assert!(!ComplexComparison::<Mongo>::is_empty(&scalar(Some(true))));
}

/// The inner comparison's keys and the null test's land in ONE operator document, because that is
/// what a BSON field's key holds — the same merge two operators of one kind go through.
#[test]
fn the_null_test_merges_into_the_fields_own_operator_document() {
  let filter =
    Nullable::new(ScalarFilter::<i64>::new().with_gt(1i64).with_lt(5i64)).with_null(false);
  let comparison = MongoNullable::<MongoScalarComparison<i64>>::try_from_filter(filter)
    .expect("the identity crossing cannot fail");

  assert_eq!(comparison.conjuncts(), 3);
  assert_eq!(
    rendered(&comparison, "v"),
    doc! { "v": { "$gt": 1_i64, "$lt": 5_i64, "$ne": Bson::Null } }
  );
}

/// `$ne` is shared with the scalar kind's own `ne`, so a comparison asking both writes one key
/// twice — and the accumulator folds the second into a top-level `$and` rather than over the first.
///
/// The corpus separates the fold from both ways of losing a key. Measured: the pair below returns
/// **4, 5, 8, 9**; keeping only `{$ne: 5}` returns 2, 3, 4, 5, 6, 7, 8, 9 and keeping only
/// `{$ne: null}` returns 1, 4, 5, 8, 9. The intersection is what the two slots each asked for, and
/// it is neither of the other two.
#[test]
fn a_shared_key_folds_rather_than_overwriting() {
  let filter = Nullable::new(ScalarFilter::<i64>::new().with_ne(5i64)).with_null(false);
  let comparison = MongoNullable::<MongoScalarComparison<i64>>::try_from_filter(filter)
    .expect("the identity crossing cannot fail");

  assert_eq!(
    rendered(&comparison, "v"),
    doc! {
      "v": { "$ne": 5_i64 },
      "$and": [ { "v": { "$ne": Bson::Null } } ],
    }
  );
}

/// The same fold against a COLLECTION's key: a list's `has_element` is written as `$eq` — MongoDB's
/// member-wise equality — so a nullable list asked whether its cell is null writes `$eq` twice.
///
/// Measured on the corpus, and this is the sharpest of the three separations: the pair below returns
/// document **7 alone**, where keeping only `{$eq: 1}` returns 5 and 7 and keeping only
/// `{$eq: null}` returns 2, 3, 6 and 7. One document, two documents, four documents — a fold that
/// collapsed either way would be visible immediately.
#[test]
fn a_collections_own_key_folds_with_the_null_test() {
  let filter = Nullable::new(ListFilter::<i64>::new().with_has_element(1i64)).with_null(true);
  let comparison =
    MongoNullable::<MongoListComparison<i64, MongoScalarComparison<i64>>>::try_from_filter(filter)
      .expect("the identity crossing cannot fail");

  assert_eq!(
    rendered(&comparison, "v"),
    doc! {
      "v": { "$eq": 1_i64 },
      "$and": [ { "v": { "$eq": Bson::Null } } ],
    }
  );
}

/// The null test and NON-EMPTINESS are two questions and two keys, and they compose in one operator
/// document rather than colliding.
///
/// `$exists` is written INSIDE `$elemMatch` by the collection kinds — the tautology over members
/// that makes an empty element scope mean *this collection has a member* — and never at the field by
/// this wrapper, which writes no `$exists` at all. Different documents, so the merge has nothing to
/// fold. Measured, the filter below returns document 5 alone: the one non-empty array whose members
/// are all values.
#[test]
fn the_null_test_composes_with_the_collections_member_tautology() {
  let filter =
    Nullable::new(ListFilter::<i64>::new().with_any(ScalarFilter::new())).with_null(false);
  let comparison =
    MongoNullable::<MongoListComparison<i64, MongoScalarComparison<i64>>>::try_from_filter(filter)
      .expect("the identity crossing cannot fail");

  assert_eq!(
    rendered(&comparison, "v"),
    doc! {
      "v": {
        "$elemMatch": { "$exists": true },
        "$ne": Bson::Null,
      },
    }
  );
}

/// The set kind's array guard is `$type`, which this wrapper no longer shares with anything, so a
/// nullable set's two questions merge into one operator document with no overflow at all.
///
/// Measured, the filter below returns document 4 — the empty array, which is the only cell that is a
/// subset of `[1]` — and the null test neither adds nor removes a document there, since an empty
/// array is a value.
#[test]
fn the_set_guard_and_the_null_test_are_separate_keys() {
  let filter = Nullable::new(SetFilter::<i64>::new().with_enclosed_by([1i64])).with_null(false);
  let comparison =
    MongoNullable::<MongoSetComparison<i64, MongoScalarComparison<i64>>>::try_from_filter(filter)
      .expect("the identity crossing cannot fail");

  assert_eq!(
    rendered(&comparison, "v"),
    doc! {
      "v": {
        "$type": "array",
        "$not": { "$elemMatch": { "$nin": [1_i64] } },
        "$ne": Bson::Null,
      },
    }
  );
}

/// A nullable column's operands are the column's storage type with the `Option` taken off, which is
/// what makes `eq: Some(None)` a type that does not exist rather than a second spelling of the null
/// test.
#[test]
fn the_column_option_lands_on_the_wrapper_and_not_on_the_operands() {
  use core::marker::PhantomData;

  fn same<A>(_: PhantomData<A>, _: PhantomData<A>) {}

  same(
    PhantomData::<
      <Nullable<ScalarFilter<i64>> as ToDatabaseComparison<Option<i64>, Mongo>>::Comparison,
    >,
    PhantomData::<MongoNullable<MongoScalarComparison<i64>>>,
  );
}

/// The default is the empty inner comparison with the question unasked, which is what a builder
/// assembling a where struct column by column starts from.
#[test]
fn the_default_is_the_empty_inner_with_no_null_test() {
  let empty = MongoNullable::<MongoScalarComparison<i64>>::default();

  assert_eq!(empty.null(), None);
  assert!(empty.inner().is_empty());
  assert_eq!(empty, MongoNullable::new(MongoScalarComparison::new()));
}

/// Nesting composes with no layer knowing its depth: the inner wrapper's key and the outer's land in
/// the same operator document, and each writes the state it was asked about.
///
/// The two states are contradictory, and the rendering says so rather than collapsing: measured,
/// `{v: {$eq: null, $ne: null}}` returns no document.
#[test]
fn nesting_composes_and_each_layer_writes_its_own_state() {
  let filter =
    Nullable::new(Nullable::new(ScalarFilter::<i64>::new()).with_null(true)).with_null(false);
  let comparison =
    MongoNullable::<MongoNullable<MongoScalarComparison<i64>>>::try_from_filter(filter)
      .expect("the identity crossing cannot fail");

  assert_eq!(comparison.conjuncts(), 2);
  assert_eq!(
    rendered(&comparison, "v"),
    doc! { "v": { "$eq": Bson::Null, "$ne": Bson::Null } }
  );
}