From 6709c1e27910b2d6daec6b21af9c78f265023ba4 Mon Sep 17 00:00:00 2001 From: Ben Kraft Date: Thu, 9 Sep 2021 16:11:19 -0700 Subject: [PATCH] Add documentation for the 32-bit issue This is something that came up at Khan; we decided that just binding to `int` is actually the right thing, but there are other options. Fixes #39. --- docs/FAQ.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index f170fb5d..4b1703c8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -66,6 +66,24 @@ if errors.As(err, &errList) { } ``` +### … require 32-bit integers? + +The GraphQL spec officially defines the `Int` type to be a [signed 32-bit integer](https://spec.graphql.org/draft/#sec-Int). GraphQL clients and servers vary wildly in their enforcement of this; for example: +- [Apollo Server](https://github.com/apollographql/apollo-server/) explicitly checks that integers are at most 32 bits +- [gqlgen](https://github.com/99designs/gqlgen) by default allows any integer that fits in `int` (i.e. 64 bits on most platforms) +- [Apollo Client](https://github.com/apollographql/apollo-client) doesn't check (but implicitly is limited to 53 bits by JavaScript) +- [shurcooL/graphql](https://github.com/shurcooL/graphql) requires integers be passed as a `graphql.Int`, defined to be an `int32` + +By default, genqlient maps GraphQL `Int`s to Go's `int`, meaning that on 64 bit systems there's no client-side restriction. If you prefer to limit integers to `int32`, you can set a binding in your `genqlient.yaml`: + +```yaml +bindings: + Int: + type: int32 +``` + +Or, you can bind it to any other type, perhaps one with size-checked constructors; see the [`genqlient.yaml` documentation](`genqlient.yaml`) for more details. + ## How do I make a query with … ### … a specific name for a field?