📖 prisma-paginate

| | | | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

🚀 Installation

# Using npm
npm install prisma @prisma/client prisma-paginate

# Using yarn
yarn add prisma @prisma/client prisma-paginate

# Using pnpm
pnpm add prisma @prisma/client prisma-paginate

📋 Version compatibility

| Prisma | prisma-paginate | | -------- | --------------- | | 7.0.0>= | 6.0.0 | | 4.16.0<= | 5.2.2 |

📚 Documentation

For comprehensive API documentation and type definitions, visit:

http://sandrewtx08.github.io/prisma-paginate/

📦 Importing

ESM (ES Modules)

// Standard Prisma client
import { PrismaClient } from "@prisma/client";
import PrismaPaginate from "prisma-paginate";

// Custom Prisma client paths also work
import { PrismaClient } from "./generated/client";
import PrismaPaginate from "prisma-paginate";

CommonJS

const { PrismaClient } = require("@prisma/client");
const PrismaPaginate = require("prisma-paginate").default;

Note: The extension works seamlessly with any Prisma client instance, regardless of the import path. No additional configuration needed!

🔧 Usage

Basic Setup

const prisma = new PrismaClient();
const xprisma = prisma.$extends(PrismaPaginate);

// Simple cursor pagination
xprisma.user
	.cursorPaginate({
		limit: 10,
		orderBy: { id: "asc" },
		cursorFields: ["id"] as const,
		select: { id: true, name: true },
	})
	.then((result) => {
		console.log(result.result);
		console.log(result.hasNextPage);
		console.log(result.nextCursor);
	});

// Pagination with filters and cursor
xprisma.post
	.cursorPaginate(
		{
			where: { published: true },
			orderBy: [{ createdAt: "desc" }, { id: "desc" }],
			cursorFields: ["createdAt", "id"] as const,
		},
		{ limit: 10, cursor: lastCursor },
	)
	.then((result) => {
		console.log(result.result);
	});

Complete Example

// Assume database has 100 rows: [ { id: 1 }, { id: 2 }, ..., { id: 100 } ]
const first = await xprisma.user.cursorPaginate({
	where: {
		active: true,
	},
	orderBy: [{ createdAt: "desc" }, { id: "desc" }],
	limit: 50,
	cursorFields: ["createdAt", "id"] as const,
});

console.log(first.result); // Array of 50 users
console.log(first.hasNextPage); // true if there's a next page
console.log(first.nextCursor); // cursor for the next page

if (first.hasNextPage) {
	const second = await xprisma.user.cursorPaginate(
		{
			where: {
				active: true,
			},
			orderBy: [{ createdAt: "desc" }, { id: "desc" }],
			cursorFields: ["createdAt", "id"] as const,
		},
		{ limit: 50, cursor: first.nextCursor },
	);

	console.log(second.result);
}

📋 API Reference

Method Signatures

// Option 1: Combined findMany args and pagination
cursorPaginate(findManyPaginationArgs: PrismaFindManyArgs & PaginationArgs)

// Option 2: Separate findMany args and pagination
cursorPaginate(findManyArgs: PrismaFindManyArgs, paginationArgs: PaginationArgs)

Parameters

findManyArgs (Object)

Standard Prisma findMany arguments including:

• where - Filter conditions
• select - Fields to select
• include - Relations to include
• orderBy - Sorting options
• And all other Prisma query options

paginationArgs (Object)

Pagination configuration:

• limit (Number) - Number of items per page
• cursor (Object) - Cursor values from the previous page
• cursorFields (Array) - Ordered unique cursor field names (must match orderBy)

Note: When using cursor pagination, orderBy is required. The cursorFields list is required, must be unique fields, and must match the orderBy fields and order.

Return Value

The cursorPaginate() method returns a Promise<PaginationResult> with the following properties:

| Property | Type | Description | | ------------- | -------- | ----------------------------------------- | | result | Array | Array of paginated records | | limit | Number | Page size | | hasNextPage | Boolean | Whether a next page exists | | nextCursor | Object | Cursor values for the next page | | nextPage | Function | Returns Promise to fetch the next page |

✨ Features

• 🚀 Easy Integration - Simple Prisma extension setup
• 📦 TypeScript Support - Full type safety with IntelliSense
• 🔄 Flexible API - Multiple ways to call pagination
• 📊 Cursor Metadata - hasNextPage and typed nextCursor
• 🎯 Prisma Native - Works with all Prisma query options
• ⚡ Zero Config - Works out of the box with any Prisma setup

🤝 Contributing

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

🔗 Links

• Documentation
• GitHub Repository
• npm Package
• Report Issues