# knex-paginate

> Extension of Knex's query builder with `paginate` method that will help with your pagination tasks.

Latest version **3.2.0** (published 2024-12-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install knex-paginate
pnpm add knex-paginate
yarn add knex-paginate
bun add knex-paginate
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2024-12-23 |
| First published | 2019-08-22 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 114 |
| Author | Felixmosh |
| Maintainers | felixmosh |
| Keywords | knex, pagination, paginate |

## Links

- npm: https://www.npmjs.com/package/knex-paginate
- Repository: https://github.com/felixmosh/knex-paginate
- Homepage: https://github.com/felixmosh/knex-paginate#readme
- Issues: https://github.com/felixmosh/knex-paginate/issues
- npm.io page: https://npm.io/package/knex-paginate

## Recent versions

- 3.2.0 (latest) — 2024-12-23
- 3.1.4 — 2024-06-04
- 3.1.3 — 2024-06-04
- 3.1.2 — 2024-04-14
- 3.1.1 — 2023-04-26
- 3.1.0 — 2023-03-19
- 3.0.2 — 2022-10-31
- 3.0.1 — 2022-04-28
- 3.0.0 — 2021-09-23
- 2.3.0 — 2021-08-29
- 2.2.1 — 2021-08-17
- 2.2.0 — 2021-06-13
- 2.1.0 — 2021-03-07
- 2.0.0 — 2021-03-07
- 1.2.4 — 2021-03-05
- … 7 more at https://npm.io/package/knex-paginate/versions

## README

# Knex-paginate

[![npm](https://img.shields.io/npm/v/knex-paginate.svg)](https://www.npmjs.com/package/knex-paginate)
[![CI](https://github.com/felixmosh/knex-paginate/actions/workflows/ci.yml/badge.svg)](https://github.com/felixmosh/knex-paginate/actions/workflows/ci.yml)

Extension of Knex's query builder with `paginate` method that will help with your pagination tasks.

## How to set up

To use this lib, first you will have to install it:

```
npm i knex-paginate --save
// or
yarn add knex-paginate
```

Then, add the following lines to your Knex set up:

```javascript
const knex = require('knex')(config);

const { attachPaginate } = require('knex-paginate');
attachPaginate();
```

## Function definition

```typescript
.paginate(params: IPaginateParams): Knex.QueryBuilder<any, IWithPagination<TResult>>;

interface IPaginateParams {
  perPage: number,
  currentPage: number,
  isFromStart?: boolean,
  isLengthAware?: boolean,
  disabled?: boolean,
}

interface IWithPagination<T = any> {
  data: T;
  pagination: IPagination;
}

interface IPagination {
  total?: number;
  lastPage?: number;
  prevPage?: number | null;
  nextPage?: number | null;
  currentPage: number;
  perPage: number;
  from: number;
  to: number;
}
```

## How to use

### Example
```javascript
const result = await knex('persons')
   .paginate({ perPage: 10, currentPage: 2 });
// result.data - will hold persons data
// result.pagination - will hold pagination object
```
## paginate options

| Key                         | type    | Value                                                                |
|-----------------------------|---------|----------------------------------------------------------------------|
| perPage                     | number  | Items per page.                                                      |
| currentPage                 | number  | The current page                                                     |
| isFromStart / isLengthAware | boolean | Indicates if the returned list should get all pages till currentPage |
| disabled                    | boolean | Disables the pagination functionality, returns all relevant rows     |

## `pagination` object

| Key         | Value                                              |
|-------------|----------------------------------------------------|
| perPage     | Items per page.                                    |
| currentPage | Current page number.                               |
| from        | Counting ID of the first item of the current page. |
| to          | Counting ID of the last item of the current page.  |

If `isLengthAware == true` or `currentPage == 1` or `isFromStart == true` pagination object will contain additional fields:

| Key      | Value                                               |
|----------|-----------------------------------------------------|
| total    | Total items that the full query contains.           |
| lastPage | Last page number.                                   |
| nextPage | The next page or `null` when at the last page.      |
| prevPage | The previous page or `null` when at the first page. |


This lib got inspiration from [`knex-paginator`](https://github.com/cannblw/knex-paginator).

---
_Source: https://npm.io/package/knex-paginate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._