chore: release v0.4.0

Author: DevNico

build.sbt

@@ -30,7 +30,7 @@ ThisBuild / makePomConfiguration := makePomConfiguration.value.withConfiguration
 )
 
 // Version and Scala settings
-val slickSeekerVersion = "0.3.3"
+val slickSeekerVersion = "0.4.0"
 
 val scala3Version   = "3.3.5"
 val scala213Version = "2.13.16"

docs/docs/cookbook.md

@@ -183,6 +183,369 @@ val seeker = persons.toSeeker
   .seek(_.id.asc)
 ```
 
+## PostgreSQL Tuple Optimization
+
+For PostgreSQL databases, use `SlickPgTupleSeeker` for type-safe, tuple-optimized pagination. This generates simpler SQL with compile-time safety guarantees.
+
+### Standard Approach (Default)
+
+```scala
+val seeker = users.toSeeker
+  .seek(_.name.asc)
+  .seek(_.id.asc)
+```
+
+Generates SQL like:
+```sql
+WHERE (name > ?) OR (name = ? AND id > ?)
+ORDER BY name ASC, id ASC
+```
+
+### PostgreSQL Tuple Approach (Type-Safe)
+
+```scala
+val seeker = users.toPgTupleSeekerAsc  // Direction enforced at creation
+  .seek(_.name)    // No .asc needed - enforced by type
+  .seek(_.id)
+```
+
+Generates SQL like:
+```sql
+WHERE (name, id) > (?, ?)
+ORDER BY name ASC, id ASC
+```
+
+### When to Use
+
+- **Use `toPgTupleSeekerAsc` / `toPgTupleSeekerDesc`** when:
+  - Your database is PostgreSQL 8.2+ or H2 in PostgreSQL mode
+  - You have multiple seek columns (2 or more)
+  - **All seek columns are non-nullable** (compile-time enforced)
+  - **All seek columns have the SAME sort direction** (compile-time enforced)
+  - Query performance is critical
+  - You want maximum type safety
+
+- **Use standard `.toSeeker`** when:
+  - You need database portability (H2, MySQL, SQLite)
+  - You have only one seek column
+  - Any of your seek columns are nullable (`Option[T]`)
+  - You have **mixed sort directions** (e.g., `col1.asc, col2.desc`)
+  - You're unsure about database compatibility
+
+### Type Safety Guarantees
+
+`SlickPgTupleSeeker` enforces constraints at **compile time**:
+
+```scala
+// ✅ CORRECT: All non-nullable, uniform direction
+val ascSeeker = users.toPgTupleSeekerAsc
+  .seek(_.name)   // String - OK
+  .seek(_.age)    // Int - OK
+  .seek(_.id)     // Int - OK
+
+// ✅ CORRECT: All DESC
+val descSeeker = users.toPgTupleSeekerDesc
+  .seek(_.createdAt)  // Timestamp - OK
+  .seek(_.id)         // Int - OK
+
+// ❌ COMPILE ERROR: Nullable column
+val broken1 = users.toPgTupleSeekerAsc
+  .seek(_.name)
+  .seek(_.email)  // Option[String] → COMPILE ERROR!
+  .seek(_.id)
+// Error: No given instance of type slick.ast.BaseTypedType[Option[String]]
+
+// ❌ IMPOSSIBLE: Mixed directions (type system prevents it)
+// Once you choose Asc or Desc, ALL columns must be that direction
+```
+
+### Example with Multiple Columns
+
+```scala
+// All columns ASC
+val seeker = orders.toPgTupleSeekerAsc
+  .seek(_.status)
+  .seek(_.priority)
+  .seek(_.createdAt)
+  .seek(_.id)
+  
+// Or all columns DESC
+val descSeeker = orders.toPgTupleSeekerDesc
+  .seek(_.createdAt)
+  .seek(_.priority)
+  .seek(_.status)
+  .seek(_.id)
+
+val page = db.run(seeker.page(limit = 50, cursor = None))
+```
+
+This generates:
+```sql
+WHERE (status, priority, created_at, id) > (?, ?, ?, ?)
+ORDER BY status ASC, priority ASC, created_at ASC, id ASC
+```
+
+**Important:** All columns must have the same direction (all ASC or all DESC). For mixed directions, use the standard `SlickSeeker`.
+
+### Performance Benefits
+
+PostgreSQL tuple comparison offers measurable benefits:
+
+**Query Complexity:**
+- Standard: `O(n)` comparisons where `n` = number of columns
+- Tuple: `O(1)` single tuple comparison
+
+**Example with 4 columns:**
+
+Standard approach:
+```sql
+WHERE (col1 > ?) OR 
+      (col1 = ? AND col2 > ?) OR
+      (col1 = ? AND col2 = ? AND col3 > ?) OR
+      (col1 = ? AND col2 = ? AND col3 = ? AND col4 > ?)
+-- 10 comparisons, 4 parameters repeated
+```
+
+Tuple approach:
+```sql
+WHERE (col1, col2, col3, col4) > (?, ?, ?, ?)
+-- 1 comparison, 4 parameters
+```
+
+**Benefits:**
+- Simpler query plans (easier for PostgreSQL optimizer)
+- Better index utilization (composite index scanned as single key)
+- Cleaner logs and explain plans
+- Reduced parsing overhead
+
+### Complete Working Example
+
+```scala
+import slick.jdbc.PostgresProfile
+import io.github.devnico.slickseeker._
+import io.github.devnico.slickseeker.playjson._
+
+// 1. Setup profile
+trait MyPostgresProfile extends PostgresProfile 
+  with SlickSeekerSupport 
+  with PlayJsonSeekerSupport {
+  
+  object MyApi extends API with SeekImplicits with JsonSeekerImplicits
+  override val api: MyApi.type = MyApi
+}
+
+object MyPostgresProfile extends MyPostgresProfile
+
+// 2. Import API
+import MyPostgresProfile.api._
+import scala.concurrent.ExecutionContext.Implicits.global
+
+// 3. Define schema
+case class Product(
+  id: Int,
+  name: String,
+  category: String,
+  price: BigDecimal,
+  stock: Int
+)
+
+class Products(tag: Tag) extends Table[Product](tag, "products") {
+  def id = column[Int]("id", O.PrimaryKey, O.AutoInc)
+  def name = column[String]("name")
+  def category = column[String]("category")
+  def price = column[BigDecimal]("price")
+  def stock = column[Int]("stock")
+  def * = (id, name, category, price, stock).mapTo[Product]
+}
+
+val products = TableQuery[Products]
+
+// 4. Create type-safe seeker
+val seeker = products.toPgTupleSeekerAsc
+  .seek(_.category)  // Group by category
+  .seek(_.price)     // Then by price
+  .seek(_.id)        // Tiebreaker
+
+// 5. Paginate
+val db = Database.forConfig("mydb")
+
+val page1 = db.run(seeker.page(limit = 50, cursor = None))
+// PaginatedResult(total=1000, items=[...], nextCursor=Some("..."))
+
+val page2 = page1.flatMap { p1 =>
+  db.run(seeker.page(limit = 50, cursor = p1.nextCursor))
+}
+
+// 6. Reverse direction for descending sort
+val descSeeker = products.toPgTupleSeekerDesc
+  .seek(_.price)      // Most expensive first
+  .seek(_.category)   // Then by category
+  .seek(_.id)         // Tiebreaker
+
+val expensiveFirst = db.run(descSeeker.page(limit = 10, cursor = None))
+```
+
+### Migration Guide
+
+If you're currently using `SlickSeeker` with uniform non-nullable columns on PostgreSQL:
+
+**Before:**
+```scala
+val seeker = users.toSeeker
+  .seek(_.lastName.asc)
+  .seek(_.firstName.asc)
+  .seek(_.id.asc)
+```
+
+**After (Type-Safe):**
+```scala
+val seeker = users.toPgTupleSeekerAsc
+  .seek(_.lastName)
+  .seek(_.firstName)
+  .seek(_.id)
+```
+
+**Migration checklist:**
+1. ✅ All columns non-nullable? (no `Option[T]`)
+2. ✅ All columns same direction? (all ASC or all DESC)
+3. ✅ Database is PostgreSQL 8.2+ or H2 in PostgreSQL mode?
+4. ✅ Want compile-time safety?
+
+If all yes → migrate to `toPgTupleSeekerAsc` / `toPgTupleSeekerDesc`
+
+### Common Pitfalls
+
+#### ❌ Trying to Mix Directions
+
+```scala
+// This won't compile - direction fixed at seeker level
+val seeker = products.toPgTupleSeekerAsc
+  .seek(_.name)
+  // No way to make price DESC - type system prevents it!
+```
+
+**Solution:** Use standard `SlickSeeker` for mixed directions.
+
+#### ❌ Using Nullable Columns
+
+```scala
+case class User(id: Int, name: String, email: Option[String])
+
+// This won't compile - email is Option[String]
+val seeker = users.toPgTupleSeekerAsc
+  .seek(_.name)
+  .seek(_.email)  // ❌ Error: No given instance of BaseTypedType[Option[String]]
+```
+
+**Solution:** Use standard `SlickSeeker` or filter out nulls beforehand:
+```scala
+val activeUsers = users.filter(_.email.isDefined)
+// Still can't use PgTupleSeeker because email is still Option[String] type
+
+// Better: Use standard SlickSeeker with nulls handling
+val seeker = users.toSeeker
+  .seek(_.name.asc)
+  .seek(_.email.nullsLast.asc)
+  .seek(_.id.asc)
+```
+
+#### ❌ Database Not PostgreSQL
+
+```scala
+// Using MySQL or SQLite?
+val seeker = users.toPgTupleSeekerAsc  // ❌ Will fail at runtime!
+  .seek(_.name)
+  .seek(_.id)
+  
+// Runtime error: Syntax error in SQL
+// MySQL/SQLite don't support tuple comparison
+```
+
+**Solution:** Use standard `SlickSeeker` for database portability.
+
+### Best Practices
+
+**1. Use PgTupleSeeker When:**
+```scala
+// ✅ PostgreSQL, non-nullable columns, uniform direction
+val fastSeeker = orders.toPgTupleSeekerDesc
+  .seek(_.createdAt)  // Latest first
+  .seek(_.id)         // Tiebreaker
+```
+
+**2. Use Standard SlickSeeker When:**
+```scala
+// ✅ Need nullable handling
+val nullableSeeker = users.toSeeker
+  .seek(_.email.nullsLast.asc)
+  .seek(_.id.asc)
+
+// ✅ Need mixed directions
+val mixedSeeker = products.toSeeker
+  .seek(_.featured.desc)     // Featured first
+  .seek(_.price.asc)         // Then cheapest
+  .seek(_.id.asc)            // Tiebreaker
+
+// ✅ Need database portability
+val portableSeeker = items.toSeeker  // Works on MySQL, SQLite, H2, etc.
+  .seek(_.name.asc)
+  .seek(_.id.asc)
+```
+
+**3. Always Include a Unique Tiebreaker:**
+```scala
+// ✅ GOOD: id is unique
+val seeker = products.toPgTupleSeekerAsc
+  .seek(_.category)
+  .seek(_.price)
+  .seek(_.id)  // Ensures stable pagination
+
+// ❌ BAD: price might have duplicates
+val badSeeker = products.toPgTupleSeekerAsc
+  .seek(_.category)
+  .seek(_.price)  // No unique tiebreaker - unstable pagination!
+```
+
+**4. Match Index Structure:**
+```sql
+-- If you have this index:
+CREATE INDEX idx_products_category_price_id ON products(category, price, id);
+
+-- Use this seeker to leverage it:
+val seeker = products.toPgTupleSeekerAsc
+  .seek(_.category)  -- Matches index order
+  .seek(_.price)
+  .seek(_.id)
+```
+
+### Troubleshooting
+
+**Compile Error: "No given instance of type BaseTypedType[Option[String]]"**
+
+```scala
+// You're trying to use a nullable column
+val seeker = users.toPgTupleSeekerAsc
+  .seek(_.email)  // email is Option[String]
+```
+
+**Fix:** Use standard `SlickSeeker` or ensure column is non-nullable in schema.
+
+**Compile Error: "value toPgTupleSeekerAsc is not a member"**
+
+```scala
+// You haven't imported the profile API
+val seeker = users.toPgTupleSeekerAsc  // ❌
+```
+
+**Fix:** Import your profile API:
+```scala
+import MyPostgresProfile.api._
+```
+
+**Runtime Error: "Syntax error near '>'"**
+
+Database doesn't support tuple comparison. Use standard `SlickSeeker`.
+
 ## Custom Cursor Environments
 
 Following are only examples and not meant to copy as-is. Adjust for your use case.

docs/docs/index.md

@@ -7,6 +7,7 @@ Type-safe, high-performance cursor-based pagination for Slick 3.5+.
 - **Keyset Pagination** - O(1) performance regardless of page depth
 - **Bidirectional** - Navigate forward and backward through result sets
 - **Type-Safe** - Compile-time verification of cursor/column matching
+- **PostgreSQL Tuple Optimization** - Compile-time safe tuple comparisons for PostgreSQL (NEW!)
 - **Profile Agnostic** - Works with any Slick JDBC profile (PostgreSQL, MySQL, H2, SQLite, Oracle, etc.)
 - **Flexible Ordering** - Support for nulls first/last, custom enum orders
 - **Modular** - Core + optional Play JSON integration
@@ -49,8 +50,8 @@ Add to your `build.sbt`:
 
 ```scala
 libraryDependencies ++= Seq(
-  "io.github.devnico" %% "slick-seeker" % "0.3.3",
-  "io.github.devnico" %% "slick-seeker-play-json" % "0.3.3"  // Optional, but you need some kind of cursor encoder
+  "io.github.devnico" %% "slick-seeker" % "0.4.0",
+  "io.github.devnico" %% "slick-seeker-play-json" % "0.4.0"  // Optional, but you need some kind of cursor encoder
 )
 ```