Add support for pagination

[IjzerenHein]

Problem

When using the useCollection hook, it's not possible to paginate using startAfter or startBefore because these query functions require "Document snapshots" (which are not accessible when using useCollection).

Possible solution 1

A possible (quick) solution that come to mind is to: return the snapshot array as an output of useCollection:

const [data, loading, snapshots] = useCollection(...

You can then use the snapshots array to paginate to the next page:

const [data, loading, snapshots] = useCollection(
   ...,
    orderBy("createdAt", "desc"),
    limit(10),
    paginationState.startAfter
      ? startAfter(paginationState.startAfter)
      : undefined,
  );

const handlePaginateNext = () => {
    const lastSnapshot = snapshots?.[data.length - 1];
    setPaginationState((prev) => ({
      ...prev,
      startAfter: lastSnapshot,
    }));
  };

Possible solution 2

An alternative solution could be to: add a snapshot field to FsDocument.

export type FsDocument<T> = Readonly<{
    id: string;
    data: T;
    snapshot: DocumentSnapshot<T>
}>;

@0x80 what are your thoughts on this?

[0x80]

I think for pagination a separate hook would be best, because you only need to keep a reference to the first and last snapshot of every page, and those references can then be handled internally by the hook.

Additionally, the hook could do an extra "count" query in parallel to return the total number of documents in the collection. You still wouldn't have the ability to jump to a random page in the collection, but at least you know how many pages there would be.

Then the hook API could maybe return callback functions for triggering previous + next navigation.

It's an interesting problem to solve. I might give it a shot later this week. Here's some relevant info I got from AI:

To implement bidirectional pagination in Firestore (both forward and backward navigation), you can use a combination of query cursors. Let me explain the available mechanisms.

Forward Pagination with startAfter

As you mentioned, Firestore uses startAfter to load more documents from the position of the last one:

// Forward pagination example
const nextPage = query.startAfter(lastVisibleDocument).limit(10);

Bidirectional Pagination Options

For backward pagination, Firestore provides several methods:

1. Using endBefore

The endBefore cursor can be used to paginate backward:

// Backward pagination example
const previousPage = query.endBefore(firstVisibleDocument).limitToLast(10);

2. Maintaining Page References

A common approach is to maintain an array of document references for each page viewed:

// Store references to first documents of each page
const pageRefs = [];

// When moving to next page
pageRefs.push(firstVisibleDocumentOfCurrentPage);
const nextPage = query.startAfter(lastVisibleDocument).limit(10);

// When moving back
const prevPageRef = pageRefs.pop();
const previousPage = query.startAt(prevPageRef).limit(10);

3. Using startAt and endAt

You can also use startAt and endAt for more precise cursor positioning:

// Forward
const nextPage = query.startAt(lastVisibleDocument).limit(10);

// Backward
const previousPage = query.endAt(firstVisibleDocument).limitToLast(10);

Best Practice for Bidirectional Pagination

The most robust approach for bidirectional pagination in Firestore is to:

1. Maintain the first and last document of the current page
2. Use startAfter(lastDoc) for "next page"
3. Use endBefore(firstDoc).limitToLast(pageSize) for "previous page"
4. Optionally store page references in an array or cache for direct page access

This approach allows you to navigate both forward and backward through your Firestore collection efficiently.

[IjzerenHein]

Yeah that's an interesting approach. I kinda like it, but I also feel it will be sort of opinionated in terms of how pagination is performed. Ideally I would still like to see a "primitive" hook that would enable building such a pagination hook, or even custom pagination hooks at the application level (if needed). But, a pagination hook that internally stores the snapshots would definitely solve my current use case.

[0x80]

Looking at the Firestore API it seems to me that there's not much you could implement apart from a "next" and "previous" action.

If you would like to play around with direct access to the snapshots, I think you could try using the CSFrequency useCollection hook directly, possibly in combination with the makeFsDocument function that is exported from typed-firestore.

[IjzerenHein]

You're probably right, supporting next, previous, first and last would likely solve 99% of all pagination scenarios. I experimented with building such a hook a couple days ago, this is what it looked like (and it worked very well):

export function usePaginatedCollection<T extends UnknownObject>(
    collectionRef: CollectionReference<T>,
    ...queryConstraints: (QueryConstraint | undefined)[]
  ) {

    const [paginationState, setPaginationState] = useState<{
        pageIndex: number;
        pageSize: number;
        startAfter?: DocumentSnapshot<T>;
        endBefore?: DocumentSnapshot<T>;
      }>({
        pageIndex: 0,
        pageSize: 5,
        startAfter: undefined,
        endBefore: undefined,
      });
    
      const [data, loading, snapshots] = useCollectionWithSnapshots(
        collectionRef,
        ...queryConstraints,
        limit(paginationState.pageSize),
        paginationState.startAfter
          ? startAfter(paginationState.startAfter)
          : paginationState.endBefore
            ? endBefore(paginationState.endBefore)
            : undefined,
      );
    
      const onPageSizeChange = (pageSize: number) => {
        setPaginationState((prev) => ({
          ...prev,
          pageSize,
        }));
      };
    
      const onFirst = () => {
        setPaginationState((prev) => ({
          ...prev,
          pageIndex: 0,
          startAfter: undefined,
          endBefore: undefined,
        }));
      };
    
      const onNext = () => {
        const lastSnapshot = snapshots?.[data.length - 1];
        if (!lastSnapshot) return;
        setPaginationState((prev) => ({
          ...prev,
          pageIndex: prev.pageIndex + 1,
          startAfter: lastSnapshot,
          endBefore: undefined,
        }));
      };
    
      const onPrevious = () => {
        const firstSnapshot = snapshots?.[data.length - 1];
        setPaginationState((prev) => ({
          ...prev,
          pageIndex: prev.pageIndex - (firstSnapshot ? 1 : 0),
          startAfter: undefined,
          endBefore: firstSnapshot,
        }));
      };

      return {
        data,
        loading,
        pageIndex: paginationState.pageIndex,
        pageSize: paginationState.pageSize,
        onPageSizeChange,
        onFirst,
        onNext,
        onPrevious,
      };
}

However, I ended up not using it and chose to just fetch all the data and do in-memory pagination . So, this is not really important for me anymore atm.

[0x80]

👍 Thanks for sharing the code, and good to know that it's not blocking you.

I don't think "last" is even possible from what I understood. Ah I see limitToLast is for that