Fix V2ListIterator: concurrency guard and empty page handling (#2747)

Fix V2ListIterator: add concurrency guard and handle empty pages

V2ListIterator had two bugs:
1. No concurrency guard — parallel .next() calls could independently
   trigger page fetches, producing duplicate or out-of-order results.
2. Empty intermediate pages terminated iteration — if the API returned
   a page with data:[] but a valid next_page_url, iteration stopped
   instead of continuing to the next page.


Committed-By-Agent: claude

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jar-stripe

src/autoPagination.ts

@@ -173,6 +173,7 @@ class V2ListIterator<T> implements AsyncIterator<T> {
   private firstPagePromise: Promise<PageResult<T>> | null;
   private currentPageIterator: Iterator<T> | null;
   private nextPageUrl: string | null;
+  private promiseCache: PromiseCache;
   private options: RequestOptions | undefined;
   private spec: MakeRequestSpec | undefined;
   private stripeResource: StripeResourceObject;
@@ -185,6 +186,7 @@ class V2ListIterator<T> implements AsyncIterator<T> {
     this.firstPagePromise = firstPagePromise;
     this.currentPageIterator = null;
     this.nextPageUrl = null;
+    this.promiseCache = {currentPromise: null};
     this.options = options;
     this.spec = spec;
     this.stripeResource = stripeResource;
@@ -210,19 +212,45 @@ class V2ListIterator<T> implements AsyncIterator<T> {
     this.currentPageIterator = page.data[Symbol.iterator]();
     return this.currentPageIterator;
   }
-  async next(): Promise<IteratorResult<T>> {
+  private async _next(): Promise<IteratorResult<T>> {
     await this.initFirstPage();
     if (this.currentPageIterator) {
       const result = this.currentPageIterator.next();
       if (!result.done) return {done: false, value: result.value};
     }
+    return this.nextFromNewPage();
+  }
+  private async nextFromNewPage(): Promise<IteratorResult<T>> {
     const nextPageIterator = await this.turnPage();
     if (!nextPageIterator) {
       return {done: true, value: undefined};
     }
     const result = nextPageIterator.next();
     if (!result.done) return {done: false, value: result.value};
-    return {done: true, value: undefined};
+    // Empty intermediate page — recurse to try the next page.
+    return this.nextFromNewPage();
+  }
+  next(): Promise<IteratorResult<T>> {
+    /**
+     * If a user calls `.next()` multiple times in parallel,
+     * return the same result until something has resolved
+     * to prevent page-turning race conditions.
+     */
+    if (this.promiseCache.currentPromise) {
+      return this.promiseCache.currentPromise;
+    }
+
+    const nextPromise = (async (): Promise<IteratorResult<T>> => {
+      try {
+        return await this._next();
+      } finally {
+        this.promiseCache.currentPromise = null;
+      }
+    })();
+
+    this.promiseCache.currentPromise = nextPromise;
+
+    return nextPromise;
   }
 }
 

test/autoPagination.spec.ts

@@ -879,6 +879,39 @@ describe('auto pagination', () => {
         'Should not have any unhandled promise rejections'
       ).to.have.length(0);
     });
+
+    it('iterates through empty intermediate pages', () => {
+      return testCaseV2List({
+        pages: [
+          {ids: [1, 2], next_page_url: '/v2/items?page=a'},
+          {ids: [], next_page_url: '/v2/items?page=b'},
+          {ids: [], next_page_url: '/v2/items?page=c'},
+          {ids: [3, 4]},
+        ],
+        limit: 10,
+        expectedIds: [1, 2, 3, 4],
+        expectedParamsLog: ['?page=a', '?page=b', '?page=c'],
+      });
+    });
+
+    it('coalesces parallel next() calls at a page boundary into one request', async () => {
+      const {paginator, paramsLog} = mockPaginationV2List(
+        [{ids: [1], next_page_url: '/v2/items?page=foo'}, {ids: [2, 3]}],
+        {}
+      );
+
+      // Drain the first page
+      const first = await paginator.next();
+      expect((first as any).value.id).to.equal(1);
+
+      // Now at page boundary — fire parallel next() calls
+      const [r1, r2] = await Promise.all([paginator.next(), paginator.next()]);
+      expect(r1).to.deep.equal(r2);
+      expect((r1 as any).value.id).to.equal(2);
+
+      // Only one page request should have been made
+      expect(paramsLog).to.deep.equal(['?page=foo']);
+    });
   });
   describe('stack traces', () => {
     // Builds a paginator whose first page succeeds but whose second page