Robust handling of ObjectID type for MongoDB

[bajtos]

MongoDB is tricky - see #1875

• It uses a custom ObjectID type for primary keys.
• ObjectID is represented as a string when converted to JSON
• In queries, string values must be cast to ObjectID, otherwise they are not considered as the same value: 'some-id' !== ObjectID('some-id').

As a result, both PK and FK properties must use ObjectID as the type, and coercion must be applied where necessary.

Ideally, I'd like LB4 to define MongoDB PK and FKs as follows:

• {type: 'string', mongodb: {dataType: 'ObjectID'}}

Even better, dataType: 'ObjectID' should be automatically applied by the connector for PK and FKs referencing ObjectID PKs.

For example:

@model()
class Product {
  @property({
    type: 'string',
    generated: true,
    // ^^ implies dataType: 'ObjectID'
  })
  id: string;

  @property({
    type: 'string',
    references: {
      model: () => Category,
      property: 'id',
    },
    // ^^ implies dataType: 'ObjectID' when Category is attached to MongoDB
  })
  categoryId: string;
}

For v1, I suppose we can ask developers to provide dataType manually.

@model()
class Product {
  @property({
    type: 'string',
    generated: true,
    mongodb: {dataType: 'ObjectID'},
  })
  id: string;

  @property({
    type: 'string',
    mongodb: {dataType: 'ObjectID'},
  })
  categoryId: string;
}

With this setup in place, id and categoryId properties should be always returned as strings from DAO and connector methods.

Related discussions

• The issue that started the discussion for LB4: Type ObjectID for model property Type ObjectID for model property  #1875
• Model inclusion resolvers are tricky when ObjectID gets involved - see https://github.com/strongloop/loopback-next/pulls
• Long-term proposal for fixing ObjectID in LB 3.x: Long term proposal for ObjectId coercion strongloop/loopback#1874
• Short-term fix for LB 3.x that was never finished: Add model def objectid support loopback-datasource-juggler#778
• Recent improvements in loopback-connector-mongodb to honor dataType: 'mongodb': feat: adds mongodb: {dataType: 'ObjectID'} to model properties loopback-connector-mongodb#517 and fix: ObjectID data type preservation loopback-connector-mongodb#525

Acceptance criteria

• For every property defined as {type: 'string', mongodb: {dataType: 'ObjectID'}}, including properties defined in nested/embedded models:

  • When the MongoDB connector returns data from database, it converts ObjectID values to strings.
  • When the MongoDB connector writes data to database, it converts string values to ObjectID
  • When the MongoDB connector queries database (think of filter.where, but also findById and replaceById), it converts string values to ObjectID. The conversion is applied to non-trivial conditions too, e.g. {where: {id: { inq: ['my-objectid-1', 'my-objectid-2'] }}}

• Documentation page for MongoDB users explaining extra configuration needed

• Blog post announcing the improvements

Tasks

• Model.toObject() should preserve prototypes (e.g. Date and ObjectID values) Model.toObject() should preserve prototypes (e.g. Date and ObjectID values) #3607
• Spike (initial research & PoC implementation): Spike: robust handling of ObjectID type for MongoDB #3456