{"id":35694406,"url":"https://github.com/fullofcaffeine/reflaxe.elixir","last_synced_at":"2026-06-13T03:08:53.777Z","repository":{"id":332225974,"uuid":"1035780534","full_name":"fullofcaffeine/reflaxe.elixir","owner":"fullofcaffeine","description":"Elixir target for Haxe. Compile Haxe to (mostly idiomatic) Elixir.","archived":false,"fork":false,"pushed_at":"2026-06-10T19:03:20.000Z","size":42449,"stargazers_count":10,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T20:07:00.625Z","etag":null,"topics":["alternative-to-gleam","compiler","elixir","fullstack","genes","gleam","haxe","haxe-externs","haxe-library","haxe-to-elixir","macros","phoenix","reflaxe","transpiler","typed","typesafe"],"latest_commit_sha":null,"homepage":"https://fullofcaffeine.co","language":"Haxe","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullofcaffeine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-11T04:47:25.000Z","updated_at":"2026-06-10T19:03:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fullofcaffeine/reflaxe.elixir","commit_stats":null,"previous_names":["fullofcaffeine/reflaxe.elixir"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/fullofcaffeine/reflaxe.elixir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.elixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.elixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.elixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.elixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullofcaffeine","download_url":"https://codeload.github.com/fullofcaffeine/reflaxe.elixir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2Freflaxe.elixir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34270443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["alternative-to-gleam","compiler","elixir","fullstack","genes","gleam","haxe","haxe-externs","haxe-library","haxe-to-elixir","macros","phoenix","reflaxe","transpiler","typed","typesafe"],"created_at":"2026-01-06T00:12:33.134Z","updated_at":"2026-06-13T03:08:53.759Z","avatar_url":"https://github.com/fullofcaffeine.png","language":"Haxe","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/haxir-logo.png\" alt=\"Haxir logo\" width=\"280\" /\u003e\n\u003c/p\u003e\n\n# Reflaxe.Elixir (aka Haxir)\n\n[![Version](https://img.shields.io/badge/version-1.3.0-blue)](https://github.com/fullofcaffeine/reflaxe.elixir/releases)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![CI](https://github.com/fullofcaffeine/reflaxe.elixir/actions/workflows/ci.yml/badge.svg)](https://github.com/fullofcaffeine/reflaxe.elixir/actions/workflows/ci.yml)\n[![Haxe](https://img.shields.io/badge/Haxe-4.3.7+-orange)](https://haxe.org)\n[![Elixir](https://img.shields.io/badge/Elixir-1.14+-purple)](https://elixir-lang.org)\n\n**Type-safe Haxe to Elixir compiler with Phoenix/LiveView support.** Write business logic in Haxe, compile to idiomatic Elixir code for the BEAM ecosystem.\n\n\u003e [!WARNING]\n\u003e **Stability**: Reflaxe.Elixir `v1.1.x` is considered **non‑alpha** for the documented subset.\n\u003e Some features remain **experimental/opt‑in** (e.g. source mapping, migrations `.exs` emission, `fast_boot`).\n\u003e See: [Known Limitations](docs/06-guides/KNOWN_LIMITATIONS.md) and [Versioning \u0026 Stability](docs/06-guides/VERSIONING_AND_STABILITY.md).\n\n### Stability tiers (tl;dr)\n\n- **Stable (documented subset)**: exercised by CI + todo-app; intended to be reliable within `v1.x`.\n- **Experimental (opt-in)**: available, but expect rough edges and possible breaking changes (e.g. source maps, migrations `.exs`, `fast_boot`).\n- **Dev/internal tooling**: debug flags and contributor-only workflows; not part of the end-user stability contract.\n\nSee: [Versioning \u0026 Stability](docs/06-guides/VERSIONING_AND_STABILITY.md).\n\n### Known sharp edges (top 3)\n\n- `fast_boot` is for faster local iteration; don’t rely on its output shape for CI/production builds.\n- Watcher port conflicts can happen (Phoenix watchers + Haxe server ports); the repo examples auto-probe, but custom setups may need tweaks.\n- Typed boundaries matter: prefer `Term` at external boundaries and decode into typed structures instead of using `Dynamic`.\n\nSee: [Known Limitations](docs/06-guides/KNOWN_LIMITATIONS.md).\n\n\u003e **Future Vision**: See [docs/08-roadmap/vision.md](docs/08-roadmap/vision.md) for long-term plans including AI tooling and universal platform support  \n\u003e **Current Status**: Stable subset (v1.1) — non‑alpha for the documented subset; experimental features are clearly labeled.\n\n## Why Reflaxe.Elixir?\n\n### 🎯 Type-Safe BEAM Development with Haxe\n\n**The Problem**: You want BEAM's incredible concurrency and fault tolerance, but Elixir's dynamic typing means runtime errors in production.\n\n**The Solution**: Reflaxe.Elixir brings compile-time type safety to the BEAM ecosystem:\n- **Type Safety Today** - Catch errors at compile time, not in production\n- **Idiomatic Elixir Output** - Generated code looks hand-written by Elixir experts\n- **Full Phoenix Integration** - LiveView, Ecto, OTP, GenServers all supported\n- **Future Expansion** - Haxe's multi-target nature enables future platform support\n\nThe BEAM is designed to *recover* from failures (supervision + “let it crash/let it heal”), but typed code still helps a lot:\n- Prevent accidental crashes and make refactors safer.\n- Make *intentional* failures explicit (e.g. `Result`/`Option` patterns) so you can be deliberate about what should crash vs what should be handled locally.\n\n### How this compares to Gleam\n\nGleam is an excellent typed BEAM language with a strong focus on correctness and a great compiler UX. Reflaxe.Elixir takes a different path:\n- **Direct Elixir ecosystem leverage**: Reflaxe.Elixir generates idiomatic Elixir and targets HEEx (`~H`) and Phoenix/LiveView patterns directly.\n- **Fewer “FFI boundary” tradeoffs**: in Gleam, calling into non-Gleam libraries via externals is powerful, but the external code can’t be type-checked by the Gleam compiler and editor assistance is reduced. Reflaxe.Elixir aims to keep you on the “typed path” while still producing standard Elixir/Phoenix code.\n\n### 💡 Real-World Scenarios\n\n#### Build Type-Safe Phoenix Applications\nWrite your Phoenix app in Haxe and get:\n- **Compile-time validation** of LiveView assign/update patterns\n- **Type-safe Ecto schemas** with automatic changeset generation\n- **OTP supervision trees** with typed GenServer callbacks\n- **Idiomatic Elixir output** that Phoenix developers recognize\n\n#### Share Code with Frontend (Future)\nThe foundation for multi-target development:\n- **Business logic in Haxe** - validation, algorithms, data transformations\n- **Backend on BEAM** - Phoenix/LiveView/Ecto with full type safety ✅\n- **Frontend on JavaScript** - Async/await support + [Genes](https://github.com/benmerckx/genes) ES module output (see todo-app) ✅\n- **TypeScript ecosystem access** - dts2hx planned (optional future)\n\n#### Leverage BEAM's Unique Strengths\n- **Massive concurrency** - Handle millions of connections with lightweight processes\n- **Fault tolerance** - Let it crash philosophy with supervisor recovery\n- **Hot code reloading** - Update production systems without downtime\n- **Type safety** - Catch errors before they reach production\n\n### 🚀 How It Compares\n\n| | Reflaxe.Elixir | Gleam | Pure Elixir | TypeScript |\n|---|---|---|---|---|\n| **Type Safety** | ✅ Compile-time | ✅ Compile-time | ❌ Runtime | ✅ Compile-time |\n| **BEAM Integration** | ✅ Full Phoenix/OTP | ✅ Native | ✅ Native | ❌ None |\n| **Phoenix LiveView** | ✅ Native support | ⚠️ Via externals (tradeoffs) | ✅ Native | ❌ None |\n| **Multi-target Potential** | ✅ Haxe foundation | ✅ BEAM + JS | ❌ BEAM only | ⚠️ JS only |\n| **Ecosystem Maturity** | ✅ Since 2005 | ⚠️ New | ✅ Mature | ✅ Mature |\n| **Learning Curve** | ✅ TypeScript-like | ⚠️ Rust-like | ⚠️ Ruby-like | ✅ Familiar |\n\n### 🎪 Built on Proven Technology\n\n- **Haxe** (2005): Battle-tested cross-platform toolkit used in production by companies like Netflix, Disney, BBC, Toyota, and more\n- **Elixir/BEAM**: Powers WhatsApp (2B users), Discord, Pinterest, and other massive-scale systems\n- **Reflaxe**: Modern compiler framework making Haxe more powerful than ever\n\n## Current Status \u0026 Roadmap\n\n### ✅ Stable (v1.1)\n- **Phoenix Integration** - LiveView, controllers, templates, routers 100% supported\n- **HXX Template System** - Complete compile-time JSX→HEEx transformation with AST-based processing\n  - **Template Helper Metadata** ✨ NEW - Uses @:templateHelper metadata for extensible Phoenix function compilation\n  - **Type-Safe Phoenix Abstractions** ✨ NEW - Assigns\u003cT\u003e, LiveViewSocket\u003cT\u003e, FlashMessage, RouteParams\u003cT\u003e with operator overloading\n- **Ecto Integration** - Schemas, changesets, and typed queries supported; **migrations remain opt‑in/experimental** (`-D ecto_migrations_exs`)  \n- **Mix Integration** - Seamless build pipeline with file watching and incremental compilation\n- **Source Mapping (experimental)** - `.ex.map` emission + `mix haxe.source_map` lookup are implemented (line coverage + many expression-level boundaries; see `docs/04-api-reference/SOURCE_MAPPING.md`)\n- **OTP Support** - GenServers, Supervisors, Registry with type-safe compilation\n- **Type Safety** - Complete Haxe→Elixir type mapping and compile-time validation\n- **JavaScript Async/Await** - Native async/await compilation for modern JS development\n\n### 🔮 Future Expansion\nFor the complete roadmap including AI tooling, universal deployment, and multi-platform support, see [docs/08-roadmap/vision.md](docs/08-roadmap/vision.md):\n\n- **JavaScript Integration** - Advanced TypeScript ecosystem access\n- **Mobile Support** - Capacitor and React Native deployment  \n- **Desktop Applications** - Electron/Tauri cross-platform apps\n- **AI-Enhanced Tooling** - Intelligent development assistance  \n\n## Installation\n\n### Prerequisites\n- Haxe 4.3.7+ (installed globally, or pinned per-project via `lix` and used via `./node_modules/.bin/haxe`)\n- Node.js 16+ (for lix package management; Node 20 recommended)\n- Elixir 1.14+ (for Phoenix/Ecto ecosystem)\n\n### Method 1: Install via Lix (Recommended)\n\n```bash\n# Create a lix scope in your project directory\nnpx lix scope create\n\n# Install the latest GitHub release tag (recommended)\n# If this fails (no `curl` / GitHub rate limit), pick a tag from the Releases page and set it manually.\nREFLAXE_ELIXIR_TAG=\"$(curl -fsSL https://api.github.com/repos/fullofcaffeine/reflaxe.elixir/releases/latest | sed -n 's/.*\\\"tag_name\\\":[[:space:]]*\\\"\\\\([^\\\"]*\\\\)\\\".*/\\\\1/p' | head -n 1)\"\nnpx lix install \"github:fullofcaffeine/reflaxe.elixir#${REFLAXE_ELIXIR_TAG}\"\n\n# Download pinned Haxe libraries for the project (reflaxe + tink_* + deps)\nnpx lix download\n\n# Bleeding edge (main branch; not necessarily a release)\n# npx lix install github:fullofcaffeine/reflaxe.elixir --force\n```\n\n\u003e Reflaxe.Elixir GitHub Releases are created for `vX.Y.Z` tags. To use a specific release, install that tag with lix.\n\n### Method 2: Vendoring (Copy source directly)\n\nFor projects that want to vendor the compiler source:\n\n```bash\n# Clone or download the repository\ngit clone https://github.com/fullofcaffeine/reflaxe.elixir.git\n\n# Copy necessary files to your project\ncp -r reflaxe.elixir/src/ your-project/vendor/reflaxe.elixir/src/\ncp -r reflaxe.elixir/std/ your-project/vendor/reflaxe.elixir/std/\ncp reflaxe.elixir/haxelib.json your-project/vendor/reflaxe.elixir/\n\n# In your build.hxml, add:\n# -cp vendor/reflaxe.elixir/src\n# -cp vendor/reflaxe.elixir/std\n# -lib reflaxe\n# --macro reflaxe.elixir.CompilerInit.Start()\n```\n\n### Usage in Your Project\n\nOnce installed, add to your `build.hxml`:\n\n```hxml\n-lib reflaxe.elixir\n-cp src_haxe\n\n# Output directory for generated .ex files\n-D elixir_output=lib/my_app_hx\n\n# Required for Reflaxe targets\n-D reflaxe_runtime\n\n# Elixir is not a UTF-16 platform\n-D no-utf16\n\n# Application module prefix (prevents collisions with Elixir built-ins like `Application`)\n-D app_name=MyAppHx\n\n# Enable dead code elimination to reduce output noise\n-dce full\n#\n# Why this repo recommends `-dce full`:\n# - Keeps generated `.ex` output small and readable (less stdlib/helpers noise).\n# - Makes snapshot diffs meaningful and keeps CI/budgets predictable.\n# - Catches “indirect runtime reference” regressions early (OTP/Phoenix callbacks/modules can be DCE’d otherwise).\n\n# Define a stable entrypoint\n# Entrypoint Haxe class (package.ClassName). Adjust to your app.\n--main my_app_hx.Main\n```\n\n### ⚠️ Important: Compiler Configuration\n\n**DO NOT use `-D analyzer-optimize`** when compiling to Elixir. This flag triggers aggressive optimizations designed for C++ and JavaScript that produce non-idiomatic Elixir code.\n\n**Recommended configuration:**\n```hxml\n# Good optimizations\n-dce full                    # Dead code elimination (recommended)\n-D loop_unroll_max_cost=0    # Disable loop unrolling (preserve functional shapes)\n\n# AVOID these\n# -D analyzer-optimize       # Destroys functional patterns\n# -D analyzer-check          # May trigger unwanted optimizations\n```\n\nFor complete compiler configuration guidance, see [docs/01-getting-started/compiler-flags-guide.md](docs/01-getting-started/compiler-flags-guide.md).\n\n## Quick Start\n\n### Start Here (New to Haxe and/or Phoenix?)\n\nFollow: `docs/01-getting-started/START_HERE.md`\n\n- Run the repo todo-app (end-to-end) with a single command\n- Learn the Haxe→Elixir→Phoenix mental model\n- Generate a fresh Phoenix+Haxe project via the generator\n\n### Hello Phoenix in ~5 minutes (no repo clone)\n\nThis creates a new Phoenix+Haxe project using the **latest GitHub release tag**:\n\n```bash\nmkdir haxir-demo \u0026\u0026 cd haxir-demo\nnpm init -y\nnpm install --save-dev lix\nnpx lix scope create\n\n# Install the generator (latest GitHub release tag)\n# If this fails (no `curl` / GitHub rate limit), pick a tag from the Releases page and set it manually.\nREFLAXE_ELIXIR_TAG=\"$(curl -fsSL https://api.github.com/repos/fullofcaffeine/reflaxe.elixir/releases/latest | sed -n 's/.*\\\"tag_name\\\":[[:space:]]*\\\"\\\\([^\\\"]*\\\\)\\\".*/\\\\1/p' | head -n 1)\"\nnpx lix install \"github:fullofcaffeine/reflaxe.elixir#${REFLAXE_ELIXIR_TAG}\"\n\n# Optional but recommended: pin a known-good Haxe toolchain (avoids relying on a global install).\nnpx lix download haxe 4.3.7\nnpx lix use haxe 4.3.7\n\n# Generate a Phoenix app\n# (Use `haxe --run Run` here because some lix/haxelib shim versions rely on an internal\n# `run-dir` command which is not reliable across environments.)\nREFLAXE_ELIXIR_SRC=\"$(./node_modules/.bin/haxelib path reflaxe.elixir | tr -d '\\r' | grep -E 'reflaxe\\.elixir/.*/src/?$' | head -n 1)\"\n./node_modules/.bin/haxe -cp \"$REFLAXE_ELIXIR_SRC\" --run Run create hello_haxir --type phoenix --no-interactive\n\ncd hello_haxir\nmix setup\nmix phx.server\n```\n\nSee also: `docs/06-guides/PHOENIX_NEW_APP.md`.\n\n### Quick Demo (Todo App)\n\nRun a full build + boot + Playwright smoke **without blocking your terminal**:\n\n```bash\nscripts/qa-sentinel.sh --app examples/todo-app --env e2e --port 4001 --playwright --e2e-spec \"e2e/*.spec.ts\" --async --deadline 900 --verbose\nscripts/qa-logpeek.sh --run-id \u003cRUN_ID\u003e --until-done 900\n```\n\n### Phoenix (Recommended Next Step)\n\n- New Phoenix project: `docs/06-guides/PHOENIX_NEW_APP.md`\n- Add Haxe gradually to an existing Phoenix project: `docs/06-guides/PHOENIX_GRADUAL_ADOPTION.md`\n\nAlso see: `docs/06-guides/QUICKSTART.md`\n\n## Development Workflow\n\n### Basic Compilation\n\n```bash\n# Compile once\nhaxe build.hxml\n\n# Watch for changes (long-running)\nmix haxe.watch\n```\n\n### Client Builds (JavaScript)\n\nFor Phoenix apps with client-side hooks, the recommended path is:\n\n- **Genes (recommended)**: ES modules + clean output via `-lib genes` (see `docs/05-architecture/HXML_ARCHITECTURE.md` and `examples/todo-app/build-client.hxml`).\n- **Plain Haxe JS target**: still works, but you’ll write more interop glue and typically won’t get ES module output.\n\n### Running Tests\n\n```bash\n# Full test suite (snapshots + Mix task tests)\nnpm test\n\n# Compile-check every example under examples/\nnpm run test:examples\n\n# Quick snapshot-only run\nnpm run test:quick\n```\n\n### Running Examples\n\nEach example is self-contained and documented. Start here:\n\n- `examples/README.md`\n\nMost examples can be compiled with:\n\n```bash\ncd examples/\u003cexample-name\u003e\nhaxe build.hxml   # or compile-all.hxml when present\n```\n\n### Phoenix Integration\n\n```bash\n# Add to your Phoenix project's mix.exs\ndefp deps do\n  [\n    # ... other deps\n    # Mix tasks only (build-time): pin to a GitHub release tag or use a commit SHA\n    # Replace \u003cRELEASE_TAG\u003e with the tag you installed via lix (e.g. v1.2.3)\n    {:reflaxe_elixir, github: \"fullofcaffeine/reflaxe.elixir\", tag: \"\u003cRELEASE_TAG\u003e\", only: [:dev, :test], runtime: false}\n  ]\nend\n\n\u003e Note: the `mix haxe.gen.*` generators are Haxe-first scaffolds (they emit **Haxe only**, not Elixir). Treat them as starting points and compare against `examples/todo-app/` for current Phoenix patterns. See `docs/04-api-reference/MIX_TASKS.md` for details.\n\n# Compile Haxe as part of your build\nmix compile.haxe\n\n# Start Phoenix with Haxe compilation\nmix phx.server\n```\n\n### File Organization\n\n```\nyour-project/\n├── src_haxe/              # Your Haxe source files\n│   ├── controllers/       # Phoenix controllers\n│   ├── live/             # LiveView modules  \n│   ├── contexts/         # Business logic\n│   └── schemas/          # Ecto schemas\n├── lib/                  # Generated Elixir files\n│   └── (compiled output)\n├── build.hxml            # Haxe build configuration\n└── mix.exs              # Phoenix/Elixir dependencies\n```\n\n## 📚 Documentation\n\nStart at **[docs/README.md](docs/README.md)** for the curated documentation index.\n\n### Quick Links\n- **[Installation Guide](docs/01-getting-started/installation.md)** - Setup and prerequisites\n- **[Quickstart](docs/06-guides/QUICKSTART.md)** - Your first Haxe→Elixir project\n- **[Phoenix (New App)](docs/06-guides/PHOENIX_NEW_APP.md)** - Greenfield Phoenix setup\n- **[Phoenix (Existing App)](docs/06-guides/PHOENIX_GRADUAL_ADOPTION.md)** - Add Haxe to an existing Phoenix app\n- **[Phoenix Integration](docs/02-user-guide/PHOENIX_INTEGRATION.md)** - Controllers, LiveView, Ecto, Channels\n- **[Escape Hatches](docs/02-user-guide/ESCAPE_HATCHES.md)** - Calling Elixir from Haxe safely\n- **[Known Limitations](docs/06-guides/KNOWN_LIMITATIONS.md)** - Sharp edges and experimental surfaces\n- **[Support Matrix](docs/06-guides/SUPPORT_MATRIX.md)** - CI-tested toolchain versions\n- **[Licensing \u0026 Distribution](docs/06-guides/LICENSING_AND_DISTRIBUTION.md)** - GPL notes (not legal advice)\n\n### Codegen Conventions\n- **[Writing Idiomatic Haxe](docs/02-user-guide/WRITING_IDIOMATIC_HAXE_FOR_ELIXIR.md)** - Practical guidance for clean, idiomatic Elixir output\n- **[Elixir Idioms \u0026 Hygiene](docs/02-user-guide/ELIXIR_IDIOMS_AND_HYGIENE.md)** - Naming, unused vars, enum shapes, and codegen conventions\n- **[Haxe→Elixir Mappings](docs/02-user-guide/HAXE_ELIXIR_MAPPINGS.md)** ✨ - Full mapping reference\n\n### Reference\n- **[Source Mapping Guide](docs/04-api-reference/SOURCE_MAPPING.md)** 🎯 - Complete guide to our pioneering source mapping feature\n- **[Annotations](docs/04-api-reference/ANNOTATIONS.md)** - Complete annotation reference\n- **[Troubleshooting](docs/06-guides/TROUBLESHOOTING.md)** - Common issues and solutions\n- **[Examples](examples/README.md)** - Working code examples (index)\n\n### Examples\n\nEach example includes its own `README.md` with compile/run steps:\n\n- `examples/01-simple-modules/README.md`\n- `examples/02-mix-project/README.md`\n- `examples/03-phoenix-app/README.md`\n- `examples/04-ecto-migrations/README.md`\n- `examples/05-heex-templates/README.md`\n- `examples/06-user-management/README.md`\n- `examples/07-protocols/README.md`\n- `examples/08-behaviors/README.md`\n- `examples/09-phoenix-router/README.md`\n- `examples/10-option-patterns/README.md`\n- `examples/11-domain-validation/README.md`\n- `examples/test-integration/README.md`\n- `examples/todo-app/README.md`\n\nYou can compile-check all examples with `npm run test:examples`.\n\n### Architecture\n- **[Architecture Overview](docs/05-architecture/ARCHITECTURE.md)** - Compiler internals\n- **[Testing Guide](docs/03-compiler-development/TESTING_INFRASTRUCTURE.md)** - Snapshot + integration testing system\n- **[Contributing](docs/10-contributing/contributing.md)** - Contributing and extending\n\n## Project Meta\n\n- `CONTRIBUTING.md` – contribution workflow and commands\n- `SECURITY.md` – vulnerability reporting process\n- `CODE_OF_CONDUCT.md` – community guidelines\n- `RELEASING.md` – release checklist and tagging\n\n### Manual Installation (For Contributors)\n\n```bash\n# Clone and setup\ngit clone https://github.com/fullofcaffeine/reflaxe.elixir\ncd reflaxe.elixir\n\n# Install dependencies (both ecosystems)\nnpm ci            # Installs lix + Haxe dependencies\nnpx lix download  # Downloads project-specific Haxe libraries\nmix deps.get      # Installs Elixir dependencies\n\n# Run tests\nnpm test          # Full suite (snapshots + Elixir validation + Mix)\nnpm run qa:sentinel  # Todo-app build + boot probe (async)\n```\n\n📖 **New to lix or Haxe?** See [docs/01-getting-started/installation.md](docs/01-getting-started/installation.md) for complete setup guide with troubleshooting.\n\n## Project Structure\n\nReflaxe.Elixir follows standard Reflaxe compiler conventions (similar to Reflaxe.CPP):\n\n```\nreflaxe.elixir/\n├── src/                    # Compiler source (macro-time transpiler code)\n│   └── reflaxe/elixir/     # ElixirCompiler.hx and helpers\n├── std/                    # Standard library (compile-time classpath)\n│   ├── elixir/             # Elixir stdlib externs (IO, File, GenServer, etc.)\n│   ├── phoenix/            # Phoenix framework externs (LiveView, Socket, etc.)\n│   └── ecto/               # Ecto ORM externs (Schema, Changeset, Query)\n├── lib/                    # Elixir runtime support (Mix integration)\n│   ├── haxe_compiler.ex    # Mix compilation task\n│   ├── haxe_watcher.ex     # File watching for development\n│   └── haxe_server.ex      # Haxe compilation server wrapper\n├── test/                   # Compiler tests (snapshot testing)\n└── examples/               # Example applications\n    └── todo-app/           \n        └── src_haxe/       # User application code in Haxe\n```\n\n### Directory Purposes\n\n- **`src/`** - The compiler that transforms Haxe TypedExpr → ElixirAST → transforms → printed Elixir\n- **`std/`** - Haxe externs and abstractions for Elixir/Phoenix/Ecto functionality (included via `-lib reflaxe.elixir` or vendoring)\n- **`lib/`** - Elixir runtime files needed for Mix integration and compilation support\n- **`src_haxe/`** - User application code written in Haxe (in examples)\n\nThis separation follows Reflaxe conventions and ensures clear boundaries between compiler code, standard library, and user application code.\n\n## Architecture\n\nReflaxe.Elixir uses a **dual-ecosystem architecture**:\n\n### 🔧 Haxe Development (npm + lix)\n- **Compiler development**: Build the Haxe→Elixir compiler\n- **Modern testing**: tink_unittest + tink_testrunner with rich output\n- **Dependency management**: lix with GitHub sources + locked versions\n\n### ⚡ Elixir Runtime (mix)  \n- **Generated code testing**: Validate compiled Elixir modules\n- **Phoenix integration**: Test LiveView, Ecto, GenServer workflows\n- **Native tooling**: Standard mix tasks and BEAM ecosystem\n\n## Usage\n\n### Source Mapping (Experimental)\n\nReflaxe.Elixir has early scaffolding for Haxe→Elixir source mapping, but it is not yet fully wired end‑to‑end (map emission + runtime lookup).\n\nSee `docs/04-api-reference/SOURCE_MAPPING.md` for current status and how to experiment.\n\n### Phoenix LiveView\n```haxe\n\timport HXX;\n\timport elixir.types.Term;\n\timport phoenix.LiveSocket;\n\timport phoenix.Phoenix.HandleEventResult;\n\timport phoenix.Phoenix.MountResult;\n\timport phoenix.Phoenix.Socket;\n\ntypedef CounterAssigns = { count: Int };\n\n\t@:native(\"MyAppWeb.CounterLive\")\n\t@:liveview\n\tclass CounterLive {\n\t    public static function mount(_params: Term, _session: Term, socket: Socket\u003cCounterAssigns\u003e): MountResult\u003cCounterAssigns\u003e {\n\t        var liveSocket: LiveSocket\u003cCounterAssigns\u003e = socket;\n\t        liveSocket = liveSocket.assign(_.count, 0);\n\t        return MountResult.Ok(liveSocket);\n\t    }\n\n\t    @:native(\"handle_event\")\n\t    public static function handle_event(event: String, _params: Term, socket: Socket\u003cCounterAssigns\u003e): HandleEventResult\u003cCounterAssigns\u003e {\n\t        var liveSocket: LiveSocket\u003cCounterAssigns\u003e = socket;\n\n        return switch (event) {\n            case \"increment\":\n                var nextCount = liveSocket.assigns.count + 1;\n                HandleEventResult.NoReply(liveSocket.assign(_.count, nextCount));\n            case _:\n                HandleEventResult.NoReply(liveSocket);\n        }\n    }\n\n    public static function render(assigns: CounterAssigns): String {\n        return HXX.hxx('\n            \u003cdiv class=\"counter\"\u003e\n                \u003ch1\u003e${assigns.count}\u003c/h1\u003e\n                \u003cbutton phx-click=\"increment\"\u003e+\u003c/button\u003e\n            \u003c/div\u003e\n        ');\n    }\n}\n```\n\nCompiles to:\n```elixir  \ndefmodule CounterLive do\n  use Phoenix.LiveView\n  \n  def mount(_params, _session, socket) do\n    {:ok, assign(socket, :count, 0)}\n  end\n  \n  def handle_event(\"increment\", _params, socket) do\n    count = socket.assigns.count + 1\n    {:noreply, assign(socket, :count, count)}\n  end\n  \n  def render(assigns) do\n    ~H\"\"\"\n    \u003cdiv class=\"counter\"\u003e\n      \u003ch1\u003e{assigns.count}\u003c/h1\u003e\n      \u003cbutton phx-click=\"increment\"\u003e+\u003c/button\u003e\n    \u003c/div\u003e\n    \"\"\"\n  end\nend\n```\n\nNote: the Haxe return values are enums (`MountResult.Ok(...)`, `HandleEventResult.NoReply(...)`), which compile to the standard Elixir atom-tagged tuples (`{:ok, ...}`, `{:noreply, ...}`).\n\n### Ecto Changesets\n```haxe\n@:changeset  \nclass UserChangeset {\n    @:validate_required([\"name\", \"email\"])\n    @:validate_format(\"email\", ~r/\\S+@\\S+\\.\\S+/)\n    static function changeset(user, attrs) {\n        // Compiled to proper Ecto.Changeset pipeline\n    }\n}\n```\n\n### OTP GenServer\n```haxe\nimport elixir.types.Atom;\nimport elixir.types.GenServerCallbackResults.HandleCallResult;\nimport elixir.types.GenServerCallbackResults.InitResult;\nimport elixir.types.Term;\n\nenum abstract CounterCall(Atom) to Atom {\n    var Get = \"get\";\n    var Increment = \"increment\";\n}\n\n@:genserver\nclass CounterServer {\n    public static function init(initial: Int): InitResult\u003cInt\u003e {\n        return InitResult.Ok(initial);\n    }\n\n    @:native(\"handle_call\")\n    public static function handle_call(request: CounterCall, _from: Term, state: Int): HandleCallResult\u003cInt, Int\u003e {\n        return switch (request) {\n            case Get:\n                HandleCallResult.Reply(state, state);\n            case Increment:\n                HandleCallResult.Reply(state + 1, state + 1);\n        }\n    }\n}\n```\n\n## Development\n\n### Testing\n\nThe project uses a dual-ecosystem testing approach with self-referential library configuration:\n\n```bash\nnpm test              # Full suite (snapshots + Elixir validation + Mix)\nnpm run test:quick    # Snapshot suite only\nnpm run test:mix      # Mix/Elixir tests only\nnpm run test:generator # Generator + Mix task scaffolds\nnpm run test:update   # Update expected snapshot outputs\nnpm run qa:sentinel   # Todo-app build + boot probe (async)\nnpm run ci:guards     # Guardrails (no app heuristics, etc.)\n```\n\n**Test Infrastructure:**\n- **Complete Coverage**: `npm test` runs Haxe compiler tests, generator tests, AND Mix runtime tests\n- **Snapshot Testing**: Validates compiler output against expected Elixir code\n- **Generator Testing**: Validates project templates and tooling\n- **Runtime Validation**: Mix tests compile/run generated Elixir code\n- **Self-Referential Library**: Tests use `-lib reflaxe.elixir` via `haxe_libraries/reflaxe.elixir.hxml`\n- **Mix Integration**: Tests real compilation in Phoenix projects\n- **Test Helper**: `test/support/haxe_test_helper.ex` handles project setup\n\n**⚠️ Critical**: For self-referential library configuration issues, see [docs/06-guides/SELF_REFERENTIAL_LIBRARY_TROUBLESHOOTING.md](docs/06-guides/SELF_REFERENTIAL_LIBRARY_TROUBLESHOOTING.md)\n\nFor detailed testing documentation, see [docs/03-compiler-development/TESTING_INFRASTRUCTURE.md](docs/03-compiler-development/TESTING_INFRASTRUCTURE.md)\n\n### Development Workflow\n```bash\n# Start file watching for instant feedback\nmix haxe.watch\n\n# In another terminal, make changes\nvim src_haxe/MyModule.hx  # Files auto-compile on save\n\n# Or for compiler development:\nvim src/reflaxe/elixir/ElixirCompiler.hx\nnpm test  # Test compiler changes\n```\n\n### LLM Development  \nPerfect for AI-assisted development with fast feedback loops:\n```bash\n# Start watching with LLM-friendly output\nmix haxe.watch --verbose\n\n# LLM creates/modifies .hx files → automatic compilation\n# Sub-second feedback enables rapid iteration\n```\n\n## Package Management\n\n### Why lix + npm?\n- **lix**: Modern Haxe package manager with GitHub sources\n- **npm**: JavaScript ecosystem integration and script orchestration  \n- **Benefits**: Project-specific Haxe versions, zero global conflicts\n\n### Why mix?\n- **Native Elixir tooling**: Industry standard for BEAM development\n- **Phoenix ecosystem**: Seamless LiveView, Ecto, OTP integration\n- **Generated code validation**: Tests the actual output, not just compilation\n\n## Performance\n\nAll compilation targets exceed performance requirements:\n\n- **Basic compilation**: 0.015ms (750x faster than 15ms target) ⚡\n- **Ecto Changesets**: 0.006ms average (2500x faster) ⚡  \n- **Migration DSL**: 6.5μs per migration (2300x faster) ⚡\n- **OTP GenServer**: 0.07ms average (214x faster) ⚡\n- **Phoenix LiveView**: \u003c1ms average (15x faster) ⚡\n\n## Verification\n\nCI is the source of truth (see the CI badge above). Locally:\n\n### New-user quickcheck (install from GitHub release tag)\n\nThis validates that a brand-new project can install Reflaxe.Elixir from a `vX.Y.Z` release and compile a generated Phoenix app.\n\n```bash\nmkdir -p /tmp/reflaxe_elixir_verify \u0026\u0026 cd /tmp/reflaxe_elixir_verify\nnpm init -y\nnpm install --save-dev lix\nnpx lix scope create\n\n# Pin a known-good Haxe toolchain (avoids relying on a global install).\nnpx lix download haxe 4.3.7\nnpx lix use haxe 4.3.7\n\n# Install the latest GitHub release tag (recommended).\n# If this fails (no `curl` / GitHub rate limit), pick a tag from the Releases page and set it manually.\nREFLAXE_ELIXIR_TAG=\"$(curl -fsSL https://api.github.com/repos/fullofcaffeine/reflaxe.elixir/releases/latest | sed -n 's/.*\\\"tag_name\\\":[[:space:]]*\\\"\\\\([^\\\"]*\\\\)\\\".*/\\\\1/p' | head -n 1)\"\nnpx lix install \"github:fullofcaffeine/reflaxe.elixir#${REFLAXE_ELIXIR_TAG}\"\nnpx lix download\n\n# Generate + compile a Phoenix app (compile-only smoke)\nREFLAXE_ELIXIR_SRC=\"$(./node_modules/.bin/haxelib path reflaxe.elixir | tr -d '\\r' | grep -E 'reflaxe\\.elixir/.*/src/?$' | head -n 1)\"\n./node_modules/.bin/haxe -cp \"$REFLAXE_ELIXIR_SRC\" --run Run create my_app --type phoenix --no-interactive --skip-install\ncd my_app\nnpm install --no-audit --no-fund\nnpx lix scope create\nnpx lix install \"github:fullofcaffeine/reflaxe.elixir#${REFLAXE_ELIXIR_TAG}\"\nnpx lix download\nmix deps.get\nmix compile\n```\n\n\u003e Maintainers: this flow is also verified weekly in CI by the scheduled workflow\n\u003e **README Release Smoke (scheduled)**.\n\n### Repo verification (contributors / maintainers)\n\n- `npm run ci:guards`\n- `npm test`\n- `npm run test:examples`\n- `npm run test:examples-elixir`\n- `npm run ci:budgets`\n- `npm run qa:sentinel` (todo-app boot + Playwright smoke; non-blocking)\n\n## Contributing\n\nSee [docs/10-contributing/contributing.md](docs/10-contributing/contributing.md) for detailed development guide.\nReleases are published automatically via semantic versioning; see [docs/10-contributing/RELEASING.md](docs/10-contributing/RELEASING.md).\n\n### Adding Features\n1. Extend the AST pipeline (`src/reflaxe/elixir/ast/`) in builder/transformer/printer layers\n2. Add/adjust std externs in `std/` when exposing Elixir/Phoenix/Ecto APIs\n3. Add snapshot coverage under `test/snapshot/` (and update intended outputs if needed)\n4. Run `npm test` and `npm run qa:sentinel`\n\n## Roadmap\n\n- Near-term priorities: [ROADMAP.md](ROADMAP.md)\n- Long-term direction: [docs/08-roadmap/vision.md](docs/08-roadmap/vision.md)\n- 1.0 readiness checklist: [docs/06-guides/PRODUCTION_READINESS.md](docs/06-guides/PRODUCTION_READINESS.md)\n\n## License\n\nGPL-3.0 - See [LICENSE](LICENSE) for details\n\n## Links\n\n- [Haxe](https://haxe.org) - The cross-platform toolkit  \n- [Reflaxe](https://github.com/SomeRanDev/reflaxe) - Haxe-to-everything compiler framework\n- [Elixir](https://elixir-lang.org) - Dynamic, functional language for BEAM\n- [Phoenix](https://phoenixframework.org) - Productive web framework  \n- [lix](https://github.com/lix-pm/lix.client) - Modern Haxe package manager\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Freflaxe.elixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullofcaffeine%2Freflaxe.elixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Freflaxe.elixir/lists"}