refactor(sql): simplify Iter API to use iter.Seq2[T, error] (#536)

Refactored the RowsIter design to provide a cleaner and more idiomatic API:

- Removed RowsIter struct and Err() method
- Changed Iter() to directly return (iter.Seq2[T, error], error)
- Errors are now yielded during iteration instead of checked afterwards
- Added rows.Err() check after iteration completes
- Updated all tests to use the new API signature

Breaking Changes:
- Iter() now returns (iter.Seq2[T, error], error) instead of *RowsIter[T]
- Users must handle errors in the range loop: for v, err := range seq

Benefits:
- More concise API with less boilerplate
- Immediate error handling in iteration loop
- Follows Go's standard error handling patterns
- Better suited for use in shortcuts

Added:
- QueryIterContext() shortcut function with automatic row cleanup

Files changed:
- sql/binder.go: Simplified Iter implementation (-78 lines)
- sql/binder_test.go: Updated tests for new API
- bind.go: Updated documentation and function signature
- shortcuts.go: Added QueryIterContext helper

Author: eatmoreapple

bind.go

@@ -16,7 +16,11 @@ limitations under the License.
 
 package juice
 
-import "github.com/go-juicedev/juice/sql"
+import (
+	"iter"
+
+	"github.com/go-juicedev/juice/sql"
+)
 
 // BindWithResultMap binds database query results to a value of type T using a custom ResultMap.
 // This function provides backward compatibility for code that imports the juice package directly.
@@ -115,22 +119,26 @@ func List2[T any](rows sql.Rows) ([]*T, error) {
 // For new code, consider using sql.Iter directly:
 //
 //	import "github.com/go-juicedev/juice/sql"
-//	iter := sql.Iter[User](rows)
+//	seq, err := sql.Iter[User](rows)
 //
-// The iterator implements Go's iter.Seq[T] interface, allowing use in range loops:
+// The function returns an iter.Seq2[T, error] that yields (value, error) pairs,
+// allowing for immediate error handling in the loop:
 //
-//	iter := Iter[User](rows)
-//	for user := range iter.Iter() {
+//	seq, err := Iter[User](rows)
+//	if err != nil {
+//	    return err
+//	}
+//	for user, err := range seq {
+//	    if err != nil {
+//	        return fmt.Errorf("iteration failed: %w", err)
+//	    }
 //	    // Process each user
 //	    fmt.Println(user.Name)
 //	}
-//	if err := iter.Err(); err != nil {
-//	    // Handle iteration error
-//	}
 //
 // Note: The caller is responsible for closing the rows when iteration is complete.
 //
-// Returns an iterator that yields values of type T.
-func Iter[T any](rows sql.Rows) *sql.RowsIter[T] {
+// Returns an iterator that yields (value, error) pairs of type T, and any initialization error.
+func Iter[T any](rows sql.Rows) (iter.Seq2[T, error], error) {
 	return sql.Iter[T](rows)
 }

shortcuts.go

@@ -19,6 +19,7 @@ package juice
 import (
 	"context"
 	"database/sql"
+	"iter"
 
 	sqllib "github.com/go-juicedev/juice/sql"
 )
@@ -64,3 +65,16 @@ func QueryList2Context[T any](ctx context.Context, statement, param any) (result
 	defer func() { _ = rows.Close() }()
 	return sqllib.List2[T](rows)
 }
+
+// QueryIterContext executes a query and returns an iterator over T.
+// Rows are automatically closed when iteration completes or stops.
+// (ctx must contain a Manager via ManagerFromContext)
+func QueryIterContext[T any](ctx context.Context, statement, param any) (iter.Seq2[T, error], error) {
+	manager := ManagerFromContext(ctx)
+	rows, err := manager.Object(statement).QueryContext(ctx, param)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rows.Close() }()
+	return sqllib.Iter[T](rows)
+}

sql/binder.go

@@ -18,7 +18,6 @@ package sql
 
 import (
 	"database/sql"
-	"errors"
 	"iter"
 	"reflect"
 	"time"
@@ -180,46 +179,16 @@ func List2[T any](rows Rows) ([]*T, error) {
 	return result, nil
 }
 
-// RowsIter provides an iterator interface for Rows.
-// It implements Go's built-in iter.Seq interface for type-safe iteration over database rows.
-// Type parameter T represents the type of values that will be yielded during iteration.
-type RowsIter[T any] struct {
-	rows Rows  // The underlying Rows to iterate over
-	err  error // Stores any error that occurs during iteration
-}
-
-// Err returns any error that occurred during iteration.
-// This method should be checked after iteration is complete to ensure
-// no errors occurred while processing the rows.
-func (r *RowsIter[T]) Err() error {
-	return errors.Join(r.err, r.rows.Err())
-}
-
-// Iter implements the iter.Seq interface for row iteration.
-// It yields values of type T, automatically handling memory allocation
-// and type conversion for each row.
-//
-// Example usage:
-//
-//	iter := Iter[User](rows)
-//	for v := range iter.Iter() {
-//	    // Process each user
-//	    fmt.Println(v.Name)
-//	}
-//	if err := iter.Err(); err != nil {
-//	    // Handle error
-//	}
-func (r *RowsIter[T]) Iter() iter.Seq[T] {
-	columns, err := r.rows.Columns()
+func Iter[T any](rows Rows) (iter.Seq2[T, error], error) {
+	columns, err := rows.Columns()
 	if err != nil {
-		r.err = err
-		return func(func(T) bool) {}
+		return nil, err
 	}
+
 	columnDest := &rowDestination{}
 	t := reflect.TypeFor[T]()
 
-	// Default object factory for non-pointer types
-	var objectFactory = func() T { return *new(T) }
+	var objectFactory func() T
 
 	isPtr := t.Kind() == reflect.Ptr
 
@@ -229,6 +198,8 @@ func (r *RowsIter[T]) Iter() iter.Seq[T] {
 			result, _ := reflect.TypeAssert[T](reflect.New(t.Elem()))
 			return result
 		}
+	} else {
+		objectFactory = func() T { return *new(T) }
 	}
 
 	// handler encapsulates the row scanning logic and object creation
@@ -248,35 +219,23 @@ func (r *RowsIter[T]) Iter() iter.Seq[T] {
 		if err != nil {
 			return t, err
 		}
-		if err = r.rows.Scan(dest...); err != nil {
+		if err = rows.Scan(dest...); err != nil {
 			return t, err
 		}
 		return t, nil
 	}
 
-	return func(yield func(T) bool) {
-
-		for r.rows.Next() {
+	return func(yield func(T, error) bool) {
+		for rows.Next() {
 			value, err := handler()
-			if err != nil {
-				r.err = err
-				return
-			}
-			if !yield(value) {
+			if !yield(value, err) {
 				return
 			}
 		}
-	}
-}
-
-// Iter creates an iterator over SQL rows that yields values of type T.
-// It handles both pointer and non-pointer types automatically and provides
-// proper memory management for each iteration.
-//
-// Note: This function does not close the Rows. The caller is responsible
-// for closing the rows when iteration is complete. This design allows for more
-// flexible resource management, especially when using the iterator in different
-// contexts or when early termination is needed.
-func Iter[T any](rows Rows) *RowsIter[T] {
-	return &RowsIter[T]{rows: rows}
+		// Check for any errors that occurred during iteration
+		if err := rows.Err(); err != nil {
+			var zero T
+			yield(zero, err)
+		}
+	}, nil
 }

sql/binder_test.go

@@ -269,12 +269,15 @@ func TestIter(t *testing.T) {
 			Data:        [][]any{{1, "Alice"}, {2, "Bob"}},
 		}
 		var users []TestUser
-		iter := Iter[TestUser](rows)
-		for user := range iter.Iter() {
-			users = append(users, user)
+		seq, err := Iter[TestUser](rows)
+		if err != nil {
+			t.Fatalf("Iter initialization failed: %v", err)
 		}
-		if err := iter.Err(); err != nil {
-			t.Fatalf("Iter failed: %v", err)
+		for user, err := range seq {
+			if err != nil {
+				t.Fatalf("Iter failed: %v", err)
+			}
+			users = append(users, user)
 		}
 		if len(users) != len(rows.Data) {
 			t.Fatalf("Expected %d users, got %d", len(rows.Data), len(users))
@@ -291,14 +294,17 @@ func TestIter(t *testing.T) {
 			ColumnsLine: []string{"id", "name"},
 			Data:        [][]any{},
 		}
-		iter := Iter[TestUser](rows)
+		seq, err := Iter[TestUser](rows)
+		if err != nil {
+			t.Fatalf("Iter initialization failed: %v", err)
+		}
 		var users []TestUser
-		for user := range iter.Iter() {
+		for user, err := range seq {
+			if err != nil {
+				t.Fatalf("Iter failed with empty rows: %v", err)
+			}
 			users = append(users, user)
 		}
-		if err := iter.Err(); err != nil {
-			t.Fatalf("Iter failed with empty rows: %v", err)
-		}
 		if len(users) != 0 {
 			t.Errorf("Expected empty slice, got %d users", len(users))
 		}