@zio.dev/zio-blocks 0.0.33 → 0.0.55

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

@@ -57,12 +57,12 @@ 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.33"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.55"
 ```
 
 ## Domain Setup
 
-We carry forward the product catalog domain and the Part 3 independent `Expr` ADT. The key additions in Part 4 are bridge extension methods, schema-driven table names, and statement builder types. The `Expr` ADT used here is the same independent design from Part 3.
+We carry forward the product catalog domain and the Part 3 independent `Expr` ADT. The key additions in Part 4 are bridge extension methods, schema-driven table names, and statement builder types. As in Part 3, the public expression layer stays typed: built-in logic remains `SchemaExpr`, and the SQL builder only drops to the dynamic AST inside interpreter helpers.
 
 ```scala
 import zio.blocks.schema._
@@ -135,6 +135,7 @@ object OrderItem extends CompanionOptics[OrderItem] {
 sealed trait Expr[S, A]
 
 object Expr {
+  final case class Builtin[S, A](schemaExpr: SchemaExpr[S, A]) extends Expr[S, A]
   final case class Column[S, A](optic: Optic[S, A]) extends Expr[S, A]
   final case class Lit[S, A](value: A, schema: Schema[A]) extends Expr[S, A]
 
@@ -155,38 +156,7 @@ object Expr {
   def col[S, A](optic: Optic[S, A]): Expr[S, A] = Column(optic)
   def lit[S, A](value: A)(implicit schema: Schema[A]): Expr[S, A] = Lit(value, schema)
 
-  def fromSchemaExpr[S, A](se: SchemaExpr[S, A]): Expr[S, A] = {
-    val result = se match {
-      case SchemaExpr.Optic(optic)      => Column(optic)
-      case l: SchemaExpr.Literal[_, _]  => Lit(l.value, l.schema)
-      case SchemaExpr.Relational(l, r, op) =>
-        val relOp = op match {
-          case SchemaExpr.RelationalOperator.Equal              => RelOp.Equal
-          case SchemaExpr.RelationalOperator.NotEqual           => RelOp.NotEqual
-          case SchemaExpr.RelationalOperator.LessThan           => RelOp.LessThan
-          case SchemaExpr.RelationalOperator.LessThanOrEqual    => RelOp.LessThanOrEqual
-          case SchemaExpr.RelationalOperator.GreaterThan        => RelOp.GreaterThan
-          case SchemaExpr.RelationalOperator.GreaterThanOrEqual => RelOp.GreaterThanOrEqual
-        }
-        Relational(fromSchemaExpr(l), fromSchemaExpr(r), relOp)
-      case SchemaExpr.Logical(l, r, op) => op match {
-        case SchemaExpr.LogicalOperator.And => And(fromSchemaExpr(l), fromSchemaExpr(r))
-        case SchemaExpr.LogicalOperator.Or  => Or(fromSchemaExpr(l), fromSchemaExpr(r))
-      }
-      case SchemaExpr.Not(inner) => Not(fromSchemaExpr(inner))
-      case SchemaExpr.Arithmetic(l, r, op, _) =>
-        val arithOp = op match {
-          case SchemaExpr.ArithmeticOperator.Add      => ArithOp.Add
-          case SchemaExpr.ArithmeticOperator.Subtract => ArithOp.Subtract
-          case SchemaExpr.ArithmeticOperator.Multiply => ArithOp.Multiply
-        }
-        Arithmetic(fromSchemaExpr(l), fromSchemaExpr(r), arithOp)
-      case SchemaExpr.StringConcat(l, r)              => StringConcat(fromSchemaExpr(l), fromSchemaExpr(r))
-      case SchemaExpr.StringRegexMatch(regex, string) => StringRegexMatch(fromSchemaExpr(regex), fromSchemaExpr(string))
-      case SchemaExpr.StringLength(string)            => StringLength(fromSchemaExpr(string))
-    }
-    result.asInstanceOf[Expr[S, A]]
-  }
+  def fromSchemaExpr[S, A](se: SchemaExpr[S, A]): Expr[S, A] = Builtin(se)
 }
 
 sealed trait RelOp
@@ -211,6 +181,9 @@ object ArithOp {
 def columnName(optic: zio.blocks.schema.Optic[_, _]): String =
   optic.toDynamic.nodes.collect { case f: DynamicOptic.Node.Field => f.name }.mkString("_")
 
+def columnName(path: DynamicOptic): String =
+  path.nodes.collect { case f: DynamicOptic.Node.Field => f.name }.mkString("_")
+
 def sqlLiteral[A](value: A, schema: Schema[A]): String = {
   val dv = schema.toDynamicValue(value)
   dv match {
@@ -223,6 +196,22 @@ def sqlLiteral[A](value: A, schema: Schema[A]): String = {
   }
 }
 
+def sqlLiteralDV(dv: DynamicValue): String = dv match {
+  case DynamicValue.Primitive(pv) =>
+    pv match {
+      case PrimitiveValue.String(s)  => s"'${s.replace("'", "''")}'"
+      case PrimitiveValue.Boolean(b) => if (b) "TRUE" else "FALSE"
+      case PrimitiveValue.Int(n)     => n.toString
+      case PrimitiveValue.Long(n)    => n.toString
+      case PrimitiveValue.Double(n)  => n.toString
+      case PrimitiveValue.Float(n)   => n.toString
+      case PrimitiveValue.Short(n)   => n.toString
+      case PrimitiveValue.Byte(n)    => n.toString
+      case other                     => other.toString
+    }
+  case other => other.toString
+}
+
 // --- Optic extension methods ---
 
 implicit final class OpticExprOps[S, A](private val optic: Optic[S, A]) {
@@ -255,8 +244,9 @@ implicit final class SchemaExprBooleanBridge[S](private val self: SchemaExpr[S,
 // --- Single unified SQL interpreter ---
 
 def exprToSql[S, A](expr: Expr[S, A]): String = expr match {
-  case Expr.Column(optic)      => columnName(optic)
-  case Expr.Lit(value, schema) => sqlLiteral(value, schema)
+  case Expr.Builtin(schemaExpr) => schemaExprToSql(schemaExpr)
+  case Expr.Column(optic)       => columnName(optic)
+  case Expr.Lit(value, schema)  => sqlLiteral(value, schema)
   case Expr.Relational(left, right, op) =>
     val sqlOp = op match {
       case RelOp.Equal              => "="
@@ -287,6 +277,46 @@ def exprToSql[S, A](expr: Expr[S, A]): String = expr match {
   case Expr.IsNull(e)        => s"${exprToSql(e)} IS NULL"
   case Expr.Like(e, pattern) => s"${exprToSql(e)} LIKE '${pattern.replace("'", "''")}'"
 }
+
+def schemaExprToSql[S, A](expr: SchemaExpr[S, A]): String =
+  toSqlDynamic(expr.dynamic)
+
+def toSqlDynamic(expr: DynamicSchemaExpr): String = expr match {
+  case DynamicSchemaExpr.Select(path)   => columnName(path)
+  case DynamicSchemaExpr.Literal(value, _) => sqlLiteralDV(value)
+  case DynamicSchemaExpr.Relational(left, right, op) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.RelationalOperator.Equal              => "="
+      case DynamicSchemaExpr.RelationalOperator.NotEqual           => "<>"
+      case DynamicSchemaExpr.RelationalOperator.LessThan           => "<"
+      case DynamicSchemaExpr.RelationalOperator.LessThanOrEqual    => "<="
+      case DynamicSchemaExpr.RelationalOperator.GreaterThan        => ">"
+      case DynamicSchemaExpr.RelationalOperator.GreaterThanOrEqual => ">="
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Logical(left, right, op) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.LogicalOperator.And => "AND"
+      case DynamicSchemaExpr.LogicalOperator.Or  => "OR"
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Not(inner) =>
+    s"NOT (${toSqlDynamic(inner)})"
+  case DynamicSchemaExpr.Arithmetic(left, right, op, _) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.ArithmeticOperator.Add      => "+"
+      case DynamicSchemaExpr.ArithmeticOperator.Subtract => "-"
+      case DynamicSchemaExpr.ArithmeticOperator.Multiply => "*"
+      case _                                             => "?"
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.StringConcat(left, right) =>
+    s"CONCAT(${toSqlDynamic(left)}, ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.StringRegexMatch(regex, string) =>
+    s"(${toSqlDynamic(string)} LIKE ${toSqlDynamic(regex)})"
+  case DynamicSchemaExpr.StringLength(string) =>
+    s"LENGTH(${toSqlDynamic(string)})"
+}
 ```
 
 ## Seamless Condition Composition
@@ -380,7 +410,7 @@ exprToSql(condition)
 // res0: String = "((((price BETWEEN 10.0 AND 500.0) AND (category = 'Electronics')) AND (rating >= 4)) AND name LIKE 'L%')"
 ```
 
-The first two `&&` calls stay in `SchemaExpr` land (direct method). The third `&&` encounters `between` (returns `Expr`), triggering the bridge. From that point on, everything is `Expr`.
+The first `&&` already involves `between`, so the bridge activates as soon as an `Expr` enters the chain. From that point on, the whole condition is represented as `Expr`.
 
 ## Schema-Driven Table Names
 
@@ -496,51 +526,51 @@ val basicSelect = select(Product.table)
 //   table = Table("products"),
 //   columnList = List("name", "price"),
 //   whereExpr = Some(
-//     Relational(
-//       left = Column(
-//         LensImpl(
-//           sources = Array(
-//             Record(
-//               fields = Vector(
-//                 Term(
-//                   name = "name",
-//                   value = Primitive(
-//                     primitiveType = String(None),
-//                     typeId = String,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
-//                     storedDefaultValue = None,
-//                     storedExamples = List()
-//                   ),
+//     Builtin(
+//       SchemaExpr(
+//         dynamic = Relational(
+//           left = Select(DynamicOptic(ArraySeq(Field("inStock")))),
+//           right = Literal(
+//             value = Primitive(Boolean(true)),
+//             schema = Schema(
+//               Primitive(
+//                 primitiveType = Boolean(None),
+//                 typeId = Boolean,
+//                 primitiveBinding = Primitive(),
+//                 doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//                 modifiers = List(),
+//                 storedDefaultValue = None,
+//                 storedExamples = List()
+//               )
+//             )
+//           ),
+//           operator = Equal
+//         ),
+//         inputSchema = Schema(
+//           Record(
+//             fields = Vector(
+//               Term(
+//                 name = "name",
+//                 value = Primitive(
+//                   primitiveType = String(None),
+//                   typeId = String,
+//                   primitiveBinding = Primitive(),
 //                   doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                   modifiers = List()
+//                   modifiers = List(),
+//                   storedDefaultValue = None,
+//                   storedExamples = List()
 //                 ),
-//                 Term(
-//                   name = "price",
-//                   value = Primitive(
-//                     primitiveType = Double(None),
-//                     typeId = Double,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
-//                     storedDefaultValue = None,
-//                     storedExamples = List()
-//                   ),
+//                 doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//                 modifiers = List()
+//               ),
+//               Term(
+//                 name = "price",
+//                 value = Primitive(
+//                   primitiveType = Double(None),
+//                   typeId = Double,
+//                   primitiveBinding = Primitive(),
 //                   doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                   modifiers = List()
-//                 ),
-//                 Term(
-//                   name = "category",
-//                   value = Primitive(
-//                     primitiveType = String(None),
-//                     typeId = String,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
-//                     storedDefaultValue = None,
-//                     storedExamples = List()
-//                   ),
+//                   modifiers = List(),
 // ...
 
 renderSelect(basicSelect)
@@ -723,48 +753,48 @@ val multiUpdate =
 //     Assignment(column = "inStock", value = "FALSE")
 //   ),
 //   whereExpr = Some(
-//     Relational(
-//       left = Column(
-//         LensImpl(
-//           sources = Array(
-//             Record(
-//               fields = Vector(
-//                 Term(
-//                   name = "name",
-//                   value = Primitive(
-//                     primitiveType = String(None),
-//                     typeId = String,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
-//                     storedDefaultValue = None,
-//                     storedExamples = List()
-//                   ),
-//                   doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                   modifiers = List()
-//                 ),
-//                 Term(
-//                   name = "price",
-//                   value = Primitive(
-//                     primitiveType = Double(None),
-//                     typeId = Double,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
-//                     storedDefaultValue = None,
-//                     storedExamples = List()
-//                   ),
+//     Builtin(
+//       SchemaExpr(
+//         dynamic = Relational(
+//           left = Select(DynamicOptic(ArraySeq(Field("category")))),
+//           right = Literal(
+//             value = Primitive(String("Clearance")),
+//             schema = Schema(
+//               Primitive(
+//                 primitiveType = String(None),
+//                 typeId = String,
+//                 primitiveBinding = Primitive(),
+//                 doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//                 modifiers = List(),
+//                 storedDefaultValue = None,
+//                 storedExamples = List()
+//               )
+//             )
+//           ),
+//           operator = Equal
+//         ),
+//         inputSchema = Schema(
+//           Record(
+//             fields = Vector(
+//               Term(
+//                 name = "name",
+//                 value = Primitive(
+//                   primitiveType = String(None),
+//                   typeId = String,
+//                   primitiveBinding = Primitive(),
 //                   doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                   modifiers = List()
+//                   modifiers = List(),
+//                   storedDefaultValue = None,
+//                   storedExamples = List()
 //                 ),
-//                 Term(
-//                   name = "category",
-//                   value = Primitive(
-//                     primitiveType = String(None),
-//                     typeId = String,
-//                     primitiveBinding = Primitive(),
-//                     doc = Doc(blocks = IndexedSeq(), metadata = Map()),
-//                     modifiers = List(),
+//                 doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//                 modifiers = List()
+//               ),
+//               Term(
+//                 name = "price",
+//                 value = Primitive(
+//                   primitiveType = Double(None),
+//                   typeId = Double,
 // ...
 
 renderUpdate(multiUpdate)
@@ -901,7 +931,7 @@ For batch inserts, create one `InsertStmt` per row and render each separately. T
 
 ## Putting It Together
 
-Here is a complete example combining schema-driven table names, bridge extensions, all four statement builders, and the renderers. The `Expr` ADT, extension methods, SQL rendering, and builder types are defined in `Common.scala` and `package.scala` — the usage code stays focused on building queries:
+Here is a complete example combining schema-driven table names, bridge extensions, all four statement builders, and the renderers. The `Expr` ADT, extension methods, SQL rendering, and builder types are defined in `Common.scala` and `package.scala` — the usage code stays focused on building queries with typed optics and `SchemaExpr`, not on manipulating `Dynamic*` nodes directly:
 
 ```scala
 import zio.blocks.schema._
@@ -972,6 +1002,7 @@ object OrderItem extends CompanionOptics[OrderItem] {
 sealed trait Expr[S, A]
 
 object Expr {
+  final case class Builtin[S, A](schemaExpr: SchemaExpr[S, A]) extends Expr[S, A]
   final case class Column[S, A](optic: Optic[S, A]) extends Expr[S, A]
   final case class Lit[S, A](value: A, schema: Schema[A]) extends Expr[S, A]
 
@@ -992,38 +1023,7 @@ object Expr {
   def col[S, A](optic: Optic[S, A]): Expr[S, A] = Column(optic)
   def lit[S, A](value: A)(implicit schema: Schema[A]): Expr[S, A] = Lit(value, schema)
 
-  def fromSchemaExpr[S, A](se: SchemaExpr[S, A]): Expr[S, A] = {
-    val result = se match {
-      case SchemaExpr.Optic(optic)      => Column(optic)
-      case l: SchemaExpr.Literal[_, _]  => Lit(l.value, l.schema)
-      case SchemaExpr.Relational(l, r, op) =>
-        val relOp = op match {
-          case SchemaExpr.RelationalOperator.Equal              => RelOp.Equal
-          case SchemaExpr.RelationalOperator.NotEqual           => RelOp.NotEqual
-          case SchemaExpr.RelationalOperator.LessThan           => RelOp.LessThan
-          case SchemaExpr.RelationalOperator.LessThanOrEqual    => RelOp.LessThanOrEqual
-          case SchemaExpr.RelationalOperator.GreaterThan        => RelOp.GreaterThan
-          case SchemaExpr.RelationalOperator.GreaterThanOrEqual => RelOp.GreaterThanOrEqual
-        }
-        Relational(fromSchemaExpr(l), fromSchemaExpr(r), relOp)
-      case SchemaExpr.Logical(l, r, op) => op match {
-        case SchemaExpr.LogicalOperator.And => And(fromSchemaExpr(l), fromSchemaExpr(r))
-        case SchemaExpr.LogicalOperator.Or  => Or(fromSchemaExpr(l), fromSchemaExpr(r))
-      }
-      case SchemaExpr.Not(inner) => Not(fromSchemaExpr(inner))
-      case SchemaExpr.Arithmetic(l, r, op, _) =>
-        val arithOp = op match {
-          case SchemaExpr.ArithmeticOperator.Add      => ArithOp.Add
-          case SchemaExpr.ArithmeticOperator.Subtract => ArithOp.Subtract
-          case SchemaExpr.ArithmeticOperator.Multiply => ArithOp.Multiply
-        }
-        Arithmetic(fromSchemaExpr(l), fromSchemaExpr(r), arithOp)
-      case SchemaExpr.StringConcat(l, r)              => StringConcat(fromSchemaExpr(l), fromSchemaExpr(r))
-      case SchemaExpr.StringRegexMatch(regex, string) => StringRegexMatch(fromSchemaExpr(regex), fromSchemaExpr(string))
-      case SchemaExpr.StringLength(string)            => StringLength(fromSchemaExpr(string))
-    }
-    result.asInstanceOf[Expr[S, A]]
-  }
+  def fromSchemaExpr[S, A](se: SchemaExpr[S, A]): Expr[S, A] = Builtin(se)
 }
 
 sealed trait RelOp
@@ -1075,6 +1075,9 @@ implicit final class SchemaExprBooleanBridge[S](private val self: SchemaExpr[S,
 def columnName(optic: zio.blocks.schema.Optic[_, _]): String =
   optic.toDynamic.nodes.collect { case f: DynamicOptic.Node.Field => f.name }.mkString("_")
 
+def columnName(path: DynamicOptic): String =
+  path.nodes.collect { case f: DynamicOptic.Node.Field => f.name }.mkString("_")
+
 def sqlLiteral[A](value: A, schema: Schema[A]): String = {
   val dv = schema.toDynamicValue(value)
   dv match {
@@ -1087,9 +1090,26 @@ def sqlLiteral[A](value: A, schema: Schema[A]): String = {
   }
 }
 
+def sqlLiteralDV(dv: DynamicValue): String = dv match {
+  case DynamicValue.Primitive(pv) =>
+    pv match {
+      case PrimitiveValue.String(s)  => s"'${s.replace("'", "''")}'"
+      case PrimitiveValue.Boolean(b) => if (b) "TRUE" else "FALSE"
+      case PrimitiveValue.Int(n)     => n.toString
+      case PrimitiveValue.Long(n)    => n.toString
+      case PrimitiveValue.Double(n)  => n.toString
+      case PrimitiveValue.Float(n)   => n.toString
+      case PrimitiveValue.Short(n)   => n.toString
+      case PrimitiveValue.Byte(n)    => n.toString
+      case other                     => other.toString
+    }
+  case other => other.toString
+}
+
 def exprToSql[S, A](expr: Expr[S, A]): String = expr match {
-  case Expr.Column(optic)      => columnName(optic)
-  case Expr.Lit(value, schema) => sqlLiteral(value, schema)
+  case Expr.Builtin(schemaExpr) => schemaExprToSql(schemaExpr)
+  case Expr.Column(optic)       => columnName(optic)
+  case Expr.Lit(value, schema)  => sqlLiteral(value, schema)
   case Expr.Relational(left, right, op) =>
     val sqlOp = op match {
       case RelOp.Equal              => "="
@@ -1121,6 +1141,46 @@ def exprToSql[S, A](expr: Expr[S, A]): String = expr match {
   case Expr.Like(e, pattern) => s"${exprToSql(e)} LIKE '${pattern.replace("'", "''")}'"
 }
 
+def schemaExprToSql[S, A](expr: SchemaExpr[S, A]): String =
+  toSqlDynamic(expr.dynamic)
+
+def toSqlDynamic(expr: DynamicSchemaExpr): String = expr match {
+  case DynamicSchemaExpr.Select(path)   => columnName(path)
+  case DynamicSchemaExpr.Literal(value, _) => sqlLiteralDV(value)
+  case DynamicSchemaExpr.Relational(left, right, op) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.RelationalOperator.Equal              => "="
+      case DynamicSchemaExpr.RelationalOperator.NotEqual           => "<>"
+      case DynamicSchemaExpr.RelationalOperator.LessThan           => "<"
+      case DynamicSchemaExpr.RelationalOperator.LessThanOrEqual    => "<="
+      case DynamicSchemaExpr.RelationalOperator.GreaterThan        => ">"
+      case DynamicSchemaExpr.RelationalOperator.GreaterThanOrEqual => ">="
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Logical(left, right, op) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.LogicalOperator.And => "AND"
+      case DynamicSchemaExpr.LogicalOperator.Or  => "OR"
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Not(inner) =>
+    s"NOT (${toSqlDynamic(inner)})"
+  case DynamicSchemaExpr.Arithmetic(left, right, op, _) =>
+    val sqlOp = op match {
+      case DynamicSchemaExpr.ArithmeticOperator.Add      => "+"
+      case DynamicSchemaExpr.ArithmeticOperator.Subtract => "-"
+      case DynamicSchemaExpr.ArithmeticOperator.Multiply => "*"
+      case _                                             => "?"
+    }
+    s"(${toSqlDynamic(left)} $sqlOp ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.StringConcat(left, right) =>
+    s"CONCAT(${toSqlDynamic(left)}, ${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.StringRegexMatch(regex, string) =>
+    s"(${toSqlDynamic(string)} LIKE ${toSqlDynamic(regex)})"
+  case DynamicSchemaExpr.StringLength(string) =>
+    s"LENGTH(${toSqlDynamic(string)})"
+}
+
 // --- Statement builders ---
 
 sealed trait SortOrder
@@ -1231,7 +1291,7 @@ val q = select(Product.table)
   .where(
     Product.category.in("Electronics", "Books") &&
     Product.price.between(10.0, 500.0) &&
-    (Product.rating >= 4).toExpr
+    (Product.rating >= 4)
   )
   .orderBy(Product.price, SortOrder.Desc)
   .limit(20)
@@ -1281,7 +1341,7 @@ println(renderSelect(orderQuery))
 - **[Part 1: Expressions](./query-dsl-reified-optics.md)** — Building query expressions with reified optics
 - **[Part 2: SQL Generation](./query-dsl-sql.md)** — Translating built-in expressions to SQL
 - **[Part 3: Extending the Expression Language](./query-dsl-extending.md)** — Adding custom operators beyond SchemaExpr
-- **[SchemaExpr Reference](../reference/schema-expr.md)** — Full API coverage of expression types
-- **[Optics Reference](../reference/optics.md)** — Lens, Prism, Optional, and Traversal
+- **[SchemaExpr Reference](../reference/schema/schema-expr.md)** — Full API coverage of expression types
+- **[Optics Reference](../reference/schema/optics.md)** — Lens, Prism, Optional, and Traversal
 
 The builder pattern shown here extends naturally to JOIN clauses (using lenses from multiple table types), subqueries (nesting `SelectStmt` in WHERE conditions), and parameterized queries (collecting `?` placeholders and parameter values during rendering). Each of these builds on the same foundation: optics for column names, `Expr` for conditions, and immutable builders for statement structure.

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

@@ -43,14 +43,14 @@ 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.33"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.55"
 ```
 
 ```scala
 import zio.blocks.schema._
 ```
 
-This guide assumes familiarity with ZIO Blocks schemas and basic optics. See the [Schema](../reference/schema.md) and [Optics](../reference/optics.md) reference pages for background.
+This guide assumes familiarity with ZIO Blocks schemas and basic optics. See the [Schema](../reference/schema/schema.md) and [Optics](../reference/schema/optics.md) reference pages for background.
 
 ## Defining Your Domain
 
@@ -233,9 +233,9 @@ val nameLength: SchemaExpr[Product, Int] =
 
 ```scala
 startsWithL.eval(laptop)
-// res12: Either[OpticCheck, Seq[Boolean]] = Right(IndexedSeq(true))
+// res12: Either[OpticCheck, Seq[Boolean]] = Right(List(true))
 startsWithL.eval(pen)
-// res13: Either[OpticCheck, Seq[Boolean]] = Right(IndexedSeq(false))
+// res13: Either[OpticCheck, Seq[Boolean]] = Right(List(false))
 
 labeledName.eval(laptop)
 // res14: Either[OpticCheck, Seq[String]] = Right(IndexedSeq("Laptop [SALE]"))
@@ -346,7 +346,9 @@ val hasExpensiveItem: SchemaExpr[Order, Boolean] =
 
 ```scala
 hasExpensiveItem.eval(order)
-// res21: Either[OpticCheck, Seq[Boolean]] = Right(List(false, true, false))
+// res21: Either[OpticCheck, Seq[Boolean]] = Right(
+//   IndexedSeq(false, true, false)
+// )
 ```
 
 :::tip
@@ -486,9 +488,9 @@ catalog.foreach { p =>
 - **[Part 2: SQL Generation](./query-dsl-sql.md)** -- Translating query expressions to SQL
 - **[Part 3: Extending the Expression Language](./query-dsl-extending.md)** -- Adding custom operators (IN, BETWEEN, aggregates) beyond SchemaExpr
 - **[Part 4: A Fluent SQL Builder](./query-dsl-fluent-builder.md)** -- Type-safe SELECT, UPDATE, INSERT, DELETE with seamless condition mixing
-- **[Optics Reference](../reference/optics.md)** -- Full API coverage of Lens, Prism, Optional, and Traversal
-- **[DynamicOptic Reference](../reference/dynamic-optic.md)** -- Runtime optic paths for programmatic query construction
-- **[Schema Reference](../reference/schema.md)** -- Schema derivation and type-level metadata
-- **[Path Interpolator](../path-interpolator.md)** -- String-based path construction with `p"..."` syntax
+- **[Optics Reference](../reference/schema/optics.md)** -- Full API coverage of Lens, Prism, Optional, and Traversal
+- **[DynamicOptic Reference](../reference/schema/dynamic-optic.md)** -- Runtime optic paths for programmatic query construction
+- **[Schema Reference](../reference/schema/schema.md)** -- Schema derivation and type-level metadata
+- **[Path Interpolator](../reference/schema/path-interpolator.md)** -- String-based path construction with `p"..."` syntax
 
-The `SchemaExpr` expression tree is a sealed trait, making it straightforward to write interpreters that translate queries to SQL, MongoDB filters, Elasticsearch queries, or any other target language. Because each optic carries its `DynamicOptic` path (via `toDynamic`), you can extract field names and paths programmatically for these translations.
+`SchemaExpr` is a typed wrapper around a serializable `DynamicSchemaExpr` tree, making it straightforward to write interpreters that translate queries to SQL, MongoDB filters, Elasticsearch queries, or any other target language. Because each optic carries its `DynamicOptic` path (via `toDynamic`), you can extract field names and paths programmatically for these translations.