feat: add AfterScan hook for post-scan field hydration

Records implementing HasAfterScan get called after every scan from
the database (Get, List, ListPaged, Insert RETURNING, Iter, etc.).
Use this to populate computed fields not stored in the DB.

Author: klaidliadon

table.go

@@ -42,6 +42,13 @@ type HasSetUpdatedAt interface {
 	SetUpdatedAt(time.Time)
 }
 
+// HasAfterScan is implemented by records that need post-scan hydration.
+// Called after every scan from the database (Get, List, ListPaged, Insert RETURNING, etc.).
+// Use this to populate computed fields that are not stored in the database.
+type HasAfterScan interface {
+	AfterScan()
+}
+
 // HasSetDeletedAt is implemented by records that support soft delete.
 // DeleteByID will call SetDeletedAt with the current UTC time to soft-delete,
 // and RestoreByID will call SetDeletedAt with a zero time.Time{} to restore.
@@ -97,6 +104,7 @@ func (t *Table[T, P, I]) insertOne(ctx context.Context, record P) error {
 	if err := t.Query.GetOne(ctx, q, record); err != nil {
 		return fmt.Errorf("insert record: %w", err)
 	}
+	callAfterScan(record)
 
 	return nil
 }
@@ -136,6 +144,7 @@ func (t *Table[T, P, I]) insertAll(ctx context.Context, records []P) error {
 		if err := t.Query.GetAll(ctx, q, &chunk); err != nil {
 			return fmt.Errorf("insert records: %w", err)
 		}
+		callAfterScanAll(chunk)
 	}
 
 	return nil
@@ -254,6 +263,7 @@ func (t *Table[T, P, I]) saveOne(ctx context.Context, record P) error {
 		if err := t.Query.GetOne(ctx, q, record); err != nil {
 			return fmt.Errorf("save: insert record: %w", err)
 		}
+		callAfterScan(record)
 
 		return nil
 	}
@@ -322,6 +332,7 @@ func (t *Table[T, P, I]) saveAll(ctx context.Context, records []P) error {
 		if err := t.Query.GetAll(ctx, q, &chunk); err != nil {
 			return fmt.Errorf("insert records: %w", err)
 		}
+		callAfterScanAll(chunk)
 
 		// update original slice
 		for i, rr := range chunk {
@@ -363,6 +374,7 @@ 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)
 	}
+	callAfterScan(record)
 
 	return record, nil
 }
@@ -374,6 +386,7 @@ 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
 	}
+	callAfterScanAll(records)
 
 	return records, nil
 }
@@ -386,6 +399,7 @@ func (t *Table[T, P, I]) ListPaged(ctx context.Context, where sq.Sqlizer, page *
 	if err := t.Query.GetAll(ctx, q, &result); err != nil {
 		return nil, nil, err
 	}
+	callAfterScanAll(result)
 	result = t.Paginator.PrepareResult(result, page)
 	return result, page, nil
 }
@@ -408,6 +422,7 @@ func (t *Table[T, P, I]) Iter(ctx context.Context, where sq.Sqlizer, orderBy []s
 				}
 				return
 			}
+			callAfterScan(&record)
 			if !yield(&record, nil) {
 				return
 			}
@@ -567,6 +582,20 @@ func (t *Table[T, P, I]) LockForUpdates(ctx context.Context, where sq.Sqlizer, o
 	})
 }
 
+func callAfterScan[P any](record P) {
+	if row, ok := any(record).(HasAfterScan); ok {
+		row.AfterScan()
+	}
+}
+
+func callAfterScanAll[P any](records []P) {
+	for _, r := range records {
+		if row, ok := any(r).(HasAfterScan); ok {
+			row.AfterScan()
+		}
+	}
+}
+
 func (t *Table[T, P, I]) lockForUpdatesWithTx(ctx context.Context, pgTx pgx.Tx, where sq.Sqlizer, orderBy []string, limit uint64, updateFn func(records []P)) error {
 	if len(orderBy) == 0 {
 		orderBy = []string{t.IDColumn}
@@ -586,6 +615,7 @@ func (t *Table[T, P, I]) lockForUpdatesWithTx(ctx context.Context, pgTx pgx.Tx,
 	if err := txQuery.GetAll(ctx, q, &records); err != nil {
 		return fmt.Errorf("select for update skip locked: %w", err)
 	}
+	callAfterScanAll(records)
 
 	updateFn(records)