feature: Compile-check the Book's code examples (and fix 3 doc bugs they caught)

[xerial]

The Book's authoring guide says every non-illustrative snippet must compile against the current uni — but nothing enforced it, so the examples could silently drift as the API evolves. This adds a book-examples module that makes the book self-verifying, and fixes the drift that compiling immediately surfaced.

The module

A JVM-only book-examples project (mirrors the existing netty project pattern; publish / skip, aggregated into the JVM build so CI compiles it). One source file per JVM-runnable chapter — Design, Logging, Data, Rx, Control, HTTP, RPC — using the same APIs as the chapter's snippets. Examples are compiled, not run (servers configured but not started); Ch04TestingTest is a real UniTest suite that also runs.

./sbt bookExamples/Test/compile   # compiles every example
./sbt bookExamples/test           # 3/3 pass

(Chapters 12–15 — Scala.js/Vite and Scala Native FFI — need the JS/Native toolchains and external bundlers, so they're verified against their reference sources instead, as the README notes.)

Doc bugs it caught — all fixed here

1. Resource.withResource does not exist. The real API is Control.withResource / Control.withResources. Fixed in the book (ch08) and control/resource.md (was wrong in 10 places).
2. The JSON access DSL needs import wvlet.uni.json.*. json("user")("name").toStringValue and json / "k" are implicit-class extensions in package object json; import wvlet.uni.json.JSON doesn't bring them into scope. Fixed in the book (ch06) and core/json.md.

These are exactly the kind of copy-paste-breaking errors the module now prevents.

pnpm docs:build passes.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new book-examples module containing compile-checked Scala examples corresponding to chapters in "The Uni Book" to prevent API drift, along with documentation updates to reflect API changes (such as replacing Resource with Control.withResource). Feedback on the changes highlights two issues: first, helper classes in Ch04TestingTest.scala are defined as inner classes, which will cause dependency injection to fail at runtime due to the missing outer class instance; second, the CircuitBreaker in Ch08Control.scala is instantiated inside the combined method, preventing it from maintaining state across invocations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Defining Database, FakeDatabase, and UserService as inner classes of Ch04TestingTest makes them non-static. Since UserService requires an outer instance of Ch04TestingTest for instantiation, Design.build[UserService] will fail at runtime because the DI container cannot satisfy the outer class dependency. Moving these helper classes to a companion object makes them static nested classes, resolving the DI instantiation issue.

class Ch04TestingTest extends UniTest:
  import Ch04TestingTest.*

  test("adds two numbers") {
    val result = 2 + 3
    result shouldBe 5
  }

  test("a list contains a value") {
    Seq("a", "b", "c") shouldContain "b"
  }

  test("looks up a user via a Design override") {
    val appDesign = Design.newDesign
      .bindSingleton[Database]
      .bindSingleton[UserService]

    val testDesign = appDesign + 
      Design.newDesign.bindInstance[Database](FakeDatabase())

    testDesign.build[UserService] { users =>
      users.findUser("123") shouldBe Some("Alice")
    }
  }

object Ch04TestingTest:
  class Database:
    def lookup(id: String): Option[String] = None
  class FakeDatabase extends Database:
    override def lookup(id: String): Option[String] = Some("Alice")
  class UserService(db: Database):
    def findUser(id: String): Option[String] = db.lookup(id)

[gemini-code-assist]

Defining the CircuitBreaker inside the combined method creates a new instance of the breaker on every invocation. A circuit breaker must be shared across multiple calls to maintain its state (failure count, open/closed status) and function correctly. Defining it as a member field of the Ch08Control object ensures the state is preserved across calls, matching the pattern described in the book.

  private val combinedBreaker = CircuitBreaker.withConsecutiveFailures(5)

  def combined(url: String): String =
    combinedBreaker.run {
      Retry.withBackOff(maxRetry = 3).run {
        Control.withResource(openConnection()) { conn =>
          conn.get(url)
        }
      }
    }