Mongoose: Why connect, createConnection, Connection#open? They overlap and conflict each other

[wzup]

Can't understand guiding principle of connection operation in mongoose.
1) Why are there three methods? What is the difference?
2) What is the main use case for each one?

You docs do not answer these questions.

What I found testing every one of them is that they conflict each other.

createConnection already connects to a DB server when called (which is strange by itself; it doesn't return a promise, doesn't accept a callback, but for some reason it deliberately connects; even before I can attach handlers!). And why Connection#open then, if createConnection already establishes a connection?

let conn1 = mongoose.createConnection(uri);

conn1.on('connected', function() {
    console.log('connected:', arguments);

    conn1.open(() => {
        console.log('open:', arguments);
    })
});

connected:
{}

Error: Trying to open unclosed connection.

connect does the same - it connects when called. But at least it accepts a callback and may return _<Thenable> pseudo-promise_ (which actually isn't true, it throws an error when .then is called https://github.com/Automattic/mongoose/issues/4699)

let conn2 = mongoose.connect(uri, function() {

    console.log('callback', arguments);

    let c = conn2.connection;
    console.log('conn2.connection', c); // NativeConnection{...}

    // I can only attach event handlers AFTER event was fired.
    c.on('connecting', function() {
        console.log('connecting', arguments)
    });
    c.on('connected', function() {
        console.log('connected', arguments)
    });
    c.on('error', function() {
        console.error('ERROR', arguments)
    });
    c.on('open', function() {
        console.error('open', arguments) // only this is called
    });
    c.on('reconnected', function() {
        console.error('reconnected', arguments) 
    });
});

open: {}

I can attach event handler only AFTER the event has been fired. It doesn't seem a correct behavior. Or did I miss something?

So, when do we need to call open? when to connect using createConnection? when to connect using connect?
Can you write some good use cases in your docs for every of three methods of connection?

[vkarpov15]

Mongoose has a notion of "connections", which are pools of sockets that connect to mongodb. Mongoose has a default connection, which is what you interact with when you do mongoose.connect(). The preferred way to create a connection is createConnection(), which mongoose.connect() uses under the hood. createConnection() really only useful if you need to connect to multiple distinct mongodb clusters or if you use multiple databases. And open() and openSet() are internal helpers that createConnection() uses, you shouldn't use those unless you really have a good reason to (I don't know of any).

[smolyakoff]

Sometimes it's useful to defer connection open to the latest possible time, but still allow application components to depend on mongoose connection object. For example if you are fetching connection uri from async configuration provider. With createConnection it's not possible, as it will immediately try to connect to the database as a side effect. If you use an override without arguments createConnection(), then you'll have to determine if uri is replica set or not in your own application and then call open or openSet.