feat: add AfterScanner hook for post-scan field hydration

Refs #43

Author: klaidliadon

table.go

@@ -12,6 +12,22 @@ import (
 	"github.com/jackc/pgx/v5"
 )
 
+// AfterScanner is implemented by structs that need post-scan field hydration.
+type AfterScanner interface {
+	AfterScan() error
+}
+
+func afterScanAll[T any](records []T) error {
+	for i := range records {
+		if as, ok := any(records[i]).(AfterScanner); ok {
+			if err := as.AfterScan(); err != nil {
+				return fmt.Errorf("after scan: %w", err)
+			}
+		}
+	}
+	return nil
+}
+
 // ID is a comparable type used for record IDs.
 type ID comparable
 
@@ -371,6 +387,11 @@ func (t *Table[T, P, I]) Get(ctx context.Context, where sq.Sqlizer, orderBy []st
 	if err := t.Query.GetOne(ctx, q, record); err != nil {
 		return nil, fmt.Errorf("get record: %w", err)
 	}
+	if as, ok := any(record).(AfterScanner); ok {
+		if err := as.AfterScan(); err != nil {
+			return nil, fmt.Errorf("after scan: %w", err)
+		}
+	}
 
 	return record, nil
 }
@@ -382,6 +403,9 @@ func (t *Table[T, P, I]) List(ctx context.Context, where sq.Sqlizer, orderBy []s
 	if err := t.Query.GetAll(ctx, q, &records); err != nil {
 		return nil, err
 	}
+	if err := afterScanAll(records); err != nil {
+		return nil, err
+	}
 
 	return records, nil
 }
@@ -402,6 +426,9 @@ func (t *Table[T, P, I]) ListPaged(ctx context.Context, where sq.Sqlizer, page *
 		return nil, nil, err
 	}
 	result = t.Paginator.PrepareResult(result, page)
+	if err := afterScanAll(result); err != nil {
+		return nil, nil, err
+	}
 	return result, page, nil
 }
 
@@ -421,6 +448,12 @@ func (t *Table[T, P, I]) Iter(ctx context.Context, where sq.Sqlizer, orderBy []s
 				yield(nil, err)
 				return
 			}
+			if as, ok := any(&record).(AfterScanner); ok {
+				if err := as.AfterScan(); err != nil {
+					yield(nil, fmt.Errorf("after scan: %w", err))
+					return
+				}
+			}
 			if !yield(&record, nil) {
 				return
 			}

tests/pgkit_test.go

@@ -1145,6 +1145,49 @@ func TestSlogTracerBatchQuery(t *testing.T) {
 	}
 }
 
+func TestAfterScan(t *testing.T) {
+	truncateAllTables(t)
+
+	ctx := t.Context()
+
+	hookTable := pgkit.Table[AccountWithHook, *AccountWithHook, int64]{DB: DB, Name: "accounts", IDColumn: "id"}
+	failTable := pgkit.Table[AccountWithFailingHook, *AccountWithFailingHook, int64]{DB: DB, Name: "accounts", IDColumn: "id"}
+	plainTable := pgkit.Table[Account, *Account, int64]{DB: DB, Name: "accounts", IDColumn: "id"}
+
+	// Seed data.
+	require.NoError(t, hookTable.Save(ctx, &AccountWithHook{Account: Account{Name: "alice"}}))
+	require.NoError(t, hookTable.Save(ctx, &AccountWithHook{Account: Account{Name: "bob"}}))
+
+	t.Run("Get", func(t *testing.T) {
+		acc, err := hookTable.Get(ctx, sq.Eq{"name": "alice"}, nil)
+		require.NoError(t, err)
+		assert.Equal(t, "ALICE", acc.UpperName)
+	})
+
+	t.Run("List", func(t *testing.T) {
+		accs, err := hookTable.List(ctx, nil, []string{"name"})
+		require.NoError(t, err)
+		require.Len(t, accs, 2)
+		assert.Equal(t, "ALICE", accs[0].UpperName)
+		assert.Equal(t, "BOB", accs[1].UpperName)
+	})
+
+	t.Run("NoHook", func(t *testing.T) {
+		// Account does not implement AfterScanner — should work unchanged.
+		acc, err := plainTable.Get(ctx, sq.Eq{"name": "alice"}, nil)
+		require.NoError(t, err)
+		assert.Equal(t, "alice", acc.Name)
+	})
+
+	t.Run("ErrorPropagation", func(t *testing.T) {
+		_, err := failTable.Get(ctx, sq.Eq{"name": "alice"}, nil)
+		require.ErrorContains(t, err, "after scan boom")
+
+		_, err = failTable.List(ctx, nil, nil)
+		require.ErrorContains(t, err, "after scan boom")
+	})
+}
+
 func getTracer(opts []tracer.Option) (*bytes.Buffer, *tracer.LogTracer) {
 	buf := &bytes.Buffer{}
 	handler := slog.NewJSONHandler(buf, nil)

tests/schema_test.go

@@ -2,6 +2,7 @@ package pgkit_test
 
 import (
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/goware/pgkit/v2/dbtype"
@@ -117,3 +118,25 @@ type Stat struct {
 	Num    dbtype.BigInt `db:"big_num"` // using NUMERIC(78,0) postgres datatype
 	Rating dbtype.BigInt `db:"rating"`  // using NUMERIC(78,0) postgres datatype
 }
+
+type AccountWithHook struct {
+	Account
+	UpperName string `db:"-"`
+}
+
+func (a *AccountWithHook) AfterScan() error {
+	a.UpperName = strings.ToUpper(a.Name)
+	return nil
+}
+
+func (a *AccountWithHook) DBTableName() string { return "accounts" }
+
+type AccountWithFailingHook struct {
+	Account
+}
+
+func (a *AccountWithFailingHook) AfterScan() error {
+	return fmt.Errorf("after scan boom")
+}
+
+func (a *AccountWithFailingHook) DBTableName() string { return "accounts" }