@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/maybe.md

@@ -3,44 +3,148 @@ id: maybe
 title: "Maybe"
 ---
 
-`Maybe[A]` is a **low-allocation alternative to `Option[A]`** that uses `null` to represent the absence of a value. It is an opaque type alias for `A | Null`, allowing you to write nullable-like code with the safety and ergonomics of an Option-style API. Core types: `Maybe[A]`.
+`Maybe[A]` is a **low-allocation alternative to `Option[A]`** that uses a top-level `Absent` sentinel object to represent the absence of a value. On Scala 3, it is an opaque type alias for `A | Absent.type | Present[A]`, where `Present[A]` is a public wrapper allocated whenever a present value would otherwise be indistinguishable from absence — nested `Maybe`s (`Maybe.present(Maybe.absent)` → `Present(Absent)`) and `null` values (`Maybe.present(null)` → `Present(null)`). On Scala 2.13, it is a sealed trait (`Present[A]` | `Absent`). Core types: `Maybe[A]`, `Present[A]`.
 
 Here's the type definition and basic construction:
 
 ```scala
-opaque type Maybe[+A] = A | Null
+// Scala 3
+final class Present[+A](val value: A) // manual companion: apply + unapply that matches both raw values and wrappers
+object Absent
+opaque type Maybe[+A] = A | Absent.type | Present[A]
 
 val present: Maybe[Int] = Maybe.present(42)
 val absent: Maybe[Int]  = Maybe.absent
 ```
 
+## Allocation Profile
+
+The new encoding minimizes allocation by using the raw value when possible:
+
+| Case | Example | Allocations |
+|------|---------|-------------|
+| Flat present | `Maybe.present(42)` | **0** (raw `42`) |
+| Flat apply | `Maybe(42)` | **0** (raw `42`) |
+| Flat fromOption | `Maybe.fromOption(Some(42))` | **0** (raw `42`) |
+| Absent | `Maybe.absent` | **0** (`Absent` singleton) |
+| Present-of-absent | `Maybe.present(Maybe.absent)` | **1** (`Present(Absent)`) |
+| Present null | `Maybe.fromOption(Some(null))` | **1** (`Present(null)`) |
+
+The `Present[A]` wrapper is allocated **only** for present-of-absent cases: wrapping a nested `Maybe` that is itself absent (`Present(Absent)`) and wrapping a `null` value (`Present(null)`). All other flat cases store the value raw with zero allocation overhead.
+
+### Nesting Depth
+
+Nested `Maybe` values reduce wrapper depth by 1 compared to `Option`:
+
+```scala
+import zio.blocks.maybe._
+
+// Option: Some(None) = 2 wrappers
+val optNested: Option[Option[Int]] = Some(None)
+
+// Maybe: Present(Absent) = 1 wrapper (Present) + Absent singleton
+val maybeNested: Maybe[Maybe[Int]] = Maybe.present(Maybe.absent[Int])
+// maybeNested matches Present(Absent), not Absent
+
+// Flattening removes the Present wrapper
+val flat: Maybe[Int] = maybeNested.flatten
+// flat is absent (Absent)
+```
+
 ## Motivation
 
 When working with optional values, you face a choice: `Option[A]` provides type safety and functional composition but allocates a wrapper object for every value. `Maybe[A]` provides an alternative with different trade-offs depending on your Scala version.
 
-**On Scala 3:** `Maybe[A]` eliminates allocation overhead by leveraging union types and null semantics—every value is either the unwrapped value itself or `null`. This is ideal for performance-critical code where allocations impact throughput or latency. The type is an opaque alias for `A | Null`, giving you a dedicated API (`map`, `flatMap`, `filter`, etc.) with zero runtime wrapper overhead—just null checks.
+**On Scala 3:** `Maybe[A]` eliminates allocation overhead by leveraging union types and a top-level `Absent` sentinel. The type is an opaque alias for `A | Absent.type | Present[A]`, where `Present[A]` is a public wrapper allocated whenever a present value would otherwise be indistinguishable from absence. Flat values (non-nested, non-null) are stored raw with zero allocation; only present-of-absent values allocate a `Present` wrapper (`Maybe.present(Maybe.absent)` → `Present(Absent)`, `Maybe.present(null)` → `Present(null)`). This gives you a dedicated API (`map`, `flatMap`, `filter`, etc.) with minimal runtime overhead. `case Absent` is a stable-identifier pattern that works directly.
 
 **On Scala 2.13:** `Maybe[A]` is implemented as a sealed trait (`Present[A]` | `Absent`). Present values allocate a wrapper, so the allocation savings versus `Option` are less pronounced. However, the unified API and interoperability benefits still apply.
 
 ### Why Maybe over Option?
 
-- **Zero allocation**: Every `Maybe` is either the value itself or `null`—no wrapper objects
+- **Zero allocation (flat case)**: Non-nested `Maybe` values are either the raw value itself or the `Absent` singleton—no wrapper objects
+- **Sound nesting**: Nested `Maybe[Maybe[A]]` is now sound via `Present[A]`, without requiring a compile-time guard
 - **Familiar API**: All your favorite `Option` combinators (`map`, `flatMap`, `fold`, etc.)
 - **Type safety**: The opaque type prevents accidentally mixing nullable and non-nullable values
 - **Interoperable**: Seamless conversion to/from `Option` with `toOption` and `Maybe#fromOption`
 
+## Cross-Version Parity
+
+The API surface is consistent across Scala 2.13 and Scala 3, but the underlying encoding differs:
+
+| Aspect | Scala 3 | Scala 2.13 |
+|--------|---------|------------|
+| Encoding | `opaque type Maybe[+A] = A \| Absent.type \| Present[A]` | Sealed trait `Present[A]` \| `Absent` |
+| Flat allocation | **0** (raw value or `Absent` singleton) | **1** (wrapper object) |
+| Nested allocation | **1** (`Present(Absent)` only) | **1** (wrapper object) |
+| `Present` type | Public `final class Present[+A]` with manual companion (`apply`/`unapply`) | `MaybeValue.Present[A]` (sealed) |
+| Nesting guard | **Removed** (nesting now sound via `Present`) | N/A (never existed) |
+
+### Behavior Differences
+
+- **`Maybe.present(null)`**: On Scala 3, produces `Present(null)` (present-of-absent). On Scala 2.13, produces `MaybeValue.Present(null)` (also present-of-absent). Both are distinguishable from `Maybe.absent`.
+- **`Maybe.fromOption(Some(null))`**: Routes through `present`, so same behavior as above.
+- **Pattern matching**: On Scala 3, `Present(v)` matches both present shapes (a raw value and a `Present(...)` wrapper); absent matches `case Absent` (stable-identifier pattern, no `case _` required inside the package; external two-case matches also compile without exhaustivity warning). On Scala 2.13, `MaybeValue.Present(v)` / `MaybeValue.Absent` are the compiler-checked native patterns.
+
+## Pattern Matching
+
+On Scala 3, a `Maybe[A]` value can take three runtime shapes. The `Present` companion's `unapply` collapses the two present shapes into one pattern; absent is now a real top-level singleton object:
+
+| Shape | Pattern | Meaning |
+|-------|---------|---------|
+| `Absent` object | `case Absent` | absent (stable-identifier pattern) |
+| `Present(v)` wrapper | `case Present(v)` | present-of-absent (a nested `Maybe`) |
+| raw `v` | `case Present(v)` | present, zero allocation |
+
+(Note: the `Present` companion's `unapply` collapses both present shapes — one `Some` allocation per present match.)
+
+```scala
+import zio.blocks.maybe._
+
+val maybe: Maybe[Int] = Maybe.present(42)
+
+val description: String = maybe match {
+  case Present(v) => s"present ($v)"
+  case Absent     => "absent"
+}
+```
+
+`case Absent` is a stable-identifier pattern that works because `Absent` is a plain top-level object (not a case object). The two-case match `case Present(v); case Absent` compiles without exhaustivity warning even from an external package — verified under this build's `-Xfatal-warnings` settings (`WildcardImportSpec`). Note that this is weaker than the sealed-hierarchy guarantee on Scala 2.13 below: exhaustivity here depends on the compiler decomposing the opaque union, so prefer `fold` when you need a guarantee that is independent of compiler behavior. `Present(v)` matches both a raw value and a `Present(...)` wrapper, at the cost of one `Some` allocation per present match (inherent to the `Option`-returning extractor protocol).
+
+For production code, prefer `fold`, which is exhaustive, warning-free, and zero-allocation:
+
+```scala
+import zio.blocks.maybe._
+
+val maybe: Maybe[Int] = Maybe.present(42)
+val description: String = maybe.fold("absent")(v => s"present ($v)")
+```
+
+Scala 2.13 parity: on Scala 2.13, absent is the non-null case object `MaybeValue.Absent`, so it **can** be matched explicitly — the sealed `MaybeValue` trait (`Present` | `Absent`) gives compiler-checked exhaustivity:
+
+```scala
+import zio.blocks.maybe._
+
+val maybe: Maybe[Int] = Maybe.present(42)
+val description: String = maybe match {
+  case MaybeValue.Present(v) => s"present ($v)"
+  case MaybeValue.Absent     => "absent"
+}
+```
+
+So on Scala 2.13 the sealed `MaybeValue` form is the compiler-checked native idiom; on Scala 3 the opaque union with `Absent` object enables `case Absent` while preserving the zero-allocation encoding.
+
 ## Installation
 
 Add the `zio-blocks-maybe` module to your build:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-maybe" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-maybe" % "0.0.55"
 ```
 
 For Scala.js:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-maybe" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-maybe" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x
@@ -84,7 +188,7 @@ Here are key patterns for working effectively with `Maybe`:
 
 ### Present and Absent States
 
-Every `Maybe` is either present (holds a non-null value) or absent (is `null`). Test the state with predicates:
+Every `Maybe` is either present (holds a value, possibly `null`) or absent (the `Absent` singleton). Test the state with predicates:
 
 ```scala
 import zio.blocks.maybe._
@@ -219,20 +323,28 @@ Wraps a value in `Maybe`, treating `null` as `Maybe.absent`:
 ```scala
 import zio.blocks.maybe._
 
-val present = Maybe(42)                  // Maybe[Int] containing 42
-val absent: Maybe[String] = Maybe(null)  // Maybe[String] absent
+val present: Maybe[Int]    = Maybe(42)                         // Maybe[Int] containing 42
+val absent: Maybe[String]  = Maybe(null.asInstanceOf[String])  // Maybe.absent (the Absent object)
 ```
 
+> **Note:** `Maybe.apply` collapses `null` to `Maybe.absent`. Use `Maybe.present` when you need to preserve present-ness even for `null` values (e.g., in nested `Maybe`s).
+
 #### Maybe.present
 
-Explicitly wraps a non-null value:
+Explicitly wraps a value, preserving present-ness even for `null`:
 
 ```scala
 import zio.blocks.maybe._
 
 val value: Maybe[Int] = Maybe.present(100)
+
+// Nested case: present of an absent Maybe produces Present(Absent), not absence
+val nested: Maybe[Maybe[Int]] = Maybe.present(Maybe.absent[Int])
+// nested is Present(Absent), distinguishable from Maybe.absent
 ```
 
+> **Note:** Unlike `Maybe.apply`, `Maybe.present` preserves present-ness even for `null`. A non-null value is returned as-is (zero allocation). A `null` value is wrapped in `Present(null)`, which is distinguishable from `Maybe.absent` (the `Absent` object). This is what makes nested `Maybe`s sound.
+
 #### Maybe.absent
 
 Creates an absent value for any type:
@@ -393,9 +505,14 @@ Unwraps a nested `Maybe`:
 ```scala
 import zio.blocks.maybe._
 
-val nested: Maybe[Maybe[Int]] = Maybe.present(Maybe.present(42))
+val nested: Maybe[Maybe[Int]] = Maybe.fromOption(Some(Maybe.fromOption(Some(42))))
 val flat: Maybe[Int]          = nested.flatten
 println(flat.get)  // 42
+
+// Nested present-of-absent flattens to absent
+val nestedAbsent: Maybe[Maybe[Int]] = Maybe.present(Maybe.absent[Int])
+val flatAbsent: Maybe[Int]          = nestedAbsent.flatten
+println(flatAbsent.isAbsent)  // true
 ```
 
 ### Filtering

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

package/reference/mux.md

@@ -0,0 +1,254 @@
+---
+id: mux
+title: "Mux"
+---
+
+`Mux[Id, In, Out]` is a zero-dependency, cross-platform multiplexed stream coordinator. It manages many independent streams over one shared transport, where each stream is keyed by an `Id`.
+
+Use it for:
+- HTTP/2 stream multiplexing
+- WebSocket subprotocols
+- Any ID-keyed protocol that needs independent stream lifecycles
+
+Key properties:
+- Thread-safe registry operations and multi-producer stream writes
+- Lock-free on JVM for queue operations
+- Virtual-thread-friendly
+- JVM uses ring buffers for stream queues
+
+## Overview
+
+`Mux` owns the stream registry. Protocol code uses `offerInbound` and `takeOutbound`, while application code uses `send` and `receive`.
+
+```
+User code → send(In) → outbound queue → Protocol reads via takeOutbound()
+Protocol  → offerInbound(Out) → inbound queue → User code reads via receive()
+```
+
+Each stream has separate inbound and outbound queues, so traffic for one ID stays isolated from the others. Half-close maps cleanly to RFC 9113 stream states, which makes the API a good fit for HTTP/2-style protocols.
+
+## API
+
+The `Mux` API is cross-compiled: Scala 3 uses zero-cost union return types, while Scala 2 uses `Either`.
+
+### Scala 3
+
+```scala
+trait Mux[Id, In, Out] {
+  def open(id: Id): MuxStream[Id, In, Out] | MuxError
+  def get(id: Id): Option[MuxStream[Id, In, Out]]
+  def cancel(id: Id, reason: MuxError): Unit
+  def closeAll(reason: MuxError): Unit
+  def activeCount: Int
+}
+
+trait MuxStream[Id, In, Out] {
+  def id: Id
+  def send(msg: In): Unit | MuxError
+  def receive(): Option[Out] | MuxError
+  def offerInbound(msg: Out): Unit | MuxError
+  def takeOutbound(): Option[In] | MuxError
+  def halfClose(): Unit
+  def signalRemoteClose(): Unit
+  def isClosed: Boolean
+  def isHalfClosed: Boolean
+  def close(): Unit
+}
+
+sealed trait MuxError
+```
+
+### Scala 2
+
+```scala
+trait Mux[Id, In, Out] {
+  def open(id: Id): Either[MuxError, MuxStream[Id, In, Out]]
+  def get(id: Id): Option[MuxStream[Id, In, Out]]
+  def cancel(id: Id, reason: MuxError): Unit
+  def closeAll(reason: MuxError): Unit
+  def activeCount: Int
+}
+
+trait MuxStream[Id, In, Out] {
+  def id: Id
+  def send(msg: In): Either[MuxError, Unit]
+  def receive(): Either[MuxError, Option[Out]]
+  def offerInbound(msg: Out): Either[MuxError, Unit]
+  def takeOutbound(): Either[MuxError, Option[In]]
+  def halfClose(): Unit
+  def signalRemoteClose(): Unit
+  def isClosed: Boolean
+  def isHalfClosed: Boolean
+  def close(): Unit
+}
+```
+
+The semantics are the same on both versions; only the surface return types differ.
+
+### Factory
+
+```scala
+object Mux {
+  def apply[Id, In, Out](capacity: Int): Mux[Id, In, Out]
+}
+```
+
+### Core Operations
+
+- `open(id)` opens a new stream
+- `get(id)` looks up an active stream
+- `cancel(id, reason)` closes one stream with an error
+- `closeAll(reason)` closes every active stream
+- `activeCount` reports how many streams are open
+
+### Per-stream Operations
+
+- `send(msg)` queues outbound data for the protocol layer
+- `receive()` reads inbound data for user code
+- `offerInbound(msg)` delivers data from the protocol layer
+- `takeOutbound()` drains outbound data for the protocol layer
+- `halfClose()` marks local send as finished
+- `signalRemoteClose()` marks remote send as finished
+- `close()` fully closes the stream immediately; buffered inbound messages can still be drained before the terminal error is observed
+
+### `MuxError`
+
+Error cases:
+
+- `MuxError.StreamClosed(id)`
+- `MuxError.CapacityExceeded(limit)` — maximum concurrent streams reached
+- `MuxError.QueueFull(queueCapacity)` — per-stream message queue is full (backpressure)
+- `MuxError.Cancelled(id, reason)`
+- `MuxError.MuxClosed`
+- `MuxError.ProtocolError(message)` — e.g., null message, invalid state transition
+
+## Examples
+
+### Basic Usage
+
+Scala 3:
+
+```scala
+import zio.blocks.mux.*
+
+val mux = Mux[Int, String, String](capacity = 100)
+
+mux.open(1) match {
+  case stream: MuxStream[Int, String, String] =>
+    stream.offerInbound("hello from peer")
+    val msg = stream.receive() // Some("hello from peer")
+    stream.send("response")
+    val out = stream.takeOutbound() // Some("response")
+  case err: MuxError =>
+    println(s"open failed: $err")
+}
+```
+
+Scala 2 uses the same flow with `Either`:
+
+```scala
+import zio.blocks.mux._
+
+val mux = Mux[Int, String, String](capacity = 100)
+
+mux.open(1) match {
+  case Right(stream) =>
+    stream.offerInbound("hello from peer")
+    val msg = stream.receive() // Right(Some("hello from peer"))
+    stream.send("response")
+    val out = stream.takeOutbound() // Right(Some("response"))
+  case Left(err) =>
+    println(s"open failed: $err")
+}
+```
+
+### HTTP/2-style Multiplexing
+
+```scala
+import zio.blocks.mux.*
+
+final case class Request(path: String)
+final case class Response(status: Int)
+
+val mux = Mux[Int, Request, Response](capacity = 1000)
+
+// Demuxer receives frames, routes by stream ID
+def onFrame(streamId: Int, data: Response): Unit = {
+  mux.get(streamId).foreach(_.offerInbound(data))
+}
+
+// Application opens streams for requests
+mux.open(7) match {
+  case stream: MuxStream[Int, Request, Response] =>
+    stream.send(Request("/docs"))
+
+    // ... later
+    val response = stream.receive()
+    stream.halfClose()
+  case err: MuxError =>
+    println(s"open failed: $err")
+}
+```
+
+In Scala 2, pattern match on `Right(stream)` / `Left(err)` instead.
+
+### Half-close Lifecycle
+
+```scala
+import zio.blocks.mux.*
+
+val mux = Mux[Int, String, String](capacity = 10)
+
+mux.open(1) match {
+  case stream: MuxStream[Int, String, String] =>
+    stream.send("last message")
+    stream.halfClose()
+
+    // Can still receive after half-close
+    val msg = stream.receive()
+
+    // send() after halfClose returns an error
+    stream.send("nope") // MuxError.StreamClosed(1)
+  case err: MuxError =>
+    println(s"open failed: $err")
+}
+```
+
+Scala 2 returns `Left(MuxError.StreamClosed(1))` for the final `send`.
+
+### Graceful Shutdown
+
+```scala
+import zio.blocks.mux.*
+
+val mux = Mux[Int, String, String](capacity = 10)
+
+// Cancel a single stream
+mux.cancel(42, MuxError.Cancelled(42, "timeout"))
+
+// Shut down everything
+mux.closeAll(MuxError.MuxClosed)
+assert(mux.activeCount == 0)
+```
+
+## Architecture
+
+`Mux` keeps a registry of active streams and gives each stream its own inbound and outbound queues. The protocol layer never talks to user code directly, it only moves messages through `offerInbound` and `takeOutbound`.
+
+Half-close models the usual protocol lifecycle:
+
+- local side done sending
+- remote side done sending
+- both sides done, stream fully closed
+
+## Performance
+
+- JVM: `MpscRingBuffer` for inbound and outbound, lock-free and zero-alloc for multi-producer writes
+- JVM: `VarHandle` CAS for stream state transitions
+- JS: `ArrayDeque` fallback
+- No `synchronized`, so it stays friendly to virtual threads
+
+## See Also
+
+- [Streams](streams/index.md) -- the pull-based `Stream`, `Reader`, `Sink`, and `Writer` module. `Mux` is not built on it, but the two are the same concurrency-infrastructure family, and a stream per multiplexed channel is the natural pairing when you are coordinating many keyed streams over one transport.
+- [Async Execution](streams/execution-and-compatibility/async-execution.md) -- how a stream runs without blocking, which is what you want on each side of a `Mux` channel.

package/reference/mux.mdx

@@ -47,13 +47,13 @@ Without multiplexing, protocols must open a new connection per concurrent operat
 Add the dependency to your build:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-mux" % "@VERSION@"
+libraryDependencies += "dev.zio" %% "zio-blocks-mux" % "0.0.55"
 ```
 
 For Scala.js:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-mux" % "@VERSION@"
+libraryDependencies += "dev.zio" %%% "zio-blocks-mux" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x
@@ -821,3 +821,8 @@ val inMux = mux.get(1)
 - JVM: `VarHandle` CAS for stream state transitions
 - JS: `ArrayDeque` fallback
 - No `synchronized`, so it stays friendly to virtual threads
+
+## See Also
+
+- [Streams](streams/index.md) -- the pull-based `Stream`, `Reader`, `Sink`, and `Writer` module. `Mux` is not built on it, but the two are the same concurrency-infrastructure family, and a stream per multiplexed channel is the natural pairing when you are coordinating many keyed streams over one transport.
+- [Async Execution](streams/execution-and-compatibility/async-execution.md) -- how a stream runs without blocking, which is what you want on each side of a `Mux` channel.

package/reference/openapi.md

@@ -27,16 +27,16 @@ The OpenAPI module bridges the gap by letting you author API specs as Scala code
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-openapi" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-openapi" % "0.0.55"
 
 // You'll also need the schema module for Schema[A] integration:
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.55"
 ```
 
 For Scala.js:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-openapi" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-openapi" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.