Docs missing for ref and refPath as function

[piyushk96]

Prerequisites

• I have written a descriptive issue title

Mongoose version

7.5.0

Node.js version

N/A

MongoDB version

N/A

Operating system

None

Operating system version (i.e. 20.04, 11.3, 10)

No response

Issue

There is no proper documentation available on how to use a ref / refPath as functions in a schema.

Also, I want to understand what is the intended behaviour of these functions? Whether they are called only once during the schema initialization phase and cache the function return value or these functions are executed for each document.

The typescript mentions that these functions have access to this and doc so, is that mean that these functions will have access to document while processing and we can use document's fields to manipulate returned model or modelName

The only mention of ref function is here but it doesn't explains the above questions

Use Case:

const Entity1 = new Schema({
  f1: { type: Number, required: true},
});
const Entity1Model = mongoose.model('Entity1', Entity1);

const Entity2 = new Schema({
  f2: { type: Number, required: true},
});
const Entity2Model = mongoose.model('Entity2', Entity2);

const E3 = new Schema({
  itemType: { type: String, enum: ['e1', 'e2'], required: true},

  itemId: {
    type: Types.ObjectId,
    ref(doc) {
      return doc.itemType === 'e1' ? Entity1Model : Entity2Model;
      // OR
      // return this.itemType === 'e1' ? Entity1Model : Entity2Model;
    }
  }
})
const E3Model = mongoose.model('E3', E3);

[piyushk96]

@vkarpov15 can you please tell me the expected behavior here until the docs are released on the website

[vkarpov15]

ref and refPath functions are called every time you populate(), for every document being populated. Is that helpful @piyushk96 ?

[piyushk96]

@vkarpov15 Thanks for the reply. Yes, this helps.