Entity Model in MemberJunction

The Entity Model is one of the core architectural components of MemberJunction, providing the foundation for data representation, business logic, and data access. Understanding the Entity Model is essential for effectively developing with MemberJunction.

What is the Entity Model?

In MemberJunction, the Entity Model is a TypeScript-based object model that represents your data entities in a strongly-typed, object-oriented manner. It provides a layer of abstraction over your database tables, adding rich functionality for data manipulation, validation, and business logic.

The Entity Model consists of:

Entity Classes: TypeScript classes representing your data entities
Metadata: Descriptive information about entities and their properties
Relationships: Connections between entities
Data Access Layer: Methods for retrieving and manipulating data
Business Logic: Rules and behaviors associated with entities

Base Entity Model

All entities in MemberJunction inherit from a common base class called EntityBase. This class provides core functionality that is shared across all entities in the system.

EntityBase Class

The EntityBase class provides:

Property management
Change tracking
Validation
Event handling
Serialization/deserialization
Data access methods

Here's a simplified representation of the EntityBase class:

export abstract class EntityBase {
  // Core properties
  private _properties: Map<string, any>;
  private _originalValues: Map<string, any>;
  private _isDirty: boolean = false;
  private _isNew: boolean = true;
  private _validationErrors: ValidationError[] = [];
  
  // Core methods
  public getValue(propertyName: string): any;
  public setValue(propertyName: string, value: any): void;
  public isDirty(): boolean;
  public isNew(): boolean;
  public resetDirty(): void;
  public validate(): boolean;
  public addValidationError(propertyName: string, errorMessage: string): void;
  public getValidationErrors(): ValidationError[];
  public save(): Promise<boolean>;
  public delete(): Promise<boolean>;
  
  // Lifecycle hooks
  protected beforeSave(): Promise<boolean>;
  protected afterSave(): Promise<void>;
  protected beforeDelete(): Promise<boolean>;
  protected afterDelete(): Promise<void>;
}

Entity Class Structure

Each entity in MemberJunction is represented by a TypeScript class that inherits from EntityBase. Entity classes are typically generated by the CodeGen system based on metadata, but they can be extended with custom logic.

A typical entity class has:

Properties: Class fields representing the entity's attributes
Metadata Decorators: TypeScript decorators providing metadata
Navigation Properties: References to related entities
Methods: Entity-specific behaviors and operations

Example entity class:

@Entity('Member', 'dbo', 'Members')
export class Member extends EntityBase {
  // Properties
  @EntityProperty({ isPrimaryKey: true, isAutoIncrement: true })
  MemberID: number;

  @EntityProperty({ isRequired: true, maxLength: 100 })
  FirstName: string;

  @EntityProperty({ isRequired: true, maxLength: 100 })
  LastName: string;

  @EntityProperty({ isRequired: true, maxLength: 255 })
  Email: string;

  @EntityProperty({ foreignKey: 'FK_Members_MembershipTypes' })
  MembershipTypeID: number;

  // Navigation properties
  MembershipType?: MembershipType;

  // Custom methods
  getFullName(): string {
    return `${this.FirstName} ${this.LastName}`;
  }

  // Lifecycle hooks
  async beforeSave(): Promise<boolean> {
    // Custom validation logic
    if (!this.Email.includes('@')) {
      this.addValidationError('Email', 'Invalid email format');
      return false;
    }
    return super.beforeSave();
  }
}

Working with Entities

Creating Entities

You can create new entity instances using the entity manager:

// Get the entity manager
const entityManager = MJ.getEntityManager();

// Create a new member
const member = entityManager.createEntity('Member') as Member;
member.FirstName = 'John';
member.LastName = 'Doe';
member.Email = '[email protected]';
member.MembershipTypeID = 1;

// Save the entity
const saved = await member.save();
if (saved) {
  console.log(`Member saved with ID: ${member.MemberID}`);
} else {
  console.error('Failed to save member:', member.getValidationErrors());
}

Reading Entities

To load existing entities:

// Load a single entity by ID
const member = await entityManager.getEntityById('Member', 1) as Member;
console.log(`Loaded member: ${member.getFullName()}`);

// Query entities using a filter
const filters = [
  { fieldName: 'LastName', operator: 'eq', value: 'Doe' }
];
const members = await entityManager.getEntitiesWithFilter('Member', filters) as Member[];
console.log(`Found ${members.length} members with last name 'Doe'`);

Updating Entities

To update existing entities:

// Update an entity
member.Email = '[email protected]';

// Check if the entity is dirty (has changes)
if (member.isDirty()) {
  await member.save();
  console.log('Member updated successfully');
}

Deleting Entities

To delete entities:

// Delete an entity
const deleted = await member.delete();
if (deleted) {
  console.log('Member deleted successfully');
} else {
  console.error('Failed to delete member');
}

Working with Relationships

MemberJunction supports various types of entity relationships:

One-to-Many Relationships

// Load a member with related membership type
const member = await entityManager.getEntityById('Member', 1, ['MembershipType']) as Member;

// Access the related entity
console.log(`Membership type: ${member.MembershipType.Name}`);

Many-to-Many Relationships

// Load a member with related groups
const member = await entityManager.getEntityById('Member', 1, ['Groups']) as Member;

// Access the related entities
console.log(`Member belongs to ${member.Groups.length} groups`);
member.Groups.forEach(group => {
  console.log(`Group: ${group.Name}`);
});

Extending the Entity Model

MemberJunction uses a "subclass registration" pattern to allow for extending generated entity classes with custom business logic.

Subclass Registration Pattern

The subclass registration pattern allows you to:

Create a subclass that extends the generated entity class
Add custom properties and methods to the subclass
Register the subclass with the system
Have the system instantiate your subclass whenever an entity of that type is needed

Example subclass registration:

// Import the generated entity class
import { Member as MemberBase } from './generated/member.entity';
import { EntityRegister } from '@memberjunction/core';

// Create a subclass with custom logic
export class Member extends MemberBase {
  // Add custom properties
  get isActive(): boolean {
    return this.Status === 'Active';
  }

  // Add custom methods
  async deactivate(): Promise<boolean> {
    this.Status = 'Inactive';
    return await this.save();
  }

  // Override lifecycle hooks
  override async beforeSave(): Promise<boolean> {
    // Custom validation
    if (this.Email && !this.Email.includes('@')) {
      this.addValidationError('Email', 'Invalid email format');
      return false;
    }
    return await super.beforeSave();
  }
}

// Register the subclass
EntityRegister.registerEntity(Member);

Two-way Data Binding

MemberJunction supports two-way data binding between entity properties and UI components. This is achieved through:

Property Change Tracking: The entity model tracks changes to property values
Event System: Events are fired when property values change
UI Integration: UI components can bind to entity properties for automatic updates

Example of two-way binding:

// In your UI component
import { MJComponentBase } from '@memberjunction/ui-components';

export class MemberEditComponent extends MJComponentBase {
  member: Member;
  
  constructor() {
    super();
    // Load the member
    this.loadMember(1);
  }
  
  async loadMember(id: number) {
    const entityManager = MJ.getEntityManager();
    this.member = await entityManager.getEntityById('Member', id) as Member;
    
    // Bind to property changes
    this.member.onPropertyChanged('Email', (newValue, oldValue) => {
      console.log(`Email changed from ${oldValue} to ${newValue}`);
      // Update UI as needed
    });
  }
  
  // Update method called from UI
  updateEmail(newEmail: string) {
    this.member.Email = newEmail;
    // The entity tracks the change automatically
    console.log(`Is dirty: ${this.member.isDirty()}`);
  }
  
  async save() {
    if (this.member.isDirty()) {
      const saved = await this.member.save();
      if (saved) {
        console.log('Member saved successfully');
      } else {
        console.error('Validation errors:', this.member.getValidationErrors());
      }
    }
  }
}

Custom Business Logic

The Entity Model allows for implementing custom business logic in several ways:

Method Overrides

Override existing methods to add custom behavior:

export class Member extends MemberBase {
  // Override the base validation method
  override validate(): boolean {
    // Call the base validation first
    const isValid = super.validate();
    
    // Add custom validation
    if (this.FirstName === this.LastName) {
      this.addValidationError('LastName', 'Last name cannot be the same as first name');
      return false;
    }
    
    return isValid;
  }
}

Lifecycle Hooks

Implement lifecycle hooks to inject logic at specific points:

export class Member extends MemberBase {
  // Before saving
  override async beforeSave(): Promise<boolean> {
    // Custom logic before saving
    this.LastUpdatedDate = new Date();
    
    // Validate email format
    if (this.Email && !this.Email.includes('@')) {
      this.addValidationError('Email', 'Invalid email format');
      return false;
    }
    
    return await super.beforeSave();
  }
  
  // After saving
  override async afterSave(): Promise<void> {
    // Custom logic after successful save
    await this.notifyMemberUpdated();
    await super.afterSave();
  }
  
  // Custom notification method
  private async notifyMemberUpdated() {
    // Send notifications, update related data, etc.
    console.log(`Member ${this.MemberID} updated`);
  }
}

Domain-Specific Methods

Add methods that encapsulate domain logic:

export class Member extends MemberBase {
  // Domain-specific method
  async renewMembership(months: number): Promise<boolean> {
    // Get the current expiration date
    const currentExpiration = this.MembershipExpirationDate || new Date();
    
    // Calculate new expiration date
    const newExpiration = new Date(currentExpiration);
    newExpiration.setMonth(newExpiration.getMonth() + months);
    
    // Update the entity
    this.MembershipExpirationDate = newExpiration;
    this.LastRenewalDate = new Date();
    
    // Save the changes
    return await this.save();
  }
  
  // Check if membership is expired
  isMembershipExpired(): boolean {
    if (!this.MembershipExpirationDate) {
      return true;
    }
    
    return this.MembershipExpirationDate < new Date();
  }
}

AI Actions

MemberJunction supports AI-powered actions on entities through the Skip AI assistant. These actions can be defined as part of the entity model to provide AI capabilities specific to each entity type.

Defining AI Actions

AI actions are defined using decorators:

export class Member extends MemberBase {
  // AI action to summarize member activity
  @AIAction({
    name: 'summarizeMemberActivity',
    description: 'Generate a summary of member activity',
    parameters: [
      { name: 'timeframe', type: 'string', required: false, defaultValue: '30 days' }
    ]
  })
  async summarizeMemberActivity(timeframe: string = '30 days'): Promise<string> {
    // Fetch member activity data
    const activities = await this.getMemberActivities(timeframe);
    
    // Use Skip to generate a summary
    const skipAPI = MJ.getSkipAPI();
    const summary = await skipAPI.generateSummary({
      entityName: 'Member',
      entityId: this.MemberID,
      data: activities,
      prompt: `Summarize this member's activity over the past ${timeframe}`
    });
    
    return summary;
  }
  
  // Helper method to get member activities
  private async getMemberActivities(timeframe: string): Promise<any[]> {
    // Implementation to fetch activity data
    // ...
  }
}

Invoking AI Actions

AI actions can be invoked programmatically:

// Load a member
const member = await entityManager.getEntityById('Member', 1) as Member;

// Invoke the AI action
const summary = await member.summarizeMemberActivity('60 days');
console.log('Activity Summary:', summary);

Or through the Skip conversational interface:

User: "Summarize John Doe's activity for the last 90 days"
Skip: [Processes request and invokes the appropriate AI action]

Entity Model Best Practices

Design Principles

Single Responsibility: Each entity should represent a single concept
Domain-Driven Design: Model entities based on domain concepts, not database tables
Separation of Concerns: Keep data, validation, and business logic separate
Encapsulation: Hide implementation details behind well-defined interfaces

Performance Considerations

Lazy Loading: Use lazy loading for related entities to avoid unnecessary data retrieval
Batch Operations: Use batch operations for multiple entities
Selective Loading: Only load the properties and related entities you need
Caching: Leverage the entity cache for frequently accessed entities

Validation Best Practices

Centralized Validation: Implement validation in the entity model, not UI
Early Validation: Validate early to catch errors before saving
Consistent Messages: Use consistent error messages for similar validation issues
Contextual Validation: Consider validation context (e.g., create vs. update)

Security Best Practices

Permission Checking: Enforce permissions at the entity level
Field-Level Security: Implement field-level security for sensitive data
Audit Trails: Record changes to sensitive entities
Input Sanitization: Sanitize inputs before processing

Common Entity Model Patterns

Repository Pattern

MemberJunction implements the Repository pattern through its EntityManager:

// Repository-like methods in entity manager
const entityManager = MJ.getEntityManager();
const members = await entityManager.getEntitiesWithFilter('Member', filters);
const member = await entityManager.getEntityById('Member', 1);

Unit of Work Pattern

Track and commit multiple changes as a single operation:

// Start a unit of work
const unitOfWork = entityManager.createUnitOfWork();

// Make changes to multiple entities
const member = unitOfWork.getEntityById('Member', 1) as Member;
member.Email = '[email protected]';

const address = unitOfWork.getEntityById('Address', member.AddressID) as Address;
address.City = 'New City';

// Commit all changes as a single operation
const saved = await unitOfWork.commit();
if (saved) {
  console.log('All changes saved successfully');
} else {
  console.error('Failed to save changes');
}

Factory Pattern

Create entities with default values or complex initialization:

// Entity factory
class MemberFactory {
  static createNewMember(firstName: string, lastName: string, email: string): Member {
    const entityManager = MJ.getEntityManager();
    const member = entityManager.createEntity('Member') as Member;
    
    // Set properties
    member.FirstName = firstName;
    member.LastName = lastName;
    member.Email = email;
    
    // Set defaults
    member.Status = 'Active';
    member.MembershipTypeID = 1; // Default membership type
    member.JoinDate = new Date();
    member.MembershipExpirationDate = new Date();
    member.MembershipExpirationDate.setFullYear(
      member.MembershipExpirationDate.getFullYear() + 1
    );
    
    return member;
  }
}

// Usage
const newMember = MemberFactory.createNewMember('John', 'Doe', '[email protected]');
await newMember.save();