refactor: introduce Iterator type alias for juicecli code generation (#537)

- Add sql.Iterator[T] as a type alias for iter.Seq2[T, error]
- Move Iter function implementation from binder.go to new iter.go file
- Update Iter and QueryIterContext to use sql.Iterator[T] type
- Remove direct iter package imports from bind.go and shortcuts.go

This change improves code organization and provides a dedicated type
for juicecli to recognize during code generation, enabling proper
iterator-based query method generation.

Files changed:
- sql/iter.go: New file with Iterator type and Iter implementation
- sql/binder.go: Remove Iter function (moved to iter.go)
- bind.go: Update Iter return type to sql.Iterator[T]
- shortcuts.go: Update QueryIterContext return type to sql.Iterator[T]

Author: eatmoreapple

bind.go

@@ -17,8 +17,6 @@ limitations under the License.
 package juice
 
 import (
-	"iter"
-
 	"github.com/go-juicedev/juice/sql"
 )
 
@@ -139,6 +137,6 @@ func List2[T any](rows sql.Rows) ([]*T, error) {
 // Note: The caller is responsible for closing the rows when iteration is complete.
 //
 // 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) {
+func Iter[T any](rows sql.Rows) (sql.Iterator[T], error) {
 	return sql.Iter[T](rows)
 }

shortcuts.go

@@ -19,8 +19,6 @@ package juice
 import (
 	"context"
 	"database/sql"
-	"iter"
-
 	sqllib "github.com/go-juicedev/juice/sql"
 )
 
@@ -69,7 +67,7 @@ func QueryList2Context[T any](ctx context.Context, statement, param any) (result
 // 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) {
+func QueryIterContext[T any](ctx context.Context, statement, param any) (sqllib.Iterator[T], error) {
 	manager := ManagerFromContext(ctx)
 	rows, err := manager.Object(statement).QueryContext(ctx, param)
 	if err != nil {

sql/binder.go

@@ -18,7 +18,6 @@ package sql
 
 import (
 	"database/sql"
-	"iter"
 	"reflect"
 	"time"
 )
@@ -178,64 +177,3 @@ func List2[T any](rows Rows) ([]*T, error) {
 	}
 	return result, nil
 }
-
-func Iter[T any](rows Rows) (iter.Seq2[T, error], error) {
-	columns, err := rows.Columns()
-	if err != nil {
-		return nil, err
-	}
-
-	columnDest := &rowDestination{}
-	t := reflect.TypeFor[T]()
-
-	var objectFactory func() T
-
-	isPtr := t.Kind() == reflect.Ptr
-
-	// Override object factory for pointer types to properly allocate memory
-	if isPtr {
-		objectFactory = func() 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
-	handler := func() (T, error) {
-		var t = objectFactory()
-
-		var v reflect.Value
-
-		if isPtr {
-			v = reflect.ValueOf(t)
-		} else {
-			v = reflect.ValueOf(&t)
-		}
-
-		// Create destination slice for scanning row values
-		dest, err := columnDest.Destination(v, columns)
-		if err != nil {
-			return t, err
-		}
-		if err = rows.Scan(dest...); err != nil {
-			return t, err
-		}
-		return t, nil
-	}
-
-	return func(yield func(T, error) bool) {
-		for rows.Next() {
-			value, err := handler()
-			if !yield(value, err) {
-				return
-			}
-		}
-		// Check for any errors that occurred during iteration
-		if err := rows.Err(); err != nil {
-			var zero T
-			yield(zero, err)
-		}
-	}, nil
-}

sql/iter.go

@@ -0,0 +1,94 @@
+/*
+Copyright 2025 eatmoreapple
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package sql
+
+import (
+	"iter"
+	"reflect"
+)
+
+// Iterator is a type alias for iter.Seq2[T, error].
+// It represents an iterator that yields values of type T and may return an error.
+//
+// This type is specifically designed for juicecli to use as a type annotation
+// during code generation, allowing the tool to recognize and generate proper
+// iterator-based query methods.
+type Iterator[T any] iter.Seq2[T, error]
+
+// Iter creates an iterator from the given Rows.
+// It scans each row into a new instance of type T and yields it.
+// If an error occurs during scanning, it yields the error.
+func Iter[T any](rows Rows) (Iterator[T], error) {
+	columns, err := rows.Columns()
+	if err != nil {
+		return nil, err
+	}
+
+	columnDest := &rowDestination{}
+	t := reflect.TypeFor[T]()
+
+	var objectFactory func() T
+
+	isPtr := t.Kind() == reflect.Ptr
+
+	// Override object factory for pointer types to properly allocate memory
+	if isPtr {
+		objectFactory = func() 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
+	handler := func() (T, error) {
+		var t = objectFactory()
+
+		var v reflect.Value
+
+		if isPtr {
+			v = reflect.ValueOf(t)
+		} else {
+			v = reflect.ValueOf(&t)
+		}
+
+		// Create destination slice for scanning row values
+		dest, err := columnDest.Destination(v, columns)
+		if err != nil {
+			return t, err
+		}
+		if err = rows.Scan(dest...); err != nil {
+			return t, err
+		}
+		return t, nil
+	}
+
+	return func(yield func(T, error) bool) {
+		for rows.Next() {
+			value, err := handler()
+			if !yield(value, err) {
+				return
+			}
+		}
+		// Check for any errors that occurred during iteration
+		if err := rows.Err(); err != nil {
+			var zero T
+			yield(zero, err)
+		}
+	}, nil
+}