@dakohhh/mongoose-paginator
Version:
Mongoose-Class-Paginator is a lightweight, flexible, and TypeScript-friendly pagination utility for Mongoose models. It provides a class-based approach to handling database pagination with support for filtering, sorting, population, projection, and metada
297 lines (220 loc) • 11.5 kB
Markdown
# @dakohhh/mongoose-paginator
[](https://www.npmjs.com/package/@dakohhh/mongoose-paginator)
[](https://opensource.org/licenses/ISC)
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
```bash
npm install @dakohhh/mongoose-paginator
```
Or with yarn:
```bash
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.
>
> ```typescript
> import { PageNumberPaginator } from '@dakohhh/mongoose-paginator';
> // Usage is identical to the old Paginator class.
> ```
### Basic Example
```typescript
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)
```typescript
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.
```typescript
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.
```typescript
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:
```typescript
// 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
```typescript
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>`
```typescript
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>`
```typescript
interface IPaginationResult<T> {
data: T[];
meta: IPaginationMeta;
}
```
#### `IPaginationMeta`
```typescript
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.