Feature/#25 pagination

[easingthemes]

Closes #25

[easingthemes]

Example usage

(async () => {
    const model = 'article'
    const fields = `{
        title
        _path
        authorFragment {
          firstName
          profilePicture {
            ...on ImageRef {
              _authorUrl
            }
          }
        }
      }`
    
    // Cursor based: Loop all pages
    const cursorQueryAll = await aemHeadlessClient.runPaginatedQuery(model, { pageSize: 3 }, fields)
    for await (let value of cursorQueryAll) {
        console.log('cursorQueryAll', value)
    }
    // Cursor based: Manually get next page
    const cursorQuery = await aemHeadlessClient.runPaginatedQuery(model, { pageSize: 4 }, fields)
    while (true) {
        const { done, value } = await cursorQuery.next();
        if (done) break
        console.log('cursorQuery', value)
    }
})()

[duynguyen]

now that we have QueryBuilder, should we create another flavor of runQuery that leverages QB instead of passing the whole query?

[easingthemes]

runPaginatedQuery is exactly this.
I've covered all types:

• List
• Paginated
• byPath

The only overhead is that even if you don't want pagination, you still have to call .next().

        const pathQuery = await aemHeadlessClient.runPaginatedQuery(model, fields, { _path: '/content/dam/wknd-shared/en/magazine/alaska-adventure/alaskan-adventures' })
        const result = pathQuery.next()

        const offsetQuery = await aemHeadlessClient.runPaginatedQuery(model, fields, { limit: 3 })
        const { value } = await offsetQuery.next();

It's easy to add another flavour of runQuery, it will be just a method which calls runPaginatedQuery and also executes .next() in it.

The biggest problem here is to come up with a name for it :)

[duynguyen]

ok, I can see how it could be done currently, without runPaginatedQuery:

const qbResult = client.buildQuery(model, fields, args)
const response = await client.runQuery(qbResult.query)

is that correct?

[easingthemes]

Yes, it can be used like this also

[duynguyen]

it's great to have jsdoc types. Would be great to add also a d.ts types file for TS projects.

[easingthemes]

Added in separate PR: #45
It's generated from JSDocs
Although TS already support JSDocs same as .d.ts.

[stefangrimm]

Just for my understanding: This pattern uses the same approach under the hood than the one using done/next().

Or, in other words: this pattern does not load everything before entering the loop, it uses lazy loading whenever there are not enough items (aka the next page) is read.

Otherwise it would be counterproductive to what we're trying to achieve with paging.

[easingthemes]

It uses exactly the same code/approach as done/next,

const cursorQueryAll = await aemHeadlessClient.runPaginatedQuery
is not making any requests.

Requests are in for loop for each page.

[duynguyen]

as config and args are optional, can they come at the end?
my preferred function signature would be:

const graphQLQueryBuilder = (model, fields, config = {}, args = {})

And same for buildQuery. I'm the kind of lazy dev and if I don't want the optional params, I would just call buildQuery(model, fields) 😄

[easingthemes]

I thought the same at first. Here are the reason why I selected this order

• model and config are both configuration related, while fields and args are strictly GraphQL query related.
• While config is optional, it's using default 10 items page size, and it would be good for devs to know that they are choosing default behaviour with providing null to config.
• I would also expect that in real usage { pageSize } will always be part of config

But again this are minor reasons, if you still prefer the change I'll add it.

[duynguyen]

Could it work if fields is an empty string? will it then return some default fields?
If that's possible, I would keep the signature as is and make fields optional as well.
If that's not, I would move fields to next to model. Because fields is mandatory anyway, I see little distinction between configuration and GraphQL.

[easingthemes]

Order changed.

[stefangrimm]

I can't really go into the details, as I'm not very familiar with "modern JavaScript", but the general usage patterns look pretty good to me.

[duynguyen]

LGTM. thanks @easingthemes