Add more SeamPaginator tests

Author: razor-x

src/lib/seam/connect/seam-paginator.ts

@@ -10,6 +10,7 @@ interface SeamPaginatorParent {
 interface Pagination {
   readonly hasNextPage: boolean
   readonly nextPageCursor: string | null
+  readonly nextPageUrl: string | null
 }
 
 export class SeamPaginator<
@@ -24,21 +25,37 @@ export class SeamPaginator<
     parent: SeamPaginatorParent,
     request: SeamHttpRequest<TResponse, TResponseKey>,
   ) {
+    if (request.responseKey == null) {
+      throw new Error(
+        `The ${request.pathname} endpoint does not support pagination`,
+      )
+    }
     this.#parent = parent
     this.#request = request
   }
 
-  async first(): Promise<
+  async firstPage(): Promise<
     [EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]
   > {
-    return await this.fetch()
+    return await this.#fetch()
   }
 
-  async fetch(
-    nextPageCursor?: Pagination['nextPageCursor'],
+  async nextPage(
+    nextPageCursor: Pagination['nextPageCursor'],
   ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> {
+    if (nextPageCursor == null) {
+      throw new Error('Cannot get the next page with a null nextPageCursor')
+    }
+
+    return await this.#fetch(nextPageCursor)
+  }
+
+  readonly #fetch = async (
+    nextPageCursor?: Pagination['nextPageCursor'],
+  ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> => {
     const responseKey = this.#request.responseKey
-    if (typeof responseKey !== 'string') {
+
+    if (responseKey == null) {
       throw new Error('Cannot paginate a response without a responseKey')
     }
 
@@ -58,6 +75,7 @@ export class SeamPaginator<
         : {
             hasNextPage: false,
             nextPageCursor: null,
+            nextPageUrl: null,
           }
     if (!Array.isArray(data)) {
       throw new Error('Expected an array response')
@@ -70,10 +88,10 @@ export class SeamPaginator<
 
   async toArray(): Promise<EnsureReadonlyArray<TResponse[TResponseKey]>> {
     const items = [] as EnsureMutableArray<TResponse[TResponseKey]>
-    let [current, pagination] = await this.first()
+    let [current, pagination] = await this.firstPage()
     items.push(...current)
     while (pagination.hasNextPage) {
-      ;[current, pagination] = await this.fetch(pagination.nextPageCursor)
+      ;[current, pagination] = await this.nextPage(pagination.nextPageCursor)
       items.push(...current)
     }
     return items as EnsureReadonlyArray<TResponse[TResponseKey]>
@@ -82,12 +100,12 @@ export class SeamPaginator<
   async *flatten(): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
-    let [current, pagination] = await this.first()
+    let [current, pagination] = await this.firstPage()
     for (const item of current) {
       yield item
     }
     while (pagination.hasNextPage) {
-      ;[current, pagination] = await this.fetch(pagination.nextPageCursor)
+      ;[current, pagination] = await this.#fetch(pagination.nextPageCursor)
       for (const item of current) {
         yield item
       }
@@ -97,10 +115,10 @@ export class SeamPaginator<
   async *[Symbol.asyncIterator](): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
-    let [current, pagination] = await this.first()
+    let [current, pagination] = await this.firstPage()
     yield current
     while (pagination.hasNextPage) {
-      ;[current, pagination] = await this.fetch(pagination.nextPageCursor)
+      ;[current, pagination] = await this.nextPage(pagination.nextPageCursor)
       yield current
     }
   }

test/seam/connect/seam-paginator.test.ts

@@ -10,35 +10,98 @@ test('SeamPaginator: creates a SeamPaginator', async (t) => {
   t.true(pages instanceof SeamPaginator)
 })
 
-test('SeamPaginator: fetches an array of devices', async (t) => {
+test('SeamPaginator: cannot paginate a request with an empty response', async (t) => {
   const { seed, endpoint } = await getTestServer(t)
   const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
-  const pages = seam.createPaginator(seam.devices.list())
 
+  // @ts-expect-error Testing validation
+  t.throws(() => seam.createPaginator(seam.devices.update()), {
+    message: /does not support pagination/,
+  })
+})
+
+// TODO: Validate the request supports pagination by extending SeamHttpRequest with this knowledge via codegen.
+test.failing(
+  'SeamPaginator: cannot paginate an request that does not return pagination data',
+  async (t) => {
+    const { seed, endpoint } = await getTestServer(t)
+    const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
+
+    t.throws(() => seam.createPaginator(seam.workspaces.list()), {
+      message: /does not support pagination/,
+    })
+  },
+)
+
+test('SeamPaginator: firstPage returns the first page', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
+  const pages = seam.createPaginator(seam.devices.list({ limit: 2 }))
+  const [devices, pagination] = await pages.firstPage()
+  t.is(devices.length, 2)
+  t.true(pagination.hasNextPage)
+  t.truthy(pagination.nextPageCursor)
+  t.truthy(pagination.nextPageUrl)
+})
+
+test('SeamPaginator: nextPage returns the next page', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
+  const pages = seam.createPaginator(seam.devices.list({ limit: 2 }))
+  const [devices, { hasNextPage, nextPageCursor }] = await pages.firstPage()
+  t.is(devices.length, 2)
+  t.true(hasNextPage)
+  const [moreDevices] = await pages.nextPage(nextPageCursor)
+  t.is(moreDevices.length, 2)
+})
+
+test('SeamPaginator: nextPage requires the nextPageCursor', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
+  const pages = seam.createPaginator(seam.devices.list({ limit: 2 }))
+  await t.throwsAsync(async () => await pages.nextPage(null), {
+    message: /nextPageCursor/,
+  })
+})
+
+test('SeamPaginator: toArray returns an array of devices', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
+  const allDevices = await seam.devices.list()
+  const pages = seam.createPaginator(seam.devices.list({ limit: 1 }))
   const devices = await pages.toArray()
   t.true(devices.length > 1)
+  t.is(devices.length, allDevices.length)
 })
 
-test('SeamPaginator: flattens an array of devices', async (t) => {
+test('SeamPaginator: flatten allows iteration over all devices', async (t) => {
   const { seed, endpoint } = await getTestServer(t)
   const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
-  const pages = seam.createPaginator(seam.devices.list())
+  const allDevices = await seam.devices.list()
+  const pages = seam.createPaginator(seam.devices.list({ limit: 1 }))
 
   const devices = []
   for await (const device of pages.flatten()) {
     devices.push(device)
   }
   t.true(devices.length > 1)
+  t.is(devices.length, allDevices.length)
 })
 
-test('SeamPaginator: Fetches an array of pages', async (t) => {
+test('SeamPaginator: instance allows iteration over all pages', async (t) => {
   const { seed, endpoint } = await getTestServer(t)
   const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, { endpoint })
-  const pages = seam.createPaginator(seam.devices.list())
+  const allDevices = await seam.devices.list()
+  const pages = seam.createPaginator(seam.devices.list({ limit: 1 }))
 
   const devices = []
+  const allPages = []
   for await (const page of pages) {
-    devices.push(page)
+    t.is(page.length, 1)
+    allPages.push(page)
+    devices.push(...page)
   }
-  t.true(devices.length > 0)
+  t.true(allPages.length > 1)
+  t.true(devices.length > 1)
+  t.is(devices.length, allDevices.length)
 })