feat: enhance aggregation and find functions with detailed parameter documentation

Author: adborroto

src/aggregate.ts

@@ -16,6 +16,44 @@ interface AggregateParams extends PaginationParams {
   collation?: Record<string, any> | null;
 }
 
+/**
+ * Performs an aggregate() query on a passed-in Mongo collection, using criteria you specify.
+ * Unlike `find()`, this method requires fine tuning by the user, and must comply with the following
+ * two criteria so that the pagination magic can work properly.
+ *
+ * 1. `aggregate()` will insert a `$sort` and `$limit` clauses in your aggregation pipeline immediately after
+ * the first $match is found. Consider this while building your pipeline.
+ *
+ * 2. The documents resulting from the aggregation _must_ contain the paginated fields so that a
+ * cursor can be built from the result set.
+ *
+ * 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 {Object} params
+ *    -aggregation {Object[]} The aggregation query.
+ *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
+ *    -paginatedField {String} 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. Immutable. If the value changes between paged queries, it could appear twice.
+ *        3. Accessible. The field must be present in the aggregation's end result so the
+ *          aggregation steps added at the end of the pipeline to implement the paging can access it.
+          4. Consistent. All values (except undefined and null values) must be of the same type.
+ *      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.
+ *    -sortAscending {boolean} Whether to sort in ascending order by the `paginatedField`.
+ *    -sortCaseInsensitive {boolean} Whether to ignore case when sorting, in which case `paginatedField`
+ *      must be a string property.
+ *    -next {String} The value to start querying the page.
+ *    -previous {String} The value to start querying previous page.
+ *    -after {String} The _id to start querying the page.
+ *    -before {String} The _id to start querying previous page.
+ *    -options {Object} Aggregation options
+ *    -collation {Object} An optional collation to provide to the mongo query. E.g. { locale: 'en', strength: 2 }. When null, disables the global collation.
+ */
 export default async function aggregate(
   collection: Collection<Document>,
   params: AggregateParams

src/find.ts

@@ -11,6 +11,35 @@ import {
 } from './utils/query';
 import sanitizeParams, { SanitizeParams } from './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 {Object} params
+ *    -query {Object} The find query.
+ *    -limit {Number} The page size. Must be between 1 and `config.MAX_LIMIT`.
+ *    -fields {Object} Fields to query in the Mongo object format, e.g. {_id: 1, timestamp :1}.
+ *      The default is to query all fields.
+ *    -paginatedField {String} 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. Consistent. All values (except undefined and null values) must be of the same type.
+ *      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.
+ *    -sortAscending {boolean} Whether to sort in ascending order by the `paginatedField`.
+ *    -sortCaseInsensitive {boolean} Whether to ignore case when sorting, in which case `paginatedField`
+ *      must be a string property.
+ *    -next {String} The value to start querying the page.
+ *    -previous {String} The value to start querying previous page.
+ *    -after {String} The _id to start querying the page.
+ *    -before {String} The _id to start querying previous page.
+ *    -hint {String} An optional index hint to provide to the mongo query
+ *    -collation {Object} An optional collation to provide to the mongo query. E.g. { locale: 'en', strength: 2 }. When null, disables the global collation.
+ */
 export interface FindParams extends PaginationParams {
   query?: Document;
   limit?: number;

src/search.ts

@@ -17,9 +17,10 @@ export interface SearchResponse<T = Document> {
 }
 
 /**
- * Performs a search query on a Mongo collection and pages the results. The results are ordered
- * by their relevancy using MongoDB's $text index.
- *
+ * Performs a search query on a Mongo collection and pages the results. This is different from
+ * find() in that the results are ordered by their relevancy, and as such, it does not take
+ * 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 collection - A MongoDB collection object. This MUST have a Mongo $text index.
  * @param searchString - The string to search for.
  * @param params - Search parameters: