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 generated document's serde road, routed through this crate's OWN two document tables.
//!
//! # What it replaces, and why the replacement is not a preference
//!
//! An emitted `<Record>Mongo` derives serde's pair, and a derive demands `Serialize` and
//! `Deserialize` OF EVERY DECLARED FIELD TYPE — two foreign traits asked for by generated code an
//! author cannot edit. `regex::Regex` carries neither and cannot be given either here (both the type
//! and the traits are foreign, so the impl is `E0117` in this crate and in every other but `regex`'s
//! and serde's), so a pattern column made the document fail to compile inside its own expansion.
//!
//! What a document row actually needs is not serde's opinion of a value but this crate's, and that
//! opinion already exists, per type, in two tables: [`MongoCarrier`] says what a storage type is
//! WRITTEN as and [`MongoExtract`] says what it is READ out of, and `tests` round-trips every row
//! through both. The framework's own write and read have gone through them since the extraction
//! landed — [`MongoWrite::document`](super::MongoWrite::document) is one
//! [`to_bson`](MongoCarrier::to_bson) per field and
//! [`from_document`](super::MongoQuery::from_document) is one [`field`](super::field) per field —
//! leaving the derive as the ONLY party still asking for serde.
//!
//! So the emission stops asking. Every field of a document carries
//! `#[serde(with = "…::query::mongo::via")]`, this module's two functions answer through the two
//! tables, and the derive's obligation on a field type becomes `MongoCarrier + MongoExtract` — which
//! that field type already owed, both halves, before this module existed. **Nothing new is demanded
//! of any type**, and the door the carrier module recorded — *removing it would widen what a mongo
//! row may hold to exactly what those tables cover, and that is the emitter's change rather than
//! this file's* — is the door this is.
//!
//! # It is the same shape [`field`](super::field) already has
//!
//! One free function generic over the field's own type, resolved by the compiler at the field, with
//! the per-type answer living in a trait row. The emission writes ONE spelling for every column and
//! reads no type's name — which is the standing rule for this emitter, and which a per-type `with`
//! path chosen by matching `Regex` in the tokens would have been the second-ever breach of.
//!
//! # What CHANGES for a type that had a serde row
//!
//! Its BSON. A field now serialises as the [`Bson`] its carrier writes rather than as whatever
//! serde's own impl said, which is the point: the derived pair and the framework's own write can no
//! longer disagree about a document, and a fixture written through `bson::to_document` is the
//! document an `insert` would have stored. Every type whose carrier arm IS its serde form — every
//! integer, `bool`, `f64`, `String` — is unmoved.
//!
//! # The read here is NOT the framework's read lane, and the error is why
//!
//! [`from_document`](super::MongoQuery::from_document) stays exactly as it was, and stays the lane
//! a query answers through, for the reason it was emitted in the first place:
//! [`serde::de::Error::custom`] takes a `Display` and hands back the FORMAT's error, so a declared
//! refusal reaching a caller through serde would arrive as a `bson::de::Error` carrying a string and
//! a `mongo(try_into(error = "…"))` cell would hold nothing. What the derived `Deserialize` is for
//! is everything that is not that lane — a fixture written as extended JSON, a `bson::from_document`
//! in a consumer's own migration, a test that round-trips a document — and for those the refusal
//! this module hands to `custom` is [`MongoTypeError`]'s own sentence, which names the situation
//! rather than merely failing.
//!
//! [`MongoCarrier`]: crate::MongoCarrier

use bson::Bson;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

use super::MongoExtract;
use crate::MongoCarrier;

/// One field of a document, written as the [`Bson`] this crate stores it as.
///
/// # Errors
///
/// The serializer's own, from writing a [`Bson`]. The crossing to BSON cannot fail —
/// [`to_bson`](MongoCarrier::to_bson) takes no `Result`, for the reason
/// [`SqlWrite::bind`](crate::query::sql::SqlWrite::bind) takes none: what it walks is storage values
/// a carrier row exists for, every declared conversion having been spent before the row was built.
pub fn serialize<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
where
  T: MongoCarrier,
  S: Serializer,
{
  value.to_bson().serialize(serializer)
}

/// One field of a document, read back through the row that says what this crate stores it as.
///
/// The two-state reading is [`MongoExtract`]'s and is unchanged here: a field the deserializer hands
/// back as [`Bson::Null`] reaches [`extract`](MongoExtract::extract) as `Some(&Bson::Null)`, which
/// an `Option<T>` row answers with [`None`] and every other row refuses by name.
///
/// # Errors
///
/// The deserializer's own, carrying [`MongoTypeError`]'s sentence — what the field held, and why
/// this type could not take it. The TYPE is lost across `custom`, which is exactly why the framework
/// reads a queried document through [`from_document`](super::MongoQuery::from_document) instead; see
/// the module note.
pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
where
  T: MongoExtract,
  D: Deserializer<'de>,
{
  let held = Bson::deserialize(deserializer)?;
  T::extract(Some(&held)).map_err(<D::Error as serde::de::Error>::custom)
}

#[cfg(test)]
mod tests;