@memberjunction/data-context

The @memberjunction/data-context library provides a comprehensive framework for managing data contexts in MemberJunction applications. It enables developers to define, load, and manipulate collections of related data items across different tiers of an application.

Overview

A Data Context in MemberJunction represents a collection of data items that can include:

• Views: Filtered and customized views of entity data
• Queries: Pre-defined SQL queries registered in the system
• Full Entities: Complete data sets from an entity
• Single Records: Individual entity records with optional related data
• SQL Statements: Direct SQL queries (server-side only)

Installation

1npm install @memberjunction/data-context

Key Features

• Type-safe data context management: Full TypeScript support with proper typing
• Flexible data loading: Support for various data sources including views, queries, entities, and SQL
• Metadata-driven: Automatic loading of metadata from the MemberJunction system
• Transaction support: Save multiple data context items in a single transaction
• Cross-tier compatibility: Works across server and client tiers with appropriate implementations
• Data persistence: Optional saving of loaded data to the database

Usage

Basic Example

1import { DataContext, DataContextItem } from '@memberjunction/data-context';
2import { Metadata } from '@memberjunction/core';
3
4// Create a new data context
5const context = new DataContext();
6
7// Load metadata and data for an existing data context
8const dataContextID = 'your-data-context-id';
9const loaded = await context.Load(
10  dataContextID,
11  dataSource, // Required for SQL type items (server-side only)
12  false,      // forceRefresh
13  true,       // loadRelatedDataOnSingleRecords
14  10,         // maxRecordsPerRelationship
15  userInfo    // contextUser
16);
17
18if (loaded) {
19  // Access the loaded data
20  context.Items.forEach(item => {
21    console.log(`Item: ${item.Description}`);
22    console.log(`Data rows: ${item.Data?.length || 0}`);
23  });
24}

Creating Data Context Items

From a View

1import { UserViewEntityExtended } from '@memberjunction/core-entities';
2
3// Assuming you have a view entity loaded
4const viewEntity: UserViewEntityExtended = await md.GetEntityObject<UserViewEntityExtended>('User Views');
5await viewEntity.Load(viewID);
6
7const viewItem = DataContextItem.FromViewEntity(viewEntity);
8context.Items.push(viewItem);

From a Single Record

1import { BaseEntity } from '@memberjunction/core';
2
3// Assuming you have an entity record loaded
4const record: BaseEntity = await md.GetEntityObject('Customers');
5await record.Load(recordID);
6
7const recordItem = DataContextItem.FromSingleRecord(record);
8context.Items.push(recordItem);

From a Query

1import { QueryInfo } from '@memberjunction/core';
2
3// Get query info from metadata
4const queryInfo = md.Queries.find(q => q.Name === 'My Query');
5if (queryInfo) {
6  const queryItem = DataContextItem.FromQuery(queryInfo);
7  context.Items.push(queryItem);
8}

From a Full Entity

1import { EntityInfo } from '@memberjunction/core';
2
3// Get entity info from metadata
4const entityInfo = md.Entities.find(e => e.Name === 'Products');
5if (entityInfo) {
6  const entityItem = DataContextItem.FromFullEntity(entityInfo);
7  context.Items.push(entityItem);
8}

Loading Data for Items

1// Load data for all items in the context
2const dataLoaded = await context.LoadData(
3  dataSource,  // Required for SQL type items
4  false,       // forceRefresh
5  true,        // loadRelatedDataOnSingleRecords
6  10          // maxRecordsPerRelationship
7);
8
9// Or load data for a specific item
10const itemLoaded = await context.Items[0].LoadData(
11  dataSource,
12  false,
13  true,
14  10
15);

Saving Data Context Items

1// Save all items in the context to the database
2const saved = await context.SaveItems(
3  userInfo,  // contextUser
4  true       // persistItemData - saves actual data, not just metadata
5);
6
7if (saved) {
8  console.log('Data context items saved successfully');
9  // Each item now has a DataContextItemID populated
10}

Working with Data

1// Validate that all items have data loaded
2if (context.ValidateDataExists()) {
3  // Convert to a simple object for easier manipulation
4  const simpleData = context.ConvertToSimpleObject('item_', false);
5  // Result: { item_0: [...], item_1: [...], ... }
6  
7  // Get type definition for the data structure
8  const typeDef = context.CreateSimpleObjectTypeDefinition('item_');
9  console.log(typeDef);
10  // Output: {item_0: []; // View: Customer List, From Entity: Customers\n...}
11}
12
13// Access individual item data
14context.Items.forEach(item => {
15  if (item.DataLoaded && item.Data) {
16    console.log(`${item.Description}: ${item.Data.length} rows`);
17    
18    // Process the data
19    item.Data.forEach(row => {
20      // Work with row data
21    });
22  } else if (item.DataLoadingError) {
23    console.error(`Error loading ${item.Description}: ${item.DataLoadingError}`);
24  }
25});

Cloning Data Contexts

1// Clone an existing data context
2const clonedContext = await DataContext.Clone(
3  originalContext,
4  true,      // includeData - copies the data along with metadata
5  userInfo   // contextUser
6);
7
8if (clonedContext) {
9  console.log(`Cloned context ID: ${clonedContext.ID}`);
10}

API Reference

DataContext Class

Properties

• ID: string - The unique identifier of the data context
• DataContextEntity: DataContextEntity - The metadata entity for the data context
• Items: DataContextItem[] - Array of data context items

Methods

• async LoadMetadata(DataContextID: string, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<boolean>

  • Loads only the metadata for the data context and its items

• async LoadData(dataSource: any, forceRefresh?: boolean, loadRelatedDataOnSingleRecords?: boolean, maxRecordsPerRelationship?: number, contextUser?: UserInfo): Promise<boolean>

  • Loads data for all items in the context

• async Load(DataContextID: string, dataSource: any, forceRefresh?: boolean, loadRelatedDataOnSingleRecords?: boolean, maxRecordsPerRelationship?: number, contextUser?: UserInfo): Promise<boolean>

  • Loads both metadata and data in one operation

• async SaveItems(contextUser?: UserInfo, persistItemData?: boolean): Promise<boolean>

  • Saves all data context items to the database

• AddDataContextItem(): DataContextItem

  • Creates and adds a new item to the context

• ValidateDataExists(ignoreFailedLoadItems?: boolean): boolean

  • Checks if all items have data loaded

• ConvertToSimpleObject(itemPrefix?: string, includeFailedLoadItems?: boolean): any

  • Converts the context to a simple object structure

• CreateSimpleObjectTypeDefinition(itemPrefix?: string, includeFailedLoadItems?: boolean): string

  • Generates TypeScript type definition for the data structure

• LoadDataFromObject(data: any[][]): boolean

  • Loads pre-fetched data into the context

• static async Clone(context: DataContext, includeData?: boolean, contextUser?: UserInfo): Promise<DataContext>

  • Creates a deep copy of a data context

• static async FromRawData(rawData: any): Promise<DataContext>

  • Creates a context from raw data object

DataContextItem Class

Properties

• Type: 'view' | 'query' | 'full_entity' | 'sql' | 'single_record' - The type of data item
• RecordID: string - Primary key for single_record types
• EntityID?: string - Entity identifier
• ViewID?: string - View identifier
• QueryID?: string - Query identifier
• RecordName: string - Name of the view, query, or entity
• SQL?: string - SQL statement for 'sql' type
• EntityName?: string - Name of the entity
• Fields: DataContextFieldInfo[] - Field metadata
• Data: any[] - The loaded data
• DataLoaded: boolean - Indicates if data has been loaded
• DataLoadingError?: string - Error message if loading failed
• Description: string - Auto-generated description
• AdditionalDescription?: string - Optional custom description

Methods

• async LoadData(dataSource: any, forceRefresh?: boolean, loadRelatedDataOnSingleRecords?: boolean, maxRecordsPerRelationship?: number, contextUser?: UserInfo): Promise<boolean>

  • Loads data for this specific item

• LoadDataFromObject(data: any[]): boolean

  • Loads pre-fetched data into the item

• ValidateDataExists(ignoreFailedLoad?: boolean): boolean

  • Validates that data has been loaded

• static FromViewEntity(viewEntity: UserViewEntityExtended): DataContextItem

• static FromSingleRecord(singleRecord: BaseEntity): DataContextItem

• static FromQuery(query: QueryInfo): DataContextItem

• static FromFullEntity(entity: EntityInfo): DataContextItem

• static FromRawItem(rawItem: any): DataContextItem

DataContextFieldInfo Class

1class DataContextFieldInfo {
2  Name: string;
3  Type: string;
4  Description?: string;
5}

Server-Side Considerations

For SQL type data context items, you'll need to use the server-side implementation from @memberjunction/data-context-server which properly handles SQL execution with appropriate security and data source management.

Dependencies

• @memberjunction/global: Core global utilities and class factory
• @memberjunction/core-entities: Entity definitions for MemberJunction
• @memberjunction/core: Core MemberJunction functionality

Best Practices

1. Always load metadata before data: Use LoadMetadata() before LoadData() or simply use Load() which does both
2. Handle loading errors: Check DataLoaded and DataLoadingError properties on items
3. Use appropriate data sources: SQL type items require server-side data sources
4. Consider performance: Use maxRecordsPerRelationship to limit related data loading
5. Validate before use: Call ValidateDataExists() before processing data
6. Use transactions: When saving multiple items, they're automatically wrapped in a transaction

License

ISC