@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/maybe.md

@@ -0,0 +1,943 @@
+---
+id: maybe
+title: "Maybe"
+---
+
+`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
+// 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 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 (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.55"
+```
+
+For Scala.js:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-maybe" % "0.0.55"
+```
+
+Supported Scala versions: 2.13.x and 3.x
+
+## Overview
+
+`Maybe[A]` provides a complete set of operations for working with optional values:
+
+- **Constructors**: `Maybe.apply`, `Maybe.present`, `Maybe.absent`, `Maybe.fromOption`
+- **Predicates**: `Maybe#isAbsent`, `isPresent`, `isEmpty`, `isDefined`, `nonEmpty`
+- **Access**: `get`, `Maybe#getOrElse`, `orElse`, `orNull`
+- **Transformations**: `map`, `flatMap`, `flatten`
+- **Filtering**: `filter`, `filterNot`, `collect`
+- **Logical**: `exists`, `forall`, `contains`
+- **Conversions**: `toOption`, `toList`, `toSeq`, `iterator`, `toRight`, `toLeft`
+- **Composition**: `Maybe#zip`, `unzip`, `unzip3`, `fold`, `foreach`
+
+## How It Works
+
+The workflow is straightforward: create a `Maybe` from a value or `None`, transform and filter it using functional operations, extract the result with safe accessors, and fall back to defaults when needed:
+
+```
+Value ─→ Maybe.apply (wrap) ─→ map / flatMap (transform) 
+  ↓                                    ↓
+[null]  ←─────── isAbsent (test) ← filter / collect (refine)
+  ↓                                    ↓
+absent ─→ orElse (fallback) ─→ get / getOrElse (extract)
+```
+
+### Typical Data Flow
+
+1. **Create** a `Maybe` using `Maybe.apply`, `Maybe.present`, `Maybe.fromOption`, or explicitly with `Maybe.absent` for no value
+2. **Transform** values using `map` or `flatMap` — operations on absent values short-circuit and remain absent
+3. **Filter** with `filter` or `collect` to refine the value or produce absence based on a predicate
+4. **Compose** with other `Maybe` values using `Maybe#zip` or flatMap chains to build complex workflows
+5. **Extract** the result using `get` (throws on absence), `Maybe#getOrElse` (provides a default), `toOption` (convert to `Option`), or `fold` (handle both branches)
+
+## Common Patterns
+
+Here are key patterns for working effectively with `Maybe`:
+
+### Present and Absent States
+
+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._
+
+val value: Maybe[Int] = Maybe.present(42)
+
+if (value.isPresent) {
+  println(value.get) // Safe: we know it's present
+} else {
+  println("No value")
+}
+```
+
+### Safe Extraction with Defaults
+
+Use `Maybe#getOrElse` to provide a fallback when the value is absent, avoiding the exception risk of `get`:
+
+```scala
+import zio.blocks.maybe._
+
+val userId: Maybe[String] = Maybe.absent
+val name = userId.getOrElse("anonymous")
+```
+
+### Chaining Transformations
+
+Combine `map` and `flatMap` to thread operations through optional values. Absence propagates automatically:
+
+```scala
+import zio.blocks.maybe._
+
+val userId: Maybe[Int] = Maybe.present(123)
+
+val greeting = userId
+  .map(id => s"User $id")
+  .map(msg => s"Hello, $msg!")
+
+println(greeting) // Maybe[String] containing "Hello, User 123!"
+```
+
+### Filtering with Predicates
+
+Use `filter` to keep a value only if it satisfies a condition, or `collect` with a partial function for both filtering and transformation:
+
+```scala
+import zio.blocks.maybe._
+
+val age: Maybe[Int] = Maybe.present(25)
+
+val isAdult = age.filter(_ >= 18) // Maybe[Int] containing 25
+val isChild = age.filter(_ < 18)  // Maybe[Int] absent
+```
+
+### Combining Multiple Maybes
+
+Use `Maybe#zip` to combine two `Maybe` values into a tuple, or chain multiple operations with `flatMap`:
+
+```scala
+import zio.blocks.maybe._
+
+val firstName: Maybe[String] = Maybe.present("Alice")
+val lastName: Maybe[String]  = Maybe.present("Smith")
+
+val fullName = firstName.zip(lastName).map { case (f, l) => s"$f $l" }
+```
+
+### Converting to and from Option
+
+Interoperate seamlessly with `Option` using `toOption` and `Maybe#fromOption`:
+
+```scala
+import zio.blocks.maybe._
+
+val opt: Option[String] = Some("value")
+val m: Maybe[String]    = Maybe.fromOption(opt)
+val backToOpt           = m.toOption
+```
+
+### Handling Errors with Either
+
+Convert a `Maybe` to an `Either` to propagate errors in fail-fast computations:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+
+val result: Either[String, Int] = value.toRight("Value not found")
+```
+
+## Integration Points
+
+`Maybe[A]` integrates with the broader Scala and ZIO ecosystem:
+
+- **Option interoperability**: Convert bidirectionally with `toOption` and `Maybe#fromOption`; a `Conversion[Option[A], Maybe[A]]` is provided for implicit conversions
+- **Schema support**: Schema codecs use private unsafe methods (`unsafeIsAbsent`, `unsafeGet`, `unsafeWrap`) for efficient serialization and deserialization
+- **For-comprehensions**: Supports `withFilter` for guard clauses in for-expressions
+- **Collections**: Convert to `List`, `Seq`, or `Iterator` for bulk operations
+- **Pattern matching**: Works naturally in match expressions, though testing with predicates is more common
+
+### Example: For-Comprehension with Guards
+
+Combine multiple `Maybe` values with filter guards:
+
+```scala
+import zio.blocks.maybe._
+
+val maybeX: Maybe[Int] = Maybe.present(5)
+val maybeY: Maybe[Int] = Maybe.present(10)
+
+val result = for {
+  x <- maybeX
+  y <- maybeY
+  if x + y > 10
+} yield x + y
+
+println(result) // Maybe[Int] containing 15
+```
+
+## Operations Reference
+
+All `Maybe` operations are organized by category. Each subsection documents a group of related methods with examples.
+
+### Constructors
+
+Create `Maybe` values using these factory methods:
+
+#### Maybe.apply
+
+Wraps a value in `Maybe`, treating `null` as `Maybe.absent`:
+
+```scala
+import zio.blocks.maybe._
+
+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 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:
+
+```scala
+import zio.blocks.maybe._
+
+val empty: Maybe[String] = Maybe.absent
+```
+
+#### Maybe.empty
+
+Alias for `Maybe.absent`:
+
+```scala
+import zio.blocks.maybe._
+
+val empty: Maybe[Double] = Maybe.empty
+```
+
+#### Maybe.fromOption
+
+Converts an `Option` to `Maybe`:
+
+```scala
+import zio.blocks.maybe._
+
+val fromSome = Maybe.fromOption(Some(5))  // Maybe[Int] containing 5
+val fromNone = Maybe.fromOption(None)     // Maybe[Nothing] absent
+```
+
+### State Testing
+
+Test whether a `Maybe` is present or absent:
+
+#### isPresent, isDefined, nonEmpty
+
+All three are equivalent—return true if the value is non-null:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(42)
+println(value.isPresent)  // true
+println(value.isDefined)  // true
+println(value.nonEmpty)   // true
+```
+
+#### isAbsent, isEmpty
+
+Both return true if the value is `null`:
+
+```scala
+import zio.blocks.maybe._
+
+val empty: Maybe[Int] = Maybe.absent
+println(empty.isAbsent)  // true
+println(empty.isEmpty)   // true
+```
+
+### Access
+
+Retrieve the value or provide a fallback:
+
+#### get
+
+Unwraps the value, throwing `NoSuchElementException` if absent:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+println(value.get)  // 10
+
+try {
+  Maybe.absent[Int].get
+} catch {
+  case e: NoSuchElementException => println(e.getMessage)  // "Maybe.absent.get"
+}
+```
+
+#### getOrElse
+
+Returns the value if present, or evaluates the default:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int]    = Maybe.absent
+val withDefault: Int     = value.getOrElse(99)
+println(withDefault)  // 99
+```
+
+#### orElse
+
+Returns the current `Maybe` if present, or another `Maybe`:
+
+```scala
+import zio.blocks.maybe._
+
+val first: Maybe[Int]  = Maybe.absent
+val second: Maybe[Int] = Maybe.present(42)
+val result = first.orElse(second)
+println(result.get)  // 42
+```
+
+#### orNull
+
+Converts to nullable, returning the value or `null`:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[String] = Maybe.absent
+val nullable: String = value.orNull
+println(nullable)  // null
+```
+
+### Transformations
+
+Transform values or short-circuit on absence:
+
+#### map
+
+Applies a function if present, remains absent otherwise:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int]      = Maybe.present(5)
+val doubled: Maybe[Int]    = value.map(_ * 2)
+val absent: Maybe[String]  = Maybe.absent.map(_ => "never runs")
+println(doubled.get)  // 10
+println(absent.isAbsent)  // true
+```
+
+#### flatMap
+
+Chains operations that return `Maybe`, flattening the result:
+
+```scala
+import zio.blocks.maybe._
+
+def safeDivide(a: Int, b: Int): Maybe[Int] =
+  if (b == 0) Maybe.absent else Maybe(a / b)
+
+val result = Maybe.present(10).flatMap(safeDivide(_, 2))
+println(result.get)  // 5
+
+val divideByZero = Maybe.present(10).flatMap(safeDivide(_, 0))
+println(divideByZero.isAbsent)  // true
+```
+
+#### flatten
+
+Unwraps a nested `Maybe`:
+
+```scala
+import zio.blocks.maybe._
+
+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
+
+Keep or discard values based on predicates:
+
+#### filter
+
+Keeps the value only if the predicate is true:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+val even = value.filter(_ % 2 == 0)  // Present: 10
+val odd  = value.filter(_ % 2 != 0)  // Absent
+println(even.get)  // 10
+println(odd.isAbsent)  // true
+```
+
+#### filterNot
+
+Inverse of `filter`—keeps the value if the predicate is false:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int]   = Maybe.present(5)
+val notOdd: Maybe[Int]  = value.filterNot(_ % 2 != 0)
+println(notOdd.isAbsent)  // true
+```
+
+#### collect
+
+Combines filtering with transformation using a partial function:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(8)
+val result = value.collect { case n if n % 2 == 0 => s"even: $n" }
+println(result.get)  // "even: 8"
+
+val odd: Maybe[Int]     = Maybe.present(7)
+val noMatch: Maybe[String] = odd.collect { case n if n % 2 == 0 => s"even: $n" }
+println(noMatch.isAbsent)  // true
+```
+
+### Logical Predicates
+
+Test conditions without extracting the value:
+
+#### contains
+
+Returns true if the value equals the given element:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(42)
+println(value.contains(42))  // true
+println(value.contains(41))  // false
+println(Maybe.absent[Int].contains(42))  // false
+```
+
+#### exists
+
+Returns true if the value satisfies the predicate:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+println(value.exists(_ > 5))   // true
+println(value.exists(_ > 20))  // false
+println(Maybe.absent[Int].exists(_ => true))  // false
+```
+
+#### forall
+
+Returns true if the value satisfies the predicate, or if absent (vacuous truth):
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+println(value.forall(_ > 5))   // true
+println(value.forall(_ > 20))  // false
+println(Maybe.absent[Int].forall(_ => false))  // true (absent = vacuously true)
+```
+
+### Iteration and Conversion
+
+Convert `Maybe` to other types or iterate its contents:
+
+#### foreach
+
+Executes a side effect if present:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(42)
+value.foreach(x => println(s"Value: $x"))
+
+Maybe.absent[Int].foreach(_ => println("not called"))
+```
+
+#### toOption
+
+Converts to `Option[A]`:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int]     = Maybe.present(7)
+val some: Option[Int]     = value.toOption
+val noneVal: Option[Int]  = Maybe.absent[Int].toOption
+println(some)  // Some(7)
+println(noneVal)  // None
+```
+
+#### toList
+
+Converts to `List[A]`:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int]   = Maybe.present(5)
+val list: List[Int]     = value.toList
+val emptyList: List[Int] = Maybe.absent[Int].toList
+println(list)  // List(5)
+println(emptyList)  // List()
+```
+
+#### toSeq
+
+Converts to `Seq[A]`:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[String] = Maybe.present("hello")
+val seq: Seq[String]     = value.toSeq
+println(seq)  // Seq("hello")
+```
+
+#### iterator
+
+Creates an iterator over the value:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(42)
+val it = value.iterator
+println(it.toList)  // List(42)
+
+Maybe.absent[Int].iterator.toList  // List()
+```
+
+### Either Conversion
+
+Convert `Maybe` to `Either` for error handling:
+
+#### toRight
+
+Converts to `Either[X, A]` with a left error value:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+val right: Either[String, Int] = value.toRight("not found")
+println(right)  // Right(10)
+
+val absent: Maybe[Int]         = Maybe.absent
+val left: Either[String, Int]  = absent.toRight("not found")
+println(left)  // Left("not found")
+```
+
+#### toLeft
+
+Converts to `Either[A, X]` with a right success value:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[String] = Maybe.present("error")
+val left: Either[String, Unit] = value.toLeft(())
+println(left)  // Left("error")
+
+val absent: Maybe[String]      = Maybe.absent
+val right: Either[String, Unit] = absent.toLeft(())
+println(right)  // Right(())
+```
+
+### Composition
+
+Combine multiple `Maybe` values:
+
+#### zip
+
+Combines two `Maybe` values into a tuple:
+
+```scala
+import zio.blocks.maybe._
+
+val x: Maybe[Int]    = Maybe.present(1)
+val y: Maybe[String] = Maybe.present("a")
+val tuple = x.zip(y)
+println(tuple.get)  // (1, "a")
+
+val absent: Maybe[String] = Maybe.absent
+val zipped = x.zip(absent)
+println(zipped.isAbsent)  // true
+```
+
+#### unzip
+
+Splits a `Maybe[(A, B)]` into a tuple of `Maybe[A]` and `Maybe[B]`:
+
+```scala
+import zio.blocks.maybe._
+
+val tuple: Maybe[(Int, String)] = Maybe.present((42, "answer"))
+val (x, y) = tuple.unzip
+println(x.get)  // 42
+println(y.get)  // "answer"
+
+val absent: Maybe[(Int, String)] = Maybe.absent
+val (ax, ay) = absent.unzip
+println(ax.isAbsent && ay.isAbsent)  // true
+```
+
+#### unzip3
+
+Splits a `Maybe[(A, B, C)]` into three `Maybe` values:
+
+```scala
+import zio.blocks.maybe._
+
+val triple: Maybe[(Int, String, Double)] = Maybe.present((1, "one", 1.0))
+val (a, b, c) = triple.unzip3
+println(a.get)  // 1
+println(b.get)  // "one"
+println(c.get)  // 1.0
+```
+
+### Folding
+
+Reduce a `Maybe` to a value by handling both branches:
+
+#### fold
+
+Applies one of two functions based on presence:
+
+```scala
+import zio.blocks.maybe._
+
+val value: Maybe[Int] = Maybe.present(10)
+val result = value.fold(-1)((x: Int) => x * 2)
+println(result)  // 20
+
+val absent: Maybe[Int] = Maybe.absent
+val fallback = absent.fold(-1)((x: Int) => x * 2)
+println(fallback)  // -1
+```
+
+### For-Comprehensions
+
+Use `withFilter` to support guard clauses:
+
+#### withFilter
+
+Enables guarded for-expressions:
+
+```scala
+import zio.blocks.maybe._
+
+val x: Maybe[Int] = Maybe.present(5)
+val y: Maybe[Int] = Maybe.present(15)
+
+val result = for {
+  a <- x
+  b <- y
+  if a + b > 15
+} yield a + b
+
+println(result.get)  // 20
+```
+
+## Running Examples
+
+End-to-end workflows combining multiple `Maybe` operations:
+
+### Example: Parsing and Transforming User Input
+
+Build a pipeline that parses user input, validates it, and transforms the result:
+
+```scala
+import zio.blocks.maybe._
+
+case class User(id: Int, name: String, age: Int)
+
+def parseId(input: String): Maybe[Int] =
+  Maybe.fromOption(input.toIntOption)
+
+def validateAge(age: Int): Maybe[Int] =
+  Maybe.absent[Int].orElse(
+    if (age >= 0 && age <= 150) Maybe.present(age) else Maybe.absent
+  )
+
+val input = "42"
+val processedAge = parseId(input)
+  .flatMap(id => Maybe.present(User(id, "Alice", 30)))
+  .map(_.age)
+  .flatMap(validateAge)
+
+println(processedAge.getOrElse(-1))  // 30
+```
+
+### Example: Chaining Optional Database Results
+
+Work with nullable database results, filtering and transforming as needed:
+
+```scala
+import zio.blocks.maybe._
+
+case class Product(id: Int, name: String, price: Double, inStock: Boolean)
+
+def findProduct(id: Int): Maybe[Product] =
+  if (id > 0) Maybe.present(Product(id, s"Product $id", 99.99, true))
+  else Maybe.absent
+
+def applyDiscount(product: Product, percent: Int): Maybe[Product] =
+  if (percent >= 0 && percent <= 100)
+    Maybe.present(product.copy(price = product.price * (1 - percent / 100.0)))
+  else Maybe.absent
+
+val discountedProduct = findProduct(123)
+  .filter(_.inStock)
+  .flatMap(applyDiscount(_, 20))
+  .map(p => s"${p.name} now costs $$${p.price}")
+
+println(discountedProduct.getOrElse("Product not available"))
+```
+
+### Example: Combining Multiple Maybes with Fallbacks
+
+Handle scenarios where multiple optional values need to be combined:
+
+```scala
+import zio.blocks.maybe._
+
+case class Config(host: Maybe[String], port: Maybe[Int], timeout: Maybe[Long])
+
+def buildConnection(config: Config): String = {
+  val host = config.host.getOrElse("localhost")
+  val port = config.port.getOrElse(8080)
+  val timeout = config.timeout.getOrElse(5000L)
+  s"Connection to $host:$port with timeout $timeout ms"
+}
+
+val config = Config(
+  host = Maybe.present("api.example.com"),
+  port = Maybe.absent,
+  timeout = Maybe.present(10000L)
+)
+
+println(buildConnection(config))
+```
+
+### Example: Error Handling with Either Conversion
+
+Convert `Maybe` to `Either` for composable error handling in result types:
+
+```scala
+import zio.blocks.maybe._
+
+case class Request(id: Maybe[String], method: Maybe[String])
+
+def validateRequest(req: Request): Either[String, (String, String)] = {
+  for {
+    id <- req.id.toRight("Missing request ID")
+    method <- req.method.toRight("Missing HTTP method")
+  } yield (id, method)
+}
+
+val validReq = Request(
+  id = Maybe.present("req-123"),
+  method = Maybe.present("GET")
+)
+
+val invalidReq = Request(
+  id = Maybe.absent,
+  method = Maybe.present("POST")
+)
+
+println(validateRequest(validReq))  // Right((req-123, GET))
+println(validateRequest(invalidReq))  // Left(Missing request ID)
+```
+
+### Example: Building a Computation Pipeline
+
+Chain multiple transformations with fallback at each step:
+
+```scala
+import zio.blocks.maybe._
+
+def getUser(id: Int): Maybe[String] =
+  if (id > 0) Maybe.present(s"user_$id") else Maybe.absent
+
+def getUserEmail(username: String): Maybe[String] =
+  if (username.nonEmpty) Maybe.present(s"$username@example.com") else Maybe.absent
+
+def getUserProfile(id: Int): Maybe[String] = {
+  val username = getUser(id)
+  username
+    .flatMap(getUserEmail)
+    .map(email => s"Profile for $email")
+    .orElse(Maybe.present("Guest user"))
+}
+
+println(getUserProfile(42))  // Profile for user_42@example.com
+println(getUserProfile(-1))  // Guest user
+```