@memberjunction/data-context-server 4.0.0 → 4.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @memberjunction/data-context-server
+
+Server-side implementation of the MemberJunction Data Context system. Provides SQL-based data loading for `DataContextItem` objects using direct database connections.
+
+## Overview
+
+The `@memberjunction/data-context-server` package extends the base `DataContextItem` class from `@memberjunction/data-context` with a server-side implementation that executes SQL queries directly against SQL Server using `mssql` connection pools. This is the server counterpart to the client-side GraphQL-based data context loading.
+
+```mermaid
+graph TD
+    A["DataContextItemServer"] -->|extends| B["DataContextItem<br/>(data-context package)"]
+    A -->|uses| C["mssql ConnectionPool"]
+    C --> D["SQL Server"]
+
+    E["Server-Side Code<br/>(MJAPI, Actions, etc.)"] --> A
+    F["Client-Side Code<br/>(Angular, React)"] --> G["DataContextItemClient<br/>(GraphQL-based)"]
+
+    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style B fill:#7c5295,stroke:#563a6b,color:#fff
+    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style E fill:#b8762f,stroke:#8a5722,color:#fff
+    style G fill:#b8762f,stroke:#8a5722,color:#fff
+```
+
+## Installation
+
+```bash
+npm install @memberjunction/data-context-server
+```
+
+## How It Works
+
+The package registers `DataContextItemServer` as a subclass of `DataContextItem` using MemberJunction's `@RegisterClass` decorator. When server-side code creates a `DataContextItem`, the class factory automatically returns the server implementation that uses direct SQL execution rather than GraphQL.
+
+```typescript
+import '@memberjunction/data-context-server';
+// DataContextItem instances now use direct SQL execution on the server
+```
+
+The `LoadFromSQL` method:
+1. Receives a SQL Server `ConnectionPool` as the data source
+2. Creates a new `Request` from the pool
+3. Executes the `DataContextItem.SQL` query directly
+4. Stores the resulting recordset in `DataContextItem.Data`
+5. Returns success/failure with error details on `DataLoadingError`
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/core` | UserInfo, LogError utilities |
+| `@memberjunction/global` | RegisterClass decorator |
+| `@memberjunction/data-context` | Base DataContextItem class |
+| `mssql` | SQL Server connectivity |
+
+## License
+
+ISC

package/dist/index.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { RegisterClass } from "@memberjunction/global";
 import { LogError } from "@memberjunction/core";
 import { DataContextItem } from "@memberjunction/data-context";
-import * as sql from "mssql";
+import sql from "mssql";
 let DataContextItemServer = class DataContextItemServer extends DataContextItem {
     /**
      * Server-Side only method to load the data context item from a SQL statement

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAGtB,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,eAAe;IACtD;;;;OAIG;IACgB,KAAK,CAAC,WAAW,CAAC,UAAe,EAAE,WAAsB;QACxE,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,UAAgC,CAAC;YAC9C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC;YAC7B,OAAO,IAAI,CAAC,CAAC,mGAAmG;QACpH,CAAC;QACD,OAAO,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,gBAAgB,GAAG,6CAA6C,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YACrG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAChC,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;CACJ,CAAA;AApBY,qBAAqB;IADjC,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC;GAC9C,qBAAqB,CAoBjC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,GAAG,MAAM,OAAO,CAAC;AAGjB,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,eAAe;IACtD;;;;OAIG;IACgB,KAAK,CAAC,WAAW,CAAC,UAAe,EAAE,WAAsB;QACxE,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,UAAgC,CAAC;YAC9C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC;YAC7B,OAAO,IAAI,CAAC,CAAC,mGAAmG;QACpH,CAAC;QACD,OAAO,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,gBAAgB,GAAG,6CAA6C,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YACrG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAChC,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;CACJ,CAAA;AApBY,qBAAqB;IADjC,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC;GAC9C,qBAAqB,CAoBjC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/data-context-server",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,9 +20,9 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/data-context": "4.0.0",
-    "@memberjunction/global": "4.0.0",
+    "@memberjunction/core": "4.1.0",
+    "@memberjunction/data-context": "4.1.0",
+    "@memberjunction/global": "4.1.0",
     "mssql": "^12.2.0"
   },
   "repository": {

package/readme.md

@@ -1,233 +1,59 @@
 # @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.
+Server-side implementation of the MemberJunction Data Context system. Provides SQL-based data loading for `DataContextItem` objects using direct database connections.
 
 ## 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.
+The `@memberjunction/data-context-server` package extends the base `DataContextItem` class from `@memberjunction/data-context` with a server-side implementation that executes SQL queries directly against SQL Server using `mssql` connection pools. This is the server counterpart to the client-side GraphQL-based data context loading.
 
-## Installation
-
-```bash
-npm install @memberjunction/data-context-server
-```
-
-## Purpose and Functionality
-
-This package serves a critical role in the MemberJunction ecosystem by:
+```mermaid
+graph TD
+    A["DataContextItemServer"] -->|extends| B["DataContextItem<br/>(data-context package)"]
+    A -->|uses| C["mssql ConnectionPool"]
+    C --> D["SQL Server"]
 
-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
+    E["Server-Side Code<br/>(MJAPI, Actions, etc.)"] --> A
+    F["Client-Side Code<br/>(Angular, React)"] --> G["DataContextItemClient<br/>(GraphQL-based)"]
 
-## Usage
-
-### Basic Setup
-
-First, ensure the server-side implementation is loaded to prevent tree-shaking:
-
-```typescript
-import { LoadDataContextItemsServer } from '@memberjunction/data-context-server';
-
-// Call this once in your server initialization code
-LoadDataContextItemsServer();
+    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style B fill:#7c5295,stroke:#563a6b,color:#fff
+    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style E fill:#b8762f,stroke:#8a5722,color:#fff
+    style G fill:#b8762f,stroke:#8a5722,color:#fff
 ```
 
-### Loading Data Contexts with SQL Items
+## Installation
 
-```typescript
-import { DataContext } from '@memberjunction/data-context';
-import { DataSource } from 'typeorm';
-import { UserInfo } from '@memberjunction/core';
-
-// Assume you have a TypeORM DataSource configured
-const dataSource: DataSource = /* your configured data source */;
-
-// Load a data context that includes SQL-type items
-const context = new DataContext();
-const user = /* current user context */;
-
-// Load metadata and data in one operation
-const success = await context.Load(
-  dataContextId,
-  dataSource,  // Pass the TypeORM DataSource
-  false,       // forceRefresh
-  false,       // loadRelatedDataOnSingleRecords
-  0,           // maxRecordsPerRelationship
-  user         // contextUser
-);
-
-if (success) {
-  // Access the loaded data
-  context.Items.forEach(item => {
-    if (item.Type === 'sql' && item.DataLoaded) {
-      console.log(`SQL Item Data:`, item.Data);
-    }
-  });
-}
+```bash
+npm install @memberjunction/data-context-server
 ```
 
-### Creating SQL Data Context Items
+## How It Works
+
+The package registers `DataContextItemServer` as a subclass of `DataContextItem` using MemberJunction's `@RegisterClass` decorator. When server-side code creates a `DataContextItem`, the class factory automatically returns the server implementation that uses direct SQL execution rather than GraphQL.
 
 ```typescript
-import { DataContext } from '@memberjunction/data-context';
-
-const context = new DataContext();
-const sqlItem = context.AddDataContextItem();
-
-// Configure as SQL type
-sqlItem.Type = 'sql';
-sqlItem.SQL = 'SELECT * FROM Customers WHERE Country = @country';
-sqlItem.RecordName = 'US Customers';
-sqlItem.AdditionalDescription = 'All customers from the United States';
-
-// Load the data
-const dataSource = /* your TypeORM DataSource */;
-const loaded = await sqlItem.LoadData(dataSource);
-
-if (loaded) {
-  console.log('SQL Results:', sqlItem.Data);
-} else {
-  console.error('Loading failed:', sqlItem.DataLoadingError);
-}
+import '@memberjunction/data-context-server';
+// DataContextItem instances now use direct SQL execution on the server
 ```
 
-## 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
+The `LoadFromSQL` method:
+1. Receives a SQL Server `ConnectionPool` as the data source
+2. Creates a new `Request` from the pool
+3. Executes the `DataContextItem.SQL` query directly
+4. Stores the resulting recordset in `DataContextItem.Data`
+5. Returns success/failure with error details on `DataLoadingError`
 
 ## Dependencies
 
-```json
-{
-  "@memberjunction/data-context": "2.43.0",
-  "@memberjunction/global": "2.43.0",
-  "typeorm": "^0.3.20"
-}
-```
-
-## 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
-
-```typescript
-import { DataContext } from '@memberjunction/data-context';
-import { LoadDataContextItemsServer } from '@memberjunction/data-context-server';
-import { createConnection, DataSource } from 'typeorm';
-import { Metadata } from '@memberjunction/core';
-
-// Initialize the server-side data context support
-LoadDataContextItemsServer();
-
-// Configure your database connection
-const dataSource = new DataSource({
-  type: 'mssql',
-  host: 'localhost',
-  username: 'your_username',
-  password: 'your_password',
-  database: 'your_database',
-  // ... other TypeORM configuration
-});
-
-async function loadDataContextWithSQL() {
-  await dataSource.initialize();
-  
-  const context = new DataContext();
-  const user = await Metadata.Provider.GetCurrentUser();
-  
-  // Create a SQL-based data context item
-  const item = context.AddDataContextItem();
-  item.Type = 'sql';
-  item.SQL = `
-    SELECT 
-      c.CustomerID,
-      c.CompanyName,
-      COUNT(o.OrderID) as OrderCount,
-      SUM(od.Quantity * od.UnitPrice) as TotalRevenue
-    FROM Customers c
-    LEFT JOIN Orders o ON c.CustomerID = o.CustomerID
-    LEFT JOIN [Order Details] od ON o.OrderID = od.OrderID
-    GROUP BY c.CustomerID, c.CompanyName
-    ORDER BY TotalRevenue DESC
-  `;
-  item.RecordName = 'Customer Revenue Summary';
-  
-  // Load the data
-  const success = await item.LoadData(dataSource, false, false, 0, user);
-  
-  if (success) {
-    console.log('Customer revenue data:', item.Data);
-    
-    // Save the context if needed
-    await context.SaveItems(user, true); // true to persist the data
-  }
-  
-  await dataSource.destroy();
-}
-```
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/core` | UserInfo, LogError utilities |
+| `@memberjunction/global` | RegisterClass decorator |
+| `@memberjunction/data-context` | Base DataContextItem class |
+| `mssql` | SQL Server connectivity |
 
 ## License
 
-This package is part of the MemberJunction framework and follows the same licensing terms.
+ISC