@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/endpoint/path-codec.md

@@ -0,0 +1,225 @@
+---
+id: path-codec
+title: "PathCodec"
+---
+
+`PathCodec[A]` is a composable descriptor for URL path structures. It holds a tree of segment codecs connected by concatenation and fallback nodes, and provides bidirectional path conversion: `PathCodec#decode` extracts a typed value from a `Path`, returning `Either[String, A]` (the typed value or error), and `PathCodec#format` formats a typed value back to a `Path`, returning `Either[String, Path]` (the path or error). Its definition begins:
+
+```scala
+sealed trait PathCodec[A]
+```
+
+## Motivation
+
+URL paths need both matching and generation. A routing library that only matches paths requires a separate URL-builder for links and redirects, leading to duplication and drift. `PathCodec` is bidirectional: every codec that can decode `/users/42` into `42: Int` can also format `42` back into `/users/42`. This makes it safe to use the same path definition for routing, link generation, and OpenAPI path parameter documentation.
+
+## Structure
+
+`PathCodec` is an ADT with four node types:
+
+| Node        | Meaning                                                        |
+| ----------- | -------------------------------------------------------------- |
+| `Segment`   | A single path segment, described by a `SegmentCodec[A]`        |
+| `Concat`    | Two path codecs composed sequentially with `/` or `++`         |
+| `Transform` | Bidirectional type mapping over an existing codec              |
+| `Fallback`  | Two literal alternatives (applies only with `orElse`)          |
+
+## Construction
+
+We build a `PathCodec` from smart constructors that produce typed segment nodes, from a path string, or by wrapping a `SegmentCodec` directly.
+
+### Predefined segment constructors
+
+The most common path building blocks are available as smart constructors on the companion:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val literalUsers: PathCodec[Unit]          = PathCodec.literal("users")
+val intId: PathCodec[Int]                  = PathCodec.int("id")
+val longId: PathCodec[Long]               = PathCodec.long("id")
+val stringSlug: PathCodec[String]         = PathCodec.string("slug")
+val uuidId: PathCodec[java.util.UUID]     = PathCodec.uuid("id")
+val boolFlag: PathCodec[Boolean]          = PathCodec.bool("enabled")
+val rest: PathCodec[zio.http.Path]        = PathCodec.trailing
+```
+
+`PathCodec.literal` validates the value — it rejects empty strings and strings containing `/` or characters requiring URL encoding.
+
+### From a string
+
+To build a codec from a slash-separated string of literal segments, use `PathCodec.apply`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val path: PathCodec[Unit] = PathCodec("/api/v1/users")
+```
+
+This is equivalent to concatenating `PathCodec.literal` for each segment.
+
+### From a `SegmentCodec`
+
+To wrap a custom `SegmentCodec[A]` into a `PathCodec[A]`, use `PathCodec.apply(segment)`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val combined = PathCodec(SegmentCodec.literal("v") ~ SegmentCodec.int("version"))
+```
+
+There is also an implicit conversion from `SegmentCodec[A]` to `PathCodec[A]` and from `String` to `PathCodec[Unit]`, so both can appear directly in `/` expressions.
+
+## Marking a capture as unused with `.unused`
+
+Sometimes a route needs to capture a segment for matching or formatting, but a downstream handler intentionally does not consume that variable. `PathCodec` instances expose `.unused`, which converts the value type to `Unit` while keeping the same path shape:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val userId: PathCodec[Int] = PathCodec.int("id")
+val ignoredUserId: PathCodec[Unit] = PathCodec.int("id").unused
+```
+
+`.unused` converts the path codec's value type to `Unit`: the route still matches the same shape and renders `{name}` placeholders, but decoding yields `Unit` instead of the captured value, so no handler parameter is required. `format` on an unused path fails because there is no value to encode back into the ignored segment.
+
+`PathCodec.unused` composes normally with `/` and is unaffected by `transform` / `transformOrFail` lifting.
+
+## Composition
+
+Path codecs compose in two ways: sequential concatenation with `/` or `++`, and literal alternatives with `orElse`.
+
+### Sequential composition with `/` and `++`
+
+`/` and `++` are equivalent: both concatenate two path codecs. The result type is flattened automatically (so `Unit / Int` gives `Int`, not `(Unit, Int)`), eliminating `Unit` components:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val route: PathCodec[Int] = PathCodec.literal("users") / PathCodec.int("id")
+```
+
+In the context of a `RoutePattern`, the same operator works directly:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val pattern = Method.GET / "users" / PathCodec.int("id") / "posts"
+```
+
+### Literal alternatives with `orElse`
+
+To match either of two literal segments, use `orElse`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val either: PathCodec[Unit] =
+  PathCodec.literal("users").orElse(PathCodec.literal("members"))
+```
+
+`orElse` is for literal alternatives only. Both branches must be `PathCodec[Unit]` with no captured path variables, and `PathCodec#alternatives` still validates at runtime that the branches are genuinely literal-only. In practice, use `orElse` only with `PathCodec.literal(...)` or string-literal path codecs.
+
+## Decoding and Formatting
+
+`PathCodec` is bidirectional: `PathCodec#decode` turns a runtime `Path` into a typed value, and `PathCodec#format` turns a typed value back into a `Path`.
+
+### `PathCodec#decode`
+
+To extract a typed value from a runtime `Path`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Path
+
+val codec = PathCodec.int("id")
+
+val result: Either[String, Int] = codec.decode(Path("/42"))
+```
+
+`PathCodec#decode` returns `Left(message)` when no segment matches or a segment cannot be parsed.
+
+### `PathCodec#format`
+
+To turn a typed value into a `Path`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Path
+
+val codec = PathCodec.uuid("id")
+
+val path: Either[String, Path] =
+  codec.format(java.util.UUID.fromString("550e8400-e29b-41d4-a716-446655440000"))
+```
+
+### `PathCodec#matches`
+
+To test whether a `Path` matches without extracting a value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Path
+
+val codec   = PathCodec.literal("users")
+val matched = codec.matches(Path("/users"))
+```
+
+## Type Transformations
+
+Use these methods to map the typed value that `PathCodec` decodes or encodes without changing the underlying path structure.
+
+### `PathCodec#transform`
+
+To map the decoded value to a different type without changing the path structure, use `PathCodec#transform`. Both directions must be total:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.endpoint.PathCodec._
+
+final case class UserId(value: Int)
+
+val userIdCodec: PathCodec[UserId] =
+  PathCodec.int("id").transform(UserId(_), _.value)
+```
+
+### `PathCodec#transformOrFail`
+
+When decoding or encoding can fail, use `PathCodec#transformOrFail`. A `Left` from the decode function causes the path not to match:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val nonNegativeInt: PathCodec[Int] =
+  PathCodec.int("count").transformOrFail(
+    n => if (n >= 0) Right(n) else Left(s"Expected non-negative, got $n"),
+    (n: Int) => Right(n)
+  )
+```
+
+## Rendering
+
+`PathCodec#render` produces a human-readable path string. Dynamic segments appear as `{name}` by default:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val codec = PathCodec.literal("users") / PathCodec.int("id")
+val rendered: String = codec.render
+```
+
+To use a different prefix/suffix for dynamic segments (e.g., `:id` for Express-style paths), call the lower-level `PathCodec.render(codec, prefix = ":", suffix = "")`.

package/reference/endpoint/route-pattern.md

@@ -0,0 +1,194 @@
+---
+id: route-pattern
+title: "RoutePattern"
+---
+
+`RoutePattern[A]` pairs an HTTP method with a typed path pattern. It is the primary routing descriptor in `zio-blocks-endpoint`: every `Endpoint` carries a `RoutePattern` that determines which HTTP method and URL path it matches. Its shape is:
+
+```scala
+final case class RoutePattern[A](
+  method: Method,
+  pathCodec: PathCodec[A],
+  doc: Doc = Doc.empty
+)
+```
+
+## Motivation
+
+HTTP routing requires matching both a method (GET, POST, …) and a path (`/users/42`). `RoutePattern` holds both in a single typed value. The type parameter `A` is the type of values extracted from the dynamic path segments — `Unit` for fully-literal paths, `Int` for a single integer segment, `(String, UUID)` for two dynamic segments, and so on.
+
+Using a typed route pattern means route construction and path extraction are verified at compile time: the type of the extracted path value is always consistent with the path codec definition.
+
+## Construction
+
+Several construction forms exist. The method-first syntax is the most common and most readable; the others cover less typical use cases.
+
+### Method-first syntax (recommended)
+
+The primary syntax uses the `Method` extension method `/` to produce a `RoutePattern` directly:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val getUsers    = Method.GET / "users"
+val postUser    = Method.POST / "users"
+val deleteOrder = Method.DELETE / "orders" / PathCodec.uuid("orderId")
+```
+
+This is the recommended construction style: it reads like the route itself and keeps the method close to the path.
+
+### Constant constructors
+
+Pre-built method-only patterns are available as constants on the `RoutePattern` companion:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+
+val get     = RoutePattern.GET
+val post    = RoutePattern.POST
+val put     = RoutePattern.PUT
+val delete  = RoutePattern.DELETE
+val patch   = RoutePattern.PATCH
+val head    = RoutePattern.HEAD
+val options = RoutePattern.OPTIONS
+```
+
+These are equivalent to `RoutePattern(Method.GET)` etc., with an empty path codec. Additional constants like `CONNECT` and `TRACE` are also available for the complete set of HTTP methods.
+
+### From a `Path` value
+
+To construct a pattern from a runtime `Path` (all literal segments), use `RoutePattern.apply(method, path)`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val route = RoutePattern(Method.GET, Path("/users/active"))
+```
+
+### Catch-all trailing patterns
+
+To match any path suffix, use `RoutePattern.any`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val catchAll: RoutePattern[Path]   = RoutePattern.any
+val getAny: RoutePattern[Path]     = RoutePattern.any(Method.GET)
+```
+
+A trailing catch-all captures a `zio.http.Path` runtime value without declaring any named path variables.
+
+## Path Composition with `/`
+
+To append additional `PathCodec` segments to a `RoutePattern`, use the `/` method:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val route = Method.GET / "users" / PathCodec.int("id") / "posts"
+```
+
+Each `/` call produces a new `RoutePattern` with a widened type. The type is automatically flattened, eliminating `Unit` components: `Unit / Int / Unit` becomes `Int`, not `((Unit, Int), Unit)`.
+
+## Decoding and Encoding
+
+`RoutePattern` is bidirectional: `RoutePattern#decode` validates a live request against the pattern, and `RoutePattern#encode` rebuilds a request pair from a typed path value.
+
+### `RoutePattern#decode`
+
+To check whether a method and path match, and extract the typed path value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val route = Method.GET / "users" / PathCodec.int("id")
+
+val result: Either[String, Int] = route.decode(Method.GET, Path("/users/42"))
+```
+
+`RoutePattern#decode` returns `Left` if the method does not match or any segment fails to parse, and `Right(value)` with the extracted path value otherwise. HEAD requests automatically fall back to GET for compatibility.
+
+### `RoutePattern#encode`
+
+To turn a typed value back into a `(Method, Path)` pair:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val route = Method.POST / "orders" / PathCodec.uuid("orderId")
+
+val result: Either[String, (Method, Path)] = route.encode(java.util.UUID.fromString("550e8400-e29b-41d4-a716-446655440000"))
+```
+
+### `RoutePattern#matches`
+
+To test membership without extracting the value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val route   = Method.GET / "users"
+val matches = route.matches(Method.GET, Path("/users"))
+```
+
+## Structural Operations
+
+Three structural operations transform an existing `RoutePattern` without building a new one from scratch: `RoutePattern#alternatives`, `RoutePattern#nest`, and `RoutePattern#render`.
+
+### Alternatives
+
+`RoutePattern#alternatives` expands `Method.ANY` and `Method.Methods` into a flat list of single-method patterns. `RouteTree` calls this before inserting into the trie:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val anyGet: RoutePattern[?] = RoutePattern.any(Method.GET)
+val expanded = anyGet.alternatives
+```
+
+### Nesting
+
+`RoutePattern#nest` prepends a literal path prefix without modifying the route's type or dynamic segments:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val route   = Method.GET / "users" / PathCodec.int("id")
+val versioned = route.nest(PathCodec("/api/v1"))
+```
+
+This is useful for adding a version prefix to a group of existing routes without rewriting each one.
+
+### Rendering
+
+`RoutePattern#render` produces a human-readable string representation, useful for logging and OpenAPI path generation:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val route = Method.GET / "users" / PathCodec.int("id")
+val rendered: String = route.render
+```
+
+Dynamic segments are rendered as `{name}` by default, matching OpenAPI path parameter convention.

package/reference/endpoint/route-tree.md

@@ -0,0 +1,111 @@
+---
+id: route-tree
+title: "RouteTree"
+---
+
+`RouteTree[A]` is a routing trie keyed by HTTP method and path. It maps `(Method, Path)` pairs to values of type `A`, performing prefix-tree lookup with segment-priority ordering. Server-side interpreters primarily use it to build efficient route dispatch tables from a collection of `RoutePattern` values. Its structure is:
+
+```scala
+final case class RouteTree[A](
+  roots: Map[Method, SegmentSubtree[A]]
+)
+```
+
+`SegmentSubtree[A]` is a single level of the trie, holding literal-keyed branches and priority-ordered dynamic segment branches:
+
+```scala
+final case class SegmentSubtree[A](
+  literals: Map[String, SegmentSubtree[A]],
+  others: ListMap[SegmentCodec.Key, (SegmentCodec[_], SegmentSubtree[A])],
+  value: Option[A]
+)
+```
+
+## Motivation
+
+Routing a `(Method, Path)` pair to a handler requires checking many patterns efficiently. A flat scan through all routes is O(n) and scales poorly. `RouteTree` uses a prefix trie keyed on path segments, so matching is O(depth) — proportional to the number of segments in the path, not the number of registered routes.
+
+Within each trie level, literal segments are stored in a `Map[String, ...]` for O(1) lookup, while dynamic segments are stored in a `ListMap` ordered by match priority. The priority order (literal → int → long → uuid → bool → string → combined → trailing) ensures that more specific segments win ambiguous matches.
+
+## Building a `RouteTree`
+
+Start from an empty tree and add patterns with `RouteTree#add`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val tree = RouteTree.empty[String]
+  .add(Method.GET / "users", "list-users")
+  .add(Method.GET / "users" / PathCodec.int("id"), "get-user")
+  .add(Method.POST / "users", "create-user")
+```
+
+`RouteTree#add` calls `RoutePattern#alternatives` internally to expand `Method.ANY` and `Method.Methods` into individual method entries before inserting into the trie.
+
+## Lookup
+
+`RouteTree#get` looks up a `(Method, Path)` pair and returns the associated value if a match is found:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Path}
+
+val tree = RouteTree.empty[String]
+  .add(Method.GET / "users" / PathCodec.int("id"), "get-user")
+
+val result: Option[String] = tree.get(Method.GET, Path("/users/42"))
+```
+
+HEAD requests automatically fall back to the GET subtree if no HEAD handler is registered, matching the HTTP specification.
+
+## Merging
+
+`RouteTree#merge` combines two trees. On conflicts, the right-hand-side value takes precedence:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val treeA = RouteTree.empty[String].add(Method.GET / "users", "users-v1")
+val treeB = RouteTree.empty[String].add(Method.GET / "users", "users-v2")
+
+val merged = treeA.merge(treeB)
+// GET /users → "users-v2"
+```
+
+## Mapping
+
+`RouteTree#map` transforms all values in the trie while preserving its structure:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val tree: RouteTree[String] = RouteTree.empty[String]
+  .add(Method.GET / "users", "get-users")
+
+val lengths: RouteTree[Int] = tree.map(_.length)
+```
+
+## Match Priority
+
+Within a single trie level, `SegmentSubtree` tries literal branches first, then dynamic branches in priority order. Given a path like `/users/active`:
+
+1. `literals.get("active")` is tried first — if an exact literal route for `"active"` exists, it matches.
+2. Otherwise, dynamic segment codecs are tried in order: `Int` (fails, `"active"` is not numeric), `Long` (fails), `UUID` (fails), `Bool` (fails), `String` (succeeds).
+
+This means `/users/42` matches an `Int` route even if a `String` route is also registered, because integers are higher priority than strings.
+
+## `SegmentSubtree`
+
+`SegmentSubtree` is the internal per-level trie node. It is not typically constructed directly — `RouteTree#add` builds it internally. The two key fields are:
+
+- **`literals`**: a `Map[String, SegmentSubtree[A]]` for O(1) exact-match lookups.
+- **`others`**: a `ListMap[SegmentCodec.Key, (SegmentCodec[_], SegmentSubtree[A])]` ordered by priority for dynamic segment matching.
+
+The `value: Option[A]` field holds the registered value when a complete path terminates at this node. Trailing segments have special handling: if a `Trailing` codec is registered and the current index is past the end of the path segments, the lookup returns its subtree value.