masterrecord 0.3.30 → 0.3.32

package/Migrations/migrations.js

@@ -26,7 +26,10 @@ class Migrations{
                         deletedColumns : [],
                         updatedColumns : [],
                         newIndexes : [],
-                        deletedIndexes : []
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : [],
+                        newSeedData : []
                     }
                     tables.push(table);
                 });
@@ -42,9 +45,12 @@ class Migrations{
                         deletedColumns : [],
                         updatedColumns : [],
                         newIndexes : [],
-                        deletedIndexes : []
+                        deletedIndexes : [],
+                        newCompositeIndexes : [],
+                        deletedCompositeIndexes : [],
+                        newSeedData : []
                     }
-                    
+
                     oldSchema.forEach(function (oldItem, index) {
                         var oldItemName = oldItem["__name"];
                         if(table.name === oldItemName){
@@ -52,7 +58,7 @@ class Migrations{
                             tables.push(table);
                         }
                     });
-    
+
                 });
             }
 
@@ -157,7 +163,7 @@ class Migrations{
     }
 
     // build table to build new migration snapshot
-    #buildMigrationObject(oldSchema, newSchema){
+    #buildMigrationObject(oldSchema, newSchema, newSeedData = {}){
 
         var tables = this.#organizeSchemaByTables(oldSchema, newSchema);
 
@@ -167,6 +173,9 @@ class Migrations{
         tables = this.#findUpdatedColumns(tables);
         tables = this.#findNewIndexes(tables);
         tables = this.#findDeletedIndexes(tables);
+        tables = this.#findNewCompositeIndexes(tables);
+        tables = this.#findDeletedCompositeIndexes(tables);
+        tables = this.#findNewSeedData(tables, newSeedData);
         return tables;
     }
 
@@ -258,6 +267,78 @@ 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;
+    }
+
+    #findNewSeedData(tables, newSeedData) {
+        // newSeedData is from schema snapshot: { tableName: [records] }
+        tables.forEach(function(item) {
+            const tableSeedData = newSeedData[item.name];
+            if (tableSeedData && tableSeedData.length > 0) {
+                item.newSeedData = tableSeedData;
+            }
+        });
+        return tables;
+    }
+
 
 
     findContextFile(executedLocation, contextFileName){
@@ -330,11 +411,18 @@ class Migrations{
         const relMigrationFolder = '.'; // the snapshot sits inside migrationsDirectory
         const relSnapshotLocation = path.basename(snapshotPath);
 
+        // Order seed data by dependencies if context instance is available
+        const orderedSeedData = snap.context && snap.context.getOrderedSeedData
+            ? snap.context.getOrderedSeedData()
+            : snap.contextSeedData || {};
+
         const content = {
             contextLocation: relContextLocation,
             migrationFolder: relMigrationFolder,
             snapShotLocation: relSnapshotLocation,
-            schema : snap.contextEntities
+            schema : snap.contextEntities,
+            seedData: orderedSeedData,
+            seedConfig: snap.contextSeedConfig || {}
         };
 
         const jsonContent = JSON.stringify(content, null, 2);
@@ -388,8 +476,8 @@ class Migrations{
     }
 
     // Returns true if there are any changes between old and new schema
-    hasChanges(oldSchema, newSchema){
-        const tables = this.#buildMigrationObject(oldSchema, newSchema);
+    hasChanges(oldSchema, newSchema, newSeedData = {}){
+        const tables = this.#buildMigrationObject(oldSchema, newSchema, newSeedData);
         for(const t of tables){
             if(!t) continue;
             if((t.newTables && t.newTables.length) ||
@@ -398,6 +486,9 @@ 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.newSeedData && t.newSeedData.length) ||
                (t.old === null) || (t.new === null)){
                 return true;
             }
@@ -405,16 +496,20 @@ class Migrations{
         return false;
     }
 
-    template(name, oldSchema, newSchema){
+    template(name, oldSchema, newSchema, newSeedData = {}, seedConfig = {}, currentEnv = null){
         var MT = new MigrationTemplate(name);
-        var tables = this.#buildMigrationObject(oldSchema, newSchema);
-    
+        // Determine current environment if not provided
+        if (!currentEnv) {
+            currentEnv = process.env.NODE_ENV || process.env.master || 'development';
+        }
+        var tables = this.#buildMigrationObject(oldSchema, newSchema, newSeedData);
+
         tables.forEach(function (item, index) {
             if(item.old === null){
                 MT.createTable("up", column, item.name);
                 MT.dropTable("down", column, item.name);
             }
-            
+
             if(item.new === null){
                 MT.dropTable("up", column, item.name);
                 MT.createTable("down", column, item.name);
@@ -452,6 +547,20 @@ 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);
+            });
+
+            // Generate seed data code
+            if (item.newSeedData && item.newSeedData.length > 0) {
+                MT.seedData("up", item.name, item.newSeedData, currentEnv);
+                MT.seedDataDown("down", item.name, item.newSeedData, seedConfig);
+            }
+
         });
 
        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

@@ -150,6 +150,16 @@ class context {
     __trackedEntities = [];
     __trackedEntitiesMap = new Map();  // Performance: O(1) entity lookup instead of O(n) linear search
     __relationshipModels = [];
+    __contextSeedData = {};  // Store seed data by table name
+    __contextSeedConfig = {  // Seed data configuration
+        generateDownMigrations: false,
+        downStrategy: 'delete',
+        deleteByPrimaryKey: true,
+        onRollbackError: 'warn',
+        detectCircularDependencies: true,
+        circularStrategy: 'warn',
+        defaultStrategy: 'insert'  // 'insert' | 'upsert'
+    };
 
     // Configuration
     __environment = '';
@@ -711,6 +721,32 @@ class context {
         }
     }
 
+    /**
+     * Configure seed data behavior for migrations
+     *
+     * @param {object} config - Seed configuration options
+     * @param {boolean} [config.generateDownMigrations=false] - Generate rollback logic for seed data
+     * @param {string} [config.downStrategy='delete'] - Strategy for down migrations ('delete' | 'skip')
+     * @param {boolean} [config.deleteByPrimaryKey=true] - Use primary key for deletion in down migrations
+     * @param {string} [config.onRollbackError='warn'] - How to handle rollback errors ('warn' | 'throw' | 'ignore')
+     * @returns {this} Context instance for chaining
+     *
+     * @example
+     * context.seedConfig({
+     *     generateDownMigrations: true,
+     *     downStrategy: 'delete'
+     * });
+     */
+    seedConfig(config) {
+        if (config && typeof config === 'object') {
+            this.__contextSeedConfig = {
+                ...this.__contextSeedConfig,
+                ...config
+            };
+        }
+        return this;
+    }
+
     /**
      * Initialize SQLite database connection using environment file
      *
@@ -925,11 +961,13 @@ class context {
      *
      * @param {Function|object} model - Entity class or model definition
      * @param {string} [name] - Optional custom table name (defaults to model.name)
+     * @returns {object} Chainable object with seed() method
      * @throws {EntityValidationError} If model is invalid or table name contains SQL injection
      *
      * @example
      * context.dbset(User);
      * context.dbset(Post, 'blog_posts');
+     * context.dbset(User).seed({ name: 'Admin', email: 'admin@example.com' });
      */
     dbset(model, name) {
         // Input validation
@@ -980,6 +1018,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
@@ -992,6 +1034,252 @@ class context {
             configurable: true,
             enumerable: true
         });
+
+        // Return chainable object with seed() method
+        return {
+            seed: (data) => this.#addSeedData(tableName, data)
+        };
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * Add seed data for a table
+     * @private
+     * @param {string} tableName - Table name
+     * @param {object|Array<object>} data - Seed data (single object or array)
+     * @returns {object} Chainable object with seed() method
+     */
+    #addSeedData(tableName, data) {
+        // Initialize seed data storage if not exists
+        if (!this.__contextSeedData) {
+            this.__contextSeedData = {};
+        }
+        if (!this.__contextSeedData[tableName]) {
+            this.__contextSeedData[tableName] = [];
+        }
+
+        // Handle both single object and array of objects
+        const records = Array.isArray(data) ? data : [data];
+
+        // Attach rollback metadata if down migrations are enabled
+        if (this.__contextSeedConfig.generateDownMigrations) {
+            // Find primary key for this table
+            const entity = this.__entities.find(e => e.__name === tableName);
+            let primaryKey = 'id'; // Default
+            if (entity) {
+                for (const key in entity) {
+                    if (entity[key] && entity[key].primary) {
+                        primaryKey = key;
+                        break;
+                    }
+                }
+            }
+
+            records.forEach(record => {
+                if (record[primaryKey] !== undefined) {
+                    record.__rollback = {
+                        strategy: this.__contextSeedConfig.downStrategy,
+                        key: primaryKey,
+                        value: record[primaryKey]
+                    };
+                }
+            });
+        }
+
+        // Apply default upsert strategy if configured
+        if (this.__contextSeedConfig.defaultStrategy === 'upsert') {
+            records.forEach(record => {
+                if (!record.__seedStrategy) {
+                    record.__seedStrategy = {
+                        type: 'upsert',
+                        conflictKey: 'primaryKey',
+                        updateFields: null
+                    };
+                }
+            });
+        }
+
+        this.__contextSeedData[tableName].push(...records);
+
+        // Return chainable object with seed(), when(), seedFactory(), and upsert() methods
+        const chainable = {
+            seed: (moreData) => this.#addSeedData(tableName, moreData),
+            seedFactory: (count, generator) => this.#seedFactory(tableName, count, generator),
+            when: (...envs) => {
+                // Mark last batch of records with environment condition
+                const lastBatch = this.__contextSeedData[tableName].slice(-records.length);
+                lastBatch.forEach(r => {
+                    r.__seedEnv = {
+                        conditions: envs,
+                        strategy: 'generation-time'
+                    };
+                });
+                return chainable; // Return self for further chaining
+            },
+            upsert: (options = {}) => {
+                // Mark last batch of records with upsert strategy
+                const lastBatch = this.__contextSeedData[tableName].slice(-records.length);
+                lastBatch.forEach(r => {
+                    r.__seedStrategy = {
+                        type: 'upsert',
+                        conflictKey: options.conflictKey || 'primaryKey',
+                        updateFields: options.updateFields || null
+                    };
+                });
+                return chainable; // Return self for further chaining
+            }
+        };
+
+        return chainable;
+    }
+
+    /**
+     * Add factory-generated seed data for a table
+     * @private
+     * @param {string} tableName - Table name
+     * @param {number} count - Number of records to generate
+     * @param {Function} generator - Function that takes index and returns record object
+     * @returns {object} Chainable object
+     */
+    #seedFactory(tableName, count, generator) {
+        if (typeof generator !== 'function') {
+            throw new Error('seedFactory requires a generator function as the second parameter');
+        }
+
+        if (typeof count !== 'number' || count < 1) {
+            throw new Error('seedFactory requires a positive number as the first parameter');
+        }
+
+        // Generate records using the generator function
+        const records = Array.from({ length: count }, (_, i) => {
+            const record = generator(i);
+            if (!record || typeof record !== 'object') {
+                throw new Error(`Generator function must return an object (returned ${typeof record} for index ${i})`);
+            }
+
+            // Mark as factory-generated
+            record.__seedMeta = {
+                generated: true,
+                index: i,
+                generatedAt: Date.now()
+            };
+
+            return record;
+        });
+
+        // Add generated records using the existing #addSeedData method
+        return this.#addSeedData(tableName, records);
+    }
+
+    /**
+     * Get seed data ordered by dependency relationships
+     * Uses topological sort to ensure foreign key constraints are satisfied
+     * @returns {Object} Ordered seed data by table name
+     */
+    getOrderedSeedData() {
+        if (!this.__contextSeedData || Object.keys(this.__contextSeedData).length === 0) {
+            return {};
+        }
+
+        const DependencyGraph = require('./Migrations/dependencyGraph');
+        const graph = new DependencyGraph(this.__entities);
+        graph.buildFromEntities();
+
+        try {
+            const orderedTables = graph.filterToSeededTables(this.__contextSeedData);
+            const orderedSeedData = {};
+            orderedTables.forEach(table => {
+                orderedSeedData[table] = this.__contextSeedData[table];
+            });
+            return orderedSeedData;
+        } catch (error) {
+            // Handle circular dependency based on strategy
+            if (this.__contextSeedConfig.circularStrategy === 'throw') {
+                throw error;
+            } else if (this.__contextSeedConfig.circularStrategy === 'warn') {
+                console.warn(`[MasterRecord] ${error.message}, using insertion order instead`);
+            }
+            // Fall back to original insertion order
+            return this.__contextSeedData;
+        }
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.30",
+  "version": "0.3.32",
   "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": {