feat: add scroll / iteration helpers

README.md

@@ -39,6 +39,30 @@ type Client
     func (c *Client) ReadItemSingle(ctx context.Context, b Bucket, pk string, sk string) (Item, CausalityToken, error)
 ```
 
+## Scrolling (Client-side / Go API)
+To handle iteration in the K2V API, helper functions for simple cases are provided.
+
+For example, to perform a bulk search:
+```go
+handleBatch := func(result *k2v.BatchSearchResult) error {
+  log.Println(result.Items)
+  return nil
+}
+err := k2v.ScrollBatchSearch(ctx, f.cli, f.bucket, []k2v.BatchSearch{
+  {
+    PartitionKey: "pk1",
+  },
+  {
+    PartitionKey: "pk2",
+    Limit:        1,
+  },
+}, handleBatch)
+```
+
+This will repeatedly make calls to **ReadBatch** (batch search), using `nextStart` from the responses to generate subsequent requests until all queries are exhausted.
+
+See `ScrollIndex(ctx context.Context, client IndexScroller, b Bucket, query ReadIndexQuery, fn ReadIndexResponseHandler) error` for the equivalent for batch index reads.
+
 ## Integration Tests
 ```shell
 K2V_ENDPOINT="http://[::1]:3904" \