mongoose 6.2.3 → 6.2.4

package/types/index.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="./Error.d.ts" />
 /// <reference path="./PipelineStage.d.ts" />
+/// <reference path="./Connection.d.ts" />
 
 import events = require('events');
 import mongodb = require('mongodb');
@@ -8,14 +9,6 @@ import stream = require('stream');
 
 declare module 'mongoose' {
 
-  export enum ConnectionStates {
-    disconnected = 0,
-    connected = 1,
-    connecting = 2,
-    disconnecting = 3,
-    uninitialized = 99,
-  }
-
   class NativeDate extends global.Date {}
 
   /** The Mongoose Date [SchemaType](/docs/schematypes.html). */
@@ -64,9 +57,6 @@ declare module 'mongoose' {
   /** The various Mongoose SchemaTypes. */
   export const SchemaTypes: typeof Schema.Types;
 
-  /** Expose connection states for user-land */
-  export const STATES: typeof ConnectionStates;
-
   /** Opens Mongoose's default connection to MongoDB, see [connections docs](https://mongoosejs.com/docs/connections.html) */
   export function connect(uri: string, options: ConnectOptions, callback: CallbackWithoutResult): void;
   export function connect(uri: string, callback: CallbackWithoutResult): void;
@@ -100,10 +90,11 @@ declare module 'mongoose' {
 
   /** An array containing all models associated with this Mongoose instance. */
   export const models: Models;
+
   /** Creates a Connection instance. */
+  export function createConnection(uri: string, options: ConnectOptions, callback: Callback<Connection>): void;
   export function createConnection(uri: string, options?: ConnectOptions): Connection;
   export function createConnection(): Connection;
-  export function createConnection(uri: string, options: ConnectOptions, callback: Callback<Connection>): void;
 
   /**
    * Removes the model named `name` from the default connection, if it exists.
@@ -288,190 +279,6 @@ declare module 'mongoose' {
   // eslint-disable-next-line @typescript-eslint/no-empty-interface
   interface ClientSession extends mongodb.ClientSession { }
 
-  interface ConnectOptions extends mongodb.MongoClientOptions {
-    /** Set to false to [disable buffering](http://mongoosejs.com/docs/faq.html#callback_never_executes) on all models associated with this connection. */
-    bufferCommands?: boolean;
-    /** The name of the database you want to use. If not provided, Mongoose uses the database name from connection string. */
-    dbName?: string;
-    /** username for authentication, equivalent to `options.auth.user`. Maintained for backwards compatibility. */
-    user?: string;
-    /** password for authentication, equivalent to `options.auth.password`. Maintained for backwards compatibility. */
-    pass?: string;
-    /** Set to false to disable automatic index creation for all models associated with this connection. */
-    autoIndex?: boolean;
-    /** Set to `true` to make Mongoose automatically call `createCollection()` on every model created on this connection. */
-    autoCreate?: boolean;
-  }
-
-  class Connection extends events.EventEmitter {
-    /** Returns a promise that resolves when this connection successfully connects to MongoDB */
-    asPromise(): Promise<this>;
-
-    /** Closes the connection */
-    close(callback: CallbackWithoutResult): void;
-    close(force: boolean, callback: CallbackWithoutResult): void;
-    close(force?: boolean): Promise<void>;
-
-    /** Retrieves a collection, creating it if not cached. */
-    collection<T = AnyObject>(name: string, options?: mongodb.CreateCollectionOptions): Collection<T>;
-
-    /** A hash of the collections associated with this connection */
-    collections: { [index: string]: Collection };
-
-    /** A hash of the global options that are associated with this connection */
-    config: any;
-
-    /** The mongodb.Db instance, set when the connection is opened */
-    db: mongodb.Db;
-
-    /**
-     * Helper for `createCollection()`. Will explicitly create the given collection
-     * with specified options. Used to create [capped collections](https://docs.mongodb.com/manual/core/capped-collections/)
-     * and [views](https://docs.mongodb.com/manual/core/views/) from mongoose.
-     */
-    createCollection<T = AnyObject>(name: string, options?: mongodb.CreateCollectionOptions): Promise<mongodb.Collection<T>>;
-    createCollection<T = AnyObject>(name: string, cb: Callback<mongodb.Collection<T>>): void;
-    createCollection<T = AnyObject>(name: string, options: mongodb.CreateCollectionOptions, cb?: Callback<mongodb.Collection<T>>): Promise<mongodb.Collection<T>>;
-
-    /**
-     * Removes the model named `name` from this connection, if it exists. You can
-     * use this function to clean up any models you created in your tests to
-     * prevent OverwriteModelErrors.
-     */
-    deleteModel(name: string): this;
-
-    /**
-     * Helper for `dropCollection()`. Will delete the given collection, including
-     * all documents and indexes.
-     */
-    dropCollection(collection: string): Promise<void>;
-    dropCollection(collection: string, cb: CallbackWithoutResult): void;
-
-    /**
-     * Helper for `dropDatabase()`. Deletes the given database, including all
-     * collections, documents, and indexes.
-     */
-    dropDatabase(): Promise<void>;
-    dropDatabase(cb: CallbackWithoutResult): void;
-
-    /** Gets the value of the option `key`. Equivalent to `conn.options[key]` */
-    get(key: string): any;
-
-    /**
-     * Returns the [MongoDB driver `MongoClient`](http://mongodb.github.io/node-mongodb-native/3.5/api/MongoClient.html) instance
-     * that this connection uses to talk to MongoDB.
-     */
-    getClient(): mongodb.MongoClient;
-
-    /**
-     * The host name portion of the URI. If multiple hosts, such as a replica set,
-     * this will contain the first host name in the URI
-     */
-    host: string;
-
-    /**
-     * A number identifier for this connection. Used for debugging when
-     * you have [multiple connections](/docs/connections.html#multiple_connections).
-     */
-    id: number;
-
-    /**
-     * A [POJO](https://masteringjs.io/tutorials/fundamentals/pojo) containing
-     * a map from model names to models. Contains all models that have been
-     * added to this connection using [`Connection#model()`](/docs/api/connection.html#connection_Connection-model).
-     */
-    models: { [index: string]: Model<any> };
-
-    /** Defines or retrieves a model. */
-    model<T>(name: string, schema?: Schema<any>, collection?: string, options?: CompileModelOptions): Model<T>;
-    model<T, U, TQueryHelpers = {}>(
-      name: string,
-      schema?: Schema<T, U, TQueryHelpers>,
-      collection?: string,
-      options?: CompileModelOptions
-    ): U;
-
-    /** Returns an array of model names created on this connection. */
-    modelNames(): Array<string>;
-
-    /** The name of the database this connection points to. */
-    name: string;
-
-    /** Opens the connection with a URI using `MongoClient.connect()`. */
-    openUri(uri: string, options?: ConnectOptions): Promise<Connection>;
-    openUri(uri: string, callback: (err: CallbackError, conn?: Connection) => void): Connection;
-    openUri(uri: string, options: ConnectOptions, callback: (err: CallbackError, conn?: Connection) => void): Connection;
-
-    /** The password specified in the URI */
-    pass: string;
-
-    /**
-     * The port portion of the URI. If multiple hosts, such as a replica set,
-     * this will contain the port from the first host name in the URI.
-     */
-    port: number;
-
-    /** Declares a plugin executed on all schemas you pass to `conn.model()` */
-    plugin(fn: (schema: Schema, opts?: any) => void, opts?: any): Connection;
-
-    /** The plugins that will be applied to all models created on this connection. */
-    plugins: Array<any>;
-
-    /**
-     * Connection ready state
-     *
-     * - 0 = disconnected
-     * - 1 = connected
-     * - 2 = connecting
-     * - 3 = disconnecting
-     */
-    readyState: number;
-
-    /** Sets the value of the option `key`. Equivalent to `conn.options[key] = val` */
-    set(key: string, value: any): any;
-
-    /**
-     * Set the [MongoDB driver `MongoClient`](http://mongodb.github.io/node-mongodb-native/3.5/api/MongoClient.html) instance
-     * that this connection uses to talk to MongoDB. This is useful if you already have a MongoClient instance, and want to
-     * reuse it.
-     */
-    setClient(client: mongodb.MongoClient): this;
-
-    /**
-     * _Requires MongoDB >= 3.6.0._ Starts a [MongoDB session](https://docs.mongodb.com/manual/release-notes/3.6/#client-sessions)
-     * for benefits like causal consistency, [retryable writes](https://docs.mongodb.com/manual/core/retryable-writes/),
-     * and [transactions](http://thecodebarbarian.com/a-node-js-perspective-on-mongodb-4-transactions.html).
-     */
-    startSession(options?: mongodb.ClientSessionOptions): Promise<mongodb.ClientSession>;
-    startSession(options: mongodb.ClientSessionOptions, cb: Callback<mongodb.ClientSession>): void;
-
-    /**
-     * Makes the indexes in MongoDB match the indexes defined in every model's
-     * schema. This function will drop any indexes that are not defined in
-     * the model's schema except the `_id` index, and build any indexes that
-     * are in your schema but not in MongoDB.
-     */
-    syncIndexes(options?: SyncIndexesOptions): Promise<ConnectionSyncIndexesResult>;
-    syncIndexes(options: SyncIndexesOptions | null, callback: Callback<ConnectionSyncIndexesResult>): void;
-
-    /**
-     * _Requires MongoDB >= 3.6.0._ Executes the wrapped async function
-     * in a transaction. Mongoose will commit the transaction if the
-     * async function executes successfully and attempt to retry if
-     * there was a retryable error.
-     */
-    transaction(fn: (session: mongodb.ClientSession) => Promise<any>): Promise<any>;
-
-    /** Switches to a different database using the same connection pool. */
-    useDb(name: string, options?: { useCache?: boolean, noListener?: boolean }): Connection;
-
-    /** The username specified in the URI */
-    user: string;
-
-    /** Watches the entire underlying database for changes. Similar to [`Model.watch()`](/docs/api/model.html#model_Model.watch). */
-    watch<ResultType = any>(pipeline?: Array<any>, options?: mongodb.ChangeStreamOptions): mongodb.ChangeStream<ResultType>;
-  }
-
    /*
    * section collection.js
    * http://mongoosejs.com/docs/api.html#collection-js
@@ -981,7 +788,7 @@ declare module 'mongoose' {
     translateAliases(raw: any): any;
 
     /** Creates a `distinct` query: returns the distinct values of the given `field` that match `filter`. */
-    distinct(field: string, filter?: FilterQuery<T>, callback?: Callback<number>): QueryWithHelpers<Array<any>, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
+    distinct<ReturnType = any>(field: string, filter?: FilterQuery<T>, callback?: Callback<number>): QueryWithHelpers<Array<ReturnType>, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /** Creates a `estimatedDocumentCount` query: counts the number of documents in the collection. */
     estimatedDocumentCount(options?: QueryOptions, callback?: Callback<number>): QueryWithHelpers<number, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
@@ -1309,6 +1116,9 @@ declare module 'mongoose' {
     /** Returns a copy of this schema */
     clone<T = this>(): T;
 
+    /** Returns a new schema that has the picked `paths` from this schema. */
+    pick<T = this>(paths: string[], options?: SchemaOptions): T;
+
     /** Object containing discriminators defined on this schema */
     discriminators?: { [name: string]: Schema };
 
@@ -1628,6 +1438,7 @@ declare module 'mongoose' {
     T extends ReadonlyArray<infer U> ? U : T;
 
   type AnyArray<T> = T[] | ReadonlyArray<T>;
+  type SchemaValidator<T> = RegExp | [RegExp, string] | Function | [Function, string] | ValidateOpts<T> | ValidateOpts<T>[];
 
   export class SchemaTypeOptions<T> {
     type?:
@@ -1650,7 +1461,7 @@ declare module 'mongoose' {
     alias?: string;
 
     /** Function or object describing how to validate this schematype. See [validation docs](https://mongoosejs.com/docs/validation.html). */
-    validate?: RegExp | [RegExp, string] | Function | [Function, string] | ValidateOpts<T> | ValidateOpts<T>[];
+    validate?: SchemaValidator<T> | AnyArray<SchemaValidator<T>>;
 
     /** Allows overriding casting logic for this individual path. If a string, the given string overwrites Mongoose's default cast error message. */
     cast?: string;
@@ -2263,7 +2074,7 @@ declare module 'mongoose' {
     deleteOne(callback: Callback): QueryWithHelpers<any, DocType, THelpers, RawDocType>;
 
     /** Creates a `distinct` query: returns the distinct values of the given `field` that match `filter`. */
-    distinct(field: string, filter?: FilterQuery<DocType>, callback?: Callback<number>): QueryWithHelpers<Array<any>, DocType, THelpers, RawDocType>;
+    distinct<ReturnType = any>(field: string, filter?: FilterQuery<DocType>, callback?: Callback<number>): QueryWithHelpers<Array<ReturnType>, DocType, THelpers, RawDocType>;
 
     /** Specifies a `$elemMatch` query condition. When called with one argument, the most recent path passed to `where()` is used. */
     elemMatch(val: Function | any): this;
@@ -2676,6 +2487,13 @@ declare module 'mongoose' {
   } &
     RootQuerySelector<T>;
 
+  /**
+   * Filter query to select the documents that match the query
+   * @example
+   * ```js
+   * { age: { $gte: 30 } }
+   * ```
+   */
   export type FilterQuery<T> = _FilterQuery<T>;
 
   type AddToSetOperators<Type> = {
@@ -2733,6 +2551,13 @@ declare module 'mongoose' {
     [K in keyof T]?: __UpdateDefProperty<T[K]>;
   };
 
+  /**
+   * Update query command to perform on the document
+   * @example
+   * ```js
+   * { age: 30 }
+   * ```
+   */
   export type UpdateQuery<T> = _UpdateQuery<_UpdateQueryDef<T>> & AnyObject;
 
   export type DocumentDefinition<T> = {
@@ -2775,6 +2600,12 @@ declare module 'mongoose' {
     T;
 
   export type SchemaDefinitionType<T> = T extends Document ? Omit<T, Exclude<keyof Document, '_id' | 'id' | '__v'>> : T;
+
+  /**
+   * Documents returned from queries with the lean option enabled.
+   * Plain old JavaScript object documents (POJO).
+   * @see https://mongoosejs.com/docs/tutorials/lean.html
+   */
   export type LeanDocument<T> = Omit<_LeanDocument<T>, Exclude<keyof Document, '_id' | 'id' | '__v'> | '$isSingleNested'>;
 
   export type LeanDocumentOrArray<T> = 0 extends (1 & T) ? T :