@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/sql/sql-name-mapper.md

@@ -41,7 +41,7 @@ SqlNameMapper.Identity("firstName")
 
 val upper = SqlNameMapper.Custom(_.toUpperCase)
 // upper: Custom = Custom(
-//   repl.MdocSession$MdocApp0$$Lambda$20339/0x00007f2996f5b000@1850c853
+//   repl.MdocSession$MdocApp0$$Lambda/0x000000003afd1000@5050da69
 // )
 upper("firstName")
 // res4: String = "FIRSTNAME"
@@ -58,9 +58,9 @@ object Order { given schema: Schema[Order] = Schema.derived }
 
 // Use UPPERCASE column names instead of snake_case
 val upperDeriver = DbCodecDeriver.withColumnNameMapper(SqlNameMapper.Custom(_.toUpperCase))
-// upperDeriver: DbCodecDeriver = zio.blocks.sql.DbCodecDeriver@646cca72
+// upperDeriver: DbCodecDeriver = zio.blocks.sql.DbCodecDeriver@282873df
 val codec: DbCodec[Order] = Order.schema.deriving(upperDeriver).derive
-// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$20@596dacd
+// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$10@6838c076
 codec.columns
 // res6: IndexedSeq[String] = Vector("ORDERID", "TOTALAMOUNT")
 ```

package/reference/sql/table-metadata.md

@@ -80,7 +80,7 @@ import zio.blocks.sql.{Table, TableNamingPolicy}
 val table1 = Table.derived[Product]
 // table1: Table[Product] = Table(
 //   name = "product",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@40f5588b,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@30880538,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
@@ -94,7 +94,7 @@ table1.name
 val table2 = Table.derived[Product](TableNamingPolicy.Plural)
 // table2: Table[Product] = Table(
 //   name = "products",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@13590a4,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@504beffa,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
@@ -108,7 +108,7 @@ table2.name
 val table3 = Table.derived[Product](TableNamingPolicy.Custom("t_" + _))
 // table3: Table[Product] = Table(
 //   name = "t_Product",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@2fa45824,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@32e4f8e3,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),

package/reference/sql/table.md

@@ -46,7 +46,7 @@ object User {
 val table = Table.derived[User]("users")
 // table: Table[User] = Table(
 //   name = "users",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@178274d,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@6651357c,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
@@ -97,7 +97,7 @@ object BlogPost {
 val table = Table.derived[BlogPost]
 // table: Table[BlogPost] = Table(
 //   name = "blog_post",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@56665516,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@6d450c2f,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "title", dbValue = DbString(""), nullable = false),
 //     ColumnMeta(name = "body", dbValue = DbString(""), nullable = false)
@@ -133,7 +133,7 @@ object UserProfile {
 val table = Table.derived[UserProfile]("profiles")
 // table: Table[UserProfile] = Table(
 //   name = "profiles",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@33f920a0,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@55ca7a37,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "first_name", dbValue = DbString(""), nullable = false),
 //     ColumnMeta(name = "last_name", dbValue = DbString(""), nullable = false)
@@ -173,7 +173,7 @@ object Category {
 val singular = Table.derived[Category](TableNamingPolicy.Singular)
 // singular: Table[Category] = Table(
 //   name = "category",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@8cbb675,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@b14761,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false)
 //   )
@@ -184,7 +184,7 @@ singular.name
 val plural = Table.derived[Category](TableNamingPolicy.Plural)
 // plural: Table[Category] = Table(
 //   name = "categories",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@54cdf256,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@27c3ea48,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false)
 //   )
@@ -195,7 +195,7 @@ plural.name
 val custom = Table.derived[Category](TableNamingPolicy.Custom(n => s"tbl_$n"))
 // custom: Table[Category] = Table(
 //   name = "tbl_Category",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@4860b66a,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@6e6a1e8c,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false)
 //   )
@@ -232,7 +232,7 @@ val meta  = IndexedSeq(
 val table = Table[Tag]("tag", DbCodec[Tag], meta)
 // table: Table[Tag] = Table(
 //   name = "tag",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@7d9c62e9,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@1b362cb8,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "label", dbValue = DbString(""), nullable = false)
@@ -278,7 +278,7 @@ object OrderLine {
 val table = Table.derived[OrderLine]
 // table: Table[OrderLine] = Table(
 //   name = "order_line",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@3d3c4a76,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@59d9d745,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "product_id", dbValue = DbInt(0), nullable = false),
 //     ColumnMeta(name = "quantity", dbValue = DbInt(0), nullable = false),
@@ -317,7 +317,7 @@ object Product {
 val table    = Table.derived[Product]
 // table: Table[Product] = Table(
 //   name = "product",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@5f7e746b,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@13a46a35,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "sku", dbValue = DbString(""), nullable = false),
 //     ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = false),
@@ -366,7 +366,7 @@ object Session {
 val table = Table.derived[Session]
 // table: Table[Session] = Table(
 //   name = "session",
-//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@3fa2a4af,
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$10@72e9a985,
 //   columnsMeta = Vector(
 //     ColumnMeta(name = "token", dbValue = DbString(""), nullable = false),
 //     ColumnMeta(name = "user_id", dbValue = DbInt(0), nullable = false)

package/reference/sql/transactor-zio.md

@@ -95,7 +95,7 @@ val transactorLayer: ZLayer[Any, Nothing, TransactorZIO] =
 Add the `zio-blocks-sql-zio` artifact to your build. It depends on `zio-blocks-sql`, so you do not need to declare both:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.56"
 ```
 
 The artifact is JVM-only and requires Scala 3.

package/reference/sql/transactor.md

@@ -25,9 +25,12 @@ The structural shape of the trait is:
 trait Transactor {
   def connect[A](f: DbCon ?=> A): A
   def transact[A](f: DbTx ?=> A): A
+  def transact[A](isolation: TransactionIsolation, readOnly: Boolean)(f: DbTx ?=> A): A
 }
 ```
 
+The no-arg `transact` preserves the driver’s default isolation level and `readOnly` flag, while the two-arg overload lets callers request an explicit `TransactionIsolation` (`ReadUncommitted(1)`, `ReadCommitted(2)`, `RepeatableRead(4)`, `Serializable(8)`) and read-only mode, plus the savepoint-based nested transaction support described in `DbTx`.
+
 `JdbcTransactor` is the concrete JDBC-backed implementation. Its companion object provides factory methods for all common connection strategies:
 
 ```scala
@@ -122,7 +125,7 @@ import zio.blocks.sql._
 // Without credentials — useful for SQLite or URL-embedded auth
 val sqlite: JdbcTransactor =
   JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// sqlite: JdbcTransactor = zio.blocks.sql.JdbcTransactor@6bc883b
+// sqlite: JdbcTransactor = zio.blocks.sql.JdbcTransactor@fa1ea01
 ```
 
 Use the three-argument overload when the database requires a username and password supplied separately:
@@ -138,7 +141,7 @@ val postgres: JdbcTransactor =
     "secret",
     SqlDialect.PostgreSQL
   )
-// postgres: JdbcTransactor = zio.blocks.sql.JdbcTransactor@40cda9e
+// postgres: JdbcTransactor = zio.blocks.sql.JdbcTransactor@6fff1b52
 ```
 
 :::caution
@@ -225,16 +228,19 @@ Inside `connect`, auto-commit is left at its default state (typically `true` for
 
 ### Transaction Management
 
-`Transactor#transact` builds on `connect` by adding full transaction semantics: it disables auto-commit before executing the body, commits when the body returns normally, and rolls back when the body throws. The connection is always closed after commit or rollback.
-
-It acquires a connection, sets `autoCommit = false`, synthesizes a `DbTx` given value, and runs the body. On success it calls `conn.commit()`. On any exception it calls `conn.rollback()`, adds any rollback failure as a suppressed exception, and rethrows the original. The connection is closed in the `finally` block regardless of outcome:
+`Transactor#transact` builds on `connect` by adding full transaction semantics: it disables auto-commit before executing the body, commits when the body returns normally, and rolls back when the body throws. The connection is always closed after commit or rollback. Two overloads are available — a no-arg form that preserves the driver’s defaults and a two-arg form that sets isolation and `readOnly` explicitly:
 
 ```scala
 trait Transactor {
   def transact[A](f: DbTx ?=> A): A
+  def transact[A](isolation: TransactionIsolation, readOnly: Boolean)(f: DbTx ?=> A): A
 }
 ```
 
+The two-arg overload acquires a connection, saves the previous isolation level and `readOnly` flag, calls `setTransactionIsolation(isolation.jdbcLevel)` (fail-fast — isolation failures propagate) and best-effort `setReadOnly(readOnly)` (SQLite may throw, which is swallowed), sets `autoCommit = false` (fail-fast), synthesizes a `DbTx` given value, and runs the body. On success it calls `conn.commit()`. On any exception it calls `conn.rollback()`, adds any rollback failure as a suppressed exception, and rethrows the original. Previous isolation, `readOnly`, and `autoCommit` are restored and the connection is closed in the `finally` block regardless of outcome. SQLite natively supports only `SERIALIZABLE` — other levels are accepted via `setTransactionIsolation` but the engine still behaves as serializable.
+
+The no-arg overload preserves driver defaults (e.g. PostgreSQL `READ_COMMITTED`) and does not force `SERIALIZABLE`; it simply sets `autoCommit = false` before running the body, with the same commit/rollback and cleanup guarantees.
+
 Because `DbTx extends DbCon`, the `DbTx` given satisfies any `DbCon ?=>` requirement inside the block. We can mix `Repo` CRUD calls with raw `sql"..."` fragments freely:
 
 ```scala
@@ -246,12 +252,12 @@ case class User(id: Int, name: String, email: String)
 object User { implicit val schema: Schema[User] = Schema.derived }
 
 implicit val userCodec: DbCodec[User] = User.schema.deriving(DbCodecDeriver).derive
-// userCodec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$20@72550983
+// userCodec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$10@74798ce9
 
 val repo       = Repo.derived[User, Int]("users", "id", _.id)
-// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@144fc885
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@25a2fe55
 val transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// transactor: JdbcTransactor = zio.blocks.sql.JdbcTransactor@12877e41
+// transactor: JdbcTransactor = zio.blocks.sql.JdbcTransactor@57b2f789
 
 transactor.transact {
   repo.table.createTable(summon[DbTx].dialect).update
@@ -272,6 +278,10 @@ transactor.transact {
 If `commit` itself throws after a successful body, the transaction is rolled back and the commit exception propagates. The body's return value is discarded in that case.
 :::
 
+### Nested Transactions (Savepoints)
+
+Inside `transact`, nested work is emulated via SQL savepoints on the same JDBC connection through `DbTx` — `summon[DbTx].transact { ... }`, `DbTx.transactNested`, or the top-level `transactNested` helper. Savepoints are named `zib_tx_1 .. zib_tx_N` with depth tracked in `DbTx.currentDepth`; inner success issues `RELEASE SAVEPOINT`, failure issues `ROLLBACK TO SAVEPOINT` then rethrows. See [DbTx](db-tx) for full savepoint semantics.
+
 ## JdbcTransactor
 
 `JdbcTransactor` is the only concrete implementation of `Transactor` in the `sql` module. It holds three constructor parameters: `connectionFactory`, `dialect`, and `sqlLogger`. The factory methods on its companion object cover the most common configurations; the primary constructor is available for custom setups such as test harnesses that inject a pre-existing connection:
@@ -323,12 +333,12 @@ case class User(id: Int, name: String, email: String)
 object User { implicit val schema: Schema[User] = Schema.derived }
 
 implicit val userCodec: DbCodec[User] = User.schema.deriving(DbCodecDeriver).derive
-// userCodec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$20@460334f6
+// userCodec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$10@3454ab4b
 
 val repo       = Repo.derived[User, Int]("users", "id", _.id)
-// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@25787e5
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@bab4308
 val transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// transactor: JdbcTransactor = zio.blocks.sql.JdbcTransactor@7fefa5d1
+// transactor: JdbcTransactor = zio.blocks.sql.JdbcTransactor@74ce711c
 
 // Helper that composes two Repo calls — requires only DbCon, not Transactor
 def upsertUser(user: User)(using DbCon): Unit = {

package/reference/sql-zio.md

@@ -1,6 +1,6 @@
 ---
 id: sql-zio
-title: "SQL — ZIO Integration"
+title: "ZIO Integration"
 ---
 
 `zio-blocks-sql-zio` is the ZIO adapter for `zio-blocks-sql`. It wraps the
@@ -16,7 +16,7 @@ and effect-aware methods. For a full method-by-method reference on
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.56"
 ```
 
 ## Quick Start

package/reference/streams/core/index.md

@@ -0,0 +1,32 @@
+---
+id: index
+title: "Core Types"
+description: "Core Types index: Stream, Pipeline, and Sink, the declarative descriptions you compose into a stream processing pipeline."
+keywords:
+  - "Pull-Based Streams"
+  - "Stream Composition"
+  - "Core Types Overview"
+  - "Sink"
+sidebar_label: "Core Types"
+---
+
+`Stream`, `Pipeline`, and `Sink` are the three types you compose to build a pipeline. Each is a lazy, immutable description rather than a running process: you assemble one with ordinary combinators, and nothing executes until a terminal operation such as `stream.runAsync(sink)` — or `stream.run(sink)`, which is JVM-only — compiles and drives it.
+
+Compiling is what materializes a description into a [`Reader`](../primitives/reader.md), the stateful cursor a sink pulls from. Those live primitives are documented under [Low-Level Primitives](../primitives/index.md); this section covers the descriptions you write.
+
+## Stream
+
+[`Stream[+E, +A]`](./stream.md) describes a source of elements of type `A` that may fail with `E`. Values are produced lazily, so a stream can outlive what fits in memory and can hold an external resource open only while it is being drained.
+
+## Pipeline
+
+[`Pipeline[-In, +Out]`](./pipeline.md) describes a reusable transformation from `In` to `Out`. Reach for it when the same steps apply to more than one stream. Pipelines compose with `andThen`, apply to a stream with `stream.via(pipe)`, and to a sink with `pipe.andThenSink(sink)`.
+
+## Sink
+
+[`Sink[+E, -A, +Z]`](./sink.md) describes how to consume elements of type `A` into a result `Z`, possibly failing with `E` — the endpoint of a pipeline, built once and reusable across streams.
+
+## See Also
+
+- [Streams Reference](../index.md) — module overview
+- [Low-Level Primitives](../primitives/index.md) — the `Reader` and `Writer` cursors these compile into