@memberjunction/actions-base

Base classes, interfaces, and metadata engines for the MemberJunction Actions framework. This package provides the foundational layer that both server-side (@memberjunction/actions) and client-side action implementations build upon. It handles action metadata loading, parameter modeling, result types, and extended entity classes with lazy-loaded relationships.

For the broader Actions design philosophy -- including when to use Actions vs. direct class imports, and the "thin wrapper" principle -- see the parent Actions CLAUDE.md.

Installation

npm install @memberjunction/actions-base
Copy

Architecture

The package is organized into two parallel engine hierarchies: one for general-purpose Actions and one for Entity Actions (actions bound to a specific entity). Both engines are singletons that extend BaseEngine from @memberjunction/core and load their metadata via Config().

graph TD
    subgraph BasePackage["@memberjunction/actions-base"]
        AEB["ActionEngineBase\n(singleton)"]
        EAEB["EntityActionEngineBase\n(singleton)"]
        AEX["MJActionEntityExtended"]
        EAEX["MJEntityActionEntityExtended"]
        RAP["RunActionParams<TContext>"]
        AR["ActionResult / ActionResultSimple"]
        AP["ActionParam"]
        GC["GeneratedCode"]
        EAIP["EntityActionInvocationParams"]
        EAR["EntityActionResult"]
    end

    subgraph CoreDeps["Dependencies"]
        BE["BaseEngine\n(@memberjunction/core)"]
        CE["Entity classes\n(@memberjunction/core-entities)"]
        RC["@RegisterClass\n(@memberjunction/global)"]
    end

    AEB -->|extends| BE
    EAEB -->|extends| BE
    AEX -->|extends| CE
    EAEX -->|extends| CE
    AEX -->|registered via| RC
    EAEX -->|registered via| RC
    AEB -->|manages| AEX
    EAEB -->|manages| EAEX

    style BasePackage fill:#2d6a9f,stroke:#1a4971,color:#fff
    style CoreDeps fill:#2d8659,stroke:#1a5c3a,color:#fff
    style AEB fill:#7c5295,stroke:#563a6b,color:#fff
    style EAEB fill:#7c5295,stroke:#563a6b,color:#fff
    style AEX fill:#b8762f,stroke:#8a5722,color:#fff
    style EAEX fill:#b8762f,stroke:#8a5722,color:#fff
Copy

Data Flow: Config and Execution

sequenceDiagram
    participant Caller
    participant AEB as ActionEngineBase
    participant DB as Database (via RunView)
    participant AEX as MJActionEntityExtended

    Caller->>AEB: Config(forceRefresh, contextUser)
    AEB->>DB: RunViews (batch load 6 entity types)
    DB-->>AEB: Actions, Categories, Filters, Params, ResultCodes, Libraries
    AEB-->>Caller: Metadata ready

    Caller->>AEB: Actions (getter)
    AEB-->>Caller: MJActionEntityExtended[]

    Caller->>AEX: ResultCodes (getter, lazy)
    AEX->>AEB: ActionResultCodes (filtered by ActionID)
    AEB-->>AEX: ActionResultCodeEntity[]
    AEX-->>Caller: Cached result codes
Copy

Exports

Engine Classes

Extended Entity Classes

Parameter and Result Types

Code Generation Support

Usage

Configuring the Action Engine

Both engines must be configured before use. Config() loads metadata from the database and caches it. Pass forceRefresh: true to reload after metadata changes.

import { ActionEngineBase } from '@memberjunction/actions-base';
import { UserInfo } from '@memberjunction/core';

async function initialize(contextUser: UserInfo) {
    const engine = ActionEngineBase.Instance;

    // Initial load -- metadata cached in GlobalObjectStore
    await engine.Config(false, contextUser);

    // Access loaded metadata
    const allActions = engine.Actions;          // MJActionEntityExtended[]
    const coreActions = engine.CoreActions;     // Only core MJ actions
    const categories = engine.ActionCategories; // ActionCategoryEntity[]
    const params = engine.ActionParams;         // ActionParamEntity[]
    const filters = engine.ActionFilters;       // ActionFilterEntity[]
    const resultCodes = engine.ActionResultCodes;
    const libraries = engine.ActionLibraries;
}
Copy

Configuring the Entity Action Engine

import { EntityActionEngineBase } from '@memberjunction/actions-base';

async function initEntityActions(contextUser: UserInfo) {
    const engine = EntityActionEngineBase.Instance;
    await engine.Config(false, contextUser);

    // All entity actions
    const entityActions = engine.EntityActions; // MJEntityActionEntityExtended[]

    // Filter by entity name and status
    const customerActions = engine.GetActionsByEntityName('Customers', 'Active');

    // Filter by entity name and invocation type
    const viewActions = engine.GetActionsByEntityNameAndInvocationType(
        'Orders',
        'View',
        'Active'
    );

    // Filter by entity ID
    const byId = engine.GetActionsByEntityID('some-entity-uuid');
}
Copy

Working with MJActionEntityExtended

The extended entity class provides lazy-loaded related data and computed properties.

import { ActionEngineBase, MJActionEntityExtended } from '@memberjunction/actions-base';

const engine = ActionEngineBase.Instance;
await engine.Config(false, contextUser);

const action: MJActionEntityExtended = engine.Actions[0];

// Computed properties
console.log(action.IsCoreAction);     // boolean -- is this a core MJ action?
console.log(action.ProgrammaticName); // Code-safe version of action name

// Lazy-loaded relationships (cached after first access)
const resultCodes = action.ResultCodes; // ActionResultCodeEntity[]
const params = action.Params;           // ActionParamEntity[]
const libraries = action.Libraries;     // ActionLibraryEntity[]
Copy

Building RunActionParams with Type-Safe Context

RunActionParams supports a generic TContext parameter for propagating runtime-specific data (API keys, environment config, feature flags) that is separate from action parameters and not persisted to logs.

import { RunActionParams, ActionParam } from '@memberjunction/actions-base';
import { ActionEntity } from '@memberjunction/core-entities';
import { UserInfo } from '@memberjunction/core';

// Define a context type for your environment
interface ServiceContext {
    apiEndpoint: string;
    apiKey: string;
    environment: 'dev' | 'staging' | 'prod';
    retryPolicy: {
        maxRetries: number;
        backoffMs: number;
    };
}

function buildRunParams(
    action: ActionEntity,
    user: UserInfo,
    context: ServiceContext
): RunActionParams<ServiceContext> {
    const params = new RunActionParams<ServiceContext>();
    params.Action = action;
    params.ContextUser = user;
    params.Params = [
        { Name: 'CustomerID', Value: 'CUST-123', Type: 'Input' },
        { Name: 'OrderTotal', Value: 250.00, Type: 'Input' }
    ];
    params.Context = context; // Type-checked against ServiceContext
    return params;
}
Copy

Entity Action Invocation

Entity actions support three invocation modes depending on the context.

import {
    EntityActionInvocationParams,
    EntityActionEngineBase
} from '@memberjunction/actions-base';

const engine = EntityActionEngineBase.Instance;
await engine.Config(false, contextUser);

const entityActions = engine.GetActionsByEntityNameAndInvocationType(
    'Customers',
    'Single Record',
    'Active'
);

if (entityActions.length > 0) {
    const invocationParams: EntityActionInvocationParams = {
        EntityAction: entityActions[0],
        InvocationType: engine.InvocationTypes.find(
            t => t.Name === 'Single Record'
        )!,
        ContextUser: contextUser,
        EntityObject: customerRecord // BaseEntity instance
    };
    // Pass to your engine's run method
}
Copy

Category Hierarchy Utilities

ActionEngineBase provides methods for navigating the action category tree.

const engine = ActionEngineBase.Instance;

// Check if a category is under the core actions root
const isCoreCategory = engine.IsCoreActionCategory(someCategoryId);

// Check if one category is a descendant of another (recursive)
const isChild = engine.IsChildCategoryOf(childCategoryId, parentCategoryId);

// Look up an action by name
const action = engine.GetActionByName('Send Email');
Copy

Code Generation Types

The GeneratedCode and ActionLibrary types support the AI-powered action generation system.

import { GeneratedCode, ActionLibrary } from '@memberjunction/actions-base';

const generated: GeneratedCode = {
    Success: true,
    Code: 'async function execute(params) { /* ... */ }',
    LibrariesUsed: [
        { LibraryName: 'lodash', ItemsUsed: ['map', 'filter', 'groupBy'] },
        { LibraryName: '@memberjunction/core', ItemsUsed: ['RunView'] }
    ],
    Comments: 'Aggregates customer orders by region and calculates totals'
};
Copy

Key Design Decisions

Singleton engines -- Both ActionEngineBase and EntityActionEngineBase use the MJ BaseEngine singleton pattern. Always access them via the static Instance getter; never construct them directly.

Lazy-loaded relationships -- MJActionEntityExtended and MJEntityActionEntityExtended fetch their related data (params, result codes, filters, invocations, libraries) lazily on first property access and cache the result. This avoids loading relationship data for actions that are never inspected.

IgnoreMaxRows on Config -- The engine overrides LoadMultipleEntityConfigs to set IgnoreMaxRows: true, ensuring all action metadata records are loaded regardless of entity-level UserViewMaxRows settings. Action Params in particular can exceed 1000 records.

Generic context on RunActionParams -- The TContext generic preserves type safety for runtime context data flowing from agents through to action implementations, without polluting the persisted parameter system.

Dependencies

Related Packages