@memberjunction/data-context-server

This library provides a server-side implementation of the DataContextItem class from @memberjunction/data-context that can handle the server-side only use case of loading data into a context using raw SQL statements.

Overview

The @memberjunction/data-context-server package extends the base DataContextItem class to provide server-side functionality for executing SQL queries directly against a database. This is particularly useful when you need to load data contexts that include custom SQL statements, which cannot be executed on the client side.

Installation

1npm install @memberjunction/data-context-server

Purpose and Functionality

This package serves a critical role in the MemberJunction ecosystem by:

1. Enabling SQL Execution: Provides the ability to execute raw SQL statements through data contexts on the server side
2. TypeORM Integration: Uses TypeORM's DataSource for database operations
3. Automatic Registration: Registers itself with higher priority (2) to override the base implementation when running on the server
4. Tree-Shaking Prevention: Includes a utility function to ensure the class isn't removed during build optimization

Usage

Basic Setup

First, ensure the server-side implementation is loaded to prevent tree-shaking:

1import { LoadDataContextItemsServer } from '@memberjunction/data-context-server';
2
3// Call this once in your server initialization code
4LoadDataContextItemsServer();

Loading Data Contexts with SQL Items

1import { DataContext } from '@memberjunction/data-context';
2import { DataSource } from 'typeorm';
3import { UserInfo } from '@memberjunction/core';
4
5// Assume you have a TypeORM DataSource configured
6const dataSource: DataSource = /* your configured data source */;
7
8// Load a data context that includes SQL-type items
9const context = new DataContext();
10const user = /* current user context */;
11
12// Load metadata and data in one operation
13const success = await context.Load(
14  dataContextId,
15  dataSource,  // Pass the TypeORM DataSource
16  false,       // forceRefresh
17  false,       // loadRelatedDataOnSingleRecords
18  0,           // maxRecordsPerRelationship
19  user         // contextUser
20);
21
22if (success) {
23  // Access the loaded data
24  context.Items.forEach(item => {
25    if (item.Type === 'sql' && item.DataLoaded) {
26      console.log(`SQL Item Data:`, item.Data);
27    }
28  });
29}

Creating SQL Data Context Items

1import { DataContext } from '@memberjunction/data-context';
2
3const context = new DataContext();
4const sqlItem = context.AddDataContextItem();
5
6// Configure as SQL type
7sqlItem.Type = 'sql';
8sqlItem.SQL = 'SELECT * FROM Customers WHERE Country = @country';
9sqlItem.RecordName = 'US Customers';
10sqlItem.AdditionalDescription = 'All customers from the United States';
11
12// Load the data
13const dataSource = /* your TypeORM DataSource */;
14const loaded = await sqlItem.LoadData(dataSource);
15
16if (loaded) {
17  console.log('SQL Results:', sqlItem.Data);
18} else {
19  console.error('Loading failed:', sqlItem.DataLoadingError);
20}

API Documentation

DataContextItemServer Class

The DataContextItemServer class extends DataContextItem and overrides the LoadFromSQL method.

Protected Methods

LoadFromSQL(dataSource: any, contextUser?: UserInfo): Promise<boolean>

Executes a SQL statement and loads the results into the DataContextItem.

Parameters:

• dataSource (any): The TypeORM DataSource object used to execute queries
• contextUser (UserInfo, optional): The user context for the operation

Returns:

• Promise<boolean>: Returns true if successful, false if an error occurs

Error Handling:

• Catches and logs any SQL execution errors
• Sets the DataLoadingError property with error details
• Returns false on failure

Utility Functions

LoadDataContextItemsServer(): void

Prevents tree-shaking from removing the DataContextItemServer class during build optimization.

Usage: Call this function after importing the package in your server application to ensure the class registration takes effect.

Integration with MemberJunction Packages

This package integrates seamlessly with:

• @memberjunction/data-context: Provides the base DataContextItem class and DataContext functionality
• @memberjunction/global: Uses the class registration system for runtime polymorphism
• @memberjunction/core: Leverages logging utilities and user context
• typeorm: Utilizes TypeORM's DataSource for database operations

Dependencies

1{
2  "@memberjunction/data-context": "2.43.0",
3  "@memberjunction/global": "2.43.0",
4  "typeorm": "^0.3.20"
5}

Configuration

No special configuration is required. The package automatically registers itself with the MemberJunction class factory system when imported.

Build and Development

Scripts

• npm run build: Compiles TypeScript to JavaScript
• npm start: Runs the TypeScript code directly using ts-node-dev

TypeScript Configuration

The package uses a standard TypeScript configuration that compiles to ES modules and includes type definitions.

Important Notes

1. Server-Side Only: This package is designed for server-side use only. Client-side applications should not include this package.

2. Class Registration Priority: The DataContextItemServer class registers with priority 2, ensuring it overrides the base implementation when present.

3. Error Handling: SQL execution errors are caught and stored in the DataLoadingError property rather than throwing exceptions.

4. Data Loading: The LoadFromSQL method stores query results directly in the Data property as an array of objects.

Example: Complete Server Application

1import { DataContext } from '@memberjunction/data-context';
2import { LoadDataContextItemsServer } from '@memberjunction/data-context-server';
3import { createConnection, DataSource } from 'typeorm';
4import { Metadata } from '@memberjunction/core';
5
6// Initialize the server-side data context support
7LoadDataContextItemsServer();
8
9// Configure your database connection
10const dataSource = new DataSource({
11  type: 'mssql',
12  host: 'localhost',
13  username: 'your_username',
14  password: 'your_password',
15  database: 'your_database',
16  // ... other TypeORM configuration
17});
18
19async function loadDataContextWithSQL() {
20  await dataSource.initialize();
21  
22  const context = new DataContext();
23  const user = await Metadata.Provider.GetCurrentUser();
24  
25  // Create a SQL-based data context item
26  const item = context.AddDataContextItem();
27  item.Type = 'sql';
28  item.SQL = `
29    SELECT 
30      c.CustomerID,
31      c.CompanyName,
32      COUNT(o.OrderID) as OrderCount,
33      SUM(od.Quantity * od.UnitPrice) as TotalRevenue
34    FROM Customers c
35    LEFT JOIN Orders o ON c.CustomerID = o.CustomerID
36    LEFT JOIN [Order Details] od ON o.OrderID = od.OrderID
37    GROUP BY c.CustomerID, c.CompanyName
38    ORDER BY TotalRevenue DESC
39  `;
40  item.RecordName = 'Customer Revenue Summary';
41  
42  // Load the data
43  const success = await item.LoadData(dataSource, false, false, 0, user);
44  
45  if (success) {
46    console.log('Customer revenue data:', item.Data);
47    
48    // Save the context if needed
49    await context.SaveItems(user, true); // true to persist the data
50  }
51  
52  await dataSource.destroy();
53}

License

This package is part of the MemberJunction framework and follows the same licensing terms.