@memberjunction/core 2.43.0 → 2.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/core",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction: Core Library including Metadata, Application, Entity Retrieval and Manipulation, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "@types/debug": "^4.1.12"
   },
   "dependencies": {
-    "@memberjunction/global": "2.43.0",
+    "@memberjunction/global": "2.44.0",
     "rxjs": "^7.8.1",
     "zod": "^3.23.8",
     "debug": "^4.4.0"

package/readme.md

@@ -1,107 +1,360 @@
 # @memberjunction/core
 
-The `@memberjunction/core` library provides a comprehensive interface for accessing and managing metadata within MemberJunction, along with facilities for working with entities, applications, and various other aspects central to the MemberJunction ecosystem. This library primarily exports a `Metadata` class which acts as the gateway to many functionalities.
+The `@memberjunction/core` library provides a comprehensive interface for accessing and managing metadata within MemberJunction, along with facilities for working with entities, applications, and various other aspects central to the MemberJunction ecosystem. This library serves as the foundation for all MemberJunction applications and provides essential functionality for data access, manipulation, and metadata management.
 
 ## Installation
 
 ```bash
 npm install @memberjunction/core
+```
 
-```markdown
-## Usage
+## Overview
 
-### Importing the Library
+The `@memberjunction/core` library is the central package in the MemberJunction ecosystem, providing:
 
-```javascript
-import { Metadata } from '@memberjunction/core';
-```
+- **Metadata Management**: Complete access to MemberJunction metadata including entities, fields, relationships, permissions, and more
+- **Entity Data Access**: Base classes and utilities for loading, saving, and manipulating entity records
+- **View Execution**: Powerful view running capabilities for both stored and dynamic views
+- **Query & Report Execution**: Tools for running queries and reports
+- **Security & Authorization**: User authentication, role management, and permission handling
+- **Transaction Management**: Support for grouped database transactions
+- **Provider Architecture**: Flexible provider model supporting different execution environments
 
-### Working with the Metadata Class
+## Core Components
 
-The `Metadata` class is a crucial part of this library, providing access to a wide array of metadata, instantiating derived classes of `BaseEntity` for record access and manipulation, and more.
+### Metadata Class
 
-#### Instantiating the Metadata Class
+The `Metadata` class is the primary entry point for accessing MemberJunction metadata and instantiating entity objects.
 
-```javascript
-const md = new Metadata();
-```
+```typescript
+import { Metadata } from '@memberjunction/core';
 
-#### Refreshing Cached Metadata
+// Create metadata instance
+const md = new Metadata();
 
-```javascript
+// Refresh cached metadata
 await md.Refresh();
-```
-
-#### Getting Applications, Entities, and Other Info
 
-```javascript
+// Access various metadata collections
 const applications = md.Applications;
 const entities = md.Entities;
 const currentUser = md.CurrentUser;
-// ... and so on for other properties
+const roles = md.Roles;
+const authorizations = md.Authorizations;
 ```
 
-#### Helper Functions
+#### Key Metadata Properties
 
-```javascript
-// Get Entity ID from name
-const entityId = md.EntityIDFromName('EntityName');
+- `Applications`: Array of all applications in the system
+- `Entities`: Array of all entity definitions
+- `CurrentUser`: Current authenticated user (when available)
+- `Roles`: System roles
+- `AuditLogTypes`: Available audit log types
+- `Authorizations`: Authorization definitions
+- `Libraries`: Registered libraries
+- `Queries`: Query definitions
+- `QueryFields`: Query field metadata
+- `QueryCategories`: Query categorization
+- `QueryPermissions`: Query-level permissions
+- `VisibleExplorerNavigationItems`: Navigation items visible to current user
+- `AllExplorerNavigationItems`: All navigation items (including hidden)
 
-// Get Entity name from ID
-const entityName = md.EntityNameFromID(1);
+#### Helper Methods
 
-// ... and other helper functions as defined in the class
+```typescript
+// Get entity ID from name
+const entityId = md.EntityIDFromName('Users');
+
+// Get entity name from ID
+const entityName = md.EntityNameFromID('12345');
+
+// Find entity by name (case-insensitive)
+const userEntity = md.EntityByName('users');
+
+// Find entity by ID
+const entity = md.EntityByID('12345');
+
+// Get entity object instance (IMPORTANT: Always use this pattern)
+const user = await md.GetEntityObject<UserEntity>('Users');
 ```
 
-#### Working with Datasets
+### BaseEntity Class
+
+The `BaseEntity` class is the foundation for all entity record manipulation in MemberJunction. All entity classes generated by the MemberJunction code generator extend this class.
 
-```javascript
-// Example: Getting a dataset by name
-const dataset = await md.GetDatasetByName('DatasetName');
+```typescript
+import { Metadata } from '@memberjunction/core';
+
+// IMPORTANT: Never instantiate entity classes directly
+// Always use Metadata.GetEntityObject() to ensure proper class registration
+
+// ✅ Correct way to create entity instances
+const md = new Metadata();
+const user = await md.GetEntityObject<UserEntity>('Users');
+
+// Load a record by ID
+await user.Load(123);
+
+// Create a new record
+user.NewRecord();
+user.FirstName = 'John';
+user.LastName = 'Doe';
+user.Email = 'john.doe@example.com';
+
+// Save the record (creates new or updates existing)
+const saveResult = await user.Save();
+if (saveResult) {
+    console.log('User saved successfully:', user.ID);
+} else {
+    console.log('Save failed:', user.LatestResult.Message);
+}
+
+// Delete a record
+const deleteResult = await user.Delete();
 ```
 
-This is a brief overview of how to interact with the `Metadata` class. The methods and properties provided by the `Metadata` class serve as a bridge to access and manage data in a structured and coherent manner within the MemberJunction ecosystem.
+#### Entity Fields
 
-## RunView and RunViewParams
+Each entity field is represented by an `EntityField` object that tracks value, dirty state, and metadata:
 
-The `@memberjunction/core` library also provides a mechanism for running either a stored or dynamic view through the `RunView` class. The parameters for running these views are specified through the `RunViewParams` type.
+```typescript
+// Access field value
+const firstName = user.Get('FirstName');
 
-### Importing Necessary Classes and Types
+// Set field value
+user.Set('FirstName', 'Jane');
 
-```javascript
-import { RunView, RunViewParams } from '@memberjunction/core';
+// Check if field is dirty
+const isDirty = user.Fields.find(f => f.Name === 'FirstName').Dirty;
+
+// Access field metadata
+const field = user.Fields.find(f => f.Name === 'Email');
+console.log(field.IsUnique); // true/false
+console.log(field.IsPrimaryKey); // true/false
+console.log(field.ReadOnly); // true/false
 ```
 
-### Using RunViewParams
+#### Save Options
+
+```typescript
+import { EntitySaveOptions } from '@memberjunction/core';
+
+const options = new EntitySaveOptions();
+options.IgnoreDirtyState = true; // Force save even if no changes detected
+options.SkipEntityAIActions = true; // Skip AI-related actions
+options.SkipEntityActions = true; // Skip entity actions
+options.SkipOldValuesCheck = true; // Skip concurrency check (client-side only)
+
+await entity.Save(options);
+```
+
+### RunView Class
+
+The `RunView` class provides powerful view execution capabilities for both stored views and dynamic queries.
+
+```typescript
+import { RunView, RunViewParams } from '@memberjunction/core';
 
-`RunViewParams` is a type that helps in specifying the parameters required to run a view. The fields in `RunViewParams` allow you to specify whether you want to run a stored or dynamic view, and provide additional filters, sorting, and other options. Here's an example of how you might create a `RunViewParams` object:
+const rv = new RunView();
 
-```javascript
+// Run a stored view by name
 const params: RunViewParams = {
-    ViewName: 'MyView',
-    ExtraFilter: 'Age > 25',
-    OrderBy: 'LastName ASC',
-    Fields: ['FirstName', 'LastName'],
-    UserSearchString: 'Smith'
-    // ... other optional properties as needed
+    ViewName: 'Active Users',
+    ExtraFilter: 'CreatedDate > \'2024-01-01\'',
+    UserSearchString: 'john'
 };
+
+const results = await rv.RunView(params);
+
+// Run a dynamic view with entity objects returned
+const dynamicResults = await rv.RunView<UserEntity>({
+    EntityName: 'Users',
+    ExtraFilter: 'IsActive = 1',
+    OrderBy: 'LastName ASC, FirstName ASC',
+    Fields: ['ID', 'FirstName', 'LastName', 'Email'],
+    ResultType: 'entity_object' // Returns actual entity objects
+});
+
+// Access typed results
+const users = dynamicResults.Results; // Properly typed as UserEntity[]
 ```
 
-### Using the RunView Class
+#### RunView Parameters
+
+- `ViewID`: ID of stored view to run
+- `ViewName`: Name of stored view to run
+- `ViewEntity`: Pre-loaded view entity object (optimal for performance)
+- `EntityName`: Entity name for dynamic views
+- `ExtraFilter`: Additional SQL WHERE clause
+- `OrderBy`: SQL ORDER BY clause (overrides stored view sorting)
+- `Fields`: Array of field names to return
+- `UserSearchString`: User search term
+- `ExcludeUserViewRunID`: Exclude records from specific prior run
+- `ExcludeDataFromAllPriorViewRuns`: Exclude all previously returned records
+- `SaveViewResults`: Store run results for future exclusion
+- `IgnoreMaxRows`: Bypass entity MaxRows setting
+- `MaxRows`: Maximum rows to return
+- `StartRow`: Row offset for pagination
+- `ResultType`: 'simple' (default) or 'entity_object'
+
+### RunQuery Class
+
+Execute stored queries with parameters:
+
+```typescript
+import { RunQuery, RunQueryParams } from '@memberjunction/core';
+
+const rq = new RunQuery();
+
+const params: RunQueryParams = {
+    QueryID: '12345',
+    Parameters: {
+        StartDate: '2024-01-01',
+        EndDate: '2024-12-31',
+        Status: 'Active'
+    }
+};
+
+const results = await rq.RunQuery(params);
+```
 
-The `RunView` class provides a method to run a view based on the provided parameters. 
+### RunReport Class
 
-#### Instantiating the RunView Class
+Execute reports with various output formats:
 
-```javascript
-const rv = new RunView();
+```typescript
+import { RunReport, RunReportParams } from '@memberjunction/core';
+
+const rr = new RunReport();
+
+const params: RunReportParams = {
+    ReportID: '12345',
+    Parameters: {
+        Year: 2024,
+        Department: 'Sales'
+    }
+};
+
+const results = await rr.RunReport(params);
+```
+
+### Transaction Management
+
+Group multiple operations in a transaction:
+
+```typescript
+import { TransactionGroupBase } from '@memberjunction/core';
+
+// Transaction management is provider-specific
+// Consult your provider documentation for implementation details
+```
+
+## Entity Relationships
+
+MemberJunction automatically handles entity relationships through the metadata system:
+
+```typescript
+// Load an entity with related data
+const order = await md.GetEntityObject<OrderEntity>('Orders');
+await order.Load(123, ['OrderDetails', 'Customer']);
+
+// Access related entities
+const orderDetails = order.OrderDetails; // Array of OrderDetailEntity
+const customer = order.Customer; // CustomerEntity
+```
+
+## Security & Permissions
+
+The library provides comprehensive security features:
+
+```typescript
+const md = new Metadata();
+
+// Check current user
+const user = md.CurrentUser;
+console.log('Current user:', user.Email);
+
+// Check user roles
+const isAdmin = user.RoleName.includes('Admin');
+
+// Entity permissions
+const entity = md.EntityByName('Orders');
+const canCreate = entity.CanCreate;
+const canUpdate = entity.CanUpdate;
+const canDelete = entity.CanDelete;
 ```
 
-#### Running a View
+## Error Handling
+
+All operations return detailed error information:
+
+```typescript
+const entity = await md.GetEntityObject('Users');
+const result = await entity.Save();
+
+if (!result) {
+    // Access detailed error information
+    const error = entity.LatestResult;
+    console.error('Error:', error.Message);
+    console.error('Details:', error.Details);
+    
+    // Check validation errors
+    if (error.ValidationErrors && error.ValidationErrors.length > 0) {
+        error.ValidationErrors.forEach(ve => {
+            console.error(`Field ${ve.FieldName}: ${ve.Message}`);
+        });
+    }
+}
+```
 
-```javascript
-const result = await rv.RunView(params);
+## Provider Architecture
+
+MemberJunction uses a provider model to support different execution environments:
+
+```typescript
+import { SetProvider } from '@memberjunction/core';
+
+// Provider setup is typically handled by your application initialization
+// The provider determines how data is accessed (direct database, API, etc.)
+SetProvider(myProvider);
 ```
 
-In this example, `params` is an object of type `RunViewParams` which contains the information necessary to run the view. The `RunView` method will return a `Promise<RunViewResult>` which will contain the result of running the view.
+## Best Practices
+
+1. **Always use Metadata.GetEntityObject()** to create entity instances - never use `new`
+2. **Use generic types** with RunView for type-safe results
+3. **Handle errors properly** - check return values and LatestResult
+4. **Use transactions** for related operations that must succeed/fail together
+5. **Leverage metadata** for dynamic UI generation and validation
+6. **Respect permissions** - always check CanCreate/Update/Delete before operations
+7. **Use ExtraFilter** carefully - ensure SQL injection protection
+8. **Cache metadata instances** when possible to improve performance
+
+## Integration with Other MemberJunction Packages
+
+- **@memberjunction/global**: Global utilities and constants
+- **@memberjunction/server**: Server-side provider implementation
+- **@memberjunction/client**: Client-side provider implementation
+- **@memberjunction/angular**: Angular-specific components and services
+- **@memberjunction/react**: React-specific components and hooks
+- **@memberjunction/ai**: AI integration features
+- **@memberjunction/communication**: Communication and messaging features
+
+## Dependencies
+
+- **@memberjunction/global**: Core global utilities
+- **rxjs**: Reactive programming support
+- **zod**: Schema validation
+- **debug**: Debug logging
+
+## TypeScript Support
+
+This library is written in TypeScript and provides full type definitions. All generated entity classes include proper typing for IntelliSense support.
+
+## License
+
+ISC License - see LICENSE file for details
+
+## Support
 
+For support, documentation, and examples, visit [MemberJunction.com](https://www.memberjunction.com)