@zio.dev/zio-blocks 0.0.27 → 0.0.29

package/reference/json.md

@@ -828,7 +828,7 @@ Type ordering: Null < Boolean < Number < String < Array < Object
 
 ## JSON Diffing
 
-`JsonDiffer` computes the difference between two JSON values, producing a `JsonPatch` that transforms the source into the target:
+`JsonDiffer` computes the difference between two JSON values, producing a [`JsonPatch`](./json-patch.md) that transforms the source into the target:
 
 ```scala
 import zio.blocks.schema.json.{Json, JsonPatch}

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.27"
+libraryDependencies += "dev.zio" %% "zio-blocks-mediatype" % "0.0.29"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.27"
+libraryDependencies += "dev.zio" %%% "zio-blocks-mediatype" % "0.0.29"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/patch.md

@@ -15,6 +15,10 @@ A `Patch[S]` represents a sequence of operations that transform a value of type
 - **Optimistic Updates** — Apply patches locally while syncing with a server
 - **Schema Evolution** — Patches work with the schema system, adapting as data structures evolve
 
+:::note
+For **untyped JSON patching** without a schema, use [`JsonPatch`](./json-patch.md) instead. `JsonPatch` is optimized for diff-and-apply workflows on raw JSON values and provides compact delta representations without requiring typed optics.
+:::
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.patch._

package/reference/resource-management-di/index.md

@@ -0,0 +1,49 @@
+---
+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.
+
+**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.
+
+**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.
+
+**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.
+
+### 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