https://github.com/srdjan/flea
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.
https://github.com/srdjan/flea
elm-lang flix spa ui web
Last synced: 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/srdjan/flea
- Owner: srdjan
- License: mit
- Created: 2025-09-28T21:39:33.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-29T18:25:08.000Z (9 months ago)
- Last Synced: 2026-04-08T12:35:28.808Z (3 months ago)
- Topics: elm-lang, flix, spa, ui, web
- Language: Flix
- Homepage:
- Size: 8.79 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Flea: Light Functional Programming Architecture (Flix)
[](LICENSE)
Flea is a pragmatic Light Functional Programming (Light FP) 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.
- Pure, testable core (no I/O in the domain)
- Side effects isolated behind effects/handlers at the edges
- Errors as values (Result[t, e])
- Elm Architecture influence for model–update–view
---
## 1) Project Overview
Flea provides a lightweight foundation and set of conventions for writing Flix
programs and libraries with functional design. You model the domain with types,
keep business logic pure, and compose effects at the boundaries using handlers.
Typical use cases:
- Libraries that want clear, composable APIs with predictable behavior
- Services/CLIs with testable core logic and effectful adapters
- UI or WASM-backed apps (see `web/`) that compose pure logic with DOM handlers
---
## 2) Architecture Philosophy (Light FP)
Three core pillars guide this codebase:
1. Model with types first; make illegal states unrepresentable
- Use Flix algebraic data types (enums) and records to encode domain states.
- Prefer precise types and smart constructors to eliminate invalid states.
2. Keep the core pure (no I/O); push effects to edges
- Domain logic is pure and deterministic.
- All I/O (time, random, FS/DB/HTTP/DOM, etc.) is expressed as effects and
handled by interpreters at the boundaries (handlers).
3. Treat errors as values (Result[t, e])
- No exceptions in domain code.
- Return explicit `Result` values and handle them with pattern matching.
---
## 3) Elm Architecture Influence
We draw from The Elm Architecture (TEA):
- Model: immutable data representing state
- Msg: events describing what happened
- update: pure function `(model, msg) -> model` (plus requested effects)
- view: pure(ish) projection of the model to outputs
In Flea, side effects are not performed in `update`; they are expressed as
requests (effects) and interpreted by handlers. This yields predictable state
transitions and makes testing straightforward.
---
## 4) Algebraic Effects (and how Flea uses them)
Read: https://interjectedfuture.com/elm-should-have-had-algebraic-effects/
Flix supports algebraic effects and handlers natively. Flea embraces this to
keep core logic pure while declaring what effects are needed. Handlers implement
those needs at the edges (e.g., real console, time, HTTP, DOM). In other
ecosystems we might call this a “ports pattern”; in Flix, it maps directly to
effect signatures and handlers.
---
## 5) Getting Started
Prerequisites:
- Flix CLI (see https://flix.dev) and Java 17+
Common commands (from repo root):
```sh
# compile/check
flix build
# run tests
flix test
# interactive REPL
flix repl
```
Running examples:
- Open the REPL (`flix repl`) and evaluate the entry function from `examples/*`,
or
- Provide a `main` function and run it via `flix run` (configure as needed).
---
## 6) Project Structure
Actual layout in this repo:
```
src/Flea/ # Core library sources
Core.flix # Core abstractions and helpers
Runtime.flix # Runtime composition and orchestration
VNode.flix # Virtual DOM primitives
Effects/ # Effect signatures
Handlers/ # Effect handlers (interpreters)
Testkit/ # Test helpers and mock handlers
examples/
counter/Counter.flix
search/Search.flix
todo/Todo.flix
tests/ # Flix test suites
TestCounter.flix
TestSearch.flix
TestUiDomMock.flix
TestVirtualTime.flix
docs/
01-architecture.md
02-effects-and-handlers.md
03-testing.md
04-dom-handler.md
web/ # Optional browser/WASM integration scaffolding
```
---
## 7) Key Patterns (tiny Flix examples)
Result type (errors as values):
```flix
enum Result[t, e] { Ok(t), Err(e) }
```
Elm-style model, msg, update:
```flix
type alias Model = { count: Int };
enum Msg { Inc, Dec }
let update(m: Model, msg: Msg): Model =
match (msg) { case Inc => { m with count = m.count + 1 }
case Dec => { m with count = m.count - 1 } }
```
Pattern matching on Result:
```flix
let mapRes(f: a -> b, r: Result[a, e]): Result[b, e] =
match (r) { case Ok(x) => Ok(f(x)); case Err(e) => Err(e) }
```
For effects and handlers, see `docs/02-effects-and-handlers.md` and the testkit.
---
## 8) Development Workflow
- Write pure domain logic first (no I/O in core functions)
- Declare effects where side effects are required; implement handlers at edges
- Compose the runtime by wiring handlers (e.g., real vs. test adapters)
- Prefer unit tests for pure logic; use mock handlers from `Testkit/` for
effects
Common commands:
```sh
flix test # run tests
flix build # compile/check
flix repl # explore interactively
```
---
## 9) Contributing Guidelines
Code style & architecture:
- Prefer ADTs and records to encode domain states
- Keep core pure; no exceptions in domain logic
- Use algebraic effects to express capabilities; handle them at the edges
- Make illegal states unrepresentable
Testing:
- Thorough unit tests for pure functions
- Use mock handlers from `Testkit/` for effectful scenarios
- No real network/DB in unit tests
Process:
- Create small, focused PRs
- Ensure `flix test` passes before requesting review
- Document noteworthy design decisions in `docs/`
## 10) License
This project is licensed under the MIT License. See the LICENSE file for
details.
---
## Further Reading
- Algebraic Effects (Elm motivation):
https://interjectedfuture.com/elm-should-have-had-algebraic-effects/
- Flix language & docs: https://flix.dev
- Functional programming overview:
https://en.wikipedia.org/wiki/Functional_programming