# @ic/paginate-sequelize

A simple and efficient helper function for paginating Sequelize queries.

[![npm version](https://badge.fury.io/js/%40ic%2fsequelize-paginate.svg)](https://www.npmjs.com/package/@ic/sequelize-paginate)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @ic/sequelize-paginate

Usage

This helper function simplifies the process of paginating your Sequelize model queries. It returns an object containing pagination metadata and the items for the current page.

const { DataTypes, Sequelize } = require('sequelize');
const paginate = require('@ic/sequelize-paginate');

// Initialize your Sequelize instance
const sequelize = new Sequelize('sqlite::memory:');

// Define your Sequelize model (example: User model)
const User = sequelize.define('User', {
  name: DataTypes.STRING,
  email: DataTypes.STRING,
});

async function main() {
  await sequelize.sync();
  await User.bulkCreate([
    { name: 'Alice', email: '[email protected]' },
    { name: 'Bob', email: '[email protected]' },
    { name: 'Charlie', email: '[email protected]' },
    { name: 'David', email: '[email protected]' },
    { name: 'Eve', email: '[email protected]' },
    { name: 'Frank', email: '[email protected]' },
    { name: 'Grace', email: '[email protected]' },
    { name: 'Heidi', email: '[email protected]' },
    { name: 'Ivan', email: '[email protected]' },
    { name: 'Judy', email: '[email protected]' },
    { name: 'Kyle', email: '[email protected]' },
  ]);

  // Basic pagination (page 2, default page size of 10)
  let results = await paginate(User, { page: 2 });
  console.log('Page 2 (default pageSize):', results);
  /*
  {
    totalItems: 11,
    totalPages: 2,
    currentPage: 2,
    pageSize: 10,
    nextPage: null,
    prevPage: 1,
    items: [
      { id: 11, name: 'Kyle', email: '[email protected]', createdAt: ..., updatedAt: ... }
    ]
  }
  */

  // Pagination with custom page size and where clause
  results = await paginate(User, {
    page: 1,
    pageSize: 5,
    where: { name: { [Sequelize.Op.like]: 'A%' } },
    order: [['name', 'ASC']],
  });
  console.log('Page 1 (pageSize 5, where name like "A%"):', results);
  /*
  {
    totalItems: 1,
    totalPages: 1,
    currentPage: 1,
    pageSize: 5,
    nextPage: null,
    prevPage: null,
    items: [
      { id: 1, name: 'Alice', email: '[email protected]', createdAt: ..., updatedAt: ... }
    ]
  }
  */
}

main();

API

paginate(model, options)

Asynchronously paginates a Sequelize model query.

Parameters:

• model: The Sequelize model you want to query (e.g., User).
• options (Object): An object containing pagination and query options.
  • page (number, optional): The desired page number (default: 1).
  • pageSize (number, optional): The number of items to return per page (default: 10).
  • ...queryOptions: Any other valid options that can be passed to Sequelize's findAndCountAll() method (e.g., where, order, include, attributes).

Returns:

A Promise that resolves to an object with the following properties:

• totalItems (number): The total number of items matching the query.
• totalPages (number): The total number of pages based on the pageSize.
• currentPage (number): The current page number.
• pageSize (number): The number of items per page.
• nextPage (number | null): The next page number, or null if it's the last page.
• prevPage (number | null): The previous page number, or null if it's the first page.
• items (Array): An array of Sequelize model instances for the current page.

License

MIT

Author

[Your Name] ([Your Email/Website])

**Explanation of the README Content:**

* **`# @ic/sequelize-paginate`:** The main heading with your package name.
* **Badges:** Includes badges for npm version and license for quick information.
* **`## Installation`:** Instructions on how to install your package using npm.
* **`## Usage`:**
    * Explains the basic purpose of the function.
    * Provides a clear and runnable code example demonstrating how to use the `paginate` function with a Sequelize model.
    * Shows how to use both default pagination and custom options like `pageSize`, `where`, and `order`.
    * Includes the expected output for the examples to help users understand the returned data structure.
* **`## API`:**
    * Clearly documents the `paginate` function.
    * Explains the parameters it accepts (`model` and `options`) with details about the properties within the `options` object.
    * Describes the structure of the object returned by the function, including all the pagination metadata and the `items` array.
* **`## License`:** Specifies the license under which your package is distributed.
* **`## Author`:** Your name and contact information.

**How to Use This:**

1.  Create a file named `README.md` in the root directory of your `ic-sequelize-paginate` project.
2.  Copy and paste the content above into this file.
3.  **Replace `[Your Name]` and `([Your Email/Website])` with your actual information.**
4.  Customize the examples and API documentation further if your function has more advanced features or options.

This `README.md` file will be displayed on the npm package page, making it easy for other developers to understand and use your pagination helper function. Make sure to keep it updated as you make changes to your package.