Upsert documentation is misleading

[mhlmhl]

The API documentation of upsert is misleading, if not downright wrong.

The documentation says that "Returns an object with keys numberAffected (the number of documents modified) and insertedId (the unique _id of the document that was inserted, if any)." Also, the callback function is "called with an error object as the first argument and, if no error, the number of affected documents as the second."

This implies that one could do:

const result = collection.upsert(...)

and the callback function would be something like: (error, count) => { ...}

BUT actual experience says that in fact no synchronous result is returned from upsert, and the callback function is actually:

(error, {numberAffected, insertedId}) => {...}

So this is a bug report for the documentation. (Maybe it will save some other developer the couple of hours that I wasted on this today.)

[alan-pl]

I just posted a similar issue re addEmail, and now I'm wondering if this will all be solved by the introduction of TypeScript... Will the docs become typescript-y?

[mhlmhl]

Also, the returned insertId is null if the upsert resulted in updating an existing document; it is non-null only when the upsert created a new document. (You can sort of read the upsert description that way, but it's not at all obvious. Another Meteor trap for developers.)

[filipenevola]

Hi @mhlmhl can you submit a PR improving the docs? https://github.com/meteor/docs

[filipenevola]

I'm closing this issue because it's too old.

If you think this issue is still relevant please open a new one.