@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/{type-class-derivation.md → schema/type-class-derivation.md}

@@ -167,6 +167,68 @@ import zio.blocks.schema.json._
 val jsonCodec = Person.schema.derive(JsonFormat)
 ```
 
+## Customizing Derivation with Instance and Modifier Overrides
+
+By default, `Deriver` automatically derives codecs for all types. But sometimes you need to customize how specific types are encoded or decoded—for example, encoding `LocalDate` as `"dd/MM/yyyy"` instead of ISO format.
+
+ZIO Blocks provides three levels of customization, in progressive order:
+
+1. **Type-level override** (`Deriver.withInstance`) — Override the codec for ALL occurrences of a type. Configure once, use everywhere:
+
+```scala
+import java.time.LocalDate
+import java.time.format.DateTimeFormatter
+
+// Create a custom JsonCodec for LocalDate
+val customDateCodec: JsonCodec[LocalDate] = new JsonCodec[LocalDate] {
+  private val fmt = DateTimeFormatter.ofPattern("dd/MM/yyyy")
+  def decodeValue(in: JsonReader): LocalDate = LocalDate.parse(in.readString(), fmt)
+  def encodeValue(x: LocalDate, out: JsonWriter): Unit = out.writeVal(fmt.format(x))
+  // ... AST overrides ...
+}
+
+// Configure the deriver once
+val myDeriver = JsonCodecDeriver.withInstance[LocalDate](customDateCodec)
+
+// Use everywhere — all LocalDate fields use the custom codec
+val codec1 = Schema[Event].deriving(myDeriver).derive
+val codec2 = Schema[Meeting].deriving(myDeriver).derive
+```
+
+2. **Field-level override** (`Deriver.withInstance` with typeId + termName) — Override a specific field only:
+
+```scala
+// Only Event.date uses custom format; other LocalDate fields are unchanged
+val deriver = JsonCodecDeriver.withInstance[Event, LocalDate](
+  TypeId.of[Event], "date", customDateCodec
+)
+```
+
+3. **Modifier override** (`Deriver.withModifier`) — Rename fields, add aliases:
+
+```scala
+val deriver = JsonCodecDeriver.withModifier(
+  TypeId.of[Person], "firstName", Modifier.rename("first_name")
+)
+```
+
+### Chaining Overrides
+
+Overrides compose, allowing you to build complex derivers incrementally:
+
+```scala
+val myDeriver = JsonCodecDeriver
+  .withInstance[LocalDate](customDateCodec)
+  .withModifier(TypeId.of[Event], "name", Modifier.rename("title"))
+```
+
+### Important Notes
+
+- `withInstance` and `withModifier` return a NEW deriver (they are immutable).
+- When combined with `DerivationBuilder`, deriver-level instance overrides take precedence over builder-level instance overrides. Modifier override precedence is order-sensitive and should not be assumed to follow the same rule.
+- Unknown `termName` values are silently ignored.
+- The `B` type parameter in field-level `withInstance` is not statically checked against the actual field type.
+
 ## Example 1: Deriving a `Show` Type Class Instance
 
 Let's say we want to derive a `Show` type class instance for any type of type `A`:
@@ -1455,7 +1517,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@643bb7d2
+// random: Random = scala.util.Random@d903a4c
 
 Person.gen.generate(random)
 // res14: Person = Person(name = "p", age = -1360544799)

package/reference/smithy.md

@@ -0,0 +1,533 @@
+---
+id: smithy
+title: "Smithy"
+---
+
+`zio-blocks-smithy` is a **Smithy IDL parser and AST library** providing a complete representation of Smithy 2.0 API models. It enables parsing Smithy IDL text into rich data structures, querying shape definitions, and pretty-printing models back to valid IDL syntax—all without external dependencies.
+
+## Installation
+
+Add the library to your build configuration:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-smithy" % "0.0.51"
+```
+
+Supported Scala versions: 2.13.x and 3.x
+
+## Quick Start
+
+Parse Smithy IDL text into a model, query shapes, and serialize back:
+
+```scala
+import zio.blocks.smithy._
+
+val smithyText = """$version: "2"
+namespace com.example.api
+
+structure User {
+  @required
+  id: String
+  name: String
+}
+
+operation GetUser {
+  input: GetUserInput
+  output: User
+}
+
+structure GetUserInput {
+  @required
+  id: String
+}
+"""
+
+// Parse IDL text into a model
+val result = SmithyModel.parse(smithyText)
+
+// Access shapes and data
+result match {
+  case Right(model) =>
+    model.findShape("User").foreach { userDef =>
+      println(s"Found shape: ${userDef.name}")
+    }
+  case Left(error) =>
+    println(s"Parse error: ${error.message}")
+}
+
+// Serialize back to IDL
+result.foreach { model =>
+  val idlText = model.prettyPrint
+  println(idlText)
+}
+```
+
+## Core Types
+
+The library provides core types that work together to parse, query, and serialize Smithy models. The main types work together in a parsing → querying → serialization pipeline:
+
+```
+Smithy IDL Text
+      ↓
+SmithyModel.parse (public API)
+      ↓
+SmithyModel (contains shapes, metadata, traits)
+      ├─ shapes: List[ShapeDefinition]
+      │   └─ shape: Shape (sealed trait — central type)
+      │       ├─ StructureShape(members: List[MemberDefinition])
+      │       ├─ ListShape(member: MemberDefinition)
+      │       ├─ MapShape(key: MemberDefinition, value: MemberDefinition)
+      │       ├─ ServiceShape(operations, resources, errors)
+      │       ├─ OperationShape(input, output, errors)
+      │       ├─ UnionShape(members: List[MemberDefinition])
+      │       ├─ StringShape, BooleanShape, IntegerShape, etc.
+      │       └─ ... (and other shape subtypes)
+      ├─ MemberDefinition(name: String, target: ShapeId, traits: List[TraitApplication])
+      ├─ TraitApplication(id: ShapeId, value: Option[NodeValue])
+      ├─ ShapeId (namespace + name identifier)
+      └─ NodeValue (metadata values: String, Number, Boolean, Array, Object, Null)
+            ↓
+SmithyModel.prettyPrint (public API)
+      ↓
+Smithy IDL Text
+```
+
+The root container for a Smithy model. Contains version, namespace, shapes, metadata, and trait applications. The case class and companion object expose the following API:
+
+```scala
+case class SmithyModel(
+  version: String,           // Smithy version (e.g., "2")
+  namespace: String,
+  useStatements: List[ShapeId],
+  metadata: Map[String, NodeValue],
+  shapes: List[ShapeDefinition],
+  applyStatements: List[ApplyStatement] = Nil
+) {
+  def findShape(name: String): Option[ShapeDefinition]
+  def allShapeIds: List[ShapeId]
+  def prettyPrint: String
+  def prettyPrint(indent: Int): String
+}
+
+object SmithyModel {
+  def parse(input: String): Either[SmithyError, SmithyModel]
+}
+```
+
+## Parsing
+
+Parse Smithy IDL text into structured models using `SmithyModel.parse`, handle errors, and validate round-trips.
+
+### Basic Parsing
+
+Parse Smithy IDL text and handle the result:
+
+```scala
+import zio.blocks.smithy._
+
+val smithyText = """$version: "2"
+namespace com.example
+
+string Name
+"""
+
+SmithyModel.parse(smithyText) match {
+  case Right(model) =>
+    println(s"Parsed ${model.shapes.length} shapes")
+  case Left(error) =>
+    println(s"Error: ${error.message}")
+}
+```
+
+### Handling Parse Errors
+
+Access error details including line and column information when parsing fails. `SmithyError` provides detailed context to help locate and fix issues in your Smithy definitions:
+
+```scala
+import zio.blocks.smithy._
+
+val invalidSmithy = """$version: "2"
+namespace com.example
+
+structure User {
+  invalid syntax
+}
+"""
+
+SmithyModel.parse(invalidSmithy) match {
+  case Right(_) =>
+    println("Unexpected success")
+  case Left(error) =>
+    println(s"Error at line ${error.line}, column ${error.column}: ${error.message}")
+}
+```
+
+### Round-Trip Validation
+
+Verify a model parses correctly by round-tripping (parse → serialize → parse again):
+
+```scala
+import zio.blocks.smithy._
+
+val original = """$version: "2"
+namespace com.example
+
+string MyString
+"""
+
+val parsed = SmithyModel.parse(original)
+val reprinted = parsed.map(_.prettyPrint)
+val reparsed = reprinted.flatMap(SmithyModel.parse)
+
+println(reparsed.isRight)  // true if round-trip succeeds
+```
+
+## Querying & Traversing Shapes
+
+Once you have a parsed model, query shapes by name, pattern match on shape types, and traverse their members.
+
+### Finding Shapes
+
+Locate shapes by name or retrieve all shape identifiers:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel.parse("""$version: "2"
+namespace example
+
+structure User {
+  id: String
+  name: String
+}
+""").toOption.get
+
+// Find by name
+model.findShape("User").foreach { shapeDef =>
+  println(s"Found: ${shapeDef.name}")
+}
+
+// Get all shape IDs
+val allIds = model.allShapeIds
+println(s"Total shapes: ${allIds.length}")
+```
+
+### Pattern Matching on Shapes
+
+Determine shape type and access type-specific properties:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel.parse("""$version: "2"
+namespace example
+
+structure User { id: String }
+list UserIds { member: String }
+""").toOption.get
+
+model.findShape("User").foreach { shapeDef =>
+  shapeDef.shape match {
+    case struct: StructureShape =>
+      println(s"Structure with ${struct.members.length} members")
+    case list: ListShape =>
+      println(s"List of ${list.member.target}")
+    case _ =>
+      println("Other shape type")
+  }
+}
+```
+
+### Traversing Members
+
+Iterate over structure/union members and inspect their traits:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel.parse("""$version: "2"
+namespace example
+
+structure User {
+  @required
+  id: String
+  name: String
+}
+""").toOption.get
+
+model.findShape("User").foreach { shapeDef =>
+  shapeDef.shape match {
+    case struct: StructureShape =>
+      struct.members.foreach { member =>
+        val required = member.traits.exists(_.id.name == "required")
+        println(s"${member.name}: ${member.target} (required: $required)")
+      }
+    case _ => ()
+  }
+}
+```
+
+## Building Models Programmatically
+
+Construct Smithy models in code by creating shapes, adding traits, and assembling them into a complete model.
+
+### Creating Shapes
+
+Programmatically construct shapes and assemble them into a complete model:
+
+```scala
+import zio.blocks.smithy._
+
+val userStructure = StructureShape(
+  "User",
+  traits = Nil,
+  members = List(
+    MemberDefinition(
+      "id",
+      ShapeId("smithy.api", "String"),
+      traits = List(TraitApplication.required)
+    ),
+    MemberDefinition(
+      "name",
+      ShapeId("smithy.api", "String"),
+      traits = Nil
+    )
+  )
+)
+
+val model = SmithyModel(
+  version = "2",
+  namespace = "com.example",
+  useStatements = Nil,
+  metadata = Map.empty,
+  shapes = List(ShapeDefinition("User", userStructure))
+)
+```
+
+### Adding Traits
+
+Attach metadata traits to shapes during construction. `TraitApplication` provides companion object helper methods like `required`, `documentation`, and others for common traits:
+
+```scala
+import zio.blocks.smithy._
+
+val serviceShape = ServiceShape(
+  "UserService",
+  traits = List(
+    TraitApplication.documentation("User management API")
+  ),
+  version = Some("1.0"),
+  operations = List(
+    ShapeId("com.example", "GetUser"),
+    ShapeId("com.example", "CreateUser")
+  ),
+  resources = Nil,
+  errors = Nil
+)
+```
+
+## Serializing Models
+
+Convert models back to valid Smithy IDL text using `prettyPrint`, with options for custom formatting.
+
+### Basic Serialization
+
+Convert a model to valid Smithy IDL text:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel(
+  version = "2",
+  namespace = "com.example",
+  useStatements = Nil,
+  metadata = Map.empty,
+  shapes = List(
+    ShapeDefinition("Name", StringShape("Name"))
+  )
+)
+
+val idlText = model.prettyPrint
+println(idlText)
+```
+
+### Custom Indentation
+
+Control indentation width when serializing models:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel(
+  version = "2",
+  namespace = "com.example",
+  useStatements = Nil,
+  metadata = Map.empty,
+  shapes = List(
+    ShapeDefinition("Data", StructureShape(
+      "Data",
+      traits = Nil,
+      members = List(
+        MemberDefinition("field1", ShapeId("smithy.api", "String")),
+        MemberDefinition("field2", ShapeId("smithy.api", "String"))
+      )
+    ))
+  )
+)
+
+val compact = model.prettyPrint(indent = 2)
+val verbose = model.prettyPrint(indent = 8)
+```
+
+## Common Use-Cases
+
+See how to apply Smithy parsing and querying to real-world workflows: code generation, validation, and model transformation.
+
+### Use-Case 1: Code Generation
+
+Load a Smithy model and generate code for each operation:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel.parse("""$version: "2"
+namespace api
+
+service MyService {
+  operations: [GetUser, CreateUser]
+}
+
+@http(method: "GET", uri: "/users/{id}")
+operation GetUser {
+  input: GetUserInput
+  output: User
+}
+
+@http(method: "POST", uri: "/users")
+operation CreateUser {
+  input: CreateUserInput
+  output: User
+}
+
+structure User { id: String, name: String }
+structure GetUserInput { @required id: String }
+structure CreateUserInput { @required name: String }
+""").toOption.get
+
+// Generate code stubs for each operation by pattern matching:
+
+model.shapes.foreach { shapeDef =>
+  shapeDef.shape match {
+    case op: OperationShape =>
+      println(s"// Generate operation: ${op.name}")
+      op.input.foreach(in => println(s"//   input: ${in.name}"))
+      op.output.foreach(out => println(s"//   output: ${out.name}"))
+    case _ => ()
+  }
+}
+```
+
+### Use-Case 2: Validation & Analysis
+
+Find deprecated shapes and analyze trait coverage:
+
+```scala
+import zio.blocks.smithy._
+
+val model = SmithyModel.parse("""$version: "2"
+namespace example
+
+@deprecated
+structure LegacyUser { id: String }
+
+structure ModernUser {
+  @required
+  id: String
+  email: String
+}
+""").toOption.get
+
+// Find all deprecated shapes:
+
+val deprecated = model.shapes.filter { shapeDef =>
+  shapeDef.shape.traits.exists(_.id.name == "deprecated")
+}
+
+println(s"Deprecated shapes: ${deprecated.map(_.name)}")
+```
+
+### Use-Case 3: Model Transformation
+
+Parse, modify, and re-serialize a model with updated metadata:
+
+```scala
+import zio.blocks.smithy._
+
+val original = """$version: "2"
+namespace com.example
+
+string UserId
+"""
+
+val modified = SmithyModel.parse(original).map { model =>
+  // Add metadata to the model:
+
+  val newMetadata = model.metadata + ("version" -> NodeValue.String("1.0"))
+  model.copy(metadata = newMetadata)
+}
+
+modified.foreach { model =>
+  println(model.prettyPrint)
+}
+```
+
+## Running the Examples
+
+All code from this guide is available as runnable examples in the `smithy-examples` module. Examples demonstrate different aspects of the Smithy library.
+
+**1. Clone the repository and navigate to the project:**
+
+```bash
+git clone https://github.com/zio/zio-blocks.git
+cd zio-blocks
+```
+
+**2. Run individual examples with sbt:**
+
+### Step 1: Basic Parsing and Querying
+
+Parse Smithy IDL text, find shapes by name, and access their structure and metadata:
+
+```bash
+sbt "smithy-examples/runMain smithyexample.BasicParsingAndQuerying"
+```
+
+### Step 2: Building Models Programmatically
+
+Construct Smithy models in code by creating shapes, adding traits, and assembling them into a complete model:
+
+```bash
+sbt "smithy-examples/runMain smithyexample.BuildingModelsAndTraits"
+```
+
+### Step 3: Validation and Analysis
+
+Analyze Smithy models for completeness, find deprecated shapes, check for documentation, and validate API contracts:
+
+```bash
+sbt "smithy-examples/runMain smithyexample.ValidationAndAnalysis"
+```
+
+### Step 4: Complete Example — Book Store API
+
+A comprehensive end-to-end workflow showing a complete book store API model with parsing, entity analysis, error handling, code generation, and statistics:
+
+```bash
+sbt "smithy-examples/runMain smithyexample.BookStoreAPI"
+```
+
+**3. Or compile all examples at once:**
+
+```bash
+sbt "smithy-examples/compile"
+```

package/reference/sql/db-codec-deriver.md

@@ -0,0 +1,71 @@
+---
+id: db-codec-deriver
+title: "DbCodecDeriver"
+description: "Reference for DbCodecDeriver, the schema-driven derivation engine that converts a Schema[A] into a DbCodec[A] in the sql module."
+keywords:
+  - "DbCodecDeriver schema derivation"
+  - "DbCodec automatic derivation"
+  - "Deriver DbCodec"
+  - "SqlNameMapper column naming"
+  - "withColumnNameMapper"
+  - "deriveRecord deriveVariant"
+  - "JSONB fallback codec"
+---
+
+`DbCodecDeriver` is a schema-driven derivation engine that converts a `Schema[A]` into a `DbCodec[A]`. 
+
+The companion object `DbCodecDeriver` is itself an instance of the class constructed with the default `SqlNameMapper.SnakeCase`. `DbCodec.derived`, `DbCodec.builder`, `DbCodec.derivedWith`, and `Table.derived` all delegate to this deriver; application code rarely constructs or calls it directly.
+
+Key properties:
+- **Schema-driven** — derivation is entirely data-driven from the `Schema`'s `Reflect` tree; no separate macro or annotation processor is involved beyond `Schema.derived`.
+- **Configurable naming** — the `columnNameMapper: SqlNameMapper` constructor parameter controls how Scala field names become SQL column names; the default is `SnakeCase`.
+- **Annotation-aware** — `@Modifier.transient` fields are skipped; `@Modifier.rename` overrides the mapper for individual fields; `@Modifier.config("sql.inline","true")` flattens a nested record into the parent's column list.
+- **JSONB fallback** — non-inline nested records, sequences, maps, and dynamic values fall back to a single `TEXT` / `JSONB` column backed by `DbCodec.jsonb`.
+
+The structural shape of `DbCodecDeriver` is:
+
+```scala
+class DbCodecDeriver(columnNameMapper: SqlNameMapper = SqlNameMapper.SnakeCase)
+    extends Deriver[DbCodec]
+
+object DbCodecDeriver extends DbCodecDeriver(SqlNameMapper.SnakeCase) {
+  def withColumnNameMapper(mapper: SqlNameMapper): DbCodecDeriver
+}
+```
+
+## Usage
+
+The following example shows the three most common ways to reach `DbCodecDeriver`: through the `derives` clause on a case class, through `DbCodec.derived` (equivalent), and through `DbCodecDeriver.withColumnNameMapper` when a non-default naming strategy is needed.
+
+```scala
+import zio.blocks.sql.{DbCodec, DbCodecDeriver, SqlNameMapper}
+import zio.blocks.schema.Schema
+
+// 1. Derives clause — most concise
+case class User(userId: Int, fullName: String) derives DbCodec
+DbCodec[User].columns
+// res0: IndexedSeq[String] = Vector("user_id", "full_name")
+
+// 2. DbCodec.derived — equivalent, explicit
+case class Event(eventId: Long, eventType: String)
+object Event { implicit val schema: Schema[Event] = Schema.derived }
+val eventCodec = DbCodec.derived[Event]
+// eventCodec: DbCodec[Event] = zio.blocks.sql.DbCodecDeriver$$anon$20@66f22c33
+eventCodec.columns
+// res1: IndexedSeq[String] = Vector("event_id", "event_type")
+
+// 3. withColumnNameMapper — use Identity when your DB already uses camelCase
+case class Widget(widgetId: Int, widgetName: String)
+object Widget { implicit val schema: Schema[Widget] = Schema.derived }
+
+val identityDeriver = DbCodecDeriver.withColumnNameMapper(SqlNameMapper.Identity)
+// identityDeriver: DbCodecDeriver = zio.blocks.sql.DbCodecDeriver@33803e98
+val widgetCodec     = Widget.schema.deriving(identityDeriver).derive
+// widgetCodec: DbCodec[Widget] = zio.blocks.sql.DbCodecDeriver$$anon$20@35131fba
+widgetCodec.columns
+// res2: IndexedSeq[String] = Vector("widgetId", "widgetName")
+```
+
+## See Also
+
+For the naming strategy that `DbCodecDeriver` applies, see [SqlNameMapper](./sql-name-mapper.md). For the `DbCodec` type that derivation produces, see [DbCodec](./db-codec.md). For `Table.derived` and DDL generation, see [Table](./table.md).