Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Executable-document IR.
//!
//! apollo-parser's CST is lossless but awkward to walk repeatedly; we convert
//! each document once into a compact IR (and memoize by document hash at the
//! engine level). The IR is also where parse-time invariants are enforced so
//! the normalize/denormalize walks can be infallible about shape.
use crate::value::canonical_json;
use apollo_parser::cst;
use apollo_parser::cst::CstNode;
use serde_json::Value as Json;
use std::collections::HashMap;
use thiserror::Error;
mod prepare;
pub(crate) use prepare::prepare_selections;
#[derive(Debug, Error)]
pub enum DocumentError {
#[error("GraphQL parse error: {0}")]
Parse(String),
#[error("document has no operations")]
NoOperation,
#[error("operation `{0}` not found")]
UnknownOperation(String),
#[error("unsupported operation type: {0}")]
UnsupportedOperationType(String),
#[error("fragment `{0}` is not defined")]
UnknownFragment(String),
#[error("unsupported directive `@{0}` requires network execution")]
UnsupportedDirective(String),
#[error("invalid condition for `@{0}`")]
InvalidCondition(String),
#[error("malformed document: {0}")]
Malformed(&'static str),
}
/// Argument value: constant JSON or a variable reference resolved at
/// read/write time.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ArgValue {
Const(Json),
Variable(String),
List(Vec<ArgValue>),
Object(Vec<(String, ArgValue)>),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FieldNode {
/// Response key (alias if present, else name).
pub response_key: String,
/// Schema field name.
pub name: String,
/// The field is persisted but omitted from hydration results.
pub cache_only: bool,
/// Conditional directives evaluated once against operation variables.
pub conditions: Vec<(String, ArgValue)>,
pub arguments: Vec<(String, ArgValue)>,
pub selection_set: Vec<Selection>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Selection {
Field(FieldNode),
/// Inline fragment or named-fragment spread, already flattened to a type
/// condition (None = no condition) plus selections.
Fragment {
type_condition: Option<String>,
conditions: Vec<(String, ArgValue)>,
selection_set: Vec<Selection>,
},
}
/// Kind of an executable operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OperationKind {
Query,
Mutation,
Subscription,
}
#[derive(Debug, Clone)]
pub struct Operation {
pub name: Option<String>,
pub kind: OperationKind,
pub variable_defaults: serde_json::Map<String, Json>,
pub selection_set: Vec<Selection>,
}
/// Named fragment definition retained for fragment-rooted record reads.
#[derive(Debug, Clone)]
pub struct Fragment {
pub name: String,
pub type_condition: String,
pub selection_set: Vec<Selection>,
}
#[derive(Debug, Clone)]
pub struct Document {
pub operations: Vec<Operation>,
pub fragments: Vec<Fragment>,
}
impl Document {
/// Parses executable document text into the IR. Fragment spreads are
/// inlined (cycles rejected by the parser's recursion limit; fragments
/// must be defined in the same document, which urql guarantees).
pub fn parse(text: &str) -> Result<Document, DocumentError> {
let tree = apollo_parser::Parser::new(text).parse();
if tree.errors().len() > 0 {
let msg = tree
.errors()
.map(|e| e.message().to_string())
.collect::<Vec<_>>()
.join("; ");
return Err(DocumentError::Parse(msg));
}
let doc = tree.document();
let mut fragments: HashMap<String, cst::FragmentDefinition> = HashMap::new();
let mut operations_cst = Vec::new();
for def in doc.definitions() {
match def {
cst::Definition::OperationDefinition(op) => operations_cst.push(op),
cst::Definition::FragmentDefinition(frag) => {
let name = frag
.fragment_name()
.and_then(|n| n.name())
.ok_or(DocumentError::Malformed("fragment without name"))?
.text()
.to_string();
fragments.insert(name, frag);
}
_ => {
return Err(DocumentError::Malformed(
"type-system definition in executable document",
));
}
}
}
if operations_cst.is_empty() && fragments.is_empty() {
return Err(DocumentError::NoOperation);
}
let mut operations = Vec::new();
for op in operations_cst {
// Shorthand (no operation type keyword) is a query.
let kind = match op.operation_type() {
None => OperationKind::Query,
Some(ty) if ty.query_token().is_some() => OperationKind::Query,
Some(ty) if ty.mutation_token().is_some() => OperationKind::Mutation,
Some(ty) if ty.subscription_token().is_some() => OperationKind::Subscription,
Some(ty) => {
let label = ty.syntax().text().to_string();
return Err(DocumentError::UnsupportedOperationType(label));
}
};
let selection_set = convert_selection_set(
op.selection_set()
.ok_or(DocumentError::Malformed("operation without selection set"))?,
&fragments,
0,
)?;
let mut variable_defaults = serde_json::Map::new();
if let Some(definitions) = op.variable_definitions() {
for definition in definitions.variable_definitions() {
if let Some(value) = definition
.default_value()
.and_then(|default| default.value())
{
let name = definition
.variable()
.ok_or(DocumentError::Malformed("variable without name"))?
.text()
.to_string();
let value = resolve_arg(&convert_value(value)?, &serde_json::Map::new())
.map_err(|_| {
DocumentError::Malformed("nonconstant variable default")
})?;
variable_defaults.insert(name, value);
}
}
}
prepare::conditions(op.directives())?;
operations.push(Operation {
name: op.name().map(|n| n.text().to_string()),
kind,
variable_defaults,
selection_set,
});
}
let mut fragment_names: Vec<_> = fragments.keys().cloned().collect();
fragment_names.sort();
let mut converted_fragments = Vec::with_capacity(fragment_names.len());
for name in fragment_names {
let definition = &fragments[&name];
let type_condition = definition
.type_condition()
.and_then(|condition| condition.named_type())
.and_then(|named| named.name())
.ok_or(DocumentError::Malformed("fragment without type condition"))?
.text()
.to_string();
let selection_set = convert_selection_set(
definition
.selection_set()
.ok_or(DocumentError::Malformed("fragment without selections"))?,
&fragments,
0,
)?;
converted_fragments.push(Fragment {
name,
type_condition,
selection_set,
});
}
Ok(Document {
operations,
fragments: converted_fragments,
})
}
/// Selects an operation by name (or the only one when unnamed).
pub fn operation(&self, name: Option<&str>) -> Result<&Operation, DocumentError> {
match name {
None if self.operations.is_empty() => Err(DocumentError::NoOperation),
None => {
if self.operations.len() == 1 {
Ok(&self.operations[0])
} else {
Err(DocumentError::Malformed(
"operation name required for multi-operation documents",
))
}
}
Some(n) => self
.operations
.iter()
.find(|o| o.name.as_deref() == Some(n))
.ok_or_else(|| DocumentError::UnknownOperation(n.to_string())),
}
}
/// Selects a named fragment from this document.
pub fn fragment(&self, name: &str) -> Result<&Fragment, DocumentError> {
self.fragments
.iter()
.find(|fragment| fragment.name == name)
.ok_or_else(|| DocumentError::UnknownFragment(name.to_string()))
}
}
const MAX_FRAGMENT_DEPTH: usize = 32;
fn convert_selection_set(
set: cst::SelectionSet,
fragments: &HashMap<String, cst::FragmentDefinition>,
depth: usize,
) -> Result<Vec<Selection>, DocumentError> {
if depth > MAX_FRAGMENT_DEPTH {
return Err(DocumentError::Malformed(
"fragment nesting too deep (cycle?)",
));
}
let mut out = Vec::new();
for sel in set.selections() {
match sel {
cst::Selection::Field(f) => {
let name = f
.name()
.ok_or(DocumentError::Malformed("field without name"))?
.text()
.to_string();
let response_key = f
.alias()
.and_then(|a| a.name())
.map(|n| n.text().to_string())
.unwrap_or_else(|| name.clone());
let mut arguments = Vec::new();
if let Some(args) = f.arguments() {
for arg in args.arguments() {
let arg_name = arg
.name()
.ok_or(DocumentError::Malformed("argument without name"))?
.text()
.to_string();
let value = arg
.value()
.ok_or(DocumentError::Malformed("argument without value"))?;
arguments.push((arg_name, convert_value(value)?));
}
}
let cache_only = f.directives().is_some_and(|directives| {
directives.directives().any(|directive| {
directive
.name()
.is_some_and(|name| name.text() == "cacheOnly")
})
});
let selection_set = match f.selection_set() {
Some(s) => convert_selection_set(s, fragments, depth + 1)?,
None => Vec::new(),
};
out.push(Selection::Field(FieldNode {
response_key,
name,
cache_only,
conditions: prepare::conditions(f.directives())?,
arguments,
selection_set,
}));
}
cst::Selection::InlineFragment(frag) => {
let type_condition = frag
.type_condition()
.and_then(|tc| tc.named_type())
.and_then(|nt| nt.name())
.map(|n| n.text().to_string());
let selection_set = convert_selection_set(
frag.selection_set().ok_or(DocumentError::Malformed(
"inline fragment without selections",
))?,
fragments,
depth + 1,
)?;
out.push(Selection::Fragment {
type_condition,
conditions: prepare::conditions(frag.directives())?,
selection_set,
});
}
cst::Selection::FragmentSpread(spread) => {
let name = spread
.fragment_name()
.and_then(|n| n.name())
.ok_or(DocumentError::Malformed("fragment spread without name"))?
.text()
.to_string();
let def = fragments
.get(&name)
.ok_or_else(|| DocumentError::UnknownFragment(name.clone()))?;
let type_condition = def
.type_condition()
.and_then(|tc| tc.named_type())
.and_then(|nt| nt.name())
.map(|n| n.text().to_string());
let selection_set = convert_selection_set(
def.selection_set()
.ok_or(DocumentError::Malformed("fragment without selections"))?,
fragments,
depth + 1,
)?;
prepare::conditions(def.directives())?;
out.push(Selection::Fragment {
type_condition,
conditions: prepare::conditions(spread.directives())?,
selection_set,
});
}
}
}
Ok(out)
}
fn convert_value(value: cst::Value) -> Result<ArgValue, DocumentError> {
Ok(match value {
cst::Value::Variable(v) => ArgValue::Variable(v.text().to_string()),
cst::Value::StringValue(s) => ArgValue::Const(Json::String(String::from(s))),
cst::Value::IntValue(i) => {
let text = i.syntax().text().to_string();
let n: serde_json::Number = text
.parse::<i64>()
.map(Into::into)
.map_err(|_| DocumentError::Malformed("invalid int literal"))?;
ArgValue::Const(Json::Number(n))
}
cst::Value::FloatValue(f) => {
let text = f.syntax().text().to_string();
let parsed: f64 = text
.parse()
.map_err(|_| DocumentError::Malformed("invalid float literal"))?;
let n = serde_json::Number::from_f64(parsed)
.ok_or(DocumentError::Malformed("non-finite float literal"))?;
ArgValue::Const(Json::Number(n))
}
cst::Value::BooleanValue(b) => {
ArgValue::Const(Json::Bool(b.syntax().text().to_string().trim() == "true"))
}
cst::Value::NullValue(_) => ArgValue::Const(Json::Null),
cst::Value::EnumValue(e) => ArgValue::Const(Json::String(e.text().to_string())),
cst::Value::ListValue(l) => {
let mut items = Vec::new();
for item in l.values() {
items.push(convert_value(item)?);
}
ArgValue::List(items)
}
cst::Value::ObjectValue(o) => {
let mut fields = Vec::new();
for f in o.object_fields() {
let name = f
.name()
.ok_or(DocumentError::Malformed("object field without name"))?
.text()
.to_string();
let value = f
.value()
.ok_or(DocumentError::Malformed("object field without value"))?;
fields.push((name, convert_value(value)?));
}
ArgValue::Object(fields)
}
})
}
#[derive(Debug, Error)]
#[error("missing variable `{0}`")]
pub struct MissingVariable(pub String);
/// Resolves an argument value against operation variables into plain JSON.
pub fn resolve_arg(
value: &ArgValue,
variables: &serde_json::Map<String, Json>,
) -> Result<Json, MissingVariable> {
Ok(match value {
ArgValue::Const(v) => v.clone(),
ArgValue::Variable(name) => variables
.get(name)
.cloned()
.ok_or_else(|| MissingVariable(name.clone()))?,
ArgValue::List(items) => Json::Array(
items
.iter()
.map(|i| resolve_arg(i, variables))
.collect::<Result<_, _>>()?,
),
ArgValue::Object(fields) => {
let mut map = serde_json::Map::new();
for (k, v) in fields {
map.insert(k.clone(), resolve_arg(v, variables)?);
}
Json::Object(map)
}
})
}
/// Resolves all of a field's arguments against operation variables.
pub fn resolve_args(
field: &FieldNode,
variables: &serde_json::Map<String, Json>,
) -> Result<serde_json::Map<String, Json>, MissingVariable> {
let mut map = serde_json::Map::new();
for (name, value) in &field.arguments {
map.insert(name.clone(), resolve_arg(value, variables)?);
}
Ok(map)
}
/// Converts already-resolved field arguments to their canonical storage-key
/// suffix (`None` when the field declares no arguments).
pub fn resolved_args_key(
field: &FieldNode,
arguments: &serde_json::Map<String, Json>,
) -> Option<String> {
(!field.arguments.is_empty()).then(|| canonical_json(&Json::Object(arguments.clone())))
}
/// Resolves a field's arguments to a canonical string (`None` when the field
/// has no arguments), for use in field storage keys.
pub fn resolve_args_key(
field: &FieldNode,
variables: &serde_json::Map<String, Json>,
) -> Result<Option<String>, MissingVariable> {
let arguments = resolve_args(field, variables)?;
Ok(resolved_args_key(field, &arguments))
}
#[cfg(test)]
mod tests {
use super::*;
const DOC: &str = r#"
query Soup($input: SoupInput!) {
soup(input: $input) {
items {
__typename
id
... on GraphqlSoupDocument { docName: name }
...ChatFields
}
nextCursor
}
}
fragment ChatFields on GraphqlSoupChat { chatName: name }
"#;
#[test]
fn parses_real_shape() {
let doc = Document::parse(DOC).unwrap();
let op = doc.operation(Some("Soup")).unwrap();
assert_eq!(op.name.as_deref(), Some("Soup"));
let Selection::Field(soup) = &op.selection_set[0] else {
panic!("expected field");
};
assert_eq!(soup.name, "soup");
assert!(matches!(&soup.arguments[0].1, ArgValue::Variable(v) if v == "input"));
// fragment spread flattened with type condition
let Selection::Field(items) = &soup.selection_set[0] else {
panic!()
};
let conditions: Vec<_> = items
.selection_set
.iter()
.filter_map(|s| match s {
Selection::Fragment { type_condition, .. } => type_condition.clone(),
_ => None,
})
.collect();
assert_eq!(conditions, vec!["GraphqlSoupDocument", "GraphqlSoupChat"]);
}
#[test]
fn alias_and_args_key() {
let doc = Document::parse(DOC).unwrap();
let op = doc.operation(Some("Soup")).unwrap();
let Selection::Field(soup) = &op.selection_set[0] else {
panic!()
};
let mut vars = serde_json::Map::new();
vars.insert(
"input".into(),
serde_json::json!({"limit": 20, "cursor": null}),
);
assert_eq!(
resolve_args_key(soup, &vars).unwrap().unwrap(),
r#"{"input":{"cursor":null,"limit":20}}"#
);
assert!(matches!(
resolve_args_key(soup, &serde_json::Map::new()),
Err(MissingVariable(v)) if v == "input"
));
}
#[test]
fn parses_operation_kinds() {
let doc = Document::parse(DOC).unwrap();
assert_eq!(
doc.operation(Some("Soup")).unwrap().kind,
OperationKind::Query
);
let doc = Document::parse("mutation M { doThing }").unwrap();
assert_eq!(
doc.operation(Some("M")).unwrap().kind,
OperationKind::Mutation
);
let doc = Document::parse("subscription S { soupUpdates { __typename } }").unwrap();
assert_eq!(
doc.operation(Some("S")).unwrap().kind,
OperationKind::Subscription
);
// Shorthand operations are queries.
let doc = Document::parse("{ user { id } }").unwrap();
assert_eq!(doc.operation(None).unwrap().kind, OperationKind::Query);
}
#[test]
fn rejects_unknown_fragment() {
let err = Document::parse("query Q { a { ...Nope } }").unwrap_err();
assert!(matches!(err, DocumentError::UnknownFragment(_)));
}
}