🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

graphql-sock

Package Overview
Dependencies
Maintainers
1
Versions
7
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

graphql-sock

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.

1.0.1
latest
Source
npm
Version published
Weekly downloads
297K
-28.75%
Maintainers
1
Weekly downloads
 
Created
Source

GraphQL SOCK

SOCK: Semantic Output Conversion Kit - converting semantic-nullability schemas into traditional schemas to support existing tooling (e.g. codegen).

What is it?

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).

Semantic nullability

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, then semantic-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 the GraphQLSemanticNonNull wrapper type (if your version of GraphQL.js supports it, otherwise it will degrade gracefully to only supporting the directive).

@semanticNonNull directive

For the directive, the two conversions work like this:

ModeInput typeOutput type
semantic-to-nullableInt @semanticNonNullInt
semantic-to-strictInt @semanticNonNullInt!
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.

GraphQLSemanticNonNull wrapper type

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:

ModeInput typeOutput type
semantic-to-nullableInt*Int
semantic-to-strictInt*Int!
semantic-to-nullable[Int*][Int]
semantic-to-strict[Int*][Int!]
semantic-to-nullable[Int*]*[Int]
semantic-to-strict[Int*]*[Int!]!

Installation

You must install both graphql-sock and graphql; pick the line that relates to your package manager:

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

Usage

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):

Input schema

directive @semanticNonNull(levels: [Int!]! = [0]) on FIELD_DEFINITION

type Query {
  someList: [Int] @semanticNonNull(levels: [0, 1])
  someOtherList: [String*]*
}

Semantic to nullable

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:

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:

import { semanticToNullable } from "graphql-sock";
import { sourceSchema as inputSchema } from "./my-schema";

export const outputSchema = semanticToNullable(inputSchema);

Semantic to strict

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:

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:

import { semanticToStrict } from "graphql-sock";
import { schema as sourceSchema } from "./my-schema";

export const schema = semanticToStrict(sourceSchema);

Advanced usage

If you just want to convert a single GraphQLFieldConfig you can use the convertFieldConfig method, passing the field config and true to convert semantic non-null positions to strict non-nulls, or false if you want to convert to nullable:

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.

Keywords

graphql

FAQs

Package last updated on 27 Mar 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts