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
use std::sync::Arc;

use super::{BeI128, BeU64, BeU128, Embedding};

/// The crossing into a blob carrier is total: every value of the width has a blob, so a field that
/// declares one needs no converter and cannot be refused.
#[test]
fn every_value_of_the_width_crosses() {
  assert_eq!(BeU64::from(u64::MAX), BeU64(u64::MAX));
  assert_eq!(u64::from(BeU64(7)), 7);
  assert_eq!(BeU128::from(u128::MAX), BeU128(u128::MAX));
  assert_eq!(BeI128::from(i128::MIN), BeI128(i128::MIN));
  assert_eq!(i128::from(BeI128(-1)), -1);
}

/// The carriers order as their inner values do, which is what makes an index over one of them
/// answer `<` and `>` — the blob's bytewise order and this `Ord` are the same relation.
#[test]
fn a_carrier_orders_as_its_value_does() {
  assert!(BeU64(1) < BeU64(256));
  assert!(BeI128(i128::MIN) < BeI128(0));
  assert!(BeU128(0) < BeU128(u128::MAX));
}

/// The codec is a round trip in both directions, which is what makes it an encoding this crate owns
/// rather than a bind helper: a carrier that could only write would leave the reading to whoever
/// happened to need it.
#[test]
fn a_blob_round_trips() {
  for v in [0u64, 1, u64::MAX, 0x0123_4567_89ab_cdef] {
    assert_eq!(BeU64::from_blob(&BeU64(v).to_blob()), Some(BeU64(v)));
  }
  for v in [0u128, 1, u128::MAX] {
    assert_eq!(BeU128::from_blob(&BeU128(v).to_blob()), Some(BeU128(v)));
  }
  for v in [0i128, 1, -1, i128::MIN, i128::MAX] {
    assert_eq!(BeI128::from_blob(&BeI128(v).to_blob()), Some(BeI128(v)));
  }
}

/// A column holds whatever width was written into it, so the width is checked rather than assumed.
#[test]
fn a_wrong_width_decodes_to_none() {
  assert_eq!(BeU64::from_blob(&[0; 7]), None);
  assert_eq!(BeU128::from_blob(&[0; 8]), None);
  assert_eq!(BeI128::from_blob(&[]), None);
}

/// The whole reason the blobs are big-endian: bytewise order IS numeric order, so a `BLOB` index
/// answers `<` and `>` without decoding. A little-endian encoding would order `1` above `256`.
#[test]
fn byte_order_is_numeric_order() {
  assert!(BeU64(1).to_blob() < BeU64(256).to_blob());
  assert!(BeU128(1).to_blob() < BeU128(256).to_blob());
}

/// The sign flip is what makes it hold across zero: without it `-1` is `0xff…` and would sort ABOVE
/// every positive value.
#[test]
fn the_sign_flip_puts_negatives_below_positives() {
  assert!(BeI128(i128::MIN).to_blob() < BeI128(-1).to_blob());
  assert!(BeI128(-1).to_blob() < BeI128(0).to_blob());
  assert!(BeI128(0).to_blob() < BeI128(1).to_blob());
  assert!(BeI128(1).to_blob() < BeI128(i128::MAX).to_blob());
}

/// The transparent wrapping is zero-copy at the SLICE level, which is the whole reason for
/// `repr(transparent)` — and no `unsafe` is written for it here, because the derive owns the
/// argument.
///
/// It rides `sqlx` because the derive does: the peel exists for a Postgres slice bind, and a build
/// without that family has neither the dependency nor a position to use it in.
#[cfg(feature = "sqlx")]
#[test]
fn a_slice_wraps_and_peels_without_copying() {
  use bytemuck::TransparentWrapper;

  let values = [1u64, 2, 3];
  let wrapped: &[BeU64] = BeU64::wrap_slice(&values);
  assert_eq!(wrapped, [BeU64(1), BeU64(2), BeU64(3)]);
  assert_eq!(wrapped.as_ptr().cast::<u64>(), values.as_ptr());
  assert_eq!(BeU64::peel_slice(wrapped), &values);
}

/// The width is the TYPE's, so it reads back with no value in hand — which is the whole of what
/// moving it out of the wiring means, and the element takes no part in it.
#[test]
fn the_width_reads_off_the_type() {
  assert_eq!(Embedding::<f32, 1>::DIM, 1);
  assert_eq!(Embedding::<f32, 768>::DIM, 768);
  assert_eq!(Embedding::<f64, 1152>::DIM, 1152);
  assert_eq!(Embedding::<u8, 4>::DIM, 4);
}

/// The one runtime check the type keeps, and why it is only one: a slice carries its length and the
/// type carries the width, so the two meet once — at construction — and agree at every reader past
/// it. The buffer crosses that boundary WITHOUT a copy, which is what the shared-slice carrier is
/// for.
#[test]
fn a_slice_of_another_length_is_not_this_embedding() {
  let coordinates: Arc<[f32]> = Arc::from(vec![0.5; 768]);
  let embedding = Embedding::<f32, 768>::new(Arc::clone(&coordinates)).unwrap();

  assert_eq!(embedding.coordinates(), &coordinates[..]);
  assert_eq!(embedding.coordinates().as_ptr(), coordinates.as_ptr());

  assert!(Embedding::<f32, 1152>::new(coordinates).is_none());
}

/// Cloning is the carrier's — a refcount bump over the same coordinates — at an element type that
/// cannot be cloned itself. That is what the hand-written `Clone` buys over the derived one, whose
/// `E: Clone` bound this element does not satisfy.
#[test]
fn cloning_shares_the_coordinates() {
  struct Opaque;

  let embedding = Embedding::<Opaque, 2>::new(Arc::from(vec![Opaque, Opaque])).unwrap();
  let shared = embedding.clone();

  assert_eq!(
    embedding.coordinates().as_ptr(),
    shared.coordinates().as_ptr()
  );
}

/// A temporal field reaches its storage form with NO backend family in the build, which is the half
/// of the split this module exists for. Nothing here names a comparison, and that is the assertion:
/// the SQL family's own tests reach `Temporal` through `SqlScalarComparison` and so cannot say
/// whether the wrapper needed it.
///
/// The lane carries the meaning rather than a `cfg` — `ci/test-matrix.sh` runs this file under
/// `--features jiff,time`, where a wrapper that had dragged `sqlx` behind it would not compile at
/// all.
#[cfg(all(feature = "jiff", feature = "time"))]
#[test]
fn a_temporal_field_names_its_storage_form_without_a_backend() {
  use jiff::civil;

  use crate::Temporal;

  let at: jiff::Timestamp = "2024-05-06T07:08:09.123456789Z".parse().unwrap();
  let instant: Temporal<time::OffsetDateTime> = at.into();
  assert_eq!(instant.get().unix_timestamp_nanos(), at.as_nanosecond());

  let zoned: Temporal<time::OffsetDateTime> = at.to_zoned(jiff::tz::TimeZone::UTC).into();
  assert_eq!(zoned, instant);

  let date: Temporal<time::Date> = civil::date(2024, 5, 6).into();
  assert_eq!(date.get().year(), 2024);

  let time: Temporal<time::Time> = civil::Time::new(7, 8, 9, 123_456_789).unwrap().into();
  assert_eq!(time.get().nanosecond(), 123_456_789);
}