npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sequelize-cursor-pagination

v3.4.0

Published

Cursor-based pagination queries for Sequelize models

Downloads

14,065

Readme

➡️ sequelize-cursor-pagination

Test npm

Cursor-based pagination queries for Sequelize models. Some motivation and background.

Install

With npm:

npm install sequelize-cursor-pagination

With Yarn:

yarn add sequelize-cursor-pagination

How to use?

Define a static pagination method for a Sequelize model with the makePaginate function:

const { makePaginate } = require('sequelize-cursor-pagination');

const Counter = sequelize.define('counter', {
  id: { type: Sequelize.INTEGER, primaryKey: true, autoIncrement: true },
  value: Sequelize.INTEGER,
});

Counter.paginate = makePaginate(Counter);

The first argument of the makePaginate function is the model class. The function also has a second, optional argument, which is the options object. The options object has the following properties:

  • primaryKeyField: The primary key field of the model. With a composite primary key, provide an array containing the keys, for example ['key1', 'key2']. If not provided, the primary key is resolved from the model's attributes (attributes with primaryKey: true). This is the desired behavior in most cases.
  • omitPrimaryKeyFromOrder: By default, the primary key is automatically included in the order if it is missing. Setting this option to true will override this behavior. The default value is false.

Call the paginate method:

const result = await Counter.paginate({
  where: { value: { [Op.gt]: 2 } },
  limit: 10,
});

The paginate method returns a promise, which resolves an object with the following properties:

  • edges: An array containing the results of the query. Each item in the array contains an object with the following properties:
    • node: The model instance
    • cursor: Cursor for the model instance
  • totalCount: The total numbers rows matching the query
  • pageInfo: An object containing the pagination related data with the following properties:
    • startCursor: The cursor for the first node in the result edges
    • endCursor: The cursor for the last node in the result edges
    • hasNextPage: A boolean that indicates whether there are edges after the endCursor (false indicates that there are no more edges after the endCursor)
    • hasPreviousPage: A boolean that indicates whether there are edges before the startCursor (false indicates that there are no more edges before the startCursor)

The paginate method has the following options:

  • after: The cursor that indicates after which edge the next set of edges should be fetched
  • before: The cursor that indicates before which edge next set of edges should be fetched
  • limit: The maximum number of edges returned

Other options passed to the paginate method will be directly passed to the model's findAll method.

⚠️ NB: The order option format only supports the ['field'] and ['field', 'DESC'] variations (field name and the optional order direction). For example, ordering by an associated model's field won't work.

Examples

The examples use the Counter model defined above.

Fetch the first 20 edges ordered by the id field (the primaryKeyField field) in ascending order:

const result = await Counter.paginate({
  limit: 20,
});

First, fetch the first 10 edges ordered by the value field in a descending order. Second, fetch the first 10 edges after the endCursor. Third, fetch the last 10 edges before startCursor:

const firstResult = await Counter.paginate({
  order: [['value', 'DESC']],
  limit: 10,
});

const secondResult = await Counter.paginate({
  order: [['value', 'DESC']],
  limit: 10,
  after: firstResult.pageInfo.endCursor,
});

const thirdResult = await Counter.paginate({
  order: [['value', 'DESC']],
  limit: 10,
  before: secondResult.pageInfo.startCursor,
});

TypeScript

The library is written in TypeScript, so types are on the house!

If you are using a static method like in the previous examples, just declare the method on your model class:

import {
  PaginateOptions,
  PaginationConnection,
  makePaginate,
} from 'sequelize-cursor-pagination';

export class Counter extends Model<
  InferAttributes<Counter>,
  InferCreationAttributes<Counter>
> {
  declare id: CreationOptional<number>;
  declare value: number;

  declare static paginate: (
    options: PaginateOptions<Counter>,
  ) => Promise<PaginationConnection<Counter>>;
}

// ...

Counter.paginate = makePaginate(Counter);

Migrating from version 2

The withPagination function is deprecated starting from version 3, but the migration is fairly simple.

Version 2:

const withPagination = require('sequelize-cursor-pagination');

const Counter = sequelize.define('counter', {
  id: { type: Sequelize.INTEGER, primaryKey: true, autoIncrement: true },
  value: Sequelize.INTEGER,
});

withPagination({ primaryKeyField: 'id' })(Counter);

Version 3 onwards:

const { makePaginate } = require('sequelize-cursor-pagination');

const Counter = sequelize.define('counter', {
  id: { type: Sequelize.INTEGER, primaryKey: true, autoIncrement: true },
  value: Sequelize.INTEGER,
});

Counter.paginate = makePaginate(Counter);