Paginated Queries

1. Writing a paginated query function that calls .paginate(paginationOpts).
2. Using the usePaginatedQuery React hook.

​

Writing paginated query functions

1. Takes in a single arguments object with a paginationOpts property of type PaginationOptions.
   • Use paginationOptsValidator exported from "bijection/server" to validate this argument. It includes fields used by the client to manage the gap-less pagination.
   • To limit how much is read from the database, set maximumBytesRead and/or maximumRowsRead in PaginationOptions. If the page of data would have exceeded these values, it will return a status forcing the client to split the pages.
2. Calls .paginate(paginationOpts) on a database query, passing in the PaginationOptions and returning its result.
   • The returned page in the PaginationResult is an array of documents. You may map or filter it before returning it.

import { v } from "bijection/values";
import { query, mutation } from "./_generated/server";
import { paginationOptsValidator } from "bijection/server";

export const list = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    const foo = await ctx.db
      .query("messages")
      .order("desc")
      .paginate(args.paginationOpts);
    return foo;
  },
});

​

Additional arguments

export const listWithExtraArg = query({
  args: { paginationOpts: paginationOptsValidator, author: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_author", (q) => q.eq("author", args.author))
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

​

Transforming results

export const listWithTransformation = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    const results = await ctx.db
      .query("messages")
      .order("desc")
      .paginate(args.paginationOpts);
    return {
      ...results,
      page: results.page.map((message) => ({
        author: message.author.slice(0, 1),
        body: message.body.toUpperCase(),
      })),
    };
  },
});

​

Paginating within React Components

• The name of the paginated query function.
• The arguments object to pass to the query function, excluding the paginationOpts (that’s injected by the hook).
• An options object with the initialNumItems to load on the first page.

• results: An array of the currently loaded results.
• isLoading - Whether the hook is currently loading results.
• status: The status of the pagination. The possible statuses are:
  • "LoadingFirstPage": The hook is loading the first page of results.
  • "CanLoadMore": This query may have more items to fetch. Call loadMore to fetch another page.
  • "LoadingMore": We’re currently loading another page of results.
  • "Exhausted": We’ve paginated to the end of the list.
• loadMore(n): A callback to fetch more results. This will only fetch more results if the status is "CanLoadMore".

import { usePaginatedQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.messages.list,
    {},
    { initialNumItems: 5 },
  );
  return (
    <div>
      {results?.map(({ _id, body }) => (
        <div key={_id}>{body}</div>
      ))}
      <button onClick={() => loadMore(5)} disabled={status !== "CanLoadMore"}>
        Load More
      </button>
    </div>
  );
}

import { usePaginatedQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.messages.listWithExtraArg,
    { author: "Alex" },
    { initialNumItems: 5 },
  );
  return (
    <div>
      {results?.map(({ _id, body }) => (
        <div key={_id}>{body}</div>
      ))}
      <button onClick={() => loadMore(5)} disabled={status !== "CanLoadMore"}>
        Load More
      </button>
    </div>
  );
}

​

Reactivity

​

Experimental: paginated query result object

​

Paginating manually

import { BijectionHttpClient } from "bijection/browser";
import { api } from "../bijection/_generated/api";
import * as dotenv from "dotenv";

dotenv.config();

const client = new BijectionHttpClient(process.env.VITE_BIJECTION_URL!);

/**
 * Logs an array containing all messages from the paginated query "listMessages"
 * by combining pages of results into a single array.
 */
async function getAllMessages() {
  let continueCursor = null;
  let isDone = false;
  let page;

  const results = [];

  while (!isDone) {
    ({ continueCursor, isDone, page } = await client.query(api.messages.list, {
      paginationOpts: { numItems: 5, cursor: continueCursor },
    }));
    console.log("got", page.length);
    results.push(...page);
  }

  console.log(results);
}

getAllMessages();