feat(NODE-1046): natively support UUID (de)serialization

[typesafe]

This introduces a global DefaultDeserializeOptions.convertUUIDs and also extends the existing DeserializeOptions with a new convertUUIDs flag. Setting the flag will simply deserialize Binary values with subtype SUBTYPE_UUID as actual UUID instances.

It's great that we have the UUID type, but I really want to avoid having to tediously map these values/fields back-and-fort. This is bound to end up in subtle bugs sooner or later. As a bonus, UUID also features a toJSON eliminating mapping altogether when returning data as JSON.

In case you're using Typescript, you can define fields as UUID and it "just works":

export interface SomeDocument {
...
externalId: UUID;
...
}

I tried to get some feedback via https://github.com/mongodb/js-bson/issues/234, but thought I might as well open a PR 🙂.

[typesafe]

Any thoughts on this?

[dariakp]

@typesafe Hi there, apologies for the delayed response, the team has been swamped with end of quarter work. At this point, the feature is not scheduled to be picked up by the team, however, given the renewed interest, we are going to revisit it later this week and check whether it aligns with our existing roadmap for this library. We'll have an update for you early next week at the latest.

At a glance, your implementation appears to present a potentially viable solution (and we certainly appreciate the added tests!), however, we need to do our due diligence to ensure that a) it does indeed meet the requirements around this feature from a product perspective, b) it does not conflict with any current plans for related features, and c) that we will be able to dedicate the necessary resources as a team to deliver and maintain this feature in the context of our other priorities. Thank you for your patience!

[typesafe]

Hey @dariakp, thanks for the update! I of course totally understand the due diligence 👍 👌 .

[dariakp]

@typesafe After a discussion with the team, we think that we'd like to take on the UUID feature improvement as a concerted effort in about 1-2 months time. There is related work that needs to be done to make our implementation fully spec compliant, and, at this point, I'm not sure that we'll be able to take your specific approach to the convertUUIDs option - we'll have to go through the technical design process for the feature set as a whole, although @nbbeeken can provide additional context on our current considerations. Thank you again for providing your suggestion. We'll keep you updated on the direction once we schedule the work.

[typesafe]

Thanks for the update. I was hoping for sooner, but I understand 🙂 .

[nbbeeken]

We appreciate your understanding @typesafe we are considering this feature carefully, its adding a new paradigm where on driver side we'll likely need to keep a global setting (as in across all MongoClient instances) for convertUUIDs along side a setting for uuidRepresentation. In the meantime there is a toBSON method that can be used to customize the way objects get serialized. One could use that to add automatic UUID support.

The purpose of the spec rule to make converting UUIDs explicit is to avoid bugs that are worse than mistakenly forgetting to do the explicit conversion. At least forgetting the explicit call will crash. However, because of those legacy language specific UUID formats if users don't correctly deserialize and serialize the UUID as the correct representation it was stored as in MongoDB, the bytes of the UUID will be reordered unexpectedly and silently, making a UUID completely different on round trip.

[nbbeeken]

Just a suggestion, obviously with its own upsides/downsides/caveats, using a combination of the cursor's map function and the toBSON method one could implement the automatic conversion at the app layer.

const docs = col.find().map(d => /* convert Binary(s) to UUID */)
const res = col.insertOne({ toBSON() { /* convert UUIDs to Binary */ } })

[typesafe]

Hey @dariakp & @nbbeeken, I was wondering if there's an update on this 😇

[dariakp]

@typesafe Unfortunately due to higher priority issues we have not yet had a chance to schedule this, and I don't know whether we'll be able to in the upcoming quarter. I did send the ticket into the triage queue to see if we can get something more concrete in terms of a date.

[nbbeeken]

Hi @typesafe, thanks again for your assistance with this feature, we've fleshed out a design to make sure we hit all the marks here. EJSON and BSON will both support the UUID instance, along with an option to control the new changes. You can look forward to the feature landing soon, and you can view the project on our JIRA here
ref: #508