Almost every project I've worked on has a .github/workflows/ci.yml that does roughly the same thing. Install the SDK with a setup action written and maintained by someone else, run pub get against pub.dev on a fresh runner, run the tests, push the result. The green check at the bottom of the PR is technically a proof that the tests passed — in a slightly different toolchain than the one on my laptop, against a slightly different snapshot of the dependencies, on a machine that trusted three external systems to behave the same way they did the last time.

For a small library that's fine. For a small library you want to publish to pub.dev and ask other people to depend on, it is also fine, in the way that a lot of things are fine until they aren't.

I just shipped caffeine 3.0 and redid the CI as strictly Nix. Not Nix wrapping setup-dart, but Nix end to end. The dev shell, the test runner, the lockfile handling, the platform deps, the workflow YAML itself — all materialized by the flake. The GitHub Actions runner does the smallest possible job: install Nix, evaluate a matrix from the flake, fan out one runner per check, go home.

What runs

flake show, trimmed:

github:purplenoodlesoop/caffeine
├───apps.x86_64-linux.sync-ci
├───checks.x86_64-linux
│   ├───caffeine
│   ├───flutter-caffeine
│   └───ci-up-to-date
├───devShells.x86_64-linux.default
├───githubActions
└───packages.x86_64-linux.ci-yaml

Three checks (one per package, plus a drift check on the workflow file itself), one dev shell, one package that is the rendered workflow YAML, one app that copies the rendered YAML into the working tree. githubActions is the matrix the workflow consumes — generated by nix-community/nix-github-actions from the checks attribute set, so the matrix and the actual list of checks share one source.

The workflow definition lives in nix/ci.nix:

let
  checkoutStep = { name = "Checkout"; uses = "actions/checkout@v4"; };
  installNixStep = {
    name = "Install Nix";
    uses = "DeterminateSystems/nix-installer-action@v22";
    "with".determinate = false;
  };
  magicCacheStep = {
    name = "Magic Nix Cache";
    uses = "DeterminateSystems/magic-nix-cache-action@v13";
  };
in
{
  name = "ci";
  on = {
    push.branches = [ "master" ];
    pull_request = { };
    workflow_dispatch = { };
  };
  jobs = {
    matrix = {
      runs-on = "ubuntu-latest";
      outputs.matrix = "\${{ steps.set-matrix.outputs.matrix }}";
      steps = [
        checkoutStep
        installNixStep
        {
          id = "set-matrix";
          name = "Generate matrix";
          run = ''
            matrix="$(nix eval --json '.#githubActions.matrix')"
            echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
          '';
        }
      ];
    };

    check = {
      name = "\${{ matrix.name }}";
      needs = "matrix";
      runs-on = "\${{ matrix.os }}";
      strategy = {
        fail-fast = false;
        matrix = "\${{ fromJSON(needs.matrix.outputs.matrix) }}";
      };
      steps = [
        checkoutStep
        installNixStep
        magicCacheStep
        { name = "Build check"; run = "nix build -L '.#\${{ matrix.attr }}'"; }
      ];
    };
  };
}

A Nix attrset. Triggers, concurrency, jobs, steps — all just fields. The matrix job evaluates the flake and emits one entry per check. The check job fans out — caffeine, flutter-caffeine, ci-up-to-date each on its own runner, each as its own status check in the PR. Adding a new check to flake.nix adds a status line to the next PR without touching this file.

The runner has zero direct knowledge of dart, flutter, pub, package_config.json or the workspace layout. It does nix build -L .#<attr> and reports the exit code.

The check derivation is the interesting part

checks.<system>.caffeine is a buildDartApplication derivation whose checkPhase runs the tests inside the Nix sandbox. The sandbox has no network. Everything has to be in the closure already.

Three things had to be true at the same time.

First, pub2nix needs the workspace lockfile as a Nix value, and it is YAML on disk. Convert it inline:

runCommand "${pname}-pubspec.lock.json"
  { nativeBuildInputs = [ yq-go ]; }
  "yq -o=json . ${src}/pubspec.lock > $out"

This is import-from-derivation, so nix flake check pauses briefly to materialize the JSON before evaluating the rest. Slightly slower, never wrong, no committed pubspec.lock.json to keep in sync with the YAML one.

Second, dart test calls pub.Entrypoint.ensureUpToDate at startup. That function compares the on-disk lockfile against the generated package_config.json and reaches for pub.dev if it doesn't like what it sees. There is no --no-pub flag on dart test. The trick is a tiny bash helper that dartConfigHook already installs into the build shell:

checkPhase = ''
  cp -rL . "$TMPDIR/src"
  chmod -R u+w "$TMPDIR/src"
  cp -rL "$TMPDIR/src/.dart_tool" "$TMPDIR/src/packages/caffeine/"
  cd "$TMPDIR/src/packages/caffeine"
  HOME=$TMPDIR packageRun test --reporter expanded
'';

packageRun test resolves to dart --packages=.dart_tool/package_config.json <test-pkg>/bin/test.dart. No pub on the call path, no ensureUpToDate, no network probe. Just the Dart VM running the test runner with an explicit package config.

Third, the workspace has to be invisible at test time. Otherwise dart test walks into the Flutter example as a sibling workspace member and demands the Flutter SDK. After dartConfigHook has built package_config.json (which needs the workspace declaration so workspace members get added to the config), strip both keys:

sed -i '/^workspace:$/,$d' pubspec.yaml
sed -i '/^resolution: workspace$/d' packages/caffeine/pubspec.yaml

Order matters. Strip in postPatch and workspacePackageConfigScript sees no workspace and never adds caffeine to the config (package:caffeine resolves to nothing, tests fail to compile). Strip in checkPhase and you keep the config but lose the workspace at runtime. The fix is the second option.

The workflow itself is also Nix

The .github/workflows/ci.yml file is a generated artifact:

ci-yaml-body = (pkgs.formats.yaml { }).generate "ci-body.yml"
  (import ./nix/ci.nix);

ci-yaml = pkgs.runCommand "ci.yml" { } ''
  cat > $out <<'HEADER'
  # AUTO-GENERATED from nix/ci.nix — DO NOT EDIT BY HAND.
  # Regenerate with: nix run .#sync-ci
  HEADER
  cat ${ci-yaml-body} >> $out
'';

nix/ci.nix is the workflow as a Nix attrset. Triggers, concurrency group, steps — all name = "..."; on = { ... };-style fields. pkgs.formats.yaml renders it. The wrapping runCommand prepends the do-not-edit header so the rendered file is self-explaining about how it got there.

apps.sync-ci is a writeShellApplication that copies the rendered YAML into .github/workflows/ci.yml at the working tree's root. It has to be a real committed file — GitHub Actions runners can't follow /nix/store/... paths, so we generate and commit, not symlink.

Drift is caught by another check. checks.<sys>.ci-up-to-date is a runCommand that diffs the committed file against the rendered one:

ci-up-to-date = pkgs.runCommand "ci-up-to-date" { } ''
  if ! diff -u ${./.github/workflows/ci.yml} ${ci-yaml}; then
    echo "❌ .github/workflows/ci.yml is out of sync with nix/ci.nix."
    echo "   Run: nix run .#sync-ci"
    exit 1
  fi
  touch $out
'';

If somebody hand-edits the workflow, the next CI run fails with a message telling them to regenerate. If somebody edits nix/ci.nix without running sync-ci, same failure. There is no third option, which is the whole point.

What it costs

Honest numbers. Cold run, empty cache: ~10–12 minutes. About 8 of those go to the post-job step uploading freshly realized /nix/store paths to GitHub Actions Cache (the Flutter SDK alone, even though we never flutter build, contributes ~150 MB of pre-bundled Linux engine artifacts — buildFlutterApplication's Linux variant pulls in wrapGAppsHook3 and friends regardless of whether you actually build anything for Linux). Warm run, no dependency changes: each check finishes in ~1–2 minutes on its own runner, ~3 minutes wall time including the matrix-evaluation job.

For comparison, the same project with subosito/flutter-action and dart test runs in ~1–2 minutes cold and ~45 seconds warm. Strictly Nix is roughly 5× slower cold and 3× slower warm. That cost is real and not going away — sandboxed builds, plus each matrix runner installing Nix from scratch, plus magic-nix-cache's upload phase, are the price.

What you get for the price is small but specific. The same nix build .#<attr> invocation runs identically on my Mac and on ubuntu-latest. Setting up the project on a fresh machine is git clone && nix develop and the toolchain is at the version pinned in flake.lock, not at whatever setup-dart@v1 resolves to today. When something breaks, the breakage is reproducible — which is the only kind of breakage worth fixing.

The value of doing CI this way only shows up the day something does break. If your hermetic test never tells you anything you didn't already know, it isn't hermetic. The whole pipeline has to be tight enough that the next surprise it produces is reproducible.

Where to look

• flake.nix — top-level wiring, dev shell, checks, packages, apps, githubActions matrix
• nix/mk-check.nix — shared check builder used by both packages
• nix/ci.nix — workflow as a Nix attrset
• .github/workflows/ci.yml — the generated file (do not edit)

• https://github.com/purplenoodlesoop/hsdart

Why?

There's a Dart package on pub.dev called pixer. It's a Flutter image manipulation library, and the interesting part isn't the API. It's that the implementation is Rust, called from Dart through FFI, with a build hook that stages prebuilt binaries during the Flutter build. The Dart developer writes nothing about Rust. They just import and call.

A nice pattern. The question that has been bugging me is whether we can do the same thing with Haskell. Not "is it possible to call Haskell from Dart", which is trivially yes (foreign export ccall on one side, @Native on the other, you're done), but "can we make it pleasant enough that the user just writes Haskell functions and they show up in Dart, without spelling out the same C ABI three times by hand".

That's what hsdart is. A pilot micro-framework, a worked Flutter example, and a benchmark that says the answer is "kinda yes".

What you write

The whole Haskell side of the example is this:

{-# LANGUAGE TemplateHaskell #-}
module Core where

import HsDart
import Data.Text (Text)
import qualified Data.Text as T

square :: Int -> Int
square x = x * x

greet :: Text -> Text
greet name = "Hello, " <> name <> "!"

shout :: Text -> Text
shout = T.toUpper

sumPrimesBelow :: Int -> Int
sumPrimesBelow n = … -- sieve via STUArray Word8 + unsafeRead/Write

exportAll ['square, 'greet, 'shout, 'sumPrimesBelow]

That is it. One splice. No foreign export ccall, no CInt, no manual C wrapper. The TH macro reifies each name, picks a marshaling recipe based on the type, and emits the matching wrapper plus the foreign export. It also embeds a tiny JSON manifest of the API into the dylib as another foreign-exported function (hsdart_manifest :: IO CString), and that manifest is what the Dart side reads to generate its bindings.

The Dart side is just as boring:

import 'haskell_example.g.dart';

void main() {
  print(square(12));                  // 144
  print(greet('world'));              // Hello, world!
  print(shout('μετά'));               // ΜΕΤΆ
  print(sumPrimesBelow(100000));      // 454396537
}

haskell_example.g.dart is generated by dart run hsdart_dart:gen before Flutter compiles. Bindings are statically typed, the marshaling wrappers (UTF-8 in/out for strings, int↔CInt for ints) are written once in the codegen, and hs_init is hidden inside a lazy _ensureRts() helper that fires on the first call.

What actually happens

Four moving parts:

Haskell source  →  GHC + cabal  →  libhaskell-example.dylib
                                   (with embedded hsdart_manifest)
                                          │
                                          ↓
                              dart run hsdart_dart:gen
                              (dlopen, read manifest, emit Dart)
                                          │
                                          ↓
                              lib/haskell_example.g.dart
                                          │
                                          ↓
                                  flutter run / build
                                          │
                                          ↓
                            build hook stages dylib as a CodeAsset
                              → Flutter bundles it in the .app

1. exportAll does the heavy lifting on the Haskell side. For each name it reifys the type, dispatches on (from, to) (currently Int and Text), and produces a wrapper hsdartFFI_<name>, a foreign export ccall <name> ..., and contributes the function's signature to a JSON blob that's bundled into the dylib as a foreign-exported function returning a freshly-malloc'd C string.
2. Building is a core-flake-based Nix flake. The Haskell side is two cabal packages, hsdart-haskell (the TH framework, publishable to Hackage) and haskell-example (the user code, depending on it).
3. dart run hsdart_dart:gen nix builds the foreign library, dlopens it from a regular Dart CLI, calls hsdart_manifest, parses the JSON, and writes lib/haskell_example.g.dart with one @Native declaration plus a marshaling wrapper per function. Plus the _ensureRts() helper around hs_init.
4. The Flutter build hook is now two lines: hsdartBuild(args, flakeAttr: 'haskell-example', flakeDir: '../..'). The helper lives in the hsdart_dart package, nix builds the foreign library, stages it under the right SONAME and registers it as a CodeAsset so Flutter bundles it into the .app.

Codegen and the build hook are deliberately split. Flutter's hook protocol runs hooks after the Dart kernel snapshot is compiled — codegen from inside the hook would write the bindings, but the snapshot was already built against the previous version (or the stub on first run), so the regenerated bindings don't reach the running app. Codegen has to be a pre-build step.

How fast is it, actually

The repo ships a benchmark package that compares Haskell-via-FFI to pure-Dart equivalents of the same four functions. It uses package:benchmark_harness with the standard 100 ms warmup and 2 s measurement window. The task runs the same logic twice, once with dart run (JIT) and once after dart compile exe (AOT), so we get four numbers per function. The foreign library is built with -O2 -funbox-strict-fields and the GHC runtime statically linked in (options: standalone).

Three things jump out.

First, the two Haskell+FFI columns are essentially identical. The Dart-side call site is compiled by either the JIT or the AOT compiler, but in both cases it boils down to "marshal arg, do an indirect call into the native lib, marshal return". That cost is structural and doesn't care which mode you compiled the rest of your Dart in. Roughly ~120 ns for a numeric round trip and ~800 ns for a string round trip (which includes the four-step String → malloc'd UTF-8 → Haskell Text → malloc'd C string → Dart String → free dance).

Second, Dart AOT is not consistently faster than Dart JIT on hot microbenchmarks. For square and shout AOT shaves off a fraction, for greet JIT is twice as fast because it specialises the string-interpolation path harder, for the sieve they are within noise. The general rule "JIT wins steady-state, AOT wins startup and consistency" holds.

Third, and this is the actual lesson, the FFI overhead is fixed per call. ~120 ns of overhead is 24× the cost of a 5 ns multiplication, but only 0.009% of a 1.4 ms sieve. Spend that fee on a millisecond of real CPU work, like a Sieve of Eratosthenes (sumPrimesBelow does ~520k cache-friendly stores in the marking pass plus ~500k reads and adds in the summing pass), and Haskell beats Dart by ~2× in either compilation mode. Spend it on a multiply and you have paid 20× the cost of the work itself.

One catch on that last row: the sieve had to use STUArray Int Word8 with unsafeRead/unsafeWrite to beat Dart. With a Bool payload and bounds-checked reads, the Haskell version was 3.3 ms, barely tied. The Word8 array packs the sieve into a byte per entry, the unsafe variants skip a per-access conditional, and together they cut the time by roughly 60%. The full discussion is in BENCHMARKS.md.

The mental model is just that. Chunky work amortizes the FFI tax, trivial work cannot. Reach for Haskell-over-FFI when your function is measured in microseconds or milliseconds, not nanoseconds, and the choice of JIT vs AOT on the Dart side doesn't change the conclusion.

Credits

• The pattern is a direct steal from pixer, which does the same thing with Rust. The "Flutter app that calls native code through a build hook" architecture is theirs.
• The Nix orchestration is built on top of purplenoodlesoop/core-flake. The tasks module turns flake attributes into nix run .#name apps, and the tasks-help task is auto-generated.

Horizon is a personal AI assistant I built that stores all its state in an Obsidian vault — a directory of plain markdown files. There is no database, no hidden state, no proprietary format. The vault is the database. Open Obsidian, and you see everything.

It runs as a daemon on my Linux box. One Dart process, one event loop, one LLM call per event. It accepts input via Telegram messages, fires on cron schedules, and watches vault files for changes. Each event goes into a pipeline: load relevant context, call the model, execute any resulting tool calls, write results back to vault.

Architecture

The core loop is straightforward. An event arrives — a Telegram message, a heartbeat tick, a vault file appearing — and the harness:

1. Loads the standing system prompt from _horizon/system/standing.md
2. Reads the capability manifest and selects capabilities relevant to the event
3. Makes one LLM call with the assembled context
4. Executes validated bash commands from a YAML allowlist
5. Writes results back to the vault

Tools are bash command templates defined in _horizon/system/allowlist.yaml. Appending a new entry makes it available on the next event — no restart, no code changes. The validation layer handles path traversal and shell escaping, so the allowlist file itself is safe to edit from a mobile Obsidian client.

The LLM endpoint is configurable. Default is Kimi K2 via CrofAI, though anything with an OpenAI-compatible chat completion API works. Every call goes through the same standing prompt, which keeps prefix caching effective — roughly 70–85% cache hit rate at providers that support it.

Capabilities

Behavior is defined in markdown files that live inside the vault itself, in _horizon/capabilities/. Each capability is a .md file with YAML frontmatter:

---
id: todo-manager
description: Load when the user mentions tasks, todos, or wants to track something to do later
schedule: 1d
---

The description field is what the orchestrator uses to decide which capabilities to load for a given event. The schedule field, when present, makes the capability eligible for heartbeat ticks at that interval.

What ships out of the box:

• Journaler — appends every interaction to journal/YYYY-MM-DD.md
• Knowledge base — maintains structured entries at knowledge/<slug>.md for facts worth keeping
• Todo manager — creates and updates tasks at todos/<slug>.md with YAML frontmatter tracking status, due dates, and context
• Relationships — tracks people at people/<slug>.md, bidirectional connections via [[wikilinks]]
• Pot tasks — delegates long-running autonomous work (coding, research, design) to separate Claude agents via the Potentiality orchestrator; results come back into the vault
• Skill reflector — audits recent activity and proposes new capability files when patterns emerge; promotion is manual
• Metacognitive monitor — scans turn records for repeated misses and inefficiencies, surfaces them for review
• Lint capabilities — LLM-driven audit of the capability descriptions themselves for semantic overlap

Editing any of these in Obsidian takes effect on the next event. No restart.

The vault as database

Every piece of state is a markdown file:

journal/2026-05-14.md
knowledge/nix-flakes.md
todos/write-horizon-article.md
people/alice.md
_horizon/capabilities/todo-manager.md
_horizon/turns/01HXK2...json

This has a few practical consequences:

• Full audit trail. Every turn is recorded in _horizon/turns/ as a structured JSON file. The whole conversation history is on disk.
• Obsidian-native. [[Wikilinks]] work. Dataview queries work. You can build a custom dashboard over your todos, a graph view of your relationships, a calendar over your journal entries.
• No lock-in. The files are plain text. If I want to stop using Horizon, the vault stays — notes, todos, journal, all of it.
• Mobile editing. Capabilities, the system prompt, and the tool allowlist are all vault files. Obsidian on iOS edits them. Changes propagate on the next event.

Signal-driven heartbeat

The heartbeat fires every five minutes by default, but it doesn't always do anything. Before making an LLM call, the harness checks whether any capability with a schedule: field is due. If none are, the tick costs zero tokens.

When a capability is due, the orchestrator sees only that capability and an instruction to reply with HEARTBEAT_OK if nothing actionable is found. Skill-reflector runs weekly. Lint runs daily. The metacognitive monitor runs every few hours. Most heartbeats are silent.

What it won't do

By design:

• It won't serve multiple users — one vault, one owner
• It won't host MCP or be an MCP client — tools are bash commands in a YAML file, nothing more
• It won't self-modify — skill-reflector proposes, I promote
• It won't hold sub-second real-time state — it's async by nature

These aren't compromises. They're the constraints that make everything else tractable.

Running it

nix run github:purplenoodlesoop/horizon

Requires a .env with TELEGRAM_TOKEN, TELEGRAM_USERNAME, and LLM_TOKEN. Vault defaults to ./vault in the working directory. The bootstrap creates the _horizon/ subtree on first run.

Source at github.com/purplenoodlesoop/horizon.

Dart is a multi-purpose, multi-paradigm, cross-platform, and JIT/AOT-compilation runnable language. You mostly hear about it in the context of Flutter, but I want to talk about the language itself, in isolation.

Why?

I'll list the parts I like about the language, not in any particular order. There are of course things that I don't like, but they are not for this post. In general, the ugly parts are mostly non-fundamental, even if they are annoying (semicolons, looking at you.)

Familiarity

The post will contain a lot of Dart examples, but they should be pretty universally understandable. Given the initial "replace JS" purpose of the language and the later focus on the mobile, I believe the team intentionally made it so innately simple to understand.

class Dog {
  void bark() {
    print('Woof!');
  }
}

int fibonacci(int n) {
  if (n == 0 || n == 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

final result = fibonacci(20);

Almost Interslavic.

Type system

Dart has a really tasty type system, in a way that it is possible to express any reasonable constraint, model most scenarios with data that can be modeled with data, and not find yourself choosing from multiple "right" ways of doing the same thing or fighting with a synthetic roadblock.

extension type Meters(int value) implements int {}

interface class Symmetric {
  Meters get val;
}

sealed class Form {}

final class Circle extends Form implements Symmetric {
  @override
  final Meters val;

  Circle(this.val);
}

On top of all that, it is safer than something like TypeScript and gives reasonable type errors.

Sound

Dart 2.0 introduced soundness that obliterated the last of the previous dynamic Dart legacy – Dart made a significant journey.

Starting as a dynamic language, to making types opt-out, to being sound and null-safe – currently, we have a very "checked" language that is protecting the developer as much as possible without being over the top.

String? doubleName() => 'Yakov' * 2;

final name = doubleName();
final String nope = doubleName(); 

Because of that, both writing new code and creating abstractions AND refactoring is a process of little friction – the compiler holds your hand and screams at you in the right proportions, at the right time.

Complete OOP

OOP is a base paradigm for Dart – even though multiparadigm and very functional approaches are allowed, on the fundamental level everything is object-oriented, and I don't think that is a bad thing, with this particular flavor.

interface class HasAge {
  int get age;
}

interface class HasName {
  String get name;
}

base class Creature implements HasAge, HasName {
  @override
  final String name;
  @override
  final int age;

  Creature(this.name, this.age);
}

interface class CanSpeak {
  void speak();
}

The main points about Dart's OOP are:

1. Primitives are classes
2. The Diamond problem is solved through mixins
3. Classes are open by default
4. There are no data classes, classes are co-data by default
5. Classes are highly tunable by a list of modifications
6. Objects have an implicit interface, taking every interaction to some level of abstraction by default

Documentation has a great entry on the specifics, but in essence, OOP is of "true" flavor for the current meaning of the paradigm and without any significant rough edges.

mixin SelfDescribingAbility on HasAge, HasName implements CanSpeak {
  @override
  void speak() {
    print("My name is ${name} and I'm ${age}");
  }
}

class Human = Creature with SelfDescribingAbility;

Flexible, yet safe and complete – once again, boring and tasty.

Anonymous Records

The latest significant feature, marking a new era in data abstractions and even some first whiff of (almost)polymorphism.

Destructuring, ad-hoc data polymorphism, named and unnamed fields – all the standard features. However, Records open a few interesting doors.

Creating anonymous objects with full inference

final counter = Module(($) {
  final increment = $.trigger<()>();
  
  return (
    increment: increment,
    value: $.store(($) {
      $.on(increment, (_) => $.self + 1); 
      return 0;
    })
  );
});

Performing operations on multiple inner values

final $Order = (
  ('city', City.new.$).with defaults(City('Haifa')),
  ('comment', Comment.new.$).optional(),
  ('buildings', $List(Building.new.$)),
).jsonSchema();

Or having some level of (pseudo)polymorphism

String doubleString(String val) => val * 2;

(
  doubleString,
  print
)
  .compose('Hello, world')

Zero-cost abstractions

New, relatively niche feature, but another nod to the completeness and relative power of the type system.

Extension types allow for both increase of the correctness and well, extending types, by composition.

Once again, the documentation does the job best of explaining.

Examples can be rather simple.

extension type Meters(int value) {}

Or rather complex

extension type Behavior<B, D>((B, D) _self) {
  B get behavior => _self.$1;
  
  D get data => _self.$2;
}

extension type Identity<T>(T _self) {
  T get id => _self;
}
  
typedef Described<T> = Behavior<String, Identity<T>>;

extension type Describable<T>(Described<T> self) implements Described<T> {
  String describe() => '${behavior} ${data.id}';
}

typedef Logged<T> = Describable<Behavior<void Function(String), T>>;

extension type Loggable<T>(Logged<T> self) implements Logged<T> {
  void log() {
    data.id.behavior(describe());
  }
}

Not only OOP

After everything written above, it is obvious that Dart not only has a complete OOP system but also offers a list of multi-paradigm features that even further remove restraints and allow for the choice of approach of a fitting paradigm for a job.

In my experience, having a strong OOP-based abstraction under the hood on the library level with a mostly functional interface is one of the most organic approaches, and Flutter demonstrates it the best.

/// I'm a function in disguise!
class CounterWidget extends StatelessWidget {
  const CounterWidget({
    super.key,
  });

  @override
  Widget build(BuildContext context) {
    final (:increment, :value) = context.use(counter);

    return Text(
	  context.use(value).toString(),
	  style: Theme.of(context).textTheme.headlineMedium,
	);
  }
}

The underlying Element system that powers descriptions like in the above is a classic, inheritance-based OOP.

Tooling

Another selling point by offering minimal friction – every single piece of needed tooling is available out of the box, working, fast and simple.

Take a look at compilation, Flutter CLI and documentation tooling.

This solid toolkit allows for some magic like JIT/AOT compilation, hot reload, small output binaries, and other features that just feel and work correctly.

pub.dev

An npm for Dart – accounting for isEven-style packages, the current choice of packages is not less in terms of functionality. Most of your common problems are solved and nicely packages, either as an official dart tools package or any of 51k public packages.

There are some silly ones, of course.

Standard Library

Even not touching on the pub.dev, those are some of the in-built (= canonical, efficient, and idiomatic) libraries.

• dart:convert
• dart:typed_data
• dart:ffi
• dart:io

Async and Concurrency

Once again, no particular innovations, but a very complete and pragmatic approach with just the right level of abstraction. TL;DR is BEAM processs/Actor model + Futures and async/await.

Also, generators.

In practice, working with Dart's models in this domain feels natural, pragmatic, and straightforward. There is enough syntactical sugar to freely express the desired scenario, and concurrency is a blast.

Some time ago, Isolates got much lighter and faster, and currently, it is possible to have the full benefit of running a piece of code in a separate process simply by spawning a green thread

int fib(int n) => n <= 1 ? 1 : fib(n - 1) + fib(n - 2); 

await Isolate.run(() => fib(40));

Spicy features

Dart has some interesting features that are unique or almost unique to the language. They are rarely used by the end developer but can be leveraged by library code to achieve elegant solutions to complex problems.

Some of those features are:

• Zones
• Expando
• Finalizer
• Extension types
• Immutable generators

What next?

Please explore Dart more! It can be in the form of Flutter, contributing to the Dart OSS community, or simply by looking at the documentation. I see the language as a really interesting example of how limited innovation and an extreme commitment to each layer produced such a sturdy worktool.

I have a list of open-source Dart projects on my profile, which can be one of the starting points of interaction with the Dart ecosystem :)

• https://github.com/purplenoodlesoop/http2-grpc-haskell
• https://github.com/purplenoodlesoop/gRPC-haskell

Structure of a gRPC toolkit

A toolkit/suite for a proto/gRPC for a specific language is a concept that this article is talking about. A toolkit consists of two mandatory public-facing parts that enable its functioning – (1) a language-specific implementation of the API with core types and functions, and (2) a code-generator from .proto files.

service VoiceService {
  rpc Call(stream InputPacket) returns (stream OutputPacket);
}

Each implementation would differ, as every part can be represented very differently – arguably, some better than others.

Ecosystem Overview

On Hackage, complete implementations are http2-grpc-haskell and gRPC-haskell. Both packages are heavily undermaintained, but mostly not outdated and fully usable.

This results in some of the toolkits' packages being broken both in vanilla Haskell and Nix ecosystems or requiring obscure, outdated dependencies themselves. Given that the implementations are very much useful, it makes sense to provide the fixes.

On mu

mu-haskell was an interesting project! Searching for gRPC lands on it as one of the solutions, but the project was archived on Oct 19, 2024. The project received its last commit almost two years ago, and the proto/grpc part is especially outdated. Their Examples, and source code are of a very much value, though.

mu-haskell uses WAI, so does http2-grpc-haskell

http2-grpc-haskell

A full, full-Haskell implementation of the protocol. Does not rely on external C, and implements everything on top of native abstractions. Flexible, correct, and idiomatic.

Implementation

A higher-level implementation of warp-grpc is the most likely part of the library for an interaction. The toolkit uses wai and warp to implement the rpc part, and the .protos are generated using an idiomatic gRPC compilation plugin that generates proto-lens message and service definitions.

''
protoc \
 --plugin=protoc-gen-haskell-protolens=${getExe pkgs.haskellPackages.proto-lens-protoc} \
 --haskell-protolens_out=packages/backend/gen \
 packages/proto/core.proto
''

The API is somewhat of a trap, however. It poses a similar flaw to grpc-web in missing an important part of functionality – asynchronous, bidirectional stream communications are impossible, as each event can be met with a 0-1 response in the borders of the same message.

handleIndex :: UnaryHandler GRPCBin "index"
handleIndex _ input = do
 print ("index"::[Char], input)
 return $ defMessage & description .~ "desc"
                        & endpoints   .~ [ defMessage & path .~ "/path1"
                                                      & description .~ "ill-supported"
 ]

nixpkgs

The toolkit is mostly broken in the Nix ecosystem, but it is easily fixed in the form of an overlay. After bumping dependencies everywhere to:

- bytestring >= 0.10.8 && < 0.13
- http2 >= 3.0 && < 5.3
- warp >=3.3.15 && <3.5
- text >= 1.2 && < 2.2
- tls >= 1.4 && < 2.1
- zlib >=0.6.2 && <0.8

Running cabal2nix on updated .cabal files generates valid .nix files that can be used in an overlay drop-in.

{ lib }:
self: super:
let
  packages = [
    "warp-grpc"
    "http2-grpc-types"
    "http2-grpc-proto3-wire"
    "http2-grpc-proto-lens"
    "http2-client-grpc"
 ];
  genName = "package.gen.nix";
  foldl = f: lib.foldl' (packages: name: packages // { ${name} = f name; }) { } packages;
in
{
  haskellPackages = super.haskellPackages.override {
    overrides = hSelf: hSuper: with data; foldl (name: hSelf.callPackage ./${name}/${genName} { });
 };
}

The fix can be found here and applied as a default overlay. The fork is based on another fork with dependency bumps.

gRPC-haskell

Implementation

Shared C usage. This implementation is really a wrapper around a mostly canonical implementation, which at the same time makes it a much less flexible implementation that does not allow room for using idiomatic underlying implementations AND provides a full API.

This solution allows for all of the standard protocol functionality.

addHandler ::
  ServerRequest 'Normal TwoInts OneInt ->
  IO (ServerResponse 'Normal OneInt)
addHandler (ServerNormalRequest _metadata (TwoInts x y)) = do
  let answer = OneInt (x + y)
 return
 ( ServerNormalResponse
 answer
 [("metadata_key_one", "metadata_value")]
        StatusOk
        "addition is easy!"
 )

The API departs from idiomatic context integrations in one more way – .hs code is generated by a separate program and not as a plugin in the protoc compiler.

{
env = with pkgs; [ haskellPackages.proto3-suite ];
text = ''
 compile-proto-file \
 --includeDir packages/proto \
 --proto core.proto \
 --out packages/backend/gen
'';
}

The resulting code is somewhat more verbose, but it is a matter of utility functions and types, which are absent in the core implementation.

nixpkgs

Again, broken, again, fixable with an overlay. The project does not use flakes, and using the latest unstable channel would result in compilation errors. The fix is two-fold.

Bumping bytestring:

- bytestring >= 0.10 && <=0.12

And utilizing an older version of gRPC

nixpkgs-grpc.url = "github:NixOS/nixpkgs?rev=d59a6c12647f8a31dda38599c2fde734ade198a8"; # gRPC 1.45.2

Running cabal2nix and building nixpkgs with an overlay that overrides Haskell packages and grpc the project is built.

Favoring over other solutions

The differences might seem subtle, but they are quite important and I see a choice as somewhat lacking.

Guarantees of implementation

gRPC-haskell expects a record with a service implementation, which allows the compiler to check its completeness of it, and http2-grpc-haskell would allow the compilation to run, even on incomplete, patchy service implementations.

voiceService state = 
 voiceServiceServer VoiceService {..} defaultServiceOptions
  where
    voiceServiceCall :: RPC 'BiDiStreaming InputPacket OutputPacket
 voiceServiceCall (ServerBiDiRequest _ req resp) = do
-- ...

Type inference

Not using fully abstract, lens-powered records allows for a neater type-completion, with the compiler being able to interact with the records closer.

Bi-directional streaming

Already been mentioned, but this is one of the reasons that pushed me to fix a second library – the imperative, persistent interface for receiving and requesting events asynchronously in independent directions.

Two paradigms unfortunately share a similar name, and it is important to differentiate them. Everything in this article is related to the first one, as most of the things discussed can be categorized as a part of it. Not to paint the second one insignificant thought – it is just a very different concept that solves very different problems.

Data-driven programming

A quote from the Wiki:

In computer programming, data-driven programming is a programming paradigm in which the program statements describe the data to be matched and the processing required rather than defining a sequence of steps to be taken.

A broad definition, I know. It can be fit onto simple map-reduce list transformations that describe the logic of the application, as well as on complex asynchronous Stream transformations, and onto something akin to dynamic programming's attribute set manipulations, like in Nix.

The main point is, that the data itself describes both the control flow and the logic, where the whole application becomes a collection of high-level and abstract data transformation. The transformations themselves are generic and the program becomes a set of rules that command those transformations.

The beautiful The Art of Unix Programming dives deeper with examples on, surprisingly, Unix systems.

Data-oriented design

A completely different approach from data-driven programming, focusing on optimizing data structures by grouping related fields into a multi-array, composite object, making the object of interest implicit.

So, instead of having

typedef User = (
  String name,
  int age,
);

typedef Users = List<User>;

The list of users is represented as

typedef Users = (
  List<String> name,
  List<int> age,
);

Representing effects as data

One example of a data-focused approach can be representing impure logic as pure data that gets evaluated later. Both FP and OOP have some sort of it that differs slightly, maintaining the main idea.

Data as a description of an Effect

In OOP and closer-to-OOP-than-others languages it is called Interpreter Pattern, somewhere in the middle it can be viewed as a simple effectful function over pure data types, and in FP it is a core of it, as the written code must be pure and every effect must be represented as some kind of data.

Below is an example of a pure function with async effects and logging in TypeScript.

const run = () async* => {
  yield {type: 'log', data: 'Starting'}
  yield {type: 'value', data: 10}
  yield {type: 'log', data: 'Waiting for 1 second'}
  yield {type: 'wait', data: 1}
  yield {type: 'log', data: 'Done!'}
}

The calling site would process those values and evaluate them, while the source function just returns plain values.

Sandwiches!

There is a whole architectural approach that focuses on this kind of design for non-strictly-functional languages, which might sound limiting, but all "strict" approaches have their benefits, as well as being used widely, either by different names or more explicitly/as a part of a bigger combination of guidelines.

An impure-pure-impure sandwich.

Dataflow and Reactive programming

Yet another data-centric approach, and arguably the most straightforward one in terms of the closeness of the problem to the nature of the solution, is a set of reactive-like paradigms.

Both deal with transformations of data as it flows through the system, and Reactive programming can be considered a subset of Dataflow, where both systems are concerned with the propagation of data through a set of transformers with the former operating on the data itself, and the latter operating on data changes.

Reactive programming can be further classified into synchronous/asynchronous and push/pull. Even further, even closely classified system implementation can differ greatly, and something like Effector is very, very different from ReactiveX, even though they share a lot in common.

Dataflow's definition is much more vague, but other than operating on the data itself it is more concerned with graphs, and TensorFlow builds upon this very notion. This article explains it much more in-depth.

On FRP

One very specific implementation of reactive programming is Functional Reactive Programming, initially proposed in the paper Functional Reactive Animation. It is not widely used due to its implementation details, but it is very influential nonetheless, and the aforementioned ReactiveX can be thought of as something that resulted from FRP.

type Behavior a = Time → a
type Event a = [(Time, a)]

As usual, there are a lot of flavors. I can pinpoint Reactive Banana as a typical, yet elegant implementation that can be used as an example for understanding the paradigm. Their unofficial tutorial is also nice.

UI as a function of State

In current component-based UI systems, the configuration of the UI itself is represented as a function of a state, which can be categorized as just another function over data that accepts immutable inputs and outputs a configuration, a description of the resulting UI, and the behavior of application-level code.

This approach was popularized by React, but currently, it is used pretty much universally – Flutter uses it, SwiftUI uses it, Kotlin Compose uses it, and so on.

I really like Flutters definition of this approach, which makes the idea a bit more radical, representing everything as a Widget. This means that data, the Widgets, describes every aspect of application-level behavior, from lifecycle events, such as showing a snack bar on opening a specific page, to the configuration of a resulting UI, such as the color of a button.

On hooks

Funnily enough, React gave birth to this UI = f(State) paradigm, and React abandoned it by introducing hooks into the equation.

Lots of disagreement with the concept of Hooks exist, but one thing is a fact – hooks break the paradigm by making Components/Widgets impure. By passing the same props to the Component that uses hooks we won't necessarily obtain the same output, as they introduce state bound to the circumstances of the caller.

Flutter solves this problem by explicitly passing to each and every widget BuildContext – a wrapper object that contains the current state of a context that this Widget exists in. Given that the context is used with InheritedWidgets, it is possible to achieve stateful behavior without making a widget impure.

Composition vs Inheritance

Prioritizing data in terms of creating collections of grouped functionality also has its applications. Composition over Inheritance is a well-used approach that is considered a "best practice" in a lot of cases, and pretty much as data-centric as it gets in a very data-opposed (and behavior-oriented) setting of combining functionality and achieving polymorphism.

Returning to Flutter as an example, it favors very strongly composition over inheritance, with a vast majority of widgets achieving only a single level of inheritance from their abstract parent class. The widgets are described as a composed, immutable data structure as well, with a polymorphic interface of the Widget class.

This demonstrates not only the extent to which the compositional approach can be pushed but also the fact that it is indeed handy to combine approaches, as stated in the Design Patterns.

Multiple inheritance

A very short tangent regarding Multiple Inheritance – CoI is an example of the simplest solution for a problem that is traditionally solved by using different "flavors" of inheritance instead.

Take a look at Dart's Mixins and Swift's Protocols and see how composition can be used to solve the very same problem, without stepping away from data as a mean for implementation of functionality.

Business logic can be stateful in settings where an application is long-running and changes based on external conditions. This could apply to applications where those conditions are a user or some stream of data. Prices of currencies, for example.

However, the example with a user is a standard application of some kind of abstraction that helps structure, control, and implement the logic behind it. Unidirectionals act as one of the many groups of those abstractions, following principles of immutability, data-first approach, and declarativity.

Data flows in one way, which usually can be summarised as Events/Intents in -> States out, and the cycle repeats – based on the states new events can be added, and so on. This can be contrasted with bidirectional approaches, like two-way bindings, for example.

A core part of all can be summarised as a reducer function

(State, Event) -> State

Why?

Dealing with a state is hard, and dealing with a reactive state is even harder. Unidirectional approaches abstract out most of the low-level stuff – actual mutations, and allow for declaratively describing the relationship between intents and resulting states.

This approach can be generalized on (side) effects as well. This is tricky, however, as reducers, the functions that actually transform the current state and an incoming event to a new state, are pure, which obviously contradicts the whole point of side effects.

Let's not get ahead, as the main value is still present – declarative, seemingly immutable, data-first, simple functions that can fully encapsulate all the possible state changes. But that's not all – given that both states and events are represented as immutable data, algebraic data types, can be transformed and manipulated as any other data. Either by simple functions over data or as complex descriptions of asynchronous data streams – for filtering, manipulating concurrency, and much more.

For games, this is basically a must, as those complex state machines are most naturally represented as unidirectional, reducer-based abstractions. And for UI applications, such as websites and mobile applications, user behavior and some other parts are pretty naturally represented as well.

What about the boilerplate?

Yep, lots of it. Unidirectional approaches absolutely bring relief to some of the hardest to deal with, and most time-consuming problems of user applications, but they also come with a tax of the boilerplate.

Redux is infamous for it, Elm is infamous for it, and a lot of libraries of the Android world are infamous for it. Boilerplate raises the complexity pointlessly, negating most of the benefits, and that's not even mentioning the raising of cognitive load, code duplication, the un-ergonomic and hard-to-debug

This is one of the reasons for an abundance of all the flavors, which is valid, but is not less of a pain to deal with. Naturally, developers try to maximize the benefits while minimizing the "price" of usage, and there have been quite a lot of improvements and development in the past n years.

Flavors

Here are briefly listed most of the existing flavors, with some thoughts and code examples alongside. Examples are in Dart, but being a general-looking C-like language, this does not really matter; don't let that discourage you if you are not familiar with it.

I will use Events for describing Events/Actions/Intents for consistency, as they are (almost) the same thing in most of the flavors.

Direct reducer

The simplest, and pioneering approach jumpstarted into the JS world and other worlds by Redux, fully resembling the pseudocode example above. Current state in, Event/Action in, new State out.

typedef Reducer1<State, Event> = State Function(State state, Event event);

Original Redux uses a single store which is not really relevant, as unidirectional approaches can utilize both multi-store and single-store approaches.

Side effects can be represented in many ways when using direct reducers, and many are listed below in their concept, just with different, arguably more ergonomic implementations. Currently, Redux evolved into a somewhat hybrid approach through RTK, but it is out of the scope of this article.

Redux and other such simple approaches make it hard to model side effects, even though there are a lot of ways that try to implement the less painful way. Not really effective.

Effects as data

The next iteration starts the route of encoding side effects directly in the reducer. The second generation Elm pioneered this approach, which eventually seeped into Redux as well, and can be implemented in pretty much any language that allows passing functions as data in one way or another.

Just as JS has a native type for async data, Elm does this nicely, as it has a native type for side effects. Not necessarily asynchronous, but side-effectful. Simplifying this approach and encoding it in Dart, it can be formulated as something like this

typedef Output2<State, Event> = (State state, Future<Event> Function() effect);

typedef Reducer2<State, Event> = Output2<State, Event> Function(
  State state,
  Event event,
);

Reducer returns not only a new state but also a thunk of a side effect that returns a new, that is then evaluated and the resulting event is added back.

Works, works predictably, looks simple, and the concept itself is relatively easy to understand. Lots of boilerplate though, even in the Elm itself that supports this approach on the language level. Trying to port it to other languages yields even more verbose code which in turn leads to bloated, hard-to-understand, and repetitive codebases.

Effects as abstract data

Even a more scary approach in terms of the amount of code, but beautiful in terms of abstraction power – reducers become very dumb and return very simple data structures that are then evaluated by interpreters.

This approach goes the full data-first route, modeling everything as data. Look at the definition of a reducer:

typedef Effect3<State, Effect, Event> = Future<Event> Function(
  State state,
  Effect effect,
);

typedef Output3<State, Effect> = (State state, List<Effect> effects);

typedef Reducer3<State, Event, Effect> = Output3<State, Effect> Function(
  State state,
  Event event,
);

Both sync and async effects are represented as synchronous, abstract data structures! Colored functions said hello, IYKYK.

It makes sense to give an example, but it will take an unimaginable amount of symbols to actually show even the simplest implementation in Dart, so pseudocode it is. Let's model some logging for a counter.

First, interfaces/data declaration

data State = Int

data LogLevel = Info or Warning

data Effect = (String message, LogLevel level)

data Event = Increment or Reset or None

After everything is encoded into data structures, they can be "evaluated" or "interpreted" by two functions, one pure – for state changes

State reducer(State state, Event event) {
  return when event
    Increment => (state + 1, [("Incremented", Info)])
    Reset => (0, [("Reset state", Warning)])
    Nothing => (state, [])
}

And one impure – for effect evaluation.

Event effect(State state, Effect effect) {
  print(effect)
  
  return None
}

This is a very powerful abstraction that fully encapsulates all the implementation details, but even in this hypothetical pseudocode language, it is verbose and scales as good as Redux. Not good.

Effects as a part of a reducer

A logical extension of those approaches is just mashing side effects and state changes together. Sounds a bit sad, as we are losing the determinative aspect of the reducer, but it is the most ergonomic approach of all the mentioned previously.

Two examples come to mind, which are BLoC as defined in the awesome article of Didier Boelens, and PureScript's Halogen.

The main idea can be formulated as "after the reducer receives a new event, it can perform any asynchronous, effectful actions while returning as many states in the process as required". This makes implementing complex effectfull flows, such as pagination, very easy and ergonomic, while maintaining the data-first approach, and consequentially, all the benefits from treating both intents and resulting states as values.

Returning to BLoC, the reducer type definition looks far simpler than other approaches

typedef Reducer5<State, Event> = Stream<State> Function(
  State state,
  Event event,
);

Stream is just an asynchronous collection, which fits the definition of a reducer that can perform async actions and return multiple states in the process.

Effects as reactive units

Lastly, an approach that was prevalent in the Android world some few years ago, effects can be described as reactions to state changes or events, decoupling them from the otherwise pure reducer that does not know absolutely anything about side effects being performed.

This approach is conceptually similar to Redux's Middlewares, which can be categorized as the same MVI.

This is a bit of a recursive definition since the effect evaluation is an effect in itself in this paradigm – a subscription to internal events of the "Store". ClojureScript's Re-frame generalizes this even further, and Redux's Saga is similar in the sense that it returns an asynchronous sequence of events to be added back.

Going back to Dart, this definition looks similar to the previous one and the very first – it combines a pure reducer with an impure async collection, with the exception that the collection describes not new States, but new Events

typedef Reducer6<State, Event> = Reducer1<State, Event>;

typedef Watcher6<State, Event> = Stream<Event> Function(
  State previousState,
  State nextState,
  Event event,
);

Closing words

What is the conclusion here? Mostly, I would say that the diversity of unidirectional flow-centered approaches says a few main things about their current state:

1. They are battles tested and proven to work and work well
2. Developers are dissatisfied with current approaches, particularly with Developer Experience that they offer
3. Some languages are more fit for some flavors, particularly if they support parts on the language level. Command in Elm and async generators in Dart and JS are examples of that
4. Some pioneering approaches combine the flavors, which is a topic for another article
5. Immutability, declarativity, and data-first approaches are useful in many ways but come with a cost