Entity Methods Support for Both Class-Based and defineEntity APIs

[vkouk]

Hi,
Love the direction MikroORM is heading! I'd like to propose adding entity methods support that works with both the decorator-based class entities and the new defineEntity API.

The Problem

Current State:

• Class-based entities can have instance methods, but large entities become bloated (500+ line files mixing schema and behavior)
• No clean way to organize methods into separate, testable classes
• The new defineEntity API has no method support at all
• Testing entity methods requires full ORM setup

What We Want:

• Organize entity behavior into separate, testable classes
• Keep entity definitions clean and focused on schema
• Support additional parameters naturally
• Maintain convenient entity.method() syntax
• Make methods pure functions that work outside entity context

Proposed Solution

Core Concept: First-Parameter Binding
Methods are defined as pure functions where the first parameter is the entity instance. MikroORM automatically binds this parameter when called on an entity.

API: For Class-Based Entities

// user-methods.ts
export class UserMethods {
  getFullName(user: User): string {
    return `${user.firstName} ${user.lastName}`;
  }
  
  calculateAge(user: User): number {
    return differenceInYears(new Date(), user.birthDate);
  }
  
  isEligibleForDiscount(user: User, minPurchase: number): boolean {
    return user.loyaltyPoints > 100 && minPurchase > 50;
  }
}

// user.entity.ts
@Entity('users', { methods: () => UserMethods })
export class User extends BaseEntity {
  @Property()
  firstName!: string;

  @Property()
  lastName!: string;

  @Property()
  birthDate!: Date;

  @Property()
  loyaltyPoints!: number;
  
  // Entity stays clean - just schema!
}

// Usage - entity is passed implicitly as first parameter
const user = await em.findOne(User, 1);
user.getFullName(); // Calls UserMethods.getFullName(user)
user.isEligibleForDiscount(100); // Calls UserMethods.isEligibleForDiscount(user, 100)
await user.sendEmail(mailerService, 'Welcome!');

Alternative: Multiple Method Classes

@Entity('users', { 
  methods:() => [UserBasicMethods, UserAuthMethods, UserNotificationMethods] 
})
export class User extends BaseEntity {
  // Methods from all classes are merged
}

API: For defineEntity

// user-methods.ts (same class!)
export class UserMethods {
  getFullName(user: User): string {
    return `${user.firstName} ${user.lastName}`;
  }
  
  calculateAge(user: User): number {
    return differenceInYears(new Date(), user.birthDate);
  }
  
  isEligibleForDiscount(user: User, minPurchase: number): boolean {
    return user.loyaltyPoints > 100 && minPurchase > 50;
  }
}

// user.entity.ts
export const User = defineEntity({
  name: 'User',
  tableName: 'users',
  properties: {
    firstName: { type: 'string' },
    lastName: { type: 'string' },
    birthDate: { type: 'date' },
    loyaltyPoints: { type: 'number' },
  },
  methods:() => [UserMethods] or UserMethods, // Same API!
});

// Usage - identical to class-based
const user = await em.findOne(User, 1);
user.getFullName(); // "John Doe"
user.isEligibleForDiscount(100); // true/false

Why First-Parameter Approach?

1. Pure Functions = Easy Testing

// Test without ORM, without entity instances
describe('UserMethods', () => {
  const methods = new UserMethods();
  
  it('calculates full name', () => {
    const mockUser = { firstName: 'John', lastName: 'Doe' } as User;
    expect(methods.getFullName(mockUser)).toBe('John Doe');
  });
  
  it('checks discount eligibility', () => {
    const mockUser = { loyaltyPoints: 150 } as User;
    expect(methods.isEligibleForDiscount(mockUser, 60)).toBe(true);
    expect(methods.isEligibleForDiscount(mockUser, 100)).toBe(false);
  });
});

2. Additional Parameters Work Naturally

class OrderMethods {
  calculateTotal(order: Order, taxRate: number, shippingCost: number): number {
    return (order.subtotal + shippingCost) * (1 + taxRate);
  }
}

// Clean, intuitive usage
order.calculateTotal(0.08, 10.99);

3. Reusable Across Contexts

// Use in services, reports, utilities - anywhere!
@Injectable()
export class ReportService {
  private userMethods = new UserMethods();
  
  generateReport(users: User[]) {
    return users.map(user => ({
      fullName: this.userMethods.getFullName(user),
      age: this.userMethods.calculateAge(user),
    }));
  }
}

4. Methods Can Reference Each Other

class UserMethods {
  isActive(user: User): boolean {
    return user.status === 'active' && !user.deletedAt;
  }
  
  canPurchase(user: User, amount: number): boolean {
    return this.isActive(user) && user.balance >= amount;
  }
}

Would love to hear thoughts from the community and maintainers!

[xcfox]

I prefer to use the simplest possible steps:

export const User = defineEntity({
  name: 'User',
  tableName: 'users',
  properties: {
    firstName: { type: 'string' },
    lastName: { type: 'string' },
    birthDate: { type: 'date' },
    loyaltyPoints: { type: 'number' },
  },
  methods: {
    getFullName: (user) => `${user.firstName} ${user.lastName}`,
    calculateAge: (user) => differenceInYears(new Date(), user.birthDate)
  },
});

If you want to declare methods for both Class-Based and defineEntity, you can promote the relevant methods:

const getFullName = (this: User) => `${user.firstName} ${user.lastName}`

const calculateAge = (this: User) => differenceInYears(new Date(), user.birthDate)

// in defineEntity
export const User = defineEntity({
  name: 'User',
  tableName: 'users',
  properties: {
    firstName: { type: 'string' },
    lastName: { type: 'string' },
    birthDate: { type: 'date' },
    loyaltyPoints: { type: 'number' },
  },
  methods: {
    getFullName,
    calculateAge
  },
});

// in Class-Based
@Entity('users', { methods: () => UserMethods })
export class User extends BaseEntity {
  @Property()
  firstName!: string;

  @Property()
  lastName!: string;

  @Property()
  birthDate!: Date;

  @Property()
  loyaltyPoints!: number;
  
  getFullName = getFullName
  calculateAge = calculateAge
}

[vkouk]

Thanks for the answer @xcfox

1. As per defineEntity, I would love to have the option to define either pure functions (ofc we must have the option to allow more params after the first one where is always the entity itself) but class based methods like my example.
2. For class based, methods: () => UserMethods it would be sufficient, I believe this

 getFullName = getFullName
  calculateAge = calculateAge

is obsolete. My opinion!

It could work behind the scenes, same as we have for repository (more or less).

[B4nan]

I don't like the idea of using pure functions for this either. Why would you want pure functions on the entity instance itself? The point of having entity methods is that they can use this to refer to the current entity, if you lose that, I don't see a reason to have such methods there.

Not to mention that I dont see how we could even implement what you are suggesting in the OP (especially on type level).

I also dont see why we would need some new way to add methods to the class-based entity definitions, let's not overcomplicate things.

The new defineEntity API has no method support at all

This is not true, you can use it with classes and define whatever methods you want, and they wont be pure, they will have correct this. And that is a good thing.

[vkouk]

I don't like the idea of using pure functions for this either. Why would you want pure functions on the entity instance itself? The point of having entity methods is that they can use this to refer to the current entity, if you lose that, I don't see a reason to have such methods there.

Not to mention that I dont see how we could even implement what you are suggesting in the OP (especially on type level).

I also dont see why we would need some new way to add methods to the class-based entity definitions, let's not overcomplicate things.

The new defineEntity API has no method support at all

This is not true, you can use it with classes and define whatever methods you want, and they wont be pure, they will have correct this. And that is a good thing.

Thanks for the answer. So, for define entity you say we can have something like:

class OrderBase extends BaseEntity {
   calculateTotal(taxRate: number, shippingCost: number): number {
    return (this.subtotal + shippingCost) * (1 + taxRate);
  }
}

----

const Order = defineEntity({
 class: OrderBase
});

Something like that?

[B4nan]

Yes, exactly that already works now. Of course, you do need to declare all the properties, not just methods.

methods: {
getFullName: (user) => ${user.firstName} ${user.lastName},
calculateAge: (user) => differenceInYears(new Date(), user.birthDate)
},

I do like this idea, since it would allow methods without defining your own class. And I would like to see a way to use the ORM base entity in a similar fashion (and generally speaking, better extension mechanism when you do not want to define custom class).

[vkouk]

Yes, exactly that already works now. Of course, you do need to declare all the properties, not just methods.

Yes this is what I wanted to avoid with the methods :D. If we could enhance the api of define entity to be able to apply supported methods (if applicable) as well as enhance the BaseEntity extension (my other proposal) that would be a great step moving forward 🚀

[B4nan]

This should now be possible with #7104: https://mikro-orm.io/docs/next/entity-schema#adding-custom-methods

The intellisense felt super slow, that should be hopefully improved in general with #7108