@zio.dev/zio-blocks 0.0.1 → 0.0.22

package/reference/dynamic-value.md

@@ -33,7 +33,7 @@ Key design decisions:
 
 Wraps scalar values in a `PrimitiveValue`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 // Using convenience constructors
@@ -53,7 +53,7 @@ val instant = DynamicValue.Primitive(
 
 A collection of named fields, analogous to case classes or JSON objects:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.chunk.Chunk
 
@@ -80,7 +80,7 @@ Field order is preserved and significant for equality. Use `sortFields` to norma
 
 A tagged union value, analogous to sealed traits:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 // A Some variant containing a value
@@ -101,7 +101,7 @@ some.caseValue  // Some(DynamicValue.Primitive(...))
 
 An ordered collection of values:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.chunk.Chunk
 
@@ -126,7 +126,7 @@ val empty = DynamicValue.Sequence.empty
 
 Key-value pairs where both keys and values are `DynamicValue`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.chunk.Chunk
 
@@ -152,7 +152,7 @@ Unlike `Record` which uses String keys, `Map` supports arbitrary `DynamicValue`
 
 Represents the absence of a value:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 val absent = DynamicValue.Null
@@ -199,7 +199,7 @@ val absent = DynamicValue.Null
 
 Use `Schema.toDynamicValue` to convert typed Scala values to `DynamicValue`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{Schema, DynamicValue}
 
 case class Person(name: String, age: Int)
@@ -220,7 +220,7 @@ val listDynamic = Schema[List[Int]].toDynamicValue(List(1, 2, 3))
 
 Use `Schema.fromDynamicValue` to convert `DynamicValue` back to typed Scala values:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{Schema, DynamicValue, SchemaError}
 
 case class Person(name: String, age: Int)
@@ -248,7 +248,7 @@ val error = Schema[Person].fromDynamicValue(badDynamic)
 
 Each `DynamicValue` has a corresponding `DynamicValueType` for runtime type checking:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicValueType}
 
 val dv = DynamicValue.Record("x" -> DynamicValue.int(1))
@@ -269,7 +269,7 @@ val fields: Option[Chunk[(String, DynamicValue)]] =
 
 ### Extracting Primitive Values
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, PrimitiveType, Validation}
 
 val dv = DynamicValue.int(42)
@@ -288,7 +288,7 @@ val stringValue: Option[String] = dv.asPrimitive(PrimitiveType.String(Validation
 
 Navigate using `get` methods that return `DynamicValueSelection`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 val data = DynamicValue.Record(
@@ -315,7 +315,7 @@ val name = firstName.one  // Either[SchemaError, DynamicValue]
 
 Use `DynamicOptic` for complex path expressions:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record(
@@ -337,7 +337,7 @@ val result = data.get(path).one  // Right(DynamicValue.Primitive(String("Alice")
 
 `DynamicValueSelection` wraps navigation results and provides fluent chaining:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicValueSelection}
 
 val selection: DynamicValueSelection = ???
@@ -366,7 +366,7 @@ selection.flatMap(dv => ???)  // Chain selections
 
 Update values at a path:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record(
@@ -386,7 +386,7 @@ val updated = data.modify(path)(dv => DynamicValue.string("Bob"))
 
 Replace a value at a path:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record("x" -> DynamicValue.int(1))
@@ -400,7 +400,7 @@ val updated = data.set(path, DynamicValue.int(99))
 
 Remove a value at a path:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record(
@@ -416,7 +416,7 @@ val updated = data.delete(DynamicOptic.root.field("a"))
 
 Add a value at a path (fails if path exists):
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record("a" -> DynamicValue.int(1))
@@ -432,7 +432,7 @@ val updated = data.insert(
 
 Use `*OrFail` variants for operations that should fail explicitly:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic, SchemaError}
 
 val data = DynamicValue.Record("x" -> DynamicValue.int(1))
@@ -452,7 +452,7 @@ val result: Either[SchemaError, DynamicValue] =
 - Adds `@ {tag: "..."}` annotations for Variants
 - Adds `@ {type: "..."}` annotations for typed primitives (Instant, Duration, etc.)
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, PrimitiveValue}
 
 val person = DynamicValue.Record(
@@ -488,7 +488,7 @@ Use `toEjson(indent)` to control indentation level.
 
 Merge two `DynamicValue` structures using configurable strategies:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicValueMergeStrategy}
 
 val left = DynamicValue.Record(
@@ -517,7 +517,7 @@ val merged = left.merge(right, DynamicValueMergeStrategy.Auto)
 | `Concat` | Concatenate Sequences instead of merging by index |
 | `Custom(f, r)` | Custom function with custom recursion control |
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicValueMergeStrategy}
 
 val list1 = DynamicValue.Sequence(DynamicValue.int(1), DynamicValue.int(2))
@@ -532,7 +532,7 @@ val concatted = list1.merge(list2, DynamicValueMergeStrategy.Concat)
 
 Transform `DynamicValue` structures for comparison or serialization:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 val data = DynamicValue.Record(
@@ -566,7 +566,7 @@ data.normalize
 
 Apply functions to all values in a structure:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic, PrimitiveValue}
 
 val data = DynamicValue.Record(
@@ -593,7 +593,7 @@ val topDown = data.transformDown { (path, dv) => ??? }
 
 Rename all record fields:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 val data = DynamicValue.Record(
@@ -615,7 +615,7 @@ val camelCase = data.transformFields { (path, name) =>
 
 Aggregate values from a `DynamicValue` tree:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic, PrimitiveValue}
 
 val data = DynamicValue.Record(
@@ -638,7 +638,7 @@ val sum = data.foldUp(0) { (path, dv, acc) =>
 
 ### To JSON
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.schema.json.Json
 
@@ -653,7 +653,7 @@ val json: Json = dynamic.toJson
 
 ### From JSON
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.schema.json.Json
 
@@ -667,7 +667,7 @@ val dynamic: DynamicValue = json.toDynamicValue
 
 Search recursively for values matching a predicate:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicValueType, PrimitiveValue}
 
 val data = DynamicValue.Record(
@@ -691,7 +691,7 @@ val atDepth2 = data.select.queryPath(path => path.nodes.length == 2)
 
 Work with data when the schema isn't known at compile time:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, PrimitiveValue}
 
 def processAnyData(data: DynamicValue): DynamicValue = {
@@ -712,7 +712,7 @@ def processAnyData(data: DynamicValue): DynamicValue = {
 
 Transform data between schema versions:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 def migrateV1toV2(data: DynamicValue): DynamicValue = {
@@ -735,7 +735,7 @@ def migrateV1toV2(data: DynamicValue): DynamicValue = {
 
 Build queries at runtime:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{DynamicValue, DynamicOptic}
 
 def buildPath(fields: List[String]): DynamicOptic =
@@ -761,7 +761,7 @@ val email = getValue(data, List("user", "profile", "email"))
 
 Use `DynamicValue` as an intermediate format:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.{Schema, DynamicValue}
 import zio.blocks.schema.json.Json
 
@@ -784,7 +784,7 @@ val json2 = dynamic2.toJson
 
 `DynamicValue` has a total ordering for sorting and comparison:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 
 val a = DynamicValue.int(1)
@@ -804,7 +804,7 @@ primitive < record  // true
 
 Compute differences between `DynamicValue` instances:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.DynamicValue
 import zio.blocks.schema.patch.DynamicPatch
 

package/reference/formats.md

@@ -1,15 +1,82 @@
 ---
 id: formats
 title: "Serialization Formats"
+sidebar_label: "Formats"
 ---
 
 ZIO Blocks Schema provides automatic codec derivation for multiple serialization formats. Once you have a `Schema[A]` for your data type, you can derive codecs for any supported format using the unified `Schema.derive(Format)` pattern.
 
-## Overview: Codec Derivation System
+A `Format` is an abstraction that bundles together everything needed to serialize and deserialize data in a specific format (JSON, Avro, Protobuf, etc.).
+
+## Overview
+
+Each format defines the types of input for decoding and output for encoding, as well as the typeclass used as a codec for that format. Each format contains a `Deriver` corresponding to its specific MIME type, which is used to derive codecs from schemas:
+
+```scala
+trait Format {
+  type DecodeInput
+  type EncodeOutput
+  type TypeClass[A] <: Codec[DecodeInput, EncodeOutput, A]
+  def mimeType: String
+  def deriver: Deriver[TypeClass]
+}
+```
+
+It unifies all metadata related to serialization formats, such as MIME type and codec deriver, in a single place. This allows for a consistent API across different formats when deriving codecs from schemas. Having MIME type information helps with runtime content negotiation and format routing, for example in HTTP servers or message queues.
+
+That is, you can easily call [`Schema[A].derive(format)`](./type-class-derivation.md#using-the-deriver-to-derive-type-class-instances) for any format that implements the `Format` trait, and receive a codec that can encode and decode values of type `A` according to the rules of that format.
+
+Formats are categorized into `BinaryFormat` and `TextFormat`, which specify the types of input and output for encoding and decoding:
+
+```scala
+sealed trait Format
+abstract class BinaryFormat[...](...) extends Format { ... }
+abstract class TextFormat[...](...) extends Format { ... }
+```
+
+For example, the `JsonFormat` is a `BinaryFormat` that represents a JSON binary format, where the input for decoding is `ByteBuffer` and the output for encoding is also `ByteBuffer`, the MIME type is `application/json`, and the deriver for generating codecs from schemas is `JsonBinaryCodecDeriver`:
+
+```scala
+object JsonFormat extends BinaryFormat("application/json", JsonBinaryCodecDeriver)
+```
+
+## Built-in Formats
+
+Here's a summary of the formats currently supported by ZIO Blocks. Each format provides a `BinaryFormat` object that can be passed to `derive`:
+
+| Format Object       | Codec Type                  | MIME Type             | Module                          |
+|---------------------|-----------------------------|-----------------------|---------------------------------|
+| `JsonFormat`        | `JsonBinaryCodec[A]`        | `application/json`    | `zio-blocks-schema`             |
+| `ToonFormat`        | `ToonBinaryCodec[A]`        | `text/toon`           | `zio-blocks-schema-toon`        |
+| `MessagePackFormat` | `MessagePackBinaryCodec[A]` | `application/msgpack` | `zio-blocks-schema-messagepack` |
+| `AvroFormat`        | `AvroBinaryCodec[A]`        | `application/avro`    | `zio-blocks-schema-avro`        |
+| `ThriftFormat`      | `ThriftBinaryCodec[A]`      | `application/thrift`  | `zio-blocks-schema-thrift`      |
+
+## Defining a Custom Format
+
+To add a new serialization format, define a `BinaryFormat` (or `TextFormat`) singleton with a custom `Deriver`:
+
+```scala
+import zio.blocks.schema.codec.{BinaryCodec, BinaryFormat}
+import zio.blocks.schema.derive.Deriver
+
+// 1. Define your codec base class
+abstract class MyCodec[A] extends BinaryCodec[A]
+
+// 2. Implement a Deriver[MyCodec] (see Type-class Derivation docs)
+// val myDeriver: Deriver[MyCodec] = ...
+
+// 3. Create the format singleton
+// object MyFormat extends BinaryFormat[MyCodec]("application/x-myformat", myDeriver)
+```
+
+For details on implementing a `Deriver`, see [Type-class Derivation](./type-class-derivation.md).
+
+## Codec Derivation System
 
 All serialization formats in ZIO Blocks follow the same pattern: given a `Schema[A]`, you derive a codec by calling `derive` with a format object:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.toon._
 
@@ -29,17 +96,6 @@ val bytes: Array[Byte] = codec.encode(Person("Alice", 30))
 val result: Either[SchemaError, Person] = codec.decode(bytes)
 ```
 
-Each format provides a `BinaryFormat` object that can be passed to `derive`:
-
-| Format | Object | MIME Type | Platform Support |
-|--------|--------|-----------|------------------|
-| JSON | `JsonFormat` | `application/json` | JVM, JS |
-| TOON | `ToonFormat` | `text/toon` | JVM, JS |
-| MessagePack | `MessagePackFormat` | `application/msgpack` | JVM, JS |
-| Avro | `AvroFormat` | `application/avro` | JVM only |
-| Thrift | `ThriftFormat` | `application/thrift` | JVM only |
-| BSON | `BsonSchemaCodec` | Binary | JVM only |
-
 ## JSON Format
 
 JSON format is the most commonly used text-based serialization format. See the dedicated [JSON documentation](json.md) for comprehensive coverage of the `Json` ADT, navigation, and transformation features.
@@ -54,7 +110,7 @@ libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "<version>"
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -89,7 +145,7 @@ Requires the Apache Avro library (1.12.x).
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.avro._
 
@@ -114,7 +170,7 @@ val decoded: Either[SchemaError, Person] = codec.decode(bytes)
 
 Each `AvroBinaryCodec` exposes an `avroSchema` property containing the Apache Avro schema:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.avro._
 import org.apache.avro.{Schema => AvroSchema}
@@ -162,7 +218,7 @@ println(avroSchema.toString(true))
 
 Sealed traits are encoded as Avro unions with an integer index prefix:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.avro._
 
@@ -202,7 +258,7 @@ libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "<version>"
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.toon._
 
@@ -260,7 +316,7 @@ orders[2]{id,total}:
 
 The `ToonBinaryCodecDeriver` provides extensive configuration:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.toon._
 
@@ -295,7 +351,7 @@ val codec = Schema[Person].derive(customDeriver)
 
 ### ADT Encoding Styles
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.toon._
 
@@ -331,7 +387,7 @@ libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "<version>
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.msgpack._
 
@@ -383,7 +439,7 @@ MessagePack provides significant space savings compared to JSON:
 
 Sealed traits encode a variant index followed by the case value:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.msgpack._
 
@@ -416,7 +472,7 @@ Requires the MongoDB BSON library (5.x).
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.bson._
 
@@ -438,7 +494,7 @@ val codec: BsonCodec[Person] = BsonSchemaCodec.bsonCodec(Schema[Person])
 
 BSON provides native support for MongoDB ObjectIds:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.bson._
 import org.bson.types.ObjectId
@@ -458,7 +514,7 @@ val codec = BsonSchemaCodec.bsonCodec(Schema[Document])
 
 ### Configuration Options
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.bson._
 import BsonSchemaCodec._
@@ -486,7 +542,7 @@ val codec = BsonSchemaCodec.bsonCodec(Schema[Person], config)
 
 ### Sum Type Handling
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.bson.BsonSchemaCodec.SumTypeHandling
 
 // Option 1: Wrapper with class name as field key (default)
@@ -515,7 +571,7 @@ Requires the Apache Thrift library (0.22.x).
 
 ### Basic Usage
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.thrift._
 import java.nio.ByteBuffer
@@ -616,7 +672,7 @@ All formats support the full set of ZIO Blocks Schema primitive types:
 
 All formats return `Either[SchemaError, A]` for decoding operations. Errors include path information for debugging:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.toon._