@memberjunction/metadata-sync 2.67.0 → 2.69.0

package/README.md

@@ -1549,6 +1549,8 @@ The pull command now supports smart update capabilities with extensive configura
 | `excludeFields` | string[] | [] | Fields to completely omit from pulled data (see detailed explanation below) |
 | `lookupFields` | object | - | Foreign keys to convert to @lookup references |
 | `relatedEntities` | object | - | Related entities to pull as embedded collections |
+| `ignoreNullFields` | boolean | false | Exclude fields with null values from pulled data |
+| `ignoreVirtualFields` | boolean | false | Exclude virtual fields (view-only fields) from pulled data |
 
 > **⚠️ Important Configuration Warning**
 > 
@@ -1649,6 +1651,61 @@ Example configuration:
 }
 ```
 
+#### Virtual Fields Configuration
+
+The `ignoreVirtualFields` option controls whether virtual fields are included in pulled data:
+
+```json
+"pull": {
+  "ignoreVirtualFields": true  // Exclude virtual fields from pulled data
+}
+```
+
+**What are Virtual Fields?**
+Virtual fields are computed fields that exist only in database views, not in the underlying tables. They typically contain:
+- Foreign key display names (e.g., `"User": "John Smith"` alongside `"UserID": "123"`)
+- Computed/calculated values
+- Aggregate data from related tables
+- Derived fields from database functions
+
+**When to use `ignoreVirtualFields: true`:**
+- **Cleaner JSON files**: Remove read-only display fields that don't need version control
+- **Reducing file size**: Eliminate redundant data that's computed from other fields
+- **Preventing confusion**: Avoid fields that can't be modified during push operations
+- **Database-focused workflow**: When you only want to manage actual table columns
+
+**When to use `ignoreVirtualFields: false` (default):**
+- **Complete data capture**: Include all available information for reference
+- **Display purposes**: Keep human-readable field values for easy review
+- **Documentation**: Maintain context about related entity names and computed values
+
+**Example difference:**
+
+With `ignoreVirtualFields: false`:
+```json
+{
+  "fields": {
+    "Name": "Test Action",
+    "CategoryID": "@lookup:Action Categories.Name=System",
+    "Category": "System",  // ← Virtual field (display name)
+    "UserID": "123",
+    "User": "John Smith"   // ← Virtual field (display name)
+  }
+}
+```
+
+With `ignoreVirtualFields: true`:
+```json
+{
+  "fields": {
+    "Name": "Test Action", 
+    "CategoryID": "@lookup:Action Categories.Name=System",
+    "UserID": "123"
+    // Virtual fields excluded
+  }
+}
+```
+
 #### Externalize Fields Patterns
 
 The `externalizeFields` configuration supports dynamic file naming with placeholders:

package/dist/config.d.ts

@@ -237,6 +237,10 @@ export interface EntityConfig {
                 field: string;
             };
         };
+        /** Whether to ignore null field values during pull (defaults to false) */
+        ignoreNullFields?: boolean;
+        /** Whether to ignore virtual fields during pull (defaults to false) */
+        ignoreVirtualFields?: boolean;
     };
 }
 /**

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;;AAGH,gDAAwB;AACxB,wDAA0B;AAC1B,yDAAqD;AAuPrD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,YAAY;IAC1B,OAAO,8BAAa,CAAC,YAAY,EAAE,CAAC;AACtC,CAAC;AAFD,oCAEC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAEnD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAbD,wCAaC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAEnD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC7C,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAfD,4CAeC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAErD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAbD,4CAaC","sourcesContent":["/**\n * @fileoverview Configuration types and loaders for MetadataSync\n * @module config\n * \n * This module defines configuration interfaces and provides utilities for loading\n * various configuration files used by the MetadataSync tool. It supports:\n * - MemberJunction database configuration (mj.config.cjs)\n * - Sync configuration (.mj-sync.json)\n * - Entity-specific configuration (.mj-sync.json with entity field)\n * - Folder-level defaults (.mj-folder.json)\n */\n\nimport { cosmiconfigSync } from 'cosmiconfig';\nimport path from 'path';\nimport fs from 'fs-extra';\nimport { configManager } from './lib/config-manager';\n\n/**\n * MemberJunction database configuration\n * \n * Defines connection parameters and settings for connecting to the MemberJunction\n * database. Typically loaded from mj.config.cjs in the project root.\n */\nexport interface MJConfig {\n  /** Database server hostname or IP address */\n  dbHost: string;\n  /** Database server port (defaults to 1433 for SQL Server) */\n  dbPort?: number;\n  /** Database name to connect to */\n  dbDatabase: string;\n  /** Database authentication username */\n  dbUsername: string;\n  /** Database authentication password */\n  dbPassword: string;\n  /** Whether to trust the server certificate (Y/N) */\n  dbTrustServerCertificate?: string;\n  /** Whether to encrypt the connection (Y/N, auto-detected for Azure SQL) */\n  dbEncrypt?: string;\n  /** SQL Server instance name (for named instances) */\n  dbInstanceName?: string;\n  /** Schema name for MemberJunction core tables (defaults to __mj) */\n  mjCoreSchema?: string;\n  /** Allow additional properties for extensibility */\n  [key: string]: any;\n}\n\n/**\n * Global sync configuration\n * \n * Defines settings that apply to the entire sync process, including push/pull\n * behaviors and watch mode configuration. Stored in .mj-sync.json at the root.\n */\nexport interface SyncConfig {\n  /** Version of the sync configuration format */\n  version: string;\n  /** Glob pattern for finding data files (defaults to \"*.json\") */\n  filePattern?: string;\n  /** \n   * Directory processing order (only applies to root-level config, not inherited by subdirectories)\n   * Specifies the order in which subdirectories should be processed to handle dependencies.\n   * Directories not listed in this array will be processed after the ordered ones in alphabetical order.\n   */\n  directoryOrder?: string[];\n  /** \n   * Directories to ignore during processing\n   * Can be directory names or glob patterns relative to the location of the .mj-sync.json file\n   * Cumulative: subdirectories inherit and add to parent ignoreDirectories\n   * Examples: [\"output\", \"examples\", \"temp\"]\n   */\n  ignoreDirectories?: string[];\n  /** Push command configuration */\n  push?: {\n    /** Whether to validate records before pushing to database */\n    validateBeforePush?: boolean;\n    /** Whether to require user confirmation before push */\n    requireConfirmation?: boolean;\n    /** \n     * Whether to automatically create new records when a primaryKey exists but record is not found\n     * Defaults to false - will warn instead of creating\n     */\n    autoCreateMissingRecords?: boolean;\n  };\n  /** SQL logging configuration (only applies to root-level config, not inherited by subdirectories) */\n  sqlLogging?: {\n    /** Whether to enable SQL logging during push operations */\n    enabled?: boolean;\n    /** Directory to output SQL log files (relative to command execution directory, defaults to './sql_logging') */\n    outputDirectory?: string;\n    /** Whether to format SQL as migration-ready files with Flyway schema placeholders */\n    formatAsMigration?: boolean;\n    /**\n     * Array of patterns to filter SQL statements.\n     * Supports both regex strings and simple wildcard patterns:\n     * - Regex: \"/spCreate.*Run/i\" (must start with \"/\" and optionally end with flags)\n     * - Simple: \"*spCreateAIPromptRun*\" (uses * as wildcard, case-insensitive by default)\n     * Examples: [\"*AIPrompt*\", \"/^EXEC sp_/i\", \"*EntityFieldValue*\"]\n     */\n    filterPatterns?: string[];\n    /**\n     * Determines how filterPatterns are applied:\n     * - 'exclude': If ANY pattern matches, the SQL is NOT logged (default)\n     * - 'include': If ANY pattern matches, the SQL IS logged\n     */\n    filterType?: 'exclude' | 'include';\n  };\n  /** Watch command configuration */\n  watch?: {\n    /** Milliseconds to wait before processing file changes */\n    debounceMs?: number;\n    /** File patterns to ignore during watch */\n    ignorePatterns?: string[];\n  };\n  /** User role validation configuration */\n  userRoleValidation?: {\n    /** Whether to enable user role validation for UserID fields */\n    enabled?: boolean;\n    /** List of role names that are allowed to be referenced in metadata */\n    allowedRoles?: string[];\n    /** Whether to allow users without any roles (defaults to false) */\n    allowUsersWithoutRoles?: boolean;\n  };\n}\n\n/**\n * Configuration for related entity synchronization\n * \n * Defines how to pull and push related entities that have foreign key relationships\n * with a parent entity. Supports nested relationships for deep object graphs.\n * NEW: Supports automatic recursive patterns for self-referencing entities.\n */\nexport interface RelatedEntityConfig {\n  /** Name of the related entity to sync */\n  entity: string;\n  /** Field name that contains the foreign key reference to parent (e.g., \"PromptID\") */\n  foreignKey: string;\n  /** Optional SQL filter to apply when pulling related records */\n  filter?: string;\n  /** \n   * Enable recursive fetching for self-referencing entities\n   * When true, automatically fetches all levels of the hierarchy until no more children found\n   */\n  recursive?: boolean;\n  /** \n   * Maximum depth for recursive fetching (optional, defaults to 10)\n   * Prevents infinite loops and controls memory usage\n   * Only applies when recursive is true\n   */\n  maxDepth?: number;\n  /** Fields to externalize to separate files for this related entity */\n  externalizeFields?: string[] | {\n    [fieldName: string]: {\n      /** File extension to use (e.g., \".md\", \".txt\", \".html\") */\n      extension?: string;\n    }\n  } | Array<{\n    /** Field name to externalize */\n    field: string;\n    /** Pattern for the output file. Supports placeholders from the entity */\n    pattern: string;\n  }>;\n  /** Fields to exclude from the pulled data for this related entity */\n  excludeFields?: string[];\n  /** Foreign key fields to convert to @lookup references for this related entity */\n  lookupFields?: {\n    [fieldName: string]: {\n      entity: string;\n      field: string;\n    };\n  };\n  /** Nested related entities for deep object graphs */\n  relatedEntities?: Record<string, RelatedEntityConfig>;\n}\n\n/**\n * Entity-specific configuration\n * \n * Defines settings for a specific entity type within a directory. Stored in\n * .mj-sync.json files that contain an \"entity\" field. Supports defaults,\n * file patterns, and related entity configuration.\n */\nexport interface EntityConfig {\n  /** Name of the entity this directory contains */\n  entity: string;\n  /** Glob pattern for finding data files (defaults to \"*.json\") */\n  filePattern?: string;\n  /** Default field values applied to all records in this directory */\n  defaults?: Record<string, any>;\n  /** \n   * Directories to ignore during processing\n   * Can be directory names or glob patterns relative to the location of the .mj-sync.json file\n   * Cumulative: subdirectories inherit and add to parent ignoreDirectories\n   * Examples: [\"output\", \"examples\", \"temp\"]\n   */\n  ignoreDirectories?: string[];\n  /** Pull command specific configuration */\n  pull?: {\n    /** Glob pattern for finding existing files to update (defaults to filePattern) */\n    filePattern?: string;\n    /** Whether to create new files for records not found locally */\n    createNewFileIfNotFound?: boolean;\n    /** Filename for new records when createNewFileIfNotFound is true */\n    newFileName?: string;\n    /** Whether to append multiple new records to a single file */\n    appendRecordsToExistingFile?: boolean;\n    /** Whether to update existing records found in local files */\n    updateExistingRecords?: boolean;\n    /** Fields to preserve during updates (never overwrite these) */\n    preserveFields?: string[];\n    /** Strategy for merging updates: \"overwrite\" | \"merge\" | \"skip\" */\n    mergeStrategy?: 'overwrite' | 'merge' | 'skip';\n    /** Create backup files before updating existing files */\n    backupBeforeUpdate?: boolean;\n    /** Directory name for backup files (defaults to \".backups\") */\n    backupDirectory?: string;\n    /** SQL filter to apply when pulling records from database */\n    filter?: string;\n    /** Configuration for pulling related entities */\n    relatedEntities?: Record<string, RelatedEntityConfig>;\n    /** Fields to externalize to separate files with optional configuration */\n    externalizeFields?: string[] | {\n      [fieldName: string]: {\n        /** File extension to use (e.g., \".md\", \".txt\", \".html\") */\n        extension?: string;\n      }\n    } | Array<{\n      /** Field name to externalize */\n      field: string;\n      /** Pattern for the output file. Supports placeholders:\n       * - {Name}: Entity's name field value\n       * - {ID}: Entity's ID\n       * - {FieldName}: The field being externalized\n       * - Any other {FieldName} from the entity\n       * Example: \"@file:templates/{Name}.template.md\"\n       */\n      pattern: string;\n    }>;\n    /** Fields to exclude from the pulled data (e.g., [\"TemplateID\"]) */\n    excludeFields?: string[];\n    /** Foreign key fields to convert to @lookup references */\n    lookupFields?: {\n      /** Field name in this entity (e.g., \"CategoryID\") */\n      [fieldName: string]: {\n        /** Target entity name (e.g., \"AI Prompt Categories\") */\n        entity: string;\n        /** Field in target entity to use for lookup (e.g., \"Name\") */\n        field: string;\n      };\n    };\n  };\n}\n\n/**\n * Folder-level configuration\n * \n * Defines default values that cascade down to all subdirectories. Stored in\n * .mj-folder.json files. Child folders can override parent defaults.\n */\nexport interface FolderConfig {\n  /** Default field values that apply to all entities in this folder and subfolders */\n  defaults: Record<string, any>;\n}\n\n/**\n * Load MemberJunction configuration from the filesystem\n * \n * Searches for mj.config.cjs starting from the current directory and walking up\n * the directory tree. Uses cosmiconfig for flexible configuration loading.\n * \n * @returns MJConfig object if found, null if not found or invalid\n * \n * @example\n * ```typescript\n * const config = loadMJConfig();\n * if (config) {\n *   console.log(`Connecting to ${config.dbHost}:${config.dbPort || 1433}`);\n * }\n * ```\n */\nexport function loadMJConfig(): MJConfig | null {\n  return configManager.loadMJConfig();\n}\n\n/**\n * Load sync configuration from a directory\n * \n * Loads .mj-sync.json file from the specified directory. This file can contain\n * either global sync configuration (no entity field) or entity-specific\n * configuration (with entity field).\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to SyncConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const syncConfig = await loadSyncConfig('/path/to/project');\n * if (syncConfig?.push?.requireConfirmation) {\n *   // Show confirmation prompt\n * }\n * ```\n */\nexport async function loadSyncConfig(dir: string): Promise<SyncConfig | null> {\n  const configPath = path.join(dir, '.mj-sync.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      return await fs.readJson(configPath);\n    } catch (error) {\n      console.error('Error loading sync config:', error);\n      return null;\n    }\n  }\n  \n  return null;\n}\n\n/**\n * Load entity-specific configuration from a directory\n * \n * Loads .mj-sync.json file that contains an \"entity\" field, indicating this\n * directory contains data for a specific entity type. Returns null if the\n * file doesn't exist or doesn't contain an entity field.\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to EntityConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const entityConfig = await loadEntityConfig('./ai-prompts');\n * if (entityConfig) {\n *   console.log(`Directory contains ${entityConfig.entity} records`);\n * }\n * ```\n */\nexport async function loadEntityConfig(dir: string): Promise<EntityConfig | null> {\n  const configPath = path.join(dir, '.mj-sync.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      const config = await fs.readJson(configPath);\n      if (config.entity) {\n        return config;\n      }\n    } catch (error) {\n      console.error('Error loading entity config:', error);\n    }\n  }\n  \n  return null;\n}\n\n/**\n * Load folder-level configuration\n * \n * Loads .mj-folder.json file that contains default values to be applied to\n * all entities in this folder and its subfolders. Used for cascading defaults\n * in deep directory structures.\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to FolderConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const folderConfig = await loadFolderConfig('./templates');\n * if (folderConfig?.defaults) {\n *   // Apply folder defaults to records\n * }\n * ```\n */\nexport async function loadFolderConfig(dir: string): Promise<FolderConfig | null> {\n  const configPath = path.join(dir, '.mj-folder.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      return await fs.readJson(configPath);\n    } catch (error) {\n      console.error('Error loading folder config:', error);\n      return null;\n    }\n  }\n  \n  return null;\n}"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;;AAGH,gDAAwB;AACxB,wDAA0B;AAC1B,yDAAqD;AA2PrD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,YAAY;IAC1B,OAAO,8BAAa,CAAC,YAAY,EAAE,CAAC;AACtC,CAAC;AAFD,oCAEC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAEnD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAbD,wCAaC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAEnD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC7C,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAfD,4CAeC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAErD,IAAI,MAAM,kBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,kBAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAbD,4CAaC","sourcesContent":["/**\n * @fileoverview Configuration types and loaders for MetadataSync\n * @module config\n * \n * This module defines configuration interfaces and provides utilities for loading\n * various configuration files used by the MetadataSync tool. It supports:\n * - MemberJunction database configuration (mj.config.cjs)\n * - Sync configuration (.mj-sync.json)\n * - Entity-specific configuration (.mj-sync.json with entity field)\n * - Folder-level defaults (.mj-folder.json)\n */\n\nimport { cosmiconfigSync } from 'cosmiconfig';\nimport path from 'path';\nimport fs from 'fs-extra';\nimport { configManager } from './lib/config-manager';\n\n/**\n * MemberJunction database configuration\n * \n * Defines connection parameters and settings for connecting to the MemberJunction\n * database. Typically loaded from mj.config.cjs in the project root.\n */\nexport interface MJConfig {\n  /** Database server hostname or IP address */\n  dbHost: string;\n  /** Database server port (defaults to 1433 for SQL Server) */\n  dbPort?: number;\n  /** Database name to connect to */\n  dbDatabase: string;\n  /** Database authentication username */\n  dbUsername: string;\n  /** Database authentication password */\n  dbPassword: string;\n  /** Whether to trust the server certificate (Y/N) */\n  dbTrustServerCertificate?: string;\n  /** Whether to encrypt the connection (Y/N, auto-detected for Azure SQL) */\n  dbEncrypt?: string;\n  /** SQL Server instance name (for named instances) */\n  dbInstanceName?: string;\n  /** Schema name for MemberJunction core tables (defaults to __mj) */\n  mjCoreSchema?: string;\n  /** Allow additional properties for extensibility */\n  [key: string]: any;\n}\n\n/**\n * Global sync configuration\n * \n * Defines settings that apply to the entire sync process, including push/pull\n * behaviors and watch mode configuration. Stored in .mj-sync.json at the root.\n */\nexport interface SyncConfig {\n  /** Version of the sync configuration format */\n  version: string;\n  /** Glob pattern for finding data files (defaults to \"*.json\") */\n  filePattern?: string;\n  /** \n   * Directory processing order (only applies to root-level config, not inherited by subdirectories)\n   * Specifies the order in which subdirectories should be processed to handle dependencies.\n   * Directories not listed in this array will be processed after the ordered ones in alphabetical order.\n   */\n  directoryOrder?: string[];\n  /** \n   * Directories to ignore during processing\n   * Can be directory names or glob patterns relative to the location of the .mj-sync.json file\n   * Cumulative: subdirectories inherit and add to parent ignoreDirectories\n   * Examples: [\"output\", \"examples\", \"temp\"]\n   */\n  ignoreDirectories?: string[];\n  /** Push command configuration */\n  push?: {\n    /** Whether to validate records before pushing to database */\n    validateBeforePush?: boolean;\n    /** Whether to require user confirmation before push */\n    requireConfirmation?: boolean;\n    /** \n     * Whether to automatically create new records when a primaryKey exists but record is not found\n     * Defaults to false - will warn instead of creating\n     */\n    autoCreateMissingRecords?: boolean;\n  };\n  /** SQL logging configuration (only applies to root-level config, not inherited by subdirectories) */\n  sqlLogging?: {\n    /** Whether to enable SQL logging during push operations */\n    enabled?: boolean;\n    /** Directory to output SQL log files (relative to command execution directory, defaults to './sql_logging') */\n    outputDirectory?: string;\n    /** Whether to format SQL as migration-ready files with Flyway schema placeholders */\n    formatAsMigration?: boolean;\n    /**\n     * Array of patterns to filter SQL statements.\n     * Supports both regex strings and simple wildcard patterns:\n     * - Regex: \"/spCreate.*Run/i\" (must start with \"/\" and optionally end with flags)\n     * - Simple: \"*spCreateAIPromptRun*\" (uses * as wildcard, case-insensitive by default)\n     * Examples: [\"*AIPrompt*\", \"/^EXEC sp_/i\", \"*EntityFieldValue*\"]\n     */\n    filterPatterns?: string[];\n    /**\n     * Determines how filterPatterns are applied:\n     * - 'exclude': If ANY pattern matches, the SQL is NOT logged (default)\n     * - 'include': If ANY pattern matches, the SQL IS logged\n     */\n    filterType?: 'exclude' | 'include';\n  };\n  /** Watch command configuration */\n  watch?: {\n    /** Milliseconds to wait before processing file changes */\n    debounceMs?: number;\n    /** File patterns to ignore during watch */\n    ignorePatterns?: string[];\n  };\n  /** User role validation configuration */\n  userRoleValidation?: {\n    /** Whether to enable user role validation for UserID fields */\n    enabled?: boolean;\n    /** List of role names that are allowed to be referenced in metadata */\n    allowedRoles?: string[];\n    /** Whether to allow users without any roles (defaults to false) */\n    allowUsersWithoutRoles?: boolean;\n  };\n}\n\n/**\n * Configuration for related entity synchronization\n * \n * Defines how to pull and push related entities that have foreign key relationships\n * with a parent entity. Supports nested relationships for deep object graphs.\n * NEW: Supports automatic recursive patterns for self-referencing entities.\n */\nexport interface RelatedEntityConfig {\n  /** Name of the related entity to sync */\n  entity: string;\n  /** Field name that contains the foreign key reference to parent (e.g., \"PromptID\") */\n  foreignKey: string;\n  /** Optional SQL filter to apply when pulling related records */\n  filter?: string;\n  /** \n   * Enable recursive fetching for self-referencing entities\n   * When true, automatically fetches all levels of the hierarchy until no more children found\n   */\n  recursive?: boolean;\n  /** \n   * Maximum depth for recursive fetching (optional, defaults to 10)\n   * Prevents infinite loops and controls memory usage\n   * Only applies when recursive is true\n   */\n  maxDepth?: number;\n  /** Fields to externalize to separate files for this related entity */\n  externalizeFields?: string[] | {\n    [fieldName: string]: {\n      /** File extension to use (e.g., \".md\", \".txt\", \".html\") */\n      extension?: string;\n    }\n  } | Array<{\n    /** Field name to externalize */\n    field: string;\n    /** Pattern for the output file. Supports placeholders from the entity */\n    pattern: string;\n  }>;\n  /** Fields to exclude from the pulled data for this related entity */\n  excludeFields?: string[];\n  /** Foreign key fields to convert to @lookup references for this related entity */\n  lookupFields?: {\n    [fieldName: string]: {\n      entity: string;\n      field: string;\n    };\n  };\n  /** Nested related entities for deep object graphs */\n  relatedEntities?: Record<string, RelatedEntityConfig>;\n}\n\n/**\n * Entity-specific configuration\n * \n * Defines settings for a specific entity type within a directory. Stored in\n * .mj-sync.json files that contain an \"entity\" field. Supports defaults,\n * file patterns, and related entity configuration.\n */\nexport interface EntityConfig {\n  /** Name of the entity this directory contains */\n  entity: string;\n  /** Glob pattern for finding data files (defaults to \"*.json\") */\n  filePattern?: string;\n  /** Default field values applied to all records in this directory */\n  defaults?: Record<string, any>;\n  /** \n   * Directories to ignore during processing\n   * Can be directory names or glob patterns relative to the location of the .mj-sync.json file\n   * Cumulative: subdirectories inherit and add to parent ignoreDirectories\n   * Examples: [\"output\", \"examples\", \"temp\"]\n   */\n  ignoreDirectories?: string[];\n  /** Pull command specific configuration */\n  pull?: {\n    /** Glob pattern for finding existing files to update (defaults to filePattern) */\n    filePattern?: string;\n    /** Whether to create new files for records not found locally */\n    createNewFileIfNotFound?: boolean;\n    /** Filename for new records when createNewFileIfNotFound is true */\n    newFileName?: string;\n    /** Whether to append multiple new records to a single file */\n    appendRecordsToExistingFile?: boolean;\n    /** Whether to update existing records found in local files */\n    updateExistingRecords?: boolean;\n    /** Fields to preserve during updates (never overwrite these) */\n    preserveFields?: string[];\n    /** Strategy for merging updates: \"overwrite\" | \"merge\" | \"skip\" */\n    mergeStrategy?: 'overwrite' | 'merge' | 'skip';\n    /** Create backup files before updating existing files */\n    backupBeforeUpdate?: boolean;\n    /** Directory name for backup files (defaults to \".backups\") */\n    backupDirectory?: string;\n    /** SQL filter to apply when pulling records from database */\n    filter?: string;\n    /** Configuration for pulling related entities */\n    relatedEntities?: Record<string, RelatedEntityConfig>;\n    /** Fields to externalize to separate files with optional configuration */\n    externalizeFields?: string[] | {\n      [fieldName: string]: {\n        /** File extension to use (e.g., \".md\", \".txt\", \".html\") */\n        extension?: string;\n      }\n    } | Array<{\n      /** Field name to externalize */\n      field: string;\n      /** Pattern for the output file. Supports placeholders:\n       * - {Name}: Entity's name field value\n       * - {ID}: Entity's ID\n       * - {FieldName}: The field being externalized\n       * - Any other {FieldName} from the entity\n       * Example: \"@file:templates/{Name}.template.md\"\n       */\n      pattern: string;\n    }>;\n    /** Fields to exclude from the pulled data (e.g., [\"TemplateID\"]) */\n    excludeFields?: string[];\n    /** Foreign key fields to convert to @lookup references */\n    lookupFields?: {\n      /** Field name in this entity (e.g., \"CategoryID\") */\n      [fieldName: string]: {\n        /** Target entity name (e.g., \"AI Prompt Categories\") */\n        entity: string;\n        /** Field in target entity to use for lookup (e.g., \"Name\") */\n        field: string;\n      };\n    };\n    /** Whether to ignore null field values during pull (defaults to false) */\n    ignoreNullFields?: boolean;\n    /** Whether to ignore virtual fields during pull (defaults to false) */\n    ignoreVirtualFields?: boolean;\n  };\n}\n\n/**\n * Folder-level configuration\n * \n * Defines default values that cascade down to all subdirectories. Stored in\n * .mj-folder.json files. Child folders can override parent defaults.\n */\nexport interface FolderConfig {\n  /** Default field values that apply to all entities in this folder and subfolders */\n  defaults: Record<string, any>;\n}\n\n/**\n * Load MemberJunction configuration from the filesystem\n * \n * Searches for mj.config.cjs starting from the current directory and walking up\n * the directory tree. Uses cosmiconfig for flexible configuration loading.\n * \n * @returns MJConfig object if found, null if not found or invalid\n * \n * @example\n * ```typescript\n * const config = loadMJConfig();\n * if (config) {\n *   console.log(`Connecting to ${config.dbHost}:${config.dbPort || 1433}`);\n * }\n * ```\n */\nexport function loadMJConfig(): MJConfig | null {\n  return configManager.loadMJConfig();\n}\n\n/**\n * Load sync configuration from a directory\n * \n * Loads .mj-sync.json file from the specified directory. This file can contain\n * either global sync configuration (no entity field) or entity-specific\n * configuration (with entity field).\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to SyncConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const syncConfig = await loadSyncConfig('/path/to/project');\n * if (syncConfig?.push?.requireConfirmation) {\n *   // Show confirmation prompt\n * }\n * ```\n */\nexport async function loadSyncConfig(dir: string): Promise<SyncConfig | null> {\n  const configPath = path.join(dir, '.mj-sync.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      return await fs.readJson(configPath);\n    } catch (error) {\n      console.error('Error loading sync config:', error);\n      return null;\n    }\n  }\n  \n  return null;\n}\n\n/**\n * Load entity-specific configuration from a directory\n * \n * Loads .mj-sync.json file that contains an \"entity\" field, indicating this\n * directory contains data for a specific entity type. Returns null if the\n * file doesn't exist or doesn't contain an entity field.\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to EntityConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const entityConfig = await loadEntityConfig('./ai-prompts');\n * if (entityConfig) {\n *   console.log(`Directory contains ${entityConfig.entity} records`);\n * }\n * ```\n */\nexport async function loadEntityConfig(dir: string): Promise<EntityConfig | null> {\n  const configPath = path.join(dir, '.mj-sync.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      const config = await fs.readJson(configPath);\n      if (config.entity) {\n        return config;\n      }\n    } catch (error) {\n      console.error('Error loading entity config:', error);\n    }\n  }\n  \n  return null;\n}\n\n/**\n * Load folder-level configuration\n * \n * Loads .mj-folder.json file that contains default values to be applied to\n * all entities in this folder and its subfolders. Used for cascading defaults\n * in deep directory structures.\n * \n * @param dir - Directory path to load configuration from\n * @returns Promise resolving to FolderConfig if found and valid, null otherwise\n * \n * @example\n * ```typescript\n * const folderConfig = await loadFolderConfig('./templates');\n * if (folderConfig?.defaults) {\n *   // Apply folder defaults to records\n * }\n * ```\n */\nexport async function loadFolderConfig(dir: string): Promise<FolderConfig | null> {\n  const configPath = path.join(dir, '.mj-folder.json');\n  \n  if (await fs.pathExists(configPath)) {\n    try {\n      return await fs.readJson(configPath);\n    } catch (error) {\n      console.error('Error loading folder config:', error);\n      return null;\n    }\n  }\n  \n  return null;\n}"]}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { ConfigManager, configManager } from './lib/config-manager';
 export { getSyncEngine, resetSyncEngine } from './lib/singleton-manager';
 export { SQLLogger } from './lib/sql-logger';
 export { TransactionManager } from './lib/transaction-manager';
+export { JsonWriteHelper } from './lib/json-write-helper';
+export { FileWriteBatch } from './lib/file-write-batch';
 export { InitService } from './services/InitService';
 export type { InitOptions, InitCallbacks } from './services/InitService';
 export { PullService } from './services/PullService';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDataProvider = exports.findEntityDirectories = exports.getSystemUser = exports.initializeProvider = exports.loadFolderConfig = exports.loadEntityConfig = exports.loadSyncConfig = exports.loadMJConfig = exports.FormattingService = exports.ValidationService = exports.WatchService = exports.FileResetService = exports.StatusService = exports.PushService = exports.PullService = exports.InitService = exports.TransactionManager = exports.SQLLogger = exports.resetSyncEngine = exports.getSyncEngine = exports.configManager = exports.ConfigManager = exports.SyncEngine = exports.FileBackupManager = void 0;
+exports.getDataProvider = exports.findEntityDirectories = exports.getSystemUser = exports.initializeProvider = exports.loadFolderConfig = exports.loadEntityConfig = exports.loadSyncConfig = exports.loadMJConfig = exports.FormattingService = exports.ValidationService = exports.WatchService = exports.FileResetService = exports.StatusService = exports.PushService = exports.PullService = exports.InitService = exports.FileWriteBatch = exports.JsonWriteHelper = exports.TransactionManager = exports.SQLLogger = exports.resetSyncEngine = exports.getSyncEngine = exports.configManager = exports.ConfigManager = exports.SyncEngine = exports.FileBackupManager = void 0;
 const core_entities_server_1 = require("@memberjunction/core-entities-server");
 // Core library exports
 var file_backup_manager_1 = require("./lib/file-backup-manager");
@@ -17,6 +17,10 @@ var sql_logger_1 = require("./lib/sql-logger");
 Object.defineProperty(exports, "SQLLogger", { enumerable: true, get: function () { return sql_logger_1.SQLLogger; } });
 var transaction_manager_1 = require("./lib/transaction-manager");
 Object.defineProperty(exports, "TransactionManager", { enumerable: true, get: function () { return transaction_manager_1.TransactionManager; } });
+var json_write_helper_1 = require("./lib/json-write-helper");
+Object.defineProperty(exports, "JsonWriteHelper", { enumerable: true, get: function () { return json_write_helper_1.JsonWriteHelper; } });
+var file_write_batch_1 = require("./lib/file-write-batch");
+Object.defineProperty(exports, "FileWriteBatch", { enumerable: true, get: function () { return file_write_batch_1.FileWriteBatch; } });
 // Service exports
 var InitService_1 = require("./services/InitService");
 Object.defineProperty(exports, "InitService", { enumerable: true, get: function () { return InitService_1.InitService; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+EAAgG;AAEhG,uBAAuB;AACvB,iEAA8D;AAArD,wHAAA,iBAAiB,OAAA;AAC1B,iDAA+C;AAAtC,yGAAA,UAAU,OAAA;AAEnB,uDAAoE;AAA3D,+GAAA,aAAa,OAAA;AAAE,+GAAA,aAAa,OAAA;AACrC,6DAAyE;AAAhE,kHAAA,aAAa,OAAA;AAAE,oHAAA,eAAe,OAAA;AACvC,+CAA6C;AAApC,uGAAA,SAAS,OAAA;AAClB,iEAA+D;AAAtD,yHAAA,kBAAkB,OAAA;AAE3B,kBAAkB;AAClB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,0DAAyD;AAAhD,8GAAA,aAAa,OAAA;AAGtB,gEAA+D;AAAtD,oHAAA,gBAAgB,OAAA;AAGzB,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAGrB,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAC1B,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAE1B,sBAAsB;AACtB,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,wGAAA,cAAc,OAAA;AACd,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAMlB,qBAAqB;AACrB,uDAK8B;AAJ5B,oHAAA,kBAAkB,OAAA;AAClB,+GAAA,aAAa,OAAA;AACb,uHAAA,qBAAqB,OAAA;AACrB,iHAAA,eAAe,OAAA;AAejB,IAAA,+DAAwC,GAAE,CAAC","sourcesContent":["import { LoadAIPromptEntityExtendedServerSubClass } from '@memberjunction/core-entities-server';\n\n// Core library exports\nexport { FileBackupManager } from './lib/file-backup-manager';\nexport { SyncEngine } from './lib/sync-engine';\nexport type { RecordData } from './lib/sync-engine';\nexport { ConfigManager, configManager } from './lib/config-manager';\nexport { getSyncEngine, resetSyncEngine } from './lib/singleton-manager';\nexport { SQLLogger } from './lib/sql-logger';\nexport { TransactionManager } from './lib/transaction-manager';\n\n// Service exports\nexport { InitService } from './services/InitService';\nexport type { InitOptions, InitCallbacks } from './services/InitService';\n\nexport { PullService } from './services/PullService';\nexport type { PullOptions, PullCallbacks, PullResult } from './services/PullService';\n\nexport { PushService } from './services/PushService';\nexport type { PushOptions, PushCallbacks, PushResult } from './services/PushService';\n\nexport { StatusService } from './services/StatusService';\nexport type { StatusOptions, StatusCallbacks, StatusResult } from './services/StatusService';\n\nexport { FileResetService } from './services/FileResetService';\nexport type { FileResetOptions, FileResetCallbacks, FileResetResult } from './services/FileResetService';\n\nexport { WatchService } from './services/WatchService';\nexport type { WatchOptions, WatchCallbacks, WatchResult } from './services/WatchService';\n\nexport { ValidationService } from './services/ValidationService';\nexport { FormattingService } from './services/FormattingService';\n\n// Configuration types\nexport {\n  loadMJConfig,\n  loadSyncConfig,\n  loadEntityConfig,\n  loadFolderConfig,\n  type EntityConfig,\n  type FolderConfig,\n  type RelatedEntityConfig\n} from './config';\n\n// Provider utilities\nexport {\n  initializeProvider,\n  getSystemUser,\n  findEntityDirectories,\n  getDataProvider\n} from './lib/provider-utils';\n\n// Validation types\nexport type {\n  ValidationResult,\n  ValidationError,\n  ValidationWarning,\n  EntityDependency,\n  FileValidationResult,\n  ValidationOptions,\n  ReferenceType,\n  ParsedReference\n} from './types/validation';\n\nLoadAIPromptEntityExtendedServerSubClass();"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+EAAgG;AAEhG,uBAAuB;AACvB,iEAA8D;AAArD,wHAAA,iBAAiB,OAAA;AAC1B,iDAA+C;AAAtC,yGAAA,UAAU,OAAA;AAEnB,uDAAoE;AAA3D,+GAAA,aAAa,OAAA;AAAE,+GAAA,aAAa,OAAA;AACrC,6DAAyE;AAAhE,kHAAA,aAAa,OAAA;AAAE,oHAAA,eAAe,OAAA;AACvC,+CAA6C;AAApC,uGAAA,SAAS,OAAA;AAClB,iEAA+D;AAAtD,yHAAA,kBAAkB,OAAA;AAC3B,6DAA0D;AAAjD,oHAAA,eAAe,OAAA;AACxB,2DAAwD;AAA/C,kHAAA,cAAc,OAAA;AAEvB,kBAAkB;AAClB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,sDAAqD;AAA5C,0GAAA,WAAW,OAAA;AAGpB,0DAAyD;AAAhD,8GAAA,aAAa,OAAA;AAGtB,gEAA+D;AAAtD,oHAAA,gBAAgB,OAAA;AAGzB,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAGrB,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAC1B,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAE1B,sBAAsB;AACtB,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,wGAAA,cAAc,OAAA;AACd,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAMlB,qBAAqB;AACrB,uDAK8B;AAJ5B,oHAAA,kBAAkB,OAAA;AAClB,+GAAA,aAAa,OAAA;AACb,uHAAA,qBAAqB,OAAA;AACrB,iHAAA,eAAe,OAAA;AAejB,IAAA,+DAAwC,GAAE,CAAC","sourcesContent":["import { LoadAIPromptEntityExtendedServerSubClass } from '@memberjunction/core-entities-server';\n\n// Core library exports\nexport { FileBackupManager } from './lib/file-backup-manager';\nexport { SyncEngine } from './lib/sync-engine';\nexport type { RecordData } from './lib/sync-engine';\nexport { ConfigManager, configManager } from './lib/config-manager';\nexport { getSyncEngine, resetSyncEngine } from './lib/singleton-manager';\nexport { SQLLogger } from './lib/sql-logger';\nexport { TransactionManager } from './lib/transaction-manager';\nexport { JsonWriteHelper } from './lib/json-write-helper';\nexport { FileWriteBatch } from './lib/file-write-batch';\n\n// Service exports\nexport { InitService } from './services/InitService';\nexport type { InitOptions, InitCallbacks } from './services/InitService';\n\nexport { PullService } from './services/PullService';\nexport type { PullOptions, PullCallbacks, PullResult } from './services/PullService';\n\nexport { PushService } from './services/PushService';\nexport type { PushOptions, PushCallbacks, PushResult } from './services/PushService';\n\nexport { StatusService } from './services/StatusService';\nexport type { StatusOptions, StatusCallbacks, StatusResult } from './services/StatusService';\n\nexport { FileResetService } from './services/FileResetService';\nexport type { FileResetOptions, FileResetCallbacks, FileResetResult } from './services/FileResetService';\n\nexport { WatchService } from './services/WatchService';\nexport type { WatchOptions, WatchCallbacks, WatchResult } from './services/WatchService';\n\nexport { ValidationService } from './services/ValidationService';\nexport { FormattingService } from './services/FormattingService';\n\n// Configuration types\nexport {\n  loadMJConfig,\n  loadSyncConfig,\n  loadEntityConfig,\n  loadFolderConfig,\n  type EntityConfig,\n  type FolderConfig,\n  type RelatedEntityConfig\n} from './config';\n\n// Provider utilities\nexport {\n  initializeProvider,\n  getSystemUser,\n  findEntityDirectories,\n  getDataProvider\n} from './lib/provider-utils';\n\n// Validation types\nexport type {\n  ValidationResult,\n  ValidationError,\n  ValidationWarning,\n  EntityDependency,\n  FileValidationResult,\n  ValidationOptions,\n  ReferenceType,\n  ParsedReference\n} from './types/validation';\n\nLoadAIPromptEntityExtendedServerSubClass();"]}

package/dist/lib/EntityPropertyExtractor.d.ts

@@ -0,0 +1,60 @@
+import { BaseEntity } from '@memberjunction/core';
+/**
+ * Handles discovery and extraction of all properties from BaseEntity objects,
+ * including both database fields and virtual properties defined in subclasses.
+ */
+export declare class EntityPropertyExtractor {
+    /**
+     * Gets ALL properties from a BaseEntity object, including both:
+     * 1. Database fields (from record.GetAll())
+     * 2. Virtual properties (getters defined in subclasses like TemplateText)
+     * @param record The BaseEntity object to get properties from
+     * @param fieldOverrides Optional field value overrides (e.g., for @parent:ID syntax)
+     */
+    extractAllProperties(record: BaseEntity, fieldOverrides?: Record<string, any>): Record<string, any>;
+    /**
+     * Extracts database fields from the entity using GetAll()
+     */
+    private extractDatabaseFields;
+    /**
+     * Applies field overrides to the properties collection
+     */
+    private applyFieldOverrides;
+    /**
+     * Extracts virtual properties by walking the prototype chain
+     */
+    private extractVirtualProperties;
+    /**
+     * Discovers virtual properties (getters) defined in BaseEntity subclasses
+     * Returns property names that are getters but not in the base database fields
+     */
+    private discoverVirtualProperties;
+    /**
+     * Gets the set of database field names from the entity
+     */
+    private getDatabaseFieldNames;
+    /**
+     * Extracts properties from a single prototype level
+     */
+    private extractPropertiesFromPrototype;
+    /**
+     * Determines if a property should be considered for inclusion
+     */
+    private shouldIncludeProperty;
+    /**
+     * Determines if a property descriptor represents a virtual property
+     */
+    private isVirtualProperty;
+    /**
+     * Determines if a property should be skipped during virtual property discovery
+     */
+    private shouldSkipProperty;
+    /**
+     * Checks if property is a common Object.prototype method
+     */
+    private isCommonObjectMethod;
+    /**
+     * Checks if property is a known BaseEntity method or property
+     */
+    private isBaseEntityMethod;
+}

package/dist/lib/EntityPropertyExtractor.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityPropertyExtractor = void 0;
+/**
+ * Handles discovery and extraction of all properties from BaseEntity objects,
+ * including both database fields and virtual properties defined in subclasses.
+ */
+class EntityPropertyExtractor {
+    /**
+     * Gets ALL properties from a BaseEntity object, including both:
+     * 1. Database fields (from record.GetAll())
+     * 2. Virtual properties (getters defined in subclasses like TemplateText)
+     * @param record The BaseEntity object to get properties from
+     * @param fieldOverrides Optional field value overrides (e.g., for @parent:ID syntax)
+     */
+    extractAllProperties(record, fieldOverrides) {
+        const allProperties = {};
+        // 1. Get database fields using GetAll()
+        this.extractDatabaseFields(record, allProperties);
+        // 2. Apply field overrides (e.g., for @parent:ID replacement in related entities)
+        this.applyFieldOverrides(allProperties, fieldOverrides);
+        // 3. Extract virtual properties by walking the prototype chain
+        this.extractVirtualProperties(record, allProperties, fieldOverrides);
+        return allProperties;
+    }
+    /**
+     * Extracts database fields from the entity using GetAll()
+     */
+    extractDatabaseFields(record, allProperties) {
+        if (typeof record.GetAll === 'function') {
+            const dbFields = record.GetAll();
+            Object.assign(allProperties, dbFields);
+        }
+    }
+    /**
+     * Applies field overrides to the properties collection
+     */
+    applyFieldOverrides(allProperties, fieldOverrides) {
+        if (fieldOverrides) {
+            Object.assign(allProperties, fieldOverrides);
+        }
+    }
+    /**
+     * Extracts virtual properties by walking the prototype chain
+     */
+    extractVirtualProperties(record, allProperties, fieldOverrides) {
+        const virtualProperties = this.discoverVirtualProperties(record);
+        for (const propertyName of virtualProperties) {
+            try {
+                // Skip if this property is overridden
+                if (fieldOverrides && propertyName in fieldOverrides) {
+                    continue;
+                }
+                // Use bracket notation to access the getter
+                const value = record[propertyName];
+                // Only include if the value is not undefined and not a function
+                if (value !== undefined && typeof value !== 'function') {
+                    allProperties[propertyName] = value;
+                }
+            }
+            catch (error) {
+                // Skip properties that throw errors when accessed
+                continue;
+            }
+        }
+    }
+    /**
+     * Discovers virtual properties (getters) defined in BaseEntity subclasses
+     * Returns property names that are getters but not in the base database fields
+     */
+    discoverVirtualProperties(record) {
+        const virtualProperties = [];
+        const dbFieldNames = this.getDatabaseFieldNames(record);
+        // Walk the prototype chain to find getters
+        let currentPrototype = Object.getPrototypeOf(record);
+        while (currentPrototype && currentPrototype !== Object.prototype) {
+            this.extractPropertiesFromPrototype(currentPrototype, virtualProperties, dbFieldNames);
+            currentPrototype = Object.getPrototypeOf(currentPrototype);
+        }
+        return virtualProperties;
+    }
+    /**
+     * Gets the set of database field names from the entity
+     */
+    getDatabaseFieldNames(record) {
+        const dbFieldNames = new Set();
+        if (typeof record.GetAll === 'function') {
+            const dbFields = record.GetAll();
+            Object.keys(dbFields).forEach(key => dbFieldNames.add(key));
+        }
+        return dbFieldNames;
+    }
+    /**
+     * Extracts properties from a single prototype level
+     */
+    extractPropertiesFromPrototype(prototype, virtualProperties, dbFieldNames) {
+        const propertyNames = Object.getOwnPropertyNames(prototype);
+        for (const propertyName of propertyNames) {
+            if (this.shouldIncludeProperty(propertyName, virtualProperties, dbFieldNames)) {
+                const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+                if (this.isVirtualProperty(descriptor)) {
+                    virtualProperties.push(propertyName);
+                }
+            }
+        }
+    }
+    /**
+     * Determines if a property should be considered for inclusion
+     */
+    shouldIncludeProperty(propertyName, virtualProperties, dbFieldNames) {
+        // Skip if already found or is a database field
+        if (virtualProperties.includes(propertyName) || dbFieldNames.has(propertyName)) {
+            return false;
+        }
+        // Skip internal properties and methods
+        return !this.shouldSkipProperty(propertyName);
+    }
+    /**
+     * Determines if a property descriptor represents a virtual property
+     */
+    isVirtualProperty(descriptor) {
+        if (!descriptor)
+            return false;
+        // Skip read-only getters (might be computed properties)
+        if (typeof descriptor.get === 'function' && !descriptor.set) {
+            return false;
+        }
+        // Include read-write getter/setter pairs (likely virtual properties)
+        return typeof descriptor.get === 'function' && typeof descriptor.set === 'function';
+    }
+    /**
+     * Determines if a property should be skipped during virtual property discovery
+     */
+    shouldSkipProperty(propertyName) {
+        // Skip private properties (starting with _ or __)
+        if (propertyName.startsWith('_') || propertyName.startsWith('__')) {
+            return true;
+        }
+        // Skip constructor and common Object.prototype methods
+        if (this.isCommonObjectMethod(propertyName)) {
+            return true;
+        }
+        // Skip known BaseEntity methods and properties
+        return this.isBaseEntityMethod(propertyName);
+    }
+    /**
+     * Checks if property is a common Object.prototype method
+     */
+    isCommonObjectMethod(propertyName) {
+        const commonMethods = ['constructor', 'toString', 'valueOf'];
+        return commonMethods.includes(propertyName);
+    }
+    /**
+     * Checks if property is a known BaseEntity method or property
+     */
+    isBaseEntityMethod(propertyName) {
+        const baseEntityMethods = [
+            'Get', 'Set', 'GetAll', 'SetMany', 'LoadFromData', 'Save', 'Load', 'Delete',
+            'Fields', 'Dirty', 'IsSaved', 'PrimaryKeys', 'EntityInfo', 'ContextCurrentUser',
+            'ProviderToUse', 'RecordChanges', 'TransactionGroup'
+        ];
+        return baseEntityMethods.includes(propertyName);
+    }
+}
+exports.EntityPropertyExtractor = EntityPropertyExtractor;
+//# sourceMappingURL=EntityPropertyExtractor.js.map

package/dist/lib/EntityPropertyExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityPropertyExtractor.js","sourceRoot":"","sources":["../../src/lib/EntityPropertyExtractor.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseEntity } from '@memberjunction/core';\n\n/**\n * Handles discovery and extraction of all properties from BaseEntity objects,\n * including both database fields and virtual properties defined in subclasses.\n */\nexport class EntityPropertyExtractor {\n  /**\n   * Gets ALL properties from a BaseEntity object, including both:\n   * 1. Database fields (from record.GetAll())\n   * 2. Virtual properties (getters defined in subclasses like TemplateText)\n   * @param record The BaseEntity object to get properties from\n   * @param fieldOverrides Optional field value overrides (e.g., for @parent:ID syntax)\n   */\n  extractAllProperties(record: BaseEntity, fieldOverrides?: Record<string, any>): Record<string, any> {\n    const allProperties: Record<string, any> = {};\n    \n    // 1. Get database fields using GetAll()\n    this.extractDatabaseFields(record, allProperties);\n    \n    // 2. Apply field overrides (e.g., for @parent:ID replacement in related entities)\n    this.applyFieldOverrides(allProperties, fieldOverrides);\n    \n    // 3. Extract virtual properties by walking the prototype chain\n    this.extractVirtualProperties(record, allProperties, fieldOverrides);\n    \n    return allProperties;\n  }\n\n  /**\n   * Extracts database fields from the entity using GetAll()\n   */\n  private extractDatabaseFields(record: BaseEntity, allProperties: Record<string, any>): void {\n    if (typeof record.GetAll === 'function') {\n      const dbFields = record.GetAll();\n      Object.assign(allProperties, dbFields);\n    }\n  }\n\n  /**\n   * Applies field overrides to the properties collection\n   */\n  private applyFieldOverrides(allProperties: Record<string, any>, fieldOverrides?: Record<string, any>): void {\n    if (fieldOverrides) {\n      Object.assign(allProperties, fieldOverrides);\n    }\n  }\n\n  /**\n   * Extracts virtual properties by walking the prototype chain\n   */\n  private extractVirtualProperties(\n    record: BaseEntity, \n    allProperties: Record<string, any>, \n    fieldOverrides?: Record<string, any>\n  ): void {\n    const virtualProperties = this.discoverVirtualProperties(record);\n    \n    for (const propertyName of virtualProperties) {\n      try {\n        // Skip if this property is overridden\n        if (fieldOverrides && propertyName in fieldOverrides) {\n          continue;\n        }\n        \n        // Use bracket notation to access the getter\n        const value = (record as any)[propertyName];\n        \n        // Only include if the value is not undefined and not a function\n        if (value !== undefined && typeof value !== 'function') {\n          allProperties[propertyName] = value;\n        }\n      } catch (error) {\n        // Skip properties that throw errors when accessed\n        continue;\n      }\n    }\n  }\n\n  /**\n   * Discovers virtual properties (getters) defined in BaseEntity subclasses\n   * Returns property names that are getters but not in the base database fields\n   */\n  private discoverVirtualProperties(record: BaseEntity): string[] {\n    const virtualProperties: string[] = [];\n    const dbFieldNames = this.getDatabaseFieldNames(record);\n    \n    // Walk the prototype chain to find getters\n    let currentPrototype = Object.getPrototypeOf(record);\n    \n    while (currentPrototype && currentPrototype !== Object.prototype) {\n      this.extractPropertiesFromPrototype(currentPrototype, virtualProperties, dbFieldNames);\n      currentPrototype = Object.getPrototypeOf(currentPrototype);\n    }\n    \n    return virtualProperties;\n  }\n\n  /**\n   * Gets the set of database field names from the entity\n   */\n  private getDatabaseFieldNames(record: BaseEntity): Set<string> {\n    const dbFieldNames = new Set<string>();\n    \n    if (typeof record.GetAll === 'function') {\n      const dbFields = record.GetAll();\n      Object.keys(dbFields).forEach(key => dbFieldNames.add(key));\n    }\n    \n    return dbFieldNames;\n  }\n\n  /**\n   * Extracts properties from a single prototype level\n   */\n  private extractPropertiesFromPrototype(\n    prototype: any, \n    virtualProperties: string[], \n    dbFieldNames: Set<string>\n  ): void {\n    const propertyNames = Object.getOwnPropertyNames(prototype);\n    \n    for (const propertyName of propertyNames) {\n      if (this.shouldIncludeProperty(propertyName, virtualProperties, dbFieldNames)) {\n        const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);\n        if (this.isVirtualProperty(descriptor)) {\n          virtualProperties.push(propertyName);\n        }\n      }\n    }\n  }\n\n  /**\n   * Determines if a property should be considered for inclusion\n   */\n  private shouldIncludeProperty(\n    propertyName: string, \n    virtualProperties: string[], \n    dbFieldNames: Set<string>\n  ): boolean {\n    // Skip if already found or is a database field\n    if (virtualProperties.includes(propertyName) || dbFieldNames.has(propertyName)) {\n      return false;\n    }\n    \n    // Skip internal properties and methods\n    return !this.shouldSkipProperty(propertyName);\n  }\n\n  /**\n   * Determines if a property descriptor represents a virtual property\n   */\n  private isVirtualProperty(descriptor: PropertyDescriptor | undefined): boolean {\n    if (!descriptor) return false;\n    \n    // Skip read-only getters (might be computed properties)\n    if (typeof descriptor.get === 'function' && !descriptor.set) {\n      return false;\n    }\n    \n    // Include read-write getter/setter pairs (likely virtual properties)\n    return typeof descriptor.get === 'function' && typeof descriptor.set === 'function';\n  }\n\n  /**\n   * Determines if a property should be skipped during virtual property discovery\n   */\n  private shouldSkipProperty(propertyName: string): boolean {\n    // Skip private properties (starting with _ or __)\n    if (propertyName.startsWith('_') || propertyName.startsWith('__')) {\n      return true;\n    }\n    \n    // Skip constructor and common Object.prototype methods\n    if (this.isCommonObjectMethod(propertyName)) {\n      return true;\n    }\n    \n    // Skip known BaseEntity methods and properties\n    return this.isBaseEntityMethod(propertyName);\n  }\n\n  /**\n   * Checks if property is a common Object.prototype method\n   */\n  private isCommonObjectMethod(propertyName: string): boolean {\n    const commonMethods = ['constructor', 'toString', 'valueOf'];\n    return commonMethods.includes(propertyName);\n  }\n\n  /**\n   * Checks if property is a known BaseEntity method or property\n   */\n  private isBaseEntityMethod(propertyName: string): boolean {\n    const baseEntityMethods = [\n      'Get', 'Set', 'GetAll', 'SetMany', 'LoadFromData', 'Save', 'Load', 'Delete',\n      'Fields', 'Dirty', 'IsSaved', 'PrimaryKeys', 'EntityInfo', 'ContextCurrentUser',\n      'ProviderToUse', 'RecordChanges', 'TransactionGroup'\n    ];\n    \n    return baseEntityMethods.includes(propertyName);\n  }\n}"]}

package/dist/lib/FieldExternalizer.d.ts

@@ -0,0 +1,62 @@
+import { BaseEntity } from '@memberjunction/core';
+/**
+ * Handles externalization of field values to separate files with @file: references
+ */
+export declare class FieldExternalizer {
+    /**
+     * Externalize a field value to a separate file and return @file: reference
+     */
+    externalizeField(fieldName: string, fieldValue: any, pattern: string, recordData: BaseEntity, targetDir: string, existingFileReference?: string, mergeStrategy?: string, verbose?: boolean): Promise<string>;
+    /**
+     * Determines the file path and reference for externalization
+     */
+    private determineFilePath;
+    /**
+     * Checks if we should use an existing file reference
+     */
+    private shouldUseExistingReference;
+    /**
+     * Uses an existing file reference
+     */
+    private useExistingFileReference;
+    /**
+     * Creates a new file reference using the pattern
+     */
+    private createNewFileReference;
+    /**
+     * Processes pattern placeholders with actual values
+     */
+    private processPattern;
+    /**
+     * Replaces a single placeholder in the pattern
+     */
+    private replacePlaceholder;
+    /**
+     * Replaces field placeholders with values from the record
+     */
+    private replaceFieldPlaceholders;
+    /**
+     * Removes @file: prefix if present
+     */
+    private removeFilePrefix;
+    /**
+     * Determines if the file should be written based on content comparison
+     */
+    private shouldWriteFile;
+    /**
+     * Writes the external file with the field content
+     */
+    private writeExternalFile;
+    /**
+     * Prepares content for writing, with JSON pretty-printing if applicable
+     */
+    private prepareContentForWriting;
+    /**
+     * Determines if content should be pretty-printed as JSON
+     */
+    private shouldPrettyPrintAsJson;
+    /**
+     * Sanitize a string for use in filenames
+     */
+    private sanitizeForFilename;
+}