@zio.dev/zio-blocks 0.0.29 → 0.0.30

package/reference/codec.md

@@ -48,23 +48,23 @@ val result: Either[SchemaError, Person] = Person.codec.decode(bytes)
 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.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 ```
 
 Additional format modules are separate artifacts:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.29"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.29"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.29"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.29"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.30"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.29"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.30"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/context.md

@@ -116,7 +116,7 @@ val config = ctx.get[Config]  // Compile-time proof it exists
 Add the ZIO Blocks Context module to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.30"
 ```
 
 ## Construction

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

package/reference/dynamic-schema.md

@@ -82,48 +82,45 @@ dynamic
 //         name = "name",
 //         value = Primitive(
 //           primitiveType = String(None),
-//           typeId = Impl(
-//             name = "String",
-//             owner = Owner(List(Package("java"), Package("lang"))),
-//             typeParams = List(),
-//             typeArgs = List(),
-//             defKind = Class(
-//               isFinal = true,
-//               isAbstract = false,
-//               isCase = false,
-//               isValue = false,
-//               bases = List(
-//                 Ref(
-//                   Impl(
-//                     name = "CharSequence",
-//                     owner = Owner(List(Package("java"), Package("lang"))),
-//                     typeParams = List(),
-//                     typeArgs = List(),
-//                     defKind = Trait(isSealed = false, bases = List()),
-//                     selfType = None,
-//                     aliasedTo = None,
-//                     representation = None,
-//                     annotations = List()
-//                   )
-//                 ),
-//                 Ref(
-//                   Impl(
-//                     name = "Comparable",
-//                     owner = Owner(List(Package("java"), Package("lang"))),
-//                     typeParams = List(
-//                       TypeParam(
-//                         name = "T",
-//                         index = 0,
-//                         variance = Invariant,
-//                         bounds = TypeBounds(lower = None, upper = None),
-//                         kind = Type
-//                       )
-//                     ),
-//                     typeArgs = List(),
-//                     defKind = Unknown,
-//                     selfType = None,
-//                     aliasedTo = None,
-//                     representation = None,
+//           typeId = String,
+//           primitiveBinding = zio.blocks.schema.binding.NoBinding$$anon$1@5b27ced8,
+//           doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//           modifiers = List(),
+//           storedDefaultValue = None,
+//           storedExamples = List()
+//         ),
+//         doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//         modifiers = List()
+//       ),
+//       Term(
+//         name = "age",
+//         value = Primitive(
+//           primitiveType = Int(None),
+//           typeId = Int,
+//           primitiveBinding = zio.blocks.schema.binding.NoBinding$$anon$1@5b27ced8,
+//           doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//           modifiers = List(),
+//           storedDefaultValue = None,
+//           storedExamples = List()
+//         ),
+//         doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//         modifiers = List()
+//       ),
+//       Term(
+//         name = "address",
+//         value = Record(
+//           fields = Vector(
+//             Term(
+//               name = "street",
+//               value = Primitive(
+//                 primitiveType = String(None),
+//                 typeId = String,
+//                 primitiveBinding = zio.blocks.schema.binding.NoBinding$$anon$1@5b27ced8,
+//                 doc = Doc(blocks = IndexedSeq(), metadata = Map()),
+//                 modifiers = List(),
+//                 storedDefaultValue = None,
+//                 storedExamples = List()
+//               ),
 // ...
 ```
 

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.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.30"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.29"
+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.

package/reference/resource-management/finalization.md

@@ -0,0 +1,286 @@
+---
+id: finalization
+title: "Finalization"
+---
+
+`Finalization` is the result of running all finalizers in a scope, collecting any errors that occurred during cleanup:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def isEmpty: Boolean
+  def nonEmpty: Boolean
+  def orThrow(): Unit
+  def suppress(initial: Throwable): Throwable
+}
+```
+
+When a scope closes, each registered finalizer runs in LIFO order. If any finalizer throws an exception, that error is caught and collected into a `Finalization`. This type ensures that all finalizers run even if some fail, and allows the caller to decide how to handle accumulated errors.
+
+`Finalization` collects errors from finalizers in a `Chunk[Throwable]`. The first error in the chunk corresponds to the head of the chunk (the first finalizer that failed in LIFO execution order).
+
+## Core Methods
+
+The following four methods allow you to inspect and handle errors from finalization:
+
+### `Finalization#isEmpty`
+
+Returns `true` if no finalizer errors were collected:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def isEmpty: Boolean
+}
+```
+
+Here's an example of checking if finalization succeeded:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    import openScope.scope._
+    defer {
+      println("Cleanup")
+    }
+    val fin = openScope.close()
+    if (fin.isEmpty) println("No errors") else println("Errors occurred")
+  }
+}
+```
+
+### `Finalization#nonEmpty`
+
+Returns `true` if at least one finalizer error was collected:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def nonEmpty: Boolean
+}
+```
+
+Here's an example of checking for errors:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    import openScope.scope._
+    defer {
+      throw new Exception("Cleanup failed")
+    }
+    val fin = openScope.close()
+    if (fin.nonEmpty) {
+      println(s"Errors occurred: ${fin.errors.length}")
+    }
+  }
+}
+```
+
+### `Finalization#orThrow()`
+
+Throws the first collected error with all remaining errors added as suppressed exceptions. Does nothing if there are no errors:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def orThrow(): Unit
+}
+```
+
+The first error corresponds to the head of the chunk (the first finalizer that failed in LIFO execution order). Remaining errors are attached as suppressed exceptions using `addSuppressed()`. Here's an example:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+  $(open()) { openScope =>
+    defer { throw Exception("Error 2") }
+    defer { throw Exception("Error 1") }
+    val fin = openScope.close()
+    
+    try {
+      fin.orThrow()
+    } catch {
+      case e: Exception =>
+        println(s"Primary: ${e.getMessage}")
+        e.getSuppressed.foreach(s => println(s"Suppressed: ${s.getMessage}"))
+    }
+  }
+}
+```
+
+### `Finalization#suppress(initial)`
+
+Adds all collected finalizer errors as suppressed exceptions to `initial` and returns it. If there are no errors, `initial` is returned unchanged:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def suppress(initial: Throwable): Throwable
+}
+```
+
+This is useful when you want to preserve the original error context while attaching cleanup errors. Here's an example:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val initialError = Exception("Original error")
+
+  $(open()) { openScope =>
+    defer { throw Exception("Cleanup error") }
+    val fin = openScope.close()
+    
+    val combined = fin.suppress(initialError)
+    println(s"Primary: ${combined.getMessage}")
+    combined.getSuppressed.foreach(s => println(s"Suppressed: ${s.getMessage}"))
+  }
+}
+```
+
+## Error Ordering
+
+Errors in the finalization are ordered by when finalizers ran (in LIFO sequence):
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    // Registered first, runs last (LIFO)
+    defer { throw Exception("Error 1") }
+
+    // Registered second, runs first
+    defer { throw Exception("Error 2") }
+
+    // Registered third, runs first
+    defer { throw Exception("Error 3") }
+
+    val fin = openScope.close()
+    
+    // Errors list order: [Error 3, Error 2, Error 1]
+    println(s"First error: ${fin.errors.head.getMessage}")
+    println(s"Total errors: ${fin.errors.length}")
+  }
+}
+```
+
+## Use Cases
+
+Here are common scenarios where finalization handling is useful:
+
+### Conditional Error Handling
+
+Check if errors occurred and handle them appropriately:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    defer {
+      println("Cleanup complete")
+    }
+    val fin = openScope.close()
+    
+    if (fin.nonEmpty) {
+      fin.orThrow()
+    } else {
+      println("No errors during finalization")
+    }
+  }
+}
+```
+
+### Combining Multiple Error Sources
+
+Attach cleanup errors to an existing error:
+
+```scala
+import zio.blocks.scope.Scope
+
+def doWork(): Unit = {
+  Scope.global.scoped { scope =>
+    import scope._
+
+    try {
+      throw Exception("Work failed")
+    } catch {
+      case workError: Exception =>
+        $(open()) { openScope =>
+          defer { throw Exception("Cleanup failed") }
+          val fin = openScope.close()
+          val combined = fin.suppress(workError)
+          throw combined
+        }
+    }
+    ()  // Return unit on normal path
+  }
+}
+
+try {
+  doWork()
+} catch {
+  case e: Exception =>
+    println(s"Work: ${e.getMessage}")
+    e.getSuppressed.foreach(s => println(s"During cleanup: ${s.getMessage}"))
+}
+```
+
+### Logging All Cleanup Errors
+
+Inspect and log all errors without stopping execution:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    defer { throw Exception("Error 1") }
+    defer { throw Exception("Error 2") }
+    val fin = openScope.close()
+    
+    if (fin.nonEmpty) {
+      println(s"Finalization collected ${fin.errors.length} errors:")
+      fin.errors.foreach(e => println(s"  - ${e.getMessage}"))
+    }
+  }
+}
+```
+
+## Relationship to Scope
+
+`Finalization` is returned by:
+
+- `Scope.open().close()` — when explicitly closing a scope
+- `Scope.global.runFinalizers()` — when running global finalizers on shutdown
+
+## See Also
+
+- [`Scope#defer`](./scope.md) — registers finalizers that produce errors
+- [`DeferHandle`](./defer-handle.md) — handle for cancelling finalizers
+- [`Finalizer`](./finalizer.md) — the trait for registering cleanup actions