@zio.dev/zio-blocks 0.0.1 → 0.0.22

package/index.md

@@ -5,7 +5,7 @@ title: "ZIO Blocks"
 
 **Modular, zero-dependency building blocks for modern Scala applications.**
 
-@PROJECT_BADGES@
+[![Development](https://img.shields.io/badge/Project%20Stage-Development-green.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-blocks/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-blocks-next-schema_3.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-blocks-next-schema_3/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-blocks-next-schema_3.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-blocks-next-schema_3/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-blocks-docs_3/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-blocks-docs_3) [![ZIO Blocks](https://img.shields.io/github/stars/zio/zio-blocks?style=social)](https://github.com/zio/zio-blocks)
 
 ## What Is ZIO Blocks?
 
@@ -19,6 +19,7 @@ The philosophy is simple: **use what you need, nothing more**. Each block is ind
 |-------|-------------|--------|
 | **Schema** | Type-safe schemas with automatic codec derivation | ✅ Available |
 | **Chunk** | High-performance immutable indexed sequences | ✅ Available |
+| **Scope** | Compile-time safe resource management and DI | ✅ Available |
 | **Docs** | GitHub Flavored Markdown parsing and rendering | ✅ Available |
 | **TypeId** | Compile-time type identity with rich metadata | ✅ Available |
 | **Context** | Type-indexed heterogeneous collections | ✅ Available |
@@ -79,14 +80,14 @@ val thriftCodec  = Schema[Person].derive(ThriftFormat)      // Thrift
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.22"
 
 // Optional format modules:
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "@VERSION@"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "@VERSION@"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "@VERSION@"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "@VERSION@"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.22"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.22"
 ```
 
 ### Example: Optics
@@ -141,7 +142,7 @@ Chunk is designed for:
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.22"
 ```
 
 ### Example
@@ -170,6 +171,151 @@ val head: Int = nonEmpty.head  // Always safe, no Option needed
 
 ---
 
+## Scope
+
+Compile-time verified resource safety for synchronous Scala code. Scope prevents resource leaks at compile time by tagging values with an unnameable type-level identity—values allocated in a scope can only be used within that scope. Child scope values cannot escape to parent scopes, enforced by both the abstract scope-tagged type and the `Unscoped` constraint on `scoped`.
+
+### The Problem
+
+Resource management in Scala is error-prone:
+
+```scala
+// Classic try/finally - verbose and easy to get wrong
+val db = openDatabase()
+try {
+  val tx = db.beginTransaction()
+  try {
+    doWork(tx)
+    tx.commit()
+  } finally tx.close()  // What if commit() throws?
+} finally db.close()
+
+// Using - better, but doesn't prevent returning resources
+Using(openDatabase()) { db =>
+  db  // Oops! Returned the resource - use after close!
+}
+```
+
+### The Solution
+
+Scope makes resource leaks a **compile error**, not a runtime bug:
+
+```scala
+import zio.blocks.scope._
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val db: $[Database] = allocate(Resource(openDatabase()))
+
+  // Methods are hidden - can't call db.query() directly
+  // Must use scope.use to access:
+  val result = scope.use(db)(_.query("SELECT 1"))
+
+  // Trying to return `db` would be a compile error!
+  result  // Only pure data escapes
+}
+// db.close() called automatically
+```
+
+### Key Features
+
+- **Compile-Time Leak Prevention**: Values of type `scope.$[A]` are opaque and unique to each scope instance. Returning a scoped value from its scope is a type error.
+- **Zero Runtime Overhead**: `$[A]` erases to `A` at runtime—zero allocation overhead.
+- **Structured Scopes**: Child scopes nest within parents; resources clean up LIFO when scopes exit.
+- **Built-in Dependency Injection**: Wire up your application with `Resource.from[T](wires*)` for automatic constructor-based DI.
+- **AutoCloseable Integration**: Resources implementing `AutoCloseable` have `close()` registered automatically.
+- **Unscoped Constraint**: The `scoped` method requires `Unscoped[A]` evidence on the return type, ensuring only pure data (not resources or closures) can escape.
+
+### Installation
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.22"
+```
+
+### Example: Basic Resource Management
+
+```scala
+import zio.blocks.scope._
+
+final class Database extends AutoCloseable {
+  def query(sql: String): String = s"Result: $sql"
+  def close(): Unit = println("Database closed")
+}
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  // Allocate returns scope.$[Database] (scoped value)
+  val db: $[Database] = allocate(Resource(new Database))
+
+  // Access via scope.use - result (String) escapes, db does not
+  val result = scope.use(db)(_.query("SELECT * FROM users"))
+
+  println(result)
+}
+// Output: Result: SELECT * FROM users
+//         Database closed
+```
+
+### Example: Dependency Injection
+
+```scala
+import zio.blocks.scope._
+
+case class Config(dbUrl: String)
+class Database(config: Config) extends AutoCloseable { ... }
+class UserRepo(db: Database) { ... }
+class UserService(repo: UserRepo) extends AutoCloseable { ... }
+
+// Resource.from auto-wires the dependency graph
+// Only provide leaf values - concrete classes are auto-wired
+val serviceResource: Resource[UserService] = Resource.from[UserService](
+  Wire(Config("jdbc:postgresql://localhost/mydb"))
+)
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val service = allocate(serviceResource)
+
+  scope.use(service)(_.createUser("Alice"))
+}
+// Cleanup runs LIFO: UserService → Database (UserRepo has no cleanup)
+```
+
+### Example: Nested Scopes with Transactions
+
+```scala
+Scope.global.scoped { connScope =>
+  import connScope._
+
+  val conn = allocate(Resource.fromAutoCloseable(new Connection))
+
+  // Transaction lives in child scope - cleaned up before connection
+  val result: String = scoped { txScope =>
+    import txScope._
+
+    // For-comprehension: flatMap unwraps $[Connection] to Connection,
+    // so c.beginTransaction() returns a raw Resource[Transaction]
+    for {
+      c  <- lower(conn)
+      tx <- allocate(c.beginTransaction())
+    } yield {
+      tx.execute("INSERT INTO users VALUES (1, 'Alice')")
+      tx.commit()
+      "success"
+    }
+  }
+  // Transaction closed here, connection still open
+
+  println(result)
+}
+// Connection closed here
+```
+
+---
+
 ## Docs
 
 A zero-dependency GitHub Flavored Markdown library for parsing, rendering, and programmatic construction of Markdown documents.
@@ -194,7 +340,7 @@ Generating documentation, README files, or any Markdown content programmatically
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.22"
 ```
 
 ### Example
@@ -278,7 +424,7 @@ Compile-time type identity with rich metadata. TypeId captures comprehensive inf
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.22"
 ```
 
 ### Example
@@ -321,7 +467,7 @@ A type-indexed heterogeneous collection that stores values by their types with c
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.22"
 ```
 
 ### Example
@@ -385,10 +531,10 @@ Each block has zero dependencies on effect systems. Use the blocks directly, or
 
 ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibility. Write your code once and compile it against either version—migrate to Scala 3 when your team is ready, not when your dependencies force you.
 
-| Platform | Schema | Chunk | Docs | TypeId | Context | Streams |
-|----------|--------|-------|------|--------|---------|---------|
-| JVM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Scala.js | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Platform | Schema | Chunk | Scope | Docs | TypeId | Context | Streams |
+|----------|--------|-------|-------|------|--------|---------|---------|
+| JVM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Scala.js | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 ## Documentation
 
@@ -407,6 +553,7 @@ ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibil
 
 ### Serialization
 
+- [Codec & Format](./reference/codec.md) - Codec, Format, BinaryCodec & TextCodec
 - [JSON](./reference/json.md) - JSON codec and parsing
 - [JSON Schema](./reference/json-schema.md) - JSON Schema generation and validation
 - [Formats](./reference/formats.md) - Avro, TOON, MessagePack, BSON, Thrift
@@ -421,6 +568,7 @@ ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibil
 ### Other Blocks
 
 - [Chunk](./reference/chunk.md) - High-performance immutable sequences
+- [Scope](./scope.md) - Compile-time safe resource management and DI
 - [TypeId](./reference/typeid.md) - Type identity and metadata
 - [Context](./reference/context.md) - Type-indexed heterogeneous collections
 - [Docs (Markdown)](./reference/docs.md) - Markdown parsing and rendering

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@zio.dev/zio-blocks",
-  "version": "0.0.1",
   "description": "ZIO Blocks Documentation",
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "version": "0.0.22",
+  "repository": {
+    "url": "https://github.com/zio/zio-blocks"
+  }
 }

package/path-interpolator.md

@@ -1,6 +1,7 @@
-# Path Interpolator
-
-## Overview
+---
+id: path-interpolator
+title: "Path Interpolator"
+---
 
 The path interpolator `p"..."` is a compile-time string interpolator for constructing `DynamicOptic` instances in ZIO Blocks. It provides a clean, concise syntax for building optic paths that navigate through complex data structures, with all parsing and validation happening at compile time for zero runtime overhead.
 
@@ -215,14 +216,14 @@ p"<A><B><C>"       // Nested variants
 
 String and character literals support standard escape sequences:
 
-| Escape | Result | Description |
-|--------|--------|-------------|
-| `\n`   | newline | Line feed |
-| `\t`   | tab | Horizontal tab |
-| `\r`   | return | Carriage return |
-| `\'`   | `'` | Single quote |
-| `\"`   | `"` | Double quote |
-| `\\`   | `\` | Backslash |
+| Escape | Result  | Description     |
+|--------|---------|-----------------|
+| `\n`   | newline | Line feed       |
+| `\t`   | tab     | Horizontal tab  |
+| `\r`   | return  | Carriage return |
+| `\'`   | `'`     | Single quote    |
+| `\"`   | `"`     | Double quote    |
+| `\\`   | `\`     | Backslash       |
 
 **Examples:**
 
@@ -618,19 +619,19 @@ val same = p".users[*].email"
 
 **Examples:**
 
-| DynamicOptic Construction | toString Output |
-|---------------------------|-----------------|
-| `DynamicOptic.root.field("name")` | `.name` |
+| DynamicOptic Construction                            | toString Output   |
+|------------------------------------------------------|-------------------|
+| `DynamicOptic.root.field("name")`                    | `.name`           |
 | `DynamicOptic.root.field("address").field("street")` | `.address.street` |
-| `DynamicOptic.root.caseOf("Some")` | `<Some>` |
-| `DynamicOptic.root.at(0)` | `[0]` |
-| `DynamicOptic.root.atIndices(0, 2, 5)` | `[0,2,5]` |
-| `DynamicOptic.elements` | `[*]` |
-| `DynamicOptic.root.atKey("host")` | `{"host"}` |
-| `DynamicOptic.root.atKey(80)` | `{80}` |
-| `DynamicOptic.mapValues` | `{*}` |
-| `DynamicOptic.mapKeys` | `{*:}` |
-| `DynamicOptic.wrapped` | `.~` |
+| `DynamicOptic.root.caseOf("Some")`                   | `<Some>`          |
+| `DynamicOptic.root.at(0)`                            | `[0]`             |
+| `DynamicOptic.root.atIndices(0, 2, 5)`               | `[0,2,5]`         |
+| `DynamicOptic.elements`                              | `[*]`             |
+| `DynamicOptic.root.atKey("host")`                    | `{"host"}`        |
+| `DynamicOptic.root.atKey(80)`                        | `{80}`            |
+| `DynamicOptic.mapValues`                             | `{*}`             |
+| `DynamicOptic.mapKeys`                               | `{*:}`            |
+| `DynamicOptic.wrapped`                               | `.~`              |
 
 ## Summary
 

package/reference/binding.md

@@ -66,7 +66,7 @@ final case class Record[A](
 
 Here is an example of a `Binding.Record` for a simple `Person` case class:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.binding._
 import zio.blocks.schema.binding.RegisterOffset._
 
@@ -115,13 +115,11 @@ final case class Variant[A](
 - `Discriminator`: Given a value of a sum type, determine which case it belongs to by returning a numerical index.
 - `Matchers`: Given a value and a case index, safely downcast the value to the specific case type, or return null if it doesn't match.
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema.binding._
 
 sealed trait Shape extends Product with Serializable
-
 case class Circle(radius: Double) extends Shape
-
 case class Rectangle(width: Double, height: Double) extends Shape
 
 val shapeBinding = Binding.Variant[Shape](
@@ -302,25 +300,21 @@ final case class Wrapper[A, B](
 
 **Components:**
 
-- `wrap`: Converts from the underlying type `B` to the wrapper type `A`, returning `Right(a)` on success or `Left(SchemaError)` on failure
-- `unwrap`: Extracts the underlying `B` from an `A`, returning `Right(b)` on success or `Left(SchemaError)` on failure
+- `wrap`: Converts from the underlying type `B` to the wrapper type `A`
+- `unwrap`: Extracts the underlying `B` from an `A`
 
-Here is an example of a `Binding.Wrapper` for an `Email` newtype with validation:
+Here is an example of a `Binding.Wrapper` for an `Email` newtype:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.schema._
 import zio.blocks.schema.binding._
 
 case class Email(value: String)
 
 object Email {
-  private val EmailRegex = "^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+$".r
   new Binding.Wrapper[Email, String](
-    wrap = {
-      case x@EmailRegex(_*) => Right(new Email(x))
-      case _ => Left(SchemaError.validationFailed("Expected valid email format"))
-    },
-    email => Right(email.value)
+    wrap = value => new Email(value),
+    unwrap = email => email.value
   )
 }
 ```