iterx

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 2 Imported by: 0

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

type LoadingIterator[T any] = iter.Seq2[T, error]

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

type PageFunc[T any] func(ctx context.Context) (items []T, hasMore bool, err error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL