ryan-haskell / graphql / GraphQL.Encode


type Value

The Value type represents a JSON value that will be sent to your GraphQL API. When you use this with the GraphQL.Http module, this is an example of what will be sent with your HTTP request:

{
    "variables": {
        "id": "123",
        "form": {
            "email": "ryan@elm.land",
            "password": "secret123"
        }
    }
}

Scalars

string : String -> Value

Create a GraphQL input from a String value:

import GraphQL.Encode

name : GraphQL.Encode.Value
name =
    GraphQL.Encode.string "Ryan"

float : Basics.Float -> Value

Create a GraphQL input from a Float value:

import GraphQL.Encode

score : GraphQL.Encode.Value
score =
    GraphQL.Encode.float 0.99

int : Basics.Int -> Value

Create a GraphQL input from a Int value:

import GraphQL.Encode

age : GraphQL.Encode.Value
age =
    GraphQL.Encode.int 62

bool : Basics.Bool -> Value

Create a GraphQL input from a Bool value:

import GraphQL.Encode

isReadingThis : GraphQL.Encode.Value
isReadingThis =
    GraphQL.Encode.bool True

id : GraphQL.Scalar.Id.Id -> Value

Create a GraphQL input from a Id value:

import GraphQL.Encode
import GraphQL.Scalar.Id exposing (Id)

userId : Id
userId =
    GraphQL.Scalar.Id.fromInt 1203

isReadingThis : GraphQL.Encode.Value
isReadingThis =
    GraphQL.Encode.id userId

scalar : { toJson : scalar -> Json.Encode.Value, value : scalar } -> Value

Here's an example of using this function to work with a DateTime type. We recommend defining each custom scalar in a separate Elm module, like GraphQL.Scalar.DateTime:

-- module GraphQL.Scalar.DateTime exposing
--     ( DateTime
--     , decoder, encode
--     )


import GraphQL.Encode
import Iso8601
import Time

type alias DateTime =
    Time.Posix

encode : DateTime -> GraphQL.Encode.Value
encode dateTime =
    GraphQL.Encode.scalar
        { toJson = Iso8601.encode
        , value = dateTime
        }

The snippet above uses elm/time and rtfeldman/elm-iso8601-date-strings to convert our Time.Posix value into an ISO 8601 String value for our API.

import GraphQL.Scalar.DateTime

GraphQL.Scalar.DateTime.encode
    (Time.millisToPosix 1672019156520)
    == Json "2022-12-26T01:45:56.520Z"

Enums

enum : { toString : enum -> String, value : enum } -> Value

Create a GraphQL input from an enum value. To avoid duplicating code, we recommend you create a separate Elm module per enum, like GraphQL.Enum.Episode.

In that module, you can define your encode function in one place:

-- module GraphQL.Enum.Episode exposing
--     ( Episode(..), list
--     , decoder, encode
--     )


import GraphQL.Encode

type Episode
    = NewHope
    | EmpireStrikesBack
    | ReturnOfTheJedi

encode : Episode -> GraphQL.Encode.Value
encode episode =
    GraphQL.Encode.enum
        { toString = toString
        , value = episode
        }

toString : Episode -> String
toString episode =
    case episode of
        NewHope ->
            "NEWHOPE"

        EmpireStrikesBack ->
            "EMPIRE"

        ReturnOfTheJedi ->
            "RETURN"

Input types

input : List ( String, Value ) -> Value

GraphQL allows the API to define input types. These allow you to group your inputs into an object, like this:

import GraphQL.Encode

reviewInputValue : GraphQL.Encode.Value
reviewInputValue =
    GraphQL.Encode.input
        [ ( "stars"
          , GraphQL.Encode.int 10
          )
        , ( "commentary"
          , GraphQL.Encode.int "Would eat again!"
          )
        ]

Advanced

list : (a -> Value) -> List a -> Value

Create a value from a list:

import GraphQL.Encode

encodeIds : List Int -> GraphQL.Encode.Value
encodeIds ids =
    GraphQL.Encode.list GraphQL.Encode.int ids


encodeIds [] == """ [] """
encodeIds [1,2,3] == """ [1,2,3] """

maybe : (a -> Value) -> Maybe a -> Value

Create a Maybe value, using null if there is no value provided:

import GraphQL.Encode

encodeEmail : Maybe String -> GraphQL.Encode.Value
encodeEmail email =
    GraphQL.Encode.maybe GraphQL.Encode.string email


encodeEmail Nothing == """ null """
encodeEmail (Just "ryan@elm.land") == """ "ryan@elm.land" """

null : Value

Send a null value to a GraphQL API. This is commonly used by mutations to mark a field as removed.

import GraphQL.Encode

profileInputValue : GraphQL.Encode.Value
profileInputValue =
    GraphQL.Encode.input
        [ ( "name"
          , GraphQL.Encode.string "Ryan"
          )
        , ( "bio"
          , GraphQL.Encode.null
          )
        ]

Internals

These functions are used internally by GraphQL.Http, and you won't need them in your projects

toJson : Value -> Json.Encode.Value