Fix pagination resumption in local world (#299)

Author: VaguelySerious

.changeset/lucky-breads-fry.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-local": patch
+---
+
+When paginating, return a cursor even at the end of the list, to allow for stable resumption

packages/world-local/src/fs.test.ts

@@ -131,7 +131,8 @@ describe('fs utilities', () => {
 
         expect(result.data).toHaveLength(5);
         expect(result.hasMore).toBe(false);
-        expect(result.cursor).toBeNull();
+        // Cursor should be set even when hasMore is false (for stable pagination)
+        expect(result.cursor).not.toBeNull();
 
         // Should be sorted in descending order (newest first)
         assert(result.data[0], 'expected first item to be defined');

packages/world-local/src/fs.ts

@@ -260,7 +260,7 @@ export async function paginatedFileSystemQuery<T extends { createdAt: Date }>(
   const hasMore = validItems.length > limit;
   const items = hasMore ? validItems.slice(0, limit) : validItems;
   const nextCursor =
-    hasMore && items.length > 0
+    items.length > 0
       ? createCursor(
           items[items.length - 1].createdAt,
           getId?.(items[items.length - 1])

packages/world-local/src/storage.test.ts

@@ -478,6 +478,210 @@ describe('Storage', () => {
         expect(page2.data).toHaveLength(2);
         expect(page2.data[0].stepId).not.toBe(page1.data[0].stepId);
       });
+
+      it('should handle pagination when new items are created after getting a cursor', async () => {
+        // Create initial set of items (4 items)
+        for (let i = 0; i < 4; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // Get first page with limit=4 (should return all 4 items)
+        const page1 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4 },
+        });
+
+        expect(page1.data).toHaveLength(4);
+        expect(page1.hasMore).toBe(false);
+        // With the fix, cursor should be set to the last item even when hasMore is false
+        expect(page1.cursor).not.toBeNull();
+
+        // Now create 4 more items (total: 8 items)
+        for (let i = 4; i < 8; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // Try to get the "next page" using the old cursor (which was null)
+        // This should show that we can't continue from where we left off
+        const page2 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4 },
+        });
+
+        // Should now return 4 items (the newest ones: step_7, step_6, step_5, step_4)
+        expect(page2.data).toHaveLength(4);
+        expect(page2.hasMore).toBe(true);
+
+        // Get the next page using the cursor from page2
+        const page3 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4, cursor: page2.cursor || undefined },
+        });
+
+        // Should return the older 4 items (step_3, step_2, step_1, step_0)
+        expect(page3.data).toHaveLength(4);
+        expect(page3.hasMore).toBe(false);
+
+        // Verify no overlap
+        const page2Ids = new Set(page2.data.map((s) => s.stepId));
+        const page3Ids = new Set(page3.data.map((s) => s.stepId));
+
+        for (const id of page3Ids) {
+          expect(page2Ids.has(id)).toBe(false);
+        }
+      });
+
+      it('should handle pagination with cursor after items are added mid-pagination', async () => {
+        // Create initial 4 items
+        for (let i = 0; i < 4; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // Get first page with limit=2
+        const page1 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 2 },
+        });
+
+        expect(page1.data).toHaveLength(2);
+        expect(page1.hasMore).toBe(true);
+        const cursor1 = page1.cursor;
+
+        // Get second page
+        const page2 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 2, cursor: cursor1 || undefined },
+        });
+
+        expect(page2.data).toHaveLength(2);
+        expect(page2.hasMore).toBe(false);
+        const cursor2 = page2.cursor;
+
+        // With the fix, cursor2 should NOT be null even when hasMore is false
+        expect(cursor2).not.toBeNull();
+
+        // Now add 4 more items (total: 8)
+        for (let i = 4; i < 8; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // Try to continue with cursor2 (should return no items since we're at the end)
+        // The cursor marks where we left off, so continuing from there should not return
+        // the newly created items (which are newer than the cursor position)
+        const page3 = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 2, cursor: cursor2 || undefined },
+        });
+
+        expect(page3.data).toHaveLength(0);
+        expect(page3.hasMore).toBe(false);
+
+        // But if we use cursor1 again (from the first page), we should still get the next 2 items
+        // This verifies that the cursor is stable and repeatable
+        const page2Retry = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 2, cursor: cursor1 || undefined },
+        });
+
+        // Should return 2 items that come after cursor1 position
+        // In descending order, these would be the next 2 oldest items
+        expect(page2Retry.data).toHaveLength(2);
+
+        // The items should be the same as page2 originally returned
+        // (the cursor position is stable regardless of new items added)
+        expect(page2Retry.data[0].stepId).toBe(page2.data[0].stepId);
+        expect(page2Retry.data[1].stepId).toBe(page2.data[1].stepId);
+      });
+
+      it('should reproduce GitHub issue #298: pagination after reaching the end and creating new items', async () => {
+        // This test reproduces the exact scenario from issue #298
+        // https://github.com/vercel/workflow/issues/298
+
+        // Start with X items (4 items)
+        for (let i = 0; i < 4; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // First page contains X items if limit=X
+        const firstPage = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4 },
+        });
+
+        expect(firstPage.data).toHaveLength(4);
+        expect(firstPage.hasMore).toBe(false);
+        const firstCursor = firstPage.cursor;
+
+        // Cursor should be set even when we reached the end
+        expect(firstCursor).not.toBeNull();
+
+        // Create new items (total becomes 2X = 8 items)
+        for (let i = 4; i < 8; i++) {
+          await storage.steps.create(testRunId, {
+            stepId: `step_${i}`,
+            stepName: `step-${i}`,
+            input: [],
+          });
+        }
+
+        // Next page with cursor=<previous-request-cursor> should return 0 items
+        // because the cursor marks where we left off, and there are no items
+        // OLDER than the cursor position (in descending order)
+        const nextPage = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4, cursor: firstCursor || undefined },
+        });
+
+        expect(nextPage.data).toHaveLength(0);
+        expect(nextPage.hasMore).toBe(false);
+
+        // If we start from the beginning (no cursor), we should get the newest 4 items
+        const freshPage = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4 },
+        });
+
+        expect(freshPage.data).toHaveLength(4);
+        expect(freshPage.hasMore).toBe(true);
+
+        // The fresh page should contain the new items (step_7, step_6, step_5, step_4)
+        expect(freshPage.data[0].stepId).toBe('step_7');
+        expect(freshPage.data[1].stepId).toBe('step_6');
+        expect(freshPage.data[2].stepId).toBe('step_5');
+        expect(freshPage.data[3].stepId).toBe('step_4');
+
+        // And the second page should contain the original items
+        const secondPage = await storage.steps.list({
+          runId: testRunId,
+          pagination: { limit: 4, cursor: freshPage.cursor || undefined },
+        });
+
+        expect(secondPage.data).toHaveLength(4);
+        expect(secondPage.data[0].stepId).toBe('step_3');
+        expect(secondPage.data[1].stepId).toBe('step_2');
+        expect(secondPage.data[2].stepId).toBe('step_1');
+        expect(secondPage.data[3].stepId).toBe('step_0');
+      });
     });
   });