From f9522e95b9a43fa57c1cd6176bcb1114bd29544d Mon Sep 17 00:00:00 2001
From: Haelnorr <lockedonohoe@gmail.com>
Date: Sun, 11 Jan 2026 18:10:52 +1100
Subject: [PATCH] Add DBTransaction interface documentation for ORM support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated JWT documentation to reflect the new DBTransaction interface
that allows ORM transactions to be used directly with the JWT package.

Changes:
- Added explanation of DBTransaction interface
- Documented that *sql.Tx automatically implements the interface
- Added examples showing GORM transaction usage (tx.Statement.ConnPool)
- Added examples showing Bun transaction usage (bunDB.BeginTx)
- Updated validation and revocation sections with ORM examples
- Clarified that users can choose between ORM or standard transactions

Benefits:
- GORM users can use gormDB.Begin() and pass tx.Statement.ConnPool
- Bun users can use bunDB.BeginTx() and pass tx directly
- Standard library users continue using db.Begin() as before
- No need to extract/manage separate transactions for different libraries

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 JWT.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 52 insertions(+), 13 deletions(-)

diff --git a/JWT.md b/JWT.md
index a0e5a30..d706372 100644
--- a/JWT.md
+++ b/JWT.md
@@ -159,7 +159,9 @@ token, expiry, err := gen.NewRefresh(42, true)
 
 ## Token Validation
 
-Tokens must be validated within a transaction context:
+Tokens must be validated within a transaction context. The package accepts any transaction type that implements the `DBTransaction` interface (which `*sql.Tx` does automatically):
+
+### Using Standard Library
 
 ```go
 // Begin transaction
@@ -185,6 +187,22 @@ if err != nil {
 tx.Commit()
 ```
 
+### Using ORM Transactions
+
+You can use ORM transactions directly since they implement the `DBTransaction` interface:
+
+```go
+// GORM transaction
+tx := gormDB.Begin()
+token, err := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
+tx.Commit()
+
+// Bun transaction
+tx, _ := bunDB.BeginTx(context.Background(), nil)
+token, err := gen.ValidateAccess(tx, tokenString)
+tx.Commit()
+```
+
 ### Token Properties
 
 After validation, you can access token claims:
@@ -204,9 +222,12 @@ ttl := token.TTL              // "session" or "exp"
 
 ## Token Revocation
 
+The revocation methods accept any transaction implementing the `DBTransaction` interface.
+
 ### Revoking a Token
 
 ```go
+// Using standard library
 tx, _ := db.Begin()
 defer tx.Rollback()
 
@@ -222,6 +243,12 @@ if err != nil {
     return err
 }
 
+tx.Commit()
+
+// Or using GORM
+tx := gormDB.Begin()
+token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
+token.Revoke(tx.Statement.ConnPool)
 tx.Commit()
 ```
 
@@ -358,6 +385,8 @@ CREATE INDEX IF NOT EXISTS idx_jwtblacklist_sub ON jwtblacklist(sub);
 
 ### GORM
 
+GORM transactions can be used directly with the JWT package:
+
 ```go
 import (
     "gorm.io/gorm"
@@ -383,19 +412,25 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
     TableConfig: jwt.DefaultTableConfig(),
 })
 
-// Use with transactions
-tx, _ := sqlDB.Begin()
-defer tx.Rollback()
-
-token, _ := gen.ValidateAccess(tx, tokenString)
-
+// Option 1: Use GORM transactions directly
+tx := gormDB.Begin()
+token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
 tx.Commit()
+
+// Option 2: Use standard sql.DB transactions
+sqlTx, _ := sqlDB.Begin()
+defer sqlTx.Rollback()
+token, _ := gen.ValidateAccess(sqlTx, tokenString)
+sqlTx.Commit()
 ```
 
 ### Bun
 
+Bun transactions can be used directly with the JWT package:
+
 ```go
 import (
+    "context"
     "database/sql"
     "github.com/uptrace/bun"
     "github.com/uptrace/bun/dialect/pgdialect"
@@ -423,13 +458,17 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
     TableConfig: jwt.DefaultTableConfig(),
 })
 
-// Use with transactions
-tx, _ := sqlDB.Begin()
-defer tx.Rollback()
-
-token, _ := gen.ValidateAccess(tx, tokenString)
-
+// Option 1: Use Bun transactions directly (recommended)
+ctx := context.Background()
+tx, _ := bunDB.BeginTx(ctx, nil)
+token, _ := gen.ValidateAccess(tx, tokenString)  // Bun's tx implements DBTransaction
 tx.Commit()
+
+// Option 2: Use standard sql.DB transactions
+sqlTx, _ := sqlDB.Begin()
+defer sqlTx.Rollback()
+token, _ := gen.ValidateAccess(sqlTx, tokenString)
+sqlTx.Commit()
 ```
 
 ## Complete Example