masterrecord 0.3.15 → 0.3.17

package/.claude/settings.local.json

@@ -32,7 +32,10 @@
       "Bash(grep:*)",
       "Bash(npm audit:*)",
       "Bash(npm test:*)",
-      "Bash(done)"
+      "Bash(done)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "Bash(master=development masterrecord update-database qaContext)"
     ],
     "deny": [],
     "ask": []

package/Migrations/schema.js

@@ -295,32 +295,33 @@ class schema{
     }
 
     // EnsureCreated equivalent for MySQL: create DB if missing
-    createDatabase(){
+    async createDatabase(){
         try{
             if(!(this.context && this.context.isMySQL)){ return; }
-            const MySQLClient = require('masterrecord/mySQLSyncConnect');
+            const MySQLAsyncClient = require('masterrecord/mySQLAsyncConnect');
             const client = this.context.db; // main client (may not be connected yet)
             if(!client || !client.config || !client.config.database){ return; }
             const dbName = client.config.database;
             // Build server-level connection (no database)
             const baseConfig = { ...client.config };
             delete baseConfig.database;
-            const admin = new MySQLClient(baseConfig);
-            admin.connect();
-            if(!admin.connection){ return; }
+            const admin = new MySQLAsyncClient(baseConfig);
+            await admin.connect();
+            const pool = admin.getPool();
+            if(!pool){ return; }
 
             // Use parameterized query for checking database existence
-            const check = admin.query(`SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = ?`, [dbName]);
-            const exists = Array.isArray(check) ? check.length > 0 : !!check?.length;
+            const [rows] = await pool.execute(`SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = ?`, [dbName]);
+            const exists = Array.isArray(rows) && rows.length > 0;
             if(!exists){
                 // Validate database name (alphanumeric, underscore, hyphen only)
                 if(!/^[a-zA-Z0-9_-]+$/.test(dbName)){
                     throw new Error(`Invalid database name: ${dbName}. Only alphanumeric characters, underscores, and hyphens are allowed.`);
                 }
                 // CREATE DATABASE doesn't support placeholders, but we've validated the name
-                admin.query(`CREATE DATABASE \`${dbName}\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+                await pool.execute(`CREATE DATABASE \`${dbName}\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
             }
-            admin.close();
+            await admin.close();
             this._dbEnsured = true;
         }catch(err){
             // Non-fatal: migrations may still proceed if DB already exists or permissions blocked

package/SQLLiteEngine.js

@@ -6,7 +6,7 @@ class SQLLiteEngine {
 
     unsupportedWords = ["order"]
 
-    update(query){
+    async update(query){
         // Security: ONLY use parameterized queries - no fallback to string concatenation
         // query.arg must contain {sql, params} from _buildSQLEqualToParameterized
         if(!query.arg || typeof query.arg !== 'object' || !query.arg.sql || !query.arg.params){
@@ -18,17 +18,17 @@ class SQLLiteEngine {
         WHERE [${query.tableName}].[${query.primaryKey}] = ?`;
         // Add primaryKeyValue to params array
         var params = [...query.arg.params, query.primaryKeyValue];
-        return this._runWithParams(sqlQuery, params);
+        return Promise.resolve(this._runWithParams(sqlQuery, params));
     }
 
-    delete(queryObject){
+    async delete(queryObject){
        var sqlObject = this._buildDeleteObject(queryObject);
        // Use parameterized query to prevent SQL injection
        var sqlQuery = `DELETE FROM [${sqlObject.tableName}] WHERE [${sqlObject.tableName}].[${sqlObject.primaryKey}] = ?`;
-       return this._executeWithParams(sqlQuery, [sqlObject.value]);
+       return Promise.resolve(this._executeWithParams(sqlQuery, [sqlObject.value]));
     }
 
-    insert(queryObject){
+    async insert(queryObject){
         // Use NEW SECURE parameterized version
         var sqlObject = this._buildSQLInsertObjectParameterized(queryObject, queryObject.__entity);
         if(sqlObject === -1){
@@ -40,28 +40,35 @@ class SQLLiteEngine {
         var open = {
             "id": queryObj.lastInsertRowid
         };
-        return open;
+        return Promise.resolve(open);
     }
 
     /**
      * Batch insert multiple entities in a single transaction
      * Performance: 100x faster than N separate inserts
      */
-    bulkInsert(entities) {
-        if (!entities || entities.length === 0) return [];
+    async bulkInsert(entities) {
+        if (!entities || entities.length === 0) return Promise.resolve([]);
 
         const results = [];
-        // SQLite: Use transaction for batch inserts
-        this.startTransaction();
+        // SQLite: Use transaction for batch inserts (only if not already in one)
+        const needsTransaction = !this.db.inTransaction;
+        if (needsTransaction) {
+            await this.startTransaction();
+        }
         try {
             for (const entity of entities) {
-                const result = this.insert(entity);
+                const result = await this.insert(entity);
                 results.push(result);
             }
-            this.endTransaction();
-            return results;
+            if (needsTransaction) {
+                await this.endTransaction();
+            }
+            return Promise.resolve(results);
         } catch (error) {
-            this.errorTransaction();
+            if (needsTransaction) {
+                await this.errorTransaction();
+            }
             throw error;
         }
     }
@@ -69,17 +76,25 @@ class SQLLiteEngine {
     /**
      * Batch update multiple entities
      */
-    bulkUpdate(updateQueries) {
-        if (!updateQueries || updateQueries.length === 0) return;
+    async bulkUpdate(updateQueries) {
+        if (!updateQueries || updateQueries.length === 0) return Promise.resolve();
 
-        this.startTransaction();
+        // Only start transaction if not already in one
+        const needsTransaction = !this.db.inTransaction;
+        if (needsTransaction) {
+            await this.startTransaction();
+        }
         try {
             for (const query of updateQueries) {
-                this.update(query);
+                await this.update(query);
+            }
+            if (needsTransaction) {
+                await this.endTransaction();
             }
-            this.endTransaction();
         } catch (error) {
-            this.errorTransaction();
+            if (needsTransaction) {
+                await this.errorTransaction();
+            }
             throw error;
         }
     }
@@ -87,15 +102,15 @@ class SQLLiteEngine {
     /**
      * Batch delete multiple entities using WHERE IN
      */
-    bulkDelete(tableName, ids) {
-        if (!ids || ids.length === 0) return;
+    async bulkDelete(tableName, ids) {
+        if (!ids || ids.length === 0) return Promise.resolve();
 
         const placeholders = ids.map(() => '?').join(', ');
         const query = `DELETE FROM [${tableName}] WHERE id IN (${placeholders})`;
-        return this._runWithParams(query, ids);
+        return Promise.resolve(this._runWithParams(query, ids));
     }
 
-    get(query, entity, context){
+    async get(query, entity, context){
         var queryString = {};
         try {
             if(query.raw){
@@ -117,26 +132,26 @@ class SQLLiteEngine {
                     console.debug("[Params]", params);
                 }
                 var queryReturn = this.db.prepare(queryString.query).get(...params);
-                return queryReturn;
+                return Promise.resolve(queryReturn);
             }
-            return null;
+            return Promise.resolve(null);
         } catch (err) {
             console.error(err);
-            return null;
+            return Promise.resolve(null);
         }
     }
 
     // Introspection helpers
-    tableExists(tableName){
+    async tableExists(tableName){
         try{
             // Use parameterized query to prevent SQL injection
             const sql = `SELECT name FROM sqlite_master WHERE type='table' AND name=?`;
             const row = this.db.prepare(sql).get(tableName);
-            return !!row;
-        }catch(_){ return false; }
+            return Promise.resolve(!!row);
+        }catch(_){ return Promise.resolve(false); }
     }
 
-    getTableInfo(tableName){
+    async getTableInfo(tableName){
         try{
             // Security: Validate table name to prevent SQL injection
             // PRAGMA statements don't support parameterized queries
@@ -149,11 +164,11 @@ class SQLLiteEngine {
             }
             const sql = `PRAGMA table_info(${tableName})`;
             const rows = this.db.prepare(sql).all();
-            return rows || [];
-        }catch(_){ return []; }
+            return Promise.resolve(rows || []);
+        }catch(_){ return Promise.resolve([]); }
     }
 
-    getCount(queryObject, entity, context){
+    async getCount(queryObject, entity, context){
         var query = queryObject.script;
         var queryString = {};
         try {
@@ -176,23 +191,23 @@ class SQLLiteEngine {
                     console.debug("[Params]", params);
                 }
                 var queryReturn = this.db.prepare(queryCount).get(...params);
-                return queryReturn;
+                return Promise.resolve(queryReturn);
             }
-            return null;
+            return Promise.resolve(null);
         } catch (err) {
             console.error(err);
-            return null;
+            return Promise.resolve(null);
         }
     }
 
-    all(query, entity, context){
+    async all(query, entity, context){
         var selectQuery = {};
         try {
             if(query.raw){
                 selectQuery.query = query.raw;
             }
             else{
-              
+
                 selectQuery = this.buildQuery(query, entity, context);
             }
             if(selectQuery.query){
@@ -203,12 +218,12 @@ class SQLLiteEngine {
                     console.debug("[Params]", params);
                 }
                 var queryReturn = this.db.prepare(selectQuery.query).all(...params);
-                return queryReturn;
+                return Promise.resolve(queryReturn);
             }
-            return null;
+            return Promise.resolve(null);
         } catch (err) {
             console.error(err);
-            return null;
+            return Promise.resolve(null);
         }
     }
 
@@ -623,16 +638,25 @@ class SQLLiteEngine {
         return false;
     }
 
-    startTransaction(){
-        this.db.prepare('BEGIN').run();
+    async startTransaction(){
+        // Prevent nested transactions (SQLite limitation)
+        return Promise.resolve(
+            this.db.inTransaction ? null : this.db.prepare('BEGIN').run()
+        );
     }
 
-    endTransaction(){
-        this.db.prepare('COMMIT').run();
+    async endTransaction(){
+        // Only commit if transaction is active
+        return Promise.resolve(
+            this.db.inTransaction ? this.db.prepare('COMMIT').run() : null
+        );
     }
 
-    errorTransaction(){
-        this.db.prepare('ROLLBACK').run();
+    async errorTransaction(){
+        // Only rollback if transaction is active
+        return Promise.resolve(
+            this.db.inTransaction ? this.db.prepare('ROLLBACK').run() : null
+        );
     }
 
     _buildSQLEqualTo(model){
@@ -1222,6 +1246,17 @@ class SQLLiteEngine {
        this.db = db;
        this.dbType = type; // this will let us know which type of sqlengine to use.
    }
+
+    /**
+     * Close database connection
+     * Required for proper cleanup of better-sqlite3 native bindings
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            console.log('SQLite database closed');
+        }
+    }
 }
 
 module.exports = SQLLiteEngine;

package/context.js

@@ -20,7 +20,7 @@ const modelBuilder = require('./Entity/entityModelBuilder');
 const query = require('masterrecord/QueryLanguage/queryMethods');
 const tools = require('./Tools');
 const SQLLiteEngine = require('masterrecord/SQLLiteEngine');
-const MYSQLEngine = require('masterrecord/mySQLEngine');
+const MySQLEngine = require('masterrecord/realMySQLEngine');
 const PostgresEngine = require('masterrecord/postgresEngine');
 const insertManager = require('./insertManager');
 const deleteManager = require('./deleteManager');
@@ -28,7 +28,7 @@ const globSearch = require('glob');
 const fs = require('fs');
 const path = require('path');
 const appRoot = require('app-root-path');
-const MySQLClient = require('masterrecord/mySQLSyncConnect');
+const MySQLAsyncClient = require('masterrecord/mySQLAsyncConnect');
 const PostgresClient = require('masterrecord/postgresSyncConnect');
 const QueryCache = require('./Cache/QueryCache');
 
@@ -284,7 +284,7 @@ class context {
      * @returns {object} MySQL connection instance
      * @throws {DatabaseConnectionError} If connection fails
      */
-    __mysqlInit(env, sqlName) {
+    async __mysqlInit(env, sqlName) {
         try {
             // Validate required MySQL configuration
             if (!env.database || typeof env.database !== 'string') {
@@ -303,11 +303,18 @@ class context {
                 );
             }
 
-            const connection = new MySQLClient(env);
-            this._SQLEngine = new MYSQLEngine();
+            console.log('[MySQL] Initializing async connection pool...');
+            const client = new MySQLAsyncClient(env);
+            await client.connect();
+
+            const pool = client.getPool();
+            this._SQLEngine = new MySQLEngine();
+            this._SQLEngine.setDB(pool);
             this._SQLEngine.__name = sqlName;
+            this.isMySQL = true;
 
-            return connection;
+            console.log('[MySQL] Connection pool ready');
+            return client;
         } catch (error) {
             // Preserve original error if it's already a ContextError
             if (error instanceof ContextError) {
@@ -624,15 +631,18 @@ class context {
                 return this;
             }
 
-            // MySQL initialization
+            // MySQL initialization (async)
             if (type === DB_TYPES.MYSQL) {
                 this.isMySQL = true;
                 this.isSQLite = false;
                 this.isPostgres = false;
 
-                this.db = this.__mysqlInit(options, 'mysql2');
-                this._SQLEngine.setDB(this.db, 'mysql');
-                return this;
+                // MySQL is async - caller must await env()
+                return (async () => {
+                    this.db = await this.__mysqlInit(options, 'mysql2');
+                    // Note: engine is already set in __mysqlInit
+                    return this;
+                })();
             }
 
             // PostgreSQL initialization (async)
@@ -833,7 +843,7 @@ class context {
      * @example
      * context.useMySql('./config/environments');
      */
-    useMySql(rootFolderLocation) {
+    async useMySql(rootFolderLocation) {
         try {
             this.isMySQL = true;
             this.isSQLite = false;
@@ -857,8 +867,8 @@ class context {
             }
 
             this.validateSQLiteOptions(options);
-            this.db = this.__mysqlInit(options, 'mysql2');
-            this._SQLEngine.setDB(this.db, 'mysql');
+            this.db = await this.__mysqlInit(options, 'mysql2');
+            // Note: engine is already set in __mysqlInit
             return this;
         } catch (error) {
             // Preserve original error if it's already a ContextError
@@ -966,7 +976,7 @@ class context {
      * @private
      * @param {Array<object>} tracked - Array of tracked entities
      */
-    _processTrackedEntities(tracked) {
+    async _processTrackedEntities(tracked) {
         // Group entities by state for batch operations (single pass)
         const toInsert = [];
         const toUpdate = [];
@@ -998,17 +1008,17 @@ class context {
 
         // Batch insert operations
         if (toInsert.length > 0) {
-            this._processBatchInserts(toInsert);
+            await this._processBatchInserts(toInsert);
         }
 
         // Batch update operations
         if (toUpdate.length > 0) {
-            this._processBatchUpdates(toUpdate);
+            await this._processBatchUpdates(toUpdate);
         }
 
         // Batch delete operations
         if (toDelete.length > 0) {
-            this._processBatchDeletes(toDelete);
+            await this._processBatchDeletes(toDelete);
         }
     }
 
@@ -1018,21 +1028,21 @@ class context {
      * @private
      * @param {Array<object>} entities - Entities to insert
      */
-    _processBatchInserts(entities) {
+    async _processBatchInserts(entities) {
         if (entities.length === 1) {
             // Single insert - use existing insertManager
             const insert = new insertManager(this._SQLEngine, this._isModelValid, this.__entities);
-            insert.init(entities[0]);
+            await insert.init(entities[0]);
         } else {
             // Batch insert - 100x faster for multiple records
             try {
-                this._SQLEngine.bulkInsert(entities);
+                await this._SQLEngine.bulkInsert(entities);
             } catch (error) {
                 console.error('[Context] Bulk insert failed, falling back to individual inserts:', error.message);
                 // Fallback to individual inserts
                 for (const entity of entities) {
                     const insert = new insertManager(this._SQLEngine, this._isModelValid, this.__entities);
-                    insert.init(entity);
+                    await insert.init(entity);
                 }
             }
         }
@@ -1044,7 +1054,7 @@ class context {
      * @private
      * @param {Array<object>} entities - Entities to update
      */
-    _processBatchUpdates(entities) {
+    async _processBatchUpdates(entities) {
         if (entities.length === 1) {
             // Single update - use existing logic
             const currentModel = entities[0];
@@ -1059,7 +1069,7 @@ class context {
                     primaryKey: primaryKey,
                     primaryKeyValue: cleanCurrentModel[primaryKey]
                 };
-                this._SQLEngine.update(sqlUpdate);
+                await this._SQLEngine.update(sqlUpdate);
             } else {
                 console.warn('[Context] Entity marked for update but no changes detected');
             }
@@ -1084,12 +1094,12 @@ class context {
 
             if (updateQueries.length > 0) {
                 try {
-                    this._SQLEngine.bulkUpdate(updateQueries);
+                    await this._SQLEngine.bulkUpdate(updateQueries);
                 } catch (error) {
                     console.error('[Context] Bulk update failed, falling back to individual updates:', error.message);
                     // Fallback to individual updates
                     for (const query of updateQueries) {
-                        this._SQLEngine.update(query);
+                        await this._SQLEngine.update(query);
                     }
                 }
             }
@@ -1102,11 +1112,11 @@ class context {
      * @private
      * @param {Array<object>} entities - Entities to delete
      */
-    _processBatchDeletes(entities) {
+    async _processBatchDeletes(entities) {
         if (entities.length === 1) {
             // Single delete - use existing deleteManager
             const deleteObject = new deleteManager(this._SQLEngine, this.__entities);
-            deleteObject.init(entities[0]);
+            await deleteObject.init(entities[0]);
         } else {
             // Batch delete - group by table for efficiency
             const deletesByTable = new Map();  // Use Map instead of object for better performance
@@ -1125,14 +1135,14 @@ class context {
             try {
                 // Performance: Use for...of with Map entries
                 for (const [tableName, ids] of deletesByTable.entries()) {
-                    this._SQLEngine.bulkDelete(tableName, ids);
+                    await this._SQLEngine.bulkDelete(tableName, ids);
                 }
             } catch (error) {
                 console.error('[Context] Bulk delete failed, falling back to individual deletes:', error.message);
                 // Fallback to individual deletes
                 for (const entity of entities) {
                     const deleteObject = new deleteManager(this._SQLEngine, this.__entities);
-                    deleteObject.init(entity);
+                    await deleteObject.init(entity);
                 }
             }
         }
@@ -1152,7 +1162,7 @@ class context {
      * user.name = 'Alice';
      * db.saveChanges();
      */
-    saveChanges() {
+    async saveChanges() {
         try {
             const tracked = this.__trackedEntities;
 
@@ -1171,22 +1181,22 @@ class context {
 
             // Handle transactions based on database type
             if (this.isSQLite) {
-                this._SQLEngine.startTransaction();
+                await this._SQLEngine.startTransaction();
                 try {
-                    this._processTrackedEntities(tracked);
+                    await this._processTrackedEntities(tracked);
                     this.__clearErrorHandler();
-                    this._SQLEngine.endTransaction();
+                    await this._SQLEngine.endTransaction();
                 } catch (error) {
-                    this._SQLEngine.errorTransaction();
+                    await this._SQLEngine.errorTransaction();
                     throw error;
                 }
             } else if (this.isMySQL) {
-                // MySQL: Synchronous operations (transaction handling managed elsewhere)
-                this._processTrackedEntities(tracked);
+                // MySQL: Async operations
+                await this._processTrackedEntities(tracked);
                 this.__clearErrorHandler();
             } else if (this.isPostgres) {
-                // PostgreSQL: Async operations (transaction handling managed elsewhere)
-                this._processTrackedEntities(tracked);
+                // PostgreSQL: Async operations
+                await this._processTrackedEntities(tracked);
                 this.__clearErrorHandler();
             }
 

package/deleteManager.js

@@ -26,14 +26,14 @@ class DeleteManager {
      * @param {Object|Array} currentModel - Entity or entities to delete
      * @throws {Error} If deletion fails
      */
-    init(currentModel) {
+    async init(currentModel) {
         // Input validation
         if (!currentModel) {
             throw new Error('DeleteManager.init() requires a valid model');
         }
 
         try {
-            this.cascadeDelete(currentModel);
+            await this.cascadeDelete(currentModel);
         } catch (error) {
             // Add context to error
             const entityName = currentModel.__entity?.__name || 'unknown';
@@ -46,15 +46,15 @@ class DeleteManager {
      * @param {Object|Array} currentModel - Entity or entities to delete
      * @throws {Error} If cascade deletion fails
      */
-    cascadeDelete(currentModel) {
+    async cascadeDelete(currentModel) {
         if (!currentModel) {
             return; // Nothing to delete
         }
 
         if (!Array.isArray(currentModel)) {
-            this._deleteSingleEntity(currentModel);
+            await this._deleteSingleEntity(currentModel);
         } else {
-            this._deleteMultipleEntities(currentModel);
+            await this._deleteMultipleEntities(currentModel);
         }
     }
 
@@ -63,7 +63,7 @@ class DeleteManager {
      * @private
      * @param {Object} entity - Entity to delete
      */
-    _deleteSingleEntity(entity) {
+    async _deleteSingleEntity(entity) {
         // Validate entity structure
         if (!entity.__entity) {
             throw new Error('Entity missing __entity metadata');
@@ -90,13 +90,13 @@ class DeleteManager {
                     }
                 } else {
                     // Recursively delete related entities
-                    this.cascadeDelete(relatedModel);
+                    await this.cascadeDelete(relatedModel);
                 }
             }
         }
 
         // Delete the entity itself after cascading
-        this._SQLEngine.delete(entity);
+        await this._SQLEngine.delete(entity);
     }
 
     /**
@@ -104,7 +104,7 @@ class DeleteManager {
      * @private
      * @param {Array} entities - Array of entities to delete
      */
-    _deleteMultipleEntities(entities) {
+    async _deleteMultipleEntities(entities) {
         if (entities.length === 0) {
             return; // Nothing to delete
         }
@@ -132,13 +132,13 @@ class DeleteManager {
                     const relatedModel = entity[property];
 
                     if (relatedModel !== null && relatedModel !== undefined) {
-                        this.cascadeDelete(relatedModel);
+                        await this.cascadeDelete(relatedModel);
                     }
                 }
             }
 
             // Delete the entity
-            this._SQLEngine.delete(entity);
+            await this._SQLEngine.delete(entity);
         }
     }