DEV Community: ardsh

Implementing Cursor Pagination with tRPC queries

ardsh — Tue, 17 Jan 2023 07:05:54 +0000

We're gonna continue where we left off in the last article in the series.

I've chosen to demonstrate cursor-based pagination, since it's a more evolved version compared to offset-based, however as you'll see offset-based pagination can be implemented in much the same way, only simpler.

Setup

For this tutorial I'm gonna use slonik-trpc for fetching data from a postgres database. It's this abstraction I created using slonik, to make it easy to build these kinds of tRPC APIs, with pure SQL queries.

With it you can declare any SQL query as a relation, and create an API from that. It handles all the details of pagination with cursors (and offsets), selecting fields, sorting and filtering etc.

You also need a PostgreSQL database to use slonik.
This is a good article for free PostgreSQL databases in the cloud. Once you have a DATABASE_URL you can use it with slonik.

Problem Requirements

We want to be able to load a page in a table of employees. Then, we want to be able to navigate to the next page, and the previous page (two-way cursor pagination).
Finally, we want to be able to jump to the last page, or the first page.

Saving the pagination state

We start by defining the state in a reducer. This is fairly boilerplate, but basically, we're gonna save this state:

type CursorPagination = {
    /** The current page cursor. If empty, we're in the first page.
     * Whenever we change the page, this changes.
    */
    currentCursor?: string,
    /** A counter that keeps track of the current page.
     * Useful if we want to show a page number in the UI */
    currentPage?: number | null,
    /** The first cursor of the current page, as specified by the data source*/
    startCursor?: string,
    /** The end cursor of the current page, as specified by the data source */
    endCursor?: string,
    /** Whether the data source has a next page */
    hasNextPage?: boolean,
    /** Whether the data source has a previous page */
    hasPreviousPage?: boolean,
    /** Whether we're paging backwards (used when going to previous/last page) */
    reverse?: boolean,
    /** The amount of items to take */
    pageSize?: number,
}

And we'll use these actions to change the data:

export type CursorPaginationAction = {
    type: 'UPDATE_DATA',
    // Update cursors when data changes
    data: {
        startCursor?: string | null,
        endCursor?: string | null,
        hasNextPage?: boolean,
        hasPreviousPage?: boolean,
    }
} | {
    type: 'TABLE_CHANGE',
    // Change the page size
    pageSize: number,
} | {
    type: 'FIRST_PAGE',
} | {
    type: 'LAST_PAGE',
} | {
    type: 'NEXT_PAGE',
} | {
    type: 'PREVIOUS_PAGE',
}

The rest of the reducer code is just boilerplate, updating the state based on actions, I'll show the code at the end.

export  function  cursorPaginationReducer(state: CursorPagination = initialCursorPagination, action: CursorPaginationAction): CursorPagination {
    // ...
}

Pagination Component UI

You can build a UI component that has 4 buttons (first, previous, next, last) and a page size dropdown. Its state would be managed by a hook that uses the above reducer, so when rendering we'd do

<CursorPagination
    {...employeeLoader.usePaginationProps()}

The API

The API should return the pageInfo with startCursor, endCursor, hasNextPage and hasPreviousPage.

This API will be built using slonik-trpc. I'll explain the backend part in another article in this series.

Attaching to tableDataLoader

We already have a tableDataLoader for declaring table columns, from the previous article.

Now we need to add two more functions for cursor pagination functionality,usePaginationProps and useUpdateQueryData

export const createTableLoader = <TPayload extends Record<string, any>>() => {
  // ...
  return {
    ContextProvider,
    useVariables,
    usePaginationProps,
    useUpdateQueryData,
    createColumn,
    useColumns
  }
}

useUpdateQueryData

This hook is supposed to be called right after the tRPC query.
The reason we call this is to update the start and end cursors of each page, when they change.

This way, the cursor reducer can be fully responsible for paginating through pages. E.g. when the NEXT_PAGE action is dispatched, the cursor pagination reducer can change its current cursor to be endCursor, or when moving to the previous page, we'd change currentCursor to be startCursor and use a negative take, to be able to query the previous 25 items.

Anyway, the actual update query hook is simple, it just dispatches the UPDATE_DATA action whenever data changes.

useUpdateQueryData: (data?: {
  nodes?: readonly TPayload[] | null,
  pageInfo?: {
    hasNextPage?: boolean,
    hasPreviousPage?: boolean,
    startCursor?: string | null,
    endCursor?: string | null,
  }
}) => {
  const dispatch = React.useContext(DispatchContext);

  React.useEffect(() => {
    if (data) {
      dispatch({
        type: 'UPDATE_DATA',
        data,
      });
    }
  }, [data, dispatch]);
},

Saving the cursor pagination state

I want to compose the entire pagination state inside the table data loader, to make it easier to work with (e.g. by composing the pagination context inside the same ContextProvider, we can only use a single ContextProvider).

There might be better ways to do this, but a simple way is to just call the pagination reducer within the larger state reducer that also saves the dependencies array.

import { CursorPaginationAction, CursorPagination, cursorPaginationReducer } from './useCursorPagination';


type Action = {
  type: "APPEND_FIELDS",
  dependencies: string[]
} | CursorPaginationAction;

const stateReducer = (state: State, action: Action) => {
  switch (action.type) {
    case 'APPEND_FIELDS':
      return {
        ...state,
        // Sort alphabetically to have a stable array
        dependencies: [... new Set(state.dependencies.concat(action.dependencies))].sort(),
      };
    default: return {
      ...state,
      pagination: cursorPaginationReducer(state.pagination, action),
    };
  }
}

export const  createTableLoader = <TPayload  extends  Record<string, any>>() => {
  const initialState = {
    dependencies: [],
    pagination: initialCursorPagination,
  };
  const DependenciesContext = React.createContext([] as (keyof TPayload)[]);
  const PaginationContext = React.createContext(initialCursorPagination);
  const DispatchContext = React.createContext((() => {
    throw new Error("tableDataLoader Context provider not found!");
  }) as React.Dispatch<Action>);

  return {
    ContextProvider: ({ children }: { children: React.ReactNode }) => {
      const [state, dispatch] = React.useReducer(stateReducer, initialState);
      return (<DispatchContext.Provider value={dispatch}>
        <DependenciesContext.Provider value={state.dependencies}>
          <PaginationContext.Provider value={state.pagination}>
            {children}
          </PaginationContext.Provider>
        </DependenciesContext.Provider>
      </DispatchContext.Provider>)
    },

The table data loader is now getting a bit more complicated, but it's still very nice to use because we've split the contexts and grouped them all in a single ContextProvider.

We're gonna need the pagination context provider in the usePaginationProps hook.

usePaginationProps

I want to simply call usePaginationProps and pass its return value down to the CursorPagination component, and not worry about managing the state of specific tables.

const getPaginationProps = employeeLoader.usePaginationProps();

// ...

<CursorPagination {...getPaginationProps()} />

This is very useful when we have lots of different tables, and we don't want to write code for handling each one of them.

So the CursorPagination component is dependent on this hook, which means this hook should return functions like onNext, onPrevious, and currentPage, all things that are stored within our cursor pagination state, or are action dispatcher functions (e.g. onNext).

So implementation would be something like this:

usePaginationProps: () => {
  const dispatch = React.useContext(DispatchContext);
  const pagination = React.useContext(PaginationContext);

  const getPaginationProps = React.useCallback(() => ({
    onNext: () => dispatch({ type: 'NEXT_PAGE' }),
    onPrevious: () => dispatch({ type: 'PREVIOUS_PAGE' }),
    onLast: () => dispatch({ type: 'LAST_PAGE' }),
    onFirst: () => dispatch({ type: 'LAST_PAGE' }),
    onPageSizeChange: (pageSize: number) => dispatch({ type: 'TABLE_CHANGE', pageSize }),
    currentPage: pagination.currentPage,
  }), [dispatch, pagination]);

  return getPaginationProps;
},

Usage

We change the useVariables hook to include take and cursor, so that variables change whenever the current pagination cursor changes, and the page data is then fetched.

useVariables: () => {
  const dependencies = React.useContext(DependenciesContext);
  const { currentCursor, pageSize = 25, reverse } = React.useContext(PaginationContext);

  return React.useMemo(() => ({
    select: dependencies,
    take: reverse ? -pageSize : pageSize,
    takeCursors: true,
    cursor: currentCursor,
  }), [dependencies, currentCursor, reverse, pageSize]);
},

When using it in the component, we just have to add an useUpdateQueryData call after getting the data

const pagination = employeeTableLoader.useVariables();
const { data, isLoading } = trpc.employees.getPaginated.useQuery({
    ...pagination,
});
employeeTableLoader.useUpdateQueryData(data);

Complete Implementation

You can see a similar example implementation at slonik-trpc/examples/datagrid-example

useCursorPagination

This is the complete implementation of useCursorPagination actions and reducer.

import React from "react";

export interface GetCursorPaginationProps {
    (): CursorPagination
}

export const initialCursorPagination: CursorPagination = {
    hasNextPage: false,
    currentPage: 1,
    hasPreviousPage: false,
    currentCursor: '',
    startCursor: '',
    endCursor: '',
    reverse: false,
    pageSize: 25,
}

export type CursorPaginationAction = {
    type: 'UPDATE_DATA',
    data: {
        startCursor?: string | null,
        endCursor?: string | null,
        hasNextPage?: boolean,
        hasPreviousPage?: boolean,
    }
} | {
    type: 'TABLE_CHANGE',
    pageSize: number,
} | {
    type: 'FIRST_PAGE',
} | {
    type: 'LAST_PAGE',
} | {
    type: 'NEXT_PAGE',
} | {
    type: 'PREVIOUS_PAGE',
}

export type CursorPagination = {
    /** The current page cursor. If empty, we're in the first page.
     * Whenever we change the page, this changes.
    */
    currentCursor?: string,
    /** A counter that keeps track of the current page.
     * Useful if we want to show a page number in the UI */
    currentPage?: number | null,
    /** The first cursor of the current page, as specified by the data source*/
    startCursor?: string,
    /** The end cursor of the current page, as specified by the data source */
    endCursor?: string,
    /** Whether the data source has a next page */
    hasNextPage?: boolean,
    /** Whether the data source has a previous page */
    hasPreviousPage?: boolean,
    /** Whether we're paging backwards (used when going to previous/last page) */
    reverse?: boolean,
    /** The amount of items to take */
    pageSize?: number,
}

export function cursorPaginationReducer(state: CursorPagination = initialCursorPagination, action: CursorPaginationAction): CursorPagination {
    switch (action.type) {
        case 'TABLE_CHANGE':
            return {
                ...state,
                currentCursor: '', // Go to first page
                currentPage: 1,
                hasNextPage: true,
                hasPreviousPage: false,
                reverse: false,
                pageSize: action.pageSize,
            }
        case 'UPDATE_DATA':
            return {
                ...state,
                ...(action.data?.startCursor && { startCursor: action.data.startCursor }),
                ...(action.data?.endCursor && { endCursor: action.data.endCursor }),
                hasNextPage: action.data?.hasNextPage,
                hasPreviousPage: action.data?.hasPreviousPage,
            }
        case 'NEXT_PAGE':
            return {
                ...state,
                // Increment current page tracker if currentPage wasn't null
                currentPage: state.currentPage !== null && state.currentCursor !== state.endCursor ?
                    (state.currentPage || 1) + 1 : null,
                hasPreviousPage: true,
                hasNextPage: false,
                currentCursor: state.endCursor,
                reverse: false,
            }
        case 'PREVIOUS_PAGE':
            return {
                ...state,
                // Keep track of current page in the counter
                currentPage: state.currentPage !== null && state.currentCursor !== state.startCursor ?
                    Math.max(1, (state.currentPage || 1) - 1) : null,
                hasNextPage: true,
                hasPreviousPage: false,
                currentCursor: state.startCursor,
                reverse: true,
            }
        case 'LAST_PAGE':
            return {
                ...state,
                // Setting currentPage to null when going to last page because total count is unknown
                currentPage: null,
                hasPreviousPage: true,
                hasNextPage: false,
                currentCursor: '',
                reverse: true,
            }
        case 'FIRST_PAGE':
            return {
                ...state,
                currentPage: 1,
                hasNextPage: true,
                hasPreviousPage: false,
                currentCursor: '',
                reverse: false,
            }
        default:
            return state;
    }
}

Notes

One thing to be careful here is when sorting data with different columns, the old cursor won't be stable, as it will refer to a different sorting configuration (read the slack cursor pagination article for more details on how base64 encoded cursors work).

So when we change the sorting columns, e.g. when sorting by salary after we've sorted by name, the cursor needs to be reset as well.
Usually that means going to the first page (an empty cursor means we're in the first page).

What's next?

Stay tuned for the next articles in this series, which will explain more in detail how to build the backend of this API, and also different patterns for tRPC queries selective type-safety.

Solving the overfetching problem with tRPC when rendering tables (Pt. 1)

ardsh — Sun, 15 Jan 2023 22:48:21 +0000

A common issue when using tRPC over GraphQL is the fact that overfetching is supposed to be solved by GraphQL, but it's not clear how you can do the same thing with tRPC.

I'm gonna try to show a pattern of how to create react tables with optional columns, when not all columns are supposed to be visible to the user.

In that case, we want to fetch only the data for the columns that we display, and not fetch all the data a tRPC query has to offer.

This is the first part in a series of articles for creating and querying tRPC queries, in efficient, type-safe methods.

Setup

I'll use React Table Library for the UI, but this pattern can work with most other tables or datagrids in a very similar way.

Solution

We can implement selective fetching in our tRPC APIs, using a select array that we pass as an argument. Doing so manually isn't too difficult, but you can also use a package like slonik-trpc that is designed to implement this kind of API automatically.

We're gonna abstract this handling of dependencies (and pagination) in its own generic function like below:

export const createTableLoader = <TPayload extends Record<string, any>>() => {
  // define initial state, context providers, and reducer
  // ...
  return {
    ContextProvider,
    useVariables,
    createColumn,
    useColumns
  }
}

This function takes a generic parameter for the type of data we're trying to load, e.g. an Employee type, and will be responsible for storing the dependencies of all visible columns, as well as making the column declaration type-safe, and any other table-related data fetching responsibilities.

Example implementation

Let's say you're building a table that displays employee information, using this type:

type Employee = {
  id: number;
  firstName: string;
  lastName: string;
  email: string;
  jobTitle: string;
  company: {
    name: string;
  };
}

Then you'd declare the columns like below:

const employeeColumns = employeeLoader.useColumns([{
  label: 'Name',
  dependencies: ["firstName", "lastName"],
  renderCell: (employee) => {
    return <div>{employee.firstName} {employee.lastName}</div>
  },
}, {
  label: 'Email',
  dependencies: ["email"],
  renderCell: (employee) => employee.email,
}, {
  label: 'Title',
  dependencies: ["jobTitle"],
  renderCell: (employee) => employee.jobTitle,
}, {
  label: 'Company',
  dependencies: ["company"],
  renderCell: (employee) => employee.company.name,
}]);

This is enough for our implementation to work, however, if we want to make each renderCell function get an argument with the correct type, we can use the createColumn function to wrap each column, and make it type-safe.

Let's start by declaring the createColumn function

import type { Column } from '@table-library/react-table-library/types/compact';

type ColumnDefinitions<TPayload> = Omit<Column, "renderCell" | "dependencies"> & {
  renderCell: (item: TPayload) => React.ReactNode,
  dependencies?: readonly (Extract<keyof TPayload, string>)[],
};

export const createTableLoader = <TPayload extends Record<string, any>>() => {
  // ...
  return {
    createColumn: <TDependencies extends keyof TPayload=never>(column: Omit<ColumnDefinitions<TPayload>, "dependencies" | "renderCell"> & {
      dependencies?: TDependencies[],
      renderCell: (data: Pick<TPayload, TDependencies>) =>  React.ReactNode,
    }) => {
      return column;
    },
  // ...
  }
}

Whoa, that looks like some complex typescript! What we're essentially doing here though, is restricting the data type, using the Pick utility.

So if you specify only the firstName field in a column, you won't be able to access other fields in the renderCellfunction. E.g. writing employee.email would result in a typescript error.

Now simply wrap all your columns in this helper function. The best part about this is, you can get easy type-safety AND composability, by declaring the columns in different places, then simply adding them to the array you need.

export const nameColumn = employeeLoader.createColumn({
  label: 'Name',
  dependencies: ["firstName", "lastName"],
  renderCell: (employee) => {
    return <div>{employee.firstName} {employee.lastName}</div>
  },
});

export const companyColumn = employeeLoader.createColumn({
  label: 'Company',
  dependencies: ["company"],
  renderCell: (employee) => employee.company.name,
});
// ...

const columns = employeeLoader.useColumns([
  nameColumn,
  employeeColumn,
]);

The useColumns implementation

Now we need to actually implement the useColumns function, and the rest of the table data loader.

We start by saving the dependencies array in a reducer.

import React from 'react';

type Action = {
  type: "APPEND_FIELDS",
  dependencies: string[]
};

type State = {
  dependencies: string[]
}

const stateReducer = (state: State, action: Action) => {
  switch (action.type) {
    case 'APPEND_FIELDS':
      return {
        ...state,
        // Sort alphabetically to have a stable array
        dependencies: [... new Set(state.dependencies.concat(action.dependencies))].sort(),
      };
    default: return state;
  }
}

This is a simple array of unique strings, that are sorted alphabetically (to prevent tRPC refetching queries if the dependent fields are attached out of order).

We're gonna pass this dependencies array down using the context provider.

export const createTableLoader = <TPayload extends Record<string, any>>() => {
  const initialState = {
    dependencies: [],
  };
  const DependenciesContext = React.createContext([] as (keyof TPayload)[]);
  const DispatchContext = React.createContext((() => {
    throw new Error("tableDataLoader Context provider not found!");
  }) as React.Dispatch<Action>);

  return {
    ContextProvider: ({ children }: { children: React.ReactNode }) => {
      const [state, dispatch] = React.useReducer(stateReducer, initialState);
      return (<DispatchContext.Provider value={dispatch}>
        <DependenciesContext.Provider value={state.dependencies}>
          {children}
        </DependenciesContext.Provider>
      </DispatchContext.Provider>)
    },
    // ...
}

The context provider makes it possible to access the state in sub-components.
You simply need to provide it at the root of your page, before you use any loader hooks.

<employeeLoader.ContextProvider>
  <EmployeesTable />
</employeeLoader.ContextProvider>

Finally, we implement the useColumns and useVariables functions

import  type { Column } from  '@table-library/react-table-library/types/compact';

const diff = (arr1: any[], arr2: any[]) => {
  return arr1.filter(x => !arr2.includes(x));
}

type ColumnDefinitions<TPayload> = Omit<Column, "renderCell"> & {
  renderCell: (item: TPayload) => React.ReactNode,
  dependencies?: readonly (Extract<keyof TPayload, string>)[],
};

export const  createTableLoader = <TPayload  extends  Record<string, any>>() => {
  // ... context state
  return {
    ContextProvider: //...
    useColumns: (columns: ColumnDefinitions<TPayload>[]) => {
      const dispatch = React.useContext(DispatchContext);
      const existingDeps = React.useContext(DependenciesContext);
      React.useEffect(() => {
        const select = columns.flatMap(column => {
          return (column.dependencies || [])
        }).filter(Boolean);
        if (diff(dependencies, existingDeps).length) {
          // We only add fields to dependencies array, without removing.
          dispatch({
            type: 'APPEND_FIELDS',
            dependencies: dependencies,
          });
        }
      }, [existingDeps, columns]);
      return columns;
    },
    useVariables: () => {
      const dependencies = React.useContext(DependenciesContext);
      return React.useMemo(() => ({
        select: dependencies,
      }), [dependencies]);
    },
  }
}

You can use the useVariables hook to get the select array while fetching the data with trpc, and pass it as an argument.

const employeeLoader = createTableLoader<Employee>();

// ...

const { select } = employeeLoader.useVariables();
const { data, isLoading } = trpc.employees.getEmployees.useQuery({
  select,
});
// ...
return <Table data={data.nodes} />

So the API can return just the fields that we actually need to display our columns.

The data loader can be extended to also handle pagination, and other API specifics. Stay tuned for the next articles in this series, about pagination and actually implementing such an API in a tRPC server!

The complete tableDataLoader implementation

Finally, here's the complete implementation of the table data loader function (so far in the series:

import type { Column } from '@table-library/react-table-library/types/compact';
import React from 'react';

const diff = (arr1: any[], arr2: any[]) => {
  return arr1.filter(x => !arr2.includes(x));
}

type Action = {
  type: "APPEND_FIELDS",
  dependencies: string[]
};

type ColumnDefinitions<TPayload> = Omit<Column, "renderCell" | "dependencies"> & {
  renderCell: (item: TPayload) => React.ReactNode,
  dependencies?: readonly (Extract<keyof TPayload, string>)[],
};

type State = {
  dependencies: string[]
}

const stateReducer = (state: State, action: Action) => {
  switch (action.type) {
    case 'APPEND_FIELDS':
      return {
        ...state,
        // Sort alphabetically to have a stable array
        dependencies: [... new Set(state.dependencies.concat(action.dependencies))].sort(),
      };
    default: return state;
  }
}

export const  createTableLoader = <TPayload  extends  Record<string, any>>() => {
  const initialState = {
    dependencies: [],
  };
  const DependenciesContext = React.createContext([] as (keyof TPayload)[]);
  const DispatchContext = React.createContext((() => {
    throw new Error("tableDataLoader Context provider not found!");
  }) as React.Dispatch<Action>);

  return {
    ContextProvider: ({ children }: { children: React.ReactNode }) => {
      const [state, dispatch] = React.useReducer(stateReducer, initialState);
      return (<DispatchContext.Provider value={dispatch}>
        <DependenciesContext.Provider value={state.dependencies}>
          {children}
        </DependenciesContext.Provider>
      </DispatchContext.Provider>)
    },
    useColumns: (columns: ColumnDefinitions<TPayload>[]) => {
      const dispatch = React.useContext(DispatchContext);
      const existingDeps = React.useContext(DependenciesContext);
      React.useEffect(() => {
        const dependencies = columns.flatMap(column => {
          return (column.dependencies || [])
        }).filter(Boolean);
        if (diff(dependencies, existingDeps).length) {
          // We only add fields to dependencies array, without removing.
          dispatch({
            type: 'APPEND_FIELDS',
            dependencies: dependencies,
          });
        }
      }, [existingDeps, columns]);
      return columns;
    },
    useVariables: () => {
      const dependencies = React.useContext(DependenciesContext);
      return React.useMemo(() => ({
        select: dependencies,
      }), [dependencies]);
    },
    createColumn: <TDependencies extends keyof  TPayload=never>(column: Omit<ColumnDefinitions<TPayload>, "dependencies" | "renderCell"> & {
      dependencies?: TDependencies[],
      renderCell: (data: Pick<TPayload, TDependencies>) =>  React.ReactNode,
    }) => {
      return column;
    },
  }
}

And the table component

import React from 'react';
import { CompactTable } from '@table-library/react-table-library/compact';

import { trpc, type Employee } from '../../utils/trpc';

const employeeTableLoader = createTableLoader<Employee>();

export default function EmployeeList() {
  const employeeColumns = employeeTableLoader.useColumns([
    employeeTableLoader.createColumn({
        label: 'Name',
        dependencies: ["firstName", "lastName"],
        renderCell: (employee) => {
            return <div>{employee.firstName} {employee.lastName}</div>
        },
    }), employeeTableLoader.createColumn({
        label: 'Salary',
        dependencies: ["salary"],
        renderCell: (employee) => employee.salary,
    }), employeeTableLoader.createColumn({
        label: 'Start Date',
        dependencies: ["startDate"],
        renderCell: (employee) => employee.startDate,
    }), employeeTableLoader.createColumn({
        label: 'Company',
        dependencies: ["company"],
        renderCell: (employee) => employee.company,
    })]);

  const pagination = employeeTableLoader.useVariables();

    const { data, isLoading } = trpc.employees.getPaginated.useQuery(
        {
            take: 100,
            ...pagination,
        }
    );


  if (!data) return null;
  const { nodes, pageInfo } = data;

  return (
    <>
      <CompactTable columns={employeeColumns} data={{
        nodes: nodes || [],
        pageInfo: pageInfo,
      }} />
    </>
  );
}