@origins-digital/prisma-pagination

A cursor-based pagination utility for Prisma ORM.

Installation

npm install @origins-digital/prisma-pagination

Features

• Cursor-based pagination for Prisma models
• Support for forward and backward pagination
• Type-safe pagination options
• Automatic cursor encoding/decoding
• Optional total count calculation
• Customizable sorting

Usage

Basic Setup

import {
  paginateWithCursor,
  PaginationOptions,
  PaginationOrder,
} from '@origins-digital/prisma-pagination';

// Define your Prisma model type
type User = {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
};

// Create pagination options
const options: PaginationOptions<keyof User> = {
  limit: 10,
  sort: {
    field: 'createdAt',
    order: 'desc',
  },
  loadTotalCount: true,
};

// Use pagination with your Prisma model
const result = await paginateWithCursor(prisma.user)(
  {}, // where clause
  options,
  { select: { id: true, name: true } }, // additional Prisma query options
);

Forward Pagination

const options: PaginationOptions<keyof User> = {
  limit: 10,
  after: 'eyJpZCI6IjEyMzQ1Njc4OTAifQ==', // Base64 encoded cursor
  sort: {
    field: 'createdAt',
    order: 'desc',
  },
};

const result = await paginateWithCursor(prisma.user)({}, options);

Backward Pagination

const options: PaginationOptions<keyof User> = {
  limit: 10,
  before: 'eyJpZCI6IjEyMzQ1Njc4OTAifQ==', // Base64 encoded cursor
  sort: {
    field: 'createdAt',
    order: 'desc',
  },
};

const result = await paginateWithCursor(prisma.user)({}, options);

Nested Field Sorting

const options: PaginationOptions<keyof User> = {
  limit: 10,
  sort: {
    field: 'profile.name', // Sort by nested field
    order: 'asc',
  },
};

const result = await paginateWithCursor(prisma.user)({}, options);

API Reference

PaginationOptions

type PaginationOptions<T> = {
  limit: number; // Number of items per page
  before?: string; // Cursor for backward pagination
  after?: string; // Cursor for forward pagination
  sort: PaginationOrder<T>; // Sorting configuration
  loadTotalCount?: boolean; // Whether to calculate total count
};

PaginationOrder

class PaginationOrder<T> {
  field: T; // Field to sort by
  order: 'desc' | 'asc'; // Sort direction
}

Response Format

The pagination function returns an object with the following structure:

{
  items: T[];            // Array of paginated items
  hasNextPage: boolean;  // Whether there are more items after
  hasPreviousPage: boolean; // Whether there are more items before
  startCursor: string;   // Cursor for the first item
  endCursor: string;     // Cursor for the last item
  totalCount?: number;   // Total number of items (if loadTotalCount is true)
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.