{"id":13393410,"url":"https://github.com/wende/elchemy","last_synced_at":"2025-04-08T16:01:31.670Z","repository":{"id":42000517,"uuid":"81605260","full_name":"wende/elchemy","owner":"wende","description":"Write Elixir code using statically-typed Elm-like syntax (compatible with Elm tooling)","archived":false,"fork":false,"pushed_at":"2020-03-17T13:19:41.000Z","size":7245,"stargazers_count":1148,"open_issues_count":25,"forks_count":28,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-01T15:13:40.532Z","etag":null,"topics":["compiler","elchemy","elixir","elixir-lang","elm","language","languages","transpiler"],"latest_commit_sha":null,"homepage":"https://wende.github.io/elchemy/","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wende.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-10T20:45:31.000Z","updated_at":"2025-03-14T14:22:33.000Z","dependencies_parsed_at":"2022-08-13T13:50:11.437Z","dependency_job_id":null,"html_url":"https://github.com/wende/elchemy","commit_stats":null,"previous_names":[],"tags_count":138,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wende%2Felchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wende%2Felchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wende%2Felchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wende%2Felchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wende","download_url":"https://codeload.github.com/wende/elchemy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247878014,"owners_count":21011158,"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":["compiler","elchemy","elixir","elixir-lang","elm","language","languages","transpiler"],"created_at":"2024-07-30T17:00:52.113Z","updated_at":"2025-04-08T16:01:31.645Z","avatar_url":"https://github.com/wende.png","language":"Elm","readme":"\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/wende/elchemy/blob/master/logo.png?raw=true\" width=\"250\" height=\"250\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://join.slack.com/t/elchemy-lang/shared_invite/enQtNjMzMDI0NzM3MzQ3LWVmZDZkMzY3OWZkMzJlOGIzZjMzMjcwMDgzNDFlZDYzY2NiYzE0ZjdhOTRmMmMyMjRiOTUzNjhhNWQ1M2VlMGY\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/chat-on%20slack-blueviolet.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"http://elchemy.neontree.pl\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/try%20now-online-yellow.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://wende.gitbooks.io/elchemy/content/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/read-docs-informational.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://medium.com/@krzysztof.wende/elmchemy-write-type-safe-elixir-code-with-elms-syntax-part-1-introduction-8968b76d721d\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/getting-started-green.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://travis-ci.org/wende/elchemy\"\u003e\n    \u003cimg src=\"https://travis-ci.org/wende/elchemy.svg?branch=master\"\u003e\n  \u003c/a\u003e\n \n\u003c/p\u003e\n\n#### Quick install\n\n```shell\nnpm install -g elchemy\n```\n\n\n# What is it?\n\nElchemy lets you write simple, fast and quality type safe code while leveraging both the Elm's safety and Elixir's ecosystem\n\n\n### In case of any questions about the project feel free to submit them in Issues with Q\u0026A label\n\n\n# Features\n\n- **Type inference:** Powerful type inference means you rarely have to annotate types. Everything gets checked for you by the compiler\n- **Easy and type-safe interop**: You can call Elixir/Erlang without any extra boiler-plate. All the calls you make are checked in terms of type-safety as thoroughly as possible based on Elixir's typespecs.\n- **All the best of Elm and Elixir**: Elchemy inherits what's best in Elm - type safety, inference and extreme expressiveness, but also what's best in Elixir - Doc-tests, tooling and obviously the entire BEAM platform.\n- **Nearly no runtime errors** - Elchemy's type system **eliminates almost all runtime errors**. With a shrinking set of edge cases, your entire Elchemy codebase is safe. Elixir parts of the codebase are the only ones to be a suspect in cases of runtime errors happening.\n- **Beautiful and fully readable output** - The produced code is idiomatic, performant and can be easily read and analyzed without taking a single look at the original source.\n\n\n# Maturity of the project\n\n- Parser - **99%** of Elm's syntax (see [elm-ast](https://github.com/Bogdanp/elm-ast/issues))\n- Compiler - **90%** (Sophisticated incremental compilation. \n  No support for Windows yet though ([#287](https://github.com/wende/elchemy/issues/287)) and also big reliance on unix tools ([#288](https://github.com/wende/elchemy/issues/288))\n- Elchemy-core - **95%** ( Everything covered except side effects and JSON Decoders) \n- Interop with Elixir - **90%** - Purity tests ([#162](https://github.com/wende/elchemy/issues/162)) and handling of macro-heavy libraries ([#276](https://github.com/wende/elchemy/issues/276)) to go \n- Ideology - **70%** - We've got a pretty solid idea of where Elchemy is going \n- Documentation - **80%** - There are two tutorials and a complete Gitbook documentation. Few entrance level tutorials though, this project tries to change it. \n- Elchemy-effects - **20%** - You can't and shouldn't write anything with side-effects in Elchemy yet. We're working on finding the best solution for effects that would fit both Elm's and Elixir's community (see [#297](https://github.com/wende/elchemy/issues/297) for more info)\n- Elchemy-core for Erlang VM - **5%** - Everything for os related tasks like filesystem, OTP goodies etc are yet to be done\n- Elchemy type checker - **20%** - Self-hosted elchemy type inference algorithm, written by @wende and inspired by @Bogdanp.\n\n# Usage\n\n### Prerequisites\n\n- [elixir@1.4.0-1.6.x](https://elixir-lang.org/install.html)\n- [node@5+](https://nodejs.org/en/)\n- [elm-lang@0.18.0](https://guide.elm-lang.org/install.html) (`npm install -g elm@0.18.0`)\n- [elm-github-install@0.1.2](https://github.com/gdotdesign/elm-github-install) - Compiler will install it automatically for you, if you don't have it yet.\n\n\n### Installation in an existing Elixir project\n\n\nInstall `elchemy` globally with:\n\n```shell\nnpm install -g elchemy\n```\n\n\nThen, in the root directory of your project do:\n\n```shell\nelchemy init\n```\n\nAnd follow the instructions.\n\n`elchemy` will find all `*.elm` files specified in `elchemy_path` and compile it into corresponding `*.ex` files in `lib` directory.\n\nYou can override output directory specifying `elixirc_paths`.\n\n\n### Installation as a standalone\n\n```shell\nnpm install -g elchemy\n```\n\nUsage\n\n```\nelchemy compile source_dir output_dir\n```\n\n### Recommended editors setup\n\n- [Atom](https://atom.io/) with [elixir-language](https://atom.io/packages/language-elixir) and [atom-elixir](https://github.com/msaraiva/atom-elixir) or [elixir-ide](https://atom.io/packages/ide-elixir) for Elixir; and [language-elm](https://atom.io/packages/language-elm) + [elmjutsu](https://atom.io/packages/elmjutsu) for Elchemy.\n- [Visual Studio Code](https://code.visualstudio.com/) with [vscode-elixir](https://marketplace.visualstudio.com/items?itemName=mjmcloug.vscode-elixir), [vscode-elixir-ls](https://github.com/JakeBecker/vscode-elixir-ls) and [vscode-elm](https://github.com/elm-tooling/elm-language-client-vscode)\n\n\n### Build from source\n\n```\ngit clone https://github.com/wende/elchemy.git\ncd elchemy\nmake compile\n./elchemy compile source_dir output_dir\n```\n\nand\n\n```\nmake dev\n```\n\nIn order to launch and test the web demo.\n\n\n## Troubleshooting\n\nIf something doesn't work, try \n\n\n```\nnpm install -g elchemy\nelchemy clean\nelchemy init\nmix test\n```\n\nfirst\n\n\n# FAQ\n\n## Why *would* I want to use that?\n\n- You like types\n- But even more you prefer compile-time errors over run-time error\n- You prefer `add b c = b + c` over `defp add(a, b), do: b + c`\n- You like curry\n- You think failing fast is cool, but not as cool as not failing at all\n\n\n## Why *wouldn't* I want to use that?\n\n- Your project relies on die-hard battle tested libraries, and you despise any versions starting with 0\n- You're afraid that when you learn what Monad is your mustache will grow, and eyesight weaken\n\n\n## Can I use it in already existing Elixir project?\n\nYou can, but nice and dandy compile tools are still on their way\n\n\n## Will my employer notice I'm having an affair with Elchemy?\n\nThe output files of Elchemy treat the code readability as a first class citizen. The code is meant to be properly indented, the comments aren't omitted, and the code is optimized as hard as it can ( f.i case clauses reduce to function overloads)\n\n\n## When will Elchemy become 1.0.0?\n\nOnce it's done, so as it is supposed to be in the so called semantic versioning. :innocent:\n\n\n## Can I contribute?\n\nDefinitely. Yes. Please do. :two_hearts:\n\n\n## How are types represented?\n\nYou're a nosy one, aren't you? :smile: Elchemy represents all type constructors as snake cased atoms, and all type applications as tuples. Which means that `MyType 42 \"Forty two\" Error` in Elchemy equals to `{:my_type, 42, \"Forty Two\", :error}` in Elixir.\n\n\n## Can I use already existing Elm libraries with Elchemy?\n\nAs long as they don't use any Native modules, Ports or Elm runtime they can be safely imported and used\n\n\n## Can I use already existing Elixir libraries with Elchemy?\n\nYes. You can do an `ffi` call to any function in any module. Whether it's Elixir module, Erlang module, or even a macro you can include it in your code. Ffi calls are a treated specially in Elchemy, and they get generated test to analyze the types based on @specs, so that you don't compromise type safety for using Elixir code. \nIn order to increase readability it's advised not to use `ffi` calls if not necessary and always document and doctest them.\n\n\n## But what about out of function macros? Like tests and `use Module`?\n\nUnfortunately you can't write any macros with `do..end` blocks yet. You can write any out of function code using an elixir inline code with:\n\n\n```elm\n{- ex\n  *code_here*\n-}\n```\n\nBut it is a last resort solution and shouldn't ever be abused.\n\n\n## Can I define an Elixir macro in Elchemy?\n\nSo you want to write an Elm-like code, that will manipulate Elixir code, which generates an Elixir code that manipulates Elixir code? How about no?\n\n\n## Do I need to have Elm installed to compile my `.elm` files with Elchemy?\n\nElchemy uses Elm to typecheck your program. It is possible to use it without Elm on your machine, while it's not advised.\n\n\n# Contributor credits:\n\n- Tomasz Cichociński - [@baransu](https://github.com/baransu)\n- Colin Bankier - [@colinbankier](https://github.com/colinbankier)\n- Nathaniel Knight - [@neganp](https://github.com/neganp)\n\n# Inspiration:\n\n- [Elm](https://github.com/elm/compiler) by Evan Czaplicki - [@evancz](https://github.com/evancz)\n- [Elixir](https://github.com/elixir-lang/elixir) by José Valim - [@josevalim](https://github.com/josevalim)\n- [Elm-AST](https://github.com/bogdanp/elm-ast) by Bogdan Popa - [@bogdanp](https://github.com/bogdanp) \n\n\n# Contributing Guide\n\n- Everyone is welcome to contribute :hugs:\n- Refer to https://bogdanp.github.io/elm-ast/example/ to have better understanding of parsed tokens.\n- Refer to https://wende.github.io/elchemy/stable/ to know the latest development version of the parser\n- For project management we use ZenHub. You can see the Kanban board, card estimates and all the reports by installing a browser extension here: [Opera/Chrome](https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd), [Firefox](zenhub.com)\n\n\n## Targeted values:\n\n- Fully readable and indented elixir code generated from compilation\n- Seamless and stress less interop with existing Elixir code, preferably with magically working type safety\n- Full integration with entire elm syntax for editors and compilers magic\n\n\n","funding_links":[],"categories":["Languages","Elm","Languages Integration","Inspired by Elm"],"sub_categories":["Games"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwende%2Felchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwende%2Felchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwende%2Felchemy/lists"}