Skuld - an effectful approach to deterministic testing, N+1 batching, and serialisable workflows

Skuld started out as a limited exploratory project, and then it snowballed…

Most Elixir apps have a layer of orchestration code bridging whatever pure model has been extracted with side-effecting components - “fetch user, check permissions, load subscription, hit an API, compute a price, write an invoice.” This code is tangled with databases, HTTP clients, and randomness. It’s hard to test, hard to refactor, and oftentimes impossible to property-test.

Skuld lets you write that code as pure descriptions of side effects. Handlers decide what those descriptions mean. Same code runs with real I/O in production, in-memory maps in tests, and properties you can verify with stream_data.

Here’s what that looks like:

Automatic N+1 batching. This reads like sequential code but fetch_user and fetch_orders run concurrently, and all the AccountQueries functions get batched into bulk queries. Stream 10 users with concurrency: 4 and FiberPool batches all deffetch calls into round-trips of [4, 4, 2]. No manual loader, no explicit batching:

defquery build_account_summary(user_id, month) do
  user <- AccountQueries.fetch_user(user_id)
  orders <- AccountQueries.fetch_orders(user_id, month)
  details <- Query.map(Enum.map(orders, & &1.id), &AccountQueries.fetch_order_details/1)
  build_account_summary(user, orders, details)
end

user_ids
|> Brook.from_enum()
|> Brook.map(&build_account_summary(&1, "2026-01"), concurrency: 4)
|> ...

Pausable state machines. A computation pauses at each Yield.yield, waits for input, resumes with full effect context. The same code wrapped in an AsyncCoroutine pauses for the user in a LiveView handle_info or, wrapped in a plain Coroutine, runs as three Coroutine.run calls in tests:

defcomp checkout do
  cart <- Yield.yield(:get_cart)
  {:ok, inventory} <- Inventory.check_stock(cart.items)
  payment <- Yield.yield(:get_payment)
  {:ok, order} <- Orders.place(cart, payment)
  ...
end

Durable computation. The same checkout state machine, above, but now serialised: pause mid-flight, save its entire execution history as JSON, resume after a restart. Every effect invocation is captured in a serialisable log. SerializableCoroutine.run(json, sc, cart) replays recorded effects and continues where it left off:

sc = SerializableCoroutine.new(checkout, fn comp -> ... end)
suspended = SerializableCoroutine.run(sc)
json = SerializableCoroutine.serialize(SerializableCoroutine.get_log(suspended))
# => EffectLogEntry{data: :get_cart, value: nil, state: :started}

SerializableCoroutine.run(json, sc, %{items: [...]})
# => EffectLogEntry{data: :get_cart, value: %{items: [...]}, state: :executed}
# => EffectLogEntry{data: :get_payment, value: nil, state: :started}

Under the hood there are algebraic effects, but you don’t need to know that. Writing domain code with State, Reader, Yield, Port (for external dispatch), and Repo (for database operations) reads naturally once you’ve seen the examples.

The library bundles effects for state management, cooperative concurrency (FiberPool, Channel, Brook), value generation (Fresh, Random), error handling (Throw, Bracket), external integration (Port, Repo, hexagonal architecture), and serialisable workflows (EffectLogger, SerializableCoroutine). Full docs at hexdocs.pm/skuld.

Add {:skuld, "~> 0.28"} to your deps.

I’d love to hear what you think - so far I’ve had reactions varying from solid interest to “I would burn that with fire”!

https://github.com/mccraigmccraig/skuld