@zio.dev/zio-blocks 0.0.1 → 0.0.21

package/reference/json.md

@@ -29,7 +29,7 @@ Key design decisions:
 
 ### Using Constructors
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 // Object with named fields
@@ -51,7 +51,7 @@ val nothing = Json.Null
 
 ### Parsing JSON Strings
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.SchemaError
 
@@ -66,7 +66,7 @@ val json = Json.parseUnsafe("""{"items": [1, 2, 3]}""")
 
 ZIO Blocks provides compile-time validated string interpolators for JSON:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -91,7 +91,7 @@ The `json"..."` interpolator validates JSON syntax at compile time, catching err
 The `Json` type provides unified methods for type testing and narrowing with path-dependent return types.
 `JsonType` also implements `Json => Boolean`, so it can be used directly as a predicate for filtering.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonType}
 
 val json: Json = Json.parseUnsafe("""{"count": 42}""")
@@ -117,7 +117,7 @@ val strings = json.select.query(JsonType.String)  // all string values in the JS
 
 ### Direct Value Access
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val obj = Json.Object("a" -> Json.Number(1))
@@ -133,7 +133,7 @@ arr.elements  // Chunk(Json.Number(1), Json.Number(2))
 
 Navigate into objects by key and arrays by index:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.SchemaError
 
@@ -161,7 +161,7 @@ val name: Either[SchemaError, String] = firstName.as[String]  // Right("Alice")
 
 Use `DynamicOptic` paths for complex navigation:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -186,7 +186,7 @@ val sameName = json.get("company").get("employees")(0).get("name").as[String]
 
 `JsonSelection` is a fluent wrapper for navigation results, enabling composable chaining:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonSelection}
 
 val json = Json.parseUnsafe("""{"users": [{"name": "Alice"}]}""")
@@ -208,7 +208,7 @@ result.isFailure   // false
 
 ### Terminal Operations
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonSelection}
 import zio.blocks.schema.SchemaError
 
@@ -222,8 +222,8 @@ val anyValue: Either[SchemaError, Json] = selection.any
 val allValues: Either[SchemaError, Json] = selection.all
 
 // Get underlying result
-val underlying: Either[SchemaError, Vector[Json]] = selection.either
-val asVector: Vector[Json] = selection.toVector  // empty on error
+val underlying: Option[zio.blocks.chunk.Chunk[Json]] = selection.values
+val asChunk: zio.blocks.chunk.Chunk[Json] = selection.toChunk  // empty on error
 
 // Decode to specific types
 val asString: Either[SchemaError, String] = selection.as[String]
@@ -238,7 +238,7 @@ val asDouble: Either[SchemaError, Double] = selection.as[Double]
 
 ### Setting Values
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -255,7 +255,7 @@ val result = json.setOrFail(p".user.email", Json.String("alice@example.com"))
 
 ### Modifying Values
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -277,7 +277,7 @@ val result = json.modifyOrFail(p".count") {
 
 ### Deleting Values
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -294,7 +294,7 @@ val result = json.deleteOrFail(p".missing")
 
 ### Inserting Values
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -311,7 +311,7 @@ val withNew = json.insert(p".newField", Json.String("value"))
 
 Transform children before parents:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.DynamicOptic
 
@@ -331,7 +331,7 @@ val doubled = json.transformUp { (path, value) =>
 
 Transform parents before children:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.DynamicOptic
 
@@ -351,7 +351,7 @@ val withId = json.transformDown { (path, value) =>
 
 Rename object keys throughout the structure:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.parseUnsafe("""{"user_name": "Alice", "user_age": 30}""")
@@ -372,7 +372,7 @@ val camelCase = json.transformKeys { (path, key) =>
 
 Keep only values matching a predicate using `retain`, or remove values using `prune`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonType}
 
 val json = Json.parseUnsafe("""{"a": 1, "b": null, "c": 2, "d": null}""")
@@ -390,7 +390,7 @@ val onlyNumbers = json.retain(_.is(JsonType.Number))
 
 Extract only specific paths:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.json._
 
@@ -408,7 +408,7 @@ val projected = json.project(p".user.name", p".user.email")
 
 Split based on a predicate:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonType}
 
 val json = Json.parseUnsafe("""{"a": 1, "b": "text", "c": 2}""")
@@ -425,7 +425,7 @@ val (numbers, nonNumbers) = json.partition(_.is(JsonType.Number))
 
 Accumulate values from children to parents:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.parseUnsafe("""{"values": [1, 2, 3, 4, 5]}""")
@@ -433,7 +433,7 @@ val json = Json.parseUnsafe("""{"values": [1, 2, 3, 4, 5]}""")
 // Sum all numbers
 val sum = json.foldUp(BigDecimal(0)) { (path, value, acc) =>
   value match {
-    case n: Json.Number => acc + n.toBigDecimal
+    case n: Json.Number => acc + n.value
     case _ => acc
   }
 }
@@ -444,7 +444,7 @@ val sum = json.foldUp(BigDecimal(0)) { (path, value, acc) =>
 
 Accumulate values from parents to children:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.DynamicOptic
 
@@ -460,7 +460,7 @@ val paths = json.foldDown(Vector.empty[DynamicOptic]) { (path, value, acc) =>
 
 Combine two JSON values using different strategies:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, MergeStrategy}
 
 val base = Json.parseUnsafe("""{"a": 1, "b": {"x": 10}}""")
@@ -502,7 +502,7 @@ val custom = base.merge(overlay, MergeStrategy.Custom { (path, left, right) =>
 
 Clean up JSON values:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.parseUnsafe("""{
@@ -535,7 +535,7 @@ val normalized = json.normalize
 
 ZIO Blocks provides `JsonEncoder` and `JsonDecoder` type classes for converting between Scala types and `Json`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonEncoder, JsonDecoder}
 
 // Encode Scala values to Json
@@ -549,7 +549,7 @@ val strResult = JsonDecoder[String].decode(Json.String("hello"))  // Right("hell
 
 ### Built-in Encoders/Decoders
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{JsonEncoder, JsonDecoder}
 
 // Primitives
@@ -577,7 +577,7 @@ JsonEncoder[java.util.UUID]
 
 For complex types, use Schema-based derivation:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.Schema
 import zio.blocks.schema.json.{Json, JsonEncoder, JsonDecoder}
 
@@ -600,7 +600,7 @@ val decoded = JsonDecoder[Person].decode(json)
 
 When a `Schema` is in scope, you can use convenient extension methods directly on values:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 
 case class Person(name: String, age: Int)
@@ -630,7 +630,7 @@ These extension methods provide a more ergonomic API compared to explicitly crea
 
 ### Using the `as` Method
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.json.JsonDecoder
 import zio.blocks.schema.{Schema, SchemaError}
@@ -654,7 +654,7 @@ val personUnsafe: Person = json.asUnsafe[Person]
 
 ### Basic Printing
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.Object("name" -> Json.String("Alice"), "age" -> Json.Number(30))
@@ -666,7 +666,7 @@ val compact: String = json.print
 
 ### With Writer Config
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.json.WriterConfig
 
@@ -692,7 +692,7 @@ val indented4 = json.print(WriterConfig.withIndentionStep(4))
 | `escapeUnicode` | `false` | Escape non-ASCII characters as `\uXXXX` |
 | `preferredBufSize` | `32768` | Internal buffer size in bytes |
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.WriterConfig
 
 // Compact output (default)
@@ -723,7 +723,7 @@ val custom = WriterConfig
 | `maxCharBufSize` | `4194304` | Maximum char buffer size (4MB) |
 | `checkForEndOfInput` | `true` | Error on trailing non-whitespace |
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.ReaderConfig
 
 // Default configuration
@@ -740,7 +740,7 @@ val largeDoc = ReaderConfig
 
 ### To Bytes
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.Object("x" -> Json.Number(1))
@@ -755,7 +755,7 @@ val bytes: Array[Byte] = json.printBytes
 
 Find all values matching a condition:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val json = Json.parseUnsafe("""{
@@ -776,7 +776,7 @@ val activeUsers = json.select.queryBoth { (path, value) =>
 
 Flatten to path-value pairs:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.DynamicOptic
 import zio.blocks.chunk.Chunk
@@ -796,7 +796,7 @@ val pairs: Chunk[(DynamicOptic, Json)] = json.toKV
 
 Objects are compared **order-independently** (keys are compared as sorted sets):
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val obj1 = Json.parseUnsafe("""{"a": 1, "b": 2}""")
@@ -809,7 +809,7 @@ obj1 == obj2  // true (order-independent)
 
 JSON values have a total ordering for sorting:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 
 val values = List(
@@ -830,7 +830,7 @@ Type ordering: Null < Boolean < Number < String < Array < Object
 
 `JsonDiffer` computes the difference between two JSON values, producing a `JsonPatch` that transforms the source into the target:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonPatch}
 
 val source = Json.parseUnsafe("""{"name": "Alice", "age": 30}""")
@@ -856,7 +856,7 @@ The differ uses optimal operations:
 
 ### Computing and Applying Patches
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonPatch}
 import zio.blocks.schema.patch.PatchMode
 import zio.blocks.schema.SchemaError
@@ -887,7 +887,7 @@ val result3 = patch(original, PatchMode.Clobber)
 
 ### Composing Patches
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.{Json, JsonPatch}
 
 val patch1 = JsonPatch.diff(
@@ -912,7 +912,7 @@ val result = combined(Json.parseUnsafe("""{"x": 1}"""))
 
 `JsonPatch` can be converted to and from `DynamicPatch` for interoperability with the typed patching system:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.JsonPatch
 import zio.blocks.schema.patch.DynamicPatch
 import zio.blocks.schema.SchemaError
@@ -930,7 +930,7 @@ val restored: Either[SchemaError, JsonPatch] = JsonPatch.fromDynamicPatch(dynami
 
 Convert JSON to ZIO Blocks' semi-structured `DynamicValue`:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.DynamicValue
 
@@ -947,7 +947,7 @@ This enables interoperability with other ZIO Blocks formats (Avro, TOON, etc.).
 
 Errors include path information for debugging:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.json.Json
 import zio.blocks.schema.SchemaError
 
@@ -959,7 +959,7 @@ val result = json.get("users")(5).get("name").as[String]
 
 ### Error Properties
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.SchemaError
 import zio.blocks.schema.DynamicOptic