@zio.dev/zio-blocks 0.0.32 → 0.0.51

package/reference/{xml.md → schema/built-in-codecs/xml.md}

@@ -1,6 +1,6 @@
 ---
 id: xml
-title: "XML"
+title: "XML Codec Module"
 ---
 
 `Xml` is a **sealed trait representing XML nodes**. It provides a type-safe, immutable representation of all valid XML document structures including elements, text nodes, CDATA sections, comments, and processing instructions.
@@ -303,7 +303,7 @@ Use `WriterConfig` to control XML output formatting:
 import zio.blocks.schema.xml.WriterConfig
 
 // Compact output (default)
-val compact = WriterConfig.default
+val compact = WriterConfig
 // <Person><name>Alice</name></Person>
 
 // Pretty-printed with 2-space indentation
@@ -466,7 +466,7 @@ val xml = XmlReader.read("""
     </book>
   </books>
 </library>
-""").toOption.get
+""")
 
 // Navigate to child elements
 val books = xml.select.get("library").get("books")
@@ -478,9 +478,16 @@ val firstBook = books.get("book")(0)
 Extract text content from the first book:
 
 ```scala
-val title: Either[XmlError, String] = firstBook.get("title").text
-// title: Either[XmlError, String] = Left(
-//   zio.blocks.schema.xml.XmlError: Expected single value but got 0
+val title: Either[SchemaError, String] = firstBook.get("title").text
+// title: Either[SchemaError, String] = Left(
+//   SchemaError(
+//     List(
+//       Message(
+//         source = DynamicOptic(IndexedSeq()),
+//         details = "Expected single value but got 0"
+//       )
+//     )
+//   )
 // )
 ```
 
@@ -513,7 +520,8 @@ Filter selections by node type or custom predicates:
 ```scala
 import zio.blocks.schema.xml._
 
-val selection: XmlSelection = ???
+val xml = XmlReader.read("<root><item>text1</item><comment>note</comment></root>")
+val selection = xml.select.descendant("item")
 
 // Filter by type
 val elements = selection.elements
@@ -531,22 +539,23 @@ Execute a selection to extract values or convert to other formats:
 ```scala
 import zio.blocks.schema.xml._
 
-val selection: XmlSelection = ???
+val xml = XmlReader.read("<root><item>A</item><item>B</item></root>")
+val selection = xml.select.get("item")
 
 // Get single value (fails if not exactly one)
-val one: Either[XmlError, Xml] = selection.one
+val one: Either[SchemaError, Xml] = selection.one
 
 // Get any value (first of many)
-val any: Either[XmlError, Xml] = selection.any
+val any: Either[SchemaError, Xml] = selection.any
 
 // Get all values as a single XML element
-val all: Either[XmlError, Xml] = selection.all
+val all: Either[SchemaError, Xml] = selection.all
 
 // Convert to chunk
 val chunk = selection.toChunk
 
 // Extract text content
-val text: Either[XmlError, String] = selection.text
+val text: Either[SchemaError, String] = selection.text
 val allText: String = selection.textContent
 ```
 
@@ -557,8 +566,10 @@ Combine and transform selections using monadic operations:
 ```scala
 import zio.blocks.schema.xml._
 
-val selection1: XmlSelection = ???
-val selection2: XmlSelection = ???
+val xml1 = XmlReader.read("<root><item>X</item></root>")
+val xml2 = XmlReader.read("<root><item>Y</item></root>")
+val selection1 = xml1.select.get("item")
+val selection2 = xml2.select.get("item")
 
 // Map over selections
 val mapped = selection1.map(xml => xml)
@@ -631,11 +642,11 @@ Apply a patch to an XML document to produce a modified result:
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
 
-val xml: Xml = ???
+val xml = XmlReader.read("<person><name>Alice</name></person>")
 val patch = XmlPatch.setAttribute(p".person", "active", "true")
 
 // Apply the patch
-val result: Either[XmlError, Xml] = patch(xml)
+val result: Either[SchemaError, Xml] = patch(xml)
 ```
 
 ### Composing Patches
@@ -657,175 +668,6 @@ val patch2 = XmlPatch.add(
 val combined = patch1 ++ patch2
 ```
 
-## XmlEncoder and XmlDecoder
-
-For more fine-grained control over XML serialization, use the separate `XmlEncoder` and `XmlDecoder` traits:
-
-### XmlEncoder
-
-`XmlEncoder[A]` provides type-safe XML encoding:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-
-// Automatic derivation from Schema
-case class Person(name: String, age: Int)
-object Person {
-  implicit val schema: Schema[Person] = Schema.derived
-  implicit val encoder: XmlEncoder[Person] = XmlEncoder.fromSchema
-}
-
-val person = Person("Alice", 30)
-val xml: Xml = XmlEncoder[Person].encode(person)
-```
-
-#### Creating custom encoders
-
-Create custom encoders from functions or using contravariance:
-
-```scala
-import zio.blocks.schema.xml._
-
-// Create from a function
-val customEncoder: XmlEncoder[Int] = XmlEncoder.instance(n =>
-  Xml.Element("number", Xml.Text(n.toString))
-)
-
-// Map with contravariance - encode a wrapper type
-case class UserId(value: Int)
-
-val userIdEncoder: XmlEncoder[UserId] =
-  customEncoder.contramap[UserId](_.value)
-```
-
-#### Using implicit resolution
-
-Leverage implicit resolution for automatic encoder derivation:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-
-case class Product(id: String, price: Double)
-object Product {
-  implicit val schema: Schema[Product] = Schema.derived
-}
-
-// No explicit encoder needed - derives automatically
-def encodeProduct[A](value: A)(implicit encoder: XmlEncoder[A]): Xml =
-  encoder.encode(value)
-
-val result = encodeProduct(Product("item-1", 99.99))
-```
-
-### XmlDecoder
-
-`XmlDecoder[A]` provides type-safe XML decoding with error handling:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-
-// Automatic derivation from Schema
-case class Person(name: String, age: Int)
-object Person {
-  implicit val schema: Schema[Person] = Schema.derived
-  implicit val decoder: XmlDecoder[Person] = XmlDecoder.fromSchema
-}
-
-val xml = Xml.Element("Person",
-  Xml.Element("name", Xml.Text("Alice")),
-  Xml.Element("age", Xml.Text("30"))
-)
-```
-
-Decode the XML:
-
-```scala
-val result: Either[XmlError, Person] = XmlDecoder[Person].decode(xml)
-// result: Either[XmlError, Person] = Right(Person(name = "Alice", age = 30))
-```
-
-#### Creating custom decoders
-
-Create custom decoders from functions or using covariance:
-
-```scala
-import zio.blocks.schema.xml._
-import zio.blocks.chunk.Chunk
-
-// Create from a function
-val numberDecoder: XmlDecoder[Int] = XmlDecoder.instance { xml =>
-  xml match {
-    case Xml.Element(_, _, Chunk(Xml.Text(text), _*)) =>
-      text.toIntOption.toRight(XmlError("Invalid number"))
-    case _ => Left(XmlError("Expected number element"))
-  }
-}
-
-// Map for covariance - decode to a wrapper type
-case class UserId(value: Int)
-
-val userIdDecoder: XmlDecoder[UserId] =
-  numberDecoder.map(UserId(_))
-```
-
-#### Error handling with decoders
-
-Handle decoding errors gracefully with fallback strategies:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-
-case class Person(name: String, age: Int)
-object Person {
-  implicit val schema: Schema[Person] = Schema.derived
-}
-
-def decodeWithFallback[A](
-  xml: Xml,
-  fallback: A
-)(implicit decoder: XmlDecoder[A]): A = {
-  decoder.decode(xml).getOrElse(fallback)
-}
-
-val invalidXml = Xml.Element("Empty")
-val defaultPerson = Person("Unknown", 0)
-val result = decodeWithFallback(invalidXml, defaultPerson)
-// Person("Unknown", 0)
-```
-
-#### Combining encoders and decoders
-
-Round-trip values by encoding and decoding:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-import zio.blocks.schema.xml.syntax._
-
-case class Message(id: String, text: String)
-object Message {
-  implicit val schema: Schema[Message] = Schema.derived
-}
-
-// Round-trip: encode then decode
-val message = Message("msg-1", "Hello")
-val encoded: Xml = message.toXml
-```
-
-Decode the encoded value:
-
-```scala
-val result: Either[XmlError, Message] =
-  implicitly[XmlDecoder[Message]].decode(encoded)
-// result: Either[XmlError, Message] = Right(
-//   Message(id = "msg-1", text = "Hello")
-// )
-```
-
 ## Extension Syntax
 
 When a `Schema` is in scope, use convenient extension methods:
@@ -955,15 +797,15 @@ object Person {
   implicit val schema: Schema[Person] = Schema.derived
 }
 
-// Get the underlying binary codec
-val codec: XmlCodec[Person] = Schema[Person].derive(XmlCodecDeriver)
+// Get the underlying XML codec
+val codec: XmlCodec[Person] = Schema[Person].derive(XmlFormat)
 
 // Encode to Xml directly
 val person = Person("Alice", 30)
 val xml: Xml = codec.encodeValue(person)
 
 // Decode from Xml directly
-val decoded: Either[XmlError, Person] = codec.decodeValue(xml)
+val decoded: Person = codec.decodeValue(xml)
 ```
 
 **XmlCodec supports all Schema types:**
@@ -977,7 +819,7 @@ val decoded: Either[XmlError, Person] = codec.decodeValue(xml)
 
 ## Error Handling
 
-All decoding operations return `Either[SchemaError, A]` or `Either[XmlError, A]`. The `XmlError` type provides detailed error information:
+All decoding operations return `Either[SchemaError, A]` or `Either[SchemaError, A]`. The `SchemaError` type provides detailed error information:
 
 ```scala
 import zio.blocks.schema._
@@ -1002,12 +844,12 @@ result match {
 }
 ```
 
-`XmlError` provides detailed error information for debugging:
+`SchemaError` provides detailed error information for debugging:
 
 ```scala
 import zio.blocks.schema.xml._
 
-val error = XmlError("Parse failed")
+val error = SchemaError("Parse failed")
 
 // Error message
 val message: String = error.getMessage
@@ -1133,7 +975,7 @@ val xmlString = """
 </library>
 """
 
-val xml = XmlReader.read(xmlString).toOption.get
+val xml = XmlReader.read(xmlString)
 
 // Find all books
 val books = xml.select.get("library").get("books").get("book")