@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/schema/built-in-codecs/json/index.md

@@ -0,0 +1,295 @@
+---
+id: index
+title: "JSON Codec"
+---
+
+The JSON codec module provides complete, type-safe support for working with JSON data in ZIO Blocks. It includes an ADT for representing JSON values, a fluent navigation API (`JsonSelection`), configurable encoding/decoding (`JsonCodec` with `WriterConfig`/`ReaderConfig`), composable patches for transformations, a diff algorithm for computing minimal changes, and full JSON Schema 2020-12 support for validation and code generation.
+
+**Core types:** `Json`, `JsonCodec`, `JsonSelection`, `JsonPatch`, `JsonDiffer`, `JsonSchema`, `JsonType`.
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json._
+
+// Represent any JSON value
+val person = Json.Object("name" -> Json.String("Alice"), "age" -> Json.Number(30))
+
+// Navigate with fluent API
+val age = person.get("age")  // JsonSelection
+
+// Encode to string
+val encoded = person.print(WriterConfig)
+
+// Compute minimal patches
+val updated = person.set(p".age", Json.Number(31))
+val patch = JsonPatch.diff(person, updated)
+
+// Validate against a schema
+case class Person(name: String, age: Int)
+object Person { implicit val schema: Schema[Person] = Schema.derived }
+val schema: JsonSchema = Schema[Person].toJsonSchema
+schema.conforms(person)  // true
+```
+
+## Installation
+
+The JSON codec is included in the ZIO Blocks Schema module. Add it to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+```
+
+For Scala.js projects, use `%%%` instead:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.51"
+```
+
+**Supported Scala versions:** 2.13.x and 3.x
+
+The JSON codec is fully integrated into ZIO Blocks Schema and provides complete type-safe JSON support with no external dependencies beyond core ZIO libraries.
+
+## How They Work Together
+
+The JSON module workflow moves through representation, navigation, encoding/decoding, diffing, patching, and validation:
+
+```
+Parse/Create JSON
+    ↓
+Json (ADT: Object, Array, String, Number, Boolean, Null)
+    ├─ Navigate with JsonSelection (fluent query API)
+    ├─ Understand with JsonType (type information)
+    └─ Transform via JsonPatch (composable operations)
+    ↓
+JsonCodec (encode/decode)
+    ├─ WriterConfig (indent, escaping, order)
+    ├─ ReaderConfig (strict validation, number handling)
+    └─ MergeStrategy (field conflict resolution)
+    ↓
+JsonDiffer (diff algorithm)
+    └─ Produces JsonPatch (minimal changes)
+    ↓
+JsonPatch.apply (transform JSON)
+    ↓
+JsonSchema (validate or generate)
+    ├─ Derive from Scala types
+    ├─ Validate JSON conformance
+    └─ Generate documentation
+```
+
+**Type Relationships:**
+- `Json` is the central value type; all operations start with or produce it
+- `JsonSelection` provides fluent navigation through nested `Json` structures
+- `JsonCodec` bridges Scala types ↔ `Json` with configurable `WriterConfig` and `ReaderConfig`
+- `JsonDiffer` computes `JsonPatch` by comparing two `Json` values
+- `JsonPatch` transforms `Json` values with composable operations
+- `JsonSchema` validates `Json` conformance and derives from Scala `Schema` types
+- `JsonType` provides type information for `Json` values at runtime
+
+## Common Patterns
+
+### Pattern 1: Parse, Transform, Serialize
+
+Read JSON, modify it, and write it back:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{Json, WriterConfig}
+
+val jsonString = """{"name": "Alice", "age": 30}"""
+val json = Json.parseUnsafe(jsonString)
+
+// Transform
+val updated = json.modify(p".age") {
+  case Json.Number(n) => Json.Number(n + 1)
+  case other => other
+}
+
+// Serialize
+val output = updated.print(WriterConfig.withIndentionStep2)
+```
+
+### Pattern 2: Diff and Apply
+
+Compute changes and apply them:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonPatch}
+
+val original = Json.Object("count" -> Json.Number(0))
+val target = Json.Object("count" -> Json.Number(1), "active" -> Json.Boolean(true))
+
+// Compute the diff
+val patch = JsonPatch.diff(original, target)
+
+// Apply to reconstruct
+val result = patch.apply(original)
+// Right({"count": 1, "active": true})
+```
+
+### Pattern 3: Validate with Schema
+
+Generate and validate using schemas:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{Json, JsonSchema}
+
+case class User(name: String, email: String, age: Int)
+object User {
+  implicit val schema: Schema[User] = Schema.derived
+}
+
+val jsonSchema: JsonSchema = Schema[User].toJsonSchema
+val validJson = Json.Object(
+  "name" -> Json.String("Alice"),
+  "email" -> Json.String("alice@example.com"),
+  "age" -> Json.Number(30)
+)
+
+jsonSchema.conforms(validJson)  // true
+```
+
+### Pattern 4: Navigate and Extract with JsonSelection
+
+Use fluent API to navigate nested structures and extract values:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.Json
+
+val data = Json.Object(
+  "users" -> Json.Array(
+    Json.Object("name" -> Json.String("Alice"), "age" -> Json.Number(30)),
+    Json.Object("name" -> Json.String("Bob"), "age" -> Json.Number(25))
+  )
+)
+
+// Navigate to first user's age
+val age: Either[SchemaError, Int] = data
+  .get("users")        // JsonSelection
+  (0)                 // Navigate to first array element
+  .get("age")         // Navigate to age field
+  .as[Int]            // Decode to Int
+
+// Check values
+val ageValue = data.get("users")(0).get("age").one  // Right(Json.Number(30))
+```
+
+### Pattern 5: Encode and Decode with Configuration
+
+Control output formatting and parsing behavior:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{Json, WriterConfig}
+
+case class Config(host: String, port: Int)
+object Config {
+  implicit val schema: Schema[Config] = Schema.derived
+}
+
+val config = Config("localhost", 8080)
+val json = config.toJson
+
+// Encode with custom formatting
+val pretty = json.print(WriterConfig.withIndentionStep(2))
+
+// Decode: parse back to Json, then decode
+val parsed: Json = Json.parseUnsafe(pretty)
+val config2: Either[SchemaError, Config] = parsed.as[Config]
+```
+
+### Pattern 6: Compose Multiple Patches
+
+Chain multiple transformations into a single patch:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{Json, JsonPatch}
+
+val original = Json.Object("x" -> Json.Number(1), "y" -> Json.Number(2))
+
+// Build patches independently
+val patchX = JsonPatch.diff(
+  original,
+  original.set(p".x", Json.Number(10))
+)
+
+val patchY = JsonPatch.diff(
+  original.set(p".x", Json.Number(10)),
+  original.set(p".x", Json.Number(10)).set(p".y", Json.Number(20))
+)
+
+// Compose them
+val combined = patchX ++ patchY
+combined.apply(original)
+// Right({"x": 10, "y": 20})
+```
+
+## Integration Points
+
+**With other codecs:** `Json` values convert to/from other formats (Avro, TOON, etc.) via `DynamicValue`:
+
+```scala
+import zio.blocks.schema.json.Json
+import zio.blocks.schema.DynamicValue
+
+val json = Json.parseUnsafe("""{"name": "Alice"}""")
+val dynamic: DynamicValue = json.toDynamicValue
+
+// Convert to other formats using DynamicValue
+```
+
+**With Schema system:** `Schema` enables automatic JSON encoding/decoding:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.Json
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// Encode using Schema-based extension methods
+val person = Person("Alice", 30)
+val json = person.toJson
+val jsonString = person.toJsonString
+
+// Decode: parse and extract with Schema
+val parsed: Json = Json.parseUnsafe(jsonString)
+val decoded: Either[SchemaError, Person] = parsed.as[Person]
+```
+
+**With patching system:** `JsonPatch` and `JsonDiffer` integrate with generic `Patch` infrastructure:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonPatch}
+import zio.blocks.schema.patch.DynamicPatch
+
+val jsonPatch: JsonPatch = JsonPatch.root(JsonPatch.Op.Set(Json.Null))
+val dynamicPatch: DynamicPatch = jsonPatch.toDynamicPatch
+```
+
+**With optics and navigation:** `JsonSelection` provides query-like access complementary to `Optic` system:
+
+- `JsonSelection` — runtime navigation through unknown JSON structures
+- `Optic` — compile-time, type-safe navigation through known Scala types
+- Both support nested access, filtering, and composition
+
+**With validation:** `JsonSchema` integrates with Schema `Validation` system:
+
+- Derive `JsonSchema` from Scala `Schema[A]`
+- Validate raw JSON before type-safe decoding
+- Compose with logical operators (allOf, anyOf, oneOf)
+
+## Type Pages
+
+- **[Json](./json.md)** — The core ADT representing JSON values with six cases (Object, Array, String, Number, Boolean, Null). Covers construction, navigation, modification, transformation, filtering, merging, and encoding.
+
+- **[JsonPatch](./json-patch.md)** — Composable patches for transforming JSON values. Create patches via diff or manually, compose them with `++`, and apply with different failure modes (Strict, Lenient, Clobber).
+
+- **[JsonDiffer](./json-differ.md)** — Diff algorithm computing minimal patches. Uses smart strategies per type: NumberDelta for numbers, LCS-based StringEdit for strings, ArrayEdit with insertion/deletion for arrays, and ObjectEdit for fields.
+
+- **[JSON Schema](./json-schema.md)** — Full JSON Schema 2020-12 support for validation and code generation. Derive schemas from Scala types, validate JSON, construct schemas manually with builders, and combine with logical operators.

package/reference/schema/built-in-codecs/json/json-config.md

@@ -0,0 +1,217 @@
+---
+id: json-config
+title: "JSON Configuration"
+---
+
+The JSON codec module provides four configuration types for controlling encoding and decoding behavior: `WriterConfig`, `ReaderConfig`, `MergeStrategy`, and `NameMapper`. These types allow fine-grained control over how JSON is serialized and deserialized.
+
+## WriterConfig
+
+`WriterConfig` controls the formatting and content of encoded JSON output. Use it when calling `Json#print` on `Json` values or when encoding values with specific formatting requirements.
+
+### Configuration Options
+
+| Option             | Type    | Default | Purpose                                                       |
+|--------------------|---------|---------|---------------------------------------------------------------|
+| `indentionStep`    | Int     | 0       | Spaces per indentation level (0 = compact JSON)               |
+| `escapeUnicode`    | Boolean | false   | Escape non-ASCII characters as `\uXXXX` for ASCII-only output |
+| `preferredBufSize` | Int     | 32768   | Internal buffer size in bytes for streaming                   |
+
+### Usage Examples
+
+Pretty-print JSON output with configurable indentation:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{WriterConfig}
+
+case class Config(server: String, port: Int, debug: Boolean)
+object Config { implicit val schema: Schema[Config] = Schema.derived }
+
+val config = Config("localhost", 8080, true)
+val json = config.toJson
+
+// Pretty-printed with 2-space indentation
+val pretty = json.print(WriterConfig.withIndentionStep(2))
+// {
+//   "server": "localhost",
+//   "port": 8080,
+//   "debug": true
+// }
+```
+
+Configure custom indentation for JSON output:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.WriterConfig
+
+case class User(name: String, email: String, age: Int)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+val user = User("Alice", "alice@example.com", 30)
+val json = user.toJson
+
+// 4-space indentation
+val sorted = json.print(WriterConfig
+  .withIndentionStep(4)
+)
+// {
+//     "name": "Alice",
+//     "email": "alice@example.com",
+//     "age": 30
+// }
+```
+
+Escape non-ASCII characters for ASCII-only transmission:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.WriterConfig
+
+case class Message(text: String)
+object Message { implicit val schema: Schema[Message] = Schema.derived }
+
+val msg = Message("Hello 世界")
+val json = msg.toJson
+
+// Escape non-ASCII characters - non-ASCII become \uXXXX sequences
+val ascii = json.print(WriterConfig.withEscapeUnicode(true))
+// Output: {"text":"Hello \\u4e16\\u754c"}
+```
+
+## ReaderConfig
+
+`ReaderConfig` controls how JSON input is parsed and validated during decoding. Use it when calling `Json.parse()` with custom parsing behavior.
+
+### Configuration Options
+
+| Option                 | Type    | Default | Purpose                                |
+|------------------------|---------|---------|----------------------------------------|
+| `checkForEndOfInput`   | Boolean | true    | Verify no extra input after valid JSON |
+| `preferredCharBufSize` | Int     | 8192    | Internal character buffer size         |
+
+### Usage Examples
+
+Allow trailing whitespace after valid JSON during parsing:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.{Json, ReaderConfig}
+
+// Lenient: allow trailing whitespace
+val lenientConfig = ReaderConfig.withCheckForEndOfInput(false)
+
+val jsonString = """{"name": "Alice"}   """  // Trailing spaces
+val result = Json.parse(jsonString, lenientConfig)
+// Right(Json.Object(...))
+```
+
+## MergeStrategy
+
+`MergeStrategy` determines how field conflicts are resolved when merging two JSON objects. It provides strategies for different use cases, from strict validation to lenient concatenation.
+
+**Available Strategies:**
+- `Strict` — Fails if the same field appears in both objects
+- `Right` — The right object's values override the left's
+- `Left` — The left object's values take precedence
+- Additional strategies may be available depending on your use case
+
+For details on merge strategies and their usage, see the Merging section of the [Json](./json.md) documentation.
+
+## NameMapper
+
+`NameMapper` customizes how field names are transformed between Scala types and JSON representation. It enables patterns like camelCase ↔ snake_case conversion.
+
+### Built-in Mappers
+
+Use identity mapping to keep field names unchanged:
+
+```scala
+import zio.blocks.schema._
+
+case class User(firstName: String, lastName: String)
+object User { 
+  implicit val schema: Schema[User] = Schema.derived
+}
+
+// Default: no transformation
+val user = User("Alice", "Smith")
+val json = user.toJson
+// {"firstName": "Alice", "lastName": "Smith"}
+```
+
+**Snake Case:**
+Convert camelCase to snake_case:
+
+```scala
+import zio.blocks.schema._
+
+case class User(firstName: String, lastName: String)
+object User { 
+  implicit val schema: Schema[User] = Schema.derived
+  implicit val nameMapper: NameMapper = NameMapper.SnakeCase
+}
+
+val user = User("Alice", "Smith")
+val json = user.toJson
+// {"first_name": "Alice", "last_name": "Smith"}
+```
+
+**Kebab Case:**
+Convert camelCase to kebab-case:
+
+```scala
+import zio.blocks.schema._
+
+case class User(firstName: String, lastName: String)
+object User { 
+  implicit val schema: Schema[User] = Schema.derived
+  implicit val nameMapper: NameMapper = NameMapper.KebabCase
+}
+
+val user = User("Alice", "Smith")
+val json = user.toJson
+// {"first-name": "Alice", "last-name": "Smith"}
+```
+
+**Custom Mappers:**
+Additional custom name mappers may be available depending on your needs. The built-in mappers (Identity, SnakeCase, KebabCase) cover most common use cases.
+
+## Combining Configuration
+
+Use multiple configuration options together for fine-grained control:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.json.WriterConfig
+
+case class Config(server: String, port: Int, timeout: Option[Int])
+object Config { implicit val schema: Schema[Config] = Schema.derived }
+
+val config = Config("example.com", 443, None)
+val json = config.toJson
+
+// Pretty-printed with 4-space indentation
+val output = json.print(WriterConfig
+  .withIndentionStep(4)
+)
+// {
+//     "server": "example.com",
+//     "port": 443
+// }
+```
+
+## Performance Implications
+
+- **WriterConfig:** Indentation increases output size but has minimal performance impact
+- **ReaderConfig:** `checkForEndOfInput` adds one comparison
+- **MergeStrategy:** Strategy choice affects merge performance based on use case
+- **NameMapper:** Applied once per field during schema derivation; zero runtime cost if identity mapping
+
+## Best Practices
+
+1. **Use WriterConfig for human-readable output only** — Compact output is faster for wire transmission
+2. **Choose MergeStrategy based on use case** — Strict for validation, others for defaults
+3. **Standardize on one NameMapper** across your codebase to avoid confusion
+4. **Cache WriterConfig/ReaderConfig instances** — They're immutable and can be reused

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

@@ -338,7 +338,7 @@ combinedPatch.apply(personJson)
 
 ### Converting
 
-`toDynamicPatch` converts a `JsonPatch` to a [`DynamicPatch`](./patch.md). This is always safe — every JSON operation maps to a corresponding dynamic operation. `NumberDelta` widens to `BigDecimalDelta`:
+`toDynamicPatch` converts a `JsonPatch` to a `DynamicPatch`. This is always safe — every JSON operation maps to a corresponding dynamic operation. `NumberDelta` widens to `BigDecimalDelta`:
 
 ```scala
 case class JsonPatch(ops: Chunk[JsonPatch.JsonPatchOp]) {
@@ -386,7 +386,7 @@ modeJson.patch(modePatch, PatchMode.Strict)
 //   SchemaError(
 //     List(
 //       ExpectationMismatch(
-//         source = DynamicOptic(IndexedSeq()),
+//         source = DynamicOptic(ArraySeq()),
 //         expectation = "Key 'a' already exists in object"
 //       )
 //     )
@@ -723,7 +723,7 @@ fieldPatch.apply(doc)
 // res40: Either[SchemaError, Json] = Left(
 //   SchemaError(
 //     List(
-//       MissingField(source = DynamicOptic(IndexedSeq()), fieldName = "updatedAt")
+//       MissingField(source = DynamicOptic(ArraySeq()), fieldName = "updatedAt")
 //     )
 //   )
 // )
@@ -769,7 +769,7 @@ val dynPatch: DynamicPatch               = jsonPatch.toDynamicPatch
 val back: Either[SchemaError, JsonPatch] = JsonPatch.fromDynamicPatch(dynPatch)
 ```
 
-See [Patching](./patch.md) for the typed `Patch[S]` API.
+For the typed `Patch[S]` API, see the Patching documentation.
 
 ### Serialization
 
@@ -782,7 +782,7 @@ import zio.blocks.schema.Schema
 val schema: Schema[JsonPatch] = implicitly[Schema[JsonPatch]]
 ```
 
-See [Codec & Format](./codec.md) for how to derive and use codecs.
+For codec derivation and usage details, see the Codec & Format documentation.
 
 ## Examples
 

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

@@ -27,9 +27,7 @@ Key features:
 
 ## Deriving JSON Schema from Schema
 
-The most common use case is deriving a JSON Schema from an existing `Schema[A]`.
-
-### Basic Derivation
+The most common use case is deriving a JSON Schema from an existing `Schema[A]`. You can derive directly from the schema or through a `JsonCodec` for more control.
 
 ```scala
 import zio.blocks.schema._
@@ -40,9 +38,13 @@ object Person {
   implicit val schema: Schema[Person] = Schema.derived
 }
 
-// Get JSON Schema directly from Schema
+// Direct derivation
 val jsonSchema: JsonSchema = Schema[Person].toJsonSchema
 
+// Or derive through JsonCodec for more control
+val codec = Schema[Person].derive(JsonFormat)
+val jsonSchema2 = codec.toJsonSchema
+
 // The derived schema validates JSON values
 val valid = Json.Object("name" -> Json.String("Alice"), "age" -> Json.Number(30))
 val invalid = Json.Object("name" -> Json.Number(123))
@@ -51,24 +53,6 @@ jsonSchema.conforms(valid)   // true
 jsonSchema.conforms(invalid) // false
 ```
 
-### Through JsonCodec
-
-For more control, derive through `JsonCodec`:
-
-```scala
-import zio.blocks.schema._
-import zio.blocks.schema.json._
-
-case class User(email: String, active: Boolean)
-object User {
-  implicit val schema: Schema[User] = Schema.derived
-}
-
-// Derive codec first, then get JSON Schema
-val codec = Schema[User].derive(JsonFormat)
-val jsonSchema = codec.toJsonSchema
-```
-
 ## Creating Schemas
 
 ### Boolean Schemas
@@ -197,22 +181,14 @@ Create schemas for object validation:
 import zio.blocks.schema.json.{JsonSchema, JsonSchemaType}
 import zio.blocks.chunk.ChunkMap
 
-// Object with properties
+// Object with properties and constraints
 val person = JsonSchema.obj(
-  properties = Some(ChunkMap(
-    "name" -> JsonSchema.ofType(JsonSchemaType.String),
-    "age" -> JsonSchema.ofType(JsonSchemaType.Integer)
-  )),
-  required = Some(Set("name"))
-)
-
-// Object with no additional properties
-val strictPerson = JsonSchema.obj(
   properties = Some(ChunkMap(
     "name" -> JsonSchema.ofType(JsonSchemaType.String),
     "age" -> JsonSchema.ofType(JsonSchemaType.Integer)
   )),
   required = Some(Set("name")),
+  // Reject properties not defined above
   additionalProperties = Some(JsonSchema.False)
 )
 ```
@@ -320,7 +296,7 @@ val paymentSchema = JsonSchema.Object(
 ### Basic Validation
 
 ```scala
-import zio.blocks.schema.json.{JsonSchema, Json, JsonSchemaType}
+import zio.blocks.schema.json.{JsonSchema, Json, JsonSchemaType, ValidationOptions}
 import zio.blocks.chunk.ChunkMap
 
 val schema = JsonSchema.obj(
@@ -347,25 +323,16 @@ schema.check(invalidJson) // Some(SchemaError(...))
 // Using conforms() - returns Boolean
 schema.conforms(validJson)   // true
 schema.conforms(invalidJson) // false
-```
-
-### Validation Options
-
-Control validation behavior:
-
-```scala
-import zio.blocks.schema.json.{JsonSchema, Json, ValidationOptions}
 
-val schema = JsonSchema.string(format = Some("email"))
-val value = Json.String("not-an-email")
+// Control validation behavior with ValidationOptions
+val emailSchema = JsonSchema.string(format = Some("email"))
+val invalidEmail = Json.String("not-an-email")
 
 // With format validation (default)
-val strictOptions = ValidationOptions.formatAssertion
-schema.check(value, strictOptions) // Some(error)
+emailSchema.check(invalidEmail, ValidationOptions.formatAssertion) // Some(error)
 
 // Without format validation (format as annotation only)
-val lenientOptions = ValidationOptions.annotationOnly
-schema.check(value, lenientOptions) // None
+emailSchema.check(invalidEmail, ValidationOptions.annotationOnly)  // None
 ```
 
 ### Error Messages