Proposal: 3.0: third argument to find() should be an options object that invokes query builders, not a projection

The issue

In 2.x calling Apostrophe’s find looks like this:

somePiecesModule.find(req, { color: 'blue' }, { title: 1, _url: 1 })...

This was originally by analogy to MongoDB’s find, which used to take a projection as a second argument (because req isn’t a thing in mongo):

someCollection.find({ color: 'blue' }, { title: 1, _url: 1 })...

However, in the MongoDB 3.x driver this changed in a backwards-incompatible way. It is now:

someCollection.find({ color: 'blue' }, {
  project: {
    title: 1, slug: 1, type: 1
  },
  sort: {
    updatedAt: -1
  }
})...

In the MongoDB 3.x driver, the final argument to find is an “options object” that basically can be used as an alternative way to call any of the chainable methods of mongodb cursors, including project and find. The above call is equivalent to:

someCollection.find({ color: 'blue' }).project({ title: 1, slug: 1, type: 1 }).sort({ updatedAt: -1 });

This was the big bc break that forced us to create emulate-mongo-2-driver, which allows A2 to use the MongoDB 3.x driver under the hood, but with MongoDB 2.x syntax to avoid a bc break in Apostrophe code that talks to MongoDB directly.

However in A3 we have already moved to using the MongoDB 3.x driver natively, no 2.x emulation, developers are expected to learn and love the MongoDB 3.x syntax if they talk to MongoDB directly.

So in places where Apostrophe’s own higher-level model APIs used to be congruent with MongoDB, they should be again. That means you should be able to write:

somePiecesModule.find(req, { color: 'blue' }, {
  project: {
    title: 1, _url: 1
  },
  sort: {
    updatedAt: -1
  }
})...

To be exact, properties of the third argument are treated as chainable query builder method names and invoked with their values.

We already have a convenience method for this, applyBuilders, so this would be a quick change. Mostly it would be about fixing existing calls that pass a projection as the third argument.

Our API is intentionally not identical to MongoDB’s because we provide higher level abstractions like permissions and pagination and children(true) and all manner of cool stuff. But, it shouldn’t be inconsistent with MongoDB’s where there is no good reason.

Yeah?

[boutell]

Yes, this is important to mention in the “so you thought you’d just migrate this lil’ site from 2.x to 3.x” list.

And, agreed that it would be nice if mongo would standardize their own API between CLI and drivers. The drivers seem to lead the way at mongo though, not so much the CLI.

[abea]

Good to close by me.