@zio.dev/zio-blocks 0.0.28 → 0.0.30

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

package/reference/resource-management/finalizer.md

@@ -0,0 +1,167 @@
+---
+id: finalizer
+title: "Finalizer"
+---
+
+`Finalizer` is a minimal capability interface for registering cleanup actions. It exposes only the `Finalizer#defer` method, preventing code from accessing scope internals like resource allocation or closing.
+
+The structural definition:
+
+```scala
+trait Finalizer {
+  def defer(f: => Unit): DeferHandle
+}
+```
+
+This trait serves as a boundary between scope management internals and user code that only needs to register cleanup actions. By exposing only `defer`, code can safely request cleanup registration without requiring full scope access.
+
+## Motivation / Use Case
+
+`Finalizer` integrates with `Scope` to enable resource management patterns:
+
+```scala
+import zio.blocks.scope.{Scope, Finalizer}
+
+def openConnection(url: String)(implicit fin: Finalizer): String = {
+  fin.defer {
+    println(s"Closing connection to $url")
+  }
+  s"Connected to $url"
+}
+
+Scope.global.scoped { scope =>
+  import scope._
+  openConnection("https://example.com")
+  // Connection closes when scope exits
+  ()
+}
+```
+
+By decoupling code that needs cleanup registration from code that manages the complete scope lifecycle, `Finalizer` allows functions to safely register finalizers without requiring full scope access.
+
+## Construction / Creating Instances
+
+`Finalizer` is not typically constructed directly. Instead, it is obtained through a scope:
+
+### From a `Scope`
+
+Any `Scope` instance can be used as a `Finalizer` since `Scope extends Finalizer`:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+  // scope is both a Scope and a Finalizer
+  val handle = scope.defer {
+    println("Cleanup")
+  }
+  ()  // Return unit
+}
+```
+
+### As a Context Bound
+
+Functions can request a `Finalizer` via `implicit` parameter, enabling decoupled cleanup registration:
+
+```scala
+import zio.blocks.scope.Finalizer
+
+def setupResource(name: String)(implicit fin: Finalizer): String = {
+  fin.defer {
+    println(s"Closing $name")
+  }
+  name
+}
+```
+
+## Core Operations
+
+The `Finalizer` interface provides a single core operation for registering cleanup handlers:
+
+### `Finalizer#defer`
+
+Registers a finalizer (cleanup action) to run when the scope closes. The cleanup action runs in LIFO order along with other finalizers registered on the same scope. Returns a `DeferHandle` that can cancel the registration before the scope closes:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle1 = scope.defer {
+    println("Cleanup 1")
+  }
+
+  val handle2 = scope.defer {
+    println("Cleanup 2")
+  }
+
+  // Finalizers run in LIFO: Cleanup 2, then Cleanup 1
+  // Can cancel before scope closes
+  handle1.cancel()
+  // Now only Cleanup 2 runs
+}
+```
+
+### Package-Level `defer` Helper
+
+A package-level convenience function allows writing `defer { cleanup }` when a `Finalizer` is in scope. The signature is:
+
+```scala
+def defer(finalizer: => Unit)(implicit fin: Finalizer): DeferHandle
+```
+
+This removes the need to write `fin.defer { cleanup }`. Here's the convenience function in use:
+
+```scala
+import zio.blocks.scope.{Scope, defer, Finalizer}
+
+def setupWithCleanup()(implicit fin: Finalizer) = {
+  defer {
+    println("Cleanup")
+  }
+}
+
+Scope.global.scoped { scope =>
+  import scope._
+  setupWithCleanup()
+  // Cleanup prints when scope closes
+  ()  // Return unit (which is Unscoped)
+}
+```
+
+## Integration
+
+`Finalizer` is a supertrait of `Scope`. The structural definition shows this relationship:
+
+```scala
+sealed abstract class Scope extends Finalizer with ScopeVersionSpecific
+```
+
+This means any `Scope` instance can be used where a `Finalizer` is expected. However, the converse is not true—a `Finalizer` reference does not provide `Scope#allocate`, `Scope#$`, or other scope operations.
+
+## Finalization Order
+
+Finalizers registered with `Finalizer#defer` run in **LIFO order** (last registered runs first) when the scope closes. This ensures that resources acquired in order can be cleaned up in reverse order:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  scope.defer { println("First registered, runs last") }
+  scope.defer { println("Second registered, runs first") }
+  // Output on scope close:
+  // Second registered, runs first
+  // First registered, runs last
+  ()  // Return unit (which is Unscoped)
+}
+```
+
+## See Also
+
+- [`Scope`](./scope.md) — the full scope lifecycle management
+- [`DeferHandle`](./defer-handle.md) — the handle returned by `Finalizer#defer` for cancellation
+- [`Finalization`](./finalization.md) — the result of running all finalizers

package/reference/resource-management/index.md

@@ -0,0 +1,44 @@
+---
+id: index
+title: "Resource Management & Dependency Injection"
+---
+
+## Introduction
+
+Resource management and dependency injection are fundamental to building reliable, maintainable applications. ZIO Blocks provides three complementary types that work together to eliminate common lifetime bugs while enabling powerful composition patterns: **Scope** provides compile-time safe resource boundaries, **Resource** encapsulates acquisition and cleanup with automatic finalization, and **Wire** describes dependency graphs with type-safe construction recipes. Together, they form a cohesive system for managing object lifecycles, preventing resource leaks, and building dependency-injected architectures.
+
+## Overview
+
+These three types solve the fundamental problem of managing resources and dependencies in concurrent, long-lived applications:
+
+**[Scope](./scope.md)** is the foundation — it provides a compile-time safe boundary that prevents resources from escaping their intended lifetime. Using path-dependent types, Scope ensures that values allocated in one scope cannot accidentally be used in another scope, catching lifetime violations at compile time rather than causing runtime bugs.
+
+**[Resource](./resource.md)** builds on Scope to describe how to acquire and finalize resources. Rather than executing immediately, a Resource is a lazy recipe that composes naturally with `map`, `flatMap`, and `zip`. When allocated within a scope, finalizers run automatically in LIFO order, ensuring cleanup happens even when errors occur.
+
+**[Wire](./wire.md)** brings it all together by describing how to construct services and their dependencies. The Wire macro automatically handles dependency resolution, cycle detection, and AutoCloseable registration, letting you declaratively specify a dependency graph that the compiler validates.
+
+### How They Work Together
+
+The typical flow is:
+
+1. **Define** dependencies using `Wire.shared[T]` or `Wire.unique[T]` — the macro inspects constructor parameters and generates a wire
+2. **Compose** wires together using `Resource.from[App](wire1, wire2, ...)` — builds the dependency graph
+3. **Allocate** within a scope using `scope.allocate(resource)` — acquires resources and registers finalizers
+4. **Use** scoped values via the `$` accessor — compile-time ensures they can't escape
+5. **Cleanup** happens automatically when the scope exits — finalizers run in reverse order (LIFO)
+
+### Common Patterns
+
+**Shared Singletons** — Use `Wire.shared[T]` for expensive resources (database connections, thread pools) that should be created once and reused across the application.
+
+**Per-Request Instances** — Use `Wire.unique[T]` for request-scoped state that should be fresh for each request or operation.
+
+**Manual Construction** — Use `Wire.Shared.fromFunction` or `Wire.Unique.fromFunction` when macro derivation doesn't fit your use case (custom initialization logic, special parameters).
+
+**Resource Composition** — Use `Resource.map`, `Resource.flatMap`, and `Resource.zip` to build complex dependency chains where later resources depend on earlier ones.
+
+### Integration Points
+
+- **Wire** uses **Resource** to manage lifecycles of constructed services
+- **Resource** uses **Scope** for finalization and scoped value boundaries
+- Both **Wire** and **Resource** produce values that are usable only within a **Scope** context