graph_weaver 0.6.1 → 0.7.1

data/examples/README.md

@@ -0,0 +1,38 @@
+# Examples
+
+Four runnable scripts, smallest first. Each is the smallest thing that shows
+its idea; run them straight from a checkout.
+
+| | shows | needs |
+|---|---|---|
+| [`countries.rb`](countries.rb) | the whole loop in 30 lines: a client, `parse`, a typed result, a one-shot `run!` | network |
+| [`rick_and_morty.rb`](rick_and_morty.rb) | filtering, pagination, an aliased field, a block-built type helper | network |
+| [`federation.rb`](federation.rb) | a federated graph planned and stitched in-process, with the fetch trace and a refusal | nothing |
+| [`github/`](github) | the production path: auth, a custom scalar, checked-in generated modules | a token |
+
+```sh
+bundle exec examples/countries.rb JP BR
+bundle exec examples/rick_and_morty.rb morty
+bundle exec examples/federation.rb
+bundle exec examples/github/run.rb        # gh auth login, or GITHUB_TOKEN=...
+```
+
+**`federation.rb` is the one with no network at all** — three real subgraphs, a
+boundary-crossing query through a generated module, the trace of the fetches it
+took, and a refusal it declines to plan. `spec/examples_spec.rb` runs it on every
+build.
+
+**`github/` is the only one with committed generated code**, so it's the one that
+looks like an app:
+
+- [`setup.rb`](github/setup.rb) — the shared wiring an initializer would hold:
+  auth and the client.
+- [`queries/`](github/queries) → [`generate.rb`](github/generate.rb) →
+  [`generated/`](github/generated) — the build loop `rake graph_weaver:generate`
+  runs in a Rails app.
+- [`run.rb`](github/run.rb) — stars this repo ⭐ and introduces you to your
+  fellow stargazers.
+
+Regeneration introspects GitHub's schema (a few seconds, cached to a gitignored
+`github/schema.json`); `run.rb` alone never introspects, because the generated
+modules already carry their types.

data/examples/countries.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# The simplest possible GraphWeaver session: a public API, no auth, no
+# build step — everything dynamic and in memory.
+#
+#      examples/countries.rb [CODE ...]
+#      examples/countries.rb JP BR
+#
+# (https://countries.trevorblades.com — a free public GraphQL API)
+require_relative "../lib/graph_weaver"
+
+api = GraphWeaver.new("https://countries.trevorblades.com/")
+
+# parse once: a typed module bound to the client's schema + transport
+CountryQuery = api.parse(<<~GRAPHQL)
+  query($code: ID!) {
+    country(code: $code) {
+      name
+      emoji
+      capital
+      continent { name }
+    }
+  }
+GRAPHQL
+
+codes = ARGV.empty? ? %w[US JP] : ARGV
+codes.each do |code|
+  country = CountryQuery.execute!(code: code.upcase).country
+  abort "unknown country code: #{code}" unless country
+
+  puts "#{country.emoji}  #{country.name} — capital #{country.capital}, #{country.continent.name}"
+end
+
+# or skip the module entirely — a one-shot with variables as kwargs
+continents = api.run!("query { continents { name countries { code } } }").continents
+biggest = continents.max_by { |c| c.countries.size }
+puts "\n#{continents.size} continents; #{biggest.name} has the most countries (#{biggest.countries.size})"

data/examples/federation.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# typed: ignore — the subgraph schema classes it borrows are themselves ignored
+# frozen_string_literal: true
+
+# The only example that needs no network: a federated graph running entirely
+# in this process. `Testing::Router` takes the composed supergraph, plans a
+# query across the subgraphs, and stitches the answer — so a generated module
+# runs against your real resolvers with no gateway, no node, no sockets.
+#
+#      bundle exec examples/federation.rb
+#
+# The subgraphs are the suite's own (spec/support/federation_router_graph.rb):
+# `accounts` owns User, `products` owns Product, and `reviews` owns Review
+# while extending both — the Apollo demo graph, as three real
+# apollo-federation schemas. supergraph.graphql beside them is Apollo's own
+# composition of the three, recomposed and diffed by the suite, so what runs
+# here is the real thing.
+#
+# Everything the router does beyond this — @requires, a partly-local
+# supergraph, the `:fake` opt-in, every refusal — is spec/router_spec.rb.
+require_relative "../lib/graph_weaver"
+require_relative "../lib/graph_weaver/testing"
+require_relative "../spec/support/federation_router_graph"
+
+# Only the supergraph is needed: which Ruby schema serves each subgraph is
+# derived from what each loaded schema defines.
+router = GraphWeaver::Testing::Router.new(supergraph: RouterGraph::SUPERGRAPH)
+puts router.inspect
+
+# me → accounts, reviews → reviews, product → products. The router holds the
+# supergraph, so it parses against it — and the module runs on the router.
+DashboardQuery = router.parse(<<~GRAPHQL, name: "DashboardQuery")
+  query Dashboard {
+    me {
+      username
+      reviews { body product { name price } }
+    }
+  }
+GRAPHQL
+
+me = DashboardQuery.execute!.me
+puts "\n#{me.username} reviewed #{me.reviews.size} products:"
+me.reviews.each { |review| puts "  #{review.product.name} ($#{review.product.price}) — #{review.body}" }
+
+# The trace is the mechanism in one read: a root fetch, then one `_entities`
+# call per subgraph per level — every node at a level in ONE call, so two
+# products are one fetch, not two.
+puts "\nfetches:"
+router.trace.each do |fetch|
+  reps = fetch[:variables]["representations"]
+  puts "  → #{fetch[:subgraph].ljust(9)} #{reps ? "_entities × #{reps.size} #{reps.first["__typename"]}" : "root fields"}"
+end
+
+# Everything it can't plan *faithfully* raises at plan time, before any
+# subgraph runs. Here the alias collides with the @key the planner injects to
+# cross the boundary, and Apollo's router and a spec-conformant server answer
+# that differently — so there is no one answer to agree with.
+begin
+  router.execute("{ me { id: username reviews { body } } }")
+rescue GraphWeaver::Testing::Unplannable => e
+  puts "\nrefused (#{e.label}):\n  #{e.message}"
+end

data/examples/github/generate.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# Regenerate the checked-in typed modules from queries/*.graphql —
+# the same workflow `rake graph_weaver:generate` runs in an app:
+#
+#      examples/github/generate.rb
+require_relative "setup"
+
+GraphWeaver.graph :github do
+  schema GraphWeaver.client.schema
+  queries File.join(__dir__, "queries")
+  output File.join(__dir__, "generated")
+end
+
+GraphWeaver.generate!
+changed = GraphWeaver.changed_files
+changed.each { |path| puts "wrote #{path}" }
+puts "already up to date" if changed.empty?

data/examples/github/generated/star_mutation.rb

@@ -0,0 +1,126 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Generated by GraphWeaver 0.7.0 — do not edit.
+
+module StarMutation
+  extend T::Sig
+
+  QUERY = T.let(<<~'GRAPHQL', String)
+    mutation StarMutation($id: ID!) {
+      addStar(input: { starrableId: $id }) {
+        starrable {
+          stargazerCount
+          viewerHasStarred
+        }
+      }
+    }
+  GRAPHQL
+
+  # sent as the request's operationName — what an APM keys traces on
+  OPERATION_NAME = T.let("StarMutation", T.nilable(String))
+
+  class Result < T::Struct
+    extend T::Sig
+    include GraphWeaver::Hints
+    include GraphWeaver::ResultStruct
+
+    class AddStar < T::Struct
+      extend T::Sig
+      include GraphWeaver::Hints
+      include GraphWeaver::ResultStruct
+
+      class Starrable < T::Struct
+        extend T::Sig
+        include GraphWeaver::Hints
+        include GraphWeaver::ResultStruct
+
+        const :stargazer_count, Integer
+        const :viewer_has_starred, T::Boolean
+
+        sig { params(data: T::Hash[String, T.untyped]).returns(Starrable) }
+        def self.from_h(data)
+          new(
+            stargazer_count: data.fetch("stargazerCount"),
+            viewer_has_starred: data.fetch("viewerHasStarred"),
+          )
+        rescue GraphWeaver::Error
+          raise # already branded by a nested struct or leaf — keep the innermost context
+        rescue StandardError => e
+          raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+        end
+      end
+
+      const :starrable, T.nilable(Starrable)
+
+      sig { params(data: T::Hash[String, T.untyped]).returns(AddStar) }
+      def self.from_h(data)
+        new(
+          starrable: data["starrable"]&.then { |v1| Starrable.from_h(v1) },
+        )
+      rescue GraphWeaver::Error
+        raise # already branded by a nested struct or leaf — keep the innermost context
+      rescue StandardError => e
+        raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+      end
+    end
+
+    const :add_star, T.nilable(AddStar)
+
+    sig { params(data: T::Hash[String, T.untyped]).returns(Result) }
+    def self.from_h(data)
+      new(
+        add_star: data["addStar"]&.then { |v1| AddStar.from_h(v1) },
+      )
+    rescue GraphWeaver::Error
+      raise # already branded by a nested struct or leaf — keep the innermost context
+    rescue StandardError => e
+      raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+    end
+  end
+
+  # client / client= — see GraphWeaver::QueryModule
+  extend GraphWeaver::QueryModule
+
+  # the graph this module was generated from — what a test mode builds
+  # its stand-in client from
+  GRAPH = T.let(:github, Symbol)
+  private_constant :GRAPH
+
+  # .checked(:never): an untyped value (a Rails param) reaches the coercion
+  # below instead of being rejected by sorbet-runtime's argument check.
+  sig { params(id: String, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
+  def self.execute(id:, client: nil)
+    variables = {
+      "id" => GraphWeaver::Coerce.variable("id", OPERATION_NAME, id) { |v| GraphWeaver::Coerce.id(v) },
+    }
+
+    from_response(dispatch(variables, client:))
+  end
+
+  sig { params(id: String, client: T.untyped).returns(Result).checked(:never) }
+  def self.execute!(id:, client: nil)
+    execute(id:, client:).data!
+  end
+
+  # Deserialize a raw GraphQL response into the typed envelope — the
+  # network-free half of execute, for responses fetched by any client.
+  # Takes the response hash (or anything with #to_h): {"data" => ...,
+  # "errors" => ..., "extensions" => ...} with wire-cased string keys.
+  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }
+  def self.from_response(response)
+    raw = GraphWeaver.check_envelope!(response, Result)
+    errors = (raw["errors"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) }
+    GraphWeaver::Response[Result].new(
+      data: (GraphWeaver.cast_data(Result, raw["data"], errors) if raw["data"]),
+      errors:,
+      extensions: raw["extensions"] || {},
+    )
+  end
+
+  # from_response + data! — the typed result, or a raised QueryError.
+  sig { params(response: T.untyped).returns(Result) }
+  def self.from_response!(response)
+    from_response(response).data!
+  end
+end

data/examples/github/generated/stargazers_query.rb

@@ -0,0 +1,232 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Generated by GraphWeaver 0.7.0 — do not edit.
+
+require "time"
+
+module StargazersQuery
+  extend T::Sig
+
+  QUERY = T.let(<<~'GRAPHQL', String)
+    query StargazersQuery($owner: String!, $name: String!, $first: Int!) {
+      repository(owner: $owner, name: $name) {
+        id
+        nameWithOwner
+        stargazerCount
+        stargazers(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+          edges {
+            starredAt
+            node {
+              login
+              name
+              repositories(first: 2, orderBy: { field: STARGAZERS, direction: DESC }) {
+                nodes {
+                  nameWithOwner
+                  stargazerCount
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  GRAPHQL
+
+  # sent as the request's operationName — what an APM keys traces on
+  OPERATION_NAME = T.let("StargazersQuery", T.nilable(String))
+
+  class Result < T::Struct
+    extend T::Sig
+    include GraphWeaver::Hints
+    include GraphWeaver::ResultStruct
+
+    class Repository < T::Struct
+      extend T::Sig
+      include GraphWeaver::Hints
+      include GraphWeaver::ResultStruct
+
+      class Stargazers < T::Struct
+        extend T::Sig
+        include GraphWeaver::Hints
+        include GraphWeaver::ResultStruct
+
+        class Edges < T::Struct
+          extend T::Sig
+          include GraphWeaver::Hints
+          include GraphWeaver::ResultStruct
+
+          class Node < T::Struct
+            extend T::Sig
+            include GraphWeaver::Hints
+            include GraphWeaver::ResultStruct
+
+            class Repositories < T::Struct
+              extend T::Sig
+              include GraphWeaver::Hints
+              include GraphWeaver::ResultStruct
+
+              class Nodes < T::Struct
+                extend T::Sig
+                include GraphWeaver::Hints
+                include GraphWeaver::ResultStruct
+
+                const :name_with_owner, String
+                const :stargazer_count, Integer
+
+                sig { params(data: T::Hash[String, T.untyped]).returns(Nodes) }
+                def self.from_h(data)
+                  new(
+                    name_with_owner: data.fetch("nameWithOwner"),
+                    stargazer_count: data.fetch("stargazerCount"),
+                  )
+                rescue GraphWeaver::Error
+                  raise # already branded by a nested struct or leaf — keep the innermost context
+                rescue StandardError => e
+                  raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+                end
+              end
+
+              const :nodes, T.nilable(T::Array[T.nilable(Nodes)])
+
+              sig { params(data: T::Hash[String, T.untyped]).returns(Repositories) }
+              def self.from_h(data)
+                new(
+                  nodes: data["nodes"]&.then { |v1| v1.map { |v2| v2&.then { |v3| Nodes.from_h(v3) } } },
+                )
+              rescue GraphWeaver::Error
+                raise # already branded by a nested struct or leaf — keep the innermost context
+              rescue StandardError => e
+                raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+              end
+            end
+
+            const :login, String
+            const :name, T.nilable(String)
+            const :repositories, Repositories
+
+            sig { params(data: T::Hash[String, T.untyped]).returns(Node) }
+            def self.from_h(data)
+              new(
+                login: data.fetch("login"),
+                name: data["name"],
+                repositories: Repositories.from_h(data.fetch("repositories")),
+              )
+            rescue GraphWeaver::Error
+              raise # already branded by a nested struct or leaf — keep the innermost context
+            rescue StandardError => e
+              raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+            end
+          end
+
+          const :starred_at, Time
+          const :node, Node
+
+          sig { params(data: T::Hash[String, T.untyped]).returns(Edges) }
+          def self.from_h(data)
+            new(
+              starred_at: GraphWeaver::Hints.field(self, "starredAt") { Time.parse(data.fetch("starredAt")) },
+              node: Node.from_h(data.fetch("node")),
+            )
+          rescue GraphWeaver::Error
+            raise # already branded by a nested struct or leaf — keep the innermost context
+          rescue StandardError => e
+            raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+          end
+        end
+
+        const :edges, T.nilable(T::Array[T.nilable(Edges)])
+
+        sig { params(data: T::Hash[String, T.untyped]).returns(Stargazers) }
+        def self.from_h(data)
+          new(
+            edges: data["edges"]&.then { |v1| v1.map { |v2| v2&.then { |v3| Edges.from_h(v3) } } },
+          )
+        rescue GraphWeaver::Error
+          raise # already branded by a nested struct or leaf — keep the innermost context
+        rescue StandardError => e
+          raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+        end
+      end
+
+      const :id, String
+      const :name_with_owner, String
+      const :stargazer_count, Integer
+      const :stargazers, Stargazers
+
+      sig { params(data: T::Hash[String, T.untyped]).returns(Repository) }
+      def self.from_h(data)
+        new(
+          id: data.fetch("id"),
+          name_with_owner: data.fetch("nameWithOwner"),
+          stargazer_count: data.fetch("stargazerCount"),
+          stargazers: Stargazers.from_h(data.fetch("stargazers")),
+        )
+      rescue GraphWeaver::Error
+        raise # already branded by a nested struct or leaf — keep the innermost context
+      rescue StandardError => e
+        raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+      end
+    end
+
+    const :repository, T.nilable(Repository)
+
+    sig { params(data: T::Hash[String, T.untyped]).returns(Result) }
+    def self.from_h(data)
+      new(
+        repository: data["repository"]&.then { |v1| Repository.from_h(v1) },
+      )
+    rescue GraphWeaver::Error
+      raise # already branded by a nested struct or leaf — keep the innermost context
+    rescue StandardError => e
+      raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+    end
+  end
+
+  # client / client= — see GraphWeaver::QueryModule
+  extend GraphWeaver::QueryModule
+
+  # the graph this module was generated from — what a test mode builds
+  # its stand-in client from
+  GRAPH = T.let(:github, Symbol)
+  private_constant :GRAPH
+
+  # .checked(:never): an untyped value (a Rails param) reaches the coercion
+  # below instead of being rejected by sorbet-runtime's argument check.
+  sig { params(owner: String, name: String, first: Integer, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
+  def self.execute(owner:, name:, first:, client: nil)
+    variables = {
+      "owner" => GraphWeaver::Coerce.variable("owner", OPERATION_NAME, owner) { |v| GraphWeaver::Coerce.string(v) },
+      "name" => GraphWeaver::Coerce.variable("name", OPERATION_NAME, name) { |v| GraphWeaver::Coerce.string(v) },
+      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v) },
+    }
+
+    from_response(dispatch(variables, client:))
+  end
+
+  sig { params(owner: String, name: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }
+  def self.execute!(owner:, name:, first:, client: nil)
+    execute(owner:, name:, first:, client:).data!
+  end
+
+  # Deserialize a raw GraphQL response into the typed envelope — the
+  # network-free half of execute, for responses fetched by any client.
+  # Takes the response hash (or anything with #to_h): {"data" => ...,
+  # "errors" => ..., "extensions" => ...} with wire-cased string keys.
+  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }
+  def self.from_response(response)
+    raw = GraphWeaver.check_envelope!(response, Result)
+    errors = (raw["errors"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) }
+    GraphWeaver::Response[Result].new(
+      data: (GraphWeaver.cast_data(Result, raw["data"], errors) if raw["data"]),
+      errors:,
+      extensions: raw["extensions"] || {},
+    )
+  end
+
+  # from_response + data! — the typed result, or a raised QueryError.
+  sig { params(response: T.untyped).returns(Result) }
+  def self.from_response!(response)
+    from_response(response).data!
+  end
+end

data/examples/github/generated/starred_query.rb

@@ -0,0 +1,151 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Generated by GraphWeaver 0.7.0 — do not edit.
+
+module StarredQuery
+  extend T::Sig
+
+  QUERY = T.let(<<~'GRAPHQL', String)
+    query StarredQuery($login: String!, $first: Int!) {
+      user(login: $login) {
+        starredRepositories(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+          totalCount
+          nodes {
+            nameWithOwner
+            stargazerCount
+          }
+        }
+      }
+    }
+  GRAPHQL
+
+  # sent as the request's operationName — what an APM keys traces on
+  OPERATION_NAME = T.let("StarredQuery", T.nilable(String))
+
+  class Result < T::Struct
+    extend T::Sig
+    include GraphWeaver::Hints
+    include GraphWeaver::ResultStruct
+
+    class User < T::Struct
+      extend T::Sig
+      include GraphWeaver::Hints
+      include GraphWeaver::ResultStruct
+
+      class StarredRepositories < T::Struct
+        extend T::Sig
+        include GraphWeaver::Hints
+        include GraphWeaver::ResultStruct
+
+        class Nodes < T::Struct
+          extend T::Sig
+          include GraphWeaver::Hints
+          include GraphWeaver::ResultStruct
+
+          const :name_with_owner, String
+          const :stargazer_count, Integer
+
+          sig { params(data: T::Hash[String, T.untyped]).returns(Nodes) }
+          def self.from_h(data)
+            new(
+              name_with_owner: data.fetch("nameWithOwner"),
+              stargazer_count: data.fetch("stargazerCount"),
+            )
+          rescue GraphWeaver::Error
+            raise # already branded by a nested struct or leaf — keep the innermost context
+          rescue StandardError => e
+            raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+          end
+        end
+
+        const :total_count, Integer
+        const :nodes, T.nilable(T::Array[T.nilable(Nodes)])
+
+        sig { params(data: T::Hash[String, T.untyped]).returns(StarredRepositories) }
+        def self.from_h(data)
+          new(
+            total_count: data.fetch("totalCount"),
+            nodes: data["nodes"]&.then { |v1| v1.map { |v2| v2&.then { |v3| Nodes.from_h(v3) } } },
+          )
+        rescue GraphWeaver::Error
+          raise # already branded by a nested struct or leaf — keep the innermost context
+        rescue StandardError => e
+          raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+        end
+      end
+
+      const :starred_repositories, StarredRepositories
+
+      sig { params(data: T::Hash[String, T.untyped]).returns(User) }
+      def self.from_h(data)
+        new(
+          starred_repositories: StarredRepositories.from_h(data.fetch("starredRepositories")),
+        )
+      rescue GraphWeaver::Error
+        raise # already branded by a nested struct or leaf — keep the innermost context
+      rescue StandardError => e
+        raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+      end
+    end
+
+    const :user, T.nilable(User)
+
+    sig { params(data: T::Hash[String, T.untyped]).returns(Result) }
+    def self.from_h(data)
+      new(
+        user: data["user"]&.then { |v1| User.from_h(v1) },
+      )
+    rescue GraphWeaver::Error
+      raise # already branded by a nested struct or leaf — keep the innermost context
+    rescue StandardError => e
+      raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
+    end
+  end
+
+  # client / client= — see GraphWeaver::QueryModule
+  extend GraphWeaver::QueryModule
+
+  # the graph this module was generated from — what a test mode builds
+  # its stand-in client from
+  GRAPH = T.let(:github, Symbol)
+  private_constant :GRAPH
+
+  # .checked(:never): an untyped value (a Rails param) reaches the coercion
+  # below instead of being rejected by sorbet-runtime's argument check.
+  sig { params(login: String, first: Integer, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
+  def self.execute(login:, first:, client: nil)
+    variables = {
+      "login" => GraphWeaver::Coerce.variable("login", OPERATION_NAME, login) { |v| GraphWeaver::Coerce.string(v) },
+      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v) },
+    }
+
+    from_response(dispatch(variables, client:))
+  end
+
+  sig { params(login: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }
+  def self.execute!(login:, first:, client: nil)
+    execute(login:, first:, client:).data!
+  end
+
+  # Deserialize a raw GraphQL response into the typed envelope — the
+  # network-free half of execute, for responses fetched by any client.
+  # Takes the response hash (or anything with #to_h): {"data" => ...,
+  # "errors" => ..., "extensions" => ...} with wire-cased string keys.
+  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }
+  def self.from_response(response)
+    raw = GraphWeaver.check_envelope!(response, Result)
+    errors = (raw["errors"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) }
+    GraphWeaver::Response[Result].new(
+      data: (GraphWeaver.cast_data(Result, raw["data"], errors) if raw["data"]),
+      errors:,
+      extensions: raw["extensions"] || {},
+    )
+  end
+
+  # from_response + data! — the typed result, or a raised QueryError.
+  sig { params(response: T.untyped).returns(Result) }
+  def self.from_response!(response)
+    from_response(response).data!
+  end
+end

data/examples/github/queries/star.graphql

@@ -0,0 +1,8 @@
+mutation($id: ID!) {
+  addStar(input: { starrableId: $id }) {
+    starrable {
+      stargazerCount
+      viewerHasStarred
+    }
+  }
+}