masterrecord 0.2.36 → 0.3.1

package/.claude/settings.local.json

@@ -9,7 +9,26 @@
       "Bash(npm whoami:*)",
       "Bash(npm pkg fix:*)",
       "Bash(~/.npmrc)",
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(node test/includesTransformTest.js:*)",
+      "Bash(node test/securityTest.js:*)",
+      "Bash(node test/transformerTest.js:*)",
+      "Bash(node:*)",
+      "Bash(npm publish)",
+      "Bash(npm owner:*)",
+      "Bash(npm profile get:*)",
+      "Bash(npm cache clean:*)",
+      "Bash(npm config:*)",
+      "Bash(npm publish:*)",
+      "Bash(npm logout)",
+      "Bash(npm access:*)",
+      "Bash(npm view:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)",
+      "Bash(find:*)",
+      "Bash(npm install)",
+      "Bash(ls:*)"
     ],
     "deny": [],
     "ask": []

package/Entity/entityModel.js

@@ -137,6 +137,12 @@ class EntityModel {
         return this;
     }
 
+    // allows you to add custom field transformers for serialization/deserialization
+    transform(transformObj){
+        this.obj.transform = transformObj;
+        return this;
+    }
+
     // allows you to add a virtual object that will skipped from being used as sql objects
     virtual(){
         this.obj.virtual = true;

package/Entity/entityTrackerModel.js

@@ -1,6 +1,8 @@
 
 // version : 0.0.9
 var tools =  require('../Tools');
+var FieldTransformer = require('./fieldTransformer');
+
 class EntityTrackerModel {
 
 
@@ -18,12 +20,27 @@ class EntityTrackerModel {
         this.buildRelationshipModels(modelClass, currentEntity, dataModel);
         
         // loop through data model fields
-        for (const [modelField, modelFieldValue] of modelFields) { 
-            
+        for (const [modelField, modelFieldValue] of modelFields) {
+
             // set the value dynamiclly
             if(!$that._isRelationship(currentEntity[modelField])){
+                // 🔥 Apply fromDatabase transformer when building entity from DB row
+                let transformedValue = modelFieldValue;
+                try {
+                    transformedValue = FieldTransformer.fromDatabase(
+                        modelFieldValue,
+                        currentEntity[modelField],
+                        currentEntity.__name,
+                        modelField
+                    );
+                } catch(transformError) {
+                    console.error(`Warning: Failed to transform ${currentEntity.__name}.${modelField} from database: ${transformError.message}`);
+                    // Use original value if transformation fails (non-fatal)
+                    transformedValue = modelFieldValue;
+                }
+
                 // current entity has a value then add
-                modelClass["__proto__"]["_" + modelField] = modelFieldValue;
+                modelClass["__proto__"]["_" + modelField] = transformedValue;
 
                 Object.defineProperty(modelClass,modelField, {
                     set: function(value) {

package/Entity/fieldTransformer.js

@@ -0,0 +1,266 @@
+/**
+ * FieldTransformer - Production-grade field transformation system
+ *
+ * Allows entity fields to define custom serialization/deserialization logic
+ * for transforming values between JavaScript types and database storage formats.
+ *
+ * @example
+ * class User {
+ *     constructor() {
+ *         this.certified_models = {
+ *             type: "string",
+ *             transform: {
+ *                 toDatabase: (value) => Array.isArray(value) ? JSON.stringify(value) : value,
+ *                 fromDatabase: (value) => {
+ *                     try { return JSON.parse(value); }
+ *                     catch { return []; }
+ *                 }
+ *             }
+ *         };
+ *     }
+ * }
+ *
+ * @author MasterRecord Team
+ * @version 1.0.0
+ */
+
+class FieldTransformer {
+
+    /**
+     * Check if a field definition has a transformer
+     * @param {Object} fieldDef - Field definition from entity
+     * @returns {boolean}
+     */
+    static hasTransformer(fieldDef) {
+        return fieldDef
+            && typeof fieldDef === 'object'
+            && fieldDef.transform
+            && typeof fieldDef.transform === 'object'
+            && (typeof fieldDef.transform.toDatabase === 'function'
+                || typeof fieldDef.transform.fromDatabase === 'function');
+    }
+
+    /**
+     * Validate transformer definition structure
+     * @param {Object} transformer - The transform object
+     * @param {string} entityName - Entity name for error messages
+     * @param {string} fieldName - Field name for error messages
+     * @throws {Error} If transformer is invalid
+     */
+    static validateTransformer(transformer, entityName, fieldName) {
+        if (!transformer || typeof transformer !== 'object') {
+            throw new Error(
+                `Invalid transformer for ${entityName}.${fieldName}: ` +
+                `transform must be an object with toDatabase and/or fromDatabase functions`
+            );
+        }
+
+        const { toDatabase, fromDatabase } = transformer;
+
+        // At least one direction must be provided
+        if (!toDatabase && !fromDatabase) {
+            throw new Error(
+                `Invalid transformer for ${entityName}.${fieldName}: ` +
+                `must provide at least one of: toDatabase, fromDatabase`
+            );
+        }
+
+        // Validate toDatabase if present
+        if (toDatabase !== undefined && typeof toDatabase !== 'function') {
+            throw new Error(
+                `Invalid transformer for ${entityName}.${fieldName}: ` +
+                `toDatabase must be a function, got ${typeof toDatabase}`
+            );
+        }
+
+        // Validate fromDatabase if present
+        if (fromDatabase !== undefined && typeof fromDatabase !== 'function') {
+            throw new Error(
+                `Invalid transformer for ${entityName}.${fieldName}: ` +
+                `fromDatabase must be a function, got ${typeof fromDatabase}`
+            );
+        }
+    }
+
+    /**
+     * Transform a value for database storage
+     * Executes the toDatabase transformer if defined
+     *
+     * @param {*} value - The value to transform
+     * @param {Object} fieldDef - Field definition with transformer
+     * @param {string} entityName - Entity name for error messages
+     * @param {string} fieldName - Field name for error messages
+     * @returns {*} Transformed value
+     * @throws {Error} If transformation fails
+     */
+    static toDatabase(value, fieldDef, entityName, fieldName) {
+        // No transformer - return original value
+        if (!this.hasTransformer(fieldDef)) {
+            return value;
+        }
+
+        const transformer = fieldDef.transform;
+
+        // No toDatabase function - return original value
+        if (!transformer.toDatabase) {
+            return value;
+        }
+
+        // Execute transformation with comprehensive error handling
+        try {
+            const transformed = transformer.toDatabase(value);
+
+            // Validate transformation returned a value
+            if (transformed === undefined) {
+                throw new Error(
+                    `Transformer for ${entityName}.${fieldName} returned undefined. ` +
+                    `Transform functions must return a value.`
+                );
+            }
+
+            return transformed;
+        } catch (err) {
+            // Re-throw with context if it's already our error
+            if (err.message.includes(entityName)) {
+                throw err;
+            }
+
+            // Wrap external errors with context
+            throw new Error(
+                `Transform error for ${entityName}.${fieldName}: ${err.message}\n` +
+                `Original value: ${JSON.stringify(value)}\n` +
+                `Stack: ${err.stack}`
+            );
+        }
+    }
+
+    /**
+     * Transform a value from database storage to application format
+     * Executes the fromDatabase transformer if defined
+     *
+     * @param {*} value - The value from database
+     * @param {Object} fieldDef - Field definition with transformer
+     * @param {string} entityName - Entity name for error messages
+     * @param {string} fieldName - Field name for error messages
+     * @returns {*} Transformed value
+     * @throws {Error} If transformation fails
+     */
+    static fromDatabase(value, fieldDef, entityName, fieldName) {
+        // No transformer - return original value
+        if (!this.hasTransformer(fieldDef)) {
+            return value;
+        }
+
+        const transformer = fieldDef.transform;
+
+        // No fromDatabase function - return original value
+        if (!transformer.fromDatabase) {
+            return value;
+        }
+
+        // Execute transformation with comprehensive error handling
+        try {
+            const transformed = transformer.fromDatabase(value);
+
+            // Allow undefined return for optional transformations
+            // (e.g., parsing may return undefined for null/empty strings)
+            return transformed;
+        } catch (err) {
+            // Re-throw with context if it's already our error
+            if (err.message.includes(entityName)) {
+                throw err;
+            }
+
+            // Wrap external errors with context
+            throw new Error(
+                `Transform error for ${entityName}.${fieldName}: ${err.message}\n` +
+                `Original value: ${JSON.stringify(value)}\n` +
+                `Stack: ${err.stack}`
+            );
+        }
+    }
+
+    /**
+     * Apply toDatabase transformers to all fields in an entity
+     * Used during INSERT/UPDATE operations
+     *
+     * @param {Object} entityData - The entity data to transform
+     * @param {Object} entityDef - Entity definition with field definitions
+     * @returns {Object} New object with transformed values
+     */
+    static applyToDatabaseTransforms(entityData, entityDef) {
+        const transformed = {};
+        const entityName = entityDef.__name || 'Entity';
+
+        for (const fieldName in entityData) {
+            // Skip internal fields
+            if (fieldName.startsWith('__')) {
+                continue;
+            }
+
+            const value = entityData[fieldName];
+            const fieldDef = entityDef[fieldName];
+
+            // If no field definition, pass through
+            if (!fieldDef) {
+                transformed[fieldName] = value;
+                continue;
+            }
+
+            // Apply transformer if present
+            try {
+                transformed[fieldName] = this.toDatabase(value, fieldDef, entityName, fieldName);
+            } catch (err) {
+                // Add operation context
+                throw new Error(
+                    `Failed to transform field for database write: ${err.message}`
+                );
+            }
+        }
+
+        return transformed;
+    }
+
+    /**
+     * Apply fromDatabase transformers to all fields in an entity
+     * Used during SELECT operations when building entities from database rows
+     *
+     * @param {Object} dbRow - Raw database row
+     * @param {Object} entityDef - Entity definition with field definitions
+     * @returns {Object} New object with transformed values
+     */
+    static applyFromDatabaseTransforms(dbRow, entityDef) {
+        const transformed = {};
+        const entityName = entityDef.__name || 'Entity';
+
+        for (const fieldName in dbRow) {
+            // Skip internal fields
+            if (fieldName.startsWith('__')) {
+                continue;
+            }
+
+            const value = dbRow[fieldName];
+            const fieldDef = entityDef[fieldName];
+
+            // If no field definition, pass through
+            if (!fieldDef) {
+                transformed[fieldName] = value;
+                continue;
+            }
+
+            // Apply transformer if present
+            try {
+                transformed[fieldName] = this.fromDatabase(value, fieldDef, entityName, fieldName);
+            } catch (err) {
+                // Add operation context
+                throw new Error(
+                    `Failed to transform field from database: ${err.message}`
+                );
+            }
+        }
+
+        return transformed;
+    }
+}
+
+module.exports = FieldTransformer;

package/Migrations/migrationMySQLQuery.js

@@ -224,7 +224,151 @@ class migrationMySQLQuery {
         return `ALTER TABLE \`${table.tableName}\` RENAME COLUMN \`${table.name}\` TO \`${table.newName}\``
     }
 
-    
+    /**
+     * SEED DATA METHODS
+     * Support for inserting seed data during migrations
+     */
+
+    /**
+     * Insert seed data into a table
+     * @param {string} tableName - Name of the table
+     * @param {Object} data - Data object with column names as keys
+     * @returns {string} INSERT query
+     */
+    insertSeedData(tableName, data){
+        const columns = Object.keys(data).filter(k => !k.startsWith('__'));
+        const values = columns.map(col => {
+            const val = data[col];
+            if(val === null || val === undefined){
+                return 'NULL';
+            }
+            if(typeof val === 'boolean'){
+                return val ? '1' : '0';  // MySQL TINYINT for boolean
+            }
+            if(typeof val === 'number'){
+                return val;
+            }
+            // Escape strings
+            const escaped = String(val).replace(/'/g, "''");
+            return `'${escaped}'`;
+        });
+
+        const columnList = columns.map(c => `\`${c}\``).join(', ');
+        const valueList = values.join(', ');
+
+        return `INSERT INTO \`${tableName}\` (${columnList}) VALUES (${valueList})`;
+    }
+
+    /**
+     * Insert multiple seed records at once
+     * @param {string} tableName - Name of the table
+     * @param {Array} dataArray - Array of data objects
+     * @returns {string} Bulk INSERT query
+     */
+    bulkInsertSeedData(tableName, dataArray){
+        if(!dataArray || dataArray.length === 0){
+            return '';
+        }
+
+        const firstRow = dataArray[0];
+        const columns = Object.keys(firstRow).filter(k => !k.startsWith('__'));
+        const columnList = columns.map(c => `\`${c}\``).join(', ');
+
+        const valueRows = dataArray.map(data => {
+            const values = columns.map(col => {
+                const val = data[col];
+                if(val === null || val === undefined){
+                    return 'NULL';
+                }
+                if(typeof val === 'boolean'){
+                    return val ? '1' : '0';
+                }
+                if(typeof val === 'number'){
+                    return val;
+                }
+                const escaped = String(val).replace(/'/g, "''");
+                return `'${escaped}'`;
+            });
+            return `(${values.join(', ')})`;
+        });
+
+        return `INSERT INTO \`${tableName}\` (${columnList}) VALUES ${valueRows.join(', ')}`;
+    }
+
+    /**
+     * Update seed data (useful for down migrations)
+     * @param {string} tableName - Name of the table
+     * @param {Object} data - Data to update
+     * @param {Object} where - WHERE conditions
+     * @returns {string} UPDATE query
+     */
+    updateSeedData(tableName, data, where){
+        const setClause = Object.keys(data)
+            .filter(k => !k.startsWith('__'))
+            .map(col => {
+                const val = data[col];
+                if(val === null || val === undefined){
+                    return `\`${col}\` = NULL`;
+                }
+                if(typeof val === 'boolean'){
+                    return `\`${col}\` = ${val ? '1' : '0'}`;
+                }
+                if(typeof val === 'number'){
+                    return `\`${col}\` = ${val}`;
+                }
+                const escaped = String(val).replace(/'/g, "''");
+                return `\`${col}\` = '${escaped}'`;
+            })
+            .join(', ');
+
+        const whereClause = Object.keys(where)
+            .map(col => {
+                const val = where[col];
+                if(val === null || val === undefined){
+                    return `\`${col}\` IS NULL`;
+                }
+                if(typeof val === 'boolean'){
+                    return `\`${col}\` = ${val ? '1' : '0'}`;
+                }
+                if(typeof val === 'number'){
+                    return `\`${col}\` = ${val}`;
+                }
+                const escaped = String(val).replace(/'/g, "''");
+                return `\`${col}\` = '${escaped}'`;
+            })
+            .join(' AND ');
+
+        return `UPDATE \`${tableName}\` SET ${setClause} WHERE ${whereClause}`;
+    }
+
+    /**
+     * Delete seed data (useful for down migrations)
+     * @param {string} tableName - Name of the table
+     * @param {Object} where - WHERE conditions
+     * @returns {string} DELETE query
+     */
+    deleteSeedData(tableName, where){
+        const whereClause = Object.keys(where)
+            .map(col => {
+                const val = where[col];
+                if(val === null || val === undefined){
+                    return `\`${col}\` IS NULL`;
+                }
+                if(typeof val === 'boolean'){
+                    return `\`${col}\` = ${val ? '1' : '0'}`;
+                }
+                if(typeof val === 'number'){
+                    return `\`${col}\` = ${val}`;
+                }
+                const escaped = String(val).replace(/'/g, "''");
+                return `\`${col}\` = '${escaped}'`;
+            })
+            .join(' AND ');
+
+        return `DELETE FROM \`${tableName}\` WHERE ${whereClause}`;
+    }
+
+
 }