{"id":23391449,"url":"https://github.com/ahrefs/graphql-ppx-0.7.1-patched","last_synced_at":"2026-02-07T00:01:42.948Z","repository":{"id":68068963,"uuid":"547142976","full_name":"ahrefs/graphql-ppx-0.7.1-patched","owner":"ahrefs","description":null,"archived":false,"fork":false,"pushed_at":"2022-10-07T11:08:44.000Z","size":54844,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"0.7.1-ahrefs","last_synced_at":"2025-12-01T08:22:31.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Reason","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahrefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2022-10-07T07:46:25.000Z","updated_at":"2022-10-07T07:47:01.000Z","dependencies_parsed_at":"2023-07-08T12:30:11.288Z","dependency_job_id":null,"html_url":"https://github.com/ahrefs/graphql-ppx-0.7.1-patched","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ahrefs/graphql-ppx-0.7.1-patched","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fgraphql-ppx-0.7.1-patched","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fgraphql-ppx-0.7.1-patched/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fgraphql-ppx-0.7.1-patched/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fgraphql-ppx-0.7.1-patched/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahrefs","download_url":"https://codeload.github.com/ahrefs/graphql-ppx-0.7.1-patched/tar.gz/refs/heads/0.7.1-ahrefs","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fgraphql-ppx-0.7.1-patched/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29181265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T23:15:33.022Z","status":"ssl_error","status_checked_at":"2026-02-06T23:15:09.128Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-12-22T04:17:28.964Z","updated_at":"2026-02-07T00:01:42.942Z","avatar_url":"https://github.com/ahrefs.png","language":"Reason","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql_ppx\n\n[![npm version](https://badge.fury.io/js/%40baransu%2Fgraphql_ppx_re.svg)](https://badge.fury.io/js/%40baransu%2Fgraphql_ppx_re)\n\n\u003e Reason/OCaml PPX (PreProcessor eXtension) helping with creating type-safe, compile time validated GraphQL queries generating response decoders.\n\nThis project builds upon [mhallin/graphql_ppx](https://github.com/mhallin/graphql_ppx). It wouldn't be possible without great work of [mhallin/graphql_ppx contributors](https://github.com/mhallin/graphql_ppx/graphs/contributors).\n\n# Installation\n\nFirst, add it to you dependencies using `npm` or `yarn`:\n\n```sh\nyarn add @baransu/graphql_ppx_re --dev\n# or\nnpm install @baransu/graphql_ppx_re  --saveDev\n```\n\nSecond, add it to `ppx-flags` in your `bsconfig.json`:\n\n```json\n\"ppx-flags\": [\"@baransu/graphql_ppx_re/ppx\"]\n```\n\n## Native\n\nIf you want to use native version edit your `esy.json` file\n\n```json\n{\n  \"dependencies\": {\n    \"graphql_ppx\": \"*\"\n  },\n  \"resolutions\": {\n    \"graphql_ppx\": \"reasonml-community/graphql_ppx:esy.json#\u003cuse latest stable commit from master\u003e\"\n  }\n}\n```\n\nand update your `dune` file:\n\n```\n(preprocess (pps graphql_ppx))\n```\n\n# Usage\n\nThis plugin requires a `graphql_schema.json` file to exist somewhere in the\nproject hierarchy, containing the result of sending an [introspection\nquery](https://github.com/graphql/graphql-js/blob/master/src/utilities/introspectionQuery.js)\nto your backend. The easiest way to do this is by using `get-graphql-schema`:\n\n```sh\nnpx get-graphql-schema ENDPOINT_URL -j \u003e graphql_schema.json\n```\n\n## Ignore `.graphql_ppx_cache` in your version control\n\n`graphql_ppx` will generate a `.graphql_ppx_cache` folder alongside your JSON\nschema to optimize parsing performance. If you're\nusing a version control system, you don't need to check it in.\n\n# Limitations\n\nWhile `graphql_ppx` covers a large portion of the GraphQL spec, there are still\nsome unsupported areas:\n\n- Not all GraphQL validations are implemented. It will _not_ validate argument\n  types and do other sanity-checking of the queries. The fact that a query\n  compiles does not mean that it will pass server-side validation.\n- Fragment support is limited and not 100% safe - because `graphql_ppx` only can\n  perform local reasoning on queries, you can construct queries with fragments\n  that are invalid.\n\n# Features\n\n- Objects are converted into `Js.t` objects\n- Enums are converted into [polymorphic\n  variants](https://2ality.com/2018/01/polymorphic-variants-reasonml.html)\n- Floats, ints, strings, booleans, id are converted into their corresponding native\n  Reason/OCaml types.\n- Custom scalars are parsed as `Js.Json.t`\n- Arguments with input objects\n- Using `@skip` and `@include` will force non-optional fields to become\n  optional.\n- Unions are converted to polymorphic variants, with exhaustiveness checking.\n  This only works for object types, not for unions containing interfaces.\n- Interfaces are also converted into polymorphic variants. Overlapping interface\n  selections and other more uncommon use cases are not yet supported.\n- Basic fragment support\n- Required arguments validation - you're not going to miss required arguments on any field.\n\n# Extra features\n\nBy using some directives prefixed `bs`, `graphql_ppx` lets you modify how the\nresult of a query is parsed. All these directives will be removed from the query\nat compile time, so your server doesn't have to support them.\n\n### Record conversion\n\nWhile `Js.t` objects often have their advantages, they also come with some\nlimitations. For example, you can't create new objects using the spread (`...`)\nsyntax or pattern match on their contents. Since they are not named, they also\nresult in quite large type error messages when there are mismatches.\n\nReason/OCaml records, on the other hand, can be pattern matched, created using the\nspread syntax, and give nicer error messages when they mismatch. `graphql_ppx`\ngives you the option to decode a field as a record using the `@bsRecord`\ndirective:\n\n```reason\ntype hero = {\n  name: string,\n  height: number,\n  mass: number\n};\n\nmodule HeroQuery = [%graphql {|\n{\n  hero @bsRecord {\n    name\n    height\n    mass\n  }\n}\n|}];\n```\n\nNote that the record has to already exist and be in scope for this to work.\n`graphql_ppx` will not _create_ the record. Even though this involves some\nduplication of both names and types, type errors will be generated if there are\nany mismatches.\n\n### Custom field decoders\n\nIf you've got a custom scalar, or just want to convert e.g. an integer to a\nstring to properly fit a record type (see above), you can use the `@bsDecoder`\ndirective to insert a custom function in the decoder:\n\n```reason\nmodule HeroQuery = [%graphql {|\n{\n  hero {\n    name\n    height @bsDecoder(fn: \"string_of_float\")\n    mass\n  }\n}\n|}];\n```\n\nIn this example, `height` will be converted from a float to a string in the\nresult. Using the `fn` argument, you can specify any function literal you want.\n\n### Non-union variant conversion\n\nIf you've got an object which in practice behaves like a variant - like `signUp`\nabove, where you _either_ get a user _or_ a list of errors - you can add a\n`@bsVariant` directive to the field to turn it into a polymorphic variant:\n\n```reason\nmodule SignUpQuery = [%graphql\n  {|\nmutation($name: String!, $email: String!, $password: String!) {\n  signUp(email: $email, email: $email, password: $password) @bsVariant {\n    user {\n      name\n    }\n\n    errors {\n      field\n      message\n    }\n  }\n}\n|}\n];\n\nlet _ =\n  SignUpQuery.make(\n    ~name=\"My name\",\n    ~email=\"email@example.com\",\n    ~password=\"secret\",\n    (),\n  )\n  |\u003e Api.sendQuery\n  |\u003e Promise.then_(response =\u003e\n       (\n         switch (response##signUp) {\n         | `User(user) =\u003e Js.log2(\"Signed up a user with name \", user##name)\n         | `Errors(errors) =\u003e Js.log2(\"Errors when signing up: \", errors)\n         }\n       )\n       |\u003e Promise.resolve\n     );\n\n```\n\nThis helps with the fairly common pattern for mutations that can fail with\nuser-readable errors.\n\n### Alternative `Query.make` syntax\n\nWhen you define a query with variables, the `make` function will take\ncorresponding labelled arguments. This is convenient when constructing and\nsending the queries yourself, but might be problematic when trying to abstract\nover multiple queries.\n\nFor this reason, another function called `makeWithVariables` is _also_\ngenerated. This function takes a single `Js.t` object containing all variables.\n\n```reason\nmodule MyQuery = [%graphql\n  {|\n  mutation ($username: String!, $password: String!) {\n    ...\n  }\n|}\n];\n\n/* You can either use `make` with labelled arguments: */\nlet query = MyQuery.make(~username=\"testUser\", password = \"supersecret\", ());\n\n/* Or, you can use `makeWithVariables`: */\nlet query =\n  MyQuery.makeWithVariables({\n    \"username\": \"testUser\",\n    \"password\": \"supersecret\",\n  });\n```\n\n### Getting the type of the parsed value\n\nIf you want to get the type of the parsed and decoded value - useful in places\nwhere you can't use Reason/OCaml's type inference - use the `t` type of the query\nmodule:\n\n```reason\nmodule MyQuery = [%graphql {| { hero { name height }} |}];\n\n/* This is something like Js.t({ . hero: Js.t({ name: string, weight: float }) }) */\ntype resultType = MyQuery.t;\n```\n\n# Troubleshooting\n\n### \"Type ... doesn't have any fields\"\n\nSometimes when working with union types you'll get the following error.\n\n```\nFatal error: exception Graphql_ppx_base__Schema.Invalid_type(\"Type IssueTimelineItems doesn't have any fields\")\n```\n\nThis is an example of a query that will result in such error:\n\n```graphql\nnodes {\n  __typename\n  ... on ClosedEvent {\n    closer {\n      __typename\n      ... on PullRequest {\n        id\n        milestone { id }\n      }\n    }\n  }\n}\n```\n\nThis is because we allow querying union fields only in certain cases. GraphQL provides the `__typename` field but it's not present in GraphQL introspection query thus `graphql_ppx` doesn't know that this field exists.\nTo fix your query simply remove `__typename`. It's added behinds a scene as an implementation detail and serves us as a way to decide which case to select when parsing your query result.\n\nThis is an example of a correct query:\n\n```graphql\nnodes {\n  ... on ClosedEvent {\n    closer {\n      ... on PullRequest {\n        id\n        milestone { id }\n      }\n    }\n  }\n}\n```\n\n# Configuration\n\nIf you need to customize certain features of `graphql_ppx` you can provide ppx arguments to do so:\n\n### -apollo-mode\n\nBy default `graphql_ppx` adds `__typename` only to fields on which we need those informations (Unions and Interfaces). If you want to add `__typename` on every object in a query you can specify it by using `-apollo-mode` in `ppx-flags`. It's usefull in case of using `apollo-client` because of it's cache.\n\n```json\n\"ppx-flags\": [\n  [\"@baransu/graphql_ppx_re/ppx\", \"-apollo-mode\",]\n],\n```\n\n### -schema\n\nBy default `graphql_ppx` uses `graphql_schema.json` file from your root directory. You can override it by providing `-schema` argument in `ppx-flags` to overriding it.\n\n```json\n\"ppx-flags\": [\n  [\"@baransu/graphql_ppx_re/ppx\", \"-schema ../graphql_schema.json\"]\n],\n```\n\n# Query specific configuration\n\nIf you want to use multiple schemas in your project it can be provided as a secondary config argument in your graphql ppx definition.\n\n```reason\nmodule MyQuery = [%graphql\n  {|\n    query pokemon($id: String, $name: String) {\n      pokemon(name: $name, id: $id) {\n        id\n        name\n      }\n    }\n  |};\n  {schema: \"pokedex_schema.json\"}\n];\n```\n\nThis will use the `pokedex_schema.json` instead of using the default `graphql_schema.json` file.\n\nThis opens up the possibility to use multiple different GraphQL APIs in the same project.\n\n**Note** the path to your file is based on where you run `bsb`. In this case `pokedex_schema.json` is a sibling to `node_modules`.\n\n# Supported platforms\n\n`graphql_ppx` somes with prebuild binaries for `linux-x64`, `darwin-x64` and `win-x64`. If you need support for other platform, please open an issue.\n\n# Contributing\n\n## Developing\n\n```\nnpm install -g esy@latest\nesy install\nesy build\n```\n\n## Running tests\n\n### BuckleScript\n\n```\ncd tests_bucklescript\nnpm test\n```\n\n### Native\n\nFor native run:\n\n```\nesy dune runtest -f\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahrefs%2Fgraphql-ppx-0.7.1-patched","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahrefs%2Fgraphql-ppx-0.7.1-patched","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahrefs%2Fgraphql-ppx-0.7.1-patched/lists"}