@memberjunction/global

Core global utilities and coordination library for MemberJunction applications. This package provides essential singleton management, class factory patterns, event coordination, and utility functions that are used throughout the MemberJunction ecosystem.

Installation

``bash
npm install @memberjunction/global
`

Overview

The @memberjunction/global library serves as the foundation for cross-component communication and coordination in MemberJunction applications. It provides:

- Global Singleton Management - Ensures true singleton instances across module boundaries
- Class Factory System - Dynamic class registration and instantiation with automatic root class detection
- Event System - RxJS-based event bus for component communication
- Object Caching - In-memory object cache for application lifetime
- Class Reflection Utilities - Runtime class hierarchy inspection and analysis
- Deep Diff Engine - Comprehensive object comparison and change tracking
- JSON Validator - Lightweight JSON validation with flexible rules and special syntax
- Warning Manager - Smart warning system with debouncing, batching, and session tracking
- Utility Functions - Common string manipulation, JSON parsing (including recursive nested JSON parsing), pattern matching, and formatting utilities

Core Components

$3

The central singleton class that coordinates events and manages components across your application.

`typescript
import { MJGlobal } from '@memberjunction/global';

// Get the singleton instance
const mjGlobal = MJGlobal.Instance;

// Register a component
mjGlobal.RegisterComponent(myComponent);

// Raise an event
mjGlobal.RaiseEvent({
component: myComponent,
event: MJEventType.ComponentEvent,
eventCode: 'CUSTOM_EVENT',
args: { data: 'example' }
});

// Listen for events
const subscription = mjGlobal.GetEventListener().subscribe(event => {
console.log('Event received:', event);
});

// Listen with replay (gets past events too)
const replaySubscription = mjGlobal.GetEventListener(true).subscribe(event => {
console.log('Event with replay:', event);
});
`

$3

Register and instantiate classes dynamically with automatic root class detection and inheritance chain support.

`typescript
import { RegisterClass, MJGlobal } from '@memberjunction/global';

// Define a base class hierarchy
class BaseProcessor {
process(data: any): void {
console.log('Base processing');
}
}

class SpecialProcessor extends BaseProcessor {
process(data: any): void {
console.log('Special processing');
}
}

// Register a subclass - automatically registers with root class (BaseProcessor)
@RegisterClass(SpecialProcessor, 'custom')
class CustomProcessor extends SpecialProcessor {
process(data: any): void {
console.log('Custom processing');
}
}

// Create instances via the factory
const factory = MJGlobal.Instance.ClassFactory;
const processor = factory.CreateInstance(BaseProcessor, 'custom');
processor.process(data); // Uses CustomProcessor

// Key Features:
// 1. Auto-registers with root class by default (BaseProcessor in this case)
// 2. Ensures proper priority ordering in inheritance chains
// 3. Can opt-out with autoRegisterWithRootClass: false
@RegisterClass(SpecialProcessor, 'special', 0, false, false) // Last param disables auto-root registration
class DirectRegistration extends SpecialProcessor {
// This registers directly to SpecialProcessor, not BaseProcessor
}
`

$3

In-memory caching system for application-lifetime object storage.

`typescript
const cache = MJGlobal.Instance.ObjectCache;

// Add an object to cache
cache.Add('user:123', { id: 123, name: 'John Doe' });

// Find an object
const user = cache.Find('user:123');

// Replace an existing object
cache.Replace('user:123', { id: 123, name: 'Jane Doe' });

// Remove from cache
cache.Remove('user:123');

// Clear all cached objects
cache.Clear();
`

$3

Abstract base class for creating global singleton instances that persist across module boundaries.

`typescript
import { BaseSingleton } from '@memberjunction/global';

export class MyService extends BaseSingleton {
private data: string[] = [];

public static get Instance(): MyService {
return super.getInstance();
}

public addData(item: string): void {
this.data.push(item);
}
}

// Usage anywhere in your app
const service = MyService.Instance;
service.addData('example');
`

$3

Runtime utilities for inspecting and analyzing class hierarchies.

`typescript
import {
GetSuperclass,
GetRootClass,
IsSubclassOf,
IsRootClass,
IsDescendantClassOf,
GetClassInheritance,
GetFullClassHierarchy,
IsClassConstructor,
GetClassName
} from '@memberjunction/global';

// Example class hierarchy
class Animal {}
class Mammal extends Animal {}
class Dog extends Mammal {}
class GoldenRetriever extends Dog {}

// Get immediate superclass
const parent = GetSuperclass(GoldenRetriever); // Returns: Dog

// Get root class of hierarchy
const root = GetRootClass(GoldenRetriever); // Returns: Animal

// Check inheritance relationships
IsSubclassOf(GoldenRetriever, Animal); // true (checks entire chain)
IsDescendantClassOf(GoldenRetriever, Animal); // true (alias for IsSubclassOf)
IsRootClass(Animal); // true
IsRootClass(Dog); // false

// Get inheritance chain
const chain = GetClassInheritance(GoldenRetriever);
// Returns: [
// { name: 'Dog', reference: Dog },
// { name: 'Mammal', reference: Mammal },
// { name: 'Animal', reference: Animal }
// ]

// Get full hierarchy including the class itself
const fullChain = GetFullClassHierarchy(GoldenRetriever);
// Returns: [
// { name: 'GoldenRetriever', reference: GoldenRetriever },
// { name: 'Dog', reference: Dog },
// { name: 'Mammal', reference: Mammal },
// { name: 'Animal', reference: Animal }
// ]

// Utility functions
IsClassConstructor(Dog); // true
IsClassConstructor(() => {}); // false
GetClassName(GoldenRetriever); // "GoldenRetriever"
`

$3

Comprehensive object comparison and change tracking with hierarchical diff visualization.

`typescript
import { DeepDiffer, DiffChangeType } from '@memberjunction/global';

// Create a differ instance
const differ = new DeepDiffer({
includeUnchanged: false, // Don't track unchanged values
maxDepth: 10, // Maximum recursion depth
maxStringLength: 100, // Truncate long strings
treatNullAsUndefined: false // Treat null and undefined as distinct (default: false)
});

// Compare two objects
const oldData = {
user: { name: 'John', age: 30, role: 'admin' },
settings: { theme: 'dark', notifications: true },
tags: ['important', 'active']
};

const newData = {
user: { name: 'John', age: 31, role: 'superadmin' },
settings: { theme: 'light', notifications: true, language: 'en' },
tags: ['important', 'active', 'premium']
};

// Get the diff
const result = differ.diff(oldData, newData);

// Access summary
console.log(result.summary);
// { added: 2, removed: 0, modified: 3, unchanged: 3, total: 8 }

// Iterate through changes
result.changes.forEach(change => {
console.log(${change.path}: ${change.type} - ${change.description});
});
// Output:
// user.age: Modified - Changed from 30 to 31
// user.role: Modified - Changed from "admin" to "superadmin"
// settings.theme: Modified - Changed from "dark" to "light"
// settings.language: Added - Value: "en"
// tags[2]: Added - Value: "premium"

// Filter changes by type
const additions = result.changes.filter(c => c.type === DiffChangeType.Added);
const modifications = result.changes.filter(c => c.type === DiffChangeType.Modified);

// Update configuration on the fly
differ.updateConfig({ includeUnchanged: true });
`

#### Treating null as undefined

When working with APIs or databases where null and undefined are used interchangeably, you can enable the treatNullAsUndefined option:

`typescript
const differ = new DeepDiffer({ treatNullAsUndefined: true });

const oldData = {
name: null,
status: 'active',
oldProp: 'value'
};

const newData = {
name: 'John', // Will show as "Added" instead of "Modified"
status: null, // Will show as "Removed" instead of "Modified"
newProp: 'value'
};

const result = differ.diff(oldData, newData);
// With treatNullAsUndefined: true
// - name: Added (not Modified, since null is treated as non-existent)
// - status: Removed (not Modified, since null is treated as non-existent)
// - oldProp: Removed
// - newProp: Added
`

$3

Lightweight JSON validation with flexible validation rules and special field suffixes.

`typescript
import { JSONValidator } from '@memberjunction/global';

// Create validator instance
const validator = new JSONValidator();

// Define validation template with rules
const template = {
name: "John Doe", // Required field
email?: "user@example.com", // Optional field
settings*: {}, // Required, any content allowed
tags:[1+]: ["tag1"], // Array with at least 1 item
age:number: 25, // Must be a number
username:string:!empty: "johndoe", // Non-empty string
items:array:[2-5]?: ["A", "B"] // Optional array with 2-5 items
};

// Validate data against template
const data = {
name: "Jane Smith",
tags: ["work", "urgent"],
age: 30,
username: "jsmith"
};

const result = validator.validate(data, template);
if (result.Success) {
console.log('Validation passed!');
} else {
result.Errors.forEach(error => {
console.log(${error.Source}: ${error.Message});
});
}
`

#### Validation Syntax

Field Suffixes:
- ? - Optional field (e.g., email?)
- - Required field with any content/structure (e.g., payload)

Validation Rules (using : delimiter):
- Array Length:
- [N+] - At least N elements (e.g., tags:[1+])
- [N-M] - Between N and M elements (e.g., items:[2-5])
- [=N] - Exactly N elements (e.g., coordinates:[=2])

- Type Checking:
- string - Must be a string
- number - Must be a number (NaN fails validation)
- boolean - Must be a boolean
- object - Must be an object (not array or null)
- array - Must be an array

- Value Constraints:
- !empty - Non-empty string, array, or object

Combining Rules:
Multiple validation rules can be combined with : delimiter:
`typescript
{
// Array of strings with 2+ items
"tags:array:[2+]": ["important", "urgent"],

// Non-empty string
"username:string:!empty": "johndoe",

// Optional number
"score:number?": 85,

// Optional array with 1-3 items
"options:array:[1-3]?": ["A", "B"]
}
`

#### Nested Object Validation

The validator recursively validates nested objects:

`typescript
const template = {
user: {
id:number: 123,
name:string:!empty: "John",
roles:array:[1+]: ["admin"]
},
settings?: {
theme: "dark",
notifications:boolean: true
}
};
`

#### Cleaning Validation Syntax

The validator can clean validation syntax from JSON objects that may have been returned by AI systems:

`typescript
// AI might return JSON with validation syntax in keys
const aiResponse = {
"name?": "John Doe",
"email:string": "john@example.com",
"tags:[2+]": ["work", "urgent"],
"settings*": { theme: "dark" },
"score:number:!empty": 85
};

// Clean the validation syntax
const cleaned = validator.cleanValidationSyntax(aiResponse);
// Returns:
// {
// "name": "John Doe",
// "email": "john@example.com",
// "tags": ["work", "urgent"],
// "settings": { theme: "dark" },
// "score": 85
// }
`

The cleanValidationSyntax method:
- Recursively processes all object keys
- Removes validation suffixes (?, *)
- Removes validation rules (:type, :[N+], :!empty, etc.)
- Preserves the original values unchanged
- Handles nested objects and arrays
- Returns a new object with cleaned keys

#### Convenience Methods

`typescript
// Validate against JSON string
const schemaJson = '{"name": "string", "age:number": 0}';
const result = validator.validateAgainstSchema(data, schemaJson);

// Integration with MemberJunction ValidationResult
// Returns standard ValidationResult with ValidationErrorInfo[]
// Compatible with existing MJ validation patterns
`

#### Use Cases

1. API Response Validation:
`typescript
const apiResponseTemplate = {
status:string: "success",
data*: {}, // Any data structure allowed
errors:array?: []
};
`

2. Configuration Validation:
`typescript
const configTemplate = {
apiUrl:string:!empty: "https://api.example.com",
timeout:number: 5000,
retries:number: 3,
features:array:[1+]: ["logging"]
};
`

3. Form Data Validation:
`typescript
const formTemplate = {
username:string:!empty: "user",
email:string: "user@example.com",
age:number?: 25,
preferences:object?: {
notifications:boolean: true
}
};
`

Event Types

The library provides predefined event types for common scenarios:

`typescript
export const MJEventType = {
ComponentRegistered: 'ComponentRegistered',
ComponentUnregistered: 'ComponentUnregistered',
ComponentEvent: 'ComponentEvent',
LoggedIn: 'LoggedIn',
LoggedOut: 'LoggedOut',
LoginFailed: 'LoginFailed',
LogoutFailed: 'LogoutFailed',
ManualResizeRequest: 'ManualResizeRequest',
DisplaySimpleNotificationRequest: 'DisplaySimpleNotificationRequest',
} as const;
`

Utility Functions

$3

`typescript
import {
convertCamelCaseToHaveSpaces,
stripWhitespace,
generatePluralName,
adjustCasing,
stripTrailingChars,
replaceAllSpaces
} from '@memberjunction/global';

// Convert camel case to spaces
convertCamelCaseToHaveSpaces('AIAgentLearningCycle'); // "AI Agent Learning Cycle"

// Remove all whitespace
stripWhitespace(' Hello World '); // "HelloWorld"

// Generate plural forms
generatePluralName('child'); // "children"
generatePluralName('box'); // "boxes"
generatePluralName('party'); // "parties"

// Adjust casing
adjustCasing('hello', { capitalizeFirstLetterOnly: true }); // "Hello"
adjustCasing('world', { capitalizeEntireWord: true }); // "WORLD"

// Strip trailing characters
stripTrailingChars('example.txt', '.txt', false); // "example"

// Remove all spaces
replaceAllSpaces('Hello World'); // "HelloWorld"
`

$3

`typescript
import { CleanJSON, SafeJSONParse, ParseJSONRecursive } from '@memberjunction/global';

// Safe JSON parsing with error handling
const parsed = SafeJSONParse('{"key": "value"}', true);

// Recursively parse JSON strings within objects
const input = {
data: '{"nested": "{\\"deeply\\": \\"nested\\"}"}',
messages: '[{"content": "{\\"type\\": \\"greeting\\", \\"text\\": \\"Hello\\"}"}]'
};
const output = ParseJSONRecursive(input);
// Returns: {
// data: { nested: { deeply: "nested" } },
// messages: [{ content: { type: "greeting", text: "Hello" } }]
// }

// Extract inline JSON from text strings
const textWithJson = {
result: 'Action completed: {"status": "success", "count": 42}'
};
const extracted = ParseJSONRecursive(textWithJson, { extractInlineJson: true });
// Returns: {
// result: "Action completed:",
// result_: { status: "success", count: 42 }
// }

// Control recursion depth and enable debugging
const deeplyNested = ParseJSONRecursive(complexData, {
maxDepth: 50, // Default: 100
extractInlineJson: true, // Default: false
debug: true // Default: false, logs parsing steps
});
`

#### CleanJSON Function

The CleanJSON function intelligently extracts and cleans JSON from various input formats, including double-escaped strings, strings with embedded JSON, and markdown code blocks. It's particularly useful when dealing with AI-generated responses or data from external systems that may have inconsistent JSON formatting.

Processing Order:
1. First attempts to parse the input as valid JSON (preserving embedded content)
2. If that fails, handles double-escaped characters (\\n, \\", etc.)
3. Only extracts from markdown blocks or inline JSON as a last resort

`typescript
import { CleanJSON } from '@memberjunction/global';

// Example 1: Already valid JSON - returns formatted
const valid = CleanJSON('{"name": "test", "value": 123}');
// Returns:
// {
// "name": "test",
// "value": 123
// }

// Example 2: Double-escaped JSON string
const escaped = CleanJSON('{\\"name\\": \\"test\\", \\"value\\": 123}');
// Returns:
// {
// "name": "test",
// "value": 123
// }

// Example 3: JSON with escaped newlines (common from AI responses)
const withNewlines = CleanJSON('\\n{\\"mode\\": \\"test\\",\\n\\"data\\": [1, 2, 3]}\\n');
// Returns:
// {
// "mode": "test",
// "data": [1, 2, 3]
// }

// Example 4: Complex JSON with embedded markdown (preserves the markdown)
const complexJson = CleanJSON({
"taskComplete": false,
"message": "Processing complete",
"nextAction": {
"type": "design",
"payload": {
"outputFormat": "\\\json\\n{\\"componentName\\": \\"Example\\"}\\n\\\"
}
}
});
// Returns the JSON with the markdown code block preserved in the outputFormat field

// Example 5: Extract JSON from markdown (only when input isn't valid JSON)
const markdown = CleanJSON('Some text `json\n{"extracted": true}\n` more text');
// Returns:
// {
// "extracted": true
// }

// Example 6: Extract inline JSON from mixed text
const mixed = CleanJSON('Response: {"status": "success", "code": 200} - Done');
// Returns:
// {
// "status": "success",
// "code": 200
// }

// Example 7: Complex real-world example with nested escaped JSON
const aiResponse = CleanJSON({
"analysis": "Complete",
"data": "{\\"users\\": [{\\"name\\": \\"John\\", \\"active\\": true}]}",
"metadata": {
"template": "\\\json\\n{\\"format\\": \\"standard\\"}\\n\\\"
}
});
// Returns properly formatted JSON with all nested structures intact
`

Key Features:
- Preserves embedded content: When the input is valid JSON, markdown blocks and escaped strings within values are preserved
- Smart unescaping: Handles \\n → \n, \\" → ", \\\\ → \ and other common escape sequences
- Markdown extraction: Extracts JSON from ``json code blocks when needed
- Inline extraction: Finds JSON objects/arrays within surrounding text
- Null safety: Returns null for invalid inputs instead of throwing errors

Common Use Cases:
- Processing AI model responses that may contain escaped JSON
- Cleaning data from external APIs with inconsistent formatting
- Extracting JSON from log files or debug output
- Handling JSON strings stored in databases that may be double-escaped
- Processing user input that may contain JSON in various formats

$3

``typescript
import { ConvertMarkdownStringToHtmlList } from '@memberjunction/global';

// Convert markdown to HTML list
const html = ConvertMarkdownStringToHtmlList('Unordered', '- Item 1\n- Item 2\n- Item 3');
// Returns:

• Item 1
• Item 2
• Item 3


`

$3

The Warning Manager provides intelligent warning batching and deduplication for console messages across your application. It tracks warnings per session, groups them by type, and displays them in clean, formatted output after a configurable debounce period.

#### Features

- Session-level tracking - Each warning shown only once per session
- Debounced output - Groups warnings and displays after a configurable quiet period (default 10s)
- Multiple warning types - Supports deprecation warnings and data integrity warnings
- Beautiful formatting - Tree-structured console output with emojis and clear grouping
- Configurable - Runtime API and environment variables for customization
- Backward compatible - DeprecationWarningManager alias provided

#### Basic Usage

`typescript
import { WarningManager } from '@memberjunction/global';

const wm = WarningManager.Instance;

// Record deprecation warnings
wm.RecordEntityDeprecationWarning('LegacyEntity', 'MyComponent::method');
wm.RecordFieldDeprecationWarning('Users', 'OldField', 'DataLoader::process');

// Record field-not-found warnings (data integrity issues)
wm.RecordFieldNotFoundWarning('Users', 'DeletedColumn', 'BaseEntity::SetMany during import');

// Warnings are automatically batched and displayed after debounce period
// Or manually flush immediately:
wm.FlushWarnings();
`

#### Example Output

`
⚠️ DEPRECATION WARNINGS - The following entities/fields are deprecated and may be removed in future versions:

📦 DEPRECATED ENTITIES:
• "LegacyEntity" (called from: MyComponent::method)

📋 DEPRECATED ENTITY FIELDS:
└─ "Users"
└─ OldField (called from: DataLoader::process)

💡 Set ShowAll=true in configuration to see every occurrence.


⚠️ DATA INTEGRITY WARNINGS - The following fields were not found in entity definitions:

📋 MISSING FIELDS:
└─ "Users"
└─ DeletedColumn (context: BaseEntity::SetMany during import)

💡 These fields exist in your data but not in the entity schema. This may indicate:
• Schema is out of sync with database
• Data contains legacy fields that were removed
• Field names have been changed
`

#### Configuration

Configure via runtime API:

`typescript
wm.UpdateConfig({
DebounceMs: 5000, // Wait 5 seconds after last warning
ShowAll: false, // Show each warning once per session (default)
DisableWarnings: false, // Enable warnings (default)
GroupWarnings: true // Group warnings in tree format (default)
});

// Get current configuration
const config = wm.GetConfig();
`

All configuration is done via the runtime API.

#### Warning Types

Deprecation Warnings indicate entities or fields that may be removed in future versions:
- RecordEntityDeprecationWarning(entityName, callerName) - Deprecated entity
- RecordFieldDeprecationWarning(entityName, fieldName, callerName) - Deprecated field

Data Integrity Warnings indicate mismatches between data and schema:
- RecordFieldNotFoundWarning(entityName, fieldName, context) - Field exists in data but not in schema

#### Advanced Usage

`typescript
// Reset all tracking (useful for testing)
wm.Reset();

// Backward compatibility - DeprecationWarningManager is an alias
import { DeprecationWarningManager } from '@memberjunction/global';
const dwm = DeprecationWarningManager.Instance; // Same as WarningManager.Instance
`

#### Use Cases

1. Framework-level warnings - Alert developers about deprecated APIs
2. Data migration - Track fields that don't match current schema
3. Development debugging - Identify outdated code patterns
4. Testing - Verify no deprecated features are used

$3

Secure boolean expression evaluation for conditional logic without allowing arbitrary code execution:

`typescript
import { SafeExpressionEvaluator } from '@memberjunction/global';

// Create evaluator instance
const evaluator = new SafeExpressionEvaluator();

// Simple comparisons
const result1 = evaluator.evaluate(
"status == 'active' && score > 80",
{ status: 'active', score: 95 }
);
console.log(result1.success); // true
console.log(result1.value); // true

// Nested property access with dot notation
const result2 = evaluator.evaluate(
"user.role == 'admin' && user.permissions.includes('write')",
{
user: {
role: 'admin',
permissions: ['read', 'write', 'delete']
}
}
);
console.log(result2.value); // true

// Array methods and complex conditions
const result3 = evaluator.evaluate(
"items.some(item => item.price > 100) && items.length >= 2",
{
items: [
{ name: 'Item 1', price: 50 },
{ name: 'Item 2', price: 150 }
]
}
);
console.log(result3.value); // true

// Error handling for invalid expressions
const result4 = evaluator.evaluate(
"eval('malicious code')", // Dangerous patterns are blocked
{ data: 'test' }
);
console.log(result4.success); // false
console.log(result4.error); // "Expression contains forbidden construct: /\beval\s*\(/i"

// With diagnostics enabled
const result5 = evaluator.evaluate(
"payload.status == 'complete'",
{ payload: { status: 'complete' } },
true // Enable diagnostics
);
console.log(result5.diagnostics);
// {
// expression: "payload.status == 'complete'",
// context: { payload: { status: 'complete' } },
// evaluationTime: 2
// }
`

#### Supported Operations

Comparison Operators:
- ==, ===, !=, !==
- <, >, <=, >=

Logical Operators:
- &&, ||, !

Property Access:
- Dot notation: object.property.nested
- Array access: array[0], array[index]

Safe Methods:
- String: .length, .includes(), .startsWith(), .endsWith(), .toLowerCase(), .toUpperCase(), .trim()
- Array: .length, .includes(), .some(), .every(), .find(), .filter(), .map()
- Type checking: typeof, limited instanceof

Type Coercion:
- Boolean(value)
- String concatenation with +

#### Security Features

The evaluator blocks dangerous patterns including:
- eval(), Function(), new Function()
- require(), import statements
- Access to global, window, document, process
- Template literals and string interpolation
- Code blocks with {} and ;
- this keyword usage
- constructor, prototype, __proto__ access

#### Use Cases

1. Workflow Conditions:
`typescript
// Evaluate workflow paths
const canProceed = evaluator.evaluate(
"order.status == 'approved' && order.total < budget",
{ order: { status: 'approved', total: 500 }, budget: 1000 }
).value;
`

2. Feature Flags:
`typescript
// Check feature availability
const featureEnabled = evaluator.evaluate(
"user.tier == 'premium' || user.roles.includes('beta')",
{ user: { tier: 'standard', roles: ['beta', 'tester'] } }
).value;
`

3. Validation Rules:
`typescript
// Dynamic validation
const isValid = evaluator.evaluate(
"form.password.length >= 8 && form.password != form.username",
{ form: { username: 'john', password: 'secretpass123' } }
).value;
`

4. Agent Decision Logic:
`typescript
// AI agent path selection
const shouldDelegate = evaluator.evaluate(
"confidence < 0.7 || taskComplexity > 8",
{ confidence: 0.6, taskComplexity: 5 }
).value;
`

#### Batch Evaluation

Evaluate multiple expressions at once:

`typescript
const results = evaluator.evaluateMultiple([
{ expression: "status == 'active'", name: 'isActive' },
{ expression: "score > threshold", name: 'passedThreshold' },
{ expression: "tags.includes('priority')", name: 'isPriority' }
], {
status: 'active',
score: 85,
threshold: 80,
tags: ['urgent', 'priority']
});

// Results:
// {
// isActive: { success: true, value: true },
// passedThreshold: { success: true, value: true },
// isPriority: { success: true, value: true }
// }
`

$3

Convert string patterns to RegExp objects with support for simple wildcards and full regex syntax:

`typescript
import {
parsePattern,
parsePatterns,
ensureRegExp,
ensureRegExps,
matchesAnyPattern,
matchesAllPatterns
} from '@memberjunction/global';

// Parse simple wildcard patterns
parsePattern('AIPrompt'); // Returns: /AIPrompt/i (case-insensitive)
parsePattern('spCreate*'); // Returns: /^spCreate/i
parsePattern('*Run'); // Returns: /Run$/i
parsePattern('exact'); // Returns: /^exact$/i

// Parse regex string patterns
parsePattern('/spCreate.Run/i'); // Returns: /spCreate.Run/i
parsePattern('/^SELECT.FROM.vw/'); // Returns: /^SELECT.FROM.vw/
parsePattern('/INSERT INTO (Users|Roles)/i'); // Returns: /INSERT INTO (Users|Roles)/i

// Parse multiple patterns at once
const patterns = parsePatterns([
'User', // Simple wildcard
'/^EXEC sp_/i', // Regex string
'EntityFieldValue' // Simple wildcard
]);

// Convert mixed string/RegExp arrays
const mixed = ['User', /^Admin/i, '/DELETE.*WHERE/i'];
const regexps = ensureRegExps(mixed); // All converted to RegExp objects

// Test if text matches any pattern
const sql = 'SELECT * FROM Users WHERE Active = 1';
matchesAnyPattern(sql, ['User', 'Role', '/^UPDATE/i']); // true

// Test if text matches all patterns
const filename = 'UserRoleManager.ts';
matchesAllPatterns(filename, ['User', 'Role', '*.ts']); // true
`

#### Pattern Syntax

Simple Wildcard Patterns (Recommended for most users):
- * acts as a wildcard matching any characters
- Case-insensitive by default
- Examples:
- pattern - Contains "pattern" anywhere
- pattern* - Starts with "pattern"
- *pattern - Ends with "pattern"
- pattern - Exact match only

Regex String Patterns (For advanced users):
- Must start with / to be recognized as regex
- Optionally end with flags like /pattern/i
- Full JavaScript regex syntax supported
- Examples:
- /^start/i - Case-insensitive start match
- /end$/ - Case-sensitive end match
- /(option1|option2)/ - Match alternatives

#### Common Use Cases

`typescript
// SQL statement filtering
const sqlFilters = [
'AIPrompt', // Exclude AI prompt operations
'/^EXEC sp_/i', // Exclude system stored procedures
'EntityFieldValue' // Exclude field value operations
];

const shouldLog = !matchesAnyPattern(sqlStatement, sqlFilters);

// File pattern matching
const includePatterns = ['.ts', '.js', '/^(?!test)/']; // TS/JS files not starting with "test"
const shouldProcess = matchesAnyPattern(filename, includePatterns);

// User input validation
const allowedFormats = ['@.com', '@.org', '*@company.net'];
const isValidEmail = matchesAnyPattern(email, allowedFormats);
`

$3

Access the global object store for cross-module state sharing:

`typescript
import { GetGlobalObjectStore } from '@memberjunction/global';

const globalStore = GetGlobalObjectStore();
// Returns window object in browser, global in Node.js
`

$3

Trigger a manual resize event across components:

`typescript
import { InvokeManualResize } from '@memberjunction/global';

// Request resize after 50ms delay
InvokeManualResize(50, myComponent);
`

Advanced Usage

$3

The Class Factory automatically detects and uses root classes for registration, ensuring proper priority ordering in inheritance hierarchies:

`typescript
class BaseEntity {} // Root class

class UserEntity extends BaseEntity {}

// This automatically registers with BaseEntity (the root)
@RegisterClass(UserEntity, 'Admin')
class AdminUserEntity extends UserEntity {}

// Also registers with BaseEntity, gets higher priority
@RegisterClass(AdminUserEntity, 'SuperAdmin')
class SuperAdminEntity extends AdminUserEntity {}

// All of these create SuperAdminEntity (highest priority)
factory.CreateInstance(BaseEntity, 'SuperAdmin'); // ✓ Works
factory.CreateInstance(UserEntity, 'SuperAdmin'); // ✓ Works
factory.CreateInstance(AdminUserEntity, 'SuperAdmin'); // ✓ Works
`

$3

Sometimes you want to register at a specific level in the hierarchy:

`typescript
// Register directly to UserEntity, not BaseEntity
@RegisterClass(UserEntity, 'Special', 0, false, false) // Last param = false
class SpecialUserEntity extends UserEntity {
// This only matches when creating from UserEntity, not BaseEntity
}

// Direct registration queries
factory.CreateInstance(UserEntity, 'Special'); // ✓ Returns SpecialUserEntity
factory.CreateInstance(BaseEntity, 'Special'); // ✗ Returns BaseEntity instance
`

$3

`typescript
// Register a class that requires constructor parameters
@RegisterClass(BaseService, 'api')
class ApiService extends BaseService {
constructor(private apiUrl: string) {
super();
}
}

// Create with parameters
const service = factory.CreateInstance(
BaseService,
'api',
'https://api.example.com'
);
`

$3

`typescript
// Lower priority (registered first)
@RegisterClass(BaseHandler, 'data', 10)
class BasicDataHandler extends BaseHandler {}

// Higher priority (overrides BasicDataHandler)
@RegisterClass(BaseHandler, 'data', 20)
class AdvancedDataHandler extends BaseHandler {}

// Will create AdvancedDataHandler instance
const handler = factory.CreateInstance(BaseHandler, 'data');
`

$3

`typescript
// Get all registrations for a base class
const registrations = factory.GetAllRegistrations(BaseEntity, 'Users');

// Get registrations by root class
const rootRegistrations = factory.GetRegistrationsByRootClass(BaseEntity);

// Each registration contains:
// - BaseClass: The class it's registered to (usually root)
// - SubClass: The actual implementation class
// - RootClass: The detected root of the hierarchy
// - Key: The registration key
// - Priority: The priority number
`

$3

Store and retrieve global properties:

`typescript
const properties = MJGlobal.Instance.Properties;
properties.push({
key: 'apiEndpoint',
value: 'https://api.example.com'
});
`

Integration with MemberJunction

This package is a core dependency for most MemberJunction packages. It provides the foundation for:

- Entity registration and instantiation
- Cross-component event communication
- Singleton service management
- Global state coordination

When building MemberJunction applications or extensions, use this package to ensure proper integration with the framework's architecture.

TypeScript Support

This package is written in TypeScript and includes full type definitions. All exports are properly typed for excellent IDE support and compile-time type checking.

Dependencies

- rxjs (^7.8.1) - For reactive event handling

Development

`bash


Build the package

npm run build

Start in development mode with hot reload

npm run start

Run tests (when implemented)

npm test
``

License

ISC

Author

MemberJunction.com