{"id":31628253,"url":"https://github.com/srdjan/flea","last_synced_at":"2026-04-19T15:04:29.385Z","repository":{"id":317249543,"uuid":"1066009680","full_name":"srdjan/flea","owner":"srdjan","description":"Flea is a pragmatic Light Functional Programming library built in Flix. It helps you structure applications around pure domain logic, predictable state transitions (Elm-inspired), and explicit control of side effects via algebraic effects and handlers.","archived":false,"fork":false,"pushed_at":"2025-09-29T18:25:08.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T12:35:28.808Z","etag":null,"topics":["elm-lang","flix","spa","ui","web"],"latest_commit_sha":null,"homepage":"","language":"Flix","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/srdjan.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T21:39:33.000Z","updated_at":"2025-09-29T12:55:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"6e5f1459-e73a-400c-a26a-47a655be838d","html_url":"https://github.com/srdjan/flea","commit_stats":null,"previous_names":["srdjan/flea"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/srdjan/flea","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srdjan%2Fflea","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srdjan%2Fflea/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srdjan%2Fflea/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srdjan%2Fflea/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srdjan","download_url":"https://codeload.github.com/srdjan/flea/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srdjan%2Fflea/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32010960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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":["elm-lang","flix","spa","ui","web"],"created_at":"2025-10-06T20:21:09.141Z","updated_at":"2026-04-19T15:04:29.377Z","avatar_url":"https://github.com/srdjan.png","language":"Flix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flea: Light Functional Programming Architecture (Flix)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nFlea is a pragmatic Light Functional Programming (Light FP) library built in\nFlix. It helps you structure applications around pure domain logic, predictable\nstate transitions (Elm-inspired), and explicit control of side effects via\nalgebraic effects and handlers.\n\n- Pure, testable core (no I/O in the domain)\n- Side effects isolated behind effects/handlers at the edges\n- Errors as values (Result[t, e])\n- Elm Architecture influence for model–update–view\n\n---\n\n## 1) Project Overview\n\nFlea provides a lightweight foundation and set of conventions for writing Flix\nprograms and libraries with functional design. You model the domain with types,\nkeep business logic pure, and compose effects at the boundaries using handlers.\n\nTypical use cases:\n\n- Libraries that want clear, composable APIs with predictable behavior\n- Services/CLIs with testable core logic and effectful adapters\n- UI or WASM-backed apps (see `web/`) that compose pure logic with DOM handlers\n\n---\n\n## 2) Architecture Philosophy (Light FP)\n\nThree core pillars guide this codebase:\n\n1. Model with types first; make illegal states unrepresentable\n   - Use Flix algebraic data types (enums) and records to encode domain states.\n   - Prefer precise types and smart constructors to eliminate invalid states.\n\n2. Keep the core pure (no I/O); push effects to edges\n   - Domain logic is pure and deterministic.\n   - All I/O (time, random, FS/DB/HTTP/DOM, etc.) is expressed as effects and\n     handled by interpreters at the boundaries (handlers).\n\n3. Treat errors as values (Result[t, e])\n   - No exceptions in domain code.\n   - Return explicit `Result` values and handle them with pattern matching.\n\n---\n\n## 3) Elm Architecture Influence\n\nWe draw from The Elm Architecture (TEA):\n\n- Model: immutable data representing state\n- Msg: events describing what happened\n- update: pure function `(model, msg) -\u003e model` (plus requested effects)\n- view: pure(ish) projection of the model to outputs\n\nIn Flea, side effects are not performed in `update`; they are expressed as\nrequests (effects) and interpreted by handlers. This yields predictable state\ntransitions and makes testing straightforward.\n\n---\n\n## 4) Algebraic Effects (and how Flea uses them)\n\nRead: https://interjectedfuture.com/elm-should-have-had-algebraic-effects/\n\nFlix supports algebraic effects and handlers natively. Flea embraces this to\nkeep core logic pure while declaring what effects are needed. Handlers implement\nthose needs at the edges (e.g., real console, time, HTTP, DOM). In other\necosystems we might call this a “ports pattern”; in Flix, it maps directly to\neffect signatures and handlers.\n\n---\n\n## 5) Getting Started\n\nPrerequisites:\n\n- Flix CLI (see https://flix.dev) and Java 17+\n\nCommon commands (from repo root):\n\n```sh\n# compile/check\nflix build\n# run tests\nflix test\n# interactive REPL\nflix repl\n```\n\nRunning examples:\n\n- Open the REPL (`flix repl`) and evaluate the entry function from `examples/*`,\n  or\n- Provide a `main` function and run it via `flix run` (configure as needed).\n\n---\n\n## 6) Project Structure\n\nActual layout in this repo:\n\n```\nsrc/Flea/           # Core library sources\n  Core.flix         # Core abstractions and helpers\n  Runtime.flix      # Runtime composition and orchestration\n  VNode.flix        # Virtual DOM primitives\n  Effects/          # Effect signatures\n  Handlers/         # Effect handlers (interpreters)\n  Testkit/          # Test helpers and mock handlers\nexamples/\n  counter/Counter.flix\n  search/Search.flix\n  todo/Todo.flix\ntests/              # Flix test suites\n  TestCounter.flix\n  TestSearch.flix\n  TestUiDomMock.flix\n  TestVirtualTime.flix\ndocs/\n  01-architecture.md\n  02-effects-and-handlers.md\n  03-testing.md\n  04-dom-handler.md\nweb/                # Optional browser/WASM integration scaffolding\n```\n\n---\n\n## 7) Key Patterns (tiny Flix examples)\n\nResult type (errors as values):\n\n```flix\nenum Result[t, e] { Ok(t), Err(e) }\n```\n\nElm-style model, msg, update:\n\n```flix\ntype alias Model = { count: Int };\nenum Msg { Inc, Dec }\nlet update(m: Model, msg: Msg): Model =\n  match (msg) { case Inc =\u003e { m with count = m.count + 1 }\n                case Dec =\u003e { m with count = m.count - 1 } }\n```\n\nPattern matching on Result:\n\n```flix\nlet mapRes(f: a -\u003e b, r: Result[a, e]): Result[b, e] =\n  match (r) { case Ok(x) =\u003e Ok(f(x)); case Err(e) =\u003e Err(e) }\n```\n\nFor effects and handlers, see `docs/02-effects-and-handlers.md` and the testkit.\n\n---\n\n## 8) Development Workflow\n\n- Write pure domain logic first (no I/O in core functions)\n- Declare effects where side effects are required; implement handlers at edges\n- Compose the runtime by wiring handlers (e.g., real vs. test adapters)\n- Prefer unit tests for pure logic; use mock handlers from `Testkit/` for\n  effects\n\nCommon commands:\n\n```sh\nflix test   # run tests\nflix build  # compile/check\nflix repl   # explore interactively\n```\n\n---\n\n## 9) Contributing Guidelines\n\nCode style \u0026 architecture:\n\n- Prefer ADTs and records to encode domain states\n- Keep core pure; no exceptions in domain logic\n- Use algebraic effects to express capabilities; handle them at the edges\n- Make illegal states unrepresentable\n\nTesting:\n\n- Thorough unit tests for pure functions\n- Use mock handlers from `Testkit/` for effectful scenarios\n- No real network/DB in unit tests\n\nProcess:\n\n- Create small, focused PRs\n- Ensure `flix test` passes before requesting review\n- Document noteworthy design decisions in `docs/`\n\n## 10) License\n\nThis project is licensed under the MIT License. See the LICENSE file for\ndetails.\n\n---\n\n## Further Reading\n\n- Algebraic Effects (Elm motivation):\n  https://interjectedfuture.com/elm-should-have-had-algebraic-effects/\n- Flix language \u0026 docs: https://flix.dev\n- Functional programming overview:\n  https://en.wikipedia.org/wiki/Functional_programming\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrdjan%2Fflea","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrdjan%2Fflea","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrdjan%2Fflea/lists"}