Documentation
¶
Overview ¶
Package iterx extends standard iterators with lazy page loading.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LoadingIterator ¶
LoadingIterator is a standard iterator over lazily loaded items and errors. Iterators returned by NewLoadingIterator are single-use and not safe for concurrent traversal. After any traversal ends, including an early break, subsequent traversals yield nothing.
func NewLoadingIterator ¶
func NewLoadingIterator[T any](ctx context.Context, page PageFunc[T]) LoadingIterator[T]
NewLoadingIterator binds page without calling it. Iteration loads one batch at a time and yields its items in order, including items in the final batch. Loading is synchronous; there is no prefetch or automatic retry. A load or context error yields (zero T, err) once and ends the iterator.
ctx must be non-nil. A nil page returns a nil iterator, which must not be ranged. Breaking stops this iterator; restarting requires a new loader and iterator. Loader cursor progress represents fetched pages, not processed items, and must not be used as a processing checkpoint after an early break.
+spec=`Construction performs no I/O; early termination never loads another page` +spec=`Each iterator is single-use; a failed page yields only its error`
Example ¶
package main
import (
"context"
"fmt"
"github.com/compforge/go-stdx/iterx"
)
func main() {
// A real loader could query a database or a paginated API. Its cursor and
// batch size are private to this traversal.
values := []string{"alice", "bob", "carol"}
cursor := 0
page := func(ctx context.Context) ([]string, bool, error) {
if err := ctx.Err(); err != nil {
return nil, false, err
}
end := min(cursor+2, len(values))
items := values[cursor:end]
cursor = end
return items, cursor < len(values), nil
}
users := iterx.NewLoadingIterator(context.Background(), page)
for user, err := range users {
if err != nil {
fmt.Println("load:", err)
return
}
fmt.Println(user)
}
}
Output: alice bob carol
type PageFunc ¶
PageFunc loads the next batch. It owns query conditions, page size, and cursor state. Each iterator needs its own paging state. An empty batch with hasMore true is allowed, but the loader must still advance toward the end.
The loader must honor ctx and release per-query resources before returning. If err is non-nil, the iterator discards any items returned with it.