masterrecord 0.3.27 → 0.3.30

package/.claude/settings.local.json

@@ -38,7 +38,27 @@
       "Bash(master=development masterrecord update-database qaContext)",
       "Bash(chmod:*)",
       "Bash(npm install:*)",
-      "Bash(sqlite3:*)"
+      "Bash(sqlite3:*)",
+      "Bash(for file in /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components/models/app/controllers/api/*.js)",
+      "Bash(do)",
+      "Bash(if grep -q \"this._currentUser = req.authService.currentUser\" \"$file\")",
+      "Bash(then)",
+      "Bash(fi)",
+      "Bash(echo:*)",
+      "Bash(/tmp/fix_controllers.sh)",
+      "Bash(wc -l echo \"\" echo \"Controllers now using async pattern:\" find /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components -name \"*Controller.js\" -path \"*/controllers/api/*\" -exec grep -l \"async _getCurrentUser\\(\\)\" {})",
+      "Bash(/tmp/fix_controllers.sh:*)",
+      "Bash(wc -l echo \"\" echo \"Total with async _getCurrentUser\\(\\):\" find /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components -name \"*Controller.js\" -path \"*/controllers/api/*\" -exec grep -l \"async _getCurrentUser\\(\\)\" {})",
+      "Bash(wc -l echo echo 'Controllers with async _getCurrentUser\\(\\):' find /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components -name *Controller.js -path */controllers/* -exec grep -l 'async _getCurrentUser\\(\\)' {})",
+      "Bash(sort -u __NEW_LINE_463d116b631aaffc__ echo 'Actual controller files \\(without .js extension\\):' find /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components/*/app/controllers/api -name *.js -type f)",
+      "Bash(xargs:*)",
+      "Bash(sort -u __NEW_LINE_463d116b631aaffc__ echo echo 'Files that exist but not referenced in routes \\(might be OK\\):' comm -13 /tmp/route_refs.txt /tmp/actual_files.txt)",
+      "Bash(head -10 __NEW_LINE_463d116b631aaffc__ echo \"\" echo \"Routes referencing non-existent files \\(PROBLEMS\\):\" comm -23 /tmp/route_refs.txt /tmp/actual_files.txt)",
+      "Bash(for file in /Users/alexanderrich/Documents/development/bookbaghq/bookbag-training/components/qa/app/controllers/api/*.js)",
+      "Bash(wc:*)",
+      "Bash(npm link)",
+      "Bash(npm link:*)",
+      "Bash(1)"
     ],
     "deny": [],
     "ask": []

package/Entity/entityModel.js

@@ -111,10 +111,18 @@ class EntityModel {
 
     unique(){
         this.obj.unique = true; // yes
-        return this; 
+        return this;
 
     }
 
+    index(indexName){
+        if(!this.obj.indexes){
+            this.obj.indexes = [];
+        }
+        this.obj.indexes.push(indexName || true);
+        return this;
+    }
+
     // this means that it can be an empty field
     nullable(){
         this.obj.nullable = true; // yes
@@ -217,5 +225,141 @@ class EntityModel {
         this.obj.nullable = false;
         return this
     }
+
+    // ===== Validation Methods =====
+
+    /**
+     * Validate that field value is required (not null, undefined, or empty string)
+     * @param {string} message - Custom error message
+     */
+    required(message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'required',
+            message: message || `${this.obj.name} is required`
+        });
+        this.obj.nullable = false;
+        return this;
+    }
+
+    /**
+     * Validate email format
+     * @param {string} message - Custom error message
+     */
+    email(message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'email',
+            pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+            message: message || `${this.obj.name} must be a valid email address`
+        });
+        return this;
+    }
+
+    /**
+     * Validate minimum string length
+     * @param {number} length - Minimum length
+     * @param {string} message - Custom error message
+     */
+    minLength(length, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'minLength',
+            length: length,
+            message: message || `${this.obj.name} must be at least ${length} characters`
+        });
+        return this;
+    }
+
+    /**
+     * Validate maximum string length
+     * @param {number} length - Maximum length
+     * @param {string} message - Custom error message
+     */
+    maxLength(length, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'maxLength',
+            length: length,
+            message: message || `${this.obj.name} must be at most ${length} characters`
+        });
+        return this;
+    }
+
+    /**
+     * Validate against regex pattern
+     * @param {RegExp} pattern - Regular expression to match
+     * @param {string} message - Custom error message
+     */
+    pattern(regex, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'pattern',
+            pattern: regex,
+            message: message || `${this.obj.name} format is invalid`
+        });
+        return this;
+    }
+
+    /**
+     * Validate minimum numeric value
+     * @param {number} min - Minimum value
+     * @param {string} message - Custom error message
+     */
+    min(minValue, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'min',
+            min: minValue,
+            message: message || `${this.obj.name} must be at least ${minValue}`
+        });
+        return this;
+    }
+
+    /**
+     * Validate maximum numeric value
+     * @param {number} max - Maximum value
+     * @param {string} message - Custom error message
+     */
+    max(maxValue, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'max',
+            max: maxValue,
+            message: message || `${this.obj.name} must be at most ${maxValue}`
+        });
+        return this;
+    }
+
+    /**
+     * Custom validation function
+     * @param {Function} validatorFn - Function that returns true if valid, false if invalid
+     * @param {string} message - Custom error message
+     */
+    custom(validatorFn, message) {
+        if (!this.obj.validators) {
+            this.obj.validators = [];
+        }
+        this.obj.validators.push({
+            type: 'custom',
+            validator: validatorFn,
+            message: message || `${this.obj.name} is invalid`
+        });
+        return this;
+    }
 }
 module.exports = EntityModel;

package/Entity/entityModelBuilder.js

@@ -17,16 +17,34 @@ class EntityModelBuilder {
         if (constructorIndex > -1) {
             methodNamesArray.splice(constructorIndex, 1);
         }
+
+        // Define lifecycle hook method names that should not be treated as field definitions
+        const lifecycleHooks = ['beforeSave', 'afterSave', 'beforeDelete', 'afterDelete'];
+
         // loop through all method names in the entity model
         for (var i = 0; i < methodNamesArray.length; i++) {
+            const methodName = methodNamesArray[i];
+
+            // Skip lifecycle hooks - they should not be called during entity construction
+            if (lifecycleHooks.includes(methodName)) {
+                // Store lifecycle hooks with the actual method function so they can be copied to entity instances
+                obj[methodName] = {
+                    virtual: true,
+                    lifecycle: true,
+                    name: methodName,
+                    method: mod[methodName] // Store the method (not bound yet - will be bound to entity instance)
+                };
+                continue;
+            }
+
             let MDB = new modelDB(model.name); // create a new instance of entity Model class
-            mod[methodNamesArray[i]](MDB);
+            mod[methodName](MDB);
             this.cleanNull(MDB.obj); // remove objects that are null or undefined
             if(Object.keys(MDB.obj).length === 0){
                 MDB.obj.virtual = true;
             }
-            MDB.obj.name = methodNamesArray[i];
-            obj[methodNamesArray[i]] = MDB.obj;
+            MDB.obj.name = methodName;
+            obj[methodName] = MDB.obj;
         }
         return obj;
     }

package/Entity/entityTrackerModel.js

@@ -14,11 +14,12 @@ class EntityTrackerModel {
         var modelClass = this.buildObject(); // build entity with models
         modelClass.__proto__ = {};
         const modelFields = Object.entries(dataModel); /// return array of objects
+
         modelClass.__entity = currentEntity;
         modelClass.__name = currentEntity.__name;
         modelClass.__context = context;
         this.buildRelationshipModels(modelClass, currentEntity, dataModel);
-        
+
         // loop through data model fields
         for (const [modelField, modelFieldValue] of modelFields) {
 
@@ -44,6 +45,67 @@ class EntityTrackerModel {
 
                 Object.defineProperty(modelClass,modelField, {
                     set: function(value) {
+                        // Run validators before setting value
+                        const fieldDef = currentEntity[modelField];
+                        if (fieldDef && fieldDef.validators && Array.isArray(fieldDef.validators)) {
+                            for (const validator of fieldDef.validators) {
+                                let isValid = true;
+                                let errorMsg = validator.message;
+
+                                switch (validator.type) {
+                                    case 'required':
+                                        isValid = value !== null && value !== undefined && value !== '';
+                                        break;
+
+                                    case 'email':
+                                        if (value) {
+                                            isValid = validator.pattern.test(value);
+                                        }
+                                        break;
+
+                                    case 'minLength':
+                                        if (value && typeof value === 'string') {
+                                            isValid = value.length >= validator.length;
+                                        }
+                                        break;
+
+                                    case 'maxLength':
+                                        if (value && typeof value === 'string') {
+                                            isValid = value.length <= validator.length;
+                                        }
+                                        break;
+
+                                    case 'pattern':
+                                        if (value) {
+                                            isValid = validator.pattern.test(value);
+                                        }
+                                        break;
+
+                                    case 'min':
+                                        if (value !== null && value !== undefined) {
+                                            isValid = Number(value) >= validator.min;
+                                        }
+                                        break;
+
+                                    case 'max':
+                                        if (value !== null && value !== undefined) {
+                                            isValid = Number(value) <= validator.max;
+                                        }
+                                        break;
+
+                                    case 'custom':
+                                        if (typeof validator.validator === 'function') {
+                                            isValid = validator.validator(value);
+                                        }
+                                        break;
+                                }
+
+                                if (!isValid) {
+                                    throw new Error(`Validation failed: ${errorMsg}`);
+                                }
+                            }
+                        }
+
                         modelClass.__state = "modified";
                         modelClass.__dirtyFields.push(modelField);
                         // ensure this entity is tracked on any modification
@@ -93,6 +155,194 @@ class EntityTrackerModel {
             return await this.__context.saveChanges();
         };
 
+        // Convert entity to plain JavaScript object
+        modelClass.toObject = function(options = {}) {
+            const includeRelationships = options.includeRelationships !== false;
+            const depth = options.depth || 1;
+            const visited = options._visited || new WeakSet();
+
+            // Prevent circular reference infinite loops
+            if (visited.has(this)) {
+                return { __circular: true, __entityName: this.__name, id: this[this.__primaryKey] };
+            }
+            visited.add(this);
+
+            const plain = {};
+
+            // Method 1: Access internal _values property (v0.3.28+ architecture)
+            // This is the FASTEST method - direct access to plain data storage
+            if (this._values && typeof this._values === 'object') {
+                for (const key in this._values) {
+                    if (this._values.hasOwnProperty(key)) {
+                        plain[key] = this._values[key];
+                    }
+                }
+            } else {
+                // Method 2: Fallback - iterate through entity definition (for older versions)
+                for (const fieldName in this.__entity) {
+                    if (fieldName.startsWith('__')) continue;
+
+                    const fieldDef = this.__entity[fieldName];
+                    const isRelationship = fieldDef?.type === 'hasMany' ||
+                                           fieldDef?.type === 'hasOne' ||
+                                           fieldDef?.relationshipType === 'belongsTo';
+
+                    // Skip relationships in this pass
+                    if (!isRelationship) {
+                        try {
+                            plain[fieldName] = this[fieldName];
+                        } catch (e) {
+                            // Skip fields that throw errors when accessed
+                        }
+                    }
+                }
+            }
+
+            // Handle relationships recursively with depth limit and cycle detection
+            if (includeRelationships && depth > 0) {
+                for (const fieldName in this.__entity) {
+                    const fieldDef = this.__entity[fieldName];
+                    const isRelationship = fieldDef?.type === 'hasMany' ||
+                                           fieldDef?.type === 'hasOne' ||
+                                           fieldDef?.relationshipType === 'belongsTo';
+
+                    if (isRelationship) {
+                        try {
+                            const value = this[fieldName];
+
+                            if (Array.isArray(value)) {
+                                plain[fieldName] = value.map(item => {
+                                    if (item?.toObject && typeof item.toObject === 'function') {
+                                        return item.toObject({
+                                            depth: depth - 1,
+                                            _visited: visited
+                                        });
+                                    }
+                                    return item;
+                                });
+                            } else if (value?.toObject && typeof value.toObject === 'function') {
+                                plain[fieldName] = value.toObject({
+                                    depth: depth - 1,
+                                    _visited: visited
+                                });
+                            }
+                        } catch (e) {
+                            // Skip relationships that throw errors when accessed
+                        }
+                    }
+                }
+            }
+
+            return plain;
+        };
+
+        // JSON.stringify compatibility - prevents circular reference errors
+        modelClass.toJSON = function() {
+            return this.toObject({ includeRelationships: false });
+        };
+
+        // Delete entity from database
+        modelClass.delete = async function() {
+            if (!this.__context) {
+                throw new Error('Cannot delete: entity is not attached to a context');
+            }
+
+            // Mark entity for deletion
+            this.__state = 'delete';
+
+            // Ensure entity is tracked
+            if (!this.__context.__trackedEntitiesMap.has(this.__ID)) {
+                this.__context.__track(this);
+            }
+
+            // Execute delete via saveChanges (handles cascade deletion)
+            return await this.__context.saveChanges();
+        };
+
+        // Reload entity from database
+        modelClass.reload = async function() {
+            if (!this.__context) {
+                throw new Error('Cannot reload: entity is not attached to a context');
+            }
+
+            // Get primary key
+            const primaryKey = tools.getPrimaryKeyObject(this.__entity);
+            const primaryKeyValue = this[primaryKey];
+
+            if (!primaryKeyValue) {
+                throw new Error('Cannot reload: entity has no primary key value');
+            }
+
+            // Fetch fresh from database
+            const EntityClass = this.__context[this.__name];
+            const fresh = await EntityClass.findById(primaryKeyValue);
+            if (!fresh) {
+                throw new Error(
+                    `Cannot reload: ${this.__name} with ${primaryKey}=${primaryKeyValue} not found`
+                );
+            }
+
+            // Copy all field values from fresh entity to this entity
+            for (const fieldName in this.__entity) {
+                if (fieldName.startsWith('__')) continue;
+
+                const fieldDef = this.__entity[fieldName];
+                const isRelationship = fieldDef?.type === 'hasMany' ||
+                                       fieldDef?.type === 'hasOne' ||
+                                       fieldDef?.relationshipType === 'belongsTo';
+
+                // Only reload scalar fields
+                if (!isRelationship) {
+                    this.__proto__["_" + fieldName] = fresh.__proto__["_" + fieldName];
+                }
+            }
+
+            // Reset dirty fields and state
+            this.__dirtyFields = [];
+            this.__state = 'track';
+
+            return this;
+        };
+
+        // Clone entity for duplication
+        modelClass.clone = function() {
+            if (!this.__context) {
+                throw new Error('Cannot clone: entity is not attached to a context');
+            }
+
+            const EntityClass = this.__context[this.__name];
+            const cloned = EntityClass.new();
+
+            // Get primary key (to skip it)
+            const primaryKey = tools.getPrimaryKeyObject(this.__entity);
+
+            // Copy all non-primary key fields
+            for (const fieldName in this.__entity) {
+                if (fieldName.startsWith('__')) continue;
+                if (fieldName === primaryKey) continue;
+
+                const fieldDef = this.__entity[fieldName];
+                const isRelationship = fieldDef?.type === 'hasMany' ||
+                                       fieldDef?.type === 'hasOne' ||
+                                       fieldDef?.relationshipType === 'belongsTo';
+
+                if (!isRelationship) {
+                    cloned[fieldName] = this[fieldName];
+                }
+            }
+
+            return cloned;
+        };
+
+        // Copy lifecycle hooks from entity definition to entity instance
+        for (const fieldName in currentEntity) {
+            const fieldDef = currentEntity[fieldName];
+            if (fieldDef && fieldDef.lifecycle === true && fieldDef.method) {
+                // Bind the lifecycle hook method directly to this entity instance
+                modelClass[fieldName] = fieldDef.method.bind(modelClass);
+            }
+        }
+
         return modelClass;
     }
 

package/Migrations/migrationMySQLQuery.js

@@ -232,6 +232,20 @@ class migrationMySQLQuery {
         return `ALTER TABLE \`${table.tableName}\` RENAME COLUMN \`${table.name}\` TO \`${table.newName}\``
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX \`${indexName}\` ON \`${indexInfo.tableName}\`(\`${indexInfo.columnName}\`)`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX \`${indexName}\` ON \`${indexInfo.tableName}\``;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationPostgresQuery.js

@@ -219,6 +219,20 @@ class migrationPostgresQuery {
         return `ALTER TABLE "${table.tableName}" RENAME COLUMN "${table.name}" TO "${table.newName}"`;
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${indexInfo.tableName}"("${indexInfo.columnName}")`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX IF EXISTS "${indexName}"`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationSQLiteQuery.js

@@ -187,6 +187,20 @@ class migrationSQLiteQuery {
         return `ALTER TABLE ${table.tableName} RENAME COLUMN ${table.name} TO ${table.newName}`
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX IF NOT EXISTS ${indexName} ON ${indexInfo.tableName}(${indexInfo.columnName})`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX IF EXISTS ${indexName}`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationTemplate.js

@@ -82,6 +82,44 @@ module.exports = ${this.name};
         }
     }
 
+    createIndex(type, indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columnName: indexInfo.columnName,
+            indexName: indexInfo.indexName
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.createIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.dropIndex(${indexInfoStr});`
+        }
+    }
+
+    dropIndex(type, indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columnName: indexInfo.columnName,
+            indexName: indexInfo.indexName
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.dropIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.createIndex(${indexInfoStr});`
+        }
+    }
+
 }
 
 module.exports = MigrationTemplate;