Skip to content

Commit

Permalink
chore(index.d.ts): add several more query methods to TypeScript defin…
Browse files Browse the repository at this point in the history 
…itions re: #8108
  • Loading branch information
@vkarpov15
vkarpov15 committed Oct 23, 2020
1 parent 59f7332 commit d7aaa55
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 35 deletions.
136 changes: 135 additions & 1 deletion index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -635,6 +635,7 @@ declare module "mongoose" {
session?: mongodb.ClientSession;
explain?: any;
multi?: boolean;
strict: boolean | string;
}

interface SaveOptions {
Expand Down Expand Up @@ -936,6 +937,9 @@ declare module "mongoose" {
/** Specifies the batchSize option. */
batchSize(val: number): this;

/** Adds a collation to this op (MongoDB 3.4 and up) */
collation(value: mongodb.CollationDocument): this;

/** Specifies the `comment` option. */
comment(val: string): this;

Expand All @@ -947,13 +951,34 @@ declare module "mongoose" {
countDocuments(callback?: (err: any, count: number) => void): Query<number, DocType>;
countDocuments(criteria: FilterQuery<DocType>, callback?: (err: any, count: number) => void): Query<number, DocType>;

/**
* Declare and/or execute this query as a `deleteMany()` operation. Works like
* remove, except it deletes _every_ document that matches `filter` in the
* collection, regardless of the value of `single`.
*/
deleteMany(filter?: FilterQuery<DocType>, options?: QueryOptions, callback?: (err: Error | null, res: any) => void): Query<any, DocType>;

/**
* Declare and/or execute this query as a `deleteOne()` operation. Works like
* remove, except it deletes at most one document regardless of the `single`
* option.
*/
deleteOne(filter?: FilterQuery<DocType>, options?: QueryOptions, callback?: (err: Error | null, res: any) => void): Query<any, DocType>;

/** Creates a `distinct` query: returns the distinct values of the given `field` that match `filter`. */
distinct(field: string, filter?: FilterQuery<DocType>, callback?: (err: any, count: number) => void): Query<Array<any>, DocType>;

/** Specifies a `$elemMatch` query condition. When called with one argument, the most recent path passed to `where()` is used. */
elemMatch(val: Function | any): this;
elemMatch(path: string, val: Function | any): this;

/**
* Gets/sets the error flag on this query. If this flag is not null or
* undefined, the `exec()` promise will reject without executing.
*/
error(): Error | null;
error(val: Error | null): this;

/** Specifies the complementary comparison value for paths specified with `where()` */
equals(val: any): this;

Expand All @@ -964,10 +989,21 @@ declare module "mongoose" {
exists(val: boolean): this;
exists(path: string, val: boolean): this;

/**
* Sets the [`explain` option](https://docs.mongodb.com/manual/reference/method/cursor.explain/),
* which makes this query return detailed execution stats instead of the actual
* query result. This method is useful for determining what index your queries
* use.
*/
explain(verbose?: string): this;

/** Creates a `find` query: gets a list of documents that match `filter`. */
find(callback?: (err: any, count: number) => void): Query<Array<DocType>, DocType>;
find(filter: FilterQuery<DocType>, callback?: (err: any, count: number) => void): Query<Array<DocType>, DocType>;
find(filter: FilterQuery<DocType>, projection?: any | null, options?: QueryOptions | null, callback?: (err: any, count: number) => void): Query<Array<DocType>, DocType>;
find(filter: FilterQuery<DocType>, projection?: any | null, options?: QueryOptions | null, callback?: (err: Error | null, count: number) => void): Query<Array<DocType>, DocType>;

/** Declares the query a findOne operation. When executed, the first found document is passed to the callback. */
findOne(filter?: FilterQuery<DocType>, projection?: any | null, options?: QueryOptions | null, callback?: (err: Error | null, count: number) => void): Query<DocType | null, DocType>;

/** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
findOneAndDelete(filter?: FilterQuery<DocType>, options?: QueryOptions | null, callback?: (err: any, doc: DocType | null, res: any) => void): Query<DocType | null, DocType>;
Expand All @@ -984,6 +1020,25 @@ declare module "mongoose" {
/** Creates a `findOneAndUpdate` query, filtering by the given `_id`. */
findByIdAndUpdate(id?: mongodb.ObjectId | any, update?: UpdateQuery<DocType>, options?: QueryOptions | null, callback?: (err: any, doc: DocType | null, res: any) => void): Query<DocType | null, DocType>;

/**
* For update operations, returns the value of a path in the update's `$set`.
* Useful for writing getters/setters that can work with both update operations
* and `save()`.
*/
get(path: string): any;

/** Returns the current query filter (also known as conditions) as a POJO. */
getFilter(): FilterQuery<DocType>;

/** Gets query options. */
getOptions(): QueryOptions;

/** Returns the current query filter. Equivalent to `getFilter()`. */
getQuery(): FilterQuery<DocType>;

/** Returns the current update operations as a JSON object. */
getUpdate(): UpdateQuery<DocType> | null;

/** Specifies a `$gt` query condition. When called with one argument, the most recent path passed to `where()` is used. */
gt(val: number): this;
gt(path: string, val: number): this;
Expand All @@ -999,6 +1054,12 @@ declare module "mongoose" {
in(val: Array<any>): this;
in(path: string, val: Array<any>): this;

/** Requests acknowledgement that this operation has been persisted to MongoDB's on-disk journal. */
j(val: boolean | null): this;

/** Sets the lean option. */
lean(val?: boolean | any): this;

/** Specifies the maximum number of documents the query will return. */
limit(val: number): this;

Expand All @@ -1017,10 +1078,26 @@ declare module "mongoose" {
/** Specifies the maxScan option. */
maxScan(val: number): this;

/**
* Sets the [maxTimeMS](https://docs.mongodb.com/manual/reference/method/cursor.maxTimeMS/)
* option. This will tell the MongoDB server to abort if the query or write op
* has been running for more than `ms` milliseconds.
*/
maxTimeMS(ms: number): this;

/** Merges another Query or conditions object into this one. */
merge(source: Query<any, any>): this;

/** Specifies a `$mod` condition, filters documents for documents whose `path` property is a number that is equal to `remainder` modulo `divisor`. */
mod(val: Array<number>): this;
mod(path: string, val: Array<number>): this;

/**
* Getter/setter around the current mongoose-specific options for this query
* Below are the current Mongoose-specific options.
*/
mongooseOptions(val?: Pick<QueryOptions, "populate" | "lean" | "omitUndefined" | "strict" | "useFindAndModify">): Pick<QueryOptions, "populate" | "lean" | "omitUndefined" | "strict" | "useFindAndModify">;

/** Specifies a `$ne` query condition. When called with one argument, the most recent path passed to `where()` is used. */
ne(val: any): this;
ne(path: string, val: any);
Expand All @@ -1035,10 +1112,51 @@ declare module "mongoose" {
/** Specifies arguments for an `$or` condition. */
or(array: Array<FilterQuery<DocType>>): this;

/** Get/set the current projection (AKA fields). Pass `null` to remove the current projection. */
projection(fields?: any | null): any;

/** Determines the MongoDB nodes from which to read. */
read(pref: string | mongodb.ReadPreferenceMode, tags?: any[]): this;

/** Sets the readConcern option for the query. */
readConcern(level: string): this;

/** Specifies a `$regex` query condition. When called with one argument, the most recent path passed to `where()` is used. */
regex(val: string | RegExp): this;
regex(path: string, val: string | RegExp): this;

/**
* Declare and/or execute this query as a remove() operation. `remove()` is
* deprecated, you should use [`deleteOne()`](#query_Query-deleteOne)
* or [`deleteMany()`](#query_Query-deleteMany) instead.
*/
remove(filter?: FilterQuery<DocType>, callback?: (err: Error | null, res: mongodb.WriteOpResult['result']) => void): Query<mongodb.WriteOpResult['result'], DocType>;

/** Specifies which document fields to include or exclude (also known as the query "projection") */
select(arg: string | any): this;

/**
* Sets the [MongoDB session](https://docs.mongodb.com/manual/reference/server-sessions/)
* associated with this query. Sessions are how you mark a query as part of a
* [transaction](/docs/transactions.html).
*/
session(session: mongodb.ClientSession | null): this;

/**
* Adds a `$set` to this query's update without changing the operation.
* This is useful for query middleware so you can add an update regardless
* of whether you use `updateOne()`, `updateMany()`, `findOneAndUpdate()`, etc.
*/
set(path: string, value: any): this;

/** Sets query options. Some options only make sense for certain operations. */
setOptions(options: QueryOptions, overwrite: boolean): this;

/** Sets the query conditions to the provided JSON object. */
setQuery(val: FilterQuery<DocType> | null): void;

setUpdate(update: UpdateQuery<DocType>): void;

/** Specifies an `$size` query condition. When called with one argument, the most recent path passed to `where()` is used. */
size(val: number): this;
size(path: string, val: number): this;
Expand All @@ -1053,14 +1171,30 @@ declare module "mongoose" {
/** Specifies this query as a `snapshot` query. */
snapshot(val?: boolean): this;

/** Sets the sort order. If an object is passed, values allowed are `asc`, `desc`, `ascending`, `descending`, `1`, and `-1`. */
sort(arg: string | any): this;

/** Converts this query to a customized, reusable query constructor with all arguments and options retained. */
toConstructor(): new (filter?: FilterQuery<DocType>, options?: QueryOptions) => Query<ResultType, DocType>;

/**
* Sets the specified number of `mongod` servers, or tag set of `mongod` servers,
* that must acknowledge this write before this write is considered successful.
*/
w(val: string | number | null): this;

/** Specifies a path for use with chaining. */
where(path: string, val?: any): this;

/** Defines a `$within` or `$geoWithin` argument for geo-spatial queries. */
within(val?: any): this;

/**
* If [`w > 1`](/docs/api.html#query_Query-w), the maximum amount of time to
* wait for this write to propagate through the replica set before this
* operation fails. The default is `0`, which means no timeout.
*/
wtimeout(ms: number): this;
}

export type FilterQuery<T> = {
Expand Down
35 changes: 1 addition & 34 deletions lib/query.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1427,7 +1427,7 @@ Query.prototype.maxTimeMS = function(ms) {
};

/**
* Returns the current query filter (also known as conditions) as a POJO.
* Returns the current query filter (also known as conditions) as a [POJO](https://masteringjs.io/tutorials/fundamentals/pojo).
*
* ####Example:
*
Expand Down Expand Up @@ -1686,39 +1686,6 @@ Query.prototype.lean = function(v) {
return this;
};

/**
* Returns an object containing the Mongoose-specific options for this query,
* including `lean` and `populate`.
*
* Mongoose-specific options are different from normal options (`sort`, `limit`, etc.)
* because they are **not** sent to the MongoDB server.
*
* ####Example:
*
* const q = new Query();
* q.mongooseOptions().lean; // undefined
*
* q.lean();
* q.mongooseOptions().lean; // true
*
* This function is useful for writing [query middleware](/docs/middleware.html).
* Below is a full list of properties the return value from this function may have:
*
* - `populate`
* - `lean`
* - `omitUndefined`
* - `strict`
* - `nearSphere`
* - `useFindAndModify`
*
* @return {Object} Mongoose-specific options
* @param public
*/

Query.prototype.mongooseOptions = function() {
return this._mongooseOptions;
};

/**
* Adds a `$set` to this query's update without changing the operation.
* This is useful for query middleware so you can add an update regardless
Expand Down

0 comments on commit d7aaa55

Please sign in to comment.