@zio.dev/zio-blocks 0.0.28 → 0.0.30

package/index.md

@@ -24,6 +24,7 @@ The philosophy is simple: **use what you need, nothing more**. Each block is ind
 | **TypeId** | Compile-time type identity with rich metadata | ✅ Available |
 | **Context** | Type-indexed heterogeneous collections | ✅ Available |
 | **MediaType** | Type-safe IANA media types with 2,600+ predefined types | ✅ Available |
+| **Ring Buffer** | High-performance bounded ring buffers (SPSC, MPSC, SPMC, MPMC) | ✅ Available |
 | **Streams** | Pull-based streaming primitives | 🚧 In Development |
 
 ## Core Principles
@@ -81,14 +82,14 @@ val thriftCodec  = Schema[Person].derive(ThriftFormat)      // Thrift
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 
 // Optional format modules:
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.30"
 ```
 
 ### Example: Optics
@@ -143,7 +144,7 @@ Chunk is designed for:
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-chunk" % "0.0.30"
 ```
 
 ### Example
@@ -232,7 +233,7 @@ Scope.global.scoped { scope =>
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.30"
 ```
 
 ### Example: Basic Resource Management
@@ -309,6 +310,12 @@ Scope.global.scoped { connScope =>
 // Connection closed here
 ```
 
+### Getting Started
+
+New to Scope? Check out the [Scope Tutorial](./guides/compile-time-resource-safety-with-scope.md) for a comprehensive step-by-step guide that walks you through the concepts, patterns, and real-world examples. The tutorial is designed for newcomers and covers everything from basic resource management to advanced dependency injection.
+
+For detailed API documentation, see the [Scope Reference](./reference/resource-management/scope.md).
+
 ---
 
 ## Docs
@@ -335,7 +342,7 @@ Generating documentation, README files, or any Markdown content programmatically
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.30"
 ```
 
 ### Example
@@ -419,7 +426,7 @@ Compile-time type identity with rich metadata. TypeId captures comprehensive inf
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-typeid" % "0.0.30"
 ```
 
 ### Example
@@ -462,7 +469,7 @@ A type-indexed heterogeneous collection that stores values by their types with c
 ### Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.30"
 ```
 
 ### Example
@@ -494,6 +501,47 @@ val merged: Context[Config & Metrics] = ctx1 ++ ctx2
 
 ---
 
+## Ring Buffer
+
+High-performance, bounded ring buffers for inter-thread communication. Four lock-free variants cover every producer/consumer pattern (SPSC, MPSC, SPMC, MPMC).
+
+### Why Ring Buffer?
+
+Standard `java.util.concurrent` queues use node allocation (`ConcurrentLinkedQueue`) or coarse locking (`ArrayBlockingQueue`). Ring buffers avoid both:
+
+- **Zero allocation** on the hot path—pre-allocated circular array
+- **Lock-free** on the fast path—CAS or release/acquire semantics only
+- **Cache-friendly**—sequential memory access with 128-byte padding between producer/consumer fields
+
+### Key Features
+
+- **Four concurrency patterns**: SPSC, SPMC, MPSC, MPMC—pick the most constrained variant for your use case
+- **Cross-platform**: Same API on JVM and Scala.js (JS uses sequential implementations)
+
+### Installation
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-ringbuffer" % "0.0.30"
+```
+
+### Example
+
+```scala
+import zio.blocks.ringbuffer._
+
+// SPSC: fastest, for dedicated producer-consumer pairs
+val spsc = SpscRingBuffer[String](1024)
+spsc.offer("hello") // true
+spsc.take()          // "hello"
+
+// MPMC: general-purpose, any number of threads
+val mpmc = MpmcRingBuffer[String](1024)
+mpmc.offer("hello") // false if full
+mpmc.take()          // null if empty
+```
+
+---
+
 ## Streams (In Development)
 
 A pull-based streaming library for composable, backpressure-aware data processing.
@@ -526,10 +574,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 | Scope | Docs | TypeId | Context | Streams |
-|----------|--------|-------|-------|------|--------|---------|---------|
-| JVM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Scala.js | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Platform | Schema | Chunk | Scope | Docs | TypeId | Context | Ring Buffer | Streams |
+|----------|--------|-------|-------|------|--------|---------|-------------|---------|
+| JVM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Scala.js | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 ## Documentation
 
@@ -555,6 +603,7 @@ ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibil
 - [Codec & Format](./reference/codec.md) - Codec, Format, BinaryCodec & TextCodec
 - [JSON](./reference/json.md) - JSON codec and parsing
 - [JsonPatch](./reference/json-patch.md) - Diff and patch JSON values
+- [JsonDiffer](./reference/json-differ.md) - Compute minimal diffs between JSON values
 - [JSON Schema](./reference/json-schema.md) - JSON Schema generation and validation
 - [Formats](./reference/formats.md) - Avro, TOON, MessagePack, BSON, Thrift
 - [Extension Syntax](./reference/syntax.md) - `.toJson`, `.fromJson`, and more
@@ -571,11 +620,14 @@ 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
+- [Scope](./reference/resource-management/scope.md) - Compile-time safe resource management and DI
+- [Wire](./reference/resource-management/wire.md) - Recipes for constructing services and dependencies
 - [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
 - [MediaType](./reference/media-type.md) - Type-safe IANA media types
+- [HTTP Model](./reference/http-model.md) - Pure HTTP data model with URL parsing, headers, cookies, and forms
+- [Ring Buffer](./ringbuffer.md) - High-performance bounded ring buffers
 
 ### Guides
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@zio.dev/zio-blocks",
   "description": "ZIO Blocks Documentation",
   "license": "Apache-2.0",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "repository": {
     "url": "https://github.com/zio/zio-blocks"
   }

package/path-interpolator.md

@@ -212,6 +212,65 @@ p"<café>"          // Unicode case names
 p"<A><B><C>"       // Nested variants
 ```
 
+### Schema Search
+
+Search for values matching a schema pattern anywhere in a data structure using the `#` prefix.
+
+**Nominal types:**
+
+```scala
+p"#Person"         // Find all values of type Person
+p"#User"           // Find all values of type User
+p"#Address"        // Find all values of type Address
+```
+
+**Primitive types:**
+
+```scala
+p"#string"         // Find all string values
+p"#int"            // Find all integer values
+p"#boolean"        // Find all boolean values
+p"#uuid"           // Find all UUID values
+```
+
+**Structural records:**
+
+```scala
+p"#record { name: string }"                // Find records with a string 'name' field
+p"#record { name: string, age: int }"      // Find records with both fields
+p"#record { items: list(Person) }"         // Nested schema
+```
+
+**Structural variants:**
+
+```scala
+p"#variant { Left: int, Right: string }"   // Find Either-like variants
+```
+
+**Collections:**
+
+```scala
+p"#list(string)"                           // Find lists of strings
+p"#list(Person)"                           // Find lists of Person
+p"#map(string, int)"                       // Find maps from string to int
+p"#option(Person)"                         // Find optional Person values
+```
+
+**Wildcard:**
+
+```scala
+p"#_"              // Find any value (matches everything)
+```
+
+**Combined paths with search:**
+
+```scala
+p".users#Person"               // Search for Person in users field
+p"#Person.name"                // Find all Person values, then get name
+p".items[*]#Person.email"      // Elements then search then field
+p"#list(Person)#Person"        // Chained searches
+```
+
 ## Escape Sequences
 
 String and character literals support standard escape sequences:
@@ -623,15 +682,17 @@ val same = p".users[*].email"
 |------------------------------------------------------|-------------------|
 | `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`                                                  | `.~`              |
+| `DynamicOptic.root.searchSchema(SchemaRepr.Nominal("Person"))`          | `#Person`         |
+| `DynamicOptic.root.searchSchema(SchemaRepr.Primitive("string"))`        | `#string`         |
 
 ## Summary
 

package/reference/allows.md

@@ -584,6 +584,22 @@ sbt "schema-examples/runMain comptime.AllowsCsvExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsCsvExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._
@@ -692,6 +708,22 @@ sbt "schema-examples/runMain comptime.AllowsEventBusExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsEventBusExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._
@@ -798,6 +830,22 @@ sbt "schema-examples/runMain comptime.AllowsGraphQLTreeExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsGraphQLTreeExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._
@@ -922,6 +970,22 @@ sbt "schema-examples/runMain comptime.AllowsSealedTraitExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsSealedTraitExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._
@@ -1017,6 +1081,22 @@ object AllowsSealedTraitExample extends App {
 Demonstrates how Allows constraints are verified at compile time — the code below shows valid examples that compile successfully, and includes comments showing which patterns would be rejected:
 
 ```scala title="schema-examples/src/main/scala/comptime/RdbmsExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._
@@ -1210,6 +1290,22 @@ object RdbmsDemo {
 Demonstrates how Allows enforces recursive schema constraints at compile time:
 
 ```scala title="schema-examples/src/main/scala/comptime/DocumentStoreExample.scala" 
+/*
+ * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package comptime
 
 import zio.blocks.schema._

package/reference/codec.md

@@ -48,23 +48,23 @@ val result: Either[SchemaError, Person] = Person.codec.decode(bytes)
 To include the base schema module with JSON support, add the following dependency to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.30"
 ```
 
 Additional format modules are separate artifacts:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.28"
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro"        % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-toon"        % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift"      % "0.0.30"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson"        % "0.0.30"
 ```
 
 For cross-platform projects (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.30"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.
@@ -152,7 +152,7 @@ object Person extends CompanionOptics[Person] {
 
 // Override the codec for the "name" field
 val customNameCodec = new JsonBinaryCodec[String] {
-  def decodeValue(in: JsonReader, default: String): String = in.readString(default)
+  def decodeValue(in: JsonReader): String = in.readString()
   def encodeValue(x: String, out: JsonWriter): Unit = out.writeVal(x.toUpperCase)
 }