@zio.dev/zio-blocks 0.0.1 → 0.0.22

package/reference/modifier.md

@@ -5,71 +5,143 @@ title: "Modifier"
 
 `Modifier` is a sealed trait that provides a mechanism to attach metadata and configuration to schema elements. Modifiers serve as annotations for record fields, variant cases, and reflect values, enabling format-specific customization without polluting domain types.
 
-Unlike Scala annotations, modifiers are **pure data** values that can be serialized, making them ideal for runtime introspection and cross-process schema exchange.
+Modifiers are designed to be **pure data** values that can be serialized, making them ideal for runtime introspection and cross-process schema exchange. When deriving schemas, modifiers are collected and attached to the corresponding fields or types, allowing codecs to read and interpret them accordingly. They are extended with `StaticAnnotation` to also support annotation syntax:
 
 ```scala
 sealed trait Modifier extends StaticAnnotation
+object Modifier {
+  sealed trait Term    extends Modifier
+  // ... term modifiers (transient, rename, alias, config) ...
+  sealed trait Reflect extends Modifier
+  // ... reflect modifiers (config) ...
+}
 ```
 
-## Modifier Hierarchy
+Modifiers can be applied in two ways:
 
-```
-┌────────────────────────────────────────────────────────────────┐
-│                         Modifier                               │
-├────────────────────────────────────────────────────────────────┤
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │  Modifier.Term                                          │   │
-│  │  (annotates record fields and variant cases)            │   │
-│  │                                                         │   │
-│  │  - transient()      : exclude from serialization        │   │
-│  │  - rename(name)     : change serialized name            │   │
-│  │  - alias(name)      : add alternative name              │   │
-│  │  - config(key, val) : attach key-value metadata         │   │
-│  └─────────────────────────────────────────────────────────┘   │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │  Modifier.Reflect                                       │   │
-│  │  (annotates reflect values / types)                     │   │
-│  │                                                         │   │
-│  │  - config(key, val) : attach key-value metadata         │   │
-│  └─────────────────────────────────────────────────────────┘   │
-└────────────────────────────────────────────────────────────────┘
+1. **Programmatic API**: Using the `Schema#modifier` and `Schema#modifiers` methods to attach modifiers to the entire schema or, for field-level modifiers, attach them to specific fields using optics when deriving codecs. This approach keeps your domain types clean and allows you to separate schema configuration from your data model:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+// Clean domain type - zero dependencies
+case class User(
+  id: String,
+  name: String,
+  cache: Map[String, String] = Map.empty
+)
+
+// Modifiers applied separately to schema and codecs
+object User extends CompanionOptics[User] {
+  implicit val schema: Schema[User] = Schema
+    .derived[User]
+    .modifier(Modifier.config("db.table-name", "users"))
+
+  implicit val jsonCodec: JsonBinaryCodec[User] =
+    schema
+      .deriving[JsonBinaryCodec](JsonBinaryCodecDeriver)
+      .modifier(User.name, Modifier.rename("username"))
+      .modifier(User.cache, Modifier.transient())
+      .derive
+
+  lazy val id   : Lens[User, String]              = $(_.id)
+  lazy val name : Lens[User, String]              = $(_.name)
+  lazy val cache: Lens[User, Map[String, String]] = $(_.cache)
+}
 ```
 
-## Term Modifiers
+In the above example, we derived a JSON codec for `User` and applied the `rename` and `transient` modifiers to the `name` and `cache` fields respectively, while keeping the domain type free of any schema-related annotations. Now when encoding a `User` to JSON, the `name` field will be serialized as `username`, and the `cache` field will be omitted. During decoding, the codec will look for `username` in the input JSON and populate the `name` field accordingly:
 
-Term modifiers annotate record fields and variant cases. They are used during schema derivation to customize how fields are serialized and deserialized.
+```scala
+val user = User(
+  id = "123",
+  name = "Alice",
+  cache = Map("lastLogin" -> "2024-06-01T12:00:00Z")
+)
+val json: String = User.jsonCodec.encodeToString(user)
+println(json)
+// Prints: {"id":"123","username":"Alice"}
+val decodedUser: Either[SchemaError, User] = User.jsonCodec.decode(json)
+println(decodedUser)
+// Prints: Right(User(123,Alice,Map()))
+```
 
-### transient
+Please note that when deriving codecs, you can access these modifiers programmatically, allowing you to build custom logic based on the presence of certain modifiers. For example, your SQL codec could check for the presence of `db.table-name` in the schema modifiers to determine which table to read from or write to.
 
-The `transient` modifier marks a field as transient, meaning it will be excluded from serialization. This is useful for computed fields, caches, or sensitive data that shouldn't be persisted.
+2. **Annotation Syntax**: Using the `@` syntax to annotate fields and cases directly in your case classes and sealed traits. These annotations are processed during schema derivation to attach the corresponding modifiers to the schema elements. At runtime, you can access these modifiers through the `Reflect` structure of the schema.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
+import zio.blocks.schema.Modifier._
 
+@Modifier.config("db.table-name", "users")
 case class User(
-  id: Long,
-  name: String,
-  @Modifier.transient cache: Map[String, String] = Map.empty
+  id: String,
+  @Modifier.rename("username") name: String,
+  @Modifier.transient() cache: Map[String, String] = Map.empty
 )
 
-object User {
-  implicit val schema: Schema[User] = Schema.derived
+object User extends CompanionOptics[User] {
+  implicit val schema: Schema[User] =
+    Schema.derived[User]
+
+  implicit val jsonCodec: JsonBinaryCodec[User] =
+    schema
+      .derive[JsonBinaryCodec](JsonBinaryCodecDeriver)
 }
 ```
 
-When encoding a `User` to JSON, the `cache` field will be omitted:
+In this example, we applied the same modifiers as in the programmatic example, but using annotation syntax directly on the case class fields. Let's try encoding and decoding a `User` instance:
+
+```scala
+val user = User(
+  id = "123",
+  name = "Alice",
+  cache = Map("lastLogin" -> "2024-06-01T12:00:00Z")
+)
+
+val json: String = User.jsonCodec.encodeToString(user)
+println(json)
+// Prints: {"id":"123","username":"Alice"}
+val decodedUser: Either[SchemaError, User] = User.jsonCodec.decode(json)
+println(decodedUser)
+// Prints: Right(User(123,Alice,Map()))
+```
+
+## Modifier Hierarchy
+
+Modifiers are organized into two main categories:
+
+1. **Term modifiers** - annotate record fields or variant cases (the data structure elements)
+2. **Reflect modifiers** - annotate schemas/reflect values themselves (the metadata about types)
 
-```json
-{"id": 1, "name": "Alice"}
 ```
+Modifier
+ ├── Modifier.Term     (annotates record fields and variant cases)
+ │    ├── transient()      : exclude from serialization
+ │    ├── rename(name)     : change serialized name
+ │    ├── alias(name)      : add alternative name
+ │    └── config(key, val) : attach key-value metadata
+ └── Modifier.Reflect  (annotates reflect values / types)
+      └── config(key, val) : attach key-value metadata
+```
+
+As you can see, `config` is the only modifier that extends both `Term` and `Reflect`, allowing it to be used on both fields and types.
+
+## Term Modifiers
+
+Term modifiers annotate record fields and variant cases. They are used to control how individual fields or cases are serialized and deserialized, as well as to attach additional metadata that can be interpreted by codecs or other tools.
+
+### transient
 
-During decoding, transient fields use their default values. Therefore, **transient fields must have default values** defined in the case class.
+The `transient` modifier marks a field as transient, meaning it will be excluded from serialization. This is useful for computed fields, caches, or sensitive data that shouldn't be persisted.
 
 ### rename
 
 The `rename` modifier changes the serialized name of a field or variant case. This is useful when the field name in your Scala code differs from the expected name in the serialized format.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Person(
@@ -82,15 +154,9 @@ object Person {
 }
 ```
 
-When encoding a `Person` to JSON:
-
-```json
-{"user_name": "Alice", "user_age": 30}
-```
-
 You can also use `rename` on variant cases to customize the discriminator value:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 sealed trait PaymentMethod
@@ -110,13 +176,15 @@ object PaymentMethod {
 
 The `alias` modifier provides an alternative name for a term during decoding. This is useful for supporting multiple names during schema evolution or data migration.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
-@Modifier.rename("NewName")
-@Modifier.alias("OldName")
-@Modifier.alias("LegacyName")
-case class MyClass(value: String)
+case class MyClass(
+  @Modifier.rename("NewName")
+  @Modifier.alias("OldName")
+  @Modifier.alias("LegacyName")
+  value: String
+)
 
 object MyClass {
   implicit val schema: Schema[MyClass] = Schema.derived
@@ -131,9 +199,9 @@ This pattern is particularly useful when migrating data formats without breaking
 
 ### config
 
-The `config` modifier attaches arbitrary key-value metadata to a term. The convention for keys is `<format>.<property>`, allowing format-specific configuration.
+The `config` modifier attaches arbitrary key-value metadata to a term (record fields or variant cases) or a type itself. The convention for keys is `<format>.<property>`, allowing format-specific configuration.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Event(
@@ -146,17 +214,17 @@ object Event {
 }
 ```
 
-The `config` modifier extends both `Term` and `Reflect`, making it usable on both fields and types.
+The `config` modifier extends both `Term` and `Reflect`, making it usable on both fields and types. We will discuss using `config` on types in the reflect modifiers section below.
 
 ## Reflect Modifiers
 
 Reflect modifiers annotate reflect values (types themselves). Currently, only `config` is a reflect modifier.
 
-### Using config on Types
+### config
 
 You can attach configuration to the type itself using the `Schema#modifier` method:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Person(name: String, age: Int)
@@ -170,7 +238,7 @@ object Person {
 
 Or add multiple modifiers at once:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Person(name: String, age: Int)
@@ -186,11 +254,25 @@ object Person {
 }
 ```
 
+Or annotate the case class directly:
+
+```scala
+import zio.blocks.schema._
+
+@Modifier.config("db.table-name", "person_table")
+@Modifier.config("schema.version", "v2")
+case class Person(name: String, age: Int)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+```
+
 ## Programmatic Modifier Access
 
 You can access modifiers programmatically through the `Reflect` structure:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Person(
@@ -218,7 +300,7 @@ reflect match {
 
 All modifier types have built-in `Schema` instances, enabling them to be serialized and deserialized:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 // Schema instances for individual modifiers
@@ -233,21 +315,19 @@ Schema[Modifier.Reflect]
 Schema[Modifier]
 ```
 
-This enables scenarios like:
-- Serializing schema metadata across process boundaries
-- Storing schema configuration in databases
-- Building schema registries with full modifier information
-
-## Format Support
+This means you can serialize modifiers as part of your schema metadata, allowing you to persist and exchange schema information with full modifier details.
 
-Different serialization formats interpret modifiers according to their semantics:
-
-| Modifier    | JSON | BSON | Avro | Protobuf |
-|-------------|------|------|------|----------|
-| `transient` | Field omitted | Field omitted | Field omitted | Field omitted |
-| `rename`    | Custom field name | Custom field name | Custom field name | Custom field name |
-| `alias`     | Accepts alternatives | Accepts alternatives | - | - |
-| `config`    | Format-specific | Format-specific | Format-specific | Format-specific |
+[//]: # (## Format Support)
+[//]: # ()
+[//]: # (Different serialization formats interpret modifiers according to their semantics.)
+[//]: # ()
+[//]: # (TODO: Add a table comparing how each modifier is supported across formats like JSON, BSON, Avro, Protobuf, etc. For example:)
+[//]: # (| Modifier    | JSON                 | BSON                 | Avro              | Protobuf          |)
+[//]: # (|-------------|----------------------|----------------------|-------------------|-------------------|)
+[//]: # (| `transient` | Field omitted        | Field omitted        | Field omitted     | Field omitted     |)
+[//]: # (| `rename`    | Custom field name    | Custom field name    | Custom field name | Custom field name |)
+[//]: # (| `alias`     | Accepts alternatives | Accepts alternatives | -                 | -                 |)
+[//]: # (| `config`    | Format-specific      | Format-specific      | Format-specific   | Format-specific   |)
 
 ## Best Practices
 
@@ -258,19 +338,3 @@ Different serialization formats interpret modifiers according to their semantics
 3. **Use `transient` sparingly**: Only mark fields as transient when they are truly derived or temporary. Remember that transient fields need default values.
 
 4. **Use namespaced keys for `config`**: Follow the `<format>.<property>` convention to avoid conflicts between different formats or tools.
-
-5. **Combine modifiers**: You can apply multiple modifiers to the same field:
-
-```scala mdoc:compile-only
-import zio.blocks.schema._
-
-case class Document(
-  @Modifier.rename("doc_id")
-  @Modifier.config("protobuf.field-id", "1")
-  id: String
-)
-
-object Document {
-  implicit val schema: Schema[Document] = Schema.derived
-}
-```