[DOCS] Add more documentation about virtual populate option match

[hasezoey]

Do you want to request a feature or report a bug?
documentation

What is the current behavior?
Currently, i can not find more than 1 example of match being used in the documentation for virtual populate (the only example i could find)

so i would like to request more documentation showcasing what this option can do, what arguments it has (when used as a function)

PS: does foreignField accept a function, when yes with what arguments?

[Apokalypt]

PS: does foreignField accept a function, when yes with what arguments?

According to the code, the foreignField allow a function : https://github.com/Automattic/mongoose/blob/master/lib/helpers/populate/getModelsMapForPopulate.js#L391
The only argument is the document you want to populate

[vkarpov15]

Yes, foreignField can be a function. Right now there's no params, just this is the document being populated.

[vkarpov15]

We have a section in the populate docs about match: https://mongoosejs.com/docs/populate.html#match . We'll add some info about using it as a function.

[hasezoey]

Yes, foreignField can be a function. Right now there's no params, just this is the document being populated.

is the same true for localField? because for localField in my testing it gives a this and argument1 (function (arg1)), both are the same

[vkarpov15]

Unfortunate inconsistency between match functions and localField+foreignField functions. match doesn't get any params, just this. But localField and foreignField get the document as this and the first arg for better arrow function support.

[hasezoey]

match doesn't get any params, just this. But localField and foreignField get the document as this and the first arg for better arrow function support.

im my last question (for reference, i mean this comment) i asked about the difference between localField and foreignField and not match

because of the following code:

// NodeJS: 17.3.0
// MongoDB: 4.2-bionic (Docker)
import * as mongoose from 'mongoose'; // [email protected]

const nestedSchema = new mongoose.Schema({
  parent: mongoose.Schema.Types.ObjectId,
});

const parentSchema = new mongoose.Schema({});

parentSchema.virtual('virt', {
  type: mongoose.Schema.Types.ObjectId,
  ref: 'nesteds',
  foreignField: function ff(...args) {
    console.log('ff this', this); // some
    console.log('ff args', args); // none

    return '_id';
  },
  localField: function lf(...args) {
    console.log('lf this', this); // some
    console.log('lf args', args); // some

    return 'parent';
  },
});

const NestedModel = mongoose.model('Nested', nestedSchema);
const ParentModel = mongoose.model('Parent', parentSchema);

(async () => {
  await mongoose.connect(`mongodb://localhost:27017/`, {
    dbName: 'verifyMASTER',
  });

  const parent1 = await ParentModel.create({});
  const nested1 = await NestedModel.create({ parent: parent1._id });
  const nested2 = await NestedModel.create({ parent: parent1._id });

  const found = await ParentModel.findById(parent1._id).orFail().exec();

  await found.populate('virt');

  await mongoose.disconnect();
})();

where some means it is the document, and none mean [] or no document

[vkarpov15]

In 6.2.5, we'll call foreignField functions with doc as first param. Also added better typings, foreignField function type is now ((this: HydratedDocType, doc: HydratedDocType) => string) instead of just Function. See 5ce23b2.