GraphQL Semantic Output Conversion Kit - converts a cutting edge SDL file that supports semantic nullability into a more traditional SDL file legacy tools can support.
npm install graphql-sockSOCK: Semantic Output Conversion Kit - converting semantic-nullability
schemas into traditional schemas to support existing tooling (e.g. codegen).
**Takes as input a GraphQL SDL and outputs a derived SDL wherein all
semantic-non-null type modifiers have either been removed (semantic to nullable)
or have been replaced with strict (traditional) non-null modifiers (semantic to
strict).**
In the latest proposals around semantic nullability, we introduce a new
"Semantic Non Null" type modifier that means that the value is "null only on
error" (i.e. it will never be null unless an error has occurred). However, not
all tools support this yet, so this library contains tools to convert a schema
or SDL that supports semantic nullability into a more traditional one, to be
used for code generation and other such functionality.
Which command you use will depend on your setup; if you're using a client that
prevents you from reading error nulls (e.g. by throwing when you read from an
errored field like graphql-toe
does, or otherwise) then you'll want semantic-to-strict to really capitalize
on the benefits of semantic nullability.
If you just want to use a semantic nullability SDL with traditional tools and
clients that don't yet understand semantic nullability, thensemantic-to-nullable will just strip out the semantic-non-null types for you.
This library supports both the @semanticNonNull directive (which should work
universally, but is likely to be a temporary placeholder), and theGraphQLSemanticNonNull wrapper type (if your version of GraphQL.js supports
it, otherwise it will degrade gracefully to only supporting the directive).
For the directive, the two conversions work like this:
| Mode | Input type | Output type |
| -------------------- | --------------------------------------- | ----------- |
| semantic-to-nullable | Int @semanticNonNull | Int |
| semantic-to-strict | Int @semanticNonNull | Int! |
| semantic-to-nullable | [Int] @semanticNonNull(levels: [1]) | [Int] |
| semantic-to-strict | [Int] @semanticNonNull(levels: [1]) | [Int!] |
| semantic-to-nullable | [Int] @semanticNonNull(levels: [0,1]) | [Int] |
| semantic-to-strict | [Int] @semanticNonNull(levels: [0,1]) | [Int!]! |
> [!NOTE]
>
> An existing strictly non-nullable type (Int!) will remain unchanged whether
> or not @semanticNonNull applies to that level.
How the GraphQLSemanticNonNull type is represented syntactically in SDL is yet
to be determined by the working group, but this library doesn't care about that
since it uses the schema directly. For the sake of this README we'll use the
originally proposed
asterisk syntax.
The above examples using asterisk syntax would be:
| Mode | Input type | Output type |
| -------------------- | ---------- | ----------- |
| semantic-to-nullable | Int* | Int |
| semantic-to-strict | Int* | Int! |
| semantic-to-nullable | [Int*] | [Int] |
| semantic-to-strict | [Int*] | [Int!] |
| semantic-to-nullable | [Int] | [Int] |
| semantic-to-strict | [Int] | [Int!]! |
You must install both graphql-sock and graphql; pick the line that relates
to your package manager:
``bash`
npm install --save graphql-sock graphql
yarn add graphql-sock graphql
pnpm install --save graphql-sock graphql
> [!NOTE]
>
> To support the * syntax, install graphql@canary-pr-4192
Consider this "input schema" which uses both the @semanticNonNull directive*
and the syntax (for syntax support, you will need to be running a
compatible version of graphql.js):
`graphql
directive @semanticNonNull(levels: [Int!]! = [0]) on FIELD_DEFINITION
type Query {
someList: [Int] @semanticNonNull(levels: [0, 1])
someOtherList: [String]
}
`
If a value is "null only on error" then it _can_ be null.
This conversion strips all semantic-non-null type wrappers from the SDL, making
a schema that appears as it traditionally would. This means that you won't reap
any of the benefits of semantic nullability, but you can support existing tools
and clients without needing to update their code.
#### Output schema
The input schema would have all the semantic non-null types removed:
`graphql`
type Query {
someList: [Int]
someOtherList: [String]
}
#### CLI
From the CLI, use the semantic-to-nullable command to convert an SDL with
semantic nullability into an SDL without semantic nullability, where all
semantic non-null positions have been removed:
`
semantic-to-nullable -i input.graphql -o output.graphql
#### Library
Use the semanticToNullable export to create a copy of a schema with all the
semantic non-null types removed:
`ts
import { semanticToNullable } from "graphql-sock";
import { sourceSchema as inputSchema } from "./my-schema";
export const outputSchema = semanticToNullable(inputSchema);
`
**Error handling clients prevent users from reading "error-nulls" (e.g. by
throwing an error), so semantically non-nullable positions are non-nullable for
these clients.**
If you're using "Throw On Error" (e.g. via
graphql-toe) or a similar technique
then when you read from an errored field an error will be thrown, preventing you
from reading the underlying null.
**Think of semantically non-null fields as "null only on error;" if you throw on
errors, then they're never null!**
As such, this position becomes equivalent to a traditional non-null for you, so
this conversion converts all semantic-non-null type wrappers into traditional
(strict) non-null wrappers. Your type generators can therefore generate fewer
nullables, and your frontend engineers have to do fewer null checks and are
therefore happier.
#### Output schema
The input schema would become:
`graphql`
type Query {
someList: [Int!]!
someOtherList: [String!]!
}
#### CLI
From the CLI, use the semantic-to-strict command to convert an SDL with
semantic nullability into an SDL without semantic nullability, where all
semantic non-null positions have become strictly non-null:
`
semantic-to-strict -i input.graphql -o output.graphql
#### Library
Use the semanticToStrict export to create a copy of a schema with all the
semantic non-null types replaced with strict (traditional) non-null types:
`ts
import { semanticToStrict } from "graphql-sock";
import { schema as sourceSchema } from "./my-schema";
export const schema = semanticToStrict(sourceSchema);
`
If you just want to convert a single GraphQLFieldConfig you can use theconvertFieldConfig method, passing the field config and true to convertfalse
semantic non-null positions to strict non-nulls, or if you want to
convert to nullable:
`ts`
const strictFieldConfig = convertFieldConfig(fieldConfig, true);
const nullableFieldConfig = convertFieldConfig(fieldConfig, false);
> [!NOTE]
>
> This method assumes that the fieldConfig has come from parsing an SDL string,
> and thus has an astNode that includes a @semanticNonNull` directive.