@memberjunction/codegen-lib

The code generation engine for the MemberJunction platform. This library transforms database schema metadata into a complete, type-safe, full-stack application: TypeScript entity classes with Zod validation, Angular form components, SQL stored procedures and views, GraphQL resolvers, Action subclasses, and Remote Operation typed bases (RemoteOperationGeneratorBase → remote_operations.ts, one BaseRemotableOperation subclass per MJ: Remote Operations row — Manual shells or complete AI/Default classes; see the Remote Operations Guide) -- all from a single mj codegen invocation.

Installation

npm install @memberjunction/codegen-lib
Copy

Overview

CodeGenLib sits at the center of MemberJunction's development workflow. When you change a database schema (add a table, alter a column, define a CHECK constraint), CodeGenLib detects those changes, updates internal metadata, and regenerates synchronized code across every layer of the stack. The result is guaranteed type safety from database to UI with zero manual boilerplate.

The library is designed for extensibility: every major generator is a base class that can be subclassed and registered via @RegisterClass to override or extend default behavior.

flowchart TD
    subgraph Input["Input Sources"]
        DB["SQL Server\nDatabase Schema"]
        CFG["mj.config.cjs\nConfiguration"]
        AI["AI Prompts\n(Advanced Generation)"]
    end

    subgraph Pipeline["CodeGen Pipeline"]
        META["Metadata\nManagement"]
        SQLGEN["SQL\nGeneration"]
        ENTITY["Entity Class\nGeneration"]
        ANGULAR["Angular\nGeneration"]
        GQL["GraphQL\nGeneration"]
        ACTION["Action\nGeneration"]
    end

    subgraph Output["Generated Outputs"]
        VIEWS["Views &\nStored Procedures"]
        TS["TypeScript Entity\nClasses + Zod"]
        NG["Angular Form\nComponents"]
        GQLR["GraphQL\nResolvers"]
        ACTS["Action\nSubclasses"]
        JSON["DB Schema\nJSON"]
    end

    DB --> META
    CFG --> META
    AI --> META

    META --> SQLGEN
    META --> ENTITY
    META --> ANGULAR
    META --> GQL
    META --> ACTION

    SQLGEN --> VIEWS
    ENTITY --> TS
    ANGULAR --> NG
    GQL --> GQLR
    ACTION --> ACTS
    META --> JSON

    style Input fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Pipeline fill:#7c5295,stroke:#563a6b,color:#fff
    style Output fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Authoring constraint: every SQL artifact CodeGen emits ships in a Flyway migration that customer databases will replay forever. The Publish-Then-No-Breaking-Changes Policy governs what schema changes are safe to feed into CodeGen: within a published OpenApp major version, only additive changes are allowed (new tables, new optional columns, widened types, new optional SP parameters). Dropping or renaming columns, narrowing types, and adding required parameters break historical migrations and require a major version bump.

Key Features

• Full-Stack Synchronization: A single schema change propagates to TypeScript entities, Angular forms, SQL procedures, and GraphQL resolvers automatically
• AI-Powered Intelligence: Uses AI prompts to translate CHECK constraints into Zod schemas, generate semantic form layouts, identify name fields, and create entity descriptions
• Extensible Architecture: Every generator (SQLCodeGenBase, EntitySubClassGeneratorBase, AngularClientGeneratorBase, etc.) can be subclassed and overridden via MJ's class factory
• Zod Validation Schemas: Generates Zod schemas from SQL CHECK constraints with proper union types and refinements
• Recursive Hierarchy Support: Automatically detects self-referential foreign keys and generates CTE-based Root{FieldName} columns in views
• Cascade Delete Generation: Produces cursor-based cascade delete procedures that call child entity stored procedures, respecting business logic at every level
• Force Regeneration: Surgically regenerate specific SQL objects for specific entities without requiring schema changes
• Class Registration Manifests: Prevents tree-shaking of @RegisterClass-decorated classes by generating static import manifests
• SQL Migration Logging: Outputs all generated SQL as Flyway-compatible migration files with schema placeholder support
• Configurable via Zod-Validated Config: All settings validated at startup through comprehensive Zod schemas with sensible defaults

Architecture

Pipeline Stages

The code generation process follows a well-defined pipeline orchestrated by the RunCodeGenBase class:

flowchart LR
    S0["BEFORE\nCommands"]
    S1["Metadata\nManagement"]
    S2["SQL Object\nGeneration"]
    S3["GraphQL\nResolvers"]
    S4["Entity\nSubclasses"]
    S5["Angular\nComponents"]
    S6["DB Schema\nJSON"]
    S7["Action\nSubclasses"]
    S8["Integrity\nChecks"]
    S9["AFTER\nCommands"]

    S0 --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9

    style S0 fill:#64748b,stroke:#475569,color:#fff
    style S1 fill:#2d6a9f,stroke:#1a4971,color:#fff
    style S2 fill:#2d6a9f,stroke:#1a4971,color:#fff
    style S3 fill:#7c5295,stroke:#563a6b,color:#fff
    style S4 fill:#7c5295,stroke:#563a6b,color:#fff
    style S5 fill:#7c5295,stroke:#563a6b,color:#fff
    style S6 fill:#7c5295,stroke:#563a6b,color:#fff
    style S7 fill:#7c5295,stroke:#563a6b,color:#fff
    style S8 fill:#b8762f,stroke:#8a5722,color:#fff
    style S9 fill:#64748b,stroke:#475569,color:#fff
Copy

Core vs Non-Core Entity Separation

CodeGen distinguishes between core MemberJunction entities (in the __mj schema) and application-specific entities. Each generator runs twice: once for core entities with output directed to @memberjunction/core-entities, and once for non-core entities with output directed to the application's generated packages. This separation ensures MJ framework code and application code stay independent.

Class Factory Extensibility

Every generator base class can be subclassed and registered with a higher priority to customize behavior:

classDiagram
    class RunCodeGenBase {
        +setupDataSource() SQLServerDataProvider
        +Run(skipDatabaseGeneration) void
    }

    class ManageMetadataBase {
        +manageMetadata(pool, user) boolean
        +loadGeneratedCode(pool, user) boolean
    }

    class SQLCodeGenBase {
        +manageSQLScriptsAndExecution(pool, entities, dir, user) boolean
        +runCustomSQLScripts(pool, when) boolean
    }

    class EntitySubClassGeneratorBase {
        +generateAllEntitySubClasses(pool, entities, dir, skipDB) boolean
    }

    class AngularClientGeneratorBase {
        +generateAngularCode(entities, dir, prefix, user) boolean
    }

    class GraphQLServerGeneratorBase {
        +generateGraphQLServerCode(entities, dir, lib, exclude) boolean
    }

    class ActionSubClassGeneratorBase {
        +generateActions(actions, dir) boolean
    }

    RunCodeGenBase --> ManageMetadataBase : creates via ClassFactory
    RunCodeGenBase --> SQLCodeGenBase : creates via ClassFactory
    RunCodeGenBase --> EntitySubClassGeneratorBase : creates via ClassFactory
    RunCodeGenBase --> AngularClientGeneratorBase : creates via ClassFactory
    RunCodeGenBase --> GraphQLServerGeneratorBase : creates via ClassFactory
    RunCodeGenBase --> ActionSubClassGeneratorBase : creates via ClassFactory

    style RunCodeGenBase fill:#2d6a9f,stroke:#1a4971,color:#fff
    style ManageMetadataBase fill:#7c5295,stroke:#563a6b,color:#fff
    style SQLCodeGenBase fill:#7c5295,stroke:#563a6b,color:#fff
    style EntitySubClassGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
    style AngularClientGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
    style GraphQLServerGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
    style ActionSubClassGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
Copy

To override any generator, subclass the base and register it:

import { RegisterClass } from '@memberjunction/global';
import { EntitySubClassGeneratorBase } from '@memberjunction/codegen-lib';

@RegisterClass(EntitySubClassGeneratorBase, undefined, 1) // priority 1 overrides default (0)
export class CustomEntityGenerator extends EntitySubClassGeneratorBase {
    // Override methods to customize generation
}
Copy

Usage

Running the Full Pipeline

import { RunCodeGenBase, initializeConfig } from '@memberjunction/codegen-lib';

// Initialize configuration from working directory
const config = initializeConfig(process.cwd());

// Run the complete code generation pipeline
const codeGen = new RunCodeGenBase();
await codeGen.Run();

// Or skip database operations for faster UI-only regeneration
await codeGen.Run(true);
Copy

The convenience function provides a simpler entry point:

import { runMemberJunctionCodeGeneration } from '@memberjunction/codegen-lib';

await runMemberJunctionCodeGeneration();
Copy

Using Individual Generators

Each generator can be used independently:

import { EntitySubClassGeneratorBase } from '@memberjunction/codegen-lib';
import { MJGlobal } from '@memberjunction/global';

const generator = MJGlobal.Instance.ClassFactory.CreateInstance<EntitySubClassGeneratorBase>(
    EntitySubClassGeneratorBase
);

await generator.generateAllEntitySubClasses(pool, entities, outputDir, false);
Copy

Generating Class Registration Manifests

The manifest generator prevents tree-shaking of @RegisterClass-decorated classes:

import { generateClassRegistrationsManifest } from '@memberjunction/codegen-lib';

const result = await generateClassRegistrationsManifest({
    outputPath: './src/generated/class-registrations-manifest.ts',
    appDir: './packages/MJAPI',
    excludePackages: ['@memberjunction'], // Use pre-built manifest for MJ packages
});

if (result.success) {
    console.log(`${result.packages.length} packages, ${result.classes.length} classes`);
}
Copy

See the Class Manifest Guide for comprehensive documentation on the manifest system.

Configuration

CodeGenLib uses cosmiconfig to locate configuration. The recommended approach is a mj.config.cjs file at the repository root:

module.exports = {
    // Database connection
    dbHost: 'localhost',
    dbPort: 1433,
    dbDatabase: 'YourDatabase',
    codeGenLogin: 'codegen_user',
    codeGenPassword: 'your_password',
    mjCoreSchema: '__mj',

    // Output directories for each generator
    output: [
        { type: 'SQL', directory: '../../SQL Scripts/generated' },
        { type: 'Angular', directory: '../MJExplorer/src/app/generated' },
        { type: 'GraphQLServer', directory: '../MJAPI/src/generated' },
        { type: 'CoreEntitySubclasses', directory: '../MJCoreEntities/src/generated' },
        { type: 'EntitySubclasses', directory: '../GeneratedEntities/src/generated' },
    ],

    // AI-powered features
    advancedGeneration: {
        enableAdvancedGeneration: true,
        features: [
            { name: 'SmartFieldIdentification', enabled: true },
            { name: 'FormLayoutGeneration', enabled: true },
            { name: 'ParseCheckConstraints', enabled: true },
            { name: 'TransitiveJoinIntelligence', enabled: true },
        ],
    },

    // SQL output for Flyway migrations
    SQLOutput: {
        enabled: true,
        folderPath: './migrations/v3/',
        convertCoreSchemaToFlywayMigrationFile: true,
    },

    // Force regeneration of specific objects
    forceRegeneration: {
        enabled: false,
        entityWhereClause: "SchemaName = 'dbo'",
        baseViews: true,
        spUpdate: true,
    },
};
Copy

All configuration is validated at startup using Zod schemas, with clear error messages for invalid settings. Environment variables (DB_HOST, DB_DATABASE, CODEGEN_DB_USERNAME, CODEGEN_DB_PASSWORD) provide fallback values for database connection settings.

Key Configuration Sections

Database Platform Selection (dbPlatform)

CodeGenLib accepts a single canonical dbPlatform field with two values:

// mj.config.cjs
module.exports = {
    dbPlatform: 'sqlserver',     // or 'postgresql'
    // …
};
Copy

The same vocabulary is used by @memberjunction/cli, @memberjunction/server, and every other MJ package that needs to branch on platform. There is one name (dbPlatform) and one pair of values ('sqlserver', 'postgresql') — no aliases ('mssql', 'postgres', 'pg') are recognized in config or env vars.

If dbPlatform is not set in mj.config.cjs, CodeGen reads DB_PLATFORM from the environment (restricted to the canonical pair) and falls back to 'sqlserver'. An unrecognized non-empty DB_PLATFORM value throws — silent fallback is the bug we don't want, because it routes the wrong provider at the wrong dialect against a real database.

Migration note (was dbType / DB_TYPE): Earlier dev builds of the PG support exposed both dbType (config key) and DB_TYPE (env var). Both have been replaced by dbPlatform / DB_PLATFORM with strict canonical values. Rename dbType: 'mssql' to dbPlatform: 'sqlserver' (and dbType: 'postgresql' to dbPlatform: 'postgresql') in your mj.config.cjs. Same for DB_TYPE=... in .env → DB_PLATFORM=.... Legacy aliases (mssql, postgres, pg) are no longer accepted in either.

Entity Naming Normalization

When CodeGen discovers new tables from legacy databases that use ALL CAPS naming conventions (e.g., PAYMENT, INDIVIDUALDESIGNATION), the entityNaming config section controls how those names are converted to human-readable entity and field names.

// In mj.config.cjs
module.exports = {
    entityNaming: {
        // Normalize ALL CAPS to Title Case: PAYMENT -> Payment
        normalizeAllCaps: true,        // default: true

        // Split compound words: INDIVIDUALDESIGNATION -> Individual Designation
        // Uses dictionary-based matching with backtracking
        splitCompoundWords: true,      // default: true

        // Apply same normalization to field/column names
        normalizeFieldNames: true,     // default: true

        // Additional domain-specific words for the compound word splitter
        additionalDomainWords: ['AutoCare', 'SKU', 'UPC'],
    },
};
Copy

Examples of normalization results:

The compound word splitter uses a built-in dictionary of ~500 common business/technical words, supplemented by known acronyms (ID, API, CRM, SQL, etc.) that stay uppercase. The additionalDomainWords config lets you add industry-specific terms for your database.

Schema Prefixes via additionalSchemaInfo

When using additionalSchemaInfo (typically generated by DBAutoDoc), the JSON file can include a Schemas array with entity name prefix/suffix recommendations:

{
    "Schemas": [
        { "name": "ACCOUNTING", "entityNamePrefix": "Accounting: ", "entityNameSuffix": "" },
        { "name": "CRM", "entityNamePrefix": "CRM: ", "entityNameSuffix": "" }
    ],
    "ACCOUNTING": [
        { "TableName": "PAYMENT", "PrimaryKey": [...], "ForeignKeys": [...] }
    ]
}
Copy

These prefixes are applied to SchemaInfo records during CodeGen, preventing entity name collisions across schemas (e.g., CRM: Categories vs Award: Categories instead of CATEGORYs__CRM). Config-file rules in newEntityDefaults.NameRulesBySchema still take priority.

What Gets Generated

TypeScript Entity Classes

From a SQL table with CHECK constraints, CodeGen produces a complete entity class:

// Auto-generated from database schema
export class AIPromptEntity extends BaseEntity {
    // Typed getter/setter for CHECK-constrained field
    get PromptRole(): 'System' | 'User' | 'Assistant' | 'SystemOrUser' {
        return this.Get('PromptRole');
    }
    set PromptRole(value: 'System' | 'User' | 'Assistant' | 'SystemOrUser') {
        this.Set('PromptRole', value);
    }

    // Zod validation from CHECK constraint
    validate(): ValidationResult {
        return this.validateWithZod(AIPromptSchema);
    }
}

// Zod schema with union types from CHECK constraint
export const AIPromptSchema = z.object({
    PromptRole: z.union([
        z.literal('System'),
        z.literal('User'),
        z.literal('Assistant'),
        z.literal('SystemOrUser'),
    ]),
    // ... all other fields
});
Copy

SQL Views with Recursive Hierarchy Support

For tables with self-referential foreign keys, CodeGen automatically generates recursive CTEs:

-- Auto-detected: Task.ParentTaskID references Task.ID
CREATE VIEW [vwTasks] AS
WITH CTE_RootParentTaskID AS (
    SELECT [ID], [ID] AS [RootParentTaskID]
    FROM [__mj].[Task]
    WHERE [ParentTaskID] IS NULL

    UNION ALL

    SELECT child.[ID], parent.[RootParentTaskID]
    FROM [__mj].[Task] child
    INNER JOIN CTE_RootParentTaskID parent
        ON child.[ParentTaskID] = parent.[ID]
)
SELECT t.*, cte.[RootParentTaskID]
FROM [__mj].[Task] AS t
LEFT OUTER JOIN CTE_RootParentTaskID cte ON t.[ID] = cte.[ID]
Copy

The CTE is zero-overhead: the SQL optimizer eliminates it entirely when the root column is not selected.

Angular Form Components

CodeGen creates production-ready Angular forms with AI-determined field categories and smart field types:

@Component({
    selector: 'mj-ai-prompt-form',
    template: `
        <mj-form-field [record]="record"
            FieldName="PromptRole"
            Type="dropdownlist"
            [EditMode]="EditMode">
        </mj-form-field>
    `
})
export class AIPromptFormComponent extends BaseFormComponent { }
Copy

Cascade Delete Procedures

Delete procedures use cursor-based stored procedure calls to respect business logic at every level of the hierarchy:

CREATE PROCEDURE [spDeleteOrder] @ID UNIQUEIDENTIFIER AS
BEGIN
    -- Cascade through child stored procedures
    DECLARE @ItemID UNIQUEIDENTIFIER
    DECLARE cascade_cursor CURSOR FOR
        SELECT [ID] FROM [OrderItems] WHERE [OrderID] = @ID

    OPEN cascade_cursor
    FETCH NEXT FROM cascade_cursor INTO @ItemID
    WHILE @@FETCH_STATUS = 0
    BEGIN
        EXEC [spDeleteOrderItem] @ItemID  -- Respects OrderItem's own cascade logic
        FETCH NEXT FROM cascade_cursor INTO @ItemID
    END
    CLOSE cascade_cursor
    DEALLOCATE cascade_cursor

    DELETE FROM [Orders] WHERE [ID] = @ID
END
Copy

AI-Powered Advanced Generation

When advancedGeneration.enableAdvancedGeneration is enabled, CodeGen uses AI prompts (stored in the database as AI Prompt entities) to enhance the generation process:

flowchart TD
    subgraph Features["AI-Powered Features"]
        SF["Smart Field\nIdentification"]
        FL["Form Layout\nGeneration"]
        CC["CHECK Constraint\nParsing"]
        ED["Entity\nDescriptions"]
        TJ["Transitive Join\nIntelligence"]
        EN["Entity Name\nGeneration"]
    end

    subgraph Results["What AI Determines"]
        SF --> R1["Name fields, Default-in-View\nfields, Searchable fields"]
        FL --> R2["Field categories, Icons\nDisplay names, Extended types"]
        CC --> R3["Zod schemas, Validation\nfunctions, Descriptions"]
        ED --> R4["Entity descriptions\nfor new entities"]
        TJ --> R5["Junction table detection\nMany-to-many relationships"]
        EN --> R6["Human-friendly entity\nnames from table names"]
    end

    style Features fill:#7c5295,stroke:#563a6b,color:#fff
    style Results fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Name Field Rules (Single Winner)

SmartFieldIdentification may propose several ranked name-field candidates (e.g. FirstName, LastName), but MemberJunction metadata supports exactly one IsNameField per entity — EntityInfo.NameField, the base-view FK-name virtual columns, and RelatedEntityNameFieldMap resolution all assume a single winner. CodeGen enforces this:

• Eligibility — a name field must be bounded text on the base table. Primary keys, uniqueidentifiers, non-text types, MAX text, and virtual (view-only) fields are rejected.
• Stability — an entity that already has exactly one valid IsNameField keeps it; AI proposals never move an established winner.
• Repair — when multiple fields are flagged (historical accumulation), the field literally named Name wins, else the first eligible flagged field in sequence order. All other auto-updatable flags are cleared.
• Fresh pick — when nothing valid is flagged, the first eligible AI candidate wins.
• Pinning — fields with AutoUpdateIsNameField = 0 are never set or cleared by CodeGen; EntityInfo.NameField's literal-Name preference arbitrates at runtime if a pinned conflict exists.

Why this matters: with multiple flags, the FK-name pick silently drifted between CodeGen runs as flags accumulated (observed: a related entity's name column flipping from one field to another, reshaping every view that joins to it).

Form Layout Stability Guarantees

The form layout system enforces stability to prevent unnecessary churn:

• Existing category names and icons are never changed by AI
• AI can assign fields to existing categories or create categories for genuinely new field groups
• Existing fields cannot be moved to newly created categories (prevents renaming)
• Per-field AutoUpdateCategory and AutoUpdateDisplayName flags provide granular control

Force Regeneration

Regenerate specific SQL objects without schema changes using surgical filtering:

// In mj.config.cjs
forceRegeneration: {
    enabled: true,
    // Filter to specific entities
    entityWhereClause: "SchemaName = 'CRM' AND __mj_UpdatedAt >= '2025-06-24'",
    // Control which object types regenerate
    baseViews: true,
    spCreate: false,
    spUpdate: true,
    spDelete: false,
    indexes: true,
}
Copy

Only the intersection of matched entities and enabled object types gets regenerated.

SQL Migration Logging

All SQL generated during metadata management and object generation is logged to a Flyway-compatible migration file. The SQLOutput configuration controls this behavior:

SQLOutput: {
    enabled: true,
    folderPath: './migrations/v3/',
    appendToFile: true,
    convertCoreSchemaToFlywayMigrationFile: true,
    schemaPlaceholders: [
        { schema: '__mj', placeholder: '${flyway:defaultSchema}' },
    ],
}
Copy

The SQLLogging class accumulates all SQL statements during a run and writes them as a single migration file with schema names replaced by Flyway placeholders.

Source Structure

src/
  index.ts                          # Public API exports
  runCodeGen.ts                     # RunCodeGenBase - main pipeline orchestrator

  Config/
    config.ts                       # Zod-validated configuration schemas and loaders
    db-connection.ts                # SQL Server connection pool management

  Database/
    manage-metadata.ts              # ManageMetadataBase - schema analysis and metadata sync
    sql_codegen.ts                  # SQLCodeGenBase - views, procedures, indexes, permissions
    sql.ts                          # SQLUtilityBase - SQL file management and execution
    dbSchema.ts                     # DBSchemaGeneratorBase - JSON schema export
    reorder-columns.ts              # Table column reordering utilities

  Angular/
    angular-codegen.ts              # AngularClientGeneratorBase - form and module generation
    related-entity-components.ts    # Base classes for related entity display components
    entity-data-grid-related-entity-component.ts  # Data grid component generator
    join-grid-related-entity-component.ts         # Join grid component generator
    timeline-related-entity-component.ts          # Timeline component generator

  Misc/
    entity_subclasses_codegen.ts    # EntitySubClassGeneratorBase - TypeScript entity generation
    action_subclasses_codegen.ts    # ActionSubClassGeneratorBase - Action class generation
    graphql_server_codegen.ts       # GraphQLServerGeneratorBase - resolver generation
    advanced_generation.ts          # AdvancedGeneration - AI-powered enhancement features
    status_logging.ts               # Spinner and log utilities (ora-based)
    sql_logging.ts                  # SQLLogging - migration file accumulator
    system_integrity.ts             # SystemIntegrityBase - post-generation validation
    createNewUser.ts                # CreateNewUserBase - initial user setup
    runCommand.ts                   # RunCommandsBase - shell command execution
    util.ts                         # File system and sorting utilities

  Manifest/
    GenerateClassRegistrationsManifest.ts  # Tree-shaking prevention manifest generator
Copy

API Reference

RunCodeGenBase

The main orchestrator class. Creates instances of all generator classes via MJGlobal.ClassFactory and runs the pipeline.

ManageMetadataBase

Analyzes database schema changes and updates MJ metadata tables.

SQLCodeGenBase

Generates database objects: views, stored procedures, indexes, and permissions. Delegates platform-specific SQL generation to CodeGenDatabaseProvider implementations (see below).

CodeGenDatabaseProvider (Database Abstraction Layer)

The CodeGenDatabaseProvider is the abstract base class that encapsulates all database-specific SQL generation for CodeGen. It has 55 abstract methods organized into categories that each platform provider must implement:

Built-in Implementations

Providers are registered via @RegisterClass(CodeGenDatabaseProvider, 'ProviderName') and selected at runtime based on the configured database platform.

Adding a New Database Backend

To add support for a new database (e.g., MySQL, Oracle):

1. Create a provider class extending CodeGenDatabaseProvider
2. Implement all 55 abstract methods with platform-native SQL
3. Create a SQLDialect subclass in @memberjunction/sql-dialect for identifier quoting, type mapping, etc.
4. Register with @RegisterClass so CodeGen discovers it at runtime
5. Create a data provider implementing DatabaseProviderBase from @memberjunction/core

import { RegisterClass } from '@memberjunction/global';
import { CodeGenDatabaseProvider } from '@memberjunction/codegen-lib';

@RegisterClass(CodeGenDatabaseProvider, 'MySQLCodeGenProvider')
export class MySQLCodeGenProvider extends CodeGenDatabaseProvider {
    get PlatformKey(): string { return 'mysql'; }
    get Dialect(): SQLDialect { return new MySQLDialect(); }

    generateDropGuard(objectType, schema, name): string {
        return `DROP ${objectType} IF EXISTS ${schema}.\`${name}\`;`;
    }
    // ... implement remaining 53 abstract methods
}
Copy

The PostgreSQL provider in @memberjunction/postgresql-dataprovider serves as the reference implementation for adding new backends.

EntitySubClassGeneratorBase

Generates TypeScript entity classes with Zod validation.

AngularClientGeneratorBase

Generates Angular form components, section components, and Angular modules.

GraphQLServerGeneratorBase

Generates TypeGraphQL resolver and type definitions.

generateClassRegistrationsManifest

Generates an import manifest that prevents tree-shaking of @RegisterClass decorated classes. See the Class Manifest Guide for full documentation.

Configuration Functions

Dependencies

This package depends on:

• @memberjunction/core - Entity framework, metadata system, and type utilities
• @memberjunction/core-entities - Generated entity classes for MJ system entities
• @memberjunction/global - @RegisterClass decorator and MJGlobal.ClassFactory
• @memberjunction/sql-dialect - Abstract SQL dialect layer for multi-database support
• @memberjunction/sqlserver-dataprovider - SQL Server data provider and connection management
• @memberjunction/ai - AI provider abstraction layer
• @memberjunction/ai-prompts - AI prompt execution for advanced generation features
• @memberjunction/ai-core-plus - AI prompt parameter types
• @memberjunction/aiengine - AI engine for model and prompt configuration
• @memberjunction/actions - Action engine for action code generation
• @memberjunction/actions-base - Action base classes and types
• @memberjunction/config - Configuration merging utilities
• @memberjunction/server-bootstrap-lite - Pre-built class registration manifest

Related Packages

• @memberjunction/cli - CLI that invokes CodeGenLib (mj codegen commands)
• @memberjunction/core-entities - Contains the generated entity_subclasses.ts output
• @memberjunction/server-bootstrap - Ships pre-built server-side class manifest
• @memberjunction/ng-bootstrap - Ships pre-built Angular class manifest

Documentation

• Multi-Database Workflow - How migrations and CodeGen work together to support SQL Server, PostgreSQL, and future database backends
• Class Manifest Guide - Comprehensive guide to the manifest system for preventing tree-shaking of @RegisterClass classes
• EXAMPLE_MANIFEST_MJAPI.md - Example server-side manifest (54 packages, 715 classes)
• EXAMPLE_MANIFEST_MJEXPLORER.md - Example client-side manifest (17 packages, 721 classes)

IS-A Type Relationships in CodeGen

MemberJunction supports IS-A (inheritance) relationships between entities, where one entity extends another by adding additional fields while inheriting the parent's schema. CodeGen automatically handles IS-A relationships with specialized generation logic.

For comprehensive conceptual documentation, see the IS-A Relationships Guide in MJCore.

How CodeGen Handles IS-A Entities

When an entity has a ParentEntity relationship (IS-A child):

1. SQL View Generation - Parent JOINs

Child views automatically JOIN to parent views to provide a complete record with all inherited fields:

-- CodeGen automatically generates:
CREATE VIEW [vwEmployee]
AS
SELECT
    e.*,               -- All Employee fields
    p.FirstName,       -- Inherited from Person
    p.LastName,        -- Inherited from Person
    p.DateOfBirth      -- Inherited from Person
FROM
    [__mj].[Employee] AS e
INNER JOIN
    [__mj].[vwPerson] AS p ON e.[ID] = p.[ID]
Copy

This ensures querying the child view returns a complete record including all parent fields.

2. Stored Procedure Generation - Child Fields Only

Create and Update procedures only include the child's own fields, not parent fields:

-- spCreateEmployee only has Employee-specific parameters
CREATE PROCEDURE [spCreateEmployee]
    @ID uniqueidentifier,
    @EmployeeNumber nvarchar(50),
    @HireDate date,
    @Salary decimal(18,2)
    -- No FirstName, LastName (those are Person fields)
AS BEGIN
    -- Only inserts into Employee table
    INSERT INTO [__mj].[Employee] (ID, EmployeeNumber, HireDate, Salary)
    VALUES (@ID, @EmployeeNumber, @HireDate, @Salary)
END
Copy

Why this design? When creating an Employee, you first create the Person record (which gets an ID), then use that same ID to create the Employee record. The stored procedures reflect this two-step creation pattern.

3. GraphQL Schema Generation - Complete Field Set

GraphQL input types include ALL fields (parent + child) for seamless API usage:

input CreateEmployeeInput {
  # Parent fields (from Person)
  firstName: String!
  lastName: String!
  dateOfBirth: Date

  # Child fields (from Employee)
  employeeNumber: String!
  hireDate: Date!
  salary: Decimal!
}
Copy

This provides a convenient single-operation API while the resolver handles the underlying two-step creation.

4. TypeScript Entity Classes - JSDoc Annotations

Generated entity classes include JSDoc annotations on getter/setter methods to indicate IS-A relationships:

export class EmployeeEntity extends BaseEntity {
  /**
   * Inherited from Person entity
   */
  get FirstName(): string {
    return this.Get('FirstName');
  }

  set FirstName(value: string) {
    this.Set('FirstName', value);
  }

  // Own fields have no annotation
  get EmployeeNumber(): string {
    return this.Get('EmployeeNumber');
  }
}
Copy

5. EntityField Metadata Synchronization

manageEntityFields() respects IS-A hierarchy when syncing field metadata:

• Fields from parent entities are NOT duplicated in child entity metadata
• Only the child's own fields appear in EntityField for the child entity
• RelatedEntityID and field relationships are preserved across the hierarchy
• Prevents metadata pollution from inherited fields

Configuration in Database Metadata

IS-A relationships are defined in the Entity table:

-- Person is the base entity
INSERT INTO Entity (ID, ParentEntity, Name)
VALUES (NEWID(), NULL, 'Person')

-- Employee IS-A Person
INSERT INTO Entity (ID, ParentEntity, Name)
VALUES (NEWID(), 'Person', 'Employee')
Copy

CodeGen detects the ParentEntity relationship and applies the specialized generation logic automatically.

Use Cases for IS-A Relationships

Common scenarios where IS-A relationships improve your schema:

• Person → Employee, Customer, Vendor - Shared contact information with role-specific fields
• Document → Invoice, PurchaseOrder, Contract - Common document metadata with type-specific data
• Product → PhysicalProduct, DigitalProduct - Shared catalog info with delivery-specific fields
• Communication → Email, SMS, PhoneCall - Common tracking with channel-specific metadata

Best Practices

1. Keep hierarchies shallow - One or two levels is ideal (Person → Employee, not Person → Worker → Employee)
2. Parent entities should be meaningful - Don't create artificial base classes just for inheritance
3. Child fields should be truly specific - If a field applies to all children, put it in the parent
4. ID management is manual - When creating child records, explicitly use the parent's ID

Virtual Entity Support

MemberJunction supports virtual entities - entities backed by database views instead of tables. Virtual entities enable read-only access to complex queries, external data sources, or denormalized views while maintaining the full MemberJunction metadata and API experience.

For comprehensive conceptual documentation, see the Virtual Entities Guide in MJCore.

Configuration-Driven Virtual Entity Creation

Virtual entities are defined in database-metadata-config.json under the VirtualEntities array:

{
  "VirtualEntities": [
    {
      "ViewName": "vwSalesSummary",
      "EntityName": "Sales Summary",
      "SchemaName": "__mj",
      "Description": "Aggregated sales data by region and period",
      "PrimaryKey": ["SummaryID"],
      "ForeignKeys": [
        {
          "FieldName": "RegionID",
          "SchemaName": "__mj",
          "RelatedTable": "Region",
          "RelatedField": "ID",
          "Description": "FK to Region table"
        }
      ]
    }
  ]
}
Copy

Key Configuration Properties

• ViewName: The SQL view name (must already exist in the database)
• EntityName: The MemberJunction entity name (appears in metadata, UI, APIs)
• SchemaName: Database schema (typically __mj for core entities)
• Description: Entity description for metadata and documentation
• PrimaryKey: Array of column names forming the primary key (supports composite keys)
• ForeignKeys: Optional array of foreign key relationships to other entities (if omitted, LLM decoration discovers them)

CodeGen Pipeline for Virtual Entities

CodeGen processes virtual entities through several specialized steps:

1. processVirtualEntityConfig() - Entity Creation

Reads the VirtualEntities configuration and calls spCreateVirtualEntity for each entry:

// CodeGen calls this stored procedure for each virtual entity
EXEC spCreateVirtualEntity
    @Name = 'Sales Summary',
    @SchemaName = '__mj',
    @BaseView = 'vwSalesSummary',
    @Description = 'Aggregated sales data...',
    @PrimaryKeyColumnName = 'SummaryID'
Copy

This creates the Entity metadata record with VirtualEntity = 1.

2. manageVirtualEntities() - Field Synchronization

Scans sys.columns on the virtual entity's view and creates EntityField metadata for each column:

• Automatically detects data types, nullability, and max lengths
• Creates EntityField records for all view columns
• Updates existing fields if column definitions change
• Marks fields as IsVirtual = 1 in metadata

// CodeGen inspects the view schema
SELECT
    c.name,
    t.name AS TypeName,
    c.max_length,
    c.is_nullable
FROM
    sys.columns c
INNER JOIN
    sys.types t ON c.user_type_id = t.user_type_id
WHERE
    object_id = OBJECT_ID('__mj.vwSalesSummary')
Copy

3. applySoftPKFKConfig() - Explicit Relationship Overrides

Applies the primaryKeyColumnName and foreignKeyDefinitions from the config:

// Sets the primary key field
UPDATE EntityField
SET IsPrimaryKey = 1
WHERE EntityID = @VirtualEntityID
  AND Name = 'SummaryID'

// Creates foreign key relationships
INSERT INTO EntityRelationship (...)
SELECT ... FROM foreignKeyDefinitions
Copy

Why explicit FK definitions? Views don't have database-level foreign keys, so CodeGen can't detect relationships automatically. The config provides this metadata.

4. LLM-Assisted Field Decoration (Advanced Feature)

The decorateVirtualEntitiesWithLLM() pipeline step uses AI to enhance virtual entity field metadata:

import { AIPromptRunner } from '@memberjunction/ai-prompts';

// CodeGen calls a database-driven prompt to decorate fields
const promptParams = new AIPromptParams();
promptParams.prompt = 'Decorate Virtual Entity Fields';
promptParams.data = {
    entityName: 'Sales Summary',
    viewDefinition: viewSQL,
    existingFields: fieldsFromMetadata
};

const runner = new AIPromptRunner();
const result = await runner.ExecutePrompt(promptParams);
Copy

The LLM analyzes the view definition and provides:

• Display names - User-friendly field labels (e.g., TotalRevenue → "Total Revenue")
• Descriptions - Field-level documentation explaining what each column represents
• Category assignments - Semantic grouping for form layouts
• DefaultInView flags - Recommended visibility settings for grid displays

This is controlled by the VirtualEntityFieldDecoration feature in the Advanced Generation Features configuration.

Virtual Entity Metadata Structure

After CodeGen processing, virtual entities have complete metadata:

-- Entity record
SELECT * FROM Entity WHERE Name = 'Sales Summary'
-- VirtualEntity = 1, BaseView = 'vwSalesSummary'

-- EntityField records (auto-detected from view)
SELECT * FROM EntityField WHERE EntityID = @SalesEntityID
-- Name, Type, Description, IsVirtual = 1

-- EntityRelationship records (from config)
SELECT * FROM EntityRelationship WHERE EntityID = @SalesEntityID
-- Foreign keys defined in foreignKeyDefinitions
Copy

Generated Code for Virtual Entities

Virtual entities generate the same TypeScript, GraphQL, and Angular code as table-based entities:

TypeScript Entity Class:

export class SalesSummaryEntity extends BaseEntity {
  get SummaryID(): string {
    return this.Get('SummaryID');
  }

  get RegionID(): string {
    return this.Get('RegionID');
  }

  get TotalRevenue(): number {
    return this.Get('TotalRevenue');
  }

  // Save/Delete methods throw errors (read-only entity)
}
Copy

GraphQL Schema:

type SalesSummary {
  summaryID: ID!
  regionID: ID!
  region: Region    # Auto-resolved from FK definition
  totalRevenue: Float!
}

type Query {
  SalesSummaries(filter: String): [SalesSummary!]!
}
Copy

Angular Form:

<mj-form-field
    [record]="record"
    FieldName="TotalRevenue"
    Type="textbox"
    [ReadOnly]="true"  <!-- Virtual entities are read-only -->
></mj-form-field>
Copy

Virtual Entity Limitations

Virtual entities are read-only by design:

• No spCreate, spUpdate, or spDelete procedures generated
• AllowCreateAPI, AllowUpdateAPI, AllowDeleteAPI set to 0 in metadata
• Entity class Save() and Delete() methods throw errors
• GraphQL mutations not generated for virtual entities
• Angular forms display in read-only mode

Advanced Generation Features Configuration

Virtual entity LLM decoration is controlled in the advancedGeneration.features array in mj.config.cjs:

advancedGeneration: {
    enableAdvancedGeneration: true,
    features: [
        {
            name: 'VirtualEntityFieldDecoration',
            enabled: true,
            // Optional: force re-decoration even if entities already have soft PK/FK annotations
            options: [{ name: 'forceRegenerate', value: true }],
        },
    ],
},
Copy

By default, VirtualEntityFieldDecoration is enabled and uses an idempotency check — entities that already have IsSoftPrimaryKey or IsSoftForeignKey annotations are skipped. Set the forceRegenerate option to true to override this check and re-run LLM decoration for all virtual entities (useful after prompt improvements or when you want to refresh metadata).

When active, CodeGen calls decorateVirtualEntitiesWithLLM() after field synchronization.

Use Cases for Virtual Entities

Virtual entities excel at:

• Reporting and Analytics - Pre-aggregated views for dashboards (sales summaries, usage metrics)
• External Data Sources - Linked server views, API-backed views, federated queries
• Denormalized Views - Flattened data for grid displays without JOIN overhead
• Legacy System Integration - Expose legacy tables through normalized MJ entity layer
• Calculated Fields - Complex computed columns not suitable for table storage
• Security Views - Row-level security via filtered views with full MJ API access

Best Practices

1. View must exist first - Create the SQL view before running CodeGen with virtual entity config
2. Primary key is required - Views must have a unique identifier column
3. Use meaningful names - entityName appears throughout UI and APIs
4. Document foreign keys - Explicit FK definitions enable relationship navigation
5. Enable LLM decoration - Let AI generate field descriptions for better UX
6. Keep views simple - Complex views with subqueries may have performance issues
7. Test read operations - Verify grid displays and API queries perform acceptably

Contributing

See the MemberJunction Contributing Guide for development setup and guidelines.

When contributing to CodeGenLib:

1. All generator base classes use the class factory pattern -- always subclass and register rather than modifying base classes directly
2. Generated SQL must be valid for the target database platform and produce valid Flyway migration output
3. Generated TypeScript must compile without errors and follow MJ naming conventions (PascalCase public members)
4. AI-powered features must enforce stability guarantees (existing categories and icons are never changed)

CLI Usage Guide

CodeGen is invoked through the MemberJunction CLI (mj command). Two subcommands are available:

mj codegen — Full Code Generation Pipeline

Runs the complete pipeline: database schema analysis, metadata sync, and code generation across all layers.

# Run the full pipeline (most common usage)
mj codegen

# Skip database operations, only regenerate code files from existing metadata
mj codegen --skipdb
Copy

Verbose Mode

Verbose output is controlled via mj.config.cjs (not a CLI flag):

module.exports = {
    verboseOutput: true,  // Enable detailed logging during code generation
};
Copy

When enabled, you see additional detail about each pipeline stage including per-entity processing, AI prompt calls, and SQL statement execution.

mj codegen manifest — Class Registration Manifest

Generates a TypeScript manifest file that prevents modern bundlers (ESBuild, Vite) from tree-shaking @RegisterClass-decorated classes.

# Generate manifest with defaults
mj codegen manifest

# Generate for a specific app, excluding MJ packages
mj codegen manifest --appDir ./packages/MJAPI \
  --output ./packages/MJAPI/src/generated/class-registrations-manifest.ts \
  --exclude-packages @memberjunction

# Only include classes extending specific base classes
mj codegen manifest --filter BaseEngine --filter BaseAction --verbose
Copy

Example Workflows

First-Time Setup

# 1. Configure database connection in mj.config.cjs
# 2. Run the full pipeline
mj codegen

# 3. Generated output lands in directories specified in mj.config.cjs:
#    - TypeScript entities  → packages/GeneratedEntities/src/generated/
#    - Angular forms        → packages/MJExplorer/src/app/generated/
#    - GraphQL resolvers    → packages/MJAPI/src/generated/
#    - SQL migration file   → migrations/v3/
Copy

After Schema Changes

# CodeGen detects schema changes automatically
mj codegen

# Review the generated Flyway migration file
ls -la migrations/v3/CodeGen_Run_*.sql
Copy

Regenerating Code Only (No DB Changes)

# Skip database operations for a faster run
mj codegen --skipdb
Copy

Forcing Regeneration of Specific Entities

Use forceRegeneration in mj.config.cjs:

module.exports = {
    forceRegeneration: {
        enabled: true,
        entityWhereClause: "SchemaName = 'CRM' AND Name LIKE 'Customer%'",
        baseViews: true,
        spUpdate: true,
    },
};
Copy

Then run mj codegen. Set enabled: false afterward to avoid unnecessary work on future runs.

Troubleshooting

Database Connection Failures

Symptom: CodeGen fails immediately with a connection error or timeout.

Common fixes:

1. Wrong credentials — Verify dbHost, dbDatabase, codeGenLogin, and codeGenPassword in mj.config.cjs. Environment variables DB_HOST, DB_DATABASE, CODEGEN_DB_USERNAME, CODEGEN_DB_PASSWORD serve as fallbacks.

2. Named instance — If using a named instance (e.g., localhost\SQLEXPRESS), set dbInstanceName in config.

3. Certificate trust — For self-signed certificates, set dbTrustServerCertificate: true.

Missing Output Directories

Symptom: ENOENT errors when writing generated files.

Fix: Ensure all directories listed in the output array of mj.config.cjs exist. CodeGen does not create parent directories automatically.

Entity Relationship Errors

Common causes:

1. Missing referenced tables — If a foreign key references a table excluded via excludeSchemas or excludeTables, either include the referenced table or remove the foreign key.

2. Stale metadata — If you dropped and recreated tables, metadata may be out of sync. Run a full mj codegen (without --skipdb) to refresh.

When to Use --skipdb

Use it when:

• You only need to regenerate code files from existing metadata
• The database is temporarily unavailable but you have valid metadata from a previous run

Don't use it when:

• You have made schema changes (new tables, altered columns, new constraints)
• You are running CodeGen for the first time
• You have changed forceRegeneration settings

Configuration Validation Errors

Symptom: Zod validation errors at startup.

CodeGen validates all configuration using Zod schemas. Common issues:

• Missing required fields (dbHost, dbDatabase, codeGenLogin, codeGenPassword)
• Invalid types (dbPort must be a positive integer, verboseOutput must be a boolean)
• Malformed output array (each entry needs type and directory properties)

AI-Powered Features Not Running

1. Verify advancedGeneration.enableAdvancedGeneration is true in mj.config.cjs
2. Verify the specific feature is enabled: true in the features array
3. Ensure the AI Prompts referenced by CodeGen exist in the database
4. Confirm that at least one AI model is configured and accessible