@zio.dev/zio-blocks 0.0.29 → 0.0.30

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-di → resource-management}/index.md

@@ -7,20 +7,15 @@ title: "Resource Management & Dependency Injection"
 
 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.
 
-**Related Types:**
-- [`Resource`](./resource.md) — Lazy recipe for managing resource lifecycles with automatic cleanup
-- [`Scope`](./scope.md) — Compile-time safe resource management and scoped value access
-- [`Wire`](./wire.md) — Type-safe recipes for constructing services and their dependencies
-
 ## Overview
 
 These three types solve the fundamental problem of managing resources and dependencies in concurrent, long-lived applications:
 
-**Scope** 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.
+**[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** 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.
+**[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** 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.
+**[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