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

@limit0/mongoose-graphql-pagination

v1.1.4

Published

Provides GraphQL cursor pagination for Mongoose models

Downloads

361

Readme

GraphQL Mongoose Cursor Pagination with Elasticsearch Support

Adds support for Relay-like cursor pagination with Mongoose models/documents. This library also provides type-ahead (autocomplete) functionality (with pagination) using MongoDB regular expression queries. In addition, you can optionally paginate hydrated Mongoose models from Elasticsearch.

Install

yarn add @limit0/mongoose-graphql-pagination

Usage

Pagination, type-ahead, and Elastic+Mongoose pagination support are available via the Pagination, TypeAhead and SearchPagination classes, respectively. All classes should be considered, "single use," and should be instantiated once per query or request.

Pagination

Returns paginated results from MongoDB for the provided Mongoose model.

To begin using, require the class

const { Pagination } = require('@limit0/mongoose-graphql-pagination');

Use the class constructor to configure the settings for the paginated query.

constructor(Model, { criteria = {}, pagination = {}, sort = {}, projection }, options = {})

Model: The Mongoose model instance to query. Required.

criteria: A query criteria object to apply to the paginated query. Can be any MongoDB query. For example: { deleted: false } or { age: { $gt: 30 } }. The criteria will be deeply merged, but will ignore "special" objects such as ObjectId and, by default, will only merge "plain objects." Optional.

pagination: The pagination parameters object. Can accept a first and/or after property. The first value specifies the limit/page size. The after value specifies the cursor to start at when paginating. For example: { first: 50, after: 'some-cursor-value' } would return the first 50 edges after the provided cursor. By default the results will be limited to 10 edges. Optional.

sort: Specifies the sort options. The field property specifies the field to sort by, and the order defines the direction. For example: { field: 'name', order: -1 } would sort the edges by name, descending. By default the edges are sorted by ID, ascending. Optional.

projection: Specifies the fields to return from the database. For example: { field: 1 } or { field: 0 } would include or exclude the specified field, respectively. If left undefined, or as an empty object, all fields will be returned (which is the default behavior). Optional.

options: Specifies additional configuration options, such as default limit, max limit, sort collation, object merge options, and sort created field.

Complete example:

const { Pagination } = require('@limit0/mongoose-graphql-pagination');
const YourModel = require('./your-model');

const paginated = new Pagination(YourModel, {
  criteria: { deleted: false },
  pagination: { first: 25 },
  sort: { field: 'name', order: -1 },
});
// Retrieve the edges...
const edges = paginated.getEdges();

Once the instance is created, use the methods listed below to access the paginated info.

getTotalCount()

Returns the total number of documents that match the query criteria, regardless of page size (limit).

getEdges()

Returns the edges (Mongoose document nodes) that match the query criteria. The results will be limited by the first value.

getEndCursor()

Returns the cursor value (non-obfuscated) of the last edge that matches the current criteria. This value will resolve to the Mongoose document ID, and can be converted into an obfuscated ID when returned by the GraphQL server. Will return null if no results were found.

hasNextPage()

Determines if another page of edges is available, based on the current criteria.

Type-Ahead (Auto Complete)

Type ahead support is implemented using MongoDB regular expression queries. To begin using, require the class:

const { TypeAhead } = require('@limit0/mongoose-graphql-pagination');

Use the class constructor to configure the settings for the type-ahead query.

constructor(field, term, criteria = {}, options = {})

field: The field to query/search against. For example: name. Required.

term: The search term. Can/should be a partial phrase. Required.

criteria: Additional MongoDB query criteria to apply when querying. For example { deleted: false }. The criteria will be deeply merged, but will ignore "special" objects such as ObjectId and, by default, will only merge "plain objects." Optional.

options: The type-ahead configuration options object. Has three type-ahead related properties:

{
  // Determines how the regex is constructed.
  // Can either be `starts-with`, `ends-with`, `exact-match` or `contains`.
  // Defaults to `contains`.
  position: 'contains',
  // Whether to escape regex special characters.
  // Defaults to `true`.
  escape: true,
  // Whether to treat the regex query as case sensitive.
  // Defaults to `false`.
  caseSensitive: false,
}

In addition, the options will also accept the optional mergeOptions object property htat can be used to override the default merge rules.

paginate(Model, pagination = {}, options = {})

Creates a Pagination instance using the constructed TypeAhead options.

buildCriteria()

Returns the MongoDB criteria that can be used for querying the database. Generally, this will not be used and, instead, should be indirectly accessed via the paginate method.

Complete example:

const { TypeAhead } = require('@limit0/mongoose-graphql-pagination');
const YourModel = require('./your-model');

const typeahead = new TypeAhead('name', 'foo', {
  deleted: false,
}, {
  position: 'starts-with',
});
const paginated = typeahead.paginate(YourModel, { first: 25 });
// Retrieve the edges...
const edges = paginated.getEdges();

Search Pagination

Returns paginated and hydrated Mongoose/MongoDB results from Elasticsearch. This assumes that you are, in some fashion, saving some data for a specific Mongoose model within Elasticsearch, as this will attempt to convert the Elastic results back into Mongoose documents from MongoDB. This also assumes that the _id value of the indexed document in Elasticsearch matches the _id value that is stored in MongoDB.

To begin using, require the class

const { SearchPagination } = require('@limit0/mongoose-graphql-pagination');

Use the class constructor to configure the settings for the paginated query.

constructor(Model, client, { params = {}, pagination = {} })

Model: The Mongoose model instance to use for re-querying MongoDB to hydrate the Elasticsearch results. Required.

client: The Elasticsearch client instance created from the elasticsearch Node/JS API library. Required.

params: The elastic search parameters that will be sent to client.search. For example: { index: 'some-index', type: 'some-type', body: { query: { match_all: {} } } } Required.

pagination: The pagination parameters object. Can accept a first and/or after property. The first value specifies the limit/page size. The after value specifies the cursor to start at when paginating. For example: { first: 50, after: 'some-cursor-value' } would return the first 50 edges after the provided cursor. By default the results will be limited to 10 edges. Optional.

Complete example:

const { SearchPagination } = require('@limit0/mongoose-graphql-pagination');
const elasticClient = require('./your-elasticsearch-client');
const YourModel = require('./your-model');

const params = {
  index: 'your-index',
  type: 'your-type',
  body: {
    query: { match_all: {} },
  },
};
const pagination = { first: 25 };

const paginated = new SearchPagination(YourModel, elasticClient, { params, pagination });
// Retrieve the edges...
const edges = paginated.getEdges();

Once the instance is created, use the methods listed below to access the paginated info.

getTotalCount()

Returns the total number of documents that match the search criteria, regardless of page size (limit).

getEdges()

Returns the edges (hydrated Mongoose document nodes from Elasticsearch hits) that match the search criteria. The results will be limited by the first value.

getEndCursor()

Returns the cursor value (non-obfuscated) of the last edge that matches the current criteria. This value will resolve to a JSON stringified version of the Elasticsearch sort value, and can be converted into an obfuscated ID when returned by the GraphQL server. Will return null if no results were found.

hasNextPage()

Determines if another page of edges is available, based on the current criteria.

Pagination Resolvers

Finally, the paginationResolvers provide helper functions for using Pagination with a GraphQL server such as Apollo.

For example, if you had a GraphQL definition similar to this:

scalar Cursor

type Query {
  allContacts(pagination: PaginationInput = {}, sort: ContactSortInput = {}): ContactConnection!
  searchContacts(pagination: PaginationInput = {}, phrase: String!): ContactConnection!
}

type ContactConnection {
  totalCount: Int!
  edges: [ContactEdge]!
  pageInfo: PageInfo!
}

type ContactEdge {
  node: Contact!
  cursor: Cursor!
}

type Contact {
  id: String!
  name: String!
  email: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: Cursor
}

input PaginationInput {
  first: Int! = 25
  after: Cursor
}

input ContactSortInput {
  field: ContactSortField! = createdAt
  order: Int! = -1
}

enum ContactSortField {
  name
  createdAt
  updatedAt
}

The following resolvers could be applied:

const { CursorType } = require('@limit0/graphql-custom-types');
const { Pagination, paginationResolvers, SearchPagination } = require('@limit0/mongoose-graphql-pagination');

const elasticClient = require('./path-to/elasticsearch-client');
const Contact = require('./path-to/contact-model');

module.exports = {
  // The cursor type.
  // Will obfuscate the MongoID for `Pagination` and the Elastic sort value for `SearchPagination`
  Cursor: CursorType,

  // Apply the pagination resolvers for the connection.
  ContactConnection: paginationResolvers.connection,

  Query: {
    /**
     * Use pagination on the query.
     * Will query MongoDB via Mongoose for the provided model.
     */
    allContacts: (root, { pagination, sort }) => new Pagination(Contact, { pagination, sort }, {
      // Informs the sort that the `createdAt` field specifies a created date.
      // Will instead use the document ID when sorting.
      sort: { createdField: 'createdAt' },
    }),

    /**
     * Use search pagination on the query.
     * Will query Elasticsearch and then hydrate the results from
     * MongoDB (via Mongoose) for the provided model.
     */
    searchContacts: (root, { pagination, phrase }) => {
      // Set the parameters for the elastic client `search` method.
      // @see https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html#api-search
      const params = {
        index: 'index-where-contacts-exist',
        type: 'type-where-contacts-exist',
        body: { query: { match: { name: phrase } } },
      };
      return new SearchPagination(Contact, elasticClient, { params, pagination });
    }),
  },
};