Static methods and instance methods

In Mongoose, static methods and instance methods are two different types of methods that operate on models and documents respectively, serving different logical scenarios. Static methods are typically used for model-level operations, while instance methods are bound to specific documents and handle document-level logic.

Characteristics and Use Cases of Static Methods

Static methods are defined directly on the model and are called through the model itself, not through model instances. These methods are typically used for operations related to the entire collection, such as complex queries, aggregations, or data statistics.

In Mongoose, static methods are defined as follows:

const userSchema = new mongoose.Schema({
  name: String,
  age: Number
});

// Define a static method
userSchema.statics.findByAge = function(age) {
  return this.find({ age });
};

const User = mongoose.model('User', userSchema);

// Use the static method
const users = await User.findByAge(25);

Static methods are particularly suitable for the following scenarios:

1. Encapsulating complex query logic
2. Implementing model-level utility functions
3. Performing cross-document operations
4. Implementing data aggregation functionality

For example, we can create a static method to count users by age range:

userSchema.statics.countByAgeRange = function(min, max) {
  return this.countDocuments({ 
    age: { $gte: min, $lte: max } 
  });
};

// Usage
const count = await User.countByAgeRange(20, 30);

Characteristics and Use Cases of Instance Methods

Instance methods are defined on documents and are called through specific document instances. These methods are typically used to handle business logic related to individual documents, such as data validation or document operations.

The syntax for defining instance methods is as follows:

userSchema.methods.getInfo = function() {
  return `Name: ${this.name}, Age: ${this.age}`;
};

const user = new User({ name: 'Alice', age: 25 });
console.log(user.getInfo()); // Output: Name: Alice, Age: 25

Common use cases for instance methods include:

1. Document-level data operations
2. Document validation
3. Document relationship handling
4. Custom document behavior

For example, we can create an instance method to update a user's age with validation:

userSchema.methods.updateAge = function(newAge) {
  if(newAge < 0) {
    throw new Error('Age cannot be negative');
  }
  this.age = newAge;
  return this.save();
};

// Usage
const user = await User.findOne({ name: 'Alice' });
await user.updateAge(26);

Comparison Between Static and Instance Methods

From the perspective of invocation, static methods are called through the model, while instance methods are called through document objects:

// Static method invocation
User.someStaticMethod();

// Instance method invocation
const user = new User();
user.someInstanceMethod();

From the scope of operation, static methods typically handle collection-level operations, while instance methods handle individual document operations:

// Static method handling multiple documents
userSchema.statics.adjustAllAges = async function(increment) {
  return this.updateMany({}, { $inc: { age: increment } });
};

// Instance method handling the current document
userSchema.methods.incrementAge = function() {
  this.age += 1;
  return this.save();
};

Combined Usage in Practical Applications

In real-world development, static and instance methods are often used together. For example, first querying documents with a static method and then processing them with instance methods:

// Define a static method to query active users
userSchema.statics.findActiveUsers = function() {
  return this.find({ isActive: true });
};

// Define an instance method to send notifications
userSchema.methods.sendNotification = function(message) {
  console.log(`Sending "${message}" to ${this.name}`);
};

// Combined usage
const activeUsers = await User.findActiveUsers();
activeUsers.forEach(user => user.sendNotification('New feature available!'));

Implementing Method Chaining

Through proper design, method chaining can be implemented to improve code readability:

userSchema.methods.setName = function(name) {
  this.name = name;
  return this; // Return 'this' to enable chaining
};

userSchema.methods.setAge = function(age) {
  this.age = age;
  return this;
};

// Chained invocation
const user = new User();
user.setName('Bob').setAge(30).save();

Handling Asynchronous Methods

Both static and instance methods can handle asynchronous operations:

// Asynchronous static method
userSchema.statics.findOrCreate = async function(conditions, defaults) {
  let user = await this.findOne(conditions);
  if(!user) {
    user = new this({ ...conditions, ...defaults });
    await user.save();
  }
  return user;
};

// Asynchronous instance method
userSchema.methods.checkAgeAsync = async function() {
  await someAsyncOperation();
  return this.age > 18;
};

Integration with Virtual Properties

Instance methods can be combined with virtual properties for more flexible data handling:

userSchema.virtual('nameWithAge').get(function() {
  return `${this.name} (${this.age})`;
});

userSchema.methods.logInfo = function() {
  console.log(`User: ${this.nameWithAge}`);
};

Application in Middleware

Both static and instance methods can be used in Mongoose middleware:

userSchema.pre('save', function(next) {
  // Using an instance method in a pre-save hook
  this.updateTimestamp();
  next();
});

userSchema.methods.updateTimestamp = function() {
  this.updatedAt = new Date();
};

Performance Considerations

Static methods are generally more efficient than instance methods, especially for batch operations:

// Efficient approach - static method for batch updates
userSchema.statics.incrementAllAges = function() {
  return this.updateMany({}, { $inc: { age: 1 } });
};

// Inefficient approach - using instance methods in a loop
userSchema.statics.incrementAllAgesSlow = async function() {
  const users = await this.find();
  for(const user of users) {
    user.age += 1;
    await user.save();
  }
};

Type Definitions and TypeScript Support

When using TypeScript, the types of static and instance methods can be explicitly defined:

interface IUserMethods {
  getInfo(): string;
  updateAge(newAge: number): Promise<void>;
}

interface UserModel extends mongoose.Model<IUser, {}, IUserMethods> {
  findByAge(age: number): Promise<IUser[]>;
  countByAgeRange(min: number, max: number): Promise<number>;
}

const userSchema = new mongoose.Schema<IUser, UserModel, IUserMethods>({
  name: String,
  age: Number
});

Common Errors and Debugging

When using these methods, be aware of common pitfalls:

1. Confusing the this context:

// Incorrect example - arrow functions change 'this' binding
userSchema.statics.findByName = (name) => {
  return this.find({ name }); // 'this' no longer points to the Model
};

// Correct approach
userSchema.statics.findByName = function(name) {
  return this.find({ name });
};

2. Forgetting to return a Promise:

// Incorrect example
userSchema.methods.saveAndLog = function() {
  this.save(); // No Promise returned
};

// Correct approach
userSchema.methods.saveAndLog = function() {
  return this.save();
};

Advanced Use Cases

For more complex applications, static and instance methods can be combined to implement domain-driven design:

// Static method as a factory method
userSchema.statics.createFromDTO = function(dto) {
  const user = new this();
  user.name = dto.fullName;
  user.age = calculateAge(dto.birthDate);
  return user;
};

// Instance method implementing business logic
userSchema.methods.applyDiscount = function() {
  if(this.age < 18 || this.age > 65) {
    this.discount = 0.2;
  }
  return this.save();
};

Testing Strategies

Different testing strategies apply to static and instance methods:

// Testing static methods
describe('User static methods', () => {
  it('should find users by age', async () => {
    await User.create({ name: 'Test', age: 30 });
    const users = await User.findByAge(30);
    expect(users).toHaveLength(1);
  });
});

// Testing instance methods
describe('User instance methods', () => {
  it('should update age correctly', async () => {
    const user = new User({ name: 'Test', age: 30 });
    await user.updateAge(31);
    expect(user.age).toBe(31);
  });
});

Integration with Mongoose Plugins

Static and instance methods can be encapsulated as Mongoose plugins for reuse:

function timestampPlugin(schema) {
  // Add a static method
  schema.statics.findRecent = function(days = 7) {
    const date = new Date();
    date.setDate(date.getDate() - days);
    return this.find({ createdAt: { $gte: date } });
  };

  // Add an instance method
  schema.methods.isRecent = function() {
    const weekAgo = new Date();
    weekAgo.setDate(weekAgo.getDate() - 7);
    return this.createdAt >= weekAgo;
  };
}

// Use the plugin
userSchema.plugin(timestampPlugin);