{"id":16297500,"url":"https://github.com/graphile/graphql-sock","last_synced_at":"2025-04-10T23:43:26.661Z","repository":{"id":257820990,"uuid":"860453919","full_name":"graphile/graphql-sock","owner":"graphile","description":"GraphQL Semantic Output Conversion Kit","archived":false,"fork":false,"pushed_at":"2025-03-27T12:57:12.000Z","size":89,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T23:43:19.482Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-20T13:16:24.000Z","updated_at":"2025-04-06T13:20:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"a26b019d-f8d4-4f62-b793-6a69081bb81b","html_url":"https://github.com/graphile/graphql-sock","commit_stats":null,"previous_names":["graphile/graphql-sock"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fgraphql-sock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fgraphql-sock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fgraphql-sock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fgraphql-sock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphile","download_url":"https://codeload.github.com/graphile/graphql-sock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248317726,"owners_count":21083527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T20:27:53.111Z","updated_at":"2025-04-10T23:43:26.653Z","avatar_url":"https://github.com/graphile.png","language":"TypeScript","funding_links":[],"categories":["Standalone Tools"],"sub_categories":[],"readme":"# GraphQL SOCK\n\nSOCK: **Semantic Output Conversion Kit** - converting semantic-nullability\nschemas into traditional schemas to support existing tooling (e.g. codegen).\n\n## What is it?\n\n**Takes as input a GraphQL SDL and outputs a derived SDL wherein all\nsemantic-non-null type modifiers have either been removed (semantic to nullable)\nor have been replaced with strict (traditional) non-null modifiers (semantic to\nstrict).**\n\n### Semantic nullability\n\nIn the latest proposals around semantic nullability, we introduce a new\n\"Semantic Non Null\" type modifier that means that the value is \"null only on\nerror\" (i.e. it will never be `null` unless an error has occurred). However, not\nall tools support this yet, so this library contains tools to convert a schema\nor SDL that supports semantic nullability into a more traditional one, to be\nused for code generation and other such functionality.\n\nWhich command you use will depend on your setup; if you're using a client that\nprevents you from reading error nulls (e.g. by throwing when you read from an\nerrored field like [`graphql-toe`](https://github.com/graphile/graphql-toe)\ndoes, or otherwise) then you'll want `semantic-to-strict` to really capitalize\non the benefits of semantic nullability.\n\nIf you just want to use a semantic nullability SDL with traditional tools and\nclients that don't yet understand semantic nullability, then\n`semantic-to-nullable` will just strip out the semantic-non-null types for you.\n\nThis library supports both the `@semanticNonNull` directive (which should work\nuniversally, but is likely to be a temporary placeholder), and the\n`GraphQLSemanticNonNull` wrapper type (if your version of GraphQL.js supports\nit, otherwise it will degrade gracefully to only supporting the directive).\n\n### `@semanticNonNull` directive\n\nFor the directive, the two conversions work like this:\n\n| Mode                 | Input type                              | Output type |\n| -------------------- | --------------------------------------- | ----------- |\n| semantic-to-nullable | `Int @semanticNonNull`                  | `Int`       |\n| semantic-to-strict   | `Int @semanticNonNull`                  | `Int!`      |\n| semantic-to-nullable | `[Int] @semanticNonNull(levels: [1])`   | `[Int]`     |\n| semantic-to-strict   | `[Int] @semanticNonNull(levels: [1])`   | `[Int!]`    |\n| semantic-to-nullable | `[Int] @semanticNonNull(levels: [0,1])` | `[Int]`     |\n| semantic-to-strict   | `[Int] @semanticNonNull(levels: [0,1])` | `[Int!]!`   |\n\n\u003e [!NOTE]\n\u003e\n\u003e An existing strictly non-nullable type (`Int!`) will remain unchanged whether\n\u003e or not `@semanticNonNull` applies to that level.\n\n### `GraphQLSemanticNonNull` wrapper type\n\nHow the `GraphQLSemanticNonNull` type is represented syntactically in SDL is yet\nto be determined by the working group, but this library doesn't care about that\nsince it uses the schema directly. For the sake of this README we'll use the\noriginally proposed\n[asterisk syntax](https://github.com/graphql/graphql-spec/pull/1065).\n\nThe above examples using asterisk syntax would be:\n\n| Mode                 | Input type | Output type |\n| -------------------- | ---------- | ----------- |\n| semantic-to-nullable | `Int*`     | `Int`       |\n| semantic-to-strict   | `Int*`     | `Int!`      |\n| semantic-to-nullable | `[Int*]`   | `[Int]`     |\n| semantic-to-strict   | `[Int*]`   | `[Int!]`    |\n| semantic-to-nullable | `[Int*]*`  | `[Int]`     |\n| semantic-to-strict   | `[Int*]*`  | `[Int!]!`   |\n\n## Installation\n\nYou must install both `graphql-sock` and `graphql`; pick the line that relates\nto your package manager:\n\n```bash\nnpm install --save graphql-sock graphql\nyarn add graphql-sock graphql\npnpm install --save graphql-sock graphql\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e To support the `*` syntax, install `graphql@canary-pr-4192`\n\n## Usage\n\nConsider this \"input schema\" which uses both the `@semanticNonNull` directive\nand the `*` syntax (for syntax support, you will need to be running a\n[compatible version of graphql.js](https://github.com/graphql/graphql-js/pull/4192#issuecomment-2351103549)):\n\n### Input schema\n\n```graphql\ndirective @semanticNonNull(levels: [Int!]! = [0]) on FIELD_DEFINITION\n\ntype Query {\n  someList: [Int] @semanticNonNull(levels: [0, 1])\n  someOtherList: [String*]*\n}\n```\n\n### Semantic to nullable\n\n**If a value is \"null only on error\" then it _can_ be null.**\n\nThis conversion strips all semantic-non-null type wrappers from the SDL, making\na schema that appears as it traditionally would. This means that you won't reap\nany of the benefits of semantic nullability, but you can support existing tools\nand clients without needing to update their code.\n\n#### Output schema\n\nThe input schema would have all the semantic non-null types removed:\n\n```graphql\ntype Query {\n  someList: [Int]\n  someOtherList: [String]\n}\n```\n\n#### CLI\n\nFrom the CLI, use the `semantic-to-nullable` command to convert an SDL with\nsemantic nullability into an SDL without semantic nullability, where all\nsemantic non-null positions have been removed:\n\n```\nsemantic-to-nullable -i input.graphql -o output.graphql\n```\n\n#### Library\n\nUse the `semanticToNullable` export to create a copy of a schema with all the\nsemantic non-null types removed:\n\n```ts\nimport { semanticToNullable } from \"graphql-sock\";\nimport { sourceSchema as inputSchema } from \"./my-schema\";\n\nexport const outputSchema = semanticToNullable(inputSchema);\n```\n\n### Semantic to strict\n\n**Error handling clients prevent users from reading \"error-nulls\" (e.g. by\nthrowing an error), so semantically non-nullable positions are non-nullable for\nthese clients.**\n\nIf you're using \"Throw On Error\" (e.g. via\n[graphql-toe](https://github.com/graphile/graphql-toe)) or a similar technique\nthen when you read from an errored field an error will be thrown, preventing you\nfrom reading the underlying `null`.\n\n**Think of semantically non-null fields as \"null only on error;\" if you throw on\nerrors, then they're never null!**\n\nAs such, this position becomes equivalent to a traditional non-null for you, so\nthis conversion converts all semantic-non-null type wrappers into traditional\n(strict) non-null wrappers. Your type generators can therefore generate fewer\nnullables, and your frontend engineers have to do fewer null checks and are\ntherefore happier.\n\n#### Output schema\n\nThe input schema would become:\n\n```graphql\ntype Query {\n  someList: [Int!]!\n  someOtherList: [String!]!\n}\n```\n\n#### CLI\n\nFrom the CLI, use the `semantic-to-strict` command to convert an SDL with\nsemantic nullability into an SDL without semantic nullability, where all\nsemantic non-null positions have become strictly non-null:\n\n```\nsemantic-to-strict -i input.graphql -o output.graphql\n```\n\n#### Library\n\nUse the `semanticToStrict` export to create a copy of a schema with all the\nsemantic non-null types replaced with strict (traditional) non-null types:\n\n```ts\nimport { semanticToStrict } from \"graphql-sock\";\nimport { schema as sourceSchema } from \"./my-schema\";\n\nexport const schema = semanticToStrict(sourceSchema);\n```\n\n## Advanced usage\n\nIf you just want to convert a single `GraphQLFieldConfig` you can use the\n`convertFieldConfig` method, passing the field config and `true` to convert\nsemantic non-null positions to strict non-nulls, or `false` if you want to\nconvert to nullable:\n\n```ts\nconst strictFieldConfig = convertFieldConfig(fieldConfig, true);\nconst nullableFieldConfig = convertFieldConfig(fieldConfig, false);\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e This method assumes that the fieldConfig has come from parsing an SDL string,\n\u003e and thus has an `astNode` that includes a `@semanticNonNull` directive.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile%2Fgraphql-sock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphile%2Fgraphql-sock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile%2Fgraphql-sock/lists"}