moka
Macro that creates a Fields object with the names of a case class' fields,
so MongoDB filters and projections don't need hardcoded strings. Misspelled
field names fail at compile time.
Works on Scala 2.13 and Scala 3 (3.3 LTS) — including cross-compiled
codebases sharing the same sources.
Installation
libraryDependencies += "io.github.vimalaguti" %% "moka" % "0.1.0"
On Scala 2.13 @moka is a macro annotation, so the compiler flag that
expands those is required:
scalacOptions ++= (CrossVersion.partialVersion(scalaVersion.value) match {
case Some((2, 13)) => Seq("-Ymacro-annotations")
case _ => Nil
})
Without it the annotation is silently left in place and every Fields
selection fails with not a member of io.moka.FieldsNotGenerated_AddYmacroAnnotations
(with @moka alone: not found: value Fields).
Scala 3 needs no flags.
Example
Cross-compiled style (works on both versions):
import io.moka._
@moka
case class Apple(color: String)
object Apple {
val Fields = generateFields[Apple]
}
Apple.Fields.color == "color"
Apple.Fields.colour // does not compile
Scala 2 only — the annotation generates the companion by itself:
@moka
case class Apple(color: String)
Apple.Fields.color == "color"
Scala 3 only — no annotation needed:
case class Apple(color: String)
object Apple {
val Fields = generateFields[Apple]
}
Renaming annotations
Fields annotated with @BsonProperty (mongo-scala-bson) or @bsonField
(zio-bson) keep their Scala name but carry the annotated wire name as value:
@moka
case class Fruit(@BsonProperty("c") color: String, @bsonField("w") weight: Double)
object Fruit {
val Fields = generateFields[Fruit]
}
Fruit.Fields.color == "c"
Fruit.Fields.weight == "w"
JSON and explicit format selectors
generateFields (and @moka) defaults to MongoDB's BSON wire format and ignores
JSON annotations, avoiding unintended renames in Mongo queries.
To target JSON or project both formats from the same model, use generateBsonFields / @mokaBson and generateJsonFields / @mokaJson:
@moka
case class Fruit(
_id: String,
@BsonProperty("b_col") @jsonField("color") color: String
)
object Fruit {
val BsonFields = generateBsonFields[Fruit] // BsonFields.color == "b_col"
val JsonFields = generateJsonFields[Fruit] // JsonFields.color == "color"
}
- Supported JSON annotations:
@jsonField (zio-json), matched by simple name without library dependencies.
- Conflict detection: if conflicting annotations appear for the same format (e.g.
@BsonProperty("a") and @bsonField("b")), compilation fails fast with an informative error. Agreeing annotations succeed.
Nested fields
A field whose type is another case class becomes a path node exposing that
type's fields, each carrying the dotted path MongoDB expects:
@moka
case class Engine(power: Int)
object Engine {
val Fields = generateFields[Engine]
}
@moka
case class Car(engine: Engine, wheels: List[Engine])
object Car {
val Fields = generateFields[Car]
}
Car.Fields.engine.power == "engine.power"
Car.Fields.engine._path == "engine"
Option and collections are transparent (List[Engine] gives the same path).
A collection of case classes also exposes MongoDB's array operators:
Car.Fields.wheels._matched.power == "wheels.$.power" // positional $
Car.Fields.wheels._all.power == "wheels.$[].power" // $[]
Every generated member starts with an underscore (_path, _matched, _all),
so it can never collide with a field of your own.
On Scala 2.13 — and so in cross-compiled sources — every nested case class
needs its own moka object (since 0.2.0), as Engine has above: the outer
object takes the nested names from it, which is what keeps zio-bson and
zio-json renames correct across modules, jars and incremental builds. Without
one, compilation fails and says what to add. Scala 3 needs none. See the
Scala 2 page for the details and the opt-out.
Usage idea
When using mongodb, you are required to set the field name when filtering or
for projections. With this macro you can avoid setting the name manually and
instead use the Fields object.
License
Apache-2.0. Copyright 2026 Vittorio Malaguti.
