refactor!: implement lazy iterators for several APIs (#4459)

Implement lazy iterators for:
- secrets
- views
- jobs
- functions
- materialized views

nodejs/__test__/materialized_view.test.ts

@@ -112,7 +112,7 @@ describe("materialized views", () => {
     await db.createMaterializedView("adults", "people", {
       where: "age >= 18",
     });
-    expect(await db.listMaterializedViews()).toEqual(["adults"]);
+    expect(await collect(db.listMaterializedViews())).toEqual(["adults"]);
     await expect(db.openMaterializedView("people")).rejects.toThrow(
       "not a materialized view",
     );
@@ -121,7 +121,7 @@ describe("materialized views", () => {
     );
 
     await db.dropMaterializedView("adults");
-    expect(await db.listMaterializedViews()).toEqual([]);
+    expect(await collect(db.listMaterializedViews())).toEqual([]);
   });
 
   it("returns a job when dropping a view asynchronously", async () => {
@@ -130,7 +130,7 @@ describe("materialized views", () => {
     const job = await db.dropMaterializedViewAsync("adults");
     expect(job.id).toBeNull();
     await job.wait();
-    expect(await db.listMaterializedViews()).toEqual([]);
+    expect(await collect(db.listMaterializedViews())).toEqual([]);
   });
 
   it("rejects an invalid expression at create time", async () => {
@@ -147,7 +147,7 @@ describe("materialized views", () => {
         db.createMaterializedView("bad", "people", { limit }),
       ).rejects.toThrow("non-negative integer");
     }
-    expect(await db.listMaterializedViews()).toEqual([]);
+    expect(await collect(db.listMaterializedViews())).toEqual([]);
 
     const view = await db.createMaterializedView("copy", "people");
     for (const sourceVersion of [-1, 1.5, Infinity, NaN]) {
@@ -173,3 +173,9 @@ describe("materialized views", () => {
     expect(await view.table().countRows()).toBe(1);
   });
 });
+
+async function collect<T>(items: AsyncIterable<T>): Promise<T[]> {
+  const result: T[] = [];
+  for await (const item of items) result.push(item);
+  return result;
+}

nodejs/__test__/remote.test.ts

@@ -258,7 +258,9 @@ describe("remote connection", () => {
           .end(JSON.stringify({ views: ["daily_sales"] }));
       },
       async (db) => {
-        expect(await db.listMaterializedViews()).toEqual(["daily_sales"]);
+        expect(await collect(db.listMaterializedViews())).toEqual([
+          "daily_sales",
+        ]);
       },
     );
   });
@@ -308,7 +310,7 @@ describe("remote connection", () => {
           .end(JSON.stringify({ views: ["adults"] }));
       },
       async (db) => {
-        expect(await db.listViews()).toEqual(["adults"]);
+        expect(await collect(db.listViews())).toEqual(["adults"]);
       },
     );
 
@@ -1377,7 +1379,7 @@ describe("remote connection jobs surface", () => {
         });
       },
       async (db) => {
-        const jobs = await db.listJobs();
+        const jobs = await collect(db.listJobs());
         expect(jobs.map((job) => job.jobId)).toEqual(["job-1", "job-2"]);
         expect(jobs[0].state).toEqual("running");
         expect(jobs[1].state).toEqual("finished");
@@ -1473,3 +1475,147 @@ describe("remote connection jobs surface", () => {
     );
   });
 });
+
+async function collect<T>(items: AsyncIterable<T>): Promise<T[]> {
+  const result: T[] = [];
+  for await (const item of items) result.push(item);
+  return result;
+}
+
+describe("lazy resource listings", () => {
+  for (const kind of ["views", "materializedViews", "jobs"] as const) {
+    const listing = (
+      db: Connection,
+      options: { pageToken?: string; pageLimit?: number } = {},
+    ) => {
+      if (kind === "jobs") return db.listJobs(options);
+      if (kind === "views") return db.listViews(["team"], options);
+      return db.listMaterializedViews(options);
+    };
+    const page = (names: string[], token?: string) => {
+      const items =
+        kind === "jobs"
+          ? names.map((name) => ({
+              // biome-ignore lint/style/useNamingConvention: server wire format
+              job_id: name,
+              table: "t",
+              // biome-ignore lint/style/useNamingConvention: server wire format
+              job_type: "create_index",
+              state: "in_progress",
+              // biome-ignore lint/style/useNamingConvention: server wire format
+              created_at_millis: 1,
+            }))
+          : names;
+      return {
+        [kind === "jobs" ? "jobs" : "views"]: items,
+        // biome-ignore lint/style/useNamingConvention: server wire format
+        page_token: token,
+      };
+    };
+
+    it(`${kind} fetches lazily, skips empty pages, and resumes`, async () => {
+      const requests: { url: string; body: Record<string, unknown> }[] = [];
+      const responses = [
+        page(["a", "b"], "empty"),
+        page([], "last"),
+        page(["c", "d"], ""),
+      ];
+      await withMockDatabase(
+        async (req, res) => {
+          const chunks: Buffer[] = [];
+          for await (const chunk of req) chunks.push(Buffer.from(chunk));
+          const body = Buffer.concat(chunks).toString();
+          requests.push({
+            url: req.url ?? "",
+            body: body ? JSON.parse(body) : {},
+          });
+          res
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify(responses.shift()));
+        },
+        async (db) => {
+          const items = listing(db, { pageToken: "start/token", pageLimit: 2 });
+          expect(requests).toHaveLength(0);
+          expect(items.pageToken()).toBe("start/token");
+          expect(items.numPageResults()).toBe(0);
+          expect((await items.next()).done).toBe(false);
+          expect(items.numPageResults()).toBe(1);
+          expect(items.pageToken()).toBe("empty");
+          await items.next();
+          expect(requests).toHaveLength(1);
+          const resumed = listing(db, {
+            pageToken: items.pageToken(),
+            pageLimit: 2,
+          });
+          await resumed.next();
+          expect(resumed.numPageResults()).toBe(1);
+          expect(resumed.pageToken()).toBeUndefined();
+          expect(requests).toHaveLength(3);
+          await resumed.next();
+          expect((await resumed.next()).done).toBe(true);
+          expect((await resumed.next()).done).toBe(true);
+          for (const [i, request] of requests.entries()) {
+            const token = ["start/token", "empty", "last"][i];
+            const url = new URL(request.url, "http://localhost");
+            if (kind === "jobs") {
+              expect(url.pathname).toBe("/v1/jobs/list");
+              expect(request.body).toEqual({
+                // biome-ignore lint/style/useNamingConvention: server wire format
+                page_token: token,
+                limit: 2,
+              });
+            } else {
+              expect(url.pathname).toBe(
+                kind === "views"
+                  ? "/v1/namespace/team/view/list"
+                  : "/v1/namespace/$/materialized_view/list",
+              );
+              expect(url.searchParams.get("page_token")).toBe(token);
+              expect(url.searchParams.get("limit")).toBe("2");
+            }
+          }
+        },
+      );
+    });
+
+    it(`${kind} retains failed tokens and serializes concurrent advances`, async () => {
+      let requests = 0;
+      await withMockDatabase(
+        (_req, res) => {
+          requests += 1;
+          res
+            .writeHead(requests === 1 ? 401 : 200, {
+              "content-type": "application/json",
+            })
+            .end(JSON.stringify(requests === 1 ? {} : page(["a", "b"])));
+        },
+        async (db) => {
+          const failed = listing(db, { pageToken: "retry" });
+          await expect(failed.next()).rejects.toThrow();
+          expect(failed.pageToken()).toBe("retry");
+          expect((await failed.next()).done).toBe(true);
+          expect(requests).toBe(1);
+          const resumed = listing(db, { pageToken: failed.pageToken() });
+          const results = await Promise.all([
+            resumed.next(),
+            resumed.next(),
+            resumed.next(),
+          ]);
+          expect(results.filter((result) => result.done)).toHaveLength(1);
+          expect(requests).toBe(2);
+          for (const limit of [
+            0,
+            -1,
+            1.5,
+            Number.NaN,
+            Number.POSITIVE_INFINITY,
+            2147483648,
+          ]) {
+            expect(() => listing(db, { pageLimit: limit })).toThrow("limit");
+          }
+          expect(requests).toBe(2);
+        },
+      );
+    });
+  }
+});