{"id":14975974,"url":"https://github.com/jamesmacaulay/elm-graphql","last_synced_at":"2025-10-05T17:20:25.355Z","repository":{"id":54443492,"uuid":"71903222","full_name":"jamesmacaulay/elm-graphql","owner":"jamesmacaulay","description":"A GraphQL library for Elm","archived":false,"fork":false,"pushed_at":"2021-02-17T15:25:21.000Z","size":286,"stargazers_count":312,"open_issues_count":9,"forks_count":19,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-26T01:08:01.775Z","etag":null,"topics":["elm","graphql","graphql-client"],"latest_commit_sha":null,"homepage":"http://package.elm-lang.org/packages/jamesmacaulay/elm-graphql/latest","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesmacaulay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-25T14:07:26.000Z","updated_at":"2024-11-19T14:36:39.000Z","dependencies_parsed_at":"2022-08-13T15:50:32.670Z","dependency_job_id":null,"html_url":"https://github.com/jamesmacaulay/elm-graphql","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/jamesmacaulay/elm-graphql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmacaulay%2Felm-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmacaulay%2Felm-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmacaulay%2Felm-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmacaulay%2Felm-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesmacaulay","download_url":"https://codeload.github.com/jamesmacaulay/elm-graphql/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmacaulay%2Felm-graphql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486435,"owners_count":25994968,"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","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["elm","graphql","graphql-client"],"created_at":"2024-09-24T13:53:03.297Z","updated_at":"2025-10-05T17:20:25.321Z","avatar_url":"https://github.com/jamesmacaulay.png","language":"Elm","readme":"\u003cimg src=\"https://raw.githubusercontent.com/jamesmacaulay/elm-graphql/master/elm-graphql.png\" alt=\"elm-graphql logo\" width=\"40%\" align=\"right\"\u003e\n\n## jamesmacaulay/elm-graphql\n\n[![Travis-CI build status](https://api.travis-ci.org/jamesmacaulay/elm-graphql.svg)](https://travis-ci.org/jamesmacaulay/elm-graphql)\n\nA [GraphQL](http://graphql.org) library for [Elm](http://elm-lang.org), written entirely in Elm.\n\nThe goal of this package is to provide a really good interface for working directly with GraphQL queries and schemas in Elm. Right now the main offering of the package is an interface for building up nested queries and mutations in a way that also builds up a decoder capable of decoding successful responses to the request. The package also provides a module for sending these requests to a GraphQL server over HTTP and decoding the responses accordingly.\n\nThe docs can be found [here](http://package.elm-lang.org/packages/jamesmacaulay/elm-graphql/latest).\n\nAnd [here's an end-to-end example](https://github.com/jamesmacaulay/elm-graphql/blob/master/example/Main.elm) that builds a query, sends it to a server, and decodes the response.\n\n### Building requests\n\nBuilding up a GraphQL query with this package feels a lot like building a JSON decoder, especially if you are familiar with the [elm-decode-pipeline](http://package.elm-lang.org/packages/NoRedInk/elm-decode-pipeline/3.0.0) package. First you define type aliases for each of the nested record types you want to construct out of the response:\n\n\n```elm\nimport GraphQL.Request.Builder exposing (..)\nimport GraphQL.Request.Builder.Arg as Arg\nimport GraphQL.Request.Builder.Variable as Var\n\ntype alias Photo =\n    { url : String\n    , caption : String\n    }\n\ntype alias User =\n    { name : String\n    , photos : List Photo }\n```\n\nThen you build a query document:\n\n```elm\nuserQuery : Document Query User { vars | userID : String }\nuserQuery =\n    let\n        userIDVar =\n            Var.required \"userID\" .userID Var.id\n\n        photo =\n            object Photo\n                |\u003e with (field \"url\" [] string)\n                |\u003e with (field \"caption\" [] string)\n\n        user =\n            object User\n                |\u003e with (field \"name\" [] string)\n                |\u003e with (field \"photos\" [] (list photo))\n        \n        queryRoot =\n            extract\n                (field \"user\"\n                    [ ( \"id\", Arg.variable userIDVar ) ]\n                    user\n                )\n    in\n        queryDocument queryRoot\n```\n\nThe `Document` type can represent both query and mutation documents. It lets you do two important things:\n  \n  * generate GraphQL request documents to send to the server, and\n  * decode JSON responses from the server.\n\nHere's what the above Document looks like when you encode it to a string to be sent to the server:\n\n```graphql\nquery ($userID: ID!) {\n  user(id: $userID) {\n    name\n    photos {\n      url\n      caption\n    }\n  }\n}\n```\n\nTo supply values for the variables used in the `Document`, you provide an Elm value that your variables can extract values from according to the getter functions supplied when you define the variables. In this example, the `\"userID\"` variable was defined as a string that's extracted from the `userID` field of some Elm record, so the following code is a valid way to create a `Request` with the required variable values supplied:\n\n```elm\nuserQueryRequest : Request Query User\nuserQueryRequest =\n    userQuery\n        |\u003e request { userID = \"123\" }\n```\n\nAssuming you've built a query that is valid for the server's schema, sending it to the server will result in a JSON response that can be decoded with a JSON decoder that is built up automatically along with the structure of the query. Here's what a JSON response for `userQuery` might look like:\n\n```\n{\n  \"data\": {\n    \"user\": {\n      \"name\": \"Lola\",\n      \"photos\": [\n        {\n          \"url\": \"http://cdn.catphotos.com/lola.jpg\",\n          \"caption\": \"Lola curling up on the chair\"\n        }\n      ]\n    }\n  }\n}\n```\n\nWhen it is decoded with the help of the decoder contained in `userQuery`, it becomes this:\n\n```elm\n{ name = \"Lola\"\n, photos =\n    [ { url = \"http://cdn.catphotos.com/lola.jpg\"\n      , caption = \"Lola curling up on the chair\"\n      }\n    ]\n}\n```\n\nMutations are built just like queries, except that you wrap them up in a call to `mutationDocument` instead of a call to `queryDocument`. Here's an example of a mutation that logs in a user and extracts an auth token from the response:\n\n```elm\ntype alias LoginVars =\n    { username : String\n    , password : String\n    }\n\n\nloginMutation : Document Mutation String LoginVars\nloginMutation =\n    let\n        usernameVar =\n            Var.required \"username\" .username Var.string\n\n        passwordVar =\n            Var.required \"password\" .password Var.string\n    in\n        mutationDocument \u003c|\n            extract\n                (field \"login\"\n                    [ ( \"username\", Arg.variable usernameVar )\n                    , ( \"password\", Arg.variable passwordVar )\n                    ]\n                    (extract (field \"token\" [] string))\n                )\n```\n\n### Future plans for this package\n\nThere are a lot of things that this package can't do right now, but might do in the future. What gets done depends on how the package ends up being used, and how much demand there is for each feature. Here are some likely possibilities:\n\n* support for [subscriptions](https://dev-blog.apollodata.com/graphql-subscriptions-in-apollo-client-9a2457f015fb)\n* generating code from a GraphQL schemas and queries\n* providing functions to validate a query against a target schema\n* leveraging Relay-compliant schemas to cache response data and transform queries so that the client only asks the server for what it doesn't have already\n* providing an interface to implement a GraphQL schema that you can run queries against\n\n### Getting and giving help\n\nIf you're having trouble figuring out how to do something with this package, check out the [#graphql channel](https://elmlang.slack.com/messages/C0RSQNQ92) on the [Elm Slack](http://elmlang.herokuapp.com/) — there are usually people there who can help. And if you can be one of those people who help other people, then thank you!\n\n### Running the tests\n\nInstall the `elm-test` npm package globally:\n\n```\nnpm install -g elm-test\n```\n\nMake sure you have the latest version of `elm-test`, otherwise it may not be able to find the the test files in the right way. You can update an older version with `npm update -g elm-test`.\n\nNow run `elm-test` in the root folder of this project:\n\n```\nelm-test\n```\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Elm Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmacaulay%2Felm-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesmacaulay%2Felm-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmacaulay%2Felm-graphql/lists"}