@memberjunction/data-context 4.0.0 → 4.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/data-context",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "This library provides a set of objects that handle run-time loading of data contexts as well as types to be able to use across application tiers for interacting with data contexts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,9 +20,9 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "4.0.0",
-    "@memberjunction/core-entities": "4.0.0",
-    "@memberjunction/core": "4.0.0"
+    "@memberjunction/global": "4.1.0",
+    "@memberjunction/core-entities": "4.1.0",
+    "@memberjunction/core": "4.1.0"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -1,15 +1,49 @@
 # @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)
+The `@memberjunction/data-context` library provides a metadata-driven framework for managing collections of related data items in MemberJunction applications. It enables developers to define, load, persist, and manipulate data from multiple sources -- views, queries, entities, single records, and raw SQL -- through a unified, type-safe API that works across both client and server tiers.
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    subgraph Consumer["Consumer Code"]
+        style Consumer fill:#2d6a9f,stroke:#1a4971,color:#fff
+        A["Application / Agent / Workflow"]
+    end
+
+    subgraph DataContextPkg["@memberjunction/data-context"]
+        style DataContextPkg fill:#7c5295,stroke:#563a6b,color:#fff
+        DC["DataContext"]
+        DCI["DataContextItem"]
+        DCFI["DataContextFieldInfo"]
+    end
+
+    subgraph Sources["Data Sources"]
+        style Sources fill:#2d8659,stroke:#1a5c3a,color:#fff
+        V["Views (RunView)"]
+        Q["Queries (RunQuery)"]
+        E["Full Entities"]
+        SR["Single Records"]
+        SQL["SQL Statements"]
+    end
+
+    subgraph Persistence["Persistence Layer"]
+        style Persistence fill:#b8762f,stroke:#8a5722,color:#fff
+        DCE["DataContextEntity"]
+        DCIE["DataContextItemEntity"]
+    end
+
+    A --> DC
+    DC -->|"manages"| DCI
+    DCI -->|"field metadata"| DCFI
+    DCI -->|"loads from"| V
+    DCI -->|"loads from"| Q
+    DCI -->|"loads from"| E
+    DCI -->|"loads from"| SR
+    DCI -->|"loads from"| SQL
+    DC -->|"persists via"| DCE
+    DC -->|"persists items via"| DCIE
+```
 
 ## Installation
 
@@ -17,54 +51,167 @@ A Data Context in MemberJunction represents a collection of data items that can
 npm install @memberjunction/data-context
 ```
 
-## Key Features
+## Key Concepts
+
+A **Data Context** is a named collection of **Data Context Items**, each of which represents a distinct data source. An item can be one of five types:
+
+| Type            | Description                                      | Required Fields                  |
+|-----------------|--------------------------------------------------|----------------------------------|
+| `view`          | A saved MemberJunction User View                 | `ViewID`, `EntityID`             |
+| `query`         | A registered MemberJunction Query                | `QueryID`                        |
+| `full_entity`   | All records from an entity                       | `EntityID`                       |
+| `single_record` | One record, optionally with related entity data  | `EntityID`, `RecordID`           |
+| `sql`           | A raw SQL statement (server-side only)            | `SQL`                            |
+
+## Class Hierarchy
+
+```mermaid
+classDiagram
+    class DataContext {
+        +ID: string
+        +DataContextEntity: DataContextEntity
+        +Items: DataContextItem[]
+        +LoadMetadata(id, contextUser, provider) Promise~boolean~
+        +LoadData(dataSource, forceRefresh, ...) Promise~boolean~
+        +Load(id, dataSource, ...) Promise~boolean~
+        +SaveItems(contextUser, persistItemData) Promise~boolean~
+        +AddDataContextItem() DataContextItem
+        +ValidateDataExists(ignoreFailedLoadItems) boolean
+        +ConvertToSimpleObject(itemPrefix, includeFailedLoadItems) object
+        +CreateSimpleObjectTypeDefinition(itemPrefix, includeFailedLoadItems) string
+        +LoadDataFromObject(data) boolean
+        +Clone(context, includeData, contextUser)$ Promise~DataContext~
+        +FromRawData(rawData)$ Promise~DataContext~
+        +CreateDataContextItem()$ DataContextItem
+        +MapEntityFieldsToDataContextFields(entity)$ DataContextFieldInfo[]
+    }
+
+    class DataContextItem {
+        +Type: ItemType
+        +RecordID: string
+        +EntityID: string
+        +ViewID: string
+        +QueryID: string
+        +RecordName: string
+        +SQL: string
+        +CodeName: string
+        +EntityName: string
+        +Fields: DataContextFieldInfo[]
+        +DataContextItemID: string
+        +Data: object[]
+        +DataLoaded: boolean
+        +DataLoadingError: string
+        +Description: string
+        +AdditionalDescription: string
+        +LoadData(dataSource, ...) Promise~boolean~
+        +LoadDataFromObject(data) boolean
+        +ValidateDataExists(ignoreFailedLoad) boolean
+        +FromViewEntity(viewEntity)$ DataContextItem
+        +FromSingleRecord(record)$ DataContextItem
+        +FromQuery(query)$ DataContextItem
+        +FromFullEntity(entity)$ DataContextItem
+        +FromRawItem(rawItem)$ DataContextItem
+        #LoadFromView(contextUser) Promise~boolean~
+        #LoadFromFullEntity(contextUser) Promise~boolean~
+        #LoadFromSingleRecord(contextUser, ...) Promise~boolean~
+        #LoadFromQuery(contextUser) Promise~boolean~
+        #LoadFromSQL(dataSource, contextUser) Promise~boolean~
+    }
+
+    class DataContextFieldInfo {
+        +Name: string
+        +Type: string
+        +Description: string
+    }
+
+    class DataContextItemServer {
+        #LoadFromSQL(dataSource, contextUser) Promise~boolean~
+    }
+
+    DataContext "1" --> "*" DataContextItem : contains
+    DataContextItem "1" --> "*" DataContextFieldInfo : describes fields
+    DataContextItemServer --|> DataContextItem : extends
+```
+
+## Data Lifecycle
+
+```mermaid
+flowchart LR
+    subgraph Step1["1. Create"]
+        style Step1 fill:#2d6a9f,stroke:#1a4971,color:#fff
+        C1["new DataContext()"]
+    end
+
+    subgraph Step2["2. Load Metadata"]
+        style Step2 fill:#7c5295,stroke:#563a6b,color:#fff
+        C2["LoadMetadata(id)"]
+    end
 
-- **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
+    subgraph Step3["3. Load Data"]
+        style Step3 fill:#2d8659,stroke:#1a5c3a,color:#fff
+        C3["LoadData(dataSource)"]
+    end
+
+    subgraph Step4["4. Process"]
+        style Step4 fill:#b8762f,stroke:#8a5722,color:#fff
+        C4["ValidateDataExists()\nConvertToSimpleObject()"]
+    end
+
+    subgraph Step5["5. Persist"]
+        style Step5 fill:#2d6a9f,stroke:#1a4971,color:#fff
+        C5["SaveItems(contextUser)"]
+    end
+
+    Step1 --> Step2 --> Step3 --> Step4 --> Step5
+```
 
 ## Usage
 
-### Basic Example
+### Loading an Existing Data Context
+
+Use `Load()` to fetch both metadata and data in a single call:
 
 ```typescript
-import { DataContext, DataContextItem } from '@memberjunction/data-context';
-import { Metadata } from '@memberjunction/core';
+import { DataContext } from '@memberjunction/data-context';
 
-// Create a new data context
 const context = new DataContext();
-
-// Load metadata and data for an existing data context
-const dataContextID = 'your-data-context-id';
 const loaded = await context.Load(
-  dataContextID,
-  dataSource, // Required for SQL type items (server-side only)
-  false,      // forceRefresh
-  true,       // loadRelatedDataOnSingleRecords
-  10,         // maxRecordsPerRelationship
-  userInfo    // contextUser
+  dataContextID,   // ID of the data context record
+  dataSource,      // Required only for SQL-type items (server-side)
+  false,           // forceRefresh -- reload even if data is cached
+  true,            // loadRelatedDataOnSingleRecords
+  10,              // maxRecordsPerRelationship
+  contextUser      // required on server-side
 );
 
 if (loaded) {
-  // Access the loaded data
   context.Items.forEach(item => {
-    console.log(`Item: ${item.Description}`);
-    console.log(`Data rows: ${item.Data?.length || 0}`);
+    console.log(`${item.Description}: ${item.Data?.length ?? 0} rows`);
   });
 }
 ```
 
-### Creating Data Context Items
+Alternatively, call `LoadMetadata()` and `LoadData()` separately for finer control:
+
+```typescript
+const context = new DataContext();
+await context.LoadMetadata(dataContextID, contextUser);
+
+// Inspect or modify items before loading data
+console.log(`Items to load: ${context.Items.length}`);
+
+await context.LoadData(dataSource, false, true, 10, contextUser);
+```
+
+### Creating Items Programmatically
+
+Each item type has a dedicated static factory method.
 
 #### From a View
 
 ```typescript
 import { UserViewEntityExtended } from '@memberjunction/core-entities';
 
-// Assuming you have a view entity loaded
 const viewEntity: UserViewEntityExtended = await md.GetEntityObject<UserViewEntityExtended>('User Views');
 await viewEntity.Load(viewID);
 
@@ -77,7 +224,6 @@ context.Items.push(viewItem);
 ```typescript
 import { BaseEntity } from '@memberjunction/core';
 
-// Assuming you have an entity record loaded
 const record: BaseEntity = await md.GetEntityObject('Customers');
 await record.Load(recordID);
 
@@ -90,8 +236,7 @@ context.Items.push(recordItem);
 ```typescript
 import { QueryInfo } from '@memberjunction/core';
 
-// Get query info from metadata
-const queryInfo = md.Queries.find(q => q.Name === 'My Query');
+const queryInfo = md.Queries.find(q => q.Name === 'Monthly Revenue');
 if (queryInfo) {
   const queryItem = DataContextItem.FromQuery(queryInfo);
   context.Items.push(queryItem);
@@ -103,7 +248,6 @@ if (queryInfo) {
 ```typescript
 import { EntityInfo } from '@memberjunction/core';
 
-// Get entity info from metadata
 const entityInfo = md.Entities.find(e => e.Name === 'Products');
 if (entityInfo) {
   const entityItem = DataContextItem.FromFullEntity(entityInfo);
@@ -115,75 +259,85 @@ if (entityInfo) {
 
 ```typescript
 // Load data for all items in the context
-const dataLoaded = await context.LoadData(
-  dataSource,  // Required for SQL type items
+const allLoaded = await context.LoadData(
+  dataSource,  // required for SQL-type items
   false,       // forceRefresh
   true,        // loadRelatedDataOnSingleRecords
-  10          // maxRecordsPerRelationship
+  10           // maxRecordsPerRelationship
 );
 
-// Or load data for a specific item
+// Or load data for a single item
 const itemLoaded = await context.Items[0].LoadData(
-  dataSource,
-  false,
-  true,
-  10
+  dataSource, false, true, 10, contextUser
 );
 ```
 
+### Loading Pre-fetched Data
+
+If you already have the data available (for example, from a cache or external API), load it directly:
+
+```typescript
+// Load into a single item
+const item = context.Items[0];
+item.LoadDataFromObject(myDataArray);
+
+// Load into all items at once (2D array, one sub-array per item in order)
+context.LoadDataFromObject([
+  rowsForItem0,
+  rowsForItem1,
+  rowsForItem2
+]);
+```
+
 ### Saving Data Context Items
 
 ```typescript
-// Save all items in the context to the database
 const saved = await context.SaveItems(
-  userInfo,  // contextUser
-  true       // persistItemData - saves actual data, not just metadata
+  contextUser,  // context user for server-side operations
+  true          // persistItemData -- also save loaded data as JSON
 );
 
 if (saved) {
-  console.log('Data context items saved successfully');
   // Each item now has a DataContextItemID populated
+  context.Items.forEach(item => {
+    console.log(`Saved item ${item.DataContextItemID}`);
+  });
 }
 ```
 
-### Working with Data
+Items are saved in a single transaction group -- either all succeed or none are committed.
+
+### Working with Loaded Data
 
 ```typescript
-// Validate that all items have data loaded
+// Validate all items have data
 if (context.ValidateDataExists()) {
-  // Convert to a simple object for easier manipulation
-  const simpleData = context.ConvertToSimpleObject('item_', false);
+  // Convert to a flat keyed object
+  const simpleObj = context.ConvertToSimpleObject('item_', false);
   // Result: { item_0: [...], item_1: [...], ... }
-  
-  // Get type definition for the data structure
+
+  // Generate a TypeScript-style type definition string
   const typeDef = context.CreateSimpleObjectTypeDefinition('item_');
-  console.log(typeDef);
   // Output: {item_0: []; // View: Customer List, From Entity: Customers\n...}
 }
 
-// Access individual item data
+// Check individual items for errors
 context.Items.forEach(item => {
   if (item.DataLoaded && item.Data) {
     console.log(`${item.Description}: ${item.Data.length} rows`);
-    
-    // Process the data
-    item.Data.forEach(row => {
-      // Work with row data
-    });
   } else if (item.DataLoadingError) {
-    console.error(`Error loading ${item.Description}: ${item.DataLoadingError}`);
+    console.error(`Failed: ${item.DataLoadingError}`);
   }
 });
 ```
 
-### Cloning Data Contexts
+### Cloning a Data Context
 
 ```typescript
-// Clone an existing data context
 const clonedContext = await DataContext.Clone(
   originalContext,
-  true,      // includeData - copies the data along with metadata
-  userInfo   // contextUser
+  true,         // includeData -- copy loaded data into the clone
+  contextUser
 );
 
 if (clonedContext) {
@@ -191,116 +345,112 @@ if (clonedContext) {
 }
 ```
 
-## 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
+### Reconstructing from Raw Data
 
-- `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
+```typescript
+const context = await DataContext.FromRawData(rawObject);
+// rawObject should have { ID, Items: [ { Type, RecordID, ... }, ... ] }
+```
 
-- `LoadDataFromObject(data: any[]): boolean`
-  - Loads pre-fetched data into the item
+## Server-Side SQL Support
 
-- `ValidateDataExists(ignoreFailedLoad?: boolean): boolean`
-  - Validates that data has been loaded
+The base `DataContextItem` class throws an error when `LoadFromSQL()` is called because raw SQL execution is inherently a server-side operation. The companion package `@memberjunction/data-context-server` provides `DataContextItemServer`, which overrides this method using an `mssql` connection pool:
 
-- `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`
+```mermaid
+flowchart TD
+    subgraph Client["Client Tier"]
+        style Client fill:#2d6a9f,stroke:#1a4971,color:#fff
+        DCI_C["DataContextItem\n(base class)"]
+    end
 
-### DataContextFieldInfo Class
+    subgraph Server["Server Tier"]
+        style Server fill:#2d8659,stroke:#1a5c3a,color:#fff
+        DCI_S["DataContextItemServer\n(@RegisterClass override)"]
+        MSSQL["mssql ConnectionPool"]
+    end
 
-```typescript
-class DataContextFieldInfo {
-  Name: string;
-  Type: string;
-  Description?: string;
-}
+    DCI_C -->|"LoadFromSQL() throws error"| X["Not supported client-side"]
+    DCI_S -->|"LoadFromSQL() executes via"| MSSQL
+    DCI_S -.->|"extends"| DCI_C
 ```
 
-## Server-Side Considerations
+`DataContextItemServer` is registered via `@RegisterClass` with a higher priority, so the MemberJunction class factory automatically returns the server variant when the server package is included. No code changes are needed -- just include `@memberjunction/data-context-server` in your server project's dependencies.
+
+## API Reference
 
-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.
+### DataContext
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `LoadMetadata(id, contextUser?, provider?)` | `Promise<boolean>` | Loads metadata for the context and all its items from the database |
+| `LoadData(dataSource, forceRefresh?, loadRelated?, maxRecords?, contextUser?)` | `Promise<boolean>` | Loads data for all items; must call `LoadMetadata()` first |
+| `Load(id, dataSource, forceRefresh?, loadRelated?, maxRecords?, contextUser?)` | `Promise<boolean>` | Combined metadata + data load in one call |
+| `SaveItems(contextUser?, persistItemData?)` | `Promise<boolean>` | Persists all items to the database in a single transaction |
+| `AddDataContextItem()` | `DataContextItem` | Creates a new item and adds it to `Items` |
+| `ValidateDataExists(ignoreFailedLoadItems?)` | `boolean` | Returns true if all items have their `Data` property set |
+| `ConvertToSimpleObject(itemPrefix?, includeFailedLoadItems?)` | `object` | Converts context to a flat keyed object |
+| `CreateSimpleObjectTypeDefinition(itemPrefix?, includeFailedLoadItems?)` | `string` | Generates a type definition string for the simple object |
+| `LoadDataFromObject(data)` | `boolean` | Loads pre-fetched data as a 2D array mapped by item index |
+| `Clone(context, includeData?, contextUser?)` (static) | `Promise<DataContext>` | Deep-clones a context and its items into new database records |
+| `FromRawData(rawData)` (static) | `Promise<DataContext>` | Reconstructs a `DataContext` from a plain object |
+| `CreateDataContextItem()` (static) | `DataContextItem` | Creates a new item via the class factory (does not add to context) |
+| `MapEntityFieldsToDataContextFields(entity)` (static) | `DataContextFieldInfo[]` | Maps `EntityInfo` fields to simplified field info objects |
+
+### DataContextItem
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Type` | `'view' \| 'query' \| 'full_entity' \| 'sql' \| 'single_record'` | The data source type |
+| `RecordID` | `string` | Primary key for `single_record` items (comma-separated for composite keys) |
+| `EntityID` | `string` | Entity identifier (not used for `query` or `sql` types) |
+| `ViewID` | `string` | View identifier (only for `view` type) |
+| `QueryID` | `string` | Query identifier (only for `query` type) |
+| `RecordName` | `string` | Display name of the view, query, or entity |
+| `SQL` | `string` | SQL statement (only for `sql` type) |
+| `CodeName` | `string` | System-generated unique code name within the context |
+| `EntityName` | `string` | Entity name (not used for `query` or `sql` types) |
+| `Fields` | `DataContextFieldInfo[]` | Field metadata for the item |
+| `DataContextItemID` | `string` | Database record ID (populated after save) |
+| `Data` | `object[]` | The loaded data rows |
+| `DataLoaded` | `boolean` | Whether data has been successfully loaded |
+| `DataLoadingError` | `string` | Error message if loading failed |
+| `Description` | `string` (readonly) | Auto-generated description based on type |
+| `AdditionalDescription` | `string` | Optional supplementary description |
+
+| Static Factory Method | Description |
+|----------------------|-------------|
+| `FromViewEntity(viewEntity)` | Creates an item from a `UserViewEntityExtended` |
+| `FromSingleRecord(record)` | Creates an item from a `BaseEntity` instance |
+| `FromQuery(query)` | Creates an item from a `QueryInfo` |
+| `FromFullEntity(entity)` | Creates an item from an `EntityInfo` |
+| `FromRawItem(rawItem)` | Creates an item from a plain object |
+
+### DataContextFieldInfo
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Name` | `string` | Field name |
+| `Type` | `string` | Field data type |
+| `Description` | `string` (optional) | Field description |
 
 ## Dependencies
 
-- `@memberjunction/global`: Core global utilities and class factory
-- `@memberjunction/core-entities`: Entity definitions for MemberJunction
-- `@memberjunction/core`: Core MemberJunction functionality
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/global` | Class factory and `@RegisterClass` decorator |
+| `@memberjunction/core` | Core framework: `Metadata`, `RunView`, `RunQuery`, `BaseEntity`, `EntityInfo`, `UserInfo` |
+| `@memberjunction/core-entities` | Generated entity classes: `DataContextEntity`, `DataContextItemEntity`, `UserViewEntityExtended` |
 
 ## 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
+1. **Always load metadata before data.** Use `LoadMetadata()` then `LoadData()`, or use the combined `Load()` method.
+2. **Check `DataLoaded` and `DataLoadingError`** on each item after loading. `LoadData()` does not throw exceptions for individual item failures -- it returns `false` and populates the error properties.
+3. **Pass `contextUser` on the server side.** Server code serves multiple users concurrently and must include the context user for proper security and audit tracking.
+4. **Use `maxRecordsPerRelationship`** to limit the amount of related data loaded for `single_record` items, especially in production environments.
+5. **Validate before processing.** Call `ValidateDataExists()` before working with data to ensure all items are ready.
+6. **Leverage transactions.** `SaveItems()` automatically wraps all item saves in a transaction group for atomicity.
+7. **Include `@memberjunction/data-context-server`** in server projects if any items use the `sql` type. The class factory handles the override automatically.
 
 ## License
 
-ISC
+ISC