masterrecord 0.3.30 → 0.3.31

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

@@ -246,6 +246,16 @@ class migrationMySQLQuery {
         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

@@ -233,6 +233,16 @@ class migrationPostgresQuery {
         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

@@ -201,6 +201,16 @@ class migrationSQLiteQuery {
         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

@@ -120,6 +120,38 @@ module.exports = ${this.name};
         }
     }
 
+    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

@@ -26,7 +26,9 @@ class Migrations{
                         deletedColumns : [],
                         updatedColumns : [],
                         newIndexes : [],
-                        deletedIndexes : []
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : []
                     }
                     tables.push(table);
                 });
@@ -42,9 +44,11 @@ class Migrations{
                         deletedColumns : [],
                         updatedColumns : [],
                         newIndexes : [],
-                        deletedIndexes : []
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : []
                     }
-                    
+
                     oldSchema.forEach(function (oldItem, index) {
                         var oldItemName = oldItem["__name"];
                         if(table.name === oldItemName){
@@ -52,7 +56,7 @@ class Migrations{
                             tables.push(table);
                         }
                     });
-    
+
                 });
             }
 
@@ -167,6 +171,8 @@ class Migrations{
         tables = this.#findUpdatedColumns(tables);
         tables = this.#findNewIndexes(tables);
         tables = this.#findDeletedIndexes(tables);
+        tables = this.#findNewCompositeIndexes(tables);
+        tables = this.#findDeletedCompositeIndexes(tables);
         return tables;
     }
 
@@ -258,6 +264,67 @@ class Migrations{
         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;
+    }
+
 
 
     findContextFile(executedLocation, contextFileName){
@@ -398,6 +465,8 @@ class Migrations{
                (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;
             }
@@ -452,6 +521,14 @@ class Migrations{
                 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

@@ -126,6 +126,19 @@ class schema{
                         });
                     }
                 });
+
+                // 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");
@@ -460,6 +473,56 @@ class schema{
         }
     }
 
+    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.30",
+  "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

@@ -1900,6 +1900,226 @@ Migrations automatically include rollback logic. Running `masterrecord migrate d
 
 ---
 
+## 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.
@@ -2411,59 +2631,40 @@ await db.saveChanges();  // Batch insert
 
 ### 3. Use Indexes
 
-Define indexes directly in your entity using `.index()`:
+**Single-column indexes:**
 
 ```javascript
 class User {
-    id(db) {
-        db.integer().primary().auto();  // Primary keys are automatically indexed
-    }
-
     email(db) {
-        db.string()
-          .notNullable()
-          .unique()
-          .index();  // Creates: idx_user_email
-    }
-
-    last_name(db) {
-        db.string().index();  // Creates: idx_user_last_name
-    }
-
-    status(db) {
-        db.string().index('idx_user_status');  // Custom index name
+        db.string().index();  // Single column
     }
 }
 ```
 
-**Migration automatically generates:**
+**Composite indexes for multi-column queries:**
 
 ```javascript
-// In migration file (generated automatically)
-this.createIndex({
-    tableName: 'User',
-    columnName: 'email',
-    indexName: 'idx_user_email'
-});
-```
+class Order {
+    user_id(db) { db.integer(); }
+    status(db) { db.string(); }
+    created_at(db) { db.timestamp(); }
 
-**Rollback support:**
+    static compositeIndexes = [
+        // For: WHERE user_id = ? AND status = ?
+        ['user_id', 'status'],
 
-```javascript
-// Down migration automatically includes
-this.dropIndex({
-    tableName: 'User',
-    columnName: 'email',
-    indexName: 'idx_user_email'
-});
+        // For: WHERE status = ? ORDER BY created_at
+        ['status', 'created_at']
+    ];
+}
 ```
 
 **Best practices:**
-- Index columns used in WHERE clauses
-- Index foreign key columns for join performance
+- 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 (no need for `.index()`)
-- Use `.unique()` for data integrity, `.index()` for query performance
+- Primary keys are automatically indexed
 
 ### 4. Limit Result Sets