Prismic Client ignores and overwrites 'page' query param for getAll methods

[malee31]

Versions

• @prismicio/client: v7.13.1
• node: v20.11.0

Reproduction

Create 4 documents of the same type, configure the following snippet, and run.

import * as prismic from "@prismicio/client";

// Replace these with your Prismic repository name and a valid custom page type
const repo = "my-repo";
const documentType = "pages";

const client = prismic.createClient(repo, {
  fetch: (...args) => {
    // For inspecting the endpoint being hit
    if(args[0].includes(documentType)) {
      console.log(`GET: ${args[0]}`);
    }

    return fetch(...args);
  },
});

// IIFE attempting to fetch the first two pages and print their IDs
(async () => {
  const pageOne = await client.getAllByType(documentType, {
    page: 1,
    limit: 2,
    pageSize: 2,
    orderings: {
      field: "document.first_publication_date",
      direction: "desc",
    },
  });

  const pageTwo = await client.getAllByType(documentType, {
    page: 1,
    limit: 2,
    pageSize: 2,
    orderings: {
      field: "document.first_publication_date",
      direction: "desc",
    },
  });

  // None of these IDs should not be the same if paging is working properly
  // Currently, they both print the same results
  console.log(`Page One: [${pageOne.map(res => res.id).join(", ")}]`);
  console.log(`Page Two: [${pageTwo.map(res => res.id).join(", ")}]`);
})();

Steps to reproduce

1. Log into or create a new Prismic Repository
2. Create a new Page Type if one does not already exist
3. Publish at least 4 documents using the aforementioned page type
4. Copy the code above into a new folder as index.js
5. Initialize a Node Project repository with npm init
6. Install the Prismic Client with npm install @prismicio/client
7. Change the constants repo and documentType
8. Run node index.js

What is expected?

From the documentation for query method params, we are able to pass the ?page=# to the REST API to paginate our results with pageSize.

So passing in page: 2 should return the second page of results.

What is actually happening?

Regardless of which page is being queried for through the client getAll* functions, results start from the very first page.
The issue comes from src/Client.ts:622 where the starting page is always undefined which defaults to 1.

This can be fixed by changing the default value used by the client to start from actualParams.page when provided rather than undefined .

[github-actions]

This issue has been labeled as a bug since it was created using the 🚨 Bug Report Template.

Hi there, thank you so much for the report!

Following our Maintenance Process, we will review your bug report and get back to you next Wednesday. To ensure a smooth review of your issue and avoid unnecessary delays, please make sure your issue includes the following:

• Information about your environment and packages you use (Node.js version, package names and their versions, etc.)
  Feel free to attach a copy of your package.json file.
• Any troubleshooting steps you already went through
• A minimal reproduction of the issue, and/or instructions on how to reproduce it

If you have identified the cause of the bug described in your report and know how to fix it, you're more than welcome to open a pull request addressing it. Check out our quick start guide for a simple contribution process.

If you think your issue is a question (not a bug) and would like quicker support, please close this issue and forward it to an appropriate section on our community forum: https://community.prismic.io

- The Prismic Open-Source Team

[malee31]

I opened a PR for this issue.
I am waiting on a fix to be released to implement offset pagination to a new project that recently went into production and has hit the limit for how much can fit on one page.

[lihbr]

Hi @malee31, thank you so much for your research and effort in submitting a PR to @prismicio/client!

From the above context you shared, it looks like you're trying to implement document pagination using @prismicio/client's getAll* methods. Have you considered relying on the client get, getByType, etc. methods instead? We designed the getAll* methods to query all documents matching a query so paginating those methods sounds a bit off to me for now 🤔

Refactoring the above snippet, something like this should achieve the desired result:

-   const pageOne = await client.getAllByType(documentType, {
+   const { results: pageOne } = await client.getByType(documentType, {
     page: 1,
-    limit: 2,
     pageSize: 2,
     orderings: {
       field: "document.first_publication_date",
       direction: "desc",
     },
   });

-  const pageTwo = await client.getAllByType(documentType, {
+  const { results: pageTwo } = await client.getByType(documentType, {
     page: 2,
-    limit: 2,
     pageSize: 2,
     orderings: {
       field: "document.first_publication_date",
       direction: "desc",
     },
   });

Maybe I got the context wrong in what you're trying to achieve so happy to have another look at it :)

Best, Lucie

[malee31]

Hi @lihbr ,

Thank you, that does resolve my pagination use case.

After thinking about it more, while I no longer need this change, I think a starting page might still be worth adding to the getAll* methods.

Since the team designed getAll* methods as a convenience method for querying all applicable documents, the limit property is useful for systems that have memory limitations or want to redistributing the work across multiple processes/servers/executions.
But after the limit is reached from the first page, subsequent processes need to know the stopping point the getAll* process and use a separate method, like getBy* or GraphQL queries, to continue where it left off.
Any thoughts?

If not, it would be nice to put a warning message with a redirect/link for anyone else that passes in the page parameter. I would be willing to make changes to improve my PR for either case.

[malee31]

Outside of that, could I suggest that the documentation be improved to reflect the getBy* pagination option?
The only dedicated pagination documentation I could find (see below) uses GraphQL or queries to implement cursor pagination instead:

• Prismic Community Post - 2021 - First to appear on Google
• Prismic Community Post - 2020 - Second result on Google
• Prismic Documentation - Integration - Specifies ?page= for REST endpoint only. Result (1/2) in Prismic Documentation's Searchbar for pagination
• Prismic Documentation - (GraphQL) Pagination fields - Specifies cursor pagination, for those using GraphQL. Result (2/2) in Prismic Documentation's Searchbar for pagination

I think it would be helpful to have a dedicated page for how to paginate with @prismic/client using both offset or cursor pagination.

In case it helps, my initial confusion came from unclear documentation on the Prismic Client Technical Reference.

The page does not specify the type/properties of params, so I assumed them all to be the same and used the Query Methods Params section as my point of reference as it states "All of the query methods accept a params object. The params object can have the following properties".

Since the page property was included there, and a method named getAllByType exists... I tried that and it did not work.
The small Get-all methods paragraph could have clued me in since it stated These results are not paginated, but I assumed that getByType is intended for querying singular documents while getAllByType is meant for querying multiple and should support paging since that made more sense to me.