feat(scanner): new API and tests

Author: tmzane

go.mod

@@ -1,3 +1,3 @@
 module go-simpler.org/queries
 
-go 1.18
+go 1.22

scanner.go

@@ -1,88 +1,75 @@
 package queries
 
 import (
-	"errors"
+	"database/sql"
 	"fmt"
 	"reflect"
 )
 
-// TODO: consider merging ScanOne() + ScanAll() -> Scan().
-
 type Rows interface {
-	Scan(...any) error
 	Columns() ([]string, error)
 	Next() bool
+	Scan(...any) error
 	Err() error
 }
 
-func ScanOne(dst any, rows Rows) error {
-	v := reflect.ValueOf(dst)
-	if !v.IsValid() || v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct || v.IsNil() {
-		panic("queries: dst must be a non-nil struct pointer")
-	}
-
-	fields := parseStruct(v.Elem())
-
-	columns, err := rows.Columns()
-	if err != nil {
-		return fmt.Errorf("getting column names: %w", err)
-	}
-
-	target := make([]any, len(columns))
-	for i, column := range columns {
-		field, ok := fields[column]
-		if !ok {
-			panic(fmt.Sprintf("queries: no field for the %#q column", column))
-		}
-		target[i] = field
-	}
-
-	if !rows.Next() {
-		return errors.New("queries: no rows to scan")
-	}
-	if err := rows.Scan(target...); err != nil {
-		return fmt.Errorf("scanning rows: %w", err)
-	}
+func Scan[T any](dst *[]T, rows Rows) error {
+	return scan[T](reflect.ValueOf(dst).Elem(), rows)
+}
 
-	return rows.Err()
+func ScanRow[T any](dst *T, rows Rows) error {
+	return scan[T](reflect.ValueOf(dst).Elem(), rows)
 }
 
-func ScanAll(dst any, rows Rows) error {
-	v := reflect.ValueOf(dst)
-	if !v.IsValid() || v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Slice || v.Elem().Type().Elem().Kind() != reflect.Struct {
-		panic("queries: dst must be a pointer to a slice of structs")
+func scan[T any](v reflect.Value, rows Rows) error {
+	typ := reflect.TypeFor[T]()
+	if typ.Kind() != reflect.Struct {
+		panic("queries: T must be a struct")
 	}
 
-	slice := v.Elem()
-	typ := slice.Type().Elem()
-	elem := reflect.New(typ).Elem()
-	fields := parseStruct(elem)
+	strct := reflect.New(typ).Elem()
+	fields := parseStruct(strct)
 
 	columns, err := rows.Columns()
 	if err != nil {
 		return fmt.Errorf("getting column names: %w", err)
 	}
 
-	target := make([]any, len(columns))
+	into := make([]any, len(columns))
 	for i, column := range columns {
 		field, ok := fields[column]
 		if !ok {
-			panic(fmt.Sprintf("queries: no field for the %#q column", column))
+			panic(fmt.Sprintf("queries: no field for column %q", column))
 		}
-		target[i] = field
+		into[i] = field
 	}
 
+	slice := reflect.New(reflect.SliceOf(typ)).Elem()
 	for rows.Next() {
-		if err := rows.Scan(target...); err != nil {
-			return fmt.Errorf("scanning rows: %w", err)
+		if err := rows.Scan(into...); err != nil {
+			return fmt.Errorf("scanning row: %w", err)
+		}
+		slice = reflect.Append(slice, strct)
+	}
+	if err := rows.Err(); err != nil {
+		return err
+	}
+
+	switch v.Kind() {
+	case reflect.Slice:
+		v.Set(slice)
+	case reflect.Struct:
+		if slice.Len() == 0 {
+			return sql.ErrNoRows
 		}
-		slice.Set(reflect.Append(slice, elem))
+		v.Set(slice.Index(0))
+	default:
+		panic("unreachable")
 	}
 
-	return rows.Err()
+	return nil
 }
 
-// TODO: support nested structs.
 func parseStruct(v reflect.Value) map[string]any {
 	fields := make(map[string]any, v.NumField())
 
@@ -92,16 +79,15 @@ func parseStruct(v reflect.Value) map[string]any {
 			continue
 		}
 
-		sf := v.Type().Field(i)
-		name, ok := sf.Tag.Lookup("sql")
+		tag, ok := v.Type().Field(i).Tag.Lookup("sql")
 		if !ok {
 			continue
 		}
-		if name == "" {
-			panic(fmt.Sprintf("queries: %s field has an empty `sql` tag", sf.Name))
+		if tag == "" {
+			panic(fmt.Sprintf("queries: field %s has an empty `sql` tag", v.Type().Field(i).Name))
 		}
 
-		fields[name] = field.Addr().Interface()
+		fields[tag] = field.Addr().Interface()
 	}
 
 	return fields

scanner_test.go

@@ -0,0 +1,106 @@
+package queries_test
+
+import (
+	"database/sql"
+	"reflect"
+	"testing"
+
+	"go-simpler.org/queries"
+	"go-simpler.org/queries/internal/assert"
+	. "go-simpler.org/queries/internal/assert/EF"
+)
+
+func Test_misuse(t *testing.T) {
+	t.Run("non-struct T", func(t *testing.T) {
+		const panicMsg = "queries: T must be a struct"
+
+		assert.Panics[E](t, func() { _ = queries.Scan(new([]int), nil) }, panicMsg)
+		assert.Panics[E](t, func() { _ = queries.ScanRow(new(int), nil) }, panicMsg)
+	})
+
+	t.Run("empty tag", func(t *testing.T) {
+		const panicMsg = "queries: field Foo has an empty `sql` tag"
+
+		type dst struct {
+			Foo int `sql:""`
+		}
+		assert.Panics[E](t, func() { _ = queries.Scan(new([]dst), nil) }, panicMsg)
+		assert.Panics[E](t, func() { _ = queries.ScanRow(new(dst), nil) }, panicMsg)
+	})
+
+	t.Run("missing field", func(t *testing.T) {
+		const panicMsg = `queries: no field for column "foo"`
+
+		rows := mockRows{columns: []string{"foo"}}
+
+		type dst struct {
+			Foo int
+		}
+		assert.Panics[E](t, func() { _ = queries.Scan(new([]dst), &rows) }, panicMsg)
+		assert.Panics[E](t, func() { _ = queries.ScanRow(new(dst), &rows) }, panicMsg)
+	})
+}
+
+func TestScan(t *testing.T) {
+	rows := mockRows{
+		columns: []string{"foo", "bar"},
+		values:  [][]any{{1, "A"}, {2, "B"}},
+	}
+
+	var dst []struct {
+		Foo int    `sql:"foo"`
+		Bar string `sql:"bar"`
+	}
+	err := queries.Scan(&dst, &rows)
+	assert.NoErr[F](t, err)
+	assert.Equal[E](t, len(dst), 2)
+	assert.Equal[E](t, dst[0].Foo, 1)
+	assert.Equal[E](t, dst[1].Foo, 2)
+	assert.Equal[E](t, dst[0].Bar, "A")
+	assert.Equal[E](t, dst[1].Bar, "B")
+}
+
+func TestScanRow(t *testing.T) {
+	rows := mockRows{
+		columns: []string{"foo", "bar"},
+		values:  [][]any{{1, "A"}},
+	}
+
+	var dst struct {
+		Foo int    `sql:"foo"`
+		Bar string `sql:"bar"`
+	}
+	err := queries.ScanRow(&dst, &rows)
+	assert.NoErr[F](t, err)
+	assert.Equal[E](t, dst.Foo, 1)
+	assert.Equal[E](t, dst.Bar, "A")
+
+	t.Run("no rows", func(t *testing.T) {
+		rows := mockRows{columns: []string{"foo"}}
+
+		var dst struct {
+			Foo int `sql:"foo"`
+		}
+		err := queries.ScanRow(&dst, &rows)
+		assert.IsErr[E](t, err, sql.ErrNoRows)
+	})
+}
+
+type mockRows struct {
+	columns []string
+	values  [][]any
+	idx     int
+}
+
+func (r *mockRows) Columns() ([]string, error) { return r.columns, nil }
+func (r *mockRows) Next() bool                 { return r.idx < len(r.values) }
+func (r *mockRows) Err() error                 { return nil }
+
+func (r *mockRows) Scan(dst ...any) error {
+	for i := 0; i < len(dst); i++ {
+		v := reflect.ValueOf(r.values[r.idx][i])
+		reflect.ValueOf(dst[i]).Elem().Set(v)
+	}
+	r.idx++
+	return nil
+}