shrink docs. (#121)

README.md

@@ -78,9 +78,7 @@ While the `Client` constructor is an easy quick start, the library also has seve
 
 - [Composer](./docs/composer.md) - merges and validates many schemas into one supergraph.
 - [Supergraph](./docs/supergraph.md) - manages the combined schema, location routing maps, and executable resources. Can be exported, cached, and rehydrated.
-- [Request](./docs/request.md) - prepares a requested GraphQL document and variables for stitching.
-- [Planner](./docs/planner.md) - builds a cacheable query plan for a request document.
-- [Executor](./docs/executor.md) - executes a query plan with given request variables.
+- [Request](./docs/request.md) - manages the lifecycle of a stitched GraphQL request.
 - [HttpExecutable](./docs/http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 ## Merged types

docs/README.md

@@ -10,8 +10,6 @@ Major components include:
 - [Composer](./composer.md) - merges and validates many schemas into one graph.
 - [Supergraph](./supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
 - [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
-- [Planner](./planner.md) - builds a cacheable query plan for a request document.
-- [Executor](./executor.md) - executes a query plan with given request variables.
 - [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 Additional topics:

docs/request.md

@@ -25,37 +25,12 @@ A `Request` provides the following information:
 - `req.variable_definitions`: a mapping of variable names to their type definitions
 - `req.fragment_definitions`: a mapping of fragment names to their fragment definitions
 
-### Preparing requests
+### Request lifecycle
 
-A request should be prepared for stitching using the `prepare!` method _after_ validations have been run:
+A request manages the flow of stitching behaviors. These are sequenced by the `Client`
+component, or you may invoke them manually:
 
-```ruby
-document = <<~GRAPHQL
-  query FetchMovie($id: ID!, $lang: String = "en", $withShowtimes: Boolean = true) {
-    movie(id:$id) {
-      id
-      title(lang: $lang)
-      showtimes @include(if: $withShowtimes) {
-        time
-      }
-    }
-  }
-GRAPHQL
-
-request = GraphQL::Stitching::Request.new(
-  supergraph,
-  document,
-  variables: { "id" => "1" },
-  operation_name: "FetchMovie",
-)
-
-errors = MySchema.validate(request.document)
-# return early with any static validation errors...
-
-request.prepare!
-```
-
-Preparing a request will apply several destructive transformations:
-
-- Default values from variable definitions will be added to request variables.
-- The document will be pre-shaped based on `@skip` and `@include` directives.
+1. `request.validate`: runs static validations on the request using the combined schema.
+2. `request.prepare!`: inserts variable defaults and pre-renders skip/include conditional shaping.
+3. `request.plan`: builds a plan for the request. May act as a setting for plans pulled from cache.
+4. `request.execute`: executes the request, and returns the resulting data.

lib/graphql/stitching/request.rb

@@ -120,12 +120,13 @@ def fragment_definitions
       end
 
       # Validates the request using the combined supergraph schema.
+      # @return [Array<GraphQL::ExecutionError>] an array of static validation errors
       def validate
         result = @supergraph.static_validator.validate(@query)
         result[:errors]
       end
 
-      # Prepares the request for stitching by rendering variable defaults and applying @skip/@include conditionals.
+      # Prepares the request for stitching by inserting variable defaults and applying @skip/@include conditionals.
       def prepare!
         operation.variables.each do |v|
           @variables[v.name] = v.default_value if @variables[v.name].nil? && !v.default_value.nil?
@@ -143,7 +144,17 @@ def prepare!
         self
       end
 
-      # Gets and sets the query plan for the request. Assigned query plans may pull from cache.
+      # Gets and sets the query plan for the request. Assigned query plans may pull from a cache,
+      # which is useful for redundant GraphQL documents (commonly sent by frontend clients).
+      # ```ruby
+      # if cached_plan = $cache.get(request.digest)
+      #   plan = GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
+      #   request.plan(plan)
+      # else
+      #   plan = request.plan
+      #   $cache.set(request.digest, JSON.generate(plan.as_json))
+      # end
+      # ```
       # @param new_plan [Plan, nil] a cached query plan for the request.
       # @return [Plan] query plan for the request.
       def plan(new_plan = nil)