@zio.dev/zio-blocks 0.0.21 → 0.0.22

package/index.md

@@ -80,14 +80,14 @@ val thriftCodec  = Schema[Person].derive(ThriftFormat)      // Thrift
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.22"
 
 // Optional format modules:
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.21"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.21"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.21"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.21"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.22"
 ```
 
 ### Example: Optics
@@ -142,7 +142,7 @@ Chunk is designed for:
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.22"
 ```
 
 ### Example
@@ -173,7 +173,7 @@ val head: Int = nonEmpty.head  // Always safe, no Option needed
 
 ## Scope
 
-Compile-time verified resource safety for synchronous Scala code. Scope prevents resource leaks at compile time by tagging values with an unnameable type-level identity—values allocated in a scope can only be used within that scope, and child scope values cannot escape to parent scopes.
+Compile-time verified resource safety for synchronous Scala code. Scope prevents resource leaks at compile time by tagging values with an unnameable type-level identity—values allocated in a scope can only be used within that scope. Child scope values cannot escape to parent scopes, enforced by both the abstract scope-tagged type and the `Unscoped` constraint on `scoped`.
 
 ### The Problem
 
@@ -204,11 +204,13 @@ Scope makes resource leaks a **compile error**, not a runtime bug:
 import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
-  val db: Database @@ scope.Tag = scope.allocate(Resource(openDatabase()))
+  import scope._
+
+  val db: $[Database] = allocate(Resource(openDatabase()))
 
   // Methods are hidden - can't call db.query() directly
-  // Must use scope $ to access:
-  val result = (scope $ db)(_.query("SELECT 1"))
+  // Must use scope.use to access:
+  val result = scope.use(db)(_.query("SELECT 1"))
 
   // Trying to return `db` would be a compile error!
   result  // Only pure data escapes
@@ -218,16 +220,17 @@ Scope.global.scoped { scope =>
 
 ### Key Features
 
-- **Compile-Time Leak Prevention**: Values tagged with `A @@ S` can only be used with proof of scope access. Returning a scoped value from its scope is a type error.
-- **Zero Runtime Overhead**: On the eager path the `@@` tag is erased—`A @@ S` is represented as just `A` when evaluated—while deferred/composed computations use a small wrapper/thunk.
+- **Compile-Time Leak Prevention**: Values of type `scope.$[A]` are opaque and unique to each scope instance. Returning a scoped value from its scope is a type error.
+- **Zero Runtime Overhead**: `$[A]` erases to `A` at runtime—zero allocation overhead.
 - **Structured Scopes**: Child scopes nest within parents; resources clean up LIFO when scopes exit.
 - **Built-in Dependency Injection**: Wire up your application with `Resource.from[T](wires*)` for automatic constructor-based DI.
 - **AutoCloseable Integration**: Resources implementing `AutoCloseable` have `close()` registered automatically.
+- **Unscoped Constraint**: The `scoped` method requires `Unscoped[A]` evidence on the return type, ensuring only pure data (not resources or closures) can escape.
 
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.22"
 ```
 
 ### Example: Basic Resource Management
@@ -241,11 +244,14 @@ final class Database extends AutoCloseable {
 }
 
 Scope.global.scoped { scope =>
-  // Allocate returns Database @@ scope.Tag (scoped value)
-  val db = scope.allocate(Resource(new Database))
+  import scope._
+
+  // Allocate returns scope.$[Database] (scoped value)
+  val db: $[Database] = allocate(Resource(new Database))
+
+  // Access via scope.use - result (String) escapes, db does not
+  val result = scope.use(db)(_.query("SELECT * FROM users"))
 
-  // Access via scope $ - result (String) escapes, db does not
-  val result = (scope $ db)(_.query("SELECT * FROM users"))
   println(result)
 }
 // Output: Result: SELECT * FROM users
@@ -269,8 +275,11 @@ val serviceResource: Resource[UserService] = Resource.from[UserService](
 )
 
 Scope.global.scoped { scope =>
-  val service = scope.allocate(serviceResource)
-  (scope $ service)(_.createUser("Alice"))
+  import scope._
+
+  val service = allocate(serviceResource)
+
+  scope.use(service)(_.createUser("Alice"))
 }
 // Cleanup runs LIFO: UserService → Database (UserRepo has no cleanup)
 ```
@@ -279,14 +288,24 @@ Scope.global.scoped { scope =>
 
 ```scala
 Scope.global.scoped { connScope =>
-  val conn = connScope.allocate(Resource.fromAutoCloseable(new Connection))
+  import connScope._
+
+  val conn = allocate(Resource.fromAutoCloseable(new Connection))
 
   // Transaction lives in child scope - cleaned up before connection
-  val result = connScope.scoped { txScope =>
-    val tx = txScope.allocate(conn.beginTransaction())  // Returns Resource!
-    (txScope $ tx)(_.execute("INSERT INTO users VALUES (1, 'Alice')"))
-    (txScope $ tx)(_.commit())
-    "success"
+  val result: String = scoped { txScope =>
+    import txScope._
+
+    // For-comprehension: flatMap unwraps $[Connection] to Connection,
+    // so c.beginTransaction() returns a raw Resource[Transaction]
+    for {
+      c  <- lower(conn)
+      tx <- allocate(c.beginTransaction())
+    } yield {
+      tx.execute("INSERT INTO users VALUES (1, 'Alice')")
+      tx.commit()
+      "success"
+    }
   }
   // Transaction closed here, connection still open
 
@@ -321,7 +340,7 @@ Generating documentation, README files, or any Markdown content programmatically
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.22"
 ```
 
 ### Example
@@ -405,7 +424,7 @@ Compile-time type identity with rich metadata. TypeId captures comprehensive inf
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.22"
 ```
 
 ### Example
@@ -448,7 +467,7 @@ A type-indexed heterogeneous collection that stores values by their types with c
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.22"
 ```
 
 ### Example
@@ -534,6 +553,7 @@ ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibil
 
 ### Serialization
 
+- [Codec & Format](./reference/codec.md) - Codec, Format, BinaryCodec & TextCodec
 - [JSON](./reference/json.md) - JSON codec and parsing
 - [JSON Schema](./reference/json-schema.md) - JSON Schema generation and validation
 - [Formats](./reference/formats.md) - Avro, TOON, MessagePack, BSON, Thrift

package/package.json

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

package/path-interpolator.md

@@ -1,6 +1,7 @@
-# Path Interpolator
-
-## Overview
+---
+id: path-interpolator
+title: "Path Interpolator"
+---
 
 The path interpolator `p"..."` is a compile-time string interpolator for constructing `DynamicOptic` instances in ZIO Blocks. It provides a clean, concise syntax for building optic paths that navigate through complex data structures, with all parsing and validation happening at compile time for zero runtime overhead.
 
@@ -215,14 +216,14 @@ p"<A><B><C>"       // Nested variants
 
 String and character literals support standard escape sequences:
 
-| Escape | Result | Description |
-|--------|--------|-------------|
-| `\n`   | newline | Line feed |
-| `\t`   | tab | Horizontal tab |
-| `\r`   | return | Carriage return |
-| `\'`   | `'` | Single quote |
-| `\"`   | `"` | Double quote |
-| `\\`   | `\` | Backslash |
+| Escape | Result  | Description     |
+|--------|---------|-----------------|
+| `\n`   | newline | Line feed       |
+| `\t`   | tab     | Horizontal tab  |
+| `\r`   | return  | Carriage return |
+| `\'`   | `'`     | Single quote    |
+| `\"`   | `"`     | Double quote    |
+| `\\`   | `\`     | Backslash       |
 
 **Examples:**
 
@@ -618,19 +619,19 @@ val same = p".users[*].email"
 
 **Examples:**
 
-| DynamicOptic Construction | toString Output |
-|---------------------------|-----------------|
-| `DynamicOptic.root.field("name")` | `.name` |
+| DynamicOptic Construction                            | toString Output   |
+|------------------------------------------------------|-------------------|
+| `DynamicOptic.root.field("name")`                    | `.name`           |
 | `DynamicOptic.root.field("address").field("street")` | `.address.street` |
-| `DynamicOptic.root.caseOf("Some")` | `<Some>` |
-| `DynamicOptic.root.at(0)` | `[0]` |
-| `DynamicOptic.root.atIndices(0, 2, 5)` | `[0,2,5]` |
-| `DynamicOptic.elements` | `[*]` |
-| `DynamicOptic.root.atKey("host")` | `{"host"}` |
-| `DynamicOptic.root.atKey(80)` | `{80}` |
-| `DynamicOptic.mapValues` | `{*}` |
-| `DynamicOptic.mapKeys` | `{*:}` |
-| `DynamicOptic.wrapped` | `.~` |
+| `DynamicOptic.root.caseOf("Some")`                   | `<Some>`          |
+| `DynamicOptic.root.at(0)`                            | `[0]`             |
+| `DynamicOptic.root.atIndices(0, 2, 5)`               | `[0,2,5]`         |
+| `DynamicOptic.elements`                              | `[*]`             |
+| `DynamicOptic.root.atKey("host")`                    | `{"host"}`        |
+| `DynamicOptic.root.atKey(80)`                        | `{80}`            |
+| `DynamicOptic.mapValues`                             | `{*}`             |
+| `DynamicOptic.mapKeys`                               | `{*:}`            |
+| `DynamicOptic.wrapped`                               | `.~`              |
 
 ## Summary
 

package/reference/codec.md

@@ -0,0 +1,384 @@
+---
+id: codec
+title: "Codec"
+---
+
+`Codec[DecodeInput, EncodeOutput, Value]` is the base abstraction for encoding and decoding values between a specific input representation and a specific output representation. It forms the foundation of ZIO Blocks' multi-format serialization system, enabling a single `Schema[A]` to derive codecs for JSON, Avro, TOON, MessagePack, Thrift, and other formats that are integrated via the `Codec`/`Format` system. BSON support is provided separately via `BsonSchemaCodec`, which is not a subtype of `codec.Codec` and is not derived via `Schema.derive(format)`.
+
+## Overview
+
+`Codec` defines two abstract methods that every concrete codec must implement:
+
+```scala
+abstract class Codec[DecodeInput, EncodeOutput, Value] {
+  def encode(value: Value, output: EncodeOutput): Unit
+  def decode(input: DecodeInput): Either[SchemaError, Value]
+}
+```
+
+- **`encode`** writes the encoded form of `value` into `output`. The output parameter is typically a mutable buffer (`ByteBuffer`, `CharBuffer`) that the caller provides.
+- **`decode`** reads from `input` and returns either a `SchemaError` describing the failure or the decoded value.
+
+End users rarely interact with `Codec` directly. Instead, they work with format-specific subclasses like `JsonBinaryCodec[A]` or `ToonBinaryCodec[A]`, which add convenience methods for common input/output types.
+
+Given a `Schema[A]`, you can derive a codec for any supported format by calling `Schema[A].derive(format)`, which uses the `Deriver` associated with that format to generate the appropriate codec instance. For example, to derive a JSON codec:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(name: String, age: Int)
+
+object Person {
+  // Derive a schema for Person (required for codec derivation)
+  implicit val schema: Schema[Person] = Schema.derived
+  // Derive a JSON codec from the schema
+  implicit val codec: JsonBinaryCodec[Person] = schema.derive[JsonFormat.type](JsonFormat)
+}
+
+// Encode
+val bytes: Array[Byte] = Person.codec.encode(Person("Alice", 30))
+
+// Decode
+val result: Either[SchemaError, Person] = Person.codec.decode(bytes)
+```
+
+## Installation
+
+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.22"
+```
+
+Additional format modules are separate artifacts:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.22"
+```
+
+For cross-platform projects (Scala.js):
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.22"
+```
+
+Supported Scala versions: 2.13.x and 3.x.
+
+## BinaryCodec and TextCodec
+
+The codec system in ZIO Blocks is organized as a layered hierarchy:
+
+```
+Codec[DecodeInput, EncodeOutput, Value]        
+├── BinaryCodec[A] =  Codec[ByteBuffer, ByteBuffer, A]   (ByteBuffer ↔ A)
+│   ├── JsonBinaryCodec[A]                    
+│   ├── AvroBinaryCodec[A]                   
+│   ├── ToonBinaryCodec[A]                  
+│   ├── ThriftBinaryCodec[A]               
+│   └── MessagePackBinaryCodec[A]         
+└── TextCodec[A] = Codec[CharBuffer, CharBuffer, A]      (CharBuffer ↔ A)
+```
+
+1. **`BinaryCodec[A]`** fixes both the input and output to `ByteBuffer` and is the base class for all codecs that operate on binary data:
+
+```scala
+abstract class BinaryCodec[A] extends Codec[ByteBuffer, ByteBuffer, A]
+```
+
+2. **`TextCodec[A]`** fixes both the input and output to `CharBuffer`:
+
+```scala
+abstract class TextCodec[A] extends Codec[CharBuffer, CharBuffer, A]
+```
+
+All built-in serialization formats (JSON, Avro, TOON, MessagePack, Thrift) extend `BinaryCodec`. Despite JSON being a text format, the JSON codec operates on UTF-8 encoded bytes for performance.
+
+`TextCodec` exists for formats that operate on character data rather than raw bytes. No built-in formats currently use `TextCodec`, but it is available for custom text-based formats.
+
+## Deriving Codecs
+
+### Using Schema.derive
+
+The primary way to obtain a codec is through `Schema[A].derive`:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// Pass a Format object to get a codec for that format
+val jsonCodec: JsonBinaryCodec[Person] = Schema[Person].derive[JsonFormat.type](JsonFormat)
+```
+
+This works with any format:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+import zio.blocks.schema.toon._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val jsonCodec = Schema[Person].derive(JsonFormat)
+val toonCodec = Schema[Person].derive(ToonFormat)
+```
+
+### Using Schema.deriving for Customization
+
+For more control over the derived codec, use `deriving` to get a `DerivationBuilder`. This lets you override instances for specific substructures or inject modifiers before finalizing:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(name: String, age: Int)
+object Person extends CompanionOptics[Person] {
+  implicit val schema: Schema[Person] = Schema.derived
+  val name = $(_.name)
+  val age  = $(_.age)
+}
+
+// Override the codec for the "name" field
+val customNameCodec = new JsonBinaryCodec[String] {
+  def decodeValue(in: JsonReader, default: String): String = in.readString(default)
+  def encodeValue(x: String, out: JsonWriter): Unit = out.writeVal(x.toUpperCase)
+}
+
+val codec: JsonBinaryCodec[Person] = Schema[Person]
+  .deriving(JsonFormat.deriver)
+  .instance(Person.name, customNameCodec)
+  .derive
+```
+
+### Using Schema#decode and Schema#encode
+
+`Schema` also provides `decode` and `encode` methods that internally call `derive` (with caching) and then delegate to the codec:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+import java.nio.ByteBuffer
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// Encode directly from Schema
+val buffer = ByteBuffer.allocate(1024)
+Schema[Person].encode(JsonFormat)(buffer)(Person("Alice", 30))
+
+// Decode directly from Schema
+buffer.flip()
+val result: Either[SchemaError, Person] = Schema[Person].decode(JsonFormat)(buffer)
+```
+
+### Using a Deriver Directly
+
+Each `Format` object contains a `Deriver[TC]` that can also be passed to `derive`:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// These are equivalent:
+val codec1 = Schema[Person].derive(JsonFormat)
+val codec2 = Schema[Person].derive(JsonFormat.deriver)
+```
+
+Passing a `Deriver` directly is useful when working with custom or configured derivers (see [Configuring Codecs](#configuring-codecs)).
+
+## Convenience Methods on Format-Specific Codecs
+
+While the base `Codec` class defines only `encode(value, output)` and `decode(input)`, format-specific subclasses like `JsonBinaryCodec` and `ToonBinaryCodec` add convenience overloads for common I/O types.
+
+### JsonBinaryCodec Convenience Methods
+
+`JsonBinaryCodec[A]` provides the following overloads beyond the base `ByteBuffer` API:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val codec = Schema[Person].derive(JsonFormat)
+val person = Person("Alice", 30)
+
+// Array[Byte]
+val bytes: Array[Byte] = codec.encode(person)
+val fromBytes: Either[SchemaError, Person] = codec.decode(bytes)
+
+// String
+val jsonStr: String = codec.encodeToString(person)
+val fromStr: Either[SchemaError, Person] = codec.decode("""{"name":"Alice","age":30}""")
+
+// InputStream / OutputStream
+import java.io.{ByteArrayInputStream, ByteArrayOutputStream}
+
+val os = new ByteArrayOutputStream()
+codec.encode(person, os)
+
+val is = new ByteArrayInputStream(os.toByteArray)
+val fromStream: Either[SchemaError, Person] = codec.decode(is)
+```
+
+### ToonBinaryCodec Convenience Methods
+
+`ToonBinaryCodec[A]` provides the same set of overloads:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.toon._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val codec = Schema[Person].derive(ToonFormat)
+val person = Person("Alice", 30)
+
+// Array[Byte]
+val bytes: Array[Byte] = codec.encode(person)
+val fromBytes: Either[SchemaError, Person] = codec.decode(bytes)
+
+// String
+val toonStr: String = codec.encodeToString(person)
+val fromStr: Either[SchemaError, Person] = codec.decode("name: Alice\nage: 30")
+```
+
+### Summary of Convenience Methods
+
+`BinaryCodec` subclasses (JSON, TOON, MessagePack, Avro, Thrift) expose the following convenience overloads (availability may vary by format):
+
+| Method                                               | Description                                  |
+|------------------------------------------------------|----------------------------------------------|
+| `encode(value): Array[Byte]`                         | Encode to a byte array                       |
+| `decode(input: Array[Byte]): Either[SchemaError, A]` | Decode from a byte array                     |
+| `encode(value, output: ByteBuffer): Unit`            | Encode into a `ByteBuffer`                   |
+| `decode(input: ByteBuffer): Either[SchemaError, A]`  | Decode from a `ByteBuffer`                   |
+| `encode(value, output: OutputStream): Unit`          | Encode into an `OutputStream` (JSON, TOON, Avro)   |
+| `decode(input: InputStream): Either[SchemaError, A]` | Decode from an `InputStream` (JSON, TOON, Avro)    |
+| `encodeToString(value): String`                      | Encode to a `String` (JSON, TOON)            |
+| `decode(input: String): Either[SchemaError, A]`      | Decode from a `String` (JSON, TOON)          |
+
+The `String`-based methods are available on text-oriented binary codecs (JSON, TOON) but not on purely binary formats like Avro or Thrift.
+
+## Configuring Codecs
+
+Format-specific derivers support configuration options that control encoding behavior. Instead of passing a `Format` object to `derive`, you pass a configured `Deriver`:
+
+### JSON Configuration
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Person(
+  firstName: String,
+  lastName: String,
+  middleName: Option[String] = None
+)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val customDeriver = JsonBinaryCodecDeriver
+  .withFieldNameMapper(NameMapper.SnakeCase)
+  .withTransientNone(true)
+  .withRejectExtraFields(true)
+
+val codec = Schema[Person].derive(customDeriver)
+
+// Encodes as: {"first_name":"Alice","last_name":"Smith"}
+// (middleName omitted because it is None and transientNone is true)
+val json = codec.encodeToString(Person("Alice", "Smith"))
+```
+
+| Option                          | Description                                            | Default    |
+|---------------------------------|--------------------------------------------------------|------------|
+| `withFieldNameMapper`           | Transform field names (Identity, SnakeCase, KebabCase) | `Identity` |
+| `withCaseNameMapper`            | Transform variant/case names                           | `Identity` |
+| `withDiscriminatorKind`         | ADT discriminator style (Key, Field, None)             | `Key`      |
+| `withRejectExtraFields`         | Error on unknown fields during decoding                | `false`    |
+| `withEnumValuesAsStrings`       | Encode enum values as strings                          | `true`     |
+| `withTransientNone`             | Omit `None` values from output                         | `true`     |
+| `withTransientEmptyCollection`  | Omit empty collections from output                     | `true`     |
+| `withTransientDefaultValue`     | Omit fields with default values                        | `true`     |
+| `withRequireOptionFields`       | Require optional fields in input                       | `false`    |
+| `withRequireCollectionFields`   | Require collection fields in input                     | `false`    |
+| `withRequireDefaultValueFields` | Require fields with defaults in input                  | `false`    |
+
+### TOON Configuration
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.toon._
+
+case class Person(
+  firstName: String,
+  lastName: String
+)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val customDeriver = ToonBinaryCodecDeriver
+  .withFieldNameMapper(NameMapper.SnakeCase)
+  .withArrayFormat(ArrayFormat.Tabular)
+  .withDiscriminatorKind(DiscriminatorKind.Field("type"))
+
+val codec = Schema[Person].derive(customDeriver)
+```
+
+## Error Handling
+
+All `decode` operations return `Either[SchemaError, A]`. `SchemaError` includes path information that pinpoints where in the data structure decoding failed:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+case class Address(street: String, city: String)
+case class Person(name: String, address: Address)
+
+object Address {
+  implicit val schema: Schema[Address] = Schema.derived
+}
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+val codec = Schema[Person].derive(JsonFormat)
+
+// Missing required field
+val result = codec.decode("""{"name":"Alice","address":{}}""")
+
+result match {
+  case Right(person) => println(person)
+  case Left(error)   => error.errors.foreach(e => println(s"Error: ${e.message}"))
+}
+```

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.21"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.22"
 ```
 
 ## Core Types