@zio.dev/zio-blocks 0.0.24 → 0.0.25

package/guides/query-dsl-extending.md

@@ -52,7 +52,7 @@ Since `SchemaExpr` is a sealed trait, you cannot add new cases to it. Instead, w
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md) and [Part 2: SQL Generation](./query-dsl-sql.md). You should be comfortable building `SchemaExpr` values and translating them to SQL.
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 ```scala

package/guides/query-dsl-fluent-builder.md

@@ -57,7 +57,7 @@ In this guide, we solve both problems: bridge extensions eliminate `.toExpr`, an
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md), [Part 2: SQL Generation](./query-dsl-sql.md), and [Part 3: Extending the Expression Language](./query-dsl-extending.md).
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 ## Domain Setup

package/guides/query-dsl-reified-optics.md

@@ -43,7 +43,7 @@ In this guide, we'll solve this by using ZIO Blocks' `SchemaExpr` and reified op
 Add the ZIO Blocks Schema dependency:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 ```scala

package/guides/query-dsl-sql.md

@@ -43,7 +43,7 @@ Since `SchemaExpr` is a sealed trait, we can write a single interpreter that tra
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md). You should be comfortable building `SchemaExpr` values with optic operators (`===`, `>`, `&&`, etc.).
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 ```scala

package/index.md

@@ -81,14 +81,14 @@ val thriftCodec  = Schema[Person].derive(ThriftFormat)      // Thrift
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 
 // Optional format modules:
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.25"
 ```
 
 ### Example: Optics
@@ -143,7 +143,7 @@ Chunk is designed for:
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.25"
 ```
 
 ### Example
@@ -231,7 +231,7 @@ Scope.global.scoped { scope =>
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.25"
 ```
 
 ### Example: Basic Resource Management
@@ -334,7 +334,7 @@ Generating documentation, README files, or any Markdown content programmatically
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.25"
 ```
 
 ### Example
@@ -418,7 +418,7 @@ Compile-time type identity with rich metadata. TypeId captures comprehensive inf
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.25"
 ```
 
 ### Example
@@ -461,7 +461,7 @@ A type-indexed heterogeneous collection that stores values by their types with c
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.25"
 ```
 
 ### Example

package/package.json

@@ -2,7 +2,7 @@
   "name": "@zio.dev/zio-blocks",
   "description": "ZIO Blocks Documentation",
   "license": "Apache-2.0",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "repository": {
     "url": "https://github.com/zio/zio-blocks"
   }

package/reference/codec.md

@@ -48,23 +48,23 @@ val result: Either[SchemaError, Person] = Person.codec.decode(bytes)
 To include the base schema module with JSON support, add the following dependency to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 Additional format modules are separate artifacts:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.24"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.25"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.25"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.25"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/docs.md

@@ -10,7 +10,7 @@ Complete API reference for the zio-blocks-docs module - a zero-dependency GitHub
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.25"
 ```
 
 ## Core Types

package/reference/media-type.md

@@ -75,13 +75,13 @@ textAny.matches(html) // true
 Add the following to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.25"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.24"
+libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.25"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/schema-expr.md

@@ -70,13 +70,13 @@ val result: Either[OpticCheck, Seq[Boolean]] = combined.eval(alice)
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.25"
 ```
 
 For cross-platform (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.24"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.25"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/type-class-derivation.md

@@ -1451,7 +1451,7 @@ Now we can use the derived `Gen[Person]` instance to generate random `Person` va
 
 ```scala
 val random = new Random(42) // Seeded for reproducible output
-// random: Random = scala.util.Random@1247c2a2
+// random: Random = scala.util.Random@280d230c
 
 Person.gen.generate(random)
 // res14: Person = Person(name = "p", age = -1360544799)
@@ -1599,12 +1599,13 @@ val tc: TC[A] = schema.deriving(deriver)
   .derive           // finalize the derivation
 ```
 
-The `DerivationBuilder` offers two overloaded `instance` methods for providing custom type class instances:
+The `DerivationBuilder` offers three overloaded `instance` methods for providing custom type class instances:
 
 ```scala
 final case class DerivationBuilder[TC[_], A](...) {
   def instance[B](optic: Optic[A, B], instance: => TC[B]): DerivationBuilder[TC, A]
-  def instance[B](typeId: TypeId[B],  instance: => TC[B]): DerivationBuilder[TC, A]
+  def instance[B](typeId: TypeId[B], instance: => TC[B]): DerivationBuilder[TC, A]
+  def instance[P, B](typeId: TypeId[P], termName: String, instance: => TC[B]): DerivationBuilder[TC, A]
 }
 ```
 
@@ -1696,15 +1697,38 @@ personShow.show(Person("Alice", 30))
 // res32: String = "Person(name = \"Alice\", age = #30)"
 ```
 
+### Overriding by TypeId and Term Name
+
+The third overload takes a `TypeId[P]` identifying the **parent** record or variant and a `termName` string identifying a field or case within it. This provides medium precision between optic-based (exact path) and type-based (all occurrences) overrides, and is useful when you want to override a specific field across all locations where the parent type appears without having to enumerate each path with an optic:
+
+```scala
+val customAgeShow: Show[Int] = new Show[Int] {
+  def show(value: Int): String = s"age=$value"
+}
+
+val personShow: Show[Person] = Person.schema
+  .deriving(DeriveShow)
+  .instance(Person.schema.reflect.typeId, "age", customAgeShow)
+  .derive
+```
+
+The `typeId` refers to the parent record/variant type (here `Person`), not the field type. If no term with the given name exists in the parent type, the override is silently ignored.
+
+```scala
+personShow.show(Person("Alice", 30))
+// res33: String = "Person(name = \"Alice\", age = age=30)"
+```
+
 ### Resolution Order
 
 When the derivation engine encounters a schema node, it resolves the type class instance using the following priority order:
 
 1. **Optic-based override** (most precise): If an instance override was registered using an optic that matches the current path in the schema tree, that instance is used.
-2. **TypeId-based override** (more general): If no optic-based match is found, it checks for an instance override registered by type ID.
-3. **Automatic derivation** (default): If no override is found, the deriver's method (e.g., `derivePrimitive`, `deriveRecord`) is called to automatically derive the instance.
+2. **TypeId + term-name override** (medium precision): If no optic-based match is found, it checks for an override registered by parent type ID and term name.
+3. **TypeId-based override** (more general): If no term-name match is found, it checks for an instance override registered by type ID.
+4. **Automatic derivation** (default): If no override is found, the deriver's method (e.g., `derivePrimitive`, `deriveRecord`) is called to automatically derive the instance.
 
-This means you can set a global override by type and then selectively refine specific fields using optics:
+This means you can set a global override by type and then selectively refine specific fields using optics or term names:
 
 ```scala
 val companyShow: Show[Company] = Company.schema
@@ -1722,7 +1746,7 @@ In this example, all `String` fields use single quotes, except for the CEO's nam
 
 ```scala
 companyShow.show(Company(Person("Alice", 30), "tech"))
-// res33: String = "Company(ceo = Person(name = ALICE, age = 30), industry = 'tech')"
+// res34: String = "Company(ceo = Person(name = ALICE, age = 30), industry = 'tech')"
 ```
 
 ### Chaining Multiple Overrides
@@ -1743,7 +1767,7 @@ val personShow: Show[Person] = Person.schema
 
 ```scala
 personShow.show(Person("Alice", 30))
-// res34: String = "Person(name = <<Alice>>, age = age=30)"
+// res35: String = "Person(name = <<Alice>>, age = age=30)"
 ```
 
 ## Custom Modifiers
@@ -1756,12 +1780,13 @@ While modifiers can be attached to schemas directly using Scala annotations (e.g
 - You need different modifiers for different derivation contexts (e.g., one JSON codec with renamed fields, another without)
 - You want to keep the schema clean and push format-specific concerns into the derivation layer
 
-The `DerivationBuilder` offers two overloaded `modifier` methods:
+The `DerivationBuilder` offers three overloaded `modifier` methods:
 
 ```scala
 final case class DerivationBuilder[TC[_], A](...) {
-  def modifier[B](typeId: TypeId[B],  modifier: Modifier.Reflect): DerivationBuilder[TC, A]
-  def modifier[B](optic: Optic[A, B], modifier: Modifier)        : DerivationBuilder[TC, A]
+  def modifier[B](typeId: TypeId[B], modifier: Modifier.Reflect): DerivationBuilder[TC, A]
+  def modifier[B](optic: Optic[A, B], modifier: Modifier): DerivationBuilder[TC, A]
+  def modifier[B](typeId: TypeId[B], termName: String, modifier: Modifier.Term): DerivationBuilder[TC, A]
 }
 ```
 
@@ -1823,7 +1848,7 @@ val user = User(1L, "Alice", "alice@example.com", 95.5)
 //   internalScore = 95.5
 // )
 new String(jsonCodec.encode(user), "UTF-8")
-// res35: String = "{\"id\":1,\"full_name\":\"Alice\",\"email\":\"alice@example.com\"}"
+// res36: String = "{\"id\":1,\"full_name\":\"Alice\",\"email\":\"alice@example.com\"}"
 ```
 
 ### Adding Modifiers by TypeId
@@ -1838,6 +1863,18 @@ val jsonCodec: JsonBinaryCodec[User] = User.schema
   .derive
 ```
 
+### Adding Modifiers by TypeId and Term Name
+
+The `modifier` method with `TypeId` and `termName` allows you to add a `Modifier.Term` to a specific field or case identified by name inside a parent type identified by its `TypeId`. This is useful when you want to target a specific term without constructing an optic for it. The `typeId` refers to the parent record/variant type that owns the term. If no term with the given name exists in the parent type, the modifier is silently ignored:
+
+```scala
+val jsonCodec: JsonBinaryCodec[User] = User.schema
+  .deriving(JsonBinaryCodecDeriver)
+  .modifier(User.schema.reflect.typeId, "name", Modifier.rename("full_name"))
+  .modifier(User.schema.reflect.typeId, "internalScore", Modifier.transient())
+  .derive
+```
+
 ## Derivation Process In-Depth
 
 Until now, we learned how to implement the `Deriver` methods for different schema patterns. But we haven't yet discussed how the overall derivation process works. In this section, we will go through the main steps of derivation in detail.