DEV Community: AranaDeDoros

ADTs & Enums in Scala 3: Making Illegal States a Compile Error

AranaDeDoros — Mon, 14 Sep 2026 15:44:07 +0000

ADTs & Enums in Scala 3

If you've worked on enough business software, you've probably seen this:

final case class Order(
  status: String,
  paidAt: Option[Instant],
  shippedAt: Option[Instant],
  cancelReason: Option[String]
)

It looks harmless.

Until you realize that this type allows all of these:

Order("pending", Some(now), None, Some("customer changed their mind"))
Order("shipped", None, None, None)
Order("cancelled", None, Some(now), Some("too expensive"))

The compiler has no idea that these combinations are nonsense.

Your domain model is effectively saying:

"An Order can have any combination of these fields, and we'll figure out later which combinations actually make sense."

That's exactly the kind of problem Algebraic Data Types (ADTs) are good at solving.

Instead of representing invalid combinations and hoping your application logic catches them, we can make those combinations impossible to construct in the first place.

The problem with "status + optional fields"

Consider a slightly more realistic order:

final case class Order(
  id: OrderId,
  status: String,
  items: List[LineItem],
  paidAt: Option[Instant],
  shippedAt: Option[Instant],
  cancelReason: Option[String]
)

The meaning of the fields depends on another field:

paidAt only makes sense when the order is paid.
shippedAt only makes sense when the order is shipped.
cancelReason only makes sense when the order is cancelled.

But the type doesn't express any of that.

You could write:

Order(
  id = orderId,
  status = "pending",
  items = items,
  paidAt = Some(now),
  shippedAt = None,
  cancelReason = Some("customer changed their mind")
)

It compiles.

And now you have a paid, cancelled, pending order.

Maybe nothing immediately crashes.

Maybe six months later a reporting query produces an impossible financial state and someone has to figure out where it came from.

The problem isn't necessarily the business logic.

The problem is that the type allowed an invalid state to exist.

Model the states instead

Scala 3's enum syntax gives us a convenient way to model this as an ADT:

enum Order:
  case Pending(
    id: OrderId,
    items: List[LineItem]
  )

  case Paid(
    id: OrderId,
    items: List[LineItem],
    paidAt: Instant
  )

  case Shipped(
    id: OrderId,
    items: List[LineItem],
    paidAt: Instant,
    shippedAt: Instant
  )

  case Cancelled(
    id: OrderId,
    items: List[LineItem],
    reason: String
  )

Now look at what happened.

Pending can't have a paidAt.

Paid can't have a shippedAt.

Cancelled can't have either.

There simply isn't a field for them.

That's the important shift:

The domain constraints are now represented by the type system.

An invalid state isn't something we need to remember to validate later.

It isn't representable.

The compiler becomes part of your test suite

ADTs become particularly useful when combined with pattern matching.

def summarize(order: Order): String =
  order match
    case Order.Pending(id, _) =>
      s"Order $id: waiting for payment"

    case Order.Paid(id, _, paidAt) =>
      s"Order $id: paid at $paidAt"

    case Order.Shipped(id, _, _, shippedAt) =>
      s"Order $id: shipped at $shippedAt"

    case Order.Cancelled(id, _, reason) =>
      s"Order $id: cancelled ($reason)"

The compiler knows all the possible cases of Order.

Now suppose the business comes back next month and says:

"We need to support refunded orders."

Add the case:

enum Order:
  case Pending(id: OrderId, items: List[LineItem])
  case Paid(id: OrderId, items: List[LineItem], paidAt: Instant)
  case Shipped(
    id: OrderId,
    items: List[LineItem],
    paidAt: Instant,
    shippedAt: Instant
  )
  case Cancelled(id: OrderId, items: List[LineItem], reason: String)
  case Refunded(id: OrderId, items: List[LineItem], refundedAt: Instant)

And suddenly all your exhaustive matches that don't handle Refunded are exposed by the compiler.

That's a huge advantage in a growing codebase.

Instead of hoping you remembered every place where order states are handled, the compiler tells you where you need to make a decision.

I strongly recommend enabling:

-Xfatal-warnings

Then a missing exhaustive case isn't merely a warning that gets buried in build output.

It's a build failure.

The compiler is now actively helping you find places where your domain model changed.

ADTs aren't just for business entities

One of my favorite applications of this technique is representing external events.

Payment providers are a great example.

You might receive JSON containing something like:

{
  "type": "payment_intent.succeeded",
  "data": {
    "id": "pi_123",
    "amount": 4999
  }
}

The type determines the shape and meaning of the rest of the payload.

That's essentially an ADT hiding inside JSON.

We can make it explicit:

enum StripeEvent:
  case PaymentSucceeded(
    paymentIntentId: String,
    amountCents: Long
  )

  case PaymentFailed(
    paymentIntentId: String,
    reason: String
  )

  case ChargeRefunded(
    chargeId: String,
    amountCents: Long
  )

  case Unhandled(rawType: String)

Now the rest of the application doesn't need to deal with arbitrary JSON.

The boundary of the application translates the external representation into a domain representation.

For example:

object StripeEvent:

  def fromJson(json: Json): StripeEvent =
    json.hcursor
      .get[String]("type")
      .getOrElse("unknown") match

      case "payment_intent.succeeded" =>
        PaymentSucceeded(
          json.hcursor
            .downField("data")
            .get[String]("id")
            .getOrElse(""),

          json.hcursor
            .downField("data")
            .get[Long]("amount")
            .getOrElse(0L)
        )

      case "payment_intent.payment_failed" =>
        PaymentFailed(
          json.hcursor
            .downField("data")
            .get[String]("id")
            .getOrElse(""),

          json.hcursor
            .downField("data")
            .get[String]("failure_message")
            .getOrElse("unknown")
        )

      case "charge.refunded" =>
        ChargeRefunded(
          json.hcursor
            .downField("data")
            .get[String]("id")
            .getOrElse(""),

          json.hcursor
            .downField("data")
            .get[Long]("amount_refunded")
            .getOrElse(0L)
        )

      case other =>
        Unhandled(other)

The Unhandled case is important.

External systems change.

New Stripe event types can appear without your application being updated at the exact same time.

Instead of turning an unknown event into a MatchError, we can represent it explicitly:

case Unhandled(rawType: String)

The webhook handler can then log it, monitor it, or safely ignore it according to the application's requirements.

The boundary deals with uncertainty. The domain gets a well-defined type.

When a plain enum is enough

Not every closed set needs associated data.

Sometimes you genuinely just have a fixed set of values:

enum Currency:
  case USD, EUR, MXN, GBP

Or:

enum SubscriptionTier derives CanEqual:
  case Free, Pro, Enterprise

This is where Scala 3 enums feel particularly nice.

If you don't need different fields for each case, don't invent them.

Use the simplest representation that accurately models the domain.

What about `sealed trait`?

Scala 3 enums aren't the answer to every ADT-shaped problem.

The traditional approach still has its place:

sealed trait Payment

final case class CreditCard(...) extends Payment
final case class BankTransfer(...) extends Payment
final case class Crypto(...) extends Payment

Reach for this style when the hierarchy needs behavior or structure that doesn't fit naturally into an enum, or when you're deliberately modeling a different kind of abstraction.

The important part isn't whether you wrote:

enum

or:

sealed trait

The important part is that you've created a closed set of alternatives that the compiler can reason about.

A useful smell: `Option` + another field

Here's the heuristic I find particularly useful.

When you see something like:

case class Something(
  state: State,
  valueA: Option[A],
  valueB: Option[B],
  valueC: Option[C]
)

ask yourself:

"Are these options actually optional, or are they only present for certain states?"

If the answer is the latter, you may have an ADT trying to escape from your case class.

For example:

case class Payment(
  status: PaymentStatus,
  approvedAt: Option[Instant],
  failureReason: Option[String]
)

could potentially become:

enum Payment:
  case Pending
  case Approved(at: Instant)
  case Failed(reason: String)

The second version communicates significantly more about the domain.

And more importantly, it makes invalid combinations impossible.

Don't let your ADTs become monsters

There's a limit.

If you end up with:

enum SomeMassiveConcept:
  case A(a: A, b: B, c: C, d: D, e: E, ...)
  case B(a: A, b: B, c: C, d: D, e: E, ...)
  case C(...)
  // ...

with fifteen cases and eight fields each, that's probably a design smell.

You may be modeling several concepts as one giant sum type.

ADTs are about making the domain clearer, not about winning a competition to put your entire business into one enum.

What about `CanEqual`?

Scala 3 introduced stricter equality through CanEqual.

For example:

enum Currency derives CanEqual:
  case USD, EUR, MXN, GBP

enum SubscriptionTier derives CanEqual:
  case Free, Pro, Enterprise

This lets the compiler reject equality comparisons between unrelated types instead of silently treating them as unequal values.

That's a small feature, but it fits the same philosophy:

Push domain mistakes toward compile time whenever the type system can reasonably express them.

The bigger idea: make illegal states unrepresentable

The real value of ADTs isn't that Scala has a nicer syntax for enums.

It's this:

Before:

Order
 ├── status
 ├── paidAt?
 ├── shippedAt?
 └── cancelReason?

      ↓

Many possible combinations
      ↓
Some are invalid
      ↓
Runtime validation required


After:

Order
 ├── Pending
 ├── Paid
 ├── Shipped
 └── Cancelled

      ↓

Only valid shapes can be constructed

You're moving correctness from:

"We need to remember to validate this."

to:

"The compiler won't let us express it incorrectly."

That's a much stronger guarantee.

Takeaway

Every time you write an Option[X] whose presence depends on the value of another field, stop and ask whether you're looking at an ADT.

If the answer is yes, model the alternatives directly.

enum Order:
  case Pending(...)
  case Paid(...)
  case Shipped(...)
  case Cancelled(...)

Then let exhaustive pattern matching make the compiler your safety net.

The goal isn't to use ADTs everywhere.

The goal is to make your types describe the domain closely enough that invalid states have nowhere to hide.

Cheat Sheet

Use ADTs when:

A value is exactly one of several distinct shapes.
Different states require different fields.
You want exhaustive pattern matching.
You're modeling domain states, events, commands, or parsed external data.

Basic Scala 3 syntax:

enum X:
  case A(fieldsForA: Type)
  case B(fieldsForB: Type)

For simple closed sets:

enum Currency:
  case USD, EUR, MXN, GBP

For exhaustive matches:

-Xfatal-warnings

Watch for this smell:

status: Status
foo: Option[Foo]
bar: Option[Bar]
baz: Option[Baz]

If the options depend on status, consider an ADT.

The core idea:

Make illegal states unrepresentable.

Want more Scala 3 domain modeling?

This is one of the patterns I explore in more depth in my book, Scala 3 Domain Design & Typelevel Stack Cookbook.

It's written around practical domain-design recipes rather than trying to be another general Scala introduction.

If you're interested in Scala 3, DDD, and the Typelevel ecosystem, you can find the book here:

Scala 3 Domain Design & Typelevel Stack Cookbook

I built a free image preprocessor to get better OCR results (PrepOCR)

AranaDeDoros — Mon, 07 Sep 2026 23:30:00 +0000

The problem

OCR is only as good as the image you feed it. A scanned form that's slightly tilted, low-contrast, or has a noisy background can tank recognition accuracy — even with a good OCR engine behind it. Most of the time the fix isn't a better OCR model, it's a cleaner input image.

I wanted something small I could throw a batch of images at before sending them to an OCR pipeline, so I built PrepOCR — a free image preprocessing service focused specifically on the transformations that actually move the needle for OCR.

What it does

Right now it supports:

Tilt correction : rotate the image by a given angle
Contrast — boost contrast so text separates more cleanly from the background
Binarization: convert to pure black and white, with a configurable threshold (0–255), which is often the single biggest accuracy win for scanned documents

You upload one or more images, pick your settings, and get back a zip of the optimized versions.

You can try it here

How it's built

The backend is Scala + http4s, AssetFlow. Uploads come in as multipart requests, get validated (size, dimensions, actual image-type sniffing via magic bytes, not just trusting the extension), processed, and zipped back up.

One thing worth sharing: since each image's transformation is CPU-bound and independent of the others, I moved the per-file processing from a sequential traverse to parTraverseN, so a batch of images gets processed concurrently instead of one at a time. On my machine (14 cores), converting/optimizing 4 PNGs dropped from ~7s to ~2s. On the free-tier host it's deployed on, that gain mostly evaporates — CPU is throttled hard enough that "parallel" mostly just means "finely interleaved" rather than truly concurrent. Cheap and free lesson: Runtime.getRuntime.availableProcessors() will happily lie to you about how much CPU you actually have in a shared container.

Where it's at

This is genuinely an MVP, I built it because I needed it, not because I've validated demand. No idea yet if anyone else will find it useful, but if you're doing anything with scanned documents, forms, or OCR pipelines and want to try offloading the preprocessing step, I'd love feedback.

Feature requests, bug reports, and "this already exists and does it better" comments are all welcome.

Stop Passing Strings Around Your Scala Domain

AranaDeDoros — Wed, 02 Sep 2026 23:26:46 +0000

At some point in every codebase, someone writes a function like this:

def transferMoney(
  fromAccount: String,
  toAccount: String,
  amount: BigDecimal
): F[Unit]

Looks harmless.

Until someone does this:

transferMoney(toAccount, fromAccount, amount)

The compiler is perfectly happy.

String is String is String.

You don't discover the mistake until the wrong account gets charged.

This is one of the things I enjoy about Scala: it gives you tools to make these mistakes impossible to express in the first place.

The obvious solution: a wrapper

One way to solve the problem is to introduce a domain type:

final case class AccountId(value: String)

Now the compiler can distinguish an AccountId from a String.

That's already a huge improvement.

But sometimes you don't actually need a new runtime object. You just need the compiler to understand that these two Strings represent different things.

That's where Scala 3's opaque types become interesting.

Opaque types

An opaque type lets you create a distinct type at compile time while retaining the underlying representation at runtime.

opaque type AccountId = String

object AccountId:
  def apply(raw: String): AccountId = raw

  extension (id: AccountId)
    def value: String = id

Now we can define:

opaque type MerchantId = String
opaque type Cents = Long

and our domain can become much more explicit:

def transferFunds(
  from: AccountId,
  to: AccountId,
  amount: Cents
): IO[Unit] =
  IO.println(s"Transferring $amount from $from to $to")

The important part isn't that the code looks nicer.

It's what the compiler prevents.

Given:

val accountId: AccountId = AccountId("account-123")
val merchantId: MerchantId = MerchantId("merchant-456")
val cents: Cents = Cents(5000)

this is fine:

transferFunds(accountId, accountId, cents)

while this isn't:

transferFunds(merchantId, accountId, cents)

Even though both AccountId and MerchantId are represented by String underneath.

We've moved the bug from:

"Someone eventually noticed the wrong value was passed."

to:

"The compiler won't let me write this."

That's a pretty good trade.

But what about runtime overhead?

This is one of the reasons I like opaque types for small domain primitives.

A case class introduces a wrapper:

final case class AccountId(value: String)

An opaque type doesn't introduce a new runtime wrapper around the underlying value.

Conceptually:

AccountId → String
MerchantId → String
Cents → Long

at runtime, while remaining distinct types to the compiler.

That makes opaque types particularly attractive for domain concepts that are fundamentally represented by primitives:

Account IDs
User IDs
Merchant IDs
Emails
Currency amounts
Version strings
External reference IDs

You get stronger domain boundaries without changing the underlying representation.

Opaque types aren't just for IDs

Consider email addresses.

You could have:

opaque type Email = String

object Email:
  def parse(raw: String): Either[String, Email] =
    if raw.matches("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$")
    then Right(raw)
    else Left(s"'$raw' is not a valid email")

  extension (email: Email)
    def value: String = email

Now your application can distinguish:

String from Email

and, more importantly, you can establish an invariant:

If I have an Email, it has already passed my validation.

Instead of scattering validation throughout the application:

def sendEmail(address: String): ...

you can make the boundary explicit:

def sendEmail(address: Email): ...

The function doesn't need to wonder whether the string is valid.

Someone had to construct an Email first.

This is one of the ideas that makes type-driven domain design so powerful: push invalid states toward the boundaries of your system.

There's a catch

Opaque types aren't a magic replacement for every case class.

If your concept has several related pieces of data:

case class Money(
  amount: BigDecimal,
  currency: Currency
)

a case class is probably the better abstraction.

Opaque types work particularly well when you have:

"this String actually means X"

or:

"this Long actually means Y"

They are also worth understanding when you're working with libraries such as Cats, Cats Effect, http4s, and Circe.

One thing that can surprise you is that type class instances don't automatically appear just because the underlying type has one.

For example, if you want to serialize:

AccountId

you may need to explicitly provide the appropriate encoder/decoder rather than expecting the String instance to magically apply.

That's a small amount of boilerplate, but it's worth knowing before introducing opaque types everywhere.

A useful rule of thumb

The next time you see this:

def process(
  userId: String,
  accountId: String,
  externalId: String
): ...

stop for a second.

Ask yourself:

Are these really three Strings?

They probably aren't.

They're three different concepts that happen to share the same representation.

That's exactly the kind of situation where opaque types shine.

opaque type UserId = String
opaque type AccountId = String
opaque type ExternalId = String

Now the compiler knows something that your original function didn't express.

And that's ultimately why I like this feature.

The goal isn't to use more types for the sake of using more types.

The goal is to make the domain model communicate things that would otherwise exist only in developers' heads.

DDD and Typelevel cookbook

AranaDeDoros — Mon, 31 Aug 2026 15:34:39 +0000

Hello everyone.

Scala's a programming language I've enjoyed learning on the side not only because I think it's stylish but because it's made me a better developer.

Some of the gripes you encounter once you try to go intermediate or beyond, it's the Typelevel stack complexity. You just want to bootstrap a server and start writing some routes, and tbh sometimes the docs aren't that friendly. That's why I wrote Scala 3 Domain Design & Typelevel Stack Cookbook — a book that teaches some DDD in Scala and gives you some recipes to get you started on the stack (cats, cats-effects, fs2, http4s).

It's a WIP currently at 40%. You can read a couple of chapters for free in leanpub: https://leanpub.com/scala3-domain-typestack-dev

Representing Music with Code

AranaDeDoros — Tue, 11 Aug 2026 22:32:40 +0000

Chordal: a Scala DSL for music theory

Another post about my previous DSL experiments. This time, the target was a different hobby of mine: music. Chordal is another DSL experiment in Scala to represent music elements; working with Notes to create Chords, and then using those same Chords to build Progressions.

I thought "Chordal" was an original name until I found plenty of repos with the same one. Oh well.

Some of the challenges I faced came from building the AST. Music theory is a huge world with a lot of inherent structure and composition rules baked in. The atomic unit could be considered the pitch, which gains meaning once paired or grouped: two or three of them become a note, then a triad. Add one more and you've got a tetrachord. Keep stacking and you're into extended chords, which open up a lot of contexts that are genuinely hard to represent cleanly.

Then there's the diatonic vs. chromatic scale problem. The chromatic scale is useful for movement/transposition (going from one note to another by some number of steps), but that convenience comes with a catch: correct representation. Enter enharmonics, the fact that a note or chord can be spelled in different ways and still be "the same" pitch, but not the same note in context. Db and C# are a good example: same pitch, different note depending on what's around it.

What a rant. There are probably some errors, both in theory and in code, but I can live with that for now. It was a ride.

Features

Working enharmonics.
Extension methods to work with strings as notes.
Useful rendering of notes.
Harmony
- Chord creation
- Triads.
- Tetrachords (subject to model changes, partial support).
- Add chords.
- Power chords.
- Suspended chords.
- Partial extension support.
- Progressions
- Generic list-like implementation.
- Quick default methods for building common progressions.

Usage

DSL

package org.aranadedoros.chordal

import chords.*
import dsl.*
import dsl.Notes.{A, D, E, G}
import extensions.Ninth
import notes.{dim, major, note, pow, Note}

import scala.language.postfixOps

// work in progress, subject to change
val C = Note("C")

val chord1 =
  chord {
    root(C)
    quality(MajorTriad)
    withExtensions(Ninth)
  }
println(chord1)

val chord2 =
  chord {
    root("D".note)
    sus(Sus4)
  }
println(chord2)

val chord3 =
  chord {
    root(E)
  }
println(chord3)

val dMajor: Triad =
  D major
println(dMajor)

val eMajorWithBassOnG: SlashChord =
  E.major / G
println(eMajorWithBassOnG)

val g5: PowerChord =
  G pow
println(g5.name)

val adim7 =
  A.dim withSeventh MinorSeventh
println(adim7)

Output

C9
Dsus4
E5
(D,F#,A)
(E,G#,B)/G
G5
(A,C,Eb,G)

Overall, this project turned out really satisfying. It scratched my DSL itch for a good long while. I don't think I'll be doing another one anytime soon.

https://github.com/AranaDeDoros/Chordal

Backend template for Scala

AranaDeDoros — Mon, 23 Feb 2026 16:09:43 +0000

Something I've always found somewhat grating is setting up scala projects, so a few days ago I decided to make a template for backend projects using the Typelevel stack.

It's got a basic, pragmatic folder structure with the goal of concern separation and resource management.

Check it out

What Happens When One Parallel Call Fails? Structured Concurrency in Scala

AranaDeDoros — Thu, 12 Feb 2026 22:38:30 +0000

When building backend systems, we often fan out to multiple services in parallel:

Price providers
Recommendation engines
Search indexes
Payment gateways

The real question isn't "How do I run these in parallel?"

It's:

What happens if one fails?
What happens if one times out?
Do retries leak work?
Can I keep partial results?

I explored this while building a small price aggregation simulator in Scala 3 using Cats Effect.

The scenario

The setup was simple:

Multiple providers
Each returns a price
We call them in parallel
We aggregate the results

But the interesting part wasn't parallelism.

It was failure semantics.

The Core Abstraction

trait PriceProvider[F[_]]:
  def name: ProviderName
  def fetchPrice(productId: ProductId): F[Price]

Providers may fail.

One specific failure is modeled explicitly:

sealed trait ProviderError extends Throwable
final case class TimeOutError(provider: String,time: LocalDateTime) 
extends ProviderError(s"$provider timed out", time)

Timeouts are not transport hacks.

They are part of the domain.

Retry as a Decorator

Instead of baking retry into the provider, I wrapped providers with a retry policy:

def retryOnTimeout[A](
  fa: IO[A],
  maxRetries: Int,
  delay: FiniteDuration
): IO[A] =

  def loop(attempt: Int): IO[A] =
    fa.handleErrorWith {
      case _: TimeOutError if attempt < maxRetries =>
        IO.sleep(delay) *> loop(attempt + 1)
      case e =>
        IO.raiseError(e)
    }

  loop(0)

Then composed it:

final class RetryingProvider(
  underlying: PriceProvider[IO],
  maxRetries: Int,
  delay: FiniteDuration
) extends PriceProvider[IO]:

  override def fetchPrice(productId: ProductId): IO[Price] =
    retryOnTimeout(
      underlying.fetchPrice(productId),
      maxRetries,
      delay
    )

Important detail:

Only timeouts retry
Other failures propagate immediately
The underlying provider remains untouched

Retry is a policy layer, not embedded behavior.

Aggregation Strategy #1 — Fail Fast

def fetchAll(
  providers: List[PriceProvider[IO]],
  productId: ProductId
): IO[List[Price]] =
  providers.parTraverse(_.fetchPrice(productId))

Semantics:

All providers run in parallel
If one fails, the whole operation fails
Remaining providers are cancelled

This is strict and correct when all results are required.

Aggregation Strategy #2 — Keep Partial Results

Sometimes partial success is acceptable.

So instead of failing the entire computation, we capture results explicitly:

def fetchSafe(
  provider: PriceProvider[IO],
  productId: ProductId
): IO[ProviderResult] =
  provider.fetchPrice(productId)
    .map(price =>
      ProviderResult.Success(provider.name, price)
    )
    .handleError {
      case e: ProviderError =>
        ProviderResult.Failure(provider.name, e)
    }

Then aggregate:

def fetchAllPartial(
  providers: List[PriceProvider[IO]],
  productId: ProductId
): IO[List[ProviderResult]] =
  providers.parTraverse(p => fetchSafe(p, productId))

Now:

All providers run in parallel
Failures don't cancel siblings
Partial results are preserved
The operation always completes

Different policy. Same building blocks.

Optional: Enforcing a Quorum

You can even require a minimum number of successes:

def requireAtLeast(
  n: Int,
  results: List[ProviderResult]
): IO[List[(ProviderName, Price)]] =
  val successes = results.collect {
    case ProviderResult.Success(p, price) => (p, price)
  }

  if successes.size >= n then IO.pure(successes)
  else IO.raiseError(new RuntimeException("Not enough providers"))

Now the system supports:

Fail-fast
Partial aggregation
Quorum-based acceptance

All composed explicitly.

What This Experiment Revealed

The interesting part wasn't syntax. It was separation of concerns.

The system has three independent policy layers:

1. Failure classification (timeouts vs other errors)

2. Retry behavior (decorator)

3. Aggregation strategy (fail-fast vs partial vs quorum)

None of them are tangled together.

That's the real value.

When to retry
When to cancel
When partial results are acceptable
When to fail the whole operation

The abstraction you choose determines how clearly you can express those decisions.

And that's a backend engineering concern, not a language feature.

Using Scala to build tooling for Django

AranaDeDoros — Mon, 02 Feb 2026 06:01:25 +0000

   ____      _               ____            
/ ___|___ | |__  _ __ __ _ / ___| ___ _ __
| |   / _ \| '_ \| '__/ _` | |  _ / _ \ '_ \
| |__| (_) | |_) | | | (_| | |_| |  __/ | | |
\____\___/|_.__/|_|  \__,_|\____|\___|_| |_|

Some of the best parts of being a polyglot developer are being able to combine your favorite languages in practical ways.

At my current job, I haven’t had many opportunities to use Scala until recently. Even if I wanted to, I can’t (and shouldn’t) force my language preferences on my teammates. What I can do is build tooling that benefits everyone.

That’s usually how these projects start: small tools to make my own life easier.

We’ve been using Django quite a bit, and I found myself writing the same model boilerplate over and over. So I built Cobragen, a small CLI tool that generates a models.py file from a YAML schema definition.

Usage

Make a yaml file with your models schema, like this:

models:
  - name: UserProfile
    fields:
      - name: username
        type: Char
        maxLen: 50
        unique: true

      - name: bio
        type: TextField
        required: false

      - name: age
        type: Integer

      - name: balance
        type: Decimal
        maxDigits: 12
        places: 2

      - name: created_at
        type: DateTime

      - name: is_verified
        type: Boolean

  - name: Post
    fields:
      - name: author
        type: ForeignKey
        to: UserProfile
        onUpdate: CASCADE

      - name: title
        type: Char
        maxLen: 200

      - name: content
        type: TextField

      - name: published_date
        type: Date
        required: false

then run:

cobragen <schema.yml> [--sort] [--name <output>]

--sort — sort models alphabetically by name before generation (default: false)
--name <filename> — custom output filename (default: models.py)

This will generate a .py file with your models:

from django.db import models


class Post(models.Model):
    author = models.ForeignKey("UserProfile", on_delete=models.CASCADE)
    title = models.CharField(max_length=200)
    content = models.TextField()
    published_date = models.DateField(null=True, blank=True)

class UserProfile(models.Model):
    username = models.CharField(max_length=50, unique=True)
    bio = models.TextField(null=True, blank=True)
    age = models.IntegerField()
    balance = models.DecimalField(max_digits=12, decimal_places=2)
    created_at = models.DateTimeField()
    is_verified = models.BooleanField()

It has its lil problems, but I can live with them. It has partial feature support and covers what I currently need; it was a nice exercise in schema modeling and code generation across ecosystems.

Repo

Building a Nim library: Monika

AranaDeDoros — Tue, 27 Jan 2026 15:07:38 +0000

Recently I went through a phase of learning Nim. It was a good time, but I ultimately decided not to dwell too deep into it. This journey however spawned a microlibrary: Monika.

I started Nim on a whim because I wanted to have a system's programming language under my belt or at least native compilation, better speed and for the sake of applying what I was learning. I did C a lot of years ago, but I didn't want to deal with pointers directly and Rust syntax was a bit too much for me (even though I'm used to seeing some unsightly Scala's method signatures).

This library is actually a port from my own library JpnUtils written in Scala. It has a few extra functions that I didn't include in JpnUtils.

Monika is a Japanese strings microlibrary for Nim. It provides a clean, "implicit-style" API for handling characters, strings, and conversions.

Features

Implicit Conversions: Treat standard strings as Japanese objects via Nim converters.
Script Detection: Easily check for Hiragana, Katakana, and Kanji.
Diacritics: Detect Dakuten (voiced) and Handakuten (semi-voiced) marks.
Half-Width Conversion: Efficiently convert between full-width and half-width forms.
Punctuation Wrappers: Scala-style string wrapping for Japanese quotes.

Usage

Monika uses a converter to extend standard strings. Simply import Monika and start using the utility methods.

import monika/japaneseutils
import monika/punctuation
import monika/halfwidthconverter

if "こんにちは".hasHiragana:
  echo "Contains Hiragana!"

if "モニカ".hasKatakana:
  echo "Contains Katakana!"

if "学校".hasKanji:
  echo "Contains Kanji!"

# full-width to half-width
echo "ハロー、ワールド！".toHalfWidth
# Output: ﾊﾛｰ､ﾜｰﾙﾄﾞ!

# Check for voiced marks
if "が".hasDakuten:
  echo "This character is voiced."

let msg = "Hello"
echo msg.wrapInSingleQuotes # Output: 「Hello」
echo msg.wrapInDoubleQuotes # Output: 『Hello』

let s = "ガキ"
let h = "が".asRune()
let k = "エ".asRune()

if h.isSome:
  echo h.get.hiraToKata() # Output: カ
else:
  echo "empty string"

if k.isSome:
  echo k.get.kataToHira() # Output: え
else:
  echo "empty string"

let str = "日本語abcカナ"
echo str.containsOnly({Kanji, Katakana})  # false
let summary = str.scriptSummary()

echo summary.hiragana  # 0
echo summary.katakana  # 2
echo summary.kanji     # 3
echo summary.other     # 3

It was a good experience, but If I were to be honest; I don't see myself using Nim that much outside of really niche things and even so, I might reconsider it. Maybe I'll make a post in the future about what I don't like about the actual Nim ecosystem.

If you wanna check it out, the repo's here

Nim + FastAPI experiment

AranaDeDoros — Wed, 21 Jan 2026 14:00:00 +0000

Why use one language when you can use two?

I've been experimenting with FastAPI and Nim lately, and I decided to bridge them together to build a simple PDF merger.

The goal? Offload the possible heavy binary lifting of PDF generation to Nim (which compiles to C) while keeping the web layer comfy with Python.

Nim process:

import nimpdf
import nimpdf/image
import os
import times

proc makePDF(outputPath: string, files: seq[string]): bool =
  let factorX = 20.0
  let factorY = 200.0
  var pdf = newPDF()

  for file in files:
    block:
      discard pdf.addPage("A4")
      let img = loadImage(file)

      if img == nil:
        echo "Warning: Could not load ", file
        continue

      pdf.drawImage(factorX, factorY, img)

  return pdf.writePDF(outputPath)

when isMainModule:
  let start = cpuTime()
  if paramCount() < 2:
    quit "Usage: pdf_merger <output.pdf> <images...>", QuitFailure

  let outputPath = paramStr(1)
  var images: seq[string] = @[]
  for i in 2 .. paramCount():
    images.add paramStr(i)

  if makePDF(outputPath, images):
    let duration = cpuTime() - start
    echo "PDF created in ", duration, " seconds at ", outputPath
    quit QuitSuccess
  else:
      quit "Failed to write PDF", QuitFailure

The endpoint:

@app.post("/upload-multiple-files/")
async def create_upload_files(files: List[UploadFile] = File(...)):
    start = time.perf_counter()
    job_id = str(uuid.uuid4())
    output_filename = os.path.join(OUTPUT_DIR, f"{job_id}.pdf")

    uploaded_paths = []
    for file in files:
        unique_img_name = f"{uuid.uuid4()}_{file.filename}"
        file_path = os.path.join(UPLOAD_DIR, unique_img_name)
        with open(file_path, "wb") as buffer:
            shutil.copyfileobj(file.file, buffer)
        uploaded_paths.append(file_path)

    def run_nim():
        return subprocess.run(
            [NIM_EXE_PATH, output_filename] + uploaded_paths,
            capture_output=True,
            text=True
        )

    result = await anyio.to_thread.run_sync(run_nim)

    if result.returncode == 0:
        end = time.perf_counter()
        duration = end - start
        return FileResponse(
            path=output_filename,
            filename="merged_images.pdf",
            media_type="application/pdf",
            headers={"X-Duration-Seconds": str(duration)}
        )
    else:
        return {"status": "error", "error": result.stderr}

Result:

The "Dirty" Details:

• The Bridge: FastAPI handles the multi-part file uploads, saves them, and then kicks off a Nim subprocess to "plaster" the images onto an A4 page.

• The Windows Trap: If you've ever tried spawning subprocesses in asyncio on Windows, you've likely met the NotImplementedError. I bypassed this using anyio.to_thread. It's a "sync-in-async" hack that keeps the server non-blocking.

• Performance: nimpdf is impressively lightweight. It makes the "binary crunching" part of the stack feel almost instant.

Why do this? Mostly curiosity. I wanted to see how much friction there was in passing data into a systems-level binary from a high-level web framework. Turns out, once you get the subprocess logic right, it's a pretty powerful pattern.

Note: From what I've read, while the subprocess approach worked, a more "pro" move would be to compile Nim to a .so file.

Feature	Subprocess	Shared Library (.so/FFI)
Setup Complexity	Low: Just call a CLI command.	High: Requires C-bindings and type mapping.
Performance	Medium: Overhead for process startup.	Maximum: Native speed, zero startup lag.
Stability	High: If Nim crashes, Python lives.	Risky: If Nim crashes, the whole server dies.
Memory	Isolated: Separate memory space.	Shared: Very efficient but easy to leak.
Best For	Quick tools and background tasks.	High-frequency, real-time operations.

Instead of Python calling a program, Python becomes the program, executing Nim code natively via C-bindings. This removes the OS overhead of spawning processes and keeps everything in-memory.

Take a peek. Beware, it's not validated, this was just a proof of concept.

Building My First Scala DSL (and the Design Mistakes I Made)

AranaDeDoros — Tue, 20 Jan 2026 19:31:03 +0000

I’ve always liked DSLs, but building one turned out to be more humbling than I expected. ScalaCron was my first real attempt at designing an embedded DSL, and while it works, it also taught me a few lessons the hard way.

Some months I decided to pick up Scala again and make some projects. One of them was my first embedded DSL experiment : ScalaCron. A DSL to generate cronjob expressions programatically.

Just in case you aren't familiar with the term, a Domain Specific Language is a language used for very specific fields. It attempts to solve the complexity of a language by removing imperative programming in favor of a more declarative approach. It has a syntax that tells what will be done instead of how to do it. There are two types: external languages and non-external. The difference is that the former runs on top of a host language and the latter does not. Some popular DSLs of both types are: SQL, Regex, and Makefiles (external), and LINQ, Scala collections, and Gradle Kotlin DSL (non-external).

Scala syntax and abstractions make writing DSLs relatively easy.

DSL development is a two layer architecture design. I knew this before, but it hit me harder a bit too late, perhaps.

What are these two layers?
1.- Domain modeling.
2.- Syntax and interpretation layer.

Designing the domain was relatively easy, but soon enough I faced a point at which, even though I had a safe model layer, it made it difficult to make the syntax more English-like.

I had this method for expressions to validate their values:

    final def applyValidated(value: A): Either[CronError, CronExpr[A]] =
      if range.contains(value) && pf.isDefinedAt(value) && pf(value) then
        Right(At(build(value)))
      else
        Left(InvalidRange(value, range.end))

At the time it worked just fine, but when I was moving on to making the syntax prettier, I found that the handling of errors leaked through and made abstracting things harder (not impossible, but syntactically ugly).

At some point I had something like:

  import CronDSL.*

    val job = CronJobExpr.build { c =>
      c.m = * / 5
      c.h = 12.h
      c.dom = 1.dom
      c.dow = 1.dow
    }

    println(job) //*/5 12 1 1

which needed a builder and I didn't like it.

After applying some abstractions and making tradeoffs for keeping my sanity without refactor, I decided to move validation to the interpretation layer:

private def validateExpr(expr: CronExpr[Int]): List[CronError] =
      expr match {

        case At(v) =>
          validateValue(v)

        case Range(from, to) =>
          validateValue(from) ++
            validateValue(to) ++
            validateRangeOrder(from, to)

        case ListExpr(values) =>
          values.flatMap(validateValue)

        case Every(step, field) =>
          val stepErrors =
            if (step <= 0) List(InvalidStep(step)) else Nil
          stepErrors

        case Step(from, step) =>
          val stepErrors =
            if (step <= 0) List(InvalidStep(step)) else Nil
          validateValue(from) ++ stepErrors
      }

Granted it made things easier, but I still feel a bit guilty that validation was delayed this way.

In the end, I decided not to refactor as this was just an experiment and the syntax was just good enough

import domain.Models.*
import domain.Models.Minute.given
import dsl.CronDSL.{to, *}
import Days.*
import scala.language.postfixOps

object Main :
  def main(args: Array[String]): Unit =

  val job2 = cron { c =>
    c.minute(* / 5)
    c.hour(2.h)
    c.dom(1.dom)
    c.dow(Friday)
  } >> "/usr/bin/backup.sh"
  println(job2?) //same as job.schedule
  println(job2) //whole expression as string

/*
- Minute        : every 5 minutes
- Hour          : at 2
- Day of Month  : at 1
- Day of Week   : Friday
*/5 2 1 5 /usr/bin/backup.sh
*/

In an upcoming post, I’ll walk through a second DSL where I applied these lessons from the start, especially around validation, layering, and syntax design and the results were noticeably better.

ScalaCron repo

DEV Community: AranaDeDoros

ADTs & Enums in Scala 3: Making Illegal States a Compile Error

ADTs & Enums in Scala 3

The problem with "status + optional fields"

Model the states instead

The compiler becomes part of your test suite

ADTs aren't just for business entities

When a plain enum is enough

What about sealed trait?

A useful smell: Option + another field

Don't let your ADTs become monsters

What about CanEqual?

The bigger idea: make illegal states unrepresentable

Takeaway

Cheat Sheet

Want more Scala 3 domain modeling?

I built a free image preprocessor to get better OCR results (PrepOCR)

The problem

What it does

How it's built

Where it's at

Stop Passing Strings Around Your Scala Domain

Opaque types

DDD and Typelevel cookbook

Representing Music with Code

Chordal: a Scala DSL for music theory

Features

Usage

DSL

Output

Backend template for Scala

What Happens When One Parallel Call Fails? Structured Concurrency in Scala

The scenario

The Core Abstraction

Retry as a Decorator

Aggregation Strategy #1 — Fail Fast

Aggregation Strategy #2 — Keep Partial Results

Optional: Enforcing a Quorum

What This Experiment Revealed

Using Scala to build tooling for Django

Usage

Building a Nim library: Monika

Features

Usage

Nim + FastAPI experiment

Building My First Scala DSL (and the Design Mistakes I Made)

What about `sealed trait`?

A useful smell: `Option` + another field

What about `CanEqual`?