@memberjunction/core-entities

A comprehensive library of strongly-typed entity classes for MemberJunction's core metadata schema. This package provides type-safe access to all MemberJunction system entities with built-in validation, custom business logic, and seamless integration with the MemberJunction framework.

Overview

The @memberjunction/core-entities package contains:
- 178+ Generated Entity Classes: Strongly-typed TypeScript classes for all core MemberJunction entities
- Extended Entity Classes: Custom subclasses with specialized business logic
- Artifact Extraction System: Metadata-driven attribute extraction with hierarchical inheritance
- Resource Permission Engine: Comprehensive permission management system
- Zod Schema Validation: Built-in runtime validation for all entity types
- Type Definitions: Full TypeScript type definitions for enhanced IDE support

Installation

``bash
npm install @memberjunction/core-entities
`

Key Features

$3

`typescript
import { Metadata } from '@memberjunction/core';
import { UserEntity, ApplicationEntity } from '@memberjunction/core-entities';

// Always use Metadata to create entity instances
const md = new Metadata();

// Load a user by ID
const user = await md.GetEntityObject('Users');
await user.Load('user-id-here');

// Access strongly-typed properties
console.log(user.Email);
console.log(user.FirstName);

// Create a new application
const app = await md.GetEntityObject('Applications');
app.NewRecord();
app.Name = 'My New Application';
app.Description = 'A test application';
await app.Save();
`

(continuing in next command due to size...)

Artifact Extraction System

The artifact extraction system enables declarative extraction of structured attributes from artifact content with hierarchical inheritance.

$3

Artifacts in MemberJunction can have extract rules defined in their ArtifactType that specify how to extract attributes from the artifact content. These rules:
- Are stored as JSON in the ArtifactType.ExtractRules column
- Support hierarchical inheritance (child types inherit and override parent rules)
- Execute JavaScript code in a controlled environment
- Map extracted values to standard properties (name, description, display formats)
- Are automatically executed when artifact versions are saved

$3

Extract rules are defined in the ArtifactType.ExtractRules JSON field:

`json
[
{
"name": "subject",
"description": "Email subject line",
"type": "string",
"standardProperty": "name",
"extractor": "const parsed = JSON.parse(content); return parsed.subject || 'Untitled';"
},
{
"name": "recipientCount",
"description": "Number of recipients",
"type": "number",
"extractor": "const parsed = JSON.parse(content); return parsed.recipients?.length || 0;"
}
]
`

$3

| Property | Type | Description |
|----------|------|-------------|
| name | string | Unique identifier for this rule |
| description | string | Human-readable description |
| type | string | TypeScript type (e.g., 'string', 'Array<{x: number}>') |
| standardProperty | string? | Maps to: 'name', 'description', 'displayMarkdown', 'displayHtml' |
| extractor | string | JavaScript code that receives content and returns value |

$3

`typescript
import { ArtifactExtractor } from '@memberjunction/core-entities';

// Resolve extract rules with inheritance
const rules = ArtifactExtractor.ResolveExtractRules(artifactTypeChain);

// Extract attributes from content
const result = await ArtifactExtractor.ExtractAttributes({
content: artifactContent,
extractRules: rules,
throwOnError: false,
timeout: 5000
});

// Get standard properties
const name = ArtifactExtractor.GetStandardProperty(result.attributes, 'name');
const description = ArtifactExtractor.GetStandardProperty(result.attributes, 'description');
`

$3

`typescript
import { ArtifactVersionExtended } from '@memberjunction/core-entities';
import { Metadata } from '@memberjunction/core';

const md = new Metadata();
const version = await md.GetEntityObject('MJ: Artifact Versions');
version.NewRecord();
version.Content = JSON.stringify({ subject: "Q4 Campaign", body: "..." });

// Save triggers automatic extraction:
// 1. Calculates SHA-256 hash → ContentHash
// 2. Resolves extract rules from ArtifactType hierarchy
// 3. Extracts attributes → Name and Description
// 4. Creates ArtifactVersionAttribute records
await version.Save();

console.log(version.Name); // "Q4 Campaign" (extracted)
console.log(version.ContentHash); // "a3f7e2..." (SHA-256)
`

For complete documentation, see the Implementation Summary.

Best Practices

1. Always use Metadata for entity creation: Never instantiate entity classes directly
2. Use RunView for bulk operations: More efficient than loading entities individually
3. Leverage TypeScript types: Use exported types for function parameters
4. Handle validation errors: Wrap entity operations in try-catch blocks
5. Use extended classes: When available, use extended versions for additional functionality
6. Import artifacts from core-entities: Artifact extraction utilities are in this package

Dependencies

- @memberjunction/core: Core MemberJunction functionality
- @memberjunction/global: Global utilities and decorators
- zod`: Runtime type validation

License

ISC - See LICENSE file for details

Support

For issues, questions, or contributions, visit the MemberJunction GitHub repository.