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 CARRIER crossing: reading a filter's operands off the wire, and writing them back, where the
//! operand crosses as a local newtype rather than as its own Rust type.
//!
//! Three families of four, one function per slot shape and direction in each, and every one of them
//! is what [`DurationFilter`](crate::DurationFilter)'s hand-written face already does inline — that
//! face was the first crossing of this kind and it wrote its own
//! `read`/`read_list`/`write`/`write_list` because it was the only one. It is no longer.
//!
//! The three differ in WHO NAMES THE CROSSING, and that is the whole of the difference:
//!
//! - [`read`] and its three siblings take the carrier as a TYPE PARAMETER and cross through
//!   `Into`/`From`. They serve [`via_filter_input_object!`](crate::via_filter_input_object), which
//!   expands into a concrete face that knows its own carrier and can spell it.
//! - [`crossed`] and its three siblings take the crossing as a FUNCTION. They serve the faces
//!   written over a READING — the text, scalar and byte kinds — where the carrier is `I::Carrier`
//!   and the conversion is `I::cross`, so a caller supplies the pair rather than naming a type the
//!   reading has not fixed yet.
//! - [`cross`] and its three siblings ask the OPERAND instead, through
//!   [`ToGraphqlInput`](crate::ToGraphqlInput). They serve the collection faces, which do not know
//!   their element.
//!
//! The middle family is written once for the three readings rather than three times: the crossing's
//! own promises — a slot's refusal re-pointed at the face being parsed, the FIRST refusal winning in
//! a list, a render that clones rather than consuming — are one implementation, so the three kinds
//! cannot come to answer them differently.
//!
//! Two reasons bring an operand onto a carrier at all, and only the first is a wall. `u128` and
//! `i128` have no `InputType` in any crate but async-graphql's, so a carrier is the only road; the
//! other ten numerics HAD a face and it did not name their width, which is a choice about what a
//! schema says rather than about what compiles — see [`scalar`](super::super::scalar).
//!
//! The domain value never leaves the filter. A slot holds `u128`; the wire holds
//! [`U128`](crate::U128); these are the two lines where one becomes the other.

use core::fmt::Display;

use async_graphql::{InputType, InputValueError, Name, Value, indexmap::IndexMap};

/// One inline operand off the parsed object, wire type to domain type.
///
/// `W` is named at the call site and `D` is inferred from the slot it lands in, so a row that named
/// the wrong carrier for a slot is `E0277` at the row rather than a value converted through the
/// wrong grammar.
pub fn read<W, D, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
) -> Result<Option<D>, InputValueError<F>>
where
  W: InputType + Into<D>,
  F: InputType,
{
  <Option<W> as InputType>::parse(object.get(name).cloned())
    .map(|slot| slot.map(Into::into))
    .map_err(InputValueError::propagate)
}

/// One LIST operand off the parsed object, element by element.
pub fn read_list<W, D, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
) -> Result<Option<Box<[D]>>, InputValueError<F>>
where
  W: InputType + Into<D>,
  F: InputType,
{
  <Option<Box<[W]>> as InputType>::parse(object.get(name).cloned())
    .map(|slot| {
      slot.map(|list| {
        Vec::from(list)
          .into_iter()
          .map(Into::into)
          .collect::<Box<[D]>>()
      })
    })
    .map_err(InputValueError::propagate)
}

/// One inline slot rendered back to its wire form.
///
/// The operand is CLONED, which is the honest cost of a total `to_value`: the carrier owns its
/// value, and rendering a filter must not consume the filter.
pub fn write<W, D>(slot: &Option<D>) -> Value
where
  W: InputType + From<D>,
  D: Clone,
{
  InputType::to_value(&slot.clone().map(W::from))
}

/// One list slot rendered back to its wire form.
pub fn write_list<W, D>(slot: &Option<Box<[D]>>) -> Value
where
  W: InputType + From<D>,
  D: Clone,
{
  let wire = slot
    .as_ref()
    .map(|list| list.iter().cloned().map(W::from).collect::<Box<[W]>>());
  InputType::to_value(&wire)
}

/// One inline slot, read off the parsed object through a READING's own crossing.
///
/// The carrier is inferred from `cross`, which is `I::cross` at every call — so a face names its
/// reading once, at the impl, and the eight, ten or twenty slots it carries cannot come to disagree
/// about which carrier they hold.
///
/// `F` is the OWNER and is spelled `Self` at every call: an `InputValueError` carries the type it is
/// about, so a slot's refusal has to be re-pointed at the face that was being parsed.
///
/// # Errors
///
/// A carrier async-graphql refuses is PROPAGATED — the wrong wire form is a question for the
/// binding — and a carrier the READING refuses becomes an `InputValueError::custom` carrying the
/// reading's own sentence, which is what puts a declarer's validation message in front of a client.
pub(crate) fn crossed<C, D, E, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
  cross: fn(C) -> Result<D, E>,
) -> Result<Option<D>, InputValueError<F>>
where
  C: InputType,
  E: Display,
  F: InputType,
{
  <Option<C> as InputType>::parse(object.get(name).cloned())
    .map_err(InputValueError::propagate)?
    .map(cross)
    .transpose()
    .map_err(InputValueError::custom)
}

/// One LIST slot under a reading, crossed element by element. The FIRST refusal is the answer.
pub(crate) fn crossed_list<C, D, E, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
  cross: fn(C) -> Result<D, E>,
) -> Result<Option<Box<[D]>>, InputValueError<F>>
where
  C: InputType,
  E: Display,
  F: InputType,
{
  let carried = <Option<Box<[C]>> as InputType>::parse(object.get(name).cloned())
    .map_err(InputValueError::propagate)?;

  match carried {
    Some(list) => Vec::from(list)
      .into_iter()
      .map(cross)
      .collect::<Result<Box<[D]>, E>>()
      .map(Some)
      .map_err(InputValueError::custom),
    None => Ok(None),
  }
}

/// One inline slot under a reading, written back onto the wire through its carrier.
pub(crate) fn carried<C, D>(slot: &Option<D>, carry: fn(&D) -> C) -> Value
where
  C: InputType,
{
  InputType::to_value(&slot.as_ref().map(carry))
}

/// One LIST slot under a reading, written back element by element.
pub(crate) fn carried_list<C, D>(slot: &Option<Box<[D]>>, carry: fn(&D) -> C) -> Value
where
  C: InputType,
{
  let carried = slot
    .as_ref()
    .map(|list| list.iter().map(carry).collect::<Box<[C]>>());
  InputType::to_value(&carried)
}

/// One inline slot, read off the parsed object through the OPERAND's own crossing.
///
/// The first four name their carrier at the call site, because the face that spends them is a
/// CONCRETE registration and knows it; the four above take it from a reading. The four below ask the
/// operand instead — which is what a face written over a PARAMETER has to do, the collection kinds
/// not knowing their element.
///
/// PUBLIC, with its three siblings and [`nested`], for the reason the first four are: a COMPOSED
/// filter's emitted face names them, and that expansion lands in a crate that cannot see a
/// `pub(crate)` item here. The rows that spell them are [`SlotFace`](crate::SlotFace)'s.
pub fn cross<D, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
) -> Result<Option<D>, InputValueError<F>>
where
  D: crate::ToGraphqlInput,
  D::Input: InputType,
  F: InputType,
{
  <Option<D::Input> as InputType>::parse(object.get(name).cloned())
    .map_err(InputValueError::propagate)?
    .map(D::cross)
    .transpose()
    .map_err(InputValueError::custom)
}

/// One LIST slot, crossed element by element. The FIRST refusal is the answer.
pub fn cross_list<D, F>(
  object: &IndexMap<Name, Value>,
  name: &str,
) -> Result<Option<Box<[D]>>, InputValueError<F>>
where
  D: crate::ToGraphqlInput,
  D::Input: InputType,
  F: InputType,
{
  let carried = <Option<Box<[D::Input]>> as InputType>::parse(object.get(name).cloned())
    .map_err(InputValueError::propagate)?;

  match carried {
    Some(list) => Vec::from(list)
      .into_iter()
      .map(D::cross)
      .collect::<Result<Box<[D]>, D::Error>>()
      .map(Some)
      .map_err(InputValueError::custom),
    None => Ok(None),
  }
}

/// One inline slot, rendered back through the operand's own crossing.
pub fn carry<D>(slot: &Option<D>) -> Value
where
  D: crate::ToGraphqlInput,
  D::Input: InputType,
{
  InputType::to_value(&slot.as_ref().map(D::carry))
}

/// One LIST slot, rendered back element by element.
pub fn carry_list<D>(slot: &Option<Box<[D]>>) -> Value
where
  D: crate::ToGraphqlInput,
  D::Input: InputType,
{
  let carried = slot
    .as_ref()
    .map(|list| list.iter().map(D::carry).collect::<Box<[D::Input]>>());
  InputType::to_value(&carried)
}

/// One NESTED slot — a whole filter over a component, read by that filter's OWN face.
///
/// No crossing at all, which is what makes it the odd one in this file: a nested slot's wire form IS
/// its type, so the value under `name` goes straight to the component's parser and a refusal is
/// PROPAGATED with the owner re-pointed. One parser per face, however deep the nesting runs.
///
/// # Errors
///
/// Whatever the component face refuses its own object with.
pub fn nested<V, F>(object: &IndexMap<Name, Value>, name: &str) -> Result<V, InputValueError<F>>
where
  V: InputType,
  F: InputType,
{
  V::parse(object.get(name).cloned()).map_err(InputValueError::propagate)
}