{"id":19422535,"url":"https://github.com/scalalandio/endpoints-elm","last_synced_at":"2025-04-24T15:32:20.905Z","repository":{"id":57736153,"uuid":"183780092","full_name":"scalalandio/endpoints-elm","owner":"scalalandio","description":"Elm code generator based on Scala endpoints library (https://github.com/julienrf/endpoints)","archived":false,"fork":false,"pushed_at":"2019-08-19T20:59:37.000Z","size":137,"stargazers_count":7,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T07:12:51.286Z","etag":null,"topics":["code","elm","endpoints","generator","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scalalandio.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":"2019-04-27T14:01:37.000Z","updated_at":"2023-08-13T16:48:45.000Z","dependencies_parsed_at":"2022-08-23T22:40:29.606Z","dependency_job_id":null,"html_url":"https://github.com/scalalandio/endpoints-elm","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalalandio%2Fendpoints-elm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalalandio%2Fendpoints-elm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalalandio%2Fendpoints-elm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalalandio%2Fendpoints-elm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scalalandio","download_url":"https://codeload.github.com/scalalandio/endpoints-elm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250654472,"owners_count":21465887,"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","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":["code","elm","endpoints","generator","scala"],"created_at":"2024-11-10T13:34:06.369Z","updated_at":"2025-04-24T15:32:20.549Z","avatar_url":"https://github.com/scalalandio.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# endpoints-elm\n\n[![Build Status](https://travis-ci.org/scalalandio/endpoints-elm.svg?branch=master)](https://travis-ci.org/scalalandio/endpoints-elm)\n[![Maven Central](https://img.shields.io/maven-central/v/io.scalaland/endpoints-elm_2.12.svg)](http://search.maven.org/#search%7Cga%7C1%7Cendpoints-elm)\n[![License](http://img.shields.io/:license-Apache%202-green.svg)](http://www.apache.org/licenses/LICENSE-2.0.txt)\n\nElm code generator based on Scala [endpoints library](https://github.com/julienrf/endpoints).\n\n#### New to endpoints?\n\nEndpoints is great Scala library that allows you to define communication protocols over HTTP and keep\nconsistent server implementation, clients and documentation.\nSee also [official project documentation](http://julienrf.github.io/endpoints/)\n\n#### Elm code generator\n\nThis project provides:\n\n- interpreter for all basic endpoints algebras that targets [data structures](src/main/scala/io/scalaland/endpoints/elm/model) that resemble elm type system\n- code emitter that takes these data structures and emits elm code containing:\n  - elm type definitions\n  - json encoders and decoders\n  - init value providers\n  - url construction methods targeting [elm-url](https://github.com/elm/url)\n  - api client methods targeting [elm-http-builder](https://github.com/lukewestby/elm-http-builder)\n\n##### Output code structure\n\n```\nData/Type1.elm\nData/Type2.elm\nData/Type3.elm\nRequest/Url/HttpModule1.elm\nRequest/Url/HttpModule2.elm\nRequest/Url/HttpModule3.elm\nRequest/HttpModule1.elm\nRequest/HttpModule2.elm\nRequest/HttpModule3.elm\n```\n\n## Getting started\n\nTo get started, first add project dependency to your `build.sbt`:\n\n```scala\nlibraryDependencies += \"io.scalaland\" %% \"endpoints-elm\" % \"0.10.0\"\n```\n\n##### Endpoints definition\n\nIf you follow [endpoints quick start guide](http://julienrf.github.io/endpoints/quick-start.html),\nyou end up with something similar to:\n\n```scala\nimport endpoints.{algebra, generic}\n\ncase class Counter(value: Int)\ncase class Increment(step: Int)\n\ntrait CounterEndpoints\n    extends algebra.Endpoints\n    with algebra.JsonSchemaEntities\n    with algebra.JsonSchemas\n    with generic.JsonSchemas {\n\n  implicit lazy val counterSchema: JsonSchema[Counter] = named(genericJsonSchema[Counter], \"Counter\")\n  implicit lazy val incrementSchema: JsonSchema[Increment] = named(genericJsonSchema[Increment], \"Increment\")\n  \n  val currentValue: Endpoint[Unit, Counter] =\n    endpoint(\n      get(path / \"current-value\"),\n      jsonResponse[Counter](docs = Some(\"Coutner status\")),\n      tags = List(\"Counter\")\n    )\n\n  val increment: Endpoint[Increment, Unit] =\n    endpoint(\n      post(path / \"increment\", jsonRequest[Increment](docs = Some(\"Counter increment request\"))),\n      emptyResponse(),\n      tags = List(\"Counter\")\n    )\n}\n```\n\nFor code generation purposes it's required to:\n- name your json schemas for types using `named(schema, \"YourSchemaName\")`\n- tag your endpoints using `tags = List(\"YourEndpointTag\")`\n\nType and file names in generated code is based on those names.\n\n##### Mixing code generator interpreter\n\nThen you need to mix in `io.scalaland.endpoints.elm.ElmCodeGenerator` with your endpoints trait.\n\n```scala\nimport io.scalaland.endpoints.elm.ElmCodeGenerator\n\nobject ElmCounterGen extends CounterEndpoints with ElmCodeGenerator {\n\n    def generateCode(): Unit = {\n      writeElmCode(\"target/directory\")(currentValue, increment)()    \n    }\n}\n```\n\nInvoking `ElmCounterGen.generateCode()` will clean target directory,\ncreate `Data` and `Request` directories and write down elm modules for\ndata types and http api client.\n\n## Codegen target\n\nGenerated code consists of bunch of modules of 2 kinds: data modules and http request modules.\n\n##### Data modules\n\nExample data module looks like follows:\n\n```elm\n{-\n  This file was generated by endpoints-elm interpreter.\n  Do not edit this file manually.\n\n  See https://github.com/scalalandio/endpoints-elm for more information.\n-}\n\nmodule Data.Counter exposing (..)\n\n\nimport Json.Decode as Decode exposing (Decoder)\nimport Json.Decode.Pipeline exposing (optional, required)\nimport Json.Encode as Encode\n\n\ntype alias Counter = \n  { value : Int\n  }\n\ninit : Counter\ninit = \n  { value = 0\n  }\n\ndecoder : Decoder Counter\ndecoder = Decode.succeed Counter\n  |\u003e required \"value\" Decode.int \n\nencoder : Counter -\u003e Encode.Value\nencoder model = Encode.object (fieldsEncoder model)\n\nencoderTagged : (String, String) -\u003e Counter -\u003e Encode.Value\nencoderTagged (discriminator, tag) model = Encode.object ((discriminator, Encode.string tag) :: fieldsEncoder model)\n\nfieldsEncoder : Counter -\u003e List (String, Encode.Value)\nfieldsEncoder model = \n  [ ( \"value\", Encode.int model.value )\n  ]\n\nsetValue : Int -\u003e Counter -\u003e Counter\nsetValue newValue counter =\n  { counter | value = newValue }\n\nupdateValue : (Int -\u003e Int) -\u003e Counter -\u003e Counter\nupdateValue f counter =\n  { counter | value = f counter.value }\n\n```\n\nIt contains:\n\n- type definition (`type alias Counter`)\n- initial/example value definition (`init`)\n- Json codecs (`decoder` and `encoder`)\n- utility functions for setting fields to a specific value (`setValue`)\n- utility functions for updating fields using provided function (`updateValue`)\n\n##### Url modules\n\nModule with urls contains one function that constructs url string for each endpoint.\n\n```elm\n{-\n   This file was generated by endpoints-elm 0.10.0 interpreter.\n   Do not edit this file manually.\n\n   See https://github.com/scalalandio/endpoints-elm for more information.\n-}\n\n\nmodule Request.Url.Counter exposing (currentvalueGet, incrementPost)\n\nimport Bool.Extra\nimport Maybe.Extra\nimport Url.Builder\n\n\ncurrentvalueGet : String\ncurrentvalueGet =\n    Url.Builder.relative\n        [ \"/\", \"current-value\" ]\n        []\n\n\nincrementPost : String\nincrementPost =\n    Url.Builder.relative\n        [ \"/\", \"increment\" ]\n        []\n```\n\n##### Http modules\n\nHttp module utilizes generated url module and for each endpoint contains\na function that returns `HttpBuilder.Task.RequestBuilder`.\n\n```elm\n{-\n   This file was generated by endpoints-elm 0.10.0 interpreter.\n   Do not edit this file manually.\n\n   See https://github.com/scalalandio/endpoints-elm for more information.\n-}\n\n\nmodule Request.Counter exposing (currentvalueGet, incrementPost)\n\nimport Request.Url.Counter\nimport EndpointsElm\nimport Http\nimport HttpBuilder.Task exposing (RequestBuilder)\nimport Json.Decode as Decode\nimport Json.Encode as Encode\nimport Bool.Extra\nimport Maybe.Extra\nimport Bytes exposing (Bytes)\nimport Dict exposing (Dict)\n\nimport Data.Counter exposing (..)\nimport Data.Increment exposing (..)\n\n\ncurrentvalueGet : RequestBuilder Http.Error Counter\ncurrentvalueGet  =\n  HttpBuilder.Task.get (Request.Url.Counter.currentvalueGet )\n    |\u003e HttpBuilder.Task.withResolver (Http.stringResolver (EndpointsElm.httpResolveJson (Data.Counter.decoder)))\n    |\u003e HttpBuilder.Task.withTimeout 30000\n\n\nincrementPost : Increment -\u003e RequestBuilder Http.Error ()\nincrementPost increment =\n  HttpBuilder.Task.post (Request.Url.Counter.incrementPost )\n    |\u003e HttpBuilder.Task.withBody (Http.jsonBody (Data.Increment.encoder increment))\n    |\u003e HttpBuilder.Task.withResolver (Http.stringResolver (EndpointsElm.httpResolveUnit))\n    |\u003e HttpBuilder.Task.withTimeout 30000\n```\n\n##### Dependencies\n\nCode generation in endpoints-elm makes some assumptions about dependencies in elm project.\n\nYou need to have installed following packages:\n\n```\n\"Chadtech/elm-bool-extra\": \"2.4.0\"\n\"NoRedInk/elm-json-decode-pipeline\": \"1.0.0\"\n\"elm/core\": \"1.0.2\"\n\"elm/http\": \"2.0.0\"\n\"elm/json\": \"1.1.3\"\n\"elm-community/maybe-extra\": \"5.0.0\",\n\"elm/url\": \"1.0.0\",\n\"elm/bytes\": \"1.0.8\",\n\"lukewestby/elm-http-builder\": \"7.0.0\"\n```\n\nFor `elm/http 1.0.0` and `lukewestby/elm-http-builder 6.0.0`, check out version `0.9.1` of this library.\n\nSee also example`out/elm.json`.\n\n\n##### Customizing code generation\n\nTBD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalalandio%2Fendpoints-elm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscalalandio%2Fendpoints-elm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalalandio%2Fendpoints-elm/lists"}