Checklist

• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

I am upgrading to v5 because it was claimed that pagination support had improved.

However, after trying to upgrade simple code, I find both the migration guide and API docs to be lacking and/or inconsistent.

The Migration Guide (commit 3fda381) says (1):

// V5: Simple pagination with .data property

const clients = await client.clients.list({ per_page: 5, page: 1 });
for (const client of clients.data) {
    console.log(`Client ID: ${client.client_id}, Name: ${client.name}`);
}

Later it says (2):

In v5, client.actions.list() returns a response of type Page, over which the following pagination code is valid:

let page = await client.actions.list();
while (page.hasNextPage()) {
    page = await page.getNextPage();
    console.log(page);
}

But the docs (https://auth0.github.io/node-auth0/#pagination) say (3):

Some list endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:

e = await client.actions.list();
for await (const item of response) {
    console.log(item);
}

I'm assuming e was a typo for response but honestly not sure.

Then immediately the docs gives this other example (4):

// Or you can manually iterate page-by-page
let page = await client.actions.list();
while (page.hasNextPage()) {
    page = await page.getNextPage();
}

Of these four examples, Only (2) and (4) are consistent:

(1) sounds like it's claiming that we can loop through every client using the clients.list() result's .data array. It implies that it will continue fetching clients, starting at page: 1, taking per_page: 5 clients per request. It's saying that in our simple synchronous for-loop, we'll see all the clients, and all this pagination will be invisible to us.

(2) is claiming that .list() for .actions returns a Page type, so we can't automatically paginate over data like (1) but must explicitly call the Page methods.

(3) Is claiming that .actions.list() can be iterated directly (no .data necessary) and contradicts (2) claiming that .actions.list() returned a Page. Unless Page is Iterator-like somehow, this is clearly contradictory. (I tried and it does not, in fact, impl Iterator).

(4) Is also claiming that .actions.list() returns a Page, same as (2).

My questions reflect my confusion:

1. How should we actually be iterating through all the possible results after calling .list()? I don't care about pages, I just want to iterate through all the data in our tenant.
2. Are all .list() results the same structure? Or are certain endpoints supposed to be iteratable like (1) and others like (3) and others like (2)/(4)?
3. How actually should we manually page versus letting the library automatically page, for each structure available from question 2. ?

Reproduction

1. Read the Migration Guide
2. Read the docs
3. Try .list() for v5.0.0

Additional context

No response

node-auth0 version

v5.0.0

Node.js version

v20.19.5