feat(core): support HTTP QUERY requests

[JoviDeCroock]

Summary

• add an opt-in preferQueryMethod client and operation-context option
• send JSON query operations as body-bearing HTTP QUERY requests
• keep mutations, subscriptions, and multipart requests on POST
• make QUERY take precedence over the existing preferGetMethod behavior
• document server, CORS, infrastructure, and browser-cache constraints

Motivation

RFC 10008 defines QUERY as a safe, idempotent, body-bearing HTTP method. This maps well to GraphQL query operations without the URL-length constraints of GET.

GraphQL over HTTP is discussing the mapping in graphql/graphql-over-http#411. This PR is intentionally a draft while that proposal and ecosystem support settle.

Behavior

createClient({
  url: '/graphql',
  exchanges: [cacheExchange, fetchExchange],
  preferQueryMethod: true,
});

When enabled, JSON query operations use uppercase QUERY with the same serialized JSON body used by POST. Mutations and subscriptions remain POST. Multipart/file-bearing queries also remain POST rather than introducing multipart QUERY behavior.

The option takes precedence over preferGetMethod, including its default 'within-url-limit' value. It does not add automatic fallback on 405/501; opted-in deployments should expose unsupported server or intermediary configuration.

Browser and infrastructure constraints

• cross-origin requests require CORS to allow QUERY
• servers, gateways, CDNs, and WAFs must recognize the method
• browser HTTP caches may not cache QUERY responses yet

Tests

• full monorepo suite: 620 passed, 2 skipped
• TypeScript check passed
• ESLint passed
• @urql/core build passed
• Prettier and git diff --check passed

[changeset-bot]

🦋 Changeset detected

Latest commit: 917ee01

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@urql/core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cloudflare-workers-and-pages]

Deploying urql with    Cloudflare Pages

Latest commit:	917ee01
Status:	✅  Deploy successful!
Preview URL:	https://f66ee783.urql.pages.dev
Branch Preview URL:	https://feat-http-query-method.urql.pages.dev

View logs