@memberjunction/metadata-sync 2.46.0 → 2.48.0

package/dist/lib/sync-engine.d.ts

@@ -1,49 +1,283 @@
+/**
+ * @fileoverview Core synchronization engine for MemberJunction metadata
+ * @module sync-engine
+ *
+ * This module provides the core functionality for synchronizing metadata between
+ * the MemberJunction database and local file system representations. It handles
+ * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),
+ * manages entity operations, and provides utilities for data transformation.
+ */
 import { EntityInfo, BaseEntity, UserInfo } from '@memberjunction/core';
 import { EntityConfig } from '../config';
+/**
+ * Represents the structure of a metadata record with optional sync tracking
+ */
 export interface RecordData {
+    /** Primary key field(s) and their values */
     primaryKey?: Record<string, any>;
+    /** Entity field names and their values */
     fields: Record<string, any>;
+    /** Related entities organized by entity name */
     relatedEntities?: Record<string, RecordData[]>;
+    /** Synchronization metadata for change tracking */
     sync?: {
+        /** ISO timestamp of last modification */
         lastModified: string;
+        /** SHA256 checksum of the fields object */
         checksum: string;
     };
 }
+/**
+ * Core engine for synchronizing MemberJunction metadata between database and files
+ *
+ * @class SyncEngine
+ * @example
+ * ```typescript
+ * const syncEngine = new SyncEngine(systemUser);
+ * await syncEngine.initialize();
+ *
+ * // Process a field value with special references
+ * const value = await syncEngine.processFieldValue('@lookup:Users.Email=admin@example.com', '/path/to/base');
+ * ```
+ */
 export declare class SyncEngine {
     private metadata;
     private contextUser;
+    /**
+     * Creates a new SyncEngine instance
+     * @param contextUser - The user context for database operations
+     */
     constructor(contextUser: UserInfo);
+    /**
+     * Initializes the sync engine by refreshing metadata cache
+     * @returns Promise that resolves when initialization is complete
+     */
     initialize(): Promise<void>;
     /**
      * Process special references in field values
+     *
+     * Handles the following reference types:
+     * - `@parent:fieldName` - References a field from the parent record
+     * - `@root:fieldName` - References a field from the root record
+     * - `@file:path` - Reads content from an external file
+     * - `@url:address` - Fetches content from a URL
+     * - `@lookup:Entity.Field=Value` - Looks up an entity ID by field value
+     * - `@env:VARIABLE` - Reads an environment variable
+     *
+     * @param value - The field value to process
+     * @param baseDir - Base directory for resolving relative file paths
+     * @param parentRecord - Optional parent entity for @parent references
+     * @param rootRecord - Optional root entity for @root references
+     * @returns The processed value with all references resolved
+     * @throws Error if a reference cannot be resolved
+     *
+     * @example
+     * ```typescript
+     * // File reference
+     * const content = await processFieldValue('@file:template.md', '/path/to/dir');
+     *
+     * // Lookup with auto-create
+     * const userId = await processFieldValue('@lookup:Users.Email=john@example.com?create', '/path');
+     * ```
      */
     processFieldValue(value: any, baseDir: string, parentRecord?: BaseEntity | null, rootRecord?: BaseEntity | null): Promise<any>;
     /**
      * Resolve a lookup reference to an ID, optionally creating the record if it doesn't exist
+     *
+     * @param entityName - Name of the entity to search in
+     * @param fieldName - Field to match against
+     * @param fieldValue - Value to search for
+     * @param autoCreate - Whether to create the record if not found
+     * @param createFields - Additional fields to set when creating
+     * @returns The ID of the found or created record
+     * @throws Error if lookup fails and autoCreate is false
+     *
+     * @example
+     * ```typescript
+     * // Simple lookup
+     * const categoryId = await resolveLookup('Categories', 'Name', 'Technology');
+     *
+     * // Lookup with auto-create
+     * const tagId = await resolveLookup('Tags', 'Name', 'New Tag', true, {
+     *   Description: 'Auto-created tag',
+     *   Status: 'Active'
+     * });
+     * ```
      */
     resolveLookup(entityName: string, fieldName: string, fieldValue: string, autoCreate?: boolean, createFields?: Record<string, any>): Promise<string>;
     /**
      * Build cascading defaults for a file path and process field values
+     *
+     * Walks up the directory tree from the file location, collecting defaults from
+     * entity config and folder configs, with deeper folders overriding parent values.
+     * All default values are processed for special references.
+     *
+     * @param filePath - Path to the file being processed
+     * @param entityConfig - Entity configuration containing base defaults
+     * @returns Processed defaults with all references resolved
+     * @throws Error if any default value processing fails
      */
     buildDefaults(filePath: string, entityConfig: EntityConfig): Promise<Record<string, any>>;
     /**
-     * Load folder configuration
+     * Load folder configuration from .mj-folder.json file
+     *
+     * @param dir - Directory to check for configuration
+     * @returns Folder configuration or null if not found/invalid
+     * @private
      */
     private loadFolderConfig;
     /**
-     * Calculate checksum for data
+     * Calculate SHA256 checksum for data
+     *
+     * Generates a deterministic hash of the provided data by converting it to
+     * formatted JSON and calculating a SHA256 digest. Used for change detection
+     * in sync operations.
+     *
+     * @param data - Any data structure to calculate checksum for
+     * @returns Hexadecimal string representation of the SHA256 hash
+     *
+     * @example
+     * ```typescript
+     * const checksum = syncEngine.calculateChecksum({
+     *   name: 'Test Record',
+     *   value: 42,
+     *   tags: ['a', 'b']
+     * });
+     * // Returns consistent hash for same data structure
+     * ```
      */
     calculateChecksum(data: any): string;
     /**
-     * Get entity info by name
+     * Get entity metadata information by name
+     *
+     * Retrieves the EntityInfo object containing schema metadata for the specified entity.
+     * Returns null if the entity is not found in the metadata cache.
+     *
+     * @param entityName - Name of the entity to look up
+     * @returns EntityInfo object with schema details or null if not found
+     *
+     * @example
+     * ```typescript
+     * const entityInfo = syncEngine.getEntityInfo('AI Prompts');
+     * if (entityInfo) {
+     *   console.log(`Primary keys: ${entityInfo.PrimaryKeys.map(pk => pk.Name).join(', ')}`);
+     * }
+     * ```
      */
     getEntityInfo(entityName: string): EntityInfo | null;
     /**
-     * Create a new entity object
+     * Create a new entity object instance
+     *
+     * Uses the MemberJunction metadata system to properly instantiate an entity object.
+     * This ensures correct class registration and respects any custom entity subclasses.
+     *
+     * @param entityName - Name of the entity to create
+     * @returns Promise resolving to the new BaseEntity instance
+     * @throws Error if entity creation fails
+     *
+     * @example
+     * ```typescript
+     * const entity = await syncEngine.createEntityObject('AI Prompts');
+     * entity.NewRecord();
+     * entity.Set('Name', 'My Prompt');
+     * await entity.Save();
+     * ```
      */
     createEntityObject(entityName: string): Promise<BaseEntity>;
     /**
-     * Load an entity by primary key
+     * Load an entity record by primary key
+     *
+     * Retrieves an existing entity record from the database using its primary key values.
+     * Supports both single and composite primary keys. Returns null if the record is not found.
+     *
+     * @param entityName - Name of the entity to load
+     * @param primaryKey - Object containing primary key field names and values
+     * @returns Promise resolving to the loaded entity or null if not found
+     * @throws Error if entity metadata is not found
+     *
+     * @example
+     * ```typescript
+     * // Single primary key
+     * const entity = await syncEngine.loadEntity('Users', { ID: '123-456' });
+     *
+     * // Composite primary key
+     * const entity = await syncEngine.loadEntity('UserRoles', {
+     *   UserID: '123-456',
+     *   RoleID: '789-012'
+     * });
+     * ```
      */
     loadEntity(entityName: string, primaryKey: Record<string, any>): Promise<BaseEntity | null>;
+    /**
+     * Process JSON object with template references
+     *
+     * Recursively processes JSON data structures to resolve `@template` references.
+     * Templates can be defined at any level and support:
+     * - Single template references: `"@template:path/to/template.json"`
+     * - Object with @template field: `{ "@template": "file.json", "override": "value" }`
+     * - Array of templates for merging: `{ "@template": ["base.json", "overrides.json"] }`
+     * - Nested template references within templates
+     *
+     * @param data - JSON data structure to process
+     * @param baseDir - Base directory for resolving relative template paths
+     * @returns Promise resolving to the processed data with all templates resolved
+     * @throws Error if template file is not found or contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * // Input data with template reference
+     * const data = {
+     *   "@template": "defaults/ai-prompt.json",
+     *   "Name": "Custom Prompt",
+     *   "Prompt": "Override the template prompt"
+     * };
+     *
+     * // Resolves template and merges with overrides
+     * const result = await syncEngine.processTemplates(data, '/path/to/dir');
+     * ```
+     */
+    processTemplates(data: any, baseDir: string): Promise<any>;
+    /**
+     * Load and process a template file
+     *
+     * Loads a JSON template file from the filesystem and recursively processes any
+     * nested template references within it. Template paths are resolved relative to
+     * the template file's directory, enabling template composition.
+     *
+     * @param templatePath - Path to the template file (relative or absolute)
+     * @param baseDir - Base directory for resolving relative paths
+     * @returns Promise resolving to the processed template content
+     * @throws Error if template file not found or contains invalid JSON
+     * @private
+     */
+    private loadAndProcessTemplate;
+    /**
+     * Deep merge two objects with target taking precedence
+     *
+     * Recursively merges two objects, with values from the target object overriding
+     * values from the source object. Arrays and primitive values are not merged but
+     * replaced entirely by the target value. Undefined values in target are skipped.
+     *
+     * @param source - Base object to merge from
+     * @param target - Object with values that override source
+     * @returns New object with merged values
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const source = {
+     *   a: 1,
+     *   b: { x: 10, y: 20 },
+     *   c: [1, 2, 3]
+     * };
+     * const target = {
+     *   a: 2,
+     *   b: { y: 30, z: 40 },
+     *   d: 'new'
+     * };
+     * const result = deepMerge(source, target);
+     * // Result: { a: 2, b: { x: 10, y: 30, z: 40 }, c: [1, 2, 3], d: 'new' }
+     * ```
+     */
+    private deepMerge;
 }

package/dist/lib/sync-engine.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * @fileoverview Core synchronization engine for MemberJunction metadata
+ * @module sync-engine
+ *
+ * This module provides the core functionality for synchronizing metadata between
+ * the MemberJunction database and local file system representations. It handles
+ * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),
+ * manages entity operations, and provides utilities for data transformation.
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,19 +18,64 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const crypto_1 = __importDefault(require("crypto"));
 const axios_1 = __importDefault(require("axios"));
 const core_1 = require("@memberjunction/core");
+/**
+ * Core engine for synchronizing MemberJunction metadata between database and files
+ *
+ * @class SyncEngine
+ * @example
+ * ```typescript
+ * const syncEngine = new SyncEngine(systemUser);
+ * await syncEngine.initialize();
+ *
+ * // Process a field value with special references
+ * const value = await syncEngine.processFieldValue('@lookup:Users.Email=admin@example.com', '/path/to/base');
+ * ```
+ */
 class SyncEngine {
     metadata;
     contextUser;
+    /**
+     * Creates a new SyncEngine instance
+     * @param contextUser - The user context for database operations
+     */
     constructor(contextUser) {
         this.metadata = new core_1.Metadata();
         this.contextUser = contextUser;
     }
+    /**
+     * Initializes the sync engine by refreshing metadata cache
+     * @returns Promise that resolves when initialization is complete
+     */
     async initialize() {
         // Initialize metadata
         await this.metadata.Refresh();
     }
     /**
      * Process special references in field values
+     *
+     * Handles the following reference types:
+     * - `@parent:fieldName` - References a field from the parent record
+     * - `@root:fieldName` - References a field from the root record
+     * - `@file:path` - Reads content from an external file
+     * - `@url:address` - Fetches content from a URL
+     * - `@lookup:Entity.Field=Value` - Looks up an entity ID by field value
+     * - `@env:VARIABLE` - Reads an environment variable
+     *
+     * @param value - The field value to process
+     * @param baseDir - Base directory for resolving relative file paths
+     * @param parentRecord - Optional parent entity for @parent references
+     * @param rootRecord - Optional root entity for @root references
+     * @returns The processed value with all references resolved
+     * @throws Error if a reference cannot be resolved
+     *
+     * @example
+     * ```typescript
+     * // File reference
+     * const content = await processFieldValue('@file:template.md', '/path/to/dir');
+     *
+     * // Lookup with auto-create
+     * const userId = await processFieldValue('@lookup:Users.Email=john@example.com?create', '/path');
+     * ```
      */
     async processFieldValue(value, baseDir, parentRecord, rootRecord) {
         if (typeof value !== 'string') {
@@ -112,6 +166,26 @@ class SyncEngine {
     }
     /**
      * Resolve a lookup reference to an ID, optionally creating the record if it doesn't exist
+     *
+     * @param entityName - Name of the entity to search in
+     * @param fieldName - Field to match against
+     * @param fieldValue - Value to search for
+     * @param autoCreate - Whether to create the record if not found
+     * @param createFields - Additional fields to set when creating
+     * @returns The ID of the found or created record
+     * @throws Error if lookup fails and autoCreate is false
+     *
+     * @example
+     * ```typescript
+     * // Simple lookup
+     * const categoryId = await resolveLookup('Categories', 'Name', 'Technology');
+     *
+     * // Lookup with auto-create
+     * const tagId = await resolveLookup('Tags', 'Name', 'New Tag', true, {
+     *   Description: 'Auto-created tag',
+     *   Status: 'Active'
+     * });
+     * ```
      */
     async resolveLookup(entityName, fieldName, fieldValue, autoCreate = false, createFields = {}) {
         // Debug logging handled by caller if needed
@@ -168,6 +242,15 @@ class SyncEngine {
     }
     /**
      * Build cascading defaults for a file path and process field values
+     *
+     * Walks up the directory tree from the file location, collecting defaults from
+     * entity config and folder configs, with deeper folders overriding parent values.
+     * All default values are processed for special references.
+     *
+     * @param filePath - Path to the file being processed
+     * @param entityConfig - Entity configuration containing base defaults
+     * @returns Processed defaults with all references resolved
+     * @throws Error if any default value processing fails
      */
     async buildDefaults(filePath, entityConfig) {
         const parts = path_1.default.dirname(filePath).split(path_1.default.sep);
@@ -195,7 +278,11 @@ class SyncEngine {
         return processedDefaults;
     }
     /**
-     * Load folder configuration
+     * Load folder configuration from .mj-folder.json file
+     *
+     * @param dir - Directory to check for configuration
+     * @returns Folder configuration or null if not found/invalid
+     * @private
      */
     async loadFolderConfig(dir) {
         const configPath = path_1.default.join(dir, '.mj-folder.json');
@@ -211,7 +298,24 @@ class SyncEngine {
         return null;
     }
     /**
-     * Calculate checksum for data
+     * Calculate SHA256 checksum for data
+     *
+     * Generates a deterministic hash of the provided data by converting it to
+     * formatted JSON and calculating a SHA256 digest. Used for change detection
+     * in sync operations.
+     *
+     * @param data - Any data structure to calculate checksum for
+     * @returns Hexadecimal string representation of the SHA256 hash
+     *
+     * @example
+     * ```typescript
+     * const checksum = syncEngine.calculateChecksum({
+     *   name: 'Test Record',
+     *   value: 42,
+     *   tags: ['a', 'b']
+     * });
+     * // Returns consistent hash for same data structure
+     * ```
      */
     calculateChecksum(data) {
         const hash = crypto_1.default.createHash('sha256');
@@ -219,13 +323,42 @@ class SyncEngine {
         return hash.digest('hex');
     }
     /**
-     * Get entity info by name
+     * Get entity metadata information by name
+     *
+     * Retrieves the EntityInfo object containing schema metadata for the specified entity.
+     * Returns null if the entity is not found in the metadata cache.
+     *
+     * @param entityName - Name of the entity to look up
+     * @returns EntityInfo object with schema details or null if not found
+     *
+     * @example
+     * ```typescript
+     * const entityInfo = syncEngine.getEntityInfo('AI Prompts');
+     * if (entityInfo) {
+     *   console.log(`Primary keys: ${entityInfo.PrimaryKeys.map(pk => pk.Name).join(', ')}`);
+     * }
+     * ```
      */
     getEntityInfo(entityName) {
         return this.metadata.EntityByName(entityName);
     }
     /**
-     * Create a new entity object
+     * Create a new entity object instance
+     *
+     * Uses the MemberJunction metadata system to properly instantiate an entity object.
+     * This ensures correct class registration and respects any custom entity subclasses.
+     *
+     * @param entityName - Name of the entity to create
+     * @returns Promise resolving to the new BaseEntity instance
+     * @throws Error if entity creation fails
+     *
+     * @example
+     * ```typescript
+     * const entity = await syncEngine.createEntityObject('AI Prompts');
+     * entity.NewRecord();
+     * entity.Set('Name', 'My Prompt');
+     * await entity.Save();
+     * ```
      */
     async createEntityObject(entityName) {
         const entity = await this.metadata.GetEntityObject(entityName, this.contextUser);
@@ -235,7 +368,27 @@ class SyncEngine {
         return entity;
     }
     /**
-     * Load an entity by primary key
+     * Load an entity record by primary key
+     *
+     * Retrieves an existing entity record from the database using its primary key values.
+     * Supports both single and composite primary keys. Returns null if the record is not found.
+     *
+     * @param entityName - Name of the entity to load
+     * @param primaryKey - Object containing primary key field names and values
+     * @returns Promise resolving to the loaded entity or null if not found
+     * @throws Error if entity metadata is not found
+     *
+     * @example
+     * ```typescript
+     * // Single primary key
+     * const entity = await syncEngine.loadEntity('Users', { ID: '123-456' });
+     *
+     * // Composite primary key
+     * const entity = await syncEngine.loadEntity('UserRoles', {
+     *   UserID: '123-456',
+     *   RoleID: '789-012'
+     * });
+     * ```
      */
     async loadEntity(entityName, primaryKey) {
         const entity = await this.createEntityObject(entityName);
@@ -249,6 +402,162 @@ class SyncEngine {
         const loaded = await entity.InnerLoad(compositeKey);
         return loaded ? entity : null;
     }
+    /**
+     * Process JSON object with template references
+     *
+     * Recursively processes JSON data structures to resolve `@template` references.
+     * Templates can be defined at any level and support:
+     * - Single template references: `"@template:path/to/template.json"`
+     * - Object with @template field: `{ "@template": "file.json", "override": "value" }`
+     * - Array of templates for merging: `{ "@template": ["base.json", "overrides.json"] }`
+     * - Nested template references within templates
+     *
+     * @param data - JSON data structure to process
+     * @param baseDir - Base directory for resolving relative template paths
+     * @returns Promise resolving to the processed data with all templates resolved
+     * @throws Error if template file is not found or contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * // Input data with template reference
+     * const data = {
+     *   "@template": "defaults/ai-prompt.json",
+     *   "Name": "Custom Prompt",
+     *   "Prompt": "Override the template prompt"
+     * };
+     *
+     * // Resolves template and merges with overrides
+     * const result = await syncEngine.processTemplates(data, '/path/to/dir');
+     * ```
+     */
+    async processTemplates(data, baseDir) {
+        // Handle arrays
+        if (Array.isArray(data)) {
+            const processedArray = [];
+            for (const item of data) {
+                processedArray.push(await this.processTemplates(item, baseDir));
+            }
+            return processedArray;
+        }
+        // Handle objects
+        if (data && typeof data === 'object') {
+            // Check for @template reference
+            if (typeof data === 'string' && data.startsWith('@template:')) {
+                const templatePath = data.substring(10);
+                return await this.loadAndProcessTemplate(templatePath, baseDir);
+            }
+            // Process object with possible @template field
+            const processed = {};
+            let templateData = {};
+            // First, check if there's a @template field to process
+            if (data['@template']) {
+                const templates = Array.isArray(data['@template']) ? data['@template'] : [data['@template']];
+                // Process templates in order, merging them
+                for (const templateRef of templates) {
+                    const templateContent = await this.loadAndProcessTemplate(templateRef, baseDir);
+                    templateData = this.deepMerge(templateData, templateContent);
+                }
+            }
+            // Process all other fields
+            for (const [key, value] of Object.entries(data)) {
+                if (key === '@template')
+                    continue; // Skip the template field itself
+                // Process the value recursively
+                processed[key] = await this.processTemplates(value, baseDir);
+            }
+            // Merge template data with processed data (processed data takes precedence)
+            return this.deepMerge(templateData, processed);
+        }
+        // Return primitive values as-is
+        return data;
+    }
+    /**
+     * Load and process a template file
+     *
+     * Loads a JSON template file from the filesystem and recursively processes any
+     * nested template references within it. Template paths are resolved relative to
+     * the template file's directory, enabling template composition.
+     *
+     * @param templatePath - Path to the template file (relative or absolute)
+     * @param baseDir - Base directory for resolving relative paths
+     * @returns Promise resolving to the processed template content
+     * @throws Error if template file not found or contains invalid JSON
+     * @private
+     */
+    async loadAndProcessTemplate(templatePath, baseDir) {
+        const fullPath = path_1.default.resolve(baseDir, templatePath);
+        if (!await fs_extra_1.default.pathExists(fullPath)) {
+            throw new Error(`Template file not found: ${fullPath}`);
+        }
+        try {
+            const templateContent = await fs_extra_1.default.readJson(fullPath);
+            // Recursively process any nested templates
+            const templateDir = path_1.default.dirname(fullPath);
+            return await this.processTemplates(templateContent, templateDir);
+        }
+        catch (error) {
+            throw new Error(`Failed to load template ${fullPath}: ${error}`);
+        }
+    }
+    /**
+     * Deep merge two objects with target taking precedence
+     *
+     * Recursively merges two objects, with values from the target object overriding
+     * values from the source object. Arrays and primitive values are not merged but
+     * replaced entirely by the target value. Undefined values in target are skipped.
+     *
+     * @param source - Base object to merge from
+     * @param target - Object with values that override source
+     * @returns New object with merged values
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const source = {
+     *   a: 1,
+     *   b: { x: 10, y: 20 },
+     *   c: [1, 2, 3]
+     * };
+     * const target = {
+     *   a: 2,
+     *   b: { y: 30, z: 40 },
+     *   d: 'new'
+     * };
+     * const result = deepMerge(source, target);
+     * // Result: { a: 2, b: { x: 10, y: 30, z: 40 }, c: [1, 2, 3], d: 'new' }
+     * ```
+     */
+    deepMerge(source, target) {
+        if (!source)
+            return target;
+        if (!target)
+            return source;
+        // If target is not an object, it completely overrides source
+        if (typeof target !== 'object' || target === null || Array.isArray(target)) {
+            return target;
+        }
+        // If source is not an object, target wins
+        if (typeof source !== 'object' || source === null || Array.isArray(source)) {
+            return target;
+        }
+        // Both are objects, merge them
+        const result = { ...source };
+        for (const [key, value] of Object.entries(target)) {
+            if (value === undefined) {
+                continue; // Skip undefined values
+            }
+            if (typeof value === 'object' && value !== null && !Array.isArray(value) &&
+                typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])) {
+                // Both are objects, merge recursively
+                result[key] = this.deepMerge(result[key], value);
+            }
+            else {
+                // Otherwise, target value wins
+                result[key] = value;
+            }
+        }
+        return result;
+    }
 }
 exports.SyncEngine = SyncEngine;
 //# sourceMappingURL=sync-engine.js.map