masterrecord 0.3.29 → 0.3.31

package/Entity/entityModel.js

@@ -111,8 +111,16 @@ 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

package/Entity/entityModelBuilder.js

@@ -46,17 +46,60 @@ class EntityModelBuilder {
             MDB.obj.name = methodName;
             obj[methodName] = MDB.obj;
         }
+
+        // Extract composite indexes from static property (Option A)
+        if (model.compositeIndexes) {
+            obj.__compositeIndexes = this.#normalizeCompositeIndexes(
+                model.compositeIndexes,
+                model.name
+            );
+        } else {
+            obj.__compositeIndexes = [];  // Initialize empty array
+        }
+
         return obj;
     }
 
     static cleanNull(obj) {
-        for (var propName in obj) { 
+        for (var propName in obj) {
           if (obj[propName] === null) {
             delete obj[propName];
           }
         }
     }
 
+    static #normalizeCompositeIndexes(indexes, tableName) {
+        if (!Array.isArray(indexes)) {
+            throw new Error(`compositeIndexes must be an array`);
+        }
+
+        return indexes.map((index, i) => {
+            // Simple array: ['col1', 'col2'] -> auto-generate name
+            if (Array.isArray(index)) {
+                const colNames = index.join('_');
+                return {
+                    columns: index,
+                    name: `idx_${tableName.toLowerCase()}_${colNames}`,
+                    unique: false
+                };
+            }
+
+            // Object: { columns: [...], name?, unique? }
+            if (!index.columns || !Array.isArray(index.columns)) {
+                throw new Error(`Composite index must have 'columns' array`);
+            }
+
+            const name = index.name ||
+                `idx_${tableName.toLowerCase()}_${index.columns.join('_')}`;
+
+            return {
+                columns: index.columns,
+                name: name,
+                unique: index.unique || false
+            };
+        });
+    }
+
 }
 
 module.exports = EntityModelBuilder;

package/Migrations/migrationMySQLQuery.js

@@ -232,6 +232,30 @@ 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}\``;
+    }
+
+    createCompositeIndex(indexInfo){
+        const columns = indexInfo.columns.map(c => `\`${c}\``).join(', ');
+        const uniqueKeyword = indexInfo.unique ? 'UNIQUE ' : '';
+        return `CREATE ${uniqueKeyword}INDEX \`${indexInfo.indexName}\` ON \`${indexInfo.tableName}\`(${columns})`;
+    }
+
+    dropCompositeIndex(indexInfo){
+        return `DROP INDEX \`${indexInfo.indexName}\` ON \`${indexInfo.tableName}\``;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationPostgresQuery.js

@@ -219,6 +219,30 @@ 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}"`;
+    }
+
+    createCompositeIndex(indexInfo){
+        const columns = indexInfo.columns.map(c => `"${c}"`).join(', ');
+        const uniqueKeyword = indexInfo.unique ? 'UNIQUE ' : '';
+        return `CREATE ${uniqueKeyword}INDEX IF NOT EXISTS "${indexInfo.indexName}" ON "${indexInfo.tableName}"(${columns})`;
+    }
+
+    dropCompositeIndex(indexInfo){
+        return `DROP INDEX IF EXISTS "${indexInfo.indexName}"`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationSQLiteQuery.js

@@ -187,6 +187,30 @@ 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}`;
+    }
+
+    createCompositeIndex(indexInfo){
+        const columns = indexInfo.columns.join(', ');
+        const uniqueKeyword = indexInfo.unique ? 'UNIQUE ' : '';
+        return `CREATE ${uniqueKeyword}INDEX IF NOT EXISTS ${indexInfo.indexName} ON ${indexInfo.tableName}(${columns})`;
+    }
+
+    dropCompositeIndex(indexInfo){
+        return `DROP INDEX IF EXISTS ${indexInfo.indexName}`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationTemplate.js

@@ -82,6 +82,76 @@ 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});`
+        }
+    }
+
+    createCompositeIndex(type, indexInfo){
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columns: indexInfo.columns,
+            indexName: indexInfo.indexName,
+            unique: indexInfo.unique
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.createCompositeIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.dropCompositeIndex(${indexInfoStr});`
+        }
+    }
+
+    dropCompositeIndex(type, indexInfo){
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columns: indexInfo.columns,
+            indexName: indexInfo.indexName,
+            unique: indexInfo.unique
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.dropCompositeIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.createCompositeIndex(${indexInfoStr});`
+        }
+    }
+
 }
 
 module.exports = MigrationTemplate;

package/Migrations/migrations.js

@@ -24,7 +24,11 @@ class Migrations{
                         newColumns : [],
                         newTables : [],
                         deletedColumns : [],
-                        updatedColumns : []
+                        updatedColumns : [],
+                        newIndexes : [],
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : []
                     }
                     tables.push(table);
                 });
@@ -38,9 +42,13 @@ class Migrations{
                         newColumns : [],
                         newTables : [],
                         deletedColumns : [],
-                        updatedColumns : []
+                        updatedColumns : [],
+                        newIndexes : [],
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : []
                     }
-                    
+
                     oldSchema.forEach(function (oldItem, index) {
                         var oldItemName = oldItem["__name"];
                         if(table.name === oldItemName){
@@ -48,7 +56,7 @@ class Migrations{
                             tables.push(table);
                         }
                     });
-    
+
                 });
             }
 
@@ -156,11 +164,164 @@ class Migrations{
     #buildMigrationObject(oldSchema, newSchema){
 
         var tables = this.#organizeSchemaByTables(oldSchema, newSchema);
-        
+
         tables = this.#findNewTables(tables);
         tables = this.#findNewColumns(tables);
         tables = this.#findDeletedColumns(tables);
         tables = this.#findUpdatedColumns(tables);
+        tables = this.#findNewIndexes(tables);
+        tables = this.#findDeletedIndexes(tables);
+        tables = this.#findNewCompositeIndexes(tables);
+        tables = this.#findDeletedCompositeIndexes(tables);
+        return tables;
+    }
+
+    #findNewIndexes(tables){
+        tables.forEach(function (item, index) {
+            if(item.new && item.old){
+                Object.keys(item.new).forEach(function (key) {
+                    if(typeof item.new[key] === "object" && item.new[key].indexes){
+                        var columnName = item.new[key].name;
+                        var newIndexes = item.new[key].indexes;
+
+                        // Check if this column existed before
+                        var oldColumn = null;
+                        Object.keys(item.old).forEach(function (oldKey) {
+                            if(typeof item.old[oldKey] === "object" && item.old[oldKey].name === columnName){
+                                oldColumn = item.old[oldKey];
+                            }
+                        });
+
+                        // If column didn't exist before, or didn't have indexes, all indexes are new
+                        if(!oldColumn || !oldColumn.indexes){
+                            newIndexes.forEach(function(indexName){
+                                item.newIndexes.push({
+                                    tableName: item.name,
+                                    columnName: columnName,
+                                    indexName: indexName
+                                });
+                            });
+                        } else {
+                            // Check for new indexes that weren't in the old column
+                            newIndexes.forEach(function(indexName){
+                                if(!oldColumn.indexes.includes(indexName)){
+                                    item.newIndexes.push({
+                                        tableName: item.name,
+                                        columnName: columnName,
+                                        indexName: indexName
+                                    });
+                                }
+                            });
+                        }
+                    }
+                });
+            }
+        });
+        return tables;
+    }
+
+    #findDeletedIndexes(tables){
+        tables.forEach(function (item, index) {
+            if(item.new && item.old){
+                Object.keys(item.old).forEach(function (key) {
+                    if(typeof item.old[key] === "object" && item.old[key].indexes){
+                        var columnName = item.old[key].name;
+                        var oldIndexes = item.old[key].indexes;
+
+                        // Check if this column still exists
+                        var newColumn = null;
+                        Object.keys(item.new).forEach(function (newKey) {
+                            if(typeof item.new[newKey] === "object" && item.new[newKey].name === columnName){
+                                newColumn = item.new[newKey];
+                            }
+                        });
+
+                        // If column doesn't exist anymore, or doesn't have indexes, all indexes are deleted
+                        if(!newColumn || !newColumn.indexes){
+                            oldIndexes.forEach(function(indexName){
+                                item.deletedIndexes.push({
+                                    tableName: item.name,
+                                    columnName: columnName,
+                                    indexName: indexName
+                                });
+                            });
+                        } else {
+                            // Check for indexes that were removed
+                            oldIndexes.forEach(function(indexName){
+                                if(!newColumn.indexes.includes(indexName)){
+                                    item.deletedIndexes.push({
+                                        tableName: item.name,
+                                        columnName: columnName,
+                                        indexName: indexName
+                                    });
+                                }
+                            });
+                        }
+                    }
+                });
+            }
+        });
+        return tables;
+    }
+
+    #findNewCompositeIndexes(tables) {
+        tables.forEach(function (item, index) {
+            if (item.new && item.old) {
+                const newComposite = item.new.__compositeIndexes || [];
+                const oldComposite = item.old.__compositeIndexes || [];
+
+                newComposite.forEach(function(newIdx) {
+                    const exists = oldComposite.some(oldIdx =>
+                        oldIdx.name === newIdx.name
+                    );
+
+                    if (!exists) {
+                        item.newCompositeIndexes.push({
+                            tableName: item.name,
+                            columns: newIdx.columns,
+                            indexName: newIdx.name,
+                            unique: newIdx.unique
+                        });
+                    }
+                });
+            } else if (item.new && !item.old) {
+                // New table - all composite indexes are new
+                const composites = item.new.__compositeIndexes || [];
+                composites.forEach(function(idx) {
+                    item.newCompositeIndexes.push({
+                        tableName: item.name,
+                        columns: idx.columns,
+                        indexName: idx.name,
+                        unique: idx.unique
+                    });
+                });
+            }
+        });
+        return tables;
+    }
+
+    #findDeletedCompositeIndexes(tables) {
+        tables.forEach(function (item, index) {
+            if (item.new && item.old) {
+                const newComposite = item.new.__compositeIndexes || [];
+                const oldComposite = item.old.__compositeIndexes || [];
+
+                oldComposite.forEach(function(oldIdx) {
+                    const exists = newComposite.some(newIdx =>
+                        newIdx.name === oldIdx.name
+                    );
+
+                    if (!exists) {
+                        item.deletedCompositeIndexes.push({
+                            tableName: item.name,
+                            columns: oldIdx.columns,
+                            indexName: oldIdx.name,
+                            unique: oldIdx.unique
+                        });
+                    }
+                });
+            }
+        });
         return tables;
     }
 
@@ -302,6 +463,10 @@ class Migrations{
                (t.newColumns && t.newColumns.length) ||
                (t.deletedColumns && t.deletedColumns.length) ||
                (t.updatedColumns && t.updatedColumns.length) ||
+               (t.newIndexes && t.newIndexes.length) ||
+               (t.deletedIndexes && t.deletedIndexes.length) ||
+               (t.newCompositeIndexes && t.newCompositeIndexes.length) ||
+               (t.deletedCompositeIndexes && t.deletedCompositeIndexes.length) ||
                (t.old === null) || (t.new === null)){
                 return true;
             }
@@ -348,6 +513,22 @@ class Migrations{
                 }
             });
 
+            item.newIndexes.forEach(function (indexInfo, index) {
+                MT.createIndex("up", indexInfo);
+            });
+
+            item.deletedIndexes.forEach(function (indexInfo, index) {
+                MT.dropIndex("up", indexInfo);
+            });
+
+            item.newCompositeIndexes.forEach(function (indexInfo, index) {
+                MT.createCompositeIndex("up", indexInfo);
+            });
+
+            item.deletedCompositeIndexes.forEach(function (indexInfo, index) {
+                MT.dropCompositeIndex("up", indexInfo);
+            });
+
         });
 
        return MT.get();

package/Migrations/schema.js

@@ -110,6 +110,35 @@ class schema{
                     var query = queryBuilder.createTable(table);
                     this.context._execute(query);
                 }
+
+                // Create indexes for columns that have .index() defined
+                const self = this;
+                Object.keys(table).forEach(function(key){
+                    if(typeof table[key] === "object" && table[key].indexes && !key.startsWith('__')){
+                        const columnName = table[key].name;
+                        table[key].indexes.forEach(function(indexName){
+                            const indexInfo = {
+                                tableName: tableName,
+                                columnName: columnName,
+                                indexName: indexName
+                            };
+                            self.createIndex(indexInfo);
+                        });
+                    }
+                });
+
+                // Create composite indexes
+                if (table.__compositeIndexes) {
+                    table.__compositeIndexes.forEach(function(compositeIdx) {
+                        const indexInfo = {
+                            tableName: tableName,
+                            columns: compositeIdx.columns,
+                            indexName: compositeIdx.name,
+                            unique: compositeIdx.unique
+                        };
+                        self.createCompositeIndex(indexInfo);
+                    });
+                }
             }
         }else{
             console.log("Table that you're trying to create is undefined. Please check if there are any changes that need to be made");
@@ -394,6 +423,106 @@ class schema{
         }
     }
 
+    createIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
+    dropIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
+    createCompositeIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.createCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.createCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.createCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
+    dropCompositeIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.dropCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.dropCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.dropCompositeIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
     seed(tableName, rows){
         if(!tableName || !rows){ return; }
         const items = Array.isArray(rows) ? rows : [rows];

package/context.js

@@ -980,6 +980,10 @@ class context {
         }
 
         validModel.__name = tableName;
+
+        // Merge context-level composite indexes with entity-defined indexes
+        this.#mergeCompositeIndexes(validModel, tableName);
+
         this.__entities.push(validModel);  // Store model object
         const buildMod = tools.createNewInstance(validModel, query, this);
         this.__builderEntities.push(buildMod);  // Store query builder entity
@@ -994,6 +998,85 @@ class context {
         });
     }
 
+    /**
+     * Define a composite index on an entity (Option C - Context-level)
+     * @param {Function|string} model - Entity class or table name
+     * @param {Array<string>} columns - Column names to include in index
+     * @param {Object} options - Index options { name?: string, unique?: boolean }
+     */
+    compositeIndex(model, columns, options = {}) {
+        // Resolve table name
+        let tableName;
+        if (typeof model === 'string') {
+            tableName = model;
+        } else if (typeof model === 'function') {
+            tableName = model.name;
+        } else {
+            throw new Error('compositeIndex: model must be entity class or table name');
+        }
+
+        // Validate columns
+        if (!Array.isArray(columns) || columns.length < 2) {
+            throw new Error('compositeIndex: columns must be array with at least 2 columns');
+        }
+
+        // Auto-generate name if not provided
+        const indexName = options.name ||
+            `idx_${tableName.toLowerCase()}_${columns.join('_')}`;
+
+        const indexDef = {
+            columns: columns,
+            name: indexName,
+            unique: options.unique || false
+        };
+
+        // Store in context for later merging with entity-defined indexes
+        if (!this.__contextCompositeIndexes) {
+            this.__contextCompositeIndexes = {};
+        }
+        if (!this.__contextCompositeIndexes[tableName]) {
+            this.__contextCompositeIndexes[tableName] = [];
+        }
+
+        // Check for duplicate index names
+        const existing = this.__contextCompositeIndexes[tableName].find(
+            idx => idx.name === indexName
+        );
+        if (existing) {
+            console.warn(`Warning: Composite index '${indexName}' already defined on ${tableName}`);
+            return;
+        }
+
+        this.__contextCompositeIndexes[tableName].push(indexDef);
+    }
+
+    /**
+     * Merge context-level and entity-level composite indexes
+     * @private
+     * @param {Object} entityObj - Entity object with __compositeIndexes
+     * @param {string} tableName - Table name
+     */
+    #mergeCompositeIndexes(entityObj, tableName) {
+        // Start with entity-defined indexes
+        const entityIndexes = entityObj.__compositeIndexes || [];
+
+        // Add context-defined indexes
+        const contextIndexes = (this.__contextCompositeIndexes &&
+                               this.__contextCompositeIndexes[tableName]) || [];
+
+        // Merge and deduplicate by name
+        const allIndexes = [...entityIndexes];
+        const existingNames = new Set(entityIndexes.map(idx => idx.name));
+
+        contextIndexes.forEach(idx => {
+            if (!existingNames.has(idx.name)) {
+                allIndexes.push(idx);
+            }
+        });
+
+        entityObj.__compositeIndexes = allIndexes;
+    }
+
     /**
      * Get current model validation state
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "description": "An Object-relational mapping for the Master framework. Master Record connects classes to relational database tables to establish a database with almost zero-configuration ",
   "main": "MasterRecord.js",
   "bin": {

package/readme.md

@@ -1790,6 +1790,336 @@ try {
 
 ---
 
+## Field Constraints & Indexes
+
+Define database constraints and performance indexes using the fluent API:
+
+```javascript
+class User {
+    id(db) {
+        db.integer().primary().auto();
+    }
+
+    email(db) {
+        db.string()
+          .notNullable()
+          .unique()
+          .index();  // Creates performance index
+    }
+
+    username(db) {
+        db.string()
+          .notNullable()
+          .index('idx_username_custom');  // Custom index name
+    }
+
+    status(db) {
+        db.string().nullable();
+    }
+
+    created_at(db) {
+        db.timestamp().default('CURRENT_TIMESTAMP');
+    }
+}
+```
+
+### Available Constraint Methods
+
+- `.notNullable()` - Column cannot be NULL
+- `.nullable()` - Column can be NULL (default)
+- `.unique()` - Unique constraint (enforces uniqueness at DB level)
+- `.index()` - Creates performance index (auto-generated name: `idx_tablename_columnname`)
+- `.index('custom_name')` - Creates index with custom name
+- `.primary()` - Primary key (automatically indexed)
+- `.default(value)` - Default value
+
+### Index vs Unique Constraint
+
+**Understanding the difference:**
+
+- `.unique()` creates a UNIQUE constraint (prevents duplicate values, enforces data integrity)
+- `.index()` creates a performance index (improves query speed, allows duplicates)
+- You can use both together: `.unique().index()` creates a unique index for both integrity and performance
+
+**Examples:**
+
+```javascript
+// Email must be unique (no performance index)
+email(db) {
+    db.string().notNullable().unique();
+}
+
+// Username indexed for fast lookups (allows duplicates)
+username(db) {
+    db.string().notNullable().index();
+}
+
+// Email with both unique constraint AND performance index
+email(db) {
+    db.string().notNullable().unique().index();
+}
+```
+
+### Automatic Index Migration
+
+When you add `.index()` to a field, MasterRecord automatically generates migration code:
+
+```javascript
+// In your entity
+class User {
+    email(db) {
+        db.string().notNullable().index();
+    }
+}
+
+// Generated migration (automatic)
+class Migration_20250101 extends masterrecord.schema {
+    async up(table) {
+        this.init(table);
+        this.createIndex({
+            tableName: 'User',
+            columnName: 'email',
+            indexName: 'idx_user_email'
+        });
+    }
+
+    async down(table) {
+        this.init(table);
+        this.dropIndex({
+            tableName: 'User',
+            columnName: 'email',
+            indexName: 'idx_user_email'
+        });
+    }
+}
+```
+
+**Rollback support:**
+
+Migrations automatically include rollback logic. Running `masterrecord migrate down` will drop all indexes created by that migration.
+
+---
+
+## Composite Indexes
+
+Create multi-column indexes for queries that filter or sort on multiple columns together.
+
+### API - Two Ways to Define
+
+**Option A: Entity Class (Recommended for core indexes)**
+
+```javascript
+class CreditLedger {
+    id(db) {
+        db.integer().primary().auto();
+    }
+
+    organization_id(db) {
+        db.integer().notNullable();
+    }
+
+    created_at(db) {
+        db.timestamp().default('CURRENT_TIMESTAMP');
+    }
+
+    resource_type(db) {
+        db.string().notNullable();
+    }
+
+    resource_id(db) {
+        db.integer().notNullable();
+    }
+
+    // Define composite indexes in entity
+    static compositeIndexes = [
+        // Simple array - auto-generates name
+        ['organization_id', 'created_at'],
+        ['resource_type', 'resource_id'],
+
+        // With custom name
+        {
+            columns: ['status', 'created_at'],
+            name: 'idx_status_timeline'
+        },
+
+        // Unique composite index
+        {
+            columns: ['email', 'tenant_id'],
+            unique: true
+        }
+    ];
+}
+```
+
+**Option C: Context-Level (For environment-specific or centralized schema)**
+
+```javascript
+class AppContext extends context {
+    onConfig() {
+        this.dbset(CreditLedger);
+
+        // Define composite indexes in context
+        this.compositeIndex(CreditLedger, ['organization_id', 'created_at']);
+        this.compositeIndex(CreditLedger, ['resource_type', 'resource_id']);
+        this.compositeIndex(CreditLedger, ['status', 'created_at'], {
+            name: 'idx_status_timeline'
+        });
+        this.compositeIndex(CreditLedger, ['email', 'tenant_id'], {
+            unique: true
+        });
+
+        // Can also use table name as string
+        this.compositeIndex('CreditLedger', ['user_id', 'created_at']);
+    }
+}
+```
+
+**Combined Usage (Best of Both)**
+
+```javascript
+class User {
+    email(db) { db.string(); }
+    tenant_id(db) { db.integer(); }
+    last_name(db) { db.string(); }
+    first_name(db) { db.string(); }
+
+    // Core indexes in entity
+    static compositeIndexes = [
+        ['last_name', 'first_name']
+    ];
+}
+
+class AppContext extends context {
+    onConfig() {
+        this.dbset(User);
+
+        // Add tenant-specific index for multi-tenant deployments
+        if (process.env.MULTI_TENANT === 'true') {
+            this.compositeIndex(User, ['tenant_id', 'email'], { unique: true });
+        }
+
+        // Add performance index for production
+        if (process.env.NODE_ENV === 'production') {
+            this.compositeIndex(User, ['tenant_id', 'last_name']);
+        }
+    }
+}
+```
+
+### When to Use Composite Indexes
+
+Composite indexes are most effective for queries that:
+1. **Filter on multiple columns**: `WHERE org_id = ? AND status = ?`
+2. **Filter and sort**: `WHERE status = ? ORDER BY created_at`
+3. **Enforce uniqueness**: Unique constraint on multiple columns together
+
+**Example queries that benefit:**
+
+```javascript
+// Benefits from composite index (organization_id, created_at)
+const ledger = await db.CreditLedger
+    .where(c => c.organization_id == $$, orgId)
+    .orderBy(c => c.created_at)
+    .toList();
+
+// Benefits from composite index (resource_type, resource_id)
+const entry = await db.CreditLedger
+    .where(c => c.resource_type == $$ && c.resource_id == $$, 'Order', 123)
+    .single();
+```
+
+### Column Order Matters
+
+The order of columns in a composite index affects query performance:
+
+```javascript
+static compositeIndexes = [
+    // Index: (status, created_at)
+    ['status', 'created_at']
+];
+
+// ✅ FAST: Uses index efficiently
+// WHERE status = ? ORDER BY created_at
+await db.Orders
+    .where(o => o.status == $$, 'pending')
+    .orderBy(o => o.created_at)
+    .toList();
+
+// ⚠️ SLOWER: Can only use first column
+// WHERE created_at > ?
+await db.Orders
+    .where(o => o.created_at > $$, yesterday)
+    .toList();
+```
+
+**Rule of thumb:** Put the most selective (filtered) columns first, then sort columns.
+
+### Automatic Migration Generation
+
+```javascript
+// Your entity definition triggers migration
+class CreditLedger {
+    organization_id(db) { db.integer(); }
+    created_at(db) { db.timestamp(); }
+
+    static compositeIndexes = [
+        ['organization_id', 'created_at']
+    ];
+}
+
+// Generated migration (automatic)
+class Migration_20250101 extends masterrecord.schema {
+    async up(table) {
+        this.init(table);
+        this.createCompositeIndex({
+            tableName: 'CreditLedger',
+            columns: ['organization_id', 'created_at'],
+            indexName: 'idx_creditleger_organization_id_created_at',
+            unique: false
+        });
+    }
+
+    async down(table) {
+        this.init(table);
+        this.dropCompositeIndex({
+            tableName: 'CreditLedger',
+            columns: ['organization_id', 'created_at'],
+            indexName: 'idx_creditleger_organization_id_created_at',
+            unique: false
+        });
+    }
+}
+```
+
+### Single vs Composite Indexes
+
+```javascript
+class User {
+    email(db) {
+        db.string().index();  // Single-column index
+    }
+
+    first_name(db) {
+        db.string();  // Part of composite below
+    }
+
+    last_name(db) {
+        db.string();  // Part of composite below
+    }
+
+    static compositeIndexes = [
+        // Composite index for name lookups
+        ['last_name', 'first_name']
+    ];
+}
+```
+
+**When to use single vs composite:**
+- **Single index**: Column queried independently (`WHERE email = ?`)
+- **Composite index**: Columns queried together (`WHERE last_name = ? AND first_name = ?`)
+
+---
+
 ## Business Logic Validation
 
 Add validators to your entity definitions for automatic validation on property assignment.
@@ -2301,20 +2631,41 @@ await db.saveChanges();  // Batch insert
 
 ### 3. Use Indexes
 
+**Single-column indexes:**
+
 ```javascript
 class User {
-    constructor() {
-        this.email = {
-            type: 'string',
-            unique: true  // Automatically creates index
-        };
+    email(db) {
+        db.string().index();  // Single column
     }
 }
+```
+
+**Composite indexes for multi-column queries:**
 
-// For complex queries, add database indexes manually
-// CREATE INDEX idx_user_status ON User(status);
+```javascript
+class Order {
+    user_id(db) { db.integer(); }
+    status(db) { db.string(); }
+    created_at(db) { db.timestamp(); }
+
+    static compositeIndexes = [
+        // For: WHERE user_id = ? AND status = ?
+        ['user_id', 'status'],
+
+        // For: WHERE status = ? ORDER BY created_at
+        ['status', 'created_at']
+    ];
+}
 ```
 
+**Best practices:**
+- Index foreign keys for join performance
+- Use composite indexes for queries with multiple WHERE conditions
+- Column order matters: most selective (filtered) columns first
+- Don't over-index - each index adds write overhead
+- Primary keys are automatically indexed
+
 ### 4. Limit Result Sets
 
 ```javascript