@zio.dev/zio-blocks 0.0.29 → 0.0.30

package/reference/resource-management/unscoped.md

@@ -0,0 +1,125 @@
+---
+id: unscoped
+title: "Unscoped"
+---
+
+`Unscoped[A]` is a marker typeclass for types that can safely escape a scope without tracking. Types with an `Unscoped` instance are considered "safe data"—they don't hold resources and can be freely extracted from a scope. Here's the definition:
+
+```scala
+trait Unscoped[A]
+```
+
+The `Unscoped` typeclass distinguishes between two categories of types:
+
+1. **Unscoped types** (have an instance): Primitives, strings, collections, value types, and pure data. These can leave a scope without risk.
+2. **Scoped types** (no instance): Resources like streams, connections, handles. These must remain tracked within a scope.
+
+When the `$` operator is used to access a scoped value, if the result type has an `Unscoped` instance, it returns the value directly (unwrapped). Otherwise, it returns the value still wrapped in `$`.
+
+## Motivation / Use Case
+
+The exact problem: A `scoped` block automatically closes all resources when it exits. If you accidentally returned a resource (like a database connection or file handle) from the block, it would be closed—but you might try to use it later, causing a **use-after-close** crash. Here's an example (this would fail without `Unscoped`):
+
+```scala
+import zio.blocks.scope.{Scope, Resource}
+
+final class Database {
+  def query(sql: String) = s"result: $sql"
+}
+
+// Without Unscoped constraint, this compiles (BAD):
+// val db: Database = Scope.global.scoped { scope =>
+//   val db = allocate(Resource(new Database()))
+//   db  // BUG: returns the resource itself, not data extracted from it
+// }
+// db.query("SELECT 1")  // CRASH: use-after-close (scope already closed it)
+```
+
+The solution: `Unscoped` makes this a **compile error** instead of a runtime bug. When a `scoped` block returns a value, that value's type must have an `Unscoped` instance—meaning the type checker verifies you're only extracting *computed results* (like `Int`, `String`, or aggregate data), not resources themselves.
+
+You can still extract computed results by using the `$` operator to unwrap scoped values *within* the scope:
+
+```scala
+import zio.blocks.scope.{Scope, Resource}
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val intValue = allocate(Resource(42))
+  // Extract the Int value (not the Resource), computed inside the scope
+  val n: Int = $(intValue)(x => x + 1)
+
+  val text = allocate(Resource("hello"))
+  // Extract the String value (not the Resource), computed inside the scope
+  val s: String = $(text)(x => x.toUpperCase)
+
+  (n, s)  // Tuple of pure data: safe to return
+}
+```
+
+## Returning Unscoped Data from Scopes
+
+Extract computed results that don't hold resources:
+
+```scala
+import zio.blocks.scope.{Scope, Resource, Unscoped}
+import scala.concurrent.duration.{Duration, FiniteDuration}
+
+case class ProcessingResult(count: Int, elapsed: FiniteDuration)
+
+object ProcessingResult {
+  implicit val unscoped: Unscoped[ProcessingResult] = new Unscoped[ProcessingResult] {}
+}
+
+def processData(): ProcessingResult = Scope.global.scoped { scope =>
+  import scope._
+
+  val startTime = java.time.Instant.now()
+  val input = allocate(Resource(Seq(1, 2, 3, 4, 5)))
+  val count = $(input)(_.length)
+
+  val endTime = java.time.Instant.now()
+  val elapsed = java.time.Duration.between(startTime, endTime).toNanos
+
+  ProcessingResult(count, FiniteDuration(elapsed, java.util.concurrent.TimeUnit.NANOSECONDS))
+}
+
+val result = processData()
+println(result)
+```
+
+Only create instances for **pure data types** that don't hold resources. Never create instances for types that contain connections, streams, handles, or any resource-like fields.
+
+## Predefined Instances
+
+All built-in instances follow a simple principle: **if a type cannot hold resources, it gets an `Unscoped` instance**. Collections inherit this property from their elements — `List[Int]` is unscoped because `Int` is unscoped.
+
+**Primitive and atomic values** (cannot hold resources by nature):
+- `Int`, `Long`, `Short`, `Byte`, `Char`, `Boolean`, `Float`, `Double`, `Unit`
+- `String`, `BigInt`, `BigDecimal`
+- `java.util.UUID`
+
+**Collections with conditional instances** (safe when elements/entries are unscoped):
+- Sequences: `Array[A]`, `List[A]`, `Vector[A]`, `Seq[A]`, `IndexedSeq[A]`, `Iterable[A]`
+- Sets: `Set[A]`
+- Maps: `Map[K, V]` (when both `K` and `V` are unscoped)
+- Wrappers: `Option[A]`, `Either[A, B]`, `Tuple2[A, B]` through `Tuple4[A, B, C, D]`
+- ZIO types: `zio.blocks.chunk.Chunk[A]`
+
+**Standard library time types** (immutable, cannot hold resources):
+- `java.time.Instant`, `LocalDate`, `LocalTime`, `LocalDateTime`, `ZonedDateTime`, `OffsetDateTime`
+- `java.time.Duration`, `Period`, `ZoneId`, `ZoneOffset`
+- `scala.concurrent.duration.Duration`, `FiniteDuration`
+
+All other types (resources, handles, connections) must be manually defined if needed.
+
+
+## Thread Safety
+
+`Unscoped` instances themselves are immutable and thread-safe. However, the types they mark must be truly immutable for safe concurrent use. For example, `Array[Int]` is mutable—if shared across threads without synchronization, it could cause data races.
+
+## Integration
+
+- [`Scope.$`](./scope.md) — the operator that uses `Unscoped`
+- [`Resource`](./resource.md) — types that provide `Unscoped` may be wrapped in resources
+- [`Scope`](./scope.md) — manages the lifecycle of resources

package/reference/{resource-management-di → resource-management}/wire.md

@@ -3,7 +3,7 @@ id: wire
 title: "Wire"
 ---
 
-`Wire[-In, +Out]` is a **compile-time safe recipe for constructing a service and its dependencies**. Wires describe how to construct an `Out` value given access to its dependencies via a `Context[In]` and a `Scope` for finalization.
+`Wire[-In, +Out]` is a **compile-time safe recipe for constructing a service and its dependencies**. Wires describe how to construct an `Out` value given access to its dependencies via a `Context[In]` and a `Scope` for finalization:
 
 ```scala
 sealed trait Wire[-In, +Out] {
@@ -60,7 +60,7 @@ final class App(service: UserService) {
 
 // Manual wiring:
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val config = Config("jdbc:postgres://localhost/db")
   val db = Resource.fromAutoCloseable(new Database(config)).allocate
   val service = new UserService($(db)(identity))
@@ -73,7 +73,7 @@ With `Wire` + `Resource.from`, the macro handles the dependency graph:
 
 ```scala
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val app = Resource.from[App](
     Wire(Config("jdbc:postgres://localhost/db"))
   ).allocate
@@ -89,23 +89,27 @@ Scope.global.scoped { scope =>
 
 ## Installation
 
+Add the following dependency to your `build.sbt`:
+
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "<version>"
+libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.30"
 ```
 
 For cross-platform (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "<version>"
+libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "0.0.30"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.
 
 ## Construction
 
+`Wire` provides multiple ways to create instances, ranging from automatic macro-based derivation to manual construction for custom logic. Here are the main construction methods:
+
 ### Wire.shared[T] — derive a shared wire
 
-The `Wire.shared[T]` macro inspects `T`'s primary constructor and generates a shared wire that reuses the same instance across dependents.
+The `Wire.shared[T]` macro inspects `T`'s primary constructor and generates a shared wire that reuses the same instance across dependents:
 
 ```scala
 import zio.blocks.scope._
@@ -121,7 +125,7 @@ final class Database(config: Config) extends AutoCloseable {
 val wire: Wire.Shared[Config, Database] = Wire.shared[Database]
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val config = Config(debug = true)
   val deps = Context[Config](config)
   val db = allocate(wire.toResource(deps))
@@ -131,7 +135,7 @@ Scope.global.scoped { scope =>
 
 ### Wire.unique[T] — derive a unique wire
 
-Like `shared[T]`, but creates a fresh instance each time the wire is used. Use for request-scoped or per-call services.
+Like `Wire.shared[T]`, but creates a fresh instance each time the wire is used. Use for request-scoped or per-call services:
 
 ```scala
 import zio.blocks.scope._
@@ -144,7 +148,7 @@ final class RequestHandler {
 val wire: Wire.Unique[Any, RequestHandler] = Wire.unique[RequestHandler]
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val deps = Context.empty[Any]
   val resource = wire.toResource(deps)
 
@@ -161,7 +165,7 @@ Scope.global.scoped { scope =>
 
 ### Wire.apply[T] — lift a pre-existing value
 
-Creates a shared wire that injects a value you already have. If the value is `AutoCloseable`, its `close()` method is automatically registered as a finalizer.
+Creates a shared wire that injects a value you already have. If the value is `AutoCloseable`, its `close()` method is automatically registered as a finalizer:
 
 ```scala
 import zio.blocks.scope._
@@ -172,7 +176,7 @@ val config = Config("jdbc:postgres://localhost/db")
 val wire: Wire.Shared[Any, Config] = Wire(config)
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val cfg = allocate(wire.toResource(Context.empty[Any]))
   $(cfg)(_.dbUrl)
 }
@@ -180,7 +184,7 @@ Scope.global.scoped { scope =>
 
 ### Wire.Shared.fromFunction — manual shared wire construction
 
-Use this for custom construction logic when macro derivation doesn't fit.
+Use this for custom construction logic when macro derivation doesn't fit:
 
 ```scala
 import zio.blocks.scope._
@@ -199,7 +203,7 @@ val wire: Wire.Shared[Config, Client] =
   }
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val config = Config(30)
   val deps = Context[Config](config)
   val client = allocate(wire.toResource(deps))
@@ -209,7 +213,7 @@ Scope.global.scoped { scope =>
 
 ### Wire.Unique.fromFunction — manual unique wire construction
 
-Like `fromFunction`, but for unique wires.
+Like `Wire.Shared.fromFunction`, but for unique wires:
 
 ```scala
 import zio.blocks.scope._
@@ -225,7 +229,7 @@ val wire: Wire.Unique[Any, RequestContext] =
   }
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val deps = Context.empty[Any]
   val resource = wire.toResource(deps)
 
@@ -249,7 +253,7 @@ The fundamental difference is **reuse semantics**:
 | **Instance reuse** | Same instance across entire dependency graph | New instance per allocation |
 | **Finalization** | Runs when last referencing scope closes | Runs when each scope closes |
 
-In the diamond pattern (where `App` depends on both `UserService` and `OrderService`, both of which depend on `Database`), a shared wire ensures `Database` is constructed once and both services receive the same instance.
+In the diamond pattern (where `App` depends on both `UserService` and `OrderService`, both of which depend on `Database`), a shared wire ensures `Database` is constructed once and both services receive the same instance:
 
 ```scala
 import zio.blocks.scope._
@@ -281,7 +285,7 @@ val resource = Resource.from[App](
 )
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val app = resource.allocate
   $(app)(_.check())  // true: Database is shared
 }
@@ -289,10 +293,21 @@ Scope.global.scoped { scope =>
 
 ## Core Operations
 
+The `Wire` interface provides a set of operations for inspecting and transforming wires:
+
 ### `Wire#isShared` and `Wire#isUnique`
 
 Check the sharing strategy of a wire:
 
+```scala
+trait Wire[-In, +Out] {
+  def isShared: Boolean
+  def isUnique: Boolean = !isShared
+}
+```
+
+Here's how to use these methods:
+
 ```scala
 import zio.blocks.scope._
 
@@ -309,6 +324,15 @@ println(s"uniqueWire.isUnique: ${uniqueWire.isUnique}")      // true
 
 Convert a wire to the opposite strategy:
 
+```scala
+trait Wire[-In, +Out] {
+  def shared: Wire.Shared[In, Out]
+  def unique: Wire.Unique[In, Out]
+}
+```
+
+Here's how to convert between sharing strategies:
+
 ```scala
 import zio.blocks.scope._
 
@@ -329,6 +353,14 @@ Calling `shared` on an already-shared wire returns `this` (identity); likewise `
 
 Converts the wire to a lazy `Resource` by providing the dependency context:
 
+```scala
+trait Wire[-In, +Out] {
+  def toResource(deps: Context[In]): Resource[Out]
+}
+```
+
+Here's how to use this method:
+
 ```scala
 import zio.blocks.scope._
 import zio.blocks.context.Context
@@ -341,7 +373,7 @@ val deps = Context[Config](Config("hello"))
 val resource: Resource[Config] = wire.toResource(deps)
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val cfg = allocate(resource)
   $(cfg)(_.value)
 }
@@ -349,7 +381,15 @@ Scope.global.scoped { scope =>
 
 ### `Wire#make` — construct directly from a wire
 
-Directly construct a value without going through `Resource.toResource`. This is a low-level operation; prefer `allocate(wire.toResource(...))` for safety.
+Directly construct a value without going through `Resource.toResource`. This is a low-level operation; prefer `allocate(wire.toResource(...))` for safety:
+
+```scala
+trait Wire.Shared[-In, +Out] {
+  def make(scope: Scope, context: Context[In]): Out
+}
+```
+
+Here's how to use this method:
 
 ```scala
 import zio.blocks.scope._
@@ -362,7 +402,7 @@ final class Service {
 val wire = Wire.shared[Service]
 
 Scope.global.scoped { scope =>
-  import scope.*
+  import scope._
   val service = wire.asInstanceOf[Wire.Shared[Any, Service]].make(scope, Context.empty[Any])
   println(service.getName)
 }
@@ -384,11 +424,11 @@ import zio.blocks.scope._
 
 final case class Config(dbUrl: String)
 
-final class Logger(using Finalizer) {
+final class Logger(implicit finalizer: Finalizer) {
   def log(msg: String): Unit = println(msg)
 }
 
-final class Database(config: Config)(using scope: Scope) extends AutoCloseable {
+final class Database(config: Config)(implicit scope: Scope) extends AutoCloseable {
   def connect(): Unit = {
     scope.defer(println("database connection closed"))
     println(s"connecting to ${config.dbUrl}")
@@ -492,7 +532,7 @@ cd zio-blocks
 
 **2. Run individual examples with sbt:**
 
-**Basic wire construction: deriving shared wires, lifting values, and converting to resources**
+Basic wire construction demonstrates how to create and use `Wire` for dependency injection. View the example source code:
 
 ```scala title="scope-examples/src/main/scala/wire/WireBasicExample.scala" 
 package wire
@@ -589,11 +629,13 @@ final class BasicApp(service: UserService) {
 
 ([source](https://github.com/zio/zio-blocks/blob/main/scope-examples/src/main/scala/wire/WireBasicExample.scala))
 
+Run this example with:
+
 ```bash
-sbt "scope-examples/runMain wire.WireBasicExample"
+sbt "scope-examples/runMain wire.wireBasicExample"
 ```
 
-**Comparing shared vs unique semantics: shared wires reuse the same instance across dependents, while unique wires create fresh instances**
+Comparing shared vs unique semantics shows how shared wires reuse the same instance across dependents, while unique wires create fresh instances. View the example:
 
 ```scala title="scope-examples/src/main/scala/wire/WireSharedUniqueExample.scala" 
 package wire
@@ -692,11 +734,13 @@ final class UniqueDependencyApp(a: ServiceA, b: ServiceB) {
 
 ([source](https://github.com/zio/zio-blocks/blob/main/scope-examples/src/main/scala/wire/WireSharedUniqueExample.scala))
 
+Run this example with:
+
 ```bash
-sbt "scope-examples/runMain wire.WireSharedUniqueExample"
+sbt "scope-examples/runMain wire.wireSharedUniqueExample"
 ```
 
-**Manual wire construction: using fromFunction for custom construction logic**
+Manual wire construction demonstrates how to use `fromFunction` for custom construction logic. View the example:
 
 ```scala title="scope-examples/src/main/scala/wire/WireFromFunctionExample.scala" 
 package wire
@@ -827,6 +871,8 @@ final class ManualWireApp(client: HttpClient, auth: Authenticator) {
 
 ([source](https://github.com/zio/zio-blocks/blob/main/scope-examples/src/main/scala/wire/WireFromFunctionExample.scala))
 
+Run this example with:
+
 ```bash
-sbt "scope-examples/runMain wire.WireFromFunctionExample"
+sbt "scope-examples/runMain wire.wireFromFunctionExample"
 ```

package/reference/schema-evolution/as.md

@@ -39,13 +39,13 @@ The bidirectional data flow looks like this:
 `As` is part of `zio-blocks-schema`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 ```
 
 For Scala.js and Scala Native, use `%%%`:
 
 ```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.
@@ -240,7 +240,7 @@ trait As[A, B] {
 
 ```scala
 val revAs: As[LongBox, IntBox] = boxAs.reverse
-// revAs: As[LongBox, IntBox] = zio.blocks.schema.As$$anon$1@29407f04
+// revAs: As[LongBox, IntBox] = zio.blocks.schema.As$$anon$1@c044a8b
 
 revAs.into(LongBox(5L))
 // res11: Either[SchemaError, IntBox] = Right(IntBox(5))
@@ -302,7 +302,7 @@ We import `As.reverseInto` and use it to obtain the reverse `Into[Int, String]`:
 import As.reverseInto
 
 val intToStr: Into[Int, String] = reverseInto[String, Int]
-// intToStr: Into[Int, String] = zio.blocks.schema.AsLowPriorityImplicits$$Lambda$16771/0x00007f092a81f330@1cdf3706
+// intToStr: Into[Int, String] = zio.blocks.schema.AsLowPriorityImplicits$$Lambda$17407/0x00007f6106975350@5d23723e
 intToStr.into(42)
 // res14: Either[SchemaError, String] = Right("42")
 ```

package/reference/schema-evolution/into.md

@@ -69,13 +69,13 @@ Compare this to a manual implementation:
 `Into` is part of the `zio-blocks-schema` module:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 ```
 
 For 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/schema-expr.md

@@ -70,13 +70,13 @@ val result: Either[OpticCheck, Seq[Boolean]] = combined.eval(alice)
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 ```
 
 For cross-platform (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.