@andrew_l/mongo-pagination 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Andrew L. <andrew.io.dev@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Mongo Pagination Toolkit <!-- omit in toc -->
+
+![license](https://img.shields.io/npm/l/%40andrew_l%2Fmongo-pagination) <!-- omit in toc -->
+![npm version](https://img.shields.io/npm/v/%40andrew_l%2Fmongo-pagination) <!-- omit in toc -->
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40andrew_l%2Fmongo-pagination) <!-- omit in toc -->
+
+This package provides an efficient and customizable way to handle pagination for MongoDB and Mongoose queries. It simplifies working with large datasets by enabling cursor pagination, handling sorting, and managing tokens for navigating between pages.
+
+[Documentation](https://men232.github.io/toolkit/reference/@andrew_l/mongo-pagination/)
+
+<!-- install placeholder -->
+
+## ✨ Features
+
+- **MongoDB & Mongoose Support**: Add pagination to queries with ease.
+- **Token-based Navigation**: Reliable page transitions without offsets.
+- **Customizable Sorting**: Sort by multiple fields and directions.
+- **TypeScript Ready**: Built-in type safety and autocompletion.
+- **Lightweight Integration**: Simple setup for existing applications.
+
+## 🚀 Example: Usage with Mongoose
+
+```js
+import { withMongoosePagination } from '@andrew_l/mongo-pagination';
+import mongoose from 'mongoose';
+
+async function paginateMongoose() {
+  const User = mongoose.model(
+    'User',
+    new mongoose.Schema({ name: String, status: String }),
+  );
+  const query = User.find({ status: 'active' });
+
+  const paginator = withMongoosePagination(query, {
+    paginationFields: ['_id'],
+  });
+
+  const result = await paginator.exec();
+  console.log(result.items); // Logs the items for the current page
+  console.log(result.metadata); // Logs pagination metadata
+}
+```
+
+## 🚀 Example: Mongoose Plugin
+
+```js
+import setupPlugin from '@andrew_l/mongo-pagination/mongoose-7'; // or 8
+
+import mongoose from 'mongoose';
+
+setupPlugin(mongoose);
+
+async function paginateMongoose() {
+  const User = mongoose.model(
+    'User',
+    new mongoose.Schema({ name: String, status: String }),
+  );
+
+  const result = await User.find({ status: 'active' }).paginator();
+
+  console.log(result.items); // Logs the items for the current page
+  console.log(result.metadata); // Logs pagination metadata
+
+  const nextPage = await User.find().paginatorNext(result.metadata.next);
+
+  console.log(nextPage.items); // Logs the items for the second page
+  console.log(nextPage.metadata);
+}
+```
+
+## 🚀 Example: Usage with MongoDB
+
+```js
+import { withMongoPagination } from '@andrew_l/mongo-pagination';
+import { MongoClient } from 'mongodb';
+
+async function paginateMongoDB() {
+  const client = new MongoClient('mongodb://localhost:27017');
+  await client.connect();
+
+  const db = client.db('exampleDb');
+  const collection = db.collection('exampleCollection');
+
+  const cursor = collection.find({ status: 'active' });
+
+  const paginator = withMongoPagination(cursor, {
+    paginationFields: ['_id'],
+  });
+
+  const result = await paginator.exec();
+  console.log(result.items); // Logs the items for the current page
+  console.log(result.metadata); // Logs pagination metadata
+}
+```
+
+## 🤔 Why Use This Package?
+
+1. **Efficient for Large Datasets:** Loads only the necessary data.
+2. **Token-based Pagination:** Ideal for dynamic datasets.
+3. **Flexible & Customizable:** Adaptable to your requirements.
+4. **TypeScript Support:** Minimized errors, better productivity.

package/dist/index.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+const withMongoosePagination = require('./shared/mongo-pagination.CHC5agt7.cjs');
+require('@andrew_l/toolkit');
+require('kareem');
+require('mongodb');
+require('@andrew_l/tl-pack');
+require('debug');
+require('node:stream');
+
+class QueryAdapterMongodb {
+  constructor(cursor) {
+    this.cursor = cursor;
+  }
+  getModelName() {
+    return this.cursor.namespace.collection;
+  }
+  getOptions() {
+    const findOptions = this.cursor.findOptions;
+    return {
+      limit: findOptions.limit,
+      sort: findOptions.sort
+    };
+  }
+  getFilter() {
+    return this.cursor.cursorFilter;
+  }
+  setOptions({ limit, sort }) {
+    if (limit !== void 0) this.cursor.limit(limit);
+    if (sort !== void 0) this.cursor.sort(sort);
+  }
+  setFilter(filter) {
+    this.cursor.filter(filter);
+  }
+  toArray() {
+    return this.cursor.toArray();
+  }
+  stream() {
+    return this.cursor.stream();
+  }
+}
+
+function withMongoPagination(cursor, options) {
+  const adapter = new QueryAdapterMongodb(cursor);
+  const pagin = new withMongoosePagination.QueryPaginator(adapter, options);
+  return pagin;
+}
+
+exports.createRangeFilter = withMongoosePagination.createRangeFilter;
+exports.createToken = withMongoosePagination.createToken;
+exports.mergeFilters = withMongoosePagination.mergeFilters;
+exports.tweakQuery = withMongoosePagination.tweakQuery;
+exports.withMongoosePagination = withMongoosePagination.withMongoosePagination;
+exports.withMongoPagination = withMongoPagination;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/QueryAdapterMongodb.ts","../src/withMongoPagination.ts"],"sourcesContent":["import type { FindCursor, FindOptions } from 'mongodb';\nimport type { Readable } from 'node:stream';\nimport type { QueryAdapter } from './QueryAdapter';\n\nexport class QueryAdapterMongodb<T = any>\n  implements QueryAdapter.QueryAdapter<T>\n{\n  constructor(private cursor: FindCursor) {}\n\n  getModelName(): string {\n    return this.cursor.namespace.collection!;\n  }\n\n  getOptions(): QueryAdapter.Options {\n    const findOptions = (this.cursor as any).findOptions as FindOptions;\n\n    return {\n      limit: findOptions.limit,\n      sort: findOptions.sort,\n    };\n  }\n\n  getFilter(): QueryAdapter.Filter {\n    return (this.cursor as any).cursorFilter;\n  }\n\n  setOptions({ limit, sort }: QueryAdapter.Options): void {\n    if (limit !== undefined) this.cursor.limit(limit);\n    if (sort !== undefined) this.cursor.sort(sort);\n  }\n\n  setFilter(filter: QueryAdapter.Filter): void {\n    this.cursor.filter(filter);\n  }\n\n  toArray(): Promise<T[]> {\n    return this.cursor.toArray();\n  }\n\n  stream(): Readable {\n    return this.cursor.stream();\n  }\n}\n","import type { FindCursor } from 'mongodb';\nimport { QueryAdapterMongodb } from './QueryAdapterMongodb';\nimport { QueryPaginator, type QueryPaginatorOptions } from './QueryPaginator';\n\ntype ExtractSchema<T> = T extends FindCursor<infer X> ? X : never;\n\n/**\n * Enhances a MongoDB `FindCursor` with pagination capabilities.\n *\n * @param cursor - The MongoDB cursor to be paginated.\n * @param [options] - Optional configuration for pagination.\n *\n * @example\n * // Basic usage with a MongoDB cursor:\n * import { MongoClient } from 'mongodb';\n *\n * async function paginateCollection() {\n *   const client = new MongoClient('mongodb://localhost:27017');\n *   await client.connect();\n *\n *   const db = client.db('exampleDb');\n *   const collection = db.collection('exampleCollection');\n *\n *   const cursor = collection.find({ status: 'active' });\n *\n *   const paginator = withMongoPagination(cursor, {\n *     paginationFields: ['_id'],\n *     next: null,\n *   });\n *\n *   const result = await paginator.exec();\n *   console.log(result.items); // Logs the items for the current page\n *   console.log(result.metadata); // Logs pagination metadata\n * }\n *\n *\n * @example\n * // Using a custom preQuery callback:\n * const paginator = withMongoPagination(cursor, {\n *   preQuery: function () {\n *     console.log('Executing query...');\n *   },\n * });\n *\n * const result = await paginator.exec();\n * console.log(result.items);\n *\n * @group Main\n */\nexport function withMongoPagination<T extends FindCursor>(\n  cursor: T,\n  options?: QueryPaginatorOptions,\n): QueryPaginator<ExtractSchema<T>> {\n  const adapter = new QueryAdapterMongodb(cursor);\n  const pagin = new QueryPaginator(adapter, options);\n\n  return pagin;\n}\n"],"names":["QueryPaginator"],"mappings":";;;;;;;;;;AAIO,MAAM,mBAEb,CAAA;AAAA,EACE,YAAoB,MAAoB,EAAA;AAApB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA,CAAA;AAAA,GAAqB;AAAA,EAEzC,YAAuB,GAAA;AACrB,IAAO,OAAA,IAAA,CAAK,OAAO,SAAU,CAAA,UAAA,CAAA;AAAA,GAC/B;AAAA,EAEA,UAAmC,GAAA;AACjC,IAAM,MAAA,WAAA,GAAe,KAAK,MAAe,CAAA,WAAA,CAAA;AAEzC,IAAO,OAAA;AAAA,MACL,OAAO,WAAY,CAAA,KAAA;AAAA,MACnB,MAAM,WAAY,CAAA,IAAA;AAAA,KACpB,CAAA;AAAA,GACF;AAAA,EAEA,SAAiC,GAAA;AAC/B,IAAA,OAAQ,KAAK,MAAe,CAAA,YAAA,CAAA;AAAA,GAC9B;AAAA,EAEA,UAAW,CAAA,EAAE,KAAO,EAAA,IAAA,EAAoC,EAAA;AACtD,IAAA,IAAI,KAAU,KAAA,KAAA,CAAA,EAAgB,IAAA,CAAA,MAAA,CAAO,MAAM,KAAK,CAAA,CAAA;AAChD,IAAA,IAAI,IAAS,KAAA,KAAA,CAAA,EAAgB,IAAA,CAAA,MAAA,CAAO,KAAK,IAAI,CAAA,CAAA;AAAA,GAC/C;AAAA,EAEA,UAAU,MAAmC,EAAA;AAC3C,IAAK,IAAA,CAAA,MAAA,CAAO,OAAO,MAAM,CAAA,CAAA;AAAA,GAC3B;AAAA,EAEA,OAAwB,GAAA;AACtB,IAAO,OAAA,IAAA,CAAK,OAAO,OAAQ,EAAA,CAAA;AAAA,GAC7B;AAAA,EAEA,MAAmB,GAAA;AACjB,IAAO,OAAA,IAAA,CAAK,OAAO,MAAO,EAAA,CAAA;AAAA,GAC5B;AACF;;ACOgB,SAAA,mBAAA,CACd,QACA,OACkC,EAAA;AAClC,EAAM,MAAA,OAAA,GAAU,IAAI,mBAAA,CAAoB,MAAM,CAAA,CAAA;AAC9C,EAAA,MAAM,KAAQ,GAAA,IAAIA,qCAAe,CAAA,OAAA,EAAS,OAAO,CAAA,CAAA;AAEjD,EAAO,OAAA,KAAA,CAAA;AACT;;;;;;;;;"}

package/dist/index.d.cts

@@ -0,0 +1,150 @@
+import { Q as QueryAdapter, T as Token, a as QueryPaginatorOptions, b as QueryPaginator } from './shared/mongo-pagination.BU3-d0QB.cjs';
+export { c as QueryPaginatorMeta, d as QueryPaginatorResult, f as TokenOptions, e as createToken } from './shared/mongo-pagination.BU3-d0QB.cjs';
+import { Sort, FindCursor } from 'mongodb';
+import { Query } from 'mongoose';
+import 'node:stream';
+
+/**
+ * Creates a range filter based on sorting direction and values.
+ *
+ * This function generates a range filter to be used in queries, typically for pagination,
+ * based on the provided sorting direction (ascending or descending) and the sorting values (field names and values).
+ *
+ * @param sortDirection - The sorting direction, which could be ascending or descending.
+ * @param sortValues - The sorting values, including field names and their respective values for sorting.
+ * @returns A range filter object that can be used in MongoDB.
+ *
+ * @example
+ * // Example usage
+ * const sortDirection = { age: 1 };
+ * const sortValues = { age: 30 };
+ * const rangeFilter = createRangeFilter(sortDirection, sortValues);
+ * console.log(rangeFilter);
+ * // Output: { age: { $gt: 30 } }
+ *
+ * @group Utils
+ */
+declare function createRangeFilter(sortDirection: Sort, sortValues: Record<string, any>): Record<string, any>;
+/**
+ * Merges two MongoDB filters in the most effective way.
+ *
+ * This function combines two filters, prioritizing the most specific criteria
+ * from both and ensuring the merged filter works efficiently for MongoDB queries.
+ *
+ * @param first - The first MongoDB filter object.
+ * @param second - The second MongoDB filter object.
+ * @returns The merged MongoDB filter object, combining both filters.
+ *
+ * @example
+ * // Basic usage:
+ * const filter1 = { status: 'active', age: { $gt: 18 } };
+ * const filter2 = { age: { $lt: 60 }, country: 'USA' };
+ *
+ * const mergedFilter = mergeFilters(filter1, filter2);
+ * console.log(mergedFilter);
+ * // Output: { status: 'active', age: { $gt: 18, $lt: 60 }, country: 'USA' }
+ *
+ * @group Utils
+ */
+declare function mergeFilters(first: Record<string, any>, second: Record<string, any>): Record<string, any>;
+interface TweakQueryOptions {
+    query: QueryAdapter.QueryAdapter;
+    paginationFields: string[];
+    token?: Token;
+}
+declare function tweakQuery({ paginationFields, token, query, }: TweakQueryOptions): string[];
+
+type AnyQuery = Query<any, any>;
+type ExtractDocType<T> = T extends Query<infer X, any> ? X : never;
+/**
+ * Enhances a Mongoose query with pagination capabilities.
+ *
+ * @param query - The Mongoose query to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a Mongoose query:
+ * import { withMongoosePagination } from './pagination';
+ * import mongoose from 'mongoose';
+ *
+ * async function paginateMongooseQuery() {
+ *   const User = mongoose.model('User', new mongoose.Schema({ name: String, status: String }));
+ *
+ *   const query = User.find({ status: 'active' });
+ *
+ *   const paginator = withMongoosePagination(query, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ * @example
+ * // Using custom preQuery and postQuery callbacks:
+ * const paginator = withMongoosePagination(query, {
+ *   preQuery: function () {
+ *     console.log('Before executing the query');
+ *   },
+ *   postQuery: function () {
+ *     console.log('After executing the query');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items); // Logs items for the current page
+ * console.log(result.metadata); // Logs pagination metadata
+ *
+ * @group Main
+ */
+declare function withMongoosePagination<T extends AnyQuery>(query: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractDocType<T>>;
+
+type ExtractSchema<T> = T extends FindCursor<infer X> ? X : never;
+/**
+ * Enhances a MongoDB `FindCursor` with pagination capabilities.
+ *
+ * @param cursor - The MongoDB cursor to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a MongoDB cursor:
+ * import { MongoClient } from 'mongodb';
+ *
+ * async function paginateCollection() {
+ *   const client = new MongoClient('mongodb://localhost:27017');
+ *   await client.connect();
+ *
+ *   const db = client.db('exampleDb');
+ *   const collection = db.collection('exampleCollection');
+ *
+ *   const cursor = collection.find({ status: 'active' });
+ *
+ *   const paginator = withMongoPagination(cursor, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ *
+ * @example
+ * // Using a custom preQuery callback:
+ * const paginator = withMongoPagination(cursor, {
+ *   preQuery: function () {
+ *     console.log('Executing query...');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items);
+ *
+ * @group Main
+ */
+declare function withMongoPagination<T extends FindCursor>(cursor: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractSchema<T>>;
+
+export { QueryPaginatorOptions, createRangeFilter, mergeFilters, tweakQuery, withMongoPagination, withMongoosePagination };

package/dist/index.d.mts

@@ -0,0 +1,150 @@
+import { Q as QueryAdapter, T as Token, a as QueryPaginatorOptions, b as QueryPaginator } from './shared/mongo-pagination.BU3-d0QB.mjs';
+export { c as QueryPaginatorMeta, d as QueryPaginatorResult, f as TokenOptions, e as createToken } from './shared/mongo-pagination.BU3-d0QB.mjs';
+import { Sort, FindCursor } from 'mongodb';
+import { Query } from 'mongoose';
+import 'node:stream';
+
+/**
+ * Creates a range filter based on sorting direction and values.
+ *
+ * This function generates a range filter to be used in queries, typically for pagination,
+ * based on the provided sorting direction (ascending or descending) and the sorting values (field names and values).
+ *
+ * @param sortDirection - The sorting direction, which could be ascending or descending.
+ * @param sortValues - The sorting values, including field names and their respective values for sorting.
+ * @returns A range filter object that can be used in MongoDB.
+ *
+ * @example
+ * // Example usage
+ * const sortDirection = { age: 1 };
+ * const sortValues = { age: 30 };
+ * const rangeFilter = createRangeFilter(sortDirection, sortValues);
+ * console.log(rangeFilter);
+ * // Output: { age: { $gt: 30 } }
+ *
+ * @group Utils
+ */
+declare function createRangeFilter(sortDirection: Sort, sortValues: Record<string, any>): Record<string, any>;
+/**
+ * Merges two MongoDB filters in the most effective way.
+ *
+ * This function combines two filters, prioritizing the most specific criteria
+ * from both and ensuring the merged filter works efficiently for MongoDB queries.
+ *
+ * @param first - The first MongoDB filter object.
+ * @param second - The second MongoDB filter object.
+ * @returns The merged MongoDB filter object, combining both filters.
+ *
+ * @example
+ * // Basic usage:
+ * const filter1 = { status: 'active', age: { $gt: 18 } };
+ * const filter2 = { age: { $lt: 60 }, country: 'USA' };
+ *
+ * const mergedFilter = mergeFilters(filter1, filter2);
+ * console.log(mergedFilter);
+ * // Output: { status: 'active', age: { $gt: 18, $lt: 60 }, country: 'USA' }
+ *
+ * @group Utils
+ */
+declare function mergeFilters(first: Record<string, any>, second: Record<string, any>): Record<string, any>;
+interface TweakQueryOptions {
+    query: QueryAdapter.QueryAdapter;
+    paginationFields: string[];
+    token?: Token;
+}
+declare function tweakQuery({ paginationFields, token, query, }: TweakQueryOptions): string[];
+
+type AnyQuery = Query<any, any>;
+type ExtractDocType<T> = T extends Query<infer X, any> ? X : never;
+/**
+ * Enhances a Mongoose query with pagination capabilities.
+ *
+ * @param query - The Mongoose query to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a Mongoose query:
+ * import { withMongoosePagination } from './pagination';
+ * import mongoose from 'mongoose';
+ *
+ * async function paginateMongooseQuery() {
+ *   const User = mongoose.model('User', new mongoose.Schema({ name: String, status: String }));
+ *
+ *   const query = User.find({ status: 'active' });
+ *
+ *   const paginator = withMongoosePagination(query, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ * @example
+ * // Using custom preQuery and postQuery callbacks:
+ * const paginator = withMongoosePagination(query, {
+ *   preQuery: function () {
+ *     console.log('Before executing the query');
+ *   },
+ *   postQuery: function () {
+ *     console.log('After executing the query');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items); // Logs items for the current page
+ * console.log(result.metadata); // Logs pagination metadata
+ *
+ * @group Main
+ */
+declare function withMongoosePagination<T extends AnyQuery>(query: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractDocType<T>>;
+
+type ExtractSchema<T> = T extends FindCursor<infer X> ? X : never;
+/**
+ * Enhances a MongoDB `FindCursor` with pagination capabilities.
+ *
+ * @param cursor - The MongoDB cursor to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a MongoDB cursor:
+ * import { MongoClient } from 'mongodb';
+ *
+ * async function paginateCollection() {
+ *   const client = new MongoClient('mongodb://localhost:27017');
+ *   await client.connect();
+ *
+ *   const db = client.db('exampleDb');
+ *   const collection = db.collection('exampleCollection');
+ *
+ *   const cursor = collection.find({ status: 'active' });
+ *
+ *   const paginator = withMongoPagination(cursor, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ *
+ * @example
+ * // Using a custom preQuery callback:
+ * const paginator = withMongoPagination(cursor, {
+ *   preQuery: function () {
+ *     console.log('Executing query...');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items);
+ *
+ * @group Main
+ */
+declare function withMongoPagination<T extends FindCursor>(cursor: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractSchema<T>>;
+
+export { QueryPaginatorOptions, createRangeFilter, mergeFilters, tweakQuery, withMongoPagination, withMongoosePagination };

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+import { Q as QueryAdapter, T as Token, a as QueryPaginatorOptions, b as QueryPaginator } from './shared/mongo-pagination.BU3-d0QB.js';
+export { c as QueryPaginatorMeta, d as QueryPaginatorResult, f as TokenOptions, e as createToken } from './shared/mongo-pagination.BU3-d0QB.js';
+import { Sort, FindCursor } from 'mongodb';
+import { Query } from 'mongoose';
+import 'node:stream';
+
+/**
+ * Creates a range filter based on sorting direction and values.
+ *
+ * This function generates a range filter to be used in queries, typically for pagination,
+ * based on the provided sorting direction (ascending or descending) and the sorting values (field names and values).
+ *
+ * @param sortDirection - The sorting direction, which could be ascending or descending.
+ * @param sortValues - The sorting values, including field names and their respective values for sorting.
+ * @returns A range filter object that can be used in MongoDB.
+ *
+ * @example
+ * // Example usage
+ * const sortDirection = { age: 1 };
+ * const sortValues = { age: 30 };
+ * const rangeFilter = createRangeFilter(sortDirection, sortValues);
+ * console.log(rangeFilter);
+ * // Output: { age: { $gt: 30 } }
+ *
+ * @group Utils
+ */
+declare function createRangeFilter(sortDirection: Sort, sortValues: Record<string, any>): Record<string, any>;
+/**
+ * Merges two MongoDB filters in the most effective way.
+ *
+ * This function combines two filters, prioritizing the most specific criteria
+ * from both and ensuring the merged filter works efficiently for MongoDB queries.
+ *
+ * @param first - The first MongoDB filter object.
+ * @param second - The second MongoDB filter object.
+ * @returns The merged MongoDB filter object, combining both filters.
+ *
+ * @example
+ * // Basic usage:
+ * const filter1 = { status: 'active', age: { $gt: 18 } };
+ * const filter2 = { age: { $lt: 60 }, country: 'USA' };
+ *
+ * const mergedFilter = mergeFilters(filter1, filter2);
+ * console.log(mergedFilter);
+ * // Output: { status: 'active', age: { $gt: 18, $lt: 60 }, country: 'USA' }
+ *
+ * @group Utils
+ */
+declare function mergeFilters(first: Record<string, any>, second: Record<string, any>): Record<string, any>;
+interface TweakQueryOptions {
+    query: QueryAdapter.QueryAdapter;
+    paginationFields: string[];
+    token?: Token;
+}
+declare function tweakQuery({ paginationFields, token, query, }: TweakQueryOptions): string[];
+
+type AnyQuery = Query<any, any>;
+type ExtractDocType<T> = T extends Query<infer X, any> ? X : never;
+/**
+ * Enhances a Mongoose query with pagination capabilities.
+ *
+ * @param query - The Mongoose query to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a Mongoose query:
+ * import { withMongoosePagination } from './pagination';
+ * import mongoose from 'mongoose';
+ *
+ * async function paginateMongooseQuery() {
+ *   const User = mongoose.model('User', new mongoose.Schema({ name: String, status: String }));
+ *
+ *   const query = User.find({ status: 'active' });
+ *
+ *   const paginator = withMongoosePagination(query, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ * @example
+ * // Using custom preQuery and postQuery callbacks:
+ * const paginator = withMongoosePagination(query, {
+ *   preQuery: function () {
+ *     console.log('Before executing the query');
+ *   },
+ *   postQuery: function () {
+ *     console.log('After executing the query');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items); // Logs items for the current page
+ * console.log(result.metadata); // Logs pagination metadata
+ *
+ * @group Main
+ */
+declare function withMongoosePagination<T extends AnyQuery>(query: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractDocType<T>>;
+
+type ExtractSchema<T> = T extends FindCursor<infer X> ? X : never;
+/**
+ * Enhances a MongoDB `FindCursor` with pagination capabilities.
+ *
+ * @param cursor - The MongoDB cursor to be paginated.
+ * @param [options] - Optional configuration for pagination.
+ *
+ * @example
+ * // Basic usage with a MongoDB cursor:
+ * import { MongoClient } from 'mongodb';
+ *
+ * async function paginateCollection() {
+ *   const client = new MongoClient('mongodb://localhost:27017');
+ *   await client.connect();
+ *
+ *   const db = client.db('exampleDb');
+ *   const collection = db.collection('exampleCollection');
+ *
+ *   const cursor = collection.find({ status: 'active' });
+ *
+ *   const paginator = withMongoPagination(cursor, {
+ *     paginationFields: ['_id'],
+ *     next: null,
+ *   });
+ *
+ *   const result = await paginator.exec();
+ *   console.log(result.items); // Logs the items for the current page
+ *   console.log(result.metadata); // Logs pagination metadata
+ * }
+ *
+ *
+ * @example
+ * // Using a custom preQuery callback:
+ * const paginator = withMongoPagination(cursor, {
+ *   preQuery: function () {
+ *     console.log('Executing query...');
+ *   },
+ * });
+ *
+ * const result = await paginator.exec();
+ * console.log(result.items);
+ *
+ * @group Main
+ */
+declare function withMongoPagination<T extends FindCursor>(cursor: T, options?: QueryPaginatorOptions): QueryPaginator<ExtractSchema<T>>;
+
+export { QueryPaginatorOptions, createRangeFilter, mergeFilters, tweakQuery, withMongoPagination, withMongoosePagination };

package/dist/index.mjs

@@ -0,0 +1,49 @@
+import { Q as QueryPaginator } from './shared/mongo-pagination.YG1DNE27.mjs';
+export { a as createRangeFilter, c as createToken, m as mergeFilters, t as tweakQuery, w as withMongoosePagination } from './shared/mongo-pagination.YG1DNE27.mjs';
+import '@andrew_l/toolkit';
+import 'kareem';
+import 'mongodb';
+import '@andrew_l/tl-pack';
+import 'debug';
+import 'node:stream';
+
+class QueryAdapterMongodb {
+  constructor(cursor) {
+    this.cursor = cursor;
+  }
+  getModelName() {
+    return this.cursor.namespace.collection;
+  }
+  getOptions() {
+    const findOptions = this.cursor.findOptions;
+    return {
+      limit: findOptions.limit,
+      sort: findOptions.sort
+    };
+  }
+  getFilter() {
+    return this.cursor.cursorFilter;
+  }
+  setOptions({ limit, sort }) {
+    if (limit !== void 0) this.cursor.limit(limit);
+    if (sort !== void 0) this.cursor.sort(sort);
+  }
+  setFilter(filter) {
+    this.cursor.filter(filter);
+  }
+  toArray() {
+    return this.cursor.toArray();
+  }
+  stream() {
+    return this.cursor.stream();
+  }
+}
+
+function withMongoPagination(cursor, options) {
+  const adapter = new QueryAdapterMongodb(cursor);
+  const pagin = new QueryPaginator(adapter, options);
+  return pagin;
+}
+
+export { withMongoPagination };
+//# sourceMappingURL=index.mjs.map