[email protected] (#762)

BREAKING

• API refactor to make it harder to ignore errors - SimonSapin, pull/752 fixing issue/709:

  • ast::Document, Schema, and ExecutableDocument not longer contain potential errors
    that users need to check separately.
  • Instead, various constructors and methods now return a Result,
    with the Err case containing both both errors and a maybe-incomplete value.
  • Change validate methods of Schema and ExecutableDocument to take ownership of self.
    On success they return the schema or document (unmodified) wrapped in a Valid<_> marker type,
    which is immutable.
  • Change ExecutableDocument to require a &Valid<Schema> instead of &Schema,
    forcing callers to either run validation or opt out explicitly with Valid::assume_valid.
  • Make parse_mixed and to_mixed validate both the schema and document.
    Rename them with a _validate suffix.
  • Corresponding changes to all of the above in Parser method signatures
  • Remove ast::Document::check_parse_errors:
    parse errors are now encoded in the return value of parse.
  • Remove ast::Document::to_schema_builder. Use SchemaBuilder::add_ast instead.
  • Move items from the crate top-level to apollo_compiler::validation:
    • Diagnostic
    • DiagnosticList
    • FileId
    • NodeLocation
  • Move items from the crate top-level to apollo_compiler::execution:
    • GraphQLError
    • GraphQLLocation
  • Remove warning-level and advice-level diagnostics. See issue/751.

  Highlight of signature changes:

  +struct Valid<T>(T); // Implements `Deref` and `AsRef` but not `DerefMut` or `AsMut`
  +
  +struct WithErrors<T> {
  +    partial: T, // Errors may cause components to be missing
  +    errors: DiagnosticList,
  +}
  
  -pub fn parse_mixed(…) -> (Schema, ExecutableDocument)
  +pub fn parse_mixed_validate(…)
  +    -> Result<(Valid<Schema>, Valid<ExecutableDocument>), DiagnosticList>
  
   impl ast::Document {
  -    pub fn parse(…) -> Self
  +    pub fn parse(…) -> Result<Self, WithErrors<Self>>
  
  -    pub fn to_schema(&self) -> Schema
  +    pub fn to_schema(&self) -> Result<Schema, WithErrors<Schema>>
  
  -    pub fn to_executable(&self) -> ExecutableDocument
  +    pub fn to_executable(&self) -> Result<ExecutableDocument, WithErrors<ExecutableDocument>>
  
  -    pub fn to_mixed(&self) -> (Schema, ExecutableDocument)
  +    pub fn to_mixed_validate(
  +        &self,
  +    ) -> Result<(Valid<Schema>, Valid<ExecutableDocument>), DiagnosticList>
   }
  
   impl Schema {
  -    pub fn parse(…) -> Self
  -    pub fn validate(&self) -> Result<DiagnosticList, DiagnosticList>
  
  +    pub fn parse_and_validate(…) -> Result<Valid<Self>, WithErrors<Self>>
  +    pub fn parse(…) -> Result<Self, WithErrors<Self>>
  +    pub fn validate(self) -> Result<Valid<Self>, WithErrors<Self>>
   }
  
   impl SchemaBuilder {
  -    pub fn build(self) -> Schema
  +    pub fn build(self) -> Result<Schema, WithErrors<Schema>>
   }
  
   impl ExecutableDocument {
  -    pub fn parse(schema: &Schema, …) -> Self
  -    pub fn validate(&self, schema: &Schema) -> Result<(), DiagnosticList>
  
  +    pub fn parse_and_validate(schema: &Valid<Schema>, …) -> Result<Valid<Self>, WithErrors<Self>>
  +    pub fn parse(schema: &Valid<Schema>, …) -> Result<Self, WithErrors<Self>>
  +    pub fn validate(self, schema: &Valid<Schema>) -> Result<Valid<Self>, WithErrors<Self>>
   }

Features

• Add parse_and_validate constructors for Schema and ExecutableDocument - SimonSapin, pull/752:
  when mutating isn’t needed after parsing, this returns an immutable Valid<_> value in one step.

• Implement serde Serialize and Deserialize for some AST types - SimonSapin, pull/760:

  • Node
  • NodeStr
  • Name
  • IntValue
  • FloatValue
  • Value
  • Type
    Source locations are not preserved through serialization.

• Add ast::Definition::as_*() -> Option<&_> methods for each variant - SimonSapin, pull/760

• Serialize (to GraphQL) multi-line strings as block strings - SimonSapin, pull/724:
  Example before:

  "Example\n\nDescription description description"
  schema { query: MyQuery }

  After:

  """
  Example
  
  Description description description
  """
  schema { query: MyQuery }

Fixes

• Limit recursion in validation - goto-bus-stop, pull/748 fixing issue/742:
  Validation now bails out of very long chains of definitions that refer to each other,
  even if they don't strictly form a cycle. These could previously cause extremely long validation
  times or stack overflows.

  The limit for input objects and directives is set at 32. For fragments, the limit is set at 100.
  Based on our datasets, real-world documents don't come anywhere close to this.