fix(iterator): only query when the cache is empty

[dudanogueira]

Fixes #483

collection.iterator() sent one Search request for every object it returned. Each call to next() fetched a page of 100 objects after the last UUID, kept only the first and threw the rest away. Results were still correct, but iterating over N objects took N round trips and moved about 100 × N objects over the wire, including vectors when includeVector is set.

Approach

The iterator already had a cache field; it was just being overwritten on every call. Now next() only queries when the cache is empty, then returns objects from it one at a time, moving the after cursor to the UUID of each object it returns. When a page is used up, the next query starts after the last object of that page. The loop still stops on the first empty page, so iterating over N objects takes ceil(N / 100) + 1 requests instead of N + 1.

This doesn't stop early on a page with fewer than 100 objects. That would save the final empty request, but only by assuming the server always fills a page when more data exists. Stopping on an empty page is the rule the iterator already relied on.

Risks

• Page boundaries: the cursor is always the UUID of the last object actually returned, so no object is skipped or repeated. A test checks the exact (limit, after) sequence.
• Staleness: objects are now served from a page fetched up to 99 next() calls earlier, so a change made mid-iteration may not show up until the next page. This is normal for cursor pagination.

Testing

New src/collections/iterator/unit.test.ts uses a mocked query function, so it needs no server:

• For N = 0, 1, 99, 100, 101 and 250: all objects are returned in order, with exactly ceil(N / 100) + 1 query calls.
• For 250 objects: the query calls are exactly (100, undefined), (100, 'uuid-99'), (100, 'uuid-199'), (100, 'uuid-249').

5 of the 7 cases fail on the previous implementation.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[tsmith023]

imo, the double nesting is somewhat confusing here

can we have it so that we do?

if (this.cache.length == 0) { this.cache = await fetch }
if (this.cache.length == 0) { return done }

[dudanogueira]

Done in df0b955, flattened to the two sequential checks as suggested. Thanks!