endpoints-elm

Elm code generator based on Scala endpoints library.

New to endpoints?

Endpoints is great Scala library that allows you to define communication protocols over HTTP and keep consistent server implementation, clients and documentation. See also official project documentation

Elm code generator

This project provides:

interpreter for all basic endpoints algebras that targets data structures that resemble elm type system
code emitter that takes these data structures and emits elm code containing:
- elm type definitions
- json encoders and decoders
- init value providers
- url construction methods targeting elm-url
- api client methods targeting elm-http-builder

Output code structure

Data/Type1.elm
Data/Type2.elm
Data/Type3.elm
Request/Url/HttpModule1.elm
Request/Url/HttpModule2.elm
Request/Url/HttpModule3.elm
Request/HttpModule1.elm
Request/HttpModule2.elm
Request/HttpModule3.elm

Getting started

To get started, first add project dependency to your build.sbt:

libraryDependencies += "io.scalaland" %% "endpoints-elm" % "0.10.0"

Endpoints definition

If you follow endpoints quick start guide, you end up with something similar to:

import endpoints.{algebra, generic}

case class Counter(value: Int)
case class Increment(step: Int)

trait CounterEndpoints
    extends algebra.Endpoints
    with algebra.JsonSchemaEntities
    with algebra.JsonSchemas
    with generic.JsonSchemas {

  implicit lazy val counterSchema: JsonSchema[Counter] = named(genericJsonSchema[Counter], "Counter")
  implicit lazy val incrementSchema: JsonSchema[Increment] = named(genericJsonSchema[Increment], "Increment")
  
  val currentValue: Endpoint[Unit, Counter] =
    endpoint(
      get(path / "current-value"),
      jsonResponse[Counter](docs = Some("Coutner status")),
      tags = List("Counter")
    )

  val increment: Endpoint[Increment, Unit] =
    endpoint(
      post(path / "increment", jsonRequest[Increment](docs = Some("Counter increment request"))),
      emptyResponse(),
      tags = List("Counter")
    )
}

For code generation purposes it's required to:

name your json schemas for types using named(schema, "YourSchemaName")
tag your endpoints using tags = List("YourEndpointTag")

Type and file names in generated code is based on those names.

Mixing code generator interpreter

Then you need to mix in io.scalaland.endpoints.elm.ElmCodeGenerator with your endpoints trait.

import io.scalaland.endpoints.elm.ElmCodeGenerator

object ElmCounterGen extends CounterEndpoints with ElmCodeGenerator {

    def generateCode(): Unit = {
      writeElmCode("target/directory")(currentValue, increment)()    
    }
}

Invoking ElmCounterGen.generateCode() will clean target directory, create Data and Request directories and write down elm modules for data types and http api client.

Codegen target

Generated code consists of bunch of modules of 2 kinds: data modules and http request modules.

Data modules

Example data module looks like follows:

{-
  This file was generated by endpoints-elm interpreter.
  Do not edit this file manually.

  See https://github.com/scalalandio/endpoints-elm for more information.
-}

module Data.Counter exposing (..)


import Json.Decode as Decode exposing (Decoder)
import Json.Decode.Pipeline exposing (optional, required)
import Json.Encode as Encode


type alias Counter = 
  { value : Int
  }

init : Counter
init = 
  { value = 0
  }

decoder : Decoder Counter
decoder = Decode.succeed Counter
  |> required "value" Decode.int 

encoder : Counter -> Encode.Value
encoder model = Encode.object (fieldsEncoder model)

encoderTagged : (String, String) -> Counter -> Encode.Value
encoderTagged (discriminator, tag) model = Encode.object ((discriminator, Encode.string tag) :: fieldsEncoder model)

fieldsEncoder : Counter -> List (String, Encode.Value)
fieldsEncoder model = 
  [ ( "value", Encode.int model.value )
  ]

setValue : Int -> Counter -> Counter
setValue newValue counter =
  { counter | value = newValue }

updateValue : (Int -> Int) -> Counter -> Counter
updateValue f counter =
  { counter | value = f counter.value }

It contains:

type definition (type alias Counter)
initial/example value definition (init)
Json codecs (decoder and encoder)
utility functions for setting fields to a specific value (setValue)
utility functions for updating fields using provided function (updateValue)

Url modules

Module with urls contains one function that constructs url string for each endpoint.

{-
   This file was generated by endpoints-elm 0.10.0 interpreter.
   Do not edit this file manually.

   See https://github.com/scalalandio/endpoints-elm for more information.
-}


module Request.Url.Counter exposing (currentvalueGet, incrementPost)

import Bool.Extra
import Maybe.Extra
import Url.Builder


currentvalueGet : String
currentvalueGet =
    Url.Builder.relative
        [ "/", "current-value" ]
        []


incrementPost : String
incrementPost =
    Url.Builder.relative
        [ "/", "increment" ]
        []

Http modules

Http module utilizes generated url module and for each endpoint contains a function that returns HttpBuilder.Task.RequestBuilder.

{-
   This file was generated by endpoints-elm 0.10.0 interpreter.
   Do not edit this file manually.

   See https://github.com/scalalandio/endpoints-elm for more information.
-}


module Request.Counter exposing (currentvalueGet, incrementPost)

import Request.Url.Counter
import EndpointsElm
import Http
import HttpBuilder.Task exposing (RequestBuilder)
import Json.Decode as Decode
import Json.Encode as Encode
import Bool.Extra
import Maybe.Extra
import Bytes exposing (Bytes)
import Dict exposing (Dict)

import Data.Counter exposing (..)
import Data.Increment exposing (..)


currentvalueGet : RequestBuilder Http.Error Counter
currentvalueGet  =
  HttpBuilder.Task.get (Request.Url.Counter.currentvalueGet )
    |> HttpBuilder.Task.withResolver (Http.stringResolver (EndpointsElm.httpResolveJson (Data.Counter.decoder)))
    |> HttpBuilder.Task.withTimeout 30000


incrementPost : Increment -> RequestBuilder Http.Error ()
incrementPost increment =
  HttpBuilder.Task.post (Request.Url.Counter.incrementPost )
    |> HttpBuilder.Task.withBody (Http.jsonBody (Data.Increment.encoder increment))
    |> HttpBuilder.Task.withResolver (Http.stringResolver (EndpointsElm.httpResolveUnit))
    |> HttpBuilder.Task.withTimeout 30000

Dependencies

Code generation in endpoints-elm makes some assumptions about dependencies in elm project.

You need to have installed following packages:

"Chadtech/elm-bool-extra": "2.4.0"
"NoRedInk/elm-json-decode-pipeline": "1.0.0"
"elm/core": "1.0.2"
"elm/http": "2.0.0"
"elm/json": "1.1.3"
"elm-community/maybe-extra": "5.0.0",
"elm/url": "1.0.0",
"elm/bytes": "1.0.8",
"lukewestby/elm-http-builder": "7.0.0"

For elm/http 1.0.0 and lukewestby/elm-http-builder 6.0.0, check out version 0.9.1 of this library.

Customizing code generation

TBD

scalalandio / endpoints-elm 0.10.0