servant-elm

Automatically derive Elm functions to query servant webservices.

http://github.com/mattjbray/servant-elm#readme

Version on this page:0.4.0.1
LTS Haskell 22.43:0.7.3
Stackage Nightly 2024-12-08:0.7.3
Latest on Hackage:0.7.3

See all snapshots servant-elm appears in

BSD-3-Clause licensed by Matt Bray
Maintained by [email protected]
This version can be pinned in stack with:servant-elm-0.4.0.1@sha256:5f8f79ffccf6f50ce8bfe2772590470f635fe819e22e12e0be2b5a1dee038294,4423

Module documentation for 0.4.0.1

Servant Elm

Build Status

Generate Elm functions to query your Servant API!

Elm type generation coutesy of krisajenkins/elm-export.

Installation

Servant Elm is available on Hackage.

Example

First, some language pragmas and imports.

{-# LANGUAGE DataKinds         #-}
{-# LANGUAGE DeriveGeneric     #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeOperators     #-}

import           Elm          (Spec (Spec), specsToDir, toElmDecoderSource,
                               toElmTypeSource)
import           GHC.Generics (Generic)
import           Servant.API  ((:>), Capture, Get, JSON)
import           Servant.Elm  (ElmType, Proxy (Proxy), defElmImports,
                               generateElmForAPI)

We have some Haskell-defined types and our Servant API.

data Book = Book
    { name :: String
    } deriving (Generic)

instance ElmType Book

type BooksApi = "books" :> Capture "bookId" Int :> Get '[JSON] Book

Now we can generate Elm functions to query the API:

spec :: Spec
spec = Spec ["Generated", "MyApi"]
            (defElmImports
             : toElmTypeSource    (Proxy :: Proxy Book)
             : toElmDecoderSource (Proxy :: Proxy Book)
             : generateElmForAPI  (Proxy :: Proxy BooksApi))

main :: IO ()
main = specsToDir [spec] "my-elm-dir"

Let’s save this as example.hs and run it:

$ stack runghc example.hs
Writing: my-elm-dir/Generated/MyApi.elm
$

Here’s what was generated:

module Generated.MyApi exposing (..)

import Json.Decode exposing (..)
import Json.Decode.Pipeline exposing (..)
import Json.Encode
import Http
import String


type alias Book =
    { name : String
    }

decodeBook : Decoder Book
decodeBook =
    decode Book
        |> required "name" string

getBooksByBookId : Int -> Http.Request (Book)
getBooksByBookId capture_bookId =
    Http.request
        { method =
            "GET"
        , headers =
            []
        , url =
            String.join "/"
                [ ""
                , "books"
                , capture_bookId |> toString |> Http.encodeUri
                ]
        , body =
            Http.emptyBody
        , expect =
            Http.expectJson decodeBook
        , timeout =
            Nothing
        , withCredentials =
            False
        }

See examples for a complete usage example, or take a look at mattjbray/servant-elm-example-app for an example project using this library.

Development

$ git clone https://github.com/mattjbray/servant-elm.git
$ cd servant-elm
$ stack test
$ stack test --flag servant-elm:integration

To build all examples:

$ make examples

To run an example:

$ cd examples/e2e-tests
$ elm-reactor
# Open http://localhost:8000/elm/Main.elm

Changes

0.4.0.1

  • Remove hyphens from generated function names. (servant-foreign-0.10 no longer does this for us.)

0.4.0.0

  • Allow passing the base URL dynamically in Elm. (#20)
  • Don’t use toString on Text parameters. (domenkozar) (#23, #24)
  • Fix query parameter generation. (domenkozar) (#25)

0.3.0.1

  • Prefix generated function arguments to ensure valid Elm identifiers (#21)
  • Put integration tests behind a Cabal flag. (#22)

0.3.0.0

  • Update for Elm 0.18 and the new elm-lang/http library.
  • Generated Elm functions now return an Http.Request value.

0.2.0.0

  • Use Text throughout the API.
  • We no longer auto-generate Elm sources for the types, encoders and decoders used in your API - you must now use elm-export’s toElmTypeSource functions explicitly. See the tests and examples for usage.
  • Allow setting options to pass to elm-export.
  • Update to servant-0.8 (purcell).
  • Basic support for custom headers.
  • Fix: String query params were being wrapped in double-quotes.
  • Test: verify that the generated code can be compiled by Elm (soenkehahn)

0.1.0.2

  • Fix for API endpoints that return Unit (kantp)

0.1.0.1

  • Convenience re-exports from Elm and Data.Proxy.
  • Add Haddoc documentation.

0.1

  • Initial release.