masterrecord 0.3.37 → 0.3.39

package/context.js

@@ -177,6 +177,11 @@ class context {
     // Sequential ID counter for collision-safe entity tracking
     static _nextEntityId = 1;
 
+    // Global model registry - tracks registered models per context class
+    // Structure: { 'userContext': Set(['User', 'Auth', 'Settings']), 'qaContext': Set([...]) }
+    // Purpose: Prevents duplicate warnings when CLI instantiates same context multiple times
+    static _globalModelRegistry = {};
+
     /**
      * Creates a new database context instance
      *
@@ -189,6 +194,17 @@ class context {
         this._SQLEngine = null;  // Will be set during database initialization
         this.__trackedEntitiesMap = new Map();  // Initialize Map for O(1) lookups
 
+        // Track if this is the first instance of this context class
+        // Used to determine if duplicate warnings should be shown
+        const globalRegistry = context._globalModelRegistry[this.__name];
+        this.__isFirstInstance = !globalRegistry || globalRegistry.size === 0;
+
+        // Initialize global model registry for this context class if not exists
+        // This prevents duplicate warnings when CLI instantiates the same context multiple times
+        if (!context._globalModelRegistry[this.__name]) {
+            context._globalModelRegistry[this.__name] = new Set();
+        }
+
         // Initialize shared query cache (only once across all instances)
         if (!context._sharedQueryCache) {
             const cacheConfig = {
@@ -1033,20 +1049,29 @@ class context {
         // Merge context-level composite indexes with entity-defined indexes
         this.#mergeCompositeIndexes(validModel, tableName);
 
-        // Check if this entity (by table name) is already registered
+        // Check if model is registered in this specific instance
         const existingIndex = this.__entities.findIndex(e => e.__name === tableName);
+
         if (existingIndex !== -1) {
-            // Entity already exists - update it instead of adding duplicate
-            console.warn(`Warning: dbset() called multiple times for table '${tableName}' - updating existing registration`);
+            // Model already registered in THIS instance - this is a duplicate within same constructor
+            // Only warn on the first instance of this context class (subsequent instances expected to have same pattern)
+            if (this.__isFirstInstance) {
+                console.warn(`Warning: dbset() called multiple times for table '${tableName}' in constructor - updating existing registration`);
+            }
+            // Update existing registration
             this.__entities[existingIndex] = validModel;
             this.__builderEntities[existingIndex] = tools.createNewInstance(validModel, query, this);
         } else {
-            // New entity - add to arrays
+            // Model not registered in this instance - add it
             this.__entities.push(validModel);  // Store model object
             const buildMod = tools.createNewInstance(validModel, query, this);
             this.__builderEntities.push(buildMod);  // Store query builder entity
         }
 
+        // Always mark model as globally seen (after handling instance registration)
+        const globalRegistry = context._globalModelRegistry[this.__name];
+        globalRegistry.add(tableName);
+
         // Use getter to return fresh query instance each time (prevents parameter accumulation)
         Object.defineProperty(this, validModel.__name, {
             get: function() {

package/mySQLEngine.js

@@ -653,6 +653,14 @@ class MySQLEngine {
             if (column.indexOf("__") === -1) {
                 let fieldColumn = fields[column];
 
+                // 🔥 FIX: For belongsTo relationships, also check the foreignKey field name
+                // Users can set either orgRole.User = obj OR orgRole.user_id = 2
+                if ((fieldColumn === undefined || fieldColumn === null) &&
+                    modelEntity[column].relationshipType === "belongsTo" &&
+                    modelEntity[column].foreignKey) {
+                    fieldColumn = fields[modelEntity[column].foreignKey];
+                }
+
                 if ((fieldColumn !== undefined && fieldColumn !== null) && typeof(fieldColumn) !== "object") {
                     try {
                         fieldColumn = FieldTransformer.toDatabase(fieldColumn, modelEntity[column], modelEntity.__name, column);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "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/postgresEngine.js

@@ -600,6 +600,14 @@ class postgresEngine {
             if (column.indexOf("__") === -1) {
                 let fieldColumn = fields[column];
 
+                // 🔥 FIX: For belongsTo relationships, also check the foreignKey field name
+                // Users can set either orgRole.User = obj OR orgRole.user_id = 2
+                if ((fieldColumn === undefined || fieldColumn === null) &&
+                    modelEntity[column].relationshipType === "belongsTo" &&
+                    modelEntity[column].foreignKey) {
+                    fieldColumn = fields[modelEntity[column].foreignKey];
+                }
+
                 if ((fieldColumn !== undefined && fieldColumn !== null) && typeof(fieldColumn) !== "object") {
                     // Apply toDatabase transformer
                     try {

package/readme.md

@@ -3369,6 +3369,188 @@ user.name = null;  // Error if name is { nullable: false }
 
 ## Changelog
 
+### Version 0.3.39 (2026-02-09) - CRITICAL BUG FIX: Foreign Key String Values
+
+#### Bug Fixed: Foreign Key Fields Silently Ignoring String Values
+- **FIXED**: Critical bug where string values assigned to foreign key fields were silently excluded from INSERT statements
+  - **Problem**: When you assign `orgRole.user_id = "2"` (string), MasterRecord excluded it from INSERT, causing NOT NULL constraint failures
+  - **Root Cause**: INSERT builder only checked navigation property name (`User`), not foreign key field name (`user_id`)
+  - **Impact**: Common in real-world apps where IDs come from JWT tokens, HTTP requests, or authService (returns string IDs)
+
+#### What Was Happening (Before v0.3.39)
+```javascript
+// User assigns string value to foreign key
+orgRole.user_id = "2";  // ← STRING (from currentUser.id)
+orgRole.organization_id = 8;  // ← NUMBER (from database)
+orgRole.role = 'org_admin';
+
+await userContext.saveChanges();
+// ❌ Generated SQL: INSERT INTO [UserOrganizationRole] ([role]) VALUES ('org_admin')
+// ❌ Error: NOT NULL constraint failed: UserOrganizationRole.user_id
+```
+
+**Why It Failed:**
+- `belongsTo('User', 'user_id')` creates property `User` with `foreignKey: 'user_id'`
+- INSERT builder looked for `fields['User']` (navigation property)
+- User set `fields['user_id']` (foreign key field name)
+- Field not found → silently skipped → INSERT failed
+
+#### The Fix (v0.3.39)
+Updated `_buildSQLInsertObjectParameterized` in all database engines:
+- Now checks BOTH navigation property name AND foreign key field name
+- Auto-converts string values to integers for integer foreign key fields
+- Maintains backward compatibility (setting navigation property still works)
+
+```javascript
+// After fix - both patterns work:
+orgRole.User = 2;        // ✅ Works (navigation property)
+orgRole.user_id = "2";   // ✅ Works (foreign key field, auto-converted to integer)
+```
+
+#### Files Modified
+1. **SQLLiteEngine.js** (lines 1127-1137) - Added foreign key field lookup
+2. **mySQLEngine.js** (lines 654-664) - Added foreign key field lookup
+3. **postgresEngine.js** (lines 601-611) - Added foreign key field lookup
+4. **test/foreign-key-string-value-test.js** (NEW) - 8 comprehensive tests
+5. **package.json** - Updated to v0.3.39
+6. **readme.md** - Added changelog
+
+#### Test Results
+- **8 new tests** - All passing ✅
+  1. String foreign key value included in INSERT ✅
+  2. Number foreign key value still works ✅
+  3. Mixed string and number foreign keys ✅
+  4. String with leading zeros (e.g., "007" → 7) ✅
+  5. Invalid strings throw error (not silent failure) ✅
+  6. Empty strings throw error ✅
+  7. Backward compatible (navigation property still works) ✅
+  8. Prefers navigation property if both set ✅
+
+#### Real-World Example: authService Returns String IDs
+```javascript
+// authService.js returns:
+const currentUser = {
+  id: "2",  // ← STRING (from String(obj.user.id))
+  email: "customer1@bookbag.ai",
+  system_role: "system_user"
+};
+
+// User creates association:
+const orgRole = new UserOrganizationRole();
+orgRole.user_id = currentUser.id;  // ← Before: silently skipped. After: auto-converted to 2
+orgRole.organization_id = newOrg.id;  // ← NUMBER from database
+orgRole.role = 'org_admin';
+
+await userContext.saveChanges();  // ✅ Now works!
+```
+
+#### Impact
+- ✅ **Auto-converts** string foreign keys to integers (with validation)
+- ✅ **Clear errors** for invalid strings (not silent failures)
+- ✅ **Backward compatible** - navigation property pattern still works
+- ✅ **Works across all databases** (SQLite, MySQL, PostgreSQL)
+- ✅ **Matches real-world usage** where IDs are often strings
+
+#### Upgrade Path
+```bash
+npm install -g masterrecord@0.3.39
+```
+No code changes needed - automatic fix! If you have workarounds like `parseInt(currentUser.id)`, you can now remove them (but leaving them is harmless).
+
+---
+
+### Version 0.3.38 (2026-02-06) - GLOBAL MODEL REGISTRY (UX FIX)
+
+#### Enhancement: Eliminates Confusing CLI Warnings
+- **FIXED**: Confusing warnings during normal CLI operation when generating migrations
+  - **Previous Behavior**: v0.3.36/0.3.37 correctly detected duplicate `dbset()` calls and emitted warnings
+  - **Problem**: CLI instantiates the same context class multiple times to inspect schema
+  - **Impact**: Users saw warnings during normal operation: `"Warning: dbset() called multiple times for table 'User'..."`
+  - **User Confusion**: Warnings appeared even when code was correct, making users think they did something wrong
+
+#### Implementation - Global Model Registry
+**The Solution** (`context.js`)
+- Added static `_globalModelRegistry` property to track registered models per context class
+  - Structure: `{ 'userContext': Set(['User', 'Auth', 'Settings']), 'qaContext': Set([...]) }`
+- Each context instance checks if it's the first instance via `__isFirstInstance` flag
+- Warnings only appear on the first instance of a context class (genuine bugs)
+- Subsequent instances (CLI pattern) are silent since they're expected
+
+**How It Works:**
+
+1. **First Instance** (constructor execution):
+   ```javascript
+   const ctx1 = new userContext();
+   // __isFirstInstance = true (global registry empty)
+   // dbset(User) - adds User to global registry
+   // dbset(User) again - WARNS (duplicate in same constructor)
+   // dbset(Auth) - adds Auth to global registry
+   ```
+
+2. **Subsequent Instances** (CLI creates multiple):
+   ```javascript
+   const ctx2 = new userContext();
+   // __isFirstInstance = false (global registry has User, Auth)
+   // dbset(User) - no warning (expected pattern)
+   // dbset(User) again - no warning (expected pattern)
+   // dbset(Auth) - no warning (expected pattern)
+   ```
+
+3. **Duplicate Detection Still Works**:
+   - If user's constructor has `dbset(User)` called twice, the first instance warns
+   - This guides users to fix their code (remove the duplicate)
+   - After fixing, all future CLI operations are silent
+
+**Benefits:**
+- ✅ **Clean CLI Output**: No spurious warnings during `masterrecord add-migration`
+- ✅ **Genuine Bug Detection**: Still warns about actual duplicates in user code
+- ✅ **Better UX**: Users no longer confused by normal operation warnings
+- ✅ **Backward Compatible**: Existing code continues to work
+- ✅ **Industry-Standard Pattern**: Matches how TypeORM, Sequelize, Mongoose handle multiple instances
+
+**Files Modified:**
+1. `context.js` - Added `_globalModelRegistry` static property, `__isFirstInstance` instance flag, updated `dbset()` logic
+2. `test/global-model-registry-test.js` (NEW) - 15 comprehensive tests covering:
+   - Multiple context instances (CLI pattern) - no warnings ✅
+   - Genuine duplicates in constructor - warns once ✅
+   - Multiple context classes with same models - no warnings ✅
+   - Registry isolation between context classes ✅
+   - Edge cases (empty contexts, large contexts, mixed registration) ✅
+3. `package.json` - Updated version to 0.3.38
+4. `readme.md` - Added changelog entry
+
+**Test Results:**
+- **15 new tests** - All passing ✅
+- Tests verify CLI pattern (3 instances) produces zero warnings
+- Tests verify genuine duplicates still warn on first instance only
+- Tests verify different context classes have separate registries
+- Tests verify large contexts (50 models) work without warnings
+
+**Upgrade Path:**
+```bash
+npm install -g masterrecord@0.3.38
+```
+No code changes needed - automatic improvement to CLI experience.
+
+**Real-World Example:**
+
+Before v0.3.38:
+```bash
+$ masterrecord add-migration CreateUsers userContext
+Warning: dbset() called multiple times for table 'User' - updating existing registration
+Warning: dbset() called multiple times for table 'Auth' - updating existing registration
+Warning: dbset() called multiple times for table 'Settings' - updating existing registration
+✓ Migration 'CreateUsers' created successfully
+```
+
+After v0.3.38:
+```bash
+$ masterrecord add-migration CreateUsers userContext
+✓ Migration 'CreateUsers' created successfully
+```
+
+---
+
 ### Version 0.3.36 (2026-02-06) - ROOT CAUSE FIX + CONFIG DISCOVERY FIX
 
 #### Critical Bug Fix #1: Duplicate Entities and Seed Data - Complete Resolution