@zio.dev/zio-blocks 0.0.28 → 0.0.30

package/reference/json-differ.md

@@ -0,0 +1,320 @@
+---
+id: json-differ
+title: "JsonDiffer"
+---
+
+`JsonDiffer` is a **diff algorithm for JSON values** that computes the minimal [`JsonPatch`](./json-patch.md) transforming one `Json` value into another. It is the foundation of `JsonPatch.diff`.
+
+```scala
+object JsonDiffer {
+  def diff(source: Json, target: Json): JsonPatch
+}
+```
+
+## Overview
+
+`JsonDiffer` solves a fundamental problem: given two `Json` values, what is the most compact representation of the changes from one to the other?
+
+Instead of transmitting or storing the entire new value, `JsonDiffer` emits a `JsonPatch` containing only the differences. For each type of change — numeric updates, string mutations, array reordering, field additions — it selects the most space-efficient representation:
+
+```
+Original JSON              Target JSON
+┌──────────────────┐      ┌──────────────────┐
+│ {                │      │ {                │
+│   "name": "Alice"│      │   "name": "Alice"│
+│   "age": 25      │─────→│   "age": 26      │
+│   "city": "NYC"  │ diff │   "city": "NYC"  │
+│ }                │      │ }                │
+└──────────────────┘      └──────────────────┘
+        │
+        ▼
+   JsonPatch {
+     ObjectEdit(
+       Modify("age", NumberDelta(1))
+     )
+   }
+```
+
+The core guarantee: `JsonDiffer.diff(source, target).apply(source) == Right(target)` always holds.
+
+## Motivation
+
+Transmitting or storing entire JSON documents wastes bandwidth, disk space, and network latency when only a fraction of the data changes. `JsonDiffer` enables:
+
+- **Efficient data synchronization** — send only what changed, not the entire document
+- **Change tracking and audit logs** — record every mutation as a first-class value
+- **Optimistic concurrency control** — detect conflicts by analyzing patches rather than full documents
+- **Replay and time-travel debugging** — reconstruct any historical state by applying patches in sequence
+- **Compression** — patches are often 10–100× smaller than the full target value
+
+## The Diffing Algorithm
+
+`JsonDiffer.diff` adapts its strategy per `Json` type, choosing the most compact representation for each kind of change.
+
+### Type Mismatches
+
+When the types differ (e.g., number to string, object to array), `JsonDiffer` emits `Op.Set` to replace the value entirely. This is the only compact choice when the types diverge:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+val numberToString = JsonDiffer.diff(Json.Number(42), Json.String("hello"))
+val objectToArray  = JsonDiffer.diff(
+  Json.Object("x" -> Json.Number(1)),
+  Json.Array(Json.Number(1), Json.Number(2))
+)
+```
+
+Both patches consist of a single `Set` operation:
+
+```scala
+import zio.blocks.schema.json.JsonPatch
+
+numberToString.apply(Json.Number(42))
+objectToArray.apply(Json.Object("x" -> Json.Number(1)))
+```
+
+### Numbers
+
+For numeric changes, `JsonDiffer` emits `NumberDelta` — representing the difference between old and new values as a delta rather than replacing the entire number:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+val increment = JsonDiffer.diff(Json.Number(100), Json.Number(105))
+val decrement = JsonDiffer.diff(Json.Number(50), Json.Number(48))
+```
+
+The patches store deltas, not full new values:
+
+```scala
+import zio.blocks.schema.json.JsonPatch
+
+increment.apply(Json.Number(100))
+decrement.apply(Json.Number(50))
+```
+
+### Strings
+
+For strings, `JsonDiffer` chooses between two strategies:
+
+1. **LCS (Longest Common Subsequence) edit operations** — if the edits are more compact than the full new string.
+2. **Full replacement with `Set`** — if the string has changed so much that storing the entire new value is smaller.
+
+The algorithm computes common characters, then emits `Insert` and `Delete` operations (with `Append` and `Modify` existing as supported patch ops but not currently produced by `JsonDiffer`). It only emits the edits if their byte size is smaller than the new string's length:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+// Prefix insertion — common suffix preserved
+val addPrefix = JsonDiffer.diff(Json.String("world"), Json.String("hello world"))
+
+// Complete replacement — almost no common subsequence
+val replacement = JsonDiffer.diff(Json.String("abc"), Json.String("xyz"))
+```
+
+The first patch uses `StringEdit` (compact), the second uses `Set` (more efficient):
+
+```scala
+addPrefix.apply(Json.String("world"))
+replacement.apply(Json.String("abc"))
+```
+
+### Arrays
+
+For arrays, `JsonDiffer` uses **LCS-aligned insert, delete, and append operations** to transform the old array into the new one. It aligns common elements and generates the minimum sequence of mutations:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+// Append elements at the end
+val append = JsonDiffer.diff(
+  Json.Array(Json.Number(1), Json.Number(2)),
+  Json.Array(Json.Number(1), Json.Number(2), Json.Number(3))
+)
+
+// Delete and reorder — LCS finds the common elements
+val reorder = JsonDiffer.diff(
+  Json.Array(Json.Number(1), Json.Number(2), Json.Number(3)),
+  Json.Array(Json.Number(3), Json.Number(2), Json.Number(1))
+)
+```
+
+Both patches use efficient `ArrayEdit` operations:
+
+```scala
+append.apply(Json.Array(Json.Number(1), Json.Number(2)))
+reorder.apply(Json.Array(Json.Number(1), Json.Number(2), Json.Number(3)))
+```
+
+### Objects
+
+For objects, `JsonDiffer` compares field-by-field:
+
+- Fields in the target but not in the source become `Add` operations.
+- Fields in the source but not in the target become `Remove` operations.
+- Fields in both are recursively diffed — if the values differ, a `Modify` with a sub-patch is emitted.
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+val original = Json.Object(
+  "name" -> Json.String("Alice"),
+  "age"  -> Json.Number(25),
+  "city" -> Json.String("NYC")
+)
+
+val updated = Json.Object(
+  "name"  -> Json.String("Alice"),
+  "age"   -> Json.Number(26),
+  "email" -> Json.String("alice@example.com")
+)
+
+val patch = JsonDiffer.diff(original, updated)
+```
+
+The patch contains `Add`, `Remove`, and `Modify` operations:
+
+```scala
+patch.apply(original)
+```
+
+### Nested Structures
+
+`JsonDiffer` handles deeply nested objects and arrays recursively. Each field or element is diffed independently, producing compact patches at every level:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+val original = Json.Object(
+  "user" -> Json.Object(
+    "name" -> Json.String("Alice"),
+    "scores" -> Json.Array(Json.Number(95), Json.Number(87))
+  )
+)
+
+val updated = Json.Object(
+  "user" -> Json.Object(
+    "name" -> Json.String("Alice"),
+    "scores" -> Json.Array(Json.Number(95), Json.Number(88), Json.Number(92))
+  )
+)
+
+val patch = JsonDiffer.diff(original, updated)
+```
+
+The patch navigates to the nested array and emits only the array changes:
+
+```scala
+patch.apply(original)
+```
+
+## Core Operations
+
+`JsonDiffer` exposes a single public operation: `diff`, which computes the minimal `JsonPatch` that transforms `source` into `target`. Returns an empty patch if the values are already equal:
+
+```scala
+object JsonDiffer {
+  def diff(source: Json, target: Json): JsonPatch
+}
+```
+
+The roundtrip property always holds — applying the patch to the source always yields the target:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer}
+
+val source = Json.Object("x" -> Json.Number(10), "y" -> Json.Number(20))
+val target = Json.Object("x" -> Json.Number(10), "y" -> Json.Number(21))
+val patch  = JsonDiffer.diff(source, target)
+```
+
+```scala
+patch.apply(source) == Right(target)
+// res13: Boolean = true
+```
+
+`JsonDiffer.diff` is also available as `JsonPatch.diff` and as the `Json#diff` extension method:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonPatch}
+
+// Via JsonPatch companion
+val p1 = JsonPatch.diff(Json.Number(1), Json.Number(2))
+
+// Via Json extension method
+val p2 = Json.Number(1).diff(Json.Number(2))
+```
+
+## Integration
+
+`JsonDiffer` is the implementation behind the public `JsonPatch.diff` API. You typically interact with it through `JsonPatch.diff` or the `Json#diff` extension method rather than calling `JsonDiffer.diff` directly.
+
+The relationship is simple: `JsonPatch.diff` delegates to `JsonDiffer.diff` and wraps the result in a `JsonPatch` for further composition and application.
+
+Once you have a `JsonPatch` from `JsonDiffer`, use the full `JsonPatch` API to apply it with different modes, compose multiple patches, or convert to/from `DynamicPatch`:
+
+```scala
+import zio.blocks.schema.json.{Json, JsonDiffer, JsonPatch}
+import zio.blocks.schema.patch.PatchMode
+
+val source = Json.Object("count" -> Json.Number(0))
+val target = Json.Object("count" -> Json.Number(1))
+val patch  = JsonDiffer.diff(source, target)
+```
+
+Apply with different failure-handling modes:
+
+```scala
+patch.apply(source, PatchMode.Strict)
+patch.apply(source, PatchMode.Lenient)
+patch.apply(source, PatchMode.Clobber)
+```
+
+Compose patches with `++`:
+
+```scala
+val patch2 = JsonDiffer.diff(target, Json.Object("count" -> Json.Number(2)))
+val combined = patch ++ patch2
+```
+
+## Implementation Notes
+
+`JsonDiffer.diff` uses the LCS (Longest Common Subsequence) algorithm for both strings and arrays, ensuring that the number of edit operations is minimized. For strings, it compares character sequences; for arrays, it compares JSON elements by structural equality.
+
+The LCS-based approach is particularly effective for arrays and strings with significant common subsequences — a common pattern in real-world data mutation scenarios (e.g., adding an item to a list, inserting a few characters into a string).
+
+:::note
+The LCS algorithm has O(n·m) time complexity, where n and m are the lengths of the two sequences. For very large strings or arrays, consider whether you need the minimal patch or can accept a faster approximation.
+:::
+
+## Running the Examples
+
+`JsonDiffer` is the foundation of the `JsonPatch` API. Runnable examples demonstrating `JsonPatch.diff` (which internally uses `JsonDiffer`) are available in the `schema-examples` module.
+
+**1. Clone the repository and navigate to the project:**
+
+```bash
+git clone https://github.com/zio/zio-blocks.git
+cd zio-blocks
+```
+
+**2. Run JsonPatch examples with sbt:**
+
+These examples demonstrate how `JsonDiffer.diff` computes minimal patches through the public `JsonPatch.diff` API:
+
+```bash
+sbt "schema-examples/runMain jsonpatch.JsonPatchDiffAndApplyExample"
+```
+
+```bash
+sbt "schema-examples/runMain jsonpatch.JsonPatchOperationsExample"
+```
+
+```bash
+sbt "schema-examples/runMain jsonpatch.JsonPatchCompositionExample"
+```
+
+```bash
+sbt "schema-examples/runMain jsonpatch.CompleteJsonPatchExample"
+```

package/reference/json-patch.md

@@ -640,7 +640,7 @@ You rarely need to construct `Nested` manually; it is primarily an internal opti
 
 ## Diffing Algorithm
 
-`JsonPatch.diff` (and its alias `Json#diff`) delegate to `JsonDiffer.diff`, which selects the most compact representation for each type of change:
+`JsonPatch.diff` (and its alias `Json#diff`) delegate to [`JsonDiffer.diff`](./json-differ.md), which selects the most compact representation for each type of change:
 
 | Value type | Change | Strategy |
 |------------|--------|----------|

package/reference/media-type.md

@@ -75,13 +75,13 @@ textAny.matches(html) // true
 Add the following to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.30"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.28"
+libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.30"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/resource-management/defer-handle.md

@@ -0,0 +1,246 @@
+---
+id: defer-handle
+title: "DeferHandle"
+---
+
+`DeferHandle` is a handle returned by `Scope.defer` that allows cancelling a registered finalizer before the scope closes:
+
+```scala
+abstract class DeferHandle {
+  def cancel(): Unit
+}
+```
+
+When `Scope#defer(cleanup)` is called, the cleanup action is registered and a `DeferHandle` is returned. This handle can be used to remove that finalizer early, preventing it from running when the scope closes. This is useful when a resource is explicitly released before the scope ends, and running the finalizer again would be unnecessary or harmful.
+
+## Construction
+
+`DeferHandle` is not instantiated directly. Instead, it is created by calling `Scope#defer` with a cleanup action:
+
+```scala
+import zio.blocks.scope.{Scope, DeferHandle}
+
+trait Scope {
+  def defer(cleanup: => Unit): DeferHandle
+}
+```
+
+The following example demonstrates creating a `DeferHandle`:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = defer {
+    println("This cleanup will run when scope closes, unless cancelled")
+  }
+
+  // The handle can now be used to cancel the cleanup
+  handle.cancel()
+}
+```
+
+## Core Operations
+
+The `DeferHandle#cancel` method removes the registered finalizer so it will not run when the scope closes:
+
+```scala
+trait DeferHandle {
+  def cancel(): Unit
+}
+```
+
+This method is:
+
+- **Thread-safe**: Can be called from any thread without synchronization
+- **Idempotent**: Calling it multiple times has the same effect as calling once
+
+If the scope has already closed (and the finalizer has already run or been discarded), calling `DeferHandle#cancel` is a no-op. In the following example, we register a cleanup action, then cancel it before the scope closes:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayOutputStream
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val buffer = allocate(ByteArrayOutputStream())
+  val closeHandle = defer {
+    println("Auto-closing buffer")
+    $(buffer)(_.close())
+  }
+
+  // Manually close the buffer
+  $(buffer)(_.close())
+
+  // Cancel the automatic finalizer since we already closed it
+  closeHandle.cancel()
+}
+```
+
+## Use Cases
+
+`DeferHandle` is useful in several common scenarios:
+
+### Preventing Duplicate Cleanup
+
+When a resource is explicitly released before the scope ends, cancel the automatic finalizer to avoid duplicate cleanup:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayOutputStream
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val buffer = allocate(ByteArrayOutputStream())
+
+  val finalizeHandle = defer {
+    println(s"Finalizer running, buffer closing")
+    $(buffer)(_.close())
+  }
+
+  // Explicit cleanup
+  $(buffer) { buf =>
+    buf.write("data".getBytes)
+    println(s"Manual use: buffer has ${buf.size()} bytes")
+    buf.close()
+  }
+
+  // Cancel the automatic finalizer
+  finalizeHandle.cancel()
+  
+  "done"
+}
+```
+
+### Conditional Cleanup
+
+Cancel finalizers based on runtime conditions:
+
+```scala
+import zio.blocks.scope.Scope
+
+def acquireResource(shouldCleanup: Boolean) = Scope.global.scoped { scope =>
+  import scope._
+
+  val resource = "important resource"
+  val handle = scope.defer {
+    println("Cleaning up resource")
+  }
+
+  if (!shouldCleanup) {
+    handle.cancel()
+    println("Cleanup disabled")
+  }
+
+  resource
+}
+
+acquireResource(shouldCleanup = false)
+acquireResource(shouldCleanup = true)
+```
+
+### Transferring Ownership
+
+When transferring a resource to external management, cancel its finalizer so the external system can control cleanup:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayInputStream
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val stream = allocate(ByteArrayInputStream("data".getBytes))
+  val handle = defer {
+    println("Scope finalizer would close stream")
+    $(stream)(_.close())
+  }
+
+  // Transfer ownership to external manager
+  // (In real code, this might pass to a thread pool or async framework)
+  handle.cancel()  // Let the manager handle cleanup
+  
+  "transferred"
+}
+```
+
+## Noop Handle
+
+When `defer()` is called on an already-closed scope, a no-op handle is returned:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = scope.defer {
+    println("This will run when scope closes")
+  }
+
+  // Subsequent calls to cancel() remove the finalizer
+  handle.cancel()
+
+  println("Finalizer has been cancelled")
+}
+```
+
+## Thread Safety
+
+`DeferHandle` is thread-safe. Multiple threads can call `cancel()` on the same handle without external synchronization:
+
+```scala
+import zio.blocks.scope.Scope
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = defer {
+    println("Finalizer")
+  }
+
+  // Use a thread pool to simulate concurrent access
+  val executor = Executors.newFixedThreadPool(5)
+  val latch = new CountDownLatch(5)
+
+  (1 to 5).foreach { i =>
+    executor.submit(new Runnable {
+      def run(): Unit = {
+        handle.cancel()
+        println(s"Thread $i cancelled")
+        latch.countDown()
+      }
+    })
+  }
+
+  // Wait for all threads to finish
+  latch.await()
+  executor.shutdown()
+  
+  "completed"
+}
+```
+
+## See Also
+
+- [`Scope#defer`](./scope.md#registering-finalizers) — the method that returns a `DeferHandle`
+- [`Finalizer`](./finalizer.md) — the trait defining `Finalizer#defer`
+- [`Finalization`](./finalization.md) — the result of running all finalizers
+
+## Integration
+
+`DeferHandle` is part of ZIO Blocks' resource management system. It works directly with:
+
+- **[`Scope`](./scope.md)** — The primary way to create a `DeferHandle` is via `Scope#defer`. A scope manages multiple finalizers and runs them all when the scope closes. `DeferHandle` allows selective cancellation of individual finalizers before that happens.
+
+- **[`Finalizer`](./finalizer.md)** — `Finalizer` defines the `Finalizer#defer` operation that returns a `DeferHandle`. It abstracts the concept of registering cleanup actions.
+
+- **[`Finalization`](./finalization.md)** — When a scope closes, it runs all registered finalizers. A cancelled `DeferHandle` removes its associated finalizer from this process.
+
+Together, these types form the foundation of compile-time resource safety in ZIO Blocks, allowing you to manage resource lifecycles with certainty that cleanup will occur exactly when needed.