@tepez/mongo-cursor-pagination 8.0.1 → 9.0.0

package/README.md

@@ -42,8 +42,7 @@ Call `find()` with the following parameters:
    Performs a find() query on a passed-in Mongo collection, using criteria you specify. The results
    are ordered by the paginatedField.
 
-   @param {MongoCollection} collection A collection object returned from the MongoDB library's
-      or the mongoist package's `db.collection(<collectionName>)` method.
+   @param {MongoCollection} collection A collection object returned from the MongoDB library's.
    @param {Object} params
       -query {Object} The find query.
       -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.

package/dist/node/aggregate.js

@@ -20,8 +20,7 @@ const sanitizeParams = require('./utils/sanitizeParams');
  * Additionally, an additional query will be appended to the first `$match` found in order to apply the offset
  * required for the cursor.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's.
  * @param {Object} params
  *    -aggregation {Object[]} The aggregation query.
  *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
@@ -74,11 +73,7 @@ module.exports = (() => {
      */
     const options = config.COLLATION ? { collation: config.COLLATION } : undefined;
 
-    // Support both the native 'mongodb' driver and 'mongoist'. See:
-    // https://www.npmjs.com/package/mongoist#cursor-operations
-    const aggregateMethod = collection.aggregateAsCursor ? 'aggregateAsCursor' : 'aggregate';
-
-    const results = yield collection[aggregateMethod](params.aggregation, options).toArray();
+    const results = yield collection.aggregate(params.aggregation, options).toArray();
 
     return prepareResponse(results, params);
   });

package/dist/node/find.js

@@ -10,8 +10,7 @@ const sanitizeParams = require('./utils/sanitizeParams');
  * Performs a find() query on a passed-in Mongo collection, using criteria you specify. The results
  * are ordered by the paginatedField.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's.
  * @param {Object} params
  *    -query {Object} The find query.
  *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
@@ -38,11 +37,10 @@ module.exports = (() => {
     const cursorQuery = generateCursorQuery(params);
     const $sort = generateSort(params);
 
-    // Support both the native 'mongodb' driver and 'mongoist'. See:
-    // https://www.npmjs.com/package/mongoist#cursor-operations
-    const findMethod = collection.findAsCursor ? 'findAsCursor' : 'find';
+    const findOptions = {};
+    if (params.fields) findOptions.projection = params.fields;
 
-    const query = collection[findMethod]({ $and: [cursorQuery, params.query] }, params.fields);
+    const query = collection.find({ $and: [cursorQuery, params.query] }, findOptions);
 
     /**
      * IMPORTANT

package/dist/node/findWithReq.js

@@ -17,7 +17,6 @@ const sanitizeQuery = require('./utils/sanitizeQuery');
  *      can be specified as a comma-delimited list. If field name used is not in params.fields,
  *      it will be ignored.
  * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
  * @param {Object} params See documentation for `find()`, plus these options:
  *    -overrideFields: an object containing fields that should override fields from the querystring, e.g.
  *      {_id: 0} or {internalField: 1}. We only support field exclusion for _id, as we expect whitelists

package/dist/node/search.js

@@ -11,8 +11,7 @@ const bsonUrlEncoding = require('./utils/bsonUrlEncoding');
  * a paginatedField parameter. Note that this is less performant than find() because it must
  * perform the full search on each call to this function.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method. This MUST have a Mongo
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's. This MUST have a Mongo
  *    $text index on it.
  *    See https://docs.mongodb.com/manual/core/index-text/.
  * @param {String} searchString String to search on.
@@ -86,11 +85,7 @@ module.exports = (() => {
 
     let response;
 
-    // Support both the native 'mongodb' driver and 'mongoist'. See:
-    // https://www.npmjs.com/package/mongoist#cursor-operations
-    const aggregateMethod = collection.aggregateAsCursor ? 'aggregateAsCursor' : 'aggregate';
-
-    const aggregateQuery = collection[aggregateMethod](aggregate);
+    const aggregateQuery = collection.aggregate(aggregate);
     const execMethod = aggregateQuery.toArray ? 'toArray' : 'exec';
     const results = yield aggregateQuery[execMethod]();
 

package/dist/node/utils/sanitizeParams.js

@@ -2,9 +2,9 @@ function _asyncToGenerator(fn) { return function () { var gen = fn.apply(this, a
 
 const _ = require('underscore');
 
-const config = require('../config');
 const bsonUrlEncoding = require('./bsonUrlEncoding');
 const getPropertyViaDotNotation = require('./getPropertyViaDotNotation');
+const config = require('../config');
 
 module.exports = (() => {
   var _ref = _asyncToGenerator(function* (collection, params) {

package/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Based on https://github.com/mixmaxhq/mongo-cursor-pagination/blob/v7.3.1/README.md
+ */
+declare module '@tepez/mongo-cursor-pagination' {
+  import { Document, FilterQuery, HydratedDocument, Schema, TreatAsPrimitives, Types } from 'mongoose';
+
+  // copy LeanDocument from mongoose 6.11.1 because it was removed in 7.0.0 and we need it to infer the lean type from the document
+  // https://github.com/Automattic/mongoose/blob/6.11.1/types/index.d.ts
+
+  type LeanType<T> =
+    0 extends (1 & T) ? T : // any
+      T extends TreatAsPrimitives ? T : // primitives
+        T extends Types.ArraySubdocument ? Omit<LeanDocument<T>, 'parentArray' | 'ownerDocument' | 'parent'> :
+          T extends Types.Subdocument ? Omit<LeanDocument<T>, '$isSingleNested' | 'ownerDocument' | 'parent'> :
+            LeanDocument<T>; // Documents and everything else
+  type LeanArray<T extends unknown[]> = T extends unknown[][] ? LeanArray<T[number]>[] : LeanType<T[number]>[];
+
+  type _LeanDocument<T> = {
+    [K in keyof T]: LeanDocumentElement<T[K]>;
+  };
+
+  // Keep this a separate type, to ensure that T is a naked type.
+  // This way, the conditional type is distributive over union types.
+  // This is required for PopulatedDoc.
+  type LeanDocumentElement<T> =
+    T extends unknown[] ? LeanArray<T> : // Array
+      T extends Document ? LeanDocument<T> : // Subdocument
+        T;
+
+  type LeanDocument<T> = Omit<_LeanDocument<T>, Exclude<keyof Document, '_id' | 'id' | '__v'> | '$isSingleNested'>;
+
+  type MongoosePlugin = Parameters<Schema['plugin']>[0]
+
+  export interface ICursorPaginationMongoosePluginOptions {
+    /**
+     * custom function name
+     * @default paginate
+     */
+    name?: string;
+  }
+
+  export interface IPaginateOptions<T extends Document<T>> {
+    /**
+     * The find query
+     */
+    query: FilterQuery<T>;
+
+    /**
+     * The page size. Must be between 1 and `config.MAX_LIMIT`.
+     */
+    limit: number;
+
+    /**
+     * Fields to query in the Mongo object format, e.g. {_id: 1, timestamp :1}.
+     * @default query all fields.
+     */
+    fields?: any;
+
+    /**
+     * The field name to query the range for. The field must be:
+     * 1. Orderable. We must sort by this value. If duplicate values for paginatedField field
+     * exist, the results will be secondarily ordered by the _id.
+     * 2. Indexed. For large collections, this should be indexed for query performance.
+     * 3. Immutable. If the value changes between paged queries, it could appear twice.
+     * 4. Complete. A value must exist for all documents.
+     * The default is to use the Mongo built-in '_id' field, which satisfies the above criteria.
+     * The only reason to NOT use the Mongo _id field is if you chose to implement your own ids.
+     * @default _id
+     */
+    paginatedField?: string;
+
+    /**
+     * True to sort using paginatedField ascending
+     * @default false - descending
+     */
+    sortAscending?: boolean;
+
+    /**
+     * The value to start querying the page.
+     */
+    next?: string;
+
+    /**
+     * The value to start querying previous page.
+     */
+    previous?: string;
+  }
+
+  export interface IPaginateResult<T extends Document> {
+    results: HydratedDocument<T>[];
+    previous?: string;
+    /**
+     * base64 encoded
+     * Contains the ID of the last object in the page
+     */
+    next: string;
+    hasNext: boolean;
+  }
+
+  export interface ICursorPaginationExtendedModel<T extends Document> {
+    paginate(options: IPaginateOptions<T>): IPaginateResult<T>;
+  }
+
+  export const mongoosePlugin: MongoosePlugin;
+
+  export const config: {
+    /**
+     * @default 50
+     */
+    DEFAULT_LIMIT: number
+
+    /**
+     * @default 300
+     */
+    MAX_LIMIT: number
+  };
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@tepez/mongo-cursor-pagination",
-  "version": "8.0.1",
+  "version": "9.0.0",
   "description": "Make it easy to return cursor-paginated results from a Mongo collection",
   "main": "index.js",
   "files": [
     "index.js",
     "dist",
-    "src"
+    "src",
+    "index.d.ts"
   ],
   "scripts": {
     "babelBuild": "babel src -d dist/node",
     "babelWatch": "babel --watch src -d dist/node",
     "lint": "eslint .",
     "test-native": "npx cross-env DRIVER=native jest",
-    "test-mongoist": "npx cross-env DRIVER=mongoist jest",
+    "test-native-debug": "npx cross-env DRIVER=native npx --node-options=--inspect-brk jest --runInBand",
     "test": "npm run test-native",
+    "test-debug": "npm run test-native-debug",
     "update": "npm run babelBuild && npx np --no-publish --branch tepez"
   },
   "repository": {
@@ -37,28 +39,27 @@
   },
   "homepage": "https://github.com/tepez/mongo-cursor-pagination#readme",
   "dependencies": {
-    "base64-url": "^2.2.0",
-    "bson": "^4.1.0",
-    "dot-prop": "^3.0.0",
+    "base64-url": "^2.3.3",
+    "bson": "^5.3.0",
+    "dot-prop": "^6.0.1",
     "projection-utils": "^1.1.0",
-    "semver": "^5.4.1",
-    "underscore": "^1.9.2"
+    "semver": "^7.5.1",
+    "underscore": "^1.13.6"
   },
   "devDependencies": {
-    "@mixmaxhq/prettier-config": "^1.0.0",
+    "@mixmaxhq/prettier-config": "^1.1.0",
     "babel-cli": "^6.26.0",
-    "babel-core": "^6.26.0",
+    "babel-core": "^6.26.3",
     "babel-plugin-transform-async-to-generator": "^6.24.1",
     "cross-env": "^7.0.3",
-    "eslint": "^6.8.0",
-    "eslint-config-mixmax": "^4.11.2",
-    "jest": "^27.0.5",
-    "mongodb": "2.2.36",
-    "mongodb-memory-server-core": "^6.9.6",
-    "mongoist": "2.3.0",
-    "mongoose": "5.12.14",
-    "np": "^7.5.0",
-    "prettier": "^1.19.1"
+    "eslint": "^8.41.0",
+    "eslint-config-mixmax": "^5.1.0",
+    "jest": "^29.5.0",
+    "mongodb": "5.5.0",
+    "mongodb-memory-server-core": "^8.12.2",
+    "mongoose": "7.2.1",
+    "np": "^8.0.1",
+    "prettier": "^2.8.8"
   },
   "engines": {
     "node": ">= 6.9.1"

package/src/aggregate.js

@@ -18,8 +18,7 @@ const sanitizeParams = require('./utils/sanitizeParams');
  * Additionally, an additional query will be appended to the first `$match` found in order to apply the offset
  * required for the cursor.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's.
  * @param {Object} params
  *    -aggregation {Object[]} The aggregation query.
  *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
@@ -69,11 +68,7 @@ module.exports = async function aggregate(collection, params) {
    */
   const options = config.COLLATION ? { collation: config.COLLATION } : undefined;
 
-  // Support both the native 'mongodb' driver and 'mongoist'. See:
-  // https://www.npmjs.com/package/mongoist#cursor-operations
-  const aggregateMethod = collection.aggregateAsCursor ? 'aggregateAsCursor' : 'aggregate';
-
-  const results = await collection[aggregateMethod](params.aggregation, options).toArray();
+  const results = await collection.aggregate(params.aggregation, options).toArray();
 
   return prepareResponse(results, params);
 };

package/src/find.js

@@ -8,8 +8,7 @@ const sanitizeParams = require('./utils/sanitizeParams');
  * Performs a find() query on a passed-in Mongo collection, using criteria you specify. The results
  * are ordered by the paginatedField.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's.
  * @param {Object} params
  *    -query {Object} The find query.
  *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
@@ -28,18 +27,17 @@ const sanitizeParams = require('./utils/sanitizeParams');
  *    -before {String} The _id to start querying previous page.
  *    -hint {String} An optional index hint to provide to the mongo query
  */
-module.exports = async function(collection, params) {
+module.exports = async function (collection, params) {
   const removePaginatedFieldInResponse = params.fields && !params.fields[params.paginatedField];
 
   params = _.defaults(await sanitizeParams(collection, params), { query: {} });
   const cursorQuery = generateCursorQuery(params);
   const $sort = generateSort(params);
 
-  // Support both the native 'mongodb' driver and 'mongoist'. See:
-  // https://www.npmjs.com/package/mongoist#cursor-operations
-  const findMethod = collection.findAsCursor ? 'findAsCursor' : 'find';
+  const findOptions = {};
+  if (params.fields) findOptions.projection = params.fields;
 
-  const query = collection[findMethod]({ $and: [cursorQuery, params.query] }, params.fields);
+  const query = collection.find({ $and: [cursorQuery, params.query] }, findOptions);
 
   /**
    * IMPORTANT

package/src/findWithReq.js

@@ -15,7 +15,6 @@ const sanitizeQuery = require('./utils/sanitizeQuery');
  *      can be specified as a comma-delimited list. If field name used is not in params.fields,
  *      it will be ignored.
  * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method.
  * @param {Object} params See documentation for `find()`, plus these options:
  *    -overrideFields: an object containing fields that should override fields from the querystring, e.g.
  *      {_id: 0} or {internalField: 1}. We only support field exclusion for _id, as we expect whitelists

package/src/mongoose.plugin.js

@@ -11,12 +11,12 @@ const search = require('./search');
  * @param {string} options.searchFnName name of the function.
  */
 
-module.exports = function(schema, options) {
+module.exports = function (schema, options) {
   /**
    * paginate function
    * @param {Object} params required parameter
    */
-  const findFn = function(params) {
+  const findFn = function (params) {
     if (!this.collection) {
       throw new Error('collection property not found');
     }
@@ -31,7 +31,7 @@ module.exports = function(schema, options) {
    * @param {String} searchString String to search on. Required parameter
    * @param {Object} params
    */
-  const searchFn = function(searchString, params) {
+  const searchFn = function (searchString, params) {
     if (!this.collection) {
       throw new Error('collection property not found');
     }

package/src/search.js

@@ -9,8 +9,7 @@ const bsonUrlEncoding = require('./utils/bsonUrlEncoding');
  * a paginatedField parameter. Note that this is less performant than find() because it must
  * perform the full search on each call to this function.
  *
- * @param {MongoCollection} collection A collection object returned from the MongoDB library's
- *    or the mongoist package's `db.collection(<collectionName>)` method. This MUST have a Mongo
+ * @param {MongoCollection} collection A collection object returned from the MongoDB library's. This MUST have a Mongo
  *    $text index on it.
  *    See https://docs.mongodb.com/manual/core/index-text/.
  * @param {String} searchString String to search on.
@@ -22,7 +21,7 @@ const bsonUrlEncoding = require('./utils/bsonUrlEncoding');
  *    -next {String} The value to start querying the page. Defaults to start at the beginning of
  *      the results.
  */
-module.exports = async function(collection, searchString, params) {
+module.exports = async function (collection, searchString, params) {
   if (_.isString(params.limit)) params.limit = parseInt(params.limit, 10);
   if (params.next) params.next = bsonUrlEncoding.decode(params.next);
 
@@ -90,11 +89,7 @@ module.exports = async function(collection, searchString, params) {
 
   let response;
 
-  // Support both the native 'mongodb' driver and 'mongoist'. See:
-  // https://www.npmjs.com/package/mongoist#cursor-operations
-  const aggregateMethod = collection.aggregateAsCursor ? 'aggregateAsCursor' : 'aggregate';
-
-  const aggregateQuery = collection[aggregateMethod](aggregate);
+  const aggregateQuery = collection.aggregate(aggregate);
   const execMethod = aggregateQuery.toArray ? 'toArray' : 'exec';
   const results = await aggregateQuery[execMethod]();
 

package/src/utils/bsonUrlEncoding.js

@@ -6,10 +6,10 @@ const { EJSON } = require('bson');
  * encode/decode as a URL-safe string.
  */
 
-module.exports.encode = function(obj) {
+module.exports.encode = function (obj) {
   return base64url.encode(EJSON.stringify(obj));
 };
 
-module.exports.decode = function(str) {
+module.exports.decode = function (str) {
   return EJSON.parse(base64url.decode(str));
 };

package/src/utils/sanitizeParams.js

@@ -1,8 +1,8 @@
 const _ = require('underscore');
 
-const config = require('../config');
 const bsonUrlEncoding = require('./bsonUrlEncoding');
 const getPropertyViaDotNotation = require('./getPropertyViaDotNotation');
+const config = require('../config');
 
 module.exports = async function sanitizeParams(collection, params) {
   if (params.previous) params.previous = bsonUrlEncoding.decode(params.previous);

package/CHANGELOG.md

@@ -1,76 +0,0 @@
-## [7.4.0](https://github.com/mixmaxhq/mongo-cursor-pagination/compare/v7.3.1...v7.4.0) (2021-03-08)
-
-
-### Features
-
-* **mongoose-plugin:** add search function ([0efd73c](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/0efd73c9a5e53887226a4a1d2b61605a0e168514))
-
-
-### Bug Fixes
-
-* skip bad commit message ([4c85357](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/4c85357f1079c6f73877ba6775b2eb6ad962c422))
-
-### [7.3.1](https://github.com/mixmaxhq/mongo-cursor-pagination/compare/v7.3.0...v7.3.1) (2020-08-10)
-
-
-### Bug Fixes
-
-* **bson:** fixes regression where string _ids were no longer supported ([1487195](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/1487195444fb1b6f151014522e498000d1dd452d))
-
-## [7.3.0](https://github.com/mixmaxhq/mongo-cursor-pagination/compare/v7.2.1...v7.3.0) (2020-05-06)
-
-
-### Features
-
-* **find:** add optional hint parameter for the cursor ([17616da](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/17616da43641ff2d455e70d96368e839afb216ae))
-
-### [7.2.1](https://github.com/mixmaxhq/mongo-cursor-pagination/compare/v7.2.0...v7.2.1) (2020-05-06)
-
-
-### Bug Fixes
-
-* apply no-var rule changes ([8cf0620](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/8cf0620b023ac460a62788b9d11763211d5a5f88))
-* comply with new eslint rules ([e5851bd](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/e5851bde1a86ab322aa6eac4c56995d98f80e74b))
-* eslint cleanup ([3c3c913](https://github.com/mixmaxhq/mongo-cursor-pagination/commit/3c3c91311cab97d51896f16c8463d73bdb7d9225))
-
-## Changelog
-
-* 7.2.0 Add support for `COLLATION` configuration parameter.
-
-* 7.1.0 Add support for `aggregate`.
-
-* 7.0.1 Update base64-url to fix security issue (https://github.com/mixmaxhq/mongo-cursor-pagination/pull/41 - thanks @pwiebe).
-
-* 7.0.0 Add findWithReq overrideFields support. Breaking: now throws errors on unusable `fields`/`overrideFields`, so check your inputs. Also changes our intersection mechanism, so it _could_ cause backwards-incompatible changes to fields resolution. If causes unexpected backwards-incompatible changes, please file an issue!
-
-* 6.3.0 Can be used as a Mongoose plugin
-
-* 6.2.0 Added support for 'after' and 'before' parameters - thanks @lirbank
-
-* 6.1.0 Added support for native mongodb driver (https://github.com/mixmaxhq/mongo-cursor-pagination/pull/24 - thanks @lirbank)
-
-* 6.0.1 Fix issue where calling `find` with a paginated field that has dot notation e.g. `start.dateTime` produces an invalid `next` token.
-
-* 6.0.0 Breaking API change: `mongo-cursor-pagination` requires a Promise enabled mongodb instance from `mongoist` and returns Promises from `find`, `findWithReq`, and `search` rather than handling callbacks. *Note: Although the library now uses `async/await`, it is still useable in node >= 6.9.0.*
-
-* 5.0.0 Now `50` results are returned by default, and up to `300` results can be returned if the `limit` parameter is used. These can be overridden by setting `mongoPaging.config.DEFAULT_LIMIT` and `mongoPaging.config.MAX_LIMIT` respectively.
-
-* 4.1.1 Fixed bug that would overwrite `$or` in queries passed in.
-
-* 4.1.0 Adds `sortAscending` option to sort by the `paginatedField` ascending. Defaults to false (existing behavior).
-
-* 4.0.0 Breaking API change: `next` and `previous` attributes are now always returned with every response (in case the client wants to poll for new changes). New attributes `hasPrevious` and `hasNext` should now be used know if there are more results in the previous or next page. Before the change, `next` and `previously` could not be replied upon to know if there were more pages.
-
-* 3.1.1 Don't use `let` for backwards compatibility.
-
-* 3.1.0 `findInReq()` now accepts dot notation for fields. So you can pass `?fields=users.userId` to only turn the `userId` property for `users` in the response.
-
-* 3.0.1 Fixed bug where the \_id field was always returned when a paginatedField was used.
-
-* 3.0.0 Breaking API change: `find()` no longer accepts a string for `limit`. Added `findWithReq`.
-
-* 2.0.0 Changed API to so you now set global config on the config object instead of the root export itself (e.g. `require('mongo-cursor-pagination').config.MAX_LIMIT = 100`). The default `MAX_LIMIT` is now a more reasonable 25 instead of 100. Added `search()`. Fixed edge case where pages will be incorrect if paginatedField has duplicate values.
-
-* 1.1.0 Add `MAX_LIMIT` global setting to clamp
-
-* 1.0.0 Initial release