sqldb: rename ExecutePagedQuery to ExecuteBatchQuery

We rename this helper along the config types & helper types for it
because the word "page" is used more often in the context of paging
through results using an offset and limit whereas this helper is
specifically used to split up the slice in queries of the form
"WHERE x in []slice". We do this rename so that there is mimimal
confusion in contexts where we use batching along with actual paging.

The config struct is also renamed to QueryConfig in preparation for it
holding more config options.

sqldb/paginate.go

@@ -5,46 +5,56 @@ import (
 	"fmt"
 )
 
-// PagedQueryFunc represents a function that takes a slice of converted items
+// QueryConfig holds configuration values for SQL queries.
+type QueryConfig struct {
+	// MaxBatchSize is the maximum number of items included in a batch
+	// query IN clauses list.
+	MaxBatchSize int
+}
+
+// DefaultQueryConfig returns a default configuration for SQL queries.
+func DefaultQueryConfig() *QueryConfig {
+	return &QueryConfig{
+		// TODO(elle): make configurable & have different defaults
+		// for SQLite and Postgres.
+		MaxBatchSize: 250,
+	}
+}
+
+// BatchQueryFunc represents a function that takes a batch of converted items
 // and returns results.
-type PagedQueryFunc[T any, R any] func(context.Context, []T) ([]R, error)
+type BatchQueryFunc[T any, R any] func(context.Context, []T) ([]R, error)
 
 // ItemCallbackFunc represents a function that processes individual results.
 type ItemCallbackFunc[R any] func(context.Context, R) error
 
 // ConvertFunc represents a function that converts from input type to query type
+// for the batch query.
 type ConvertFunc[I any, T any] func(I) T
 
-// PagedQueryConfig holds configuration values for calls to ExecutePagedQuery.
-type PagedQueryConfig struct {
-	PageSize int
-}
-
-// DefaultPagedQueryConfig returns a default configuration
-func DefaultPagedQueryConfig() *PagedQueryConfig {
-	return &PagedQueryConfig{
-		// TODO(elle): make configurable & have different defaults
-		// for SQLite and Postgres.
-		PageSize: 250,
-	}
-}
-
-// ExecutePagedQuery executes a paginated query over a slice of input items.
+// ExecuteBatchQuery executes a query in batches over a slice of input items.
 // It converts the input items to a query type using the provided convertFunc,
-// executes the query using the provided queryFunc, and applies the callback
-// to each result.
-func ExecutePagedQuery[I any, T any, R any](ctx context.Context,
-	cfg *PagedQueryConfig, inputItems []I, convertFunc ConvertFunc[I, T],
-	queryFunc PagedQueryFunc[T, R], callback ItemCallbackFunc[R]) error {
+// executes the query in batches using the provided queryFunc, and applies
+// the callback to each result. This is useful for queries using the
+// "WHERE x IN []slice" pattern. It takes that slice, splits it into batches of
+// size MaxBatchSize, and executes the query for each batch.
+//
+// NOTE: it is the caller's responsibility to ensure that the expected return
+// results are unique across all pages. Meaning that if the input items are
+// split up, a result that is returned in one page should not be expected to
+// be returned in another page.
+func ExecuteBatchQuery[I any, T any, R any](ctx context.Context,
+	cfg *QueryConfig, inputItems []I, convertFunc ConvertFunc[I, T],
+	queryFunc BatchQueryFunc[T, R], callback ItemCallbackFunc[R]) error {
 
 	if len(inputItems) == 0 {
 		return nil
 	}
 
 	// Process items in pages.
-	for i := 0; i < len(inputItems); i += cfg.PageSize {
+	for i := 0; i < len(inputItems); i += cfg.MaxBatchSize {
 		// Calculate the end index for this page.
-		end := i + cfg.PageSize
+		end := i + cfg.MaxBatchSize
 		if end > len(inputItems) {
 			end = len(inputItems)
 		}