@dakohhh/mongoose-paginator

A lightweight, flexible, and TypeScript-friendly pagination utility for Mongoose models. This package provides a class-based approach to handling database pagination with support for filtering, sorting, population, projection, and metadata customization — all without relying on heavy plugins.

Features

• 🚀 Lightweight & Performant: Minimal overhead with optimized query execution
• 🔧 Fully Configurable: Customize filters, sorting, projections, and more
• 📊 Rich Metadata: Comprehensive pagination metadata including total count, page info, and navigation
• 🧩 Fluent API: Chainable methods for a clean and intuitive interface
• 📝 TypeScript Support: Full type safety with generic typing
• 🔄 Document/JSON Flexibility: Support for both Mongoose documents and lean objects
• 🔍 Advanced Querying: Compatible with all Mongoose query operators
• 🧪 Zero Dependencies: No external dependencies beyond Mongoose

Installation

npm install @dakohhh/mongoose-paginator

Or with yarn:

yarn add @dakohhh/mongoose-paginator

Usage

⚠️ Deprecation Notice:

The Paginator class has been deprecated and will be removed in a future release. Please use the PageNumberPaginator class instead. PageNumberPaginator is functionally identical to Paginator and is now the recommended way to perform page-number-based pagination.

import { PageNumberPaginator } from '@dakohhh/mongoose-paginator';
// Usage is identical to the old Paginator class.

Basic Example

import { Paginator } from '@dakohhh/mongoose-paginator';
import { model, Schema, Document } from 'mongoose';

// Define your Mongoose model
interface IUser extends Document {
  name: string;
  email: string;
  age: number;
  createdAt: Date;
}

const UserModel = model<IUser>('User', userSchema);

// Create a paginator instance
const paginator = new Paginator<IUser>(UserModel);

// Execute pagination
const result = await paginator.paginate();

console.log(result);
// Output: { data: [...], meta: { total, lastPage, currentPage, perPage, prev, next } }

// You can also destructure the results for cleaner code
const { data: users, meta: paginationInfo } = await paginator.paginate();
console.log(users); // Array of user documents
console.log(paginationInfo); // Pagination metadata

Advanced Usage

Page Number Pagination (Recommended)

import { PageNumberPaginator } from '@dakohhh/mongoose-paginator';

const page = 1
const limit = 10
const paginator = new PageNumberPaginator<IUser>(UserModel, page, limit, {
  filter: { age: { $gte: 18 } },
  sort: { createdAt: -1 },
  projection: ['name', 'email', '-_id'],
  populate: [{ path: 'posts', select: 'title' }],
  lean: true
});

const result = await paginator.paginate();
console.log(result);
// {
//   data: [...],
//   meta: { total, lastPage, currentPage, perPage, prev, next }
// }

Offset Pagination

Offset-based pagination is useful for traditional skip-limit pagination scenarios.

import { OffsetPaginator } from '@dakohhh/mongoose-paginator';

const offset = 0; // Start offset
const limit = 10; // Items per page
const paginator = new OffsetPaginator<IUser>(UserModel, offset, limit, {
  filter: { age: { $gte: 18 } },
  sort: { createdAt: -1 },
  projection: ['name', 'email', '-_id'],
  populate: [{ path: 'posts', select: 'title' }],
  lean: true
});

const result = await paginator.paginate();
console.log(result);
// {
//   data: [...],
//   meta: { total, lastPage, currentPage, perPage, prev, next }
// }

Cursor Pagination

Cursor-based pagination is ideal for real-time feeds or infinite scrolling. Use the nextCursor from the previous result to fetch the next page.

import { CursorPaginator } from '@dakohhh/mongoose-paginator';

let cursor: string | null = null; // BSON ObjectId
const limit = 10;
const paginator = new CursorPaginator<IUser>(UserModel, cursor, limit, {
  filter: { age: { $gte: 18 } },
  projection: ['name', 'email', '-_id'],
  populate: [{ path: 'posts', select: 'title' }],
  lean: true
});

const result = await paginator.paginate();
console.log(result);
// {
//   data: [...],
//   meta: { nextCursor }
// }

// To fetch the next page:
cursor = result.meta.nextCursor;
const nextPage = await new CursorPaginator<IUser>(UserModel, cursor, limit).paginate();

---

Result Customization

One of the key advantages of this paginator is the ability to easily customize how you access your results through destructuring:

// Standard result object
const result = await paginator.paginate();

// Customize variable names through destructuring
const { data: users, meta: paginationInfo } = await paginator.paginate();

// Access your data with your preferred variable names
console.log(users); // Your paginated documents with your custom name
console.log(paginationInfo.currentPage); // Access pagination metadata with your custom name

// Use in a response object
return {
  success: true,
  users, // Your renamed data array
  pagination: paginationInfo // Your renamed metadata
};

API Reference

Paginator<T>

The main class for pagination operations.

Constructor

constructor(
  model: Model<T>,
  page: number = 1,
  limit: number = 10,
  args: IPaginateArgs<T> = { filter: {}, sort: { createdAt: -1 }, lean: true }
)

Methods

• paginate(): Executes the pagination query and returns results with metadata
• setPage(page: number): Sets the current page number
• setLimit(limit: number): Sets the number of items per page
• setArgs(args: IPaginateArgs<T>): Sets the query arguments

Interfaces

IPaginateArgs<T>

interface IPaginateArgs<T> {
  filter?: FilterQuery<T>;
  sort?: Record<string, SortOrder>;
  projection?: string | string[] | Record<string, number | boolean | string | object>;
  populate?: PopulateOptions | PopulateOptions[];
  lean?: boolean;
}

IPaginationResult<T>

interface IPaginationResult<T> {
  data: T[];
  meta: IPaginationMeta;
}

IPaginationMeta

interface IPaginationMeta {
  total: number;
  lastPage: number;
  currentPage: number;
  perPage: number;
  prev: number | null;
  next: number | null;
}

Advantages Over Other Solutions

• Class-Based Design: Unlike function-based pagination utilities, our class-based approach allows for a more intuitive and chainable API.

• TypeScript First: Built with TypeScript from the ground up, providing complete type safety without compromising on features.

• Lightweight: No external dependencies beyond Mongoose itself, making it a lightweight addition to your project.

• Flexible Query Options: Full support for all Mongoose query capabilities including complex filtering, sorting, and population.

• Performance Optimized: Uses Promise.all to run document fetching and count queries in parallel for better performance.

• Lean Option: Built-in support for lean queries, significantly improving performance when working with large datasets.

• Comprehensive Metadata: Provides rich pagination metadata including total count, current page, last page, and navigation helpers.

• Fluent API: Chainable methods make the API intuitive and easy to use, improving code readability.

Use Cases

• RESTful APIs: Implement standardized pagination for your API endpoints
• Admin Dashboards: Paginate large datasets in admin interfaces
• Data Tables: Power data tables with server-side pagination
• Search Results: Paginate search results efficiently
• Feed Systems: Implement "load more" or paginated content feeds

🔄 Comparison: @dakohhh/mongoose-paginator vs mongoose-paginate-v2

Feature	@dakohhh/mongoose-paginator	mongoose-paginate-v2
🏗️ Architecture	Class-based with fluent, chainable methods	Plugin-based (requires schema.plugin)
✅ TypeScript Support	✅ First-class TypeScript support with full generic typing	⚠️ Partial — requires community types
🧩 Integration	No schema modification needed — use directly with any Mongoose model	Requires modification via schema.plugin
🚀 Performance	Parallel execution of data & count queries using Promise.all()	Serial execution (slightly slower on large queries)
🧠 Query Options	Advanced support: filtering, sorting, projection, population, lean queries	Basic support for filter, select, populate, lean
📊 Pagination Metadata	Rich meta: total, perPage, currentPage, prev, next, lastPage	Provides basic pagination metadata
🔄 Chainable API	✅ Fluent API: .setPage().setLimit().setArgs()	❌ Not supported
🧼 Clean API	Supports destructuring (const { data, meta } = ...)	Partially supported
🧪 Testability	Easily testable: no schema mutation, class-based structure	Harder to mock due to schema plugin requirement
⚙️ Projection Support	✅ Yes	✅ Yes
🔌 Populate Support	✅ Yes	✅ Yes
💬 Lean Document Support	✅ Yes	✅ Yes
📦 Dependencies	Zero dependencies beyond Mongoose	Depends on Mongoose and plugin structure
🧠 Learning Curve	Slightly higher (class-based, customizable)	Very beginner-friendly
📚 Community	New and growing	Large and established
🔐 Schema Safety	Does not modify original schema	Alters schema with plugin

---

License

ISC

Author

Wisdom Dakoh

Contributing

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