@memberjunction/core

Overview

The @memberjunction/core package is the foundation of the MemberJunction platform. It provides the essential entity model, business logic, and metadata handling that power the entire system. This package serves as the central building block for all other MemberJunction components.

Key Features

Entity object model
Metadata management
Business logic framework
Data validation
Change tracking
Event system
Security and permissions

Main Components

Entity Object Model

The Entity Object Model provides a structured way to work with business data:

BaseEntity Class

All entities in MemberJunction inherit from the BaseEntity class, which provides:

Standard CRUD operations
Change tracking
Validation
Permission checking
Event firing

// Example of using the BaseEntity class
import { BaseEntity } from '@memberjunction/core';

// Load an existing organization record
const org = await OrganizationEntity.load(123);

// Update properties
org.name = "New Organization Name";
org.website = "https://example.com";

// Save changes
await org.save();

Entity Metadata

Entity metadata defines the structure and behavior of entities:

// Example of entity metadata
{
  "name": "Organization",
  "displayName": "Organization",
  "description": "Represents a business organization",
  "schema": "dbo",
  "tableName": "Organizations",
  "primaryKey": "id",
  "fields": [...],
  "relationships": [...]
}

Metadata Registry

The Metadata Registry manages all metadata in the system:

Entity definitions
Field properties
Relationships
UI metadata
Validation rules

// Example of accessing metadata
import { MetadataRegistry } from '@memberjunction/core';

// Get metadata for an entity
const orgMetadata = MetadataRegistry.getEntityMetadata('Organization');

// Get field metadata
const nameField = orgMetadata.getField('name');

Business Logic Framework

The business logic framework enables custom logic implementation:

Subclass Registration

MemberJunction allows extending base entity classes with custom business logic:

import { RegisterClass, BaseEntity, ValidationResult } from '@memberjunction/core';

@RegisterClass('Organization')
export class CustomOrganizationEntity extends BaseEntity {
  // Override base methods
  async validate(): Promise<ValidationResult> {
    const result = await super.validate();
    
    // Add custom validation
    if (this.name && this.name.length < 3) {
      result.addError('name', 'Organization name must be at least 3 characters');
    }
    
    return result;
  }
  
  // Add custom methods
  async getRevenueAnalysis(): Promise<RevenueAnalysis> {
    // Custom business logic implementation
    return analysis;
  }
}

Business Rules

Business rules provide a way to define validation and calculation logic:

import { BusinessRule, EntityEvent } from '@memberjunction/core';

// Create a business rule that validates the organization name
const nameValidationRule = new BusinessRule({
  entity: 'Organization',
  event: EntityEvent.BeforeSave,
  description: 'Ensure organization name meets requirements',
  execute: async (entity) => {
    if (!entity.name || entity.name.length < 3) {
      return {
        isValid: false,
        errors: ['Organization name must be at least 3 characters']
      };
    }
    return { isValid: true };
  }
});

// Register the business rule
BusinessRuleRegistry.register(nameValidationRule);

Data Validation

The validation system ensures data integrity:

Field-level validation
Entity-level validation
Cross-field validation
Custom validation rules

// Example of validation
const validationResult = await entity.validate();
if (!validationResult.isValid) {
  console.error('Validation errors:', validationResult.errors);
}

Change Tracking

MemberJunction tracks changes to entity data:

Track modified fields
Track original values
Support for optimistic concurrency
Audit trail generation

// Example of change tracking
const entity = await OrganizationEntity.load(123);
entity.name = "New Name"; // This change is tracked

// Check if field has changed
if (entity.isFieldChanged('name')) {
  console.log('Original name:', entity.getOriginalValue('name'));
  console.log('New name:', entity.name);
}

Event System

The event system allows for hooking into entity lifecycle events:

BeforeLoad
AfterLoad
BeforeSave
AfterSave
BeforeDelete
AfterDelete

// Example of using events
import { EntityEventListener, EntityEvent } from '@memberjunction/core';

// Create an event listener
class OrganizationEventListener implements EntityEventListener {
  entityName = 'Organization';
  events = [EntityEvent.AfterSave];
  
  async handleEvent(event: EntityEvent, entity: BaseEntity): Promise<void> {
    if (event === EntityEvent.AfterSave) {
      console.log(`Organization ${entity.id} was saved`);
      // Perform additional actions
    }
  }
}

// Register the event listener
EntityEventManager.registerListener(new OrganizationEventListener());

Security and Permissions

The security system controls access to entities and fields:

Role-based access control
Entity-level permissions
Field-level security
Record-level security

// Example of checking permissions
import { SecurityManager } from '@memberjunction/core';

// Check if user can edit an entity
const canEdit = await SecurityManager.checkPermission(
  userId,
  'Organization',
  'Edit',
  entityId
);

// Check if user can access a field
const canAccessField = await SecurityManager.checkFieldAccess(
  userId,
  'Organization',
  'confidentialInfo',
  'Read'
);

Integration with Other Packages

The @memberjunction/core package is used by:

@memberjunction/graphql: For GraphQL API implementation
@memberjunction/ui: For UI components
@memberjunction/codegen: For code generation
@memberjunction/skip: For AI assistant integration

Usage Examples

Basic Entity Operations

// Import necessary components
import { EntityManager } from '@memberjunction/core';

// Get an entity manager instance
const entityManager = EntityManager.getInstance();

// Load an entity
const org = await entityManager.getEntity('Organization', 123);

// Update properties
org.name = "New Organization Name";

// Save changes
await org.save();

// Delete an entity
await org.delete();

Working with Collections

// Import necessary components
import { EntityManager, QueryOptions } from '@memberjunction/core';

// Get an entity manager instance
const entityManager = EntityManager.getInstance();

// Define query options
const options: QueryOptions = {
  filter: "state = 'CA'",
  sort: [{ field: 'name', direction: 'asc' }],
  page: 1,
  pageSize: 10
};

// Get a collection of entities
const organizations = await entityManager.getEntities('Organization', options);

// Work with the collection
for (const org of organizations.items) {
  console.log(org.name);
}

Creating New Entities

// Import necessary components
import { EntityManager } from '@memberjunction/core';

// Get an entity manager instance
const entityManager = EntityManager.getInstance();

// Create a new entity
const newOrg = entityManager.createEntity('Organization');

// Set properties
newOrg.name = "New Organization";
newOrg.website = "https://example.com";
newOrg.phone = "555-123-4567";

// Save the new entity
await newOrg.save();
console.log(`Created organization with ID: ${newOrg.id}`);

API Reference

The @memberjunction/core package provides a comprehensive API for working with entities and metadata. Key classes include:

BaseEntity: Base class for all entity objects
EntityManager: Manages entity instances
MetadataRegistry: Manages metadata
BusinessRuleRegistry: Manages business rules
EntityEventManager: Manages entity events
SecurityManager: Handles security and permissions
ValidationManager: Manages validation rules

For complete API documentation, refer to the generated TypeDoc documentation in the repository.