fix(populate): consistently convert Buffer representation of UUID to hex string to avoid confusing populate assignment

lib/helpers/populate/assignRawDocsToIdStructure.js

@@ -81,6 +81,8 @@ function assignRawDocsToIdStructure(rawIds, resultDocs, resultOrder, options, re
     if (id?.constructor?.name === 'Binary' && id.sub_type === 4 && typeof id.toUUID === 'function') {
       // Workaround for gh-15315 because Mongoose UUIDs don't use BSON UUIDs yet.
       sid = String(id.toUUID());
+    } else if (id?.constructor?.name === 'Buffer' && id._subtype === 4 && typeof id.toUUID === 'function') {
+      sid = String(id.toUUID());
     } else {
       sid = String(id);
     }

lib/model.js

@@ -4688,7 +4688,14 @@ function _assign(model, vals, mod, assignmentOpts) {
           if (__val instanceof Document) {
             __val = __val._doc._id;
           }
-          key = String(__val);
+          if (__val?.constructor?.name === 'Binary' && __val.sub_type === 4 && typeof __val.toUUID === 'function') {
+            // Workaround for gh-15315 because Mongoose UUIDs don't use BSON UUIDs yet.
+            key = String(__val.toUUID());
+          } else if (__val?.constructor?.name === 'Buffer' && __val._subtype === 4 && typeof __val.toUUID === 'function') {
+            key = String(__val.toUUID());
+          } else {
+            key = String(__val);
+          }
           if (rawDocs[key]) {
             if (Array.isArray(rawDocs[key])) {
               rawDocs[key].push(val);
@@ -4711,7 +4718,14 @@ function _assign(model, vals, mod, assignmentOpts) {
         if (_val instanceof Document) {
           _val = _val._doc._id;
         }
-        key = String(_val);
+        if (_val?.constructor?.name === 'Binary' && _val.sub_type === 4 && typeof _val.toUUID === 'function') {
+          // Workaround for gh-15315 because Mongoose UUIDs don't use BSON UUIDs yet.
+          key = String(_val.toUUID());
+        } else if (_val?.constructor?.name === 'Buffer' && _val._subtype === 4 && typeof _val.toUUID === 'function') {
+          key = String(_val.toUUID());
+        } else {
+          key = String(_val);
+        }
         if (rawDocs[key]) {
           if (Array.isArray(rawDocs[key])) {
             rawDocs[key].push(val);

lib/types/buffer.js

@@ -5,6 +5,7 @@
 'use strict';
 
 const Binary = require('bson').Binary;
+const UUID = require('bson').UUID;
 const utils = require('../utils');
 
 /**
@@ -207,6 +208,22 @@ MongooseBuffer.mixin.toBSON = function() {
   return new Binary(this, this._subtype || 0);
 };
 
+/**
+ * Converts this buffer to a UUID. Throws an error if subtype is not 4.
+ *
+ * @return {UUID}
+ * @api public
+ * @method toUUID
+ * @memberOf MongooseBuffer
+ */
+
+MongooseBuffer.mixin.toUUID = function() {
+  if (this._subtype !== 4) {
+    throw new Error('Cannot convert a Buffer with subtype ' + this._subtype + ' to a UUID');
+  }
+  return new UUID(this);
+};
+
 /**
  * Determines if this buffer is equals to `other` buffer
  *

test/model.populate.test.js

@@ -11463,4 +11463,41 @@ describe('model: populate:', function() {
     assert.strictEqual(populatedCategory.announcements.length, 1);
     assert.strictEqual(populatedCategory.announcements[0].title, 'New Tech Release');
   });
+
+  it('handles virtual populated UUID array field (gh-15316)', async function() {
+    const RoleSchema = Schema({
+      _id: { type: 'UUID', required: true },
+      name: String
+    });
+
+    const MemberSchema = Schema({
+      _id: { type: 'UUID', required: true },
+      _role_ids: [{
+        type: 'UUID',
+        ref: 'Role',
+        required: true
+      }]
+    });
+
+    MemberSchema.virtual('roles', {
+      ref: 'Role',
+      localField: '_role_ids',
+      foreignField: '_id'
+    });
+
+    const Role = db.model('Role', RoleSchema);
+    const Member = db.model('Member', MemberSchema);
+
+    const role1 = await Role.create({ _id: randomUUID(), name: 'admin' });
+    const role2 = await Role.create({ _id: randomUUID(), name: 'user' });
+
+    const memberId = randomUUID();
+    await Member.create({ _id: memberId, _role_ids: [role1._id, role2._id] });
+
+    const populated = await Member.findOne({ _id: memberId }).populate('roles');
+    assert.deepStrictEqual(
+      populated.roles.sort((a, b) => a.name.localeCompare(b.name)).map(role => role.name),
+      ['admin', 'user']
+    );
+  });
 });