masterrecord 0.3.50 → 0.3.52

package/QueryLanguage/queryMethods.js

@@ -171,6 +171,8 @@ class queryMethods{
             this.__queryObject.count(str, this.__entity.__name);
         }
 
+        await this.__context._ensureReady();
+
         if(this.__context.isSQLite){
             // trying to match string select and relace with select Count(*);
             var entityValue = await this.__context._SQLEngine.getCount(this.__queryObject, this.__entity, this.__context);
@@ -178,22 +180,24 @@ class queryMethods{
             this.__reset();
             return val;
         }
-
-        if(this.__context.isMySQL){
+        else if(this.__context.isMySQL){
             // trying to match string select and relace with select Count(*);
             var entityValue = await this.__context._SQLEngine.getCount(this.__queryObject, this.__entity, this.__context);
             var val = entityValue[Object.keys(entityValue)[0]];
             this.__reset();
             return val;
         }
-
-        if(this.__context.isPostgres){
+        else if(this.__context.isPostgres){
             // trying to match string select and relace with select Count(*);
             var entityValue = await this.__context._SQLEngine.getCount(this.__queryObject, this.__entity, this.__context);
             var val = entityValue[Object.keys(entityValue)[0]];
             this.__reset();
             return val;
         }
+        else {
+            this.__reset();
+            throw new Error('No database type configured. Ensure context.env() or context.useMySql()/useSqlite() has been called and awaited.');
+        }
     }
 
     /**
@@ -315,7 +319,7 @@ class queryMethods{
         // Get database type from context
         const dbType = this.__context.isSQLite ? 'sqlite' :
                       this.__context.isMySQL ? 'mysql' :
-                      this.__context.isPostgres ? 'postgres' : 'sqlite';
+                      this.__context.isPostgres ? 'postgres' : 'unknown';
 
         // Replace $$ with ? placeholders and collect parameter values
         if(args){
@@ -436,20 +440,23 @@ class queryMethods{
         }
 
         // Cache miss - execute query
+        await this.__context._ensureReady();
         var result = null;
         if(this.__context.isSQLite){
             var entityValue = await this.__context._SQLEngine.get(this.__queryObject.script, this.__entity, this.__context);
             result = this.__singleEntityBuilder(entityValue);
         }
-
-        if(this.__context.isMySQL){
+        else if(this.__context.isMySQL){
             var entityValue = await this.__context._SQLEngine.get(this.__queryObject.script, this.__entity, this.__context);
-            result = this.__singleEntityBuilder(entityValue[0]);
+            result = this.__singleEntityBuilder(entityValue);
         }
-
-        if(this.__context.isPostgres){
+        else if(this.__context.isPostgres){
             var entityValue = await this.__context._SQLEngine.get(this.__queryObject.script, this.__entity, this.__context);
-            result = this.__singleEntityBuilder(entityValue[0]);
+            result = this.__singleEntityBuilder(entityValue);
+        }
+        else {
+            this.__reset();
+            throw new Error('No database type configured. Ensure context.env() or context.useMySql()/useSqlite() has been called and awaited.');
         }
 
         // Store in cache
@@ -486,21 +493,24 @@ class queryMethods{
         }
 
         // Cache miss - execute query
+        await this.__context._ensureReady();
         var result = [];
         if(this.__context.isSQLite){
             var entityValue = await this.__context._SQLEngine.all(this.__queryObject.script, this.__entity, this.__context);
             result = this.__multipleEntityBuilder(entityValue);
         }
-
-        if(this.__context.isMySQL){
+        else if(this.__context.isMySQL){
             var entityValue = await this.__context._SQLEngine.all(this.__queryObject.script, this.__entity, this.__context);
             result = this.__multipleEntityBuilder(entityValue);
         }
-
-        if(this.__context.isPostgres){
+        else if(this.__context.isPostgres){
             var entityValue = await this.__context._SQLEngine.all(this.__queryObject.script, this.__entity, this.__context);
             result = this.__multipleEntityBuilder(entityValue);
         }
+        else {
+            this.__reset();
+            throw new Error('No database type configured. Ensure context.env() or context.useMySql()/useSqlite() has been called and awaited.');
+        }
 
         // Store in cache
         if (this.__useCache && result) {

package/context.js

@@ -184,6 +184,9 @@ class context {
     isMySQL = false;
     isPostgres = false;
 
+    // Async readiness flag — set by _ensureReady() after _initPromise resolves
+    _ready = false;
+
     // Static shared cache - all context instances share the same cache
     static _sharedQueryCache = null;
 
@@ -233,6 +236,33 @@ class context {
         this._queryCache = context._sharedQueryCache;
     }
 
+    /**
+     * Ensure the database engine is initialized and ready for queries.
+     *
+     * If an async init is in flight (_initPromise), awaits it.
+     * If _SQLEngine is still null after that, throws a clear error.
+     * Subsequent calls are a single boolean check (no-op).
+     *
+     * @throws {DatabaseConnectionError} If the engine failed to initialize
+     */
+    async _ensureReady() {
+        if (this._ready) return;
+        if (this._initPromise) {
+            await this._initPromise;
+        }
+        if (!this._SQLEngine) {
+            const dbType = this.isMySQL ? 'MySQL' :
+                           this.isPostgres ? 'PostgreSQL' :
+                           this.isSQLite ? 'SQLite' : 'unknown';
+            throw new DatabaseConnectionError(
+                'Database engine not initialized. Ensure you have awaited env() or the appropriate use*() method before querying.',
+                dbType,
+                { hasInitPromise: !!this._initPromise, isSQLite: this.isSQLite, isMySQL: this.isMySQL, isPostgres: this.isPostgres }
+            );
+        }
+        this._ready = true;
+    }
+
     /**
      * Parse integer environment variable with validation
      *
@@ -769,8 +799,10 @@ class context {
                     // Note: engine is already set in __mysqlInit
                     return this;
                 })();
-                // Prevent unhandled rejection crash — _ensureReady() will handle errors
-                this._initPromise.catch(() => {});
+                // Prevent unhandled rejection crash — _ensureReady() will re-throw on query
+                this._initPromise.catch((err) => {
+                    console.error(`[MasterRecord] Database initialization failed: ${err.message || err}`);
+                });
                 return this._initPromise;
             }
 
@@ -790,8 +822,10 @@ class context {
                     // Note: engine is already set in __postgresInit
                     return this;
                 })();
-                // Prevent unhandled rejection crash — _ensureReady() will handle errors
-                this._initPromise.catch(() => {});
+                // Prevent unhandled rejection crash — _ensureReady() will re-throw on query
+                this._initPromise.catch((err) => {
+                    console.error(`[MasterRecord] Database initialization failed: ${err.message || err}`);
+                });
                 return this._initPromise;
             }
 
@@ -879,7 +913,7 @@ class context {
                 );
             }
 
-            this.validateSQLiteOptions(options);
+            this.validateDatabaseOptions(options);
 
             // Resolve database path using extracted method (eliminates duplicate code)
             const dbPath = this._resolveDatabasePath(options.connection, file.rootFolder, contextName);
@@ -931,7 +965,7 @@ class context {
      * @param {object} options - Database configuration options
      * @throws {ConfigurationError} If options are invalid
      */
-    validateSQLiteOptions(options) {
+    validateDatabaseOptions(options) {
         if (!options || typeof options !== 'object') {
             throw new ConfigurationError('Configuration object is missing or invalid');
         }
@@ -1005,6 +1039,11 @@ class context {
         );
     }
 
+    /** @deprecated Use validateDatabaseOptions() */
+    validateSQLiteOptions(options) {
+        return this.validateDatabaseOptions(options);
+    }
+
     /**
      * Initialize MySQL database connection using environment file
      *
@@ -1039,7 +1078,7 @@ class context {
                 );
             }
 
-            this.validateSQLiteOptions(options);
+            this.validateDatabaseOptions(options);
             this.db = await this.__mysqlInit(options, 'mysql2');
             // Note: engine is already set in __mysqlInit
             return this;
@@ -1708,6 +1747,7 @@ class context {
      * db.saveChanges();
      */
     async saveChanges() {
+        await this._ensureReady();
         try {
             const tracked = this.__trackedEntities;
 
@@ -1773,6 +1813,12 @@ class context {
      * context._execute('CREATE INDEX idx_user_email ON User(email)');
      */
     _execute(query) {
+        if (!this._SQLEngine) {
+            throw new DatabaseConnectionError(
+                'Cannot execute query: database engine not initialized. Ensure you have awaited env() before running queries.',
+                this.isMySQL ? 'MySQL' : this.isPostgres ? 'PostgreSQL' : 'SQLite'
+            );
+        }
         return this._SQLEngine._execute(query);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.50",
+  "version": "0.3.52",
   "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/test/ensure-ready-test.js

@@ -0,0 +1,251 @@
+/**
+ * Test: _ensureReady(), validateDatabaseOptions rename, and async guards
+ *
+ * Verifies:
+ * - Query before env() resolves → throws clear DatabaseConnectionError
+ * - Query after await env() → works normally (no regression)
+ * - SQLite works without _initPromise (fast path)
+ * - validateDatabaseOptions works, validateSQLiteOptions alias works
+ * - _execute() throws when engine is null
+ * - saveChanges() throws when engine is null
+ */
+
+const context = require('../context');
+
+console.log("╔════════════════════════════════════════════════════════════════╗");
+console.log("║       _ensureReady + Rename + Async Guards Test              ║");
+console.log("╚════════════════════════════════════════════════════════════════╝\n");
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, passMsg, failMsg) {
+    if (condition) {
+        console.log(`   ✓ ${passMsg}`);
+        passed++;
+    } else {
+        console.log(`   ✗ ${failMsg}`);
+        failed++;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: _ensureReady() throws when engine is null and no init promise
+// ---------------------------------------------------------------------------
+console.log("📝 Test 1: _ensureReady() throws DatabaseConnectionError when engine is null");
+console.log("──────────────────────────────────────────────────────────────────");
+
+(async () => {
+    try {
+        const ctx = new context();
+        // No env() called — _SQLEngine is null, no _initPromise
+        try {
+            await ctx._ensureReady();
+            assert(false, "", "_ensureReady() did not throw when engine is null");
+        } catch (err) {
+            assert(
+                err.name === 'DatabaseConnectionError',
+                `Throws DatabaseConnectionError (got: ${err.name})`,
+                `Expected DatabaseConnectionError, got: ${err.name}`
+            );
+            assert(
+                err.message.includes('Database engine not initialized'),
+                `Error message is descriptive: "${err.message.substring(0, 60)}..."`,
+                `Unexpected error message: ${err.message}`
+            );
+        }
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 2: _ensureReady() is a no-op after _ready is set
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 2: _ensureReady() fast path — no-op when _ready is true");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        ctx._SQLEngine = {};  // Fake engine
+        ctx.isSQLite = true;
+        await ctx._ensureReady();  // Should set _ready = true
+        assert(ctx._ready === true, "_ready is true after first call", "_ready was not set");
+
+        // Second call should be instant (no-op)
+        await ctx._ensureReady();
+        assert(true, "Second call completes without error (fast path)", "");
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 3: _ensureReady() awaits _initPromise if present
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 3: _ensureReady() awaits _initPromise");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        ctx.isMySQL = true;
+        // Simulate async init that sets _SQLEngine after a tick
+        ctx._initPromise = new Promise((resolve) => {
+            setTimeout(() => {
+                ctx._SQLEngine = {};  // Fake engine
+                resolve();
+            }, 10);
+        });
+        // Prevent unhandled rejection
+        ctx._initPromise.catch(() => {});
+
+        await ctx._ensureReady();
+        assert(
+            ctx._SQLEngine !== null,
+            "_SQLEngine is set after _ensureReady() awaits _initPromise",
+            "_SQLEngine is still null"
+        );
+        assert(ctx._ready === true, "_ready is true", "_ready was not set");
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 4: _ensureReady() propagates _initPromise rejection
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 4: _ensureReady() propagates _initPromise rejection");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        ctx.isMySQL = true;
+        ctx._initPromise = Promise.reject(new Error('Connection refused'));
+        // Prevent unhandled rejection warning
+        ctx._initPromise.catch(() => {});
+
+        try {
+            await ctx._ensureReady();
+            assert(false, "", "_ensureReady() did not throw when _initPromise rejected");
+        } catch (err) {
+            assert(
+                err.message === 'Connection refused',
+                `Propagates original rejection: "${err.message}"`,
+                `Unexpected error: ${err.message}`
+            );
+        }
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 5: validateDatabaseOptions exists and works
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 5: validateDatabaseOptions() exists and works");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        assert(
+            typeof ctx.validateDatabaseOptions === 'function',
+            "validateDatabaseOptions is a function",
+            `validateDatabaseOptions is ${typeof ctx.validateDatabaseOptions}`
+        );
+
+        // Test with a valid SQLite config
+        const options = { type: 'sqlite', connection: './test.db' };
+        ctx.validateDatabaseOptions(options);
+        assert(true, "validateDatabaseOptions accepts valid SQLite config", "");
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 6: validateSQLiteOptions deprecated alias works
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 6: validateSQLiteOptions() deprecated alias works");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        assert(
+            typeof ctx.validateSQLiteOptions === 'function',
+            "validateSQLiteOptions alias exists",
+            `validateSQLiteOptions is ${typeof ctx.validateSQLiteOptions}`
+        );
+
+        // Should delegate to validateDatabaseOptions
+        const options = { type: 'sqlite', connection: './test.db' };
+        ctx.validateSQLiteOptions(options);
+        assert(true, "validateSQLiteOptions alias delegates correctly", "");
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 7: _execute() throws when _SQLEngine is null
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 7: _execute() throws when _SQLEngine is null");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        // _SQLEngine is null by default
+        try {
+            ctx._execute('SELECT 1');
+            assert(false, "", "_execute() did not throw when engine is null");
+        } catch (err) {
+            assert(
+                err.name === 'DatabaseConnectionError',
+                `Throws DatabaseConnectionError (got: ${err.name})`,
+                `Expected DatabaseConnectionError, got: ${err.name}`
+            );
+            assert(
+                err.message.includes('database engine not initialized'),
+                `Error message is descriptive`,
+                `Unexpected error message: ${err.message}`
+            );
+        }
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Test 8: saveChanges() throws when engine is null (via _ensureReady)
+    // ---------------------------------------------------------------------------
+    console.log("\n📝 Test 8: saveChanges() throws when engine is null");
+    console.log("──────────────────────────────────────────────────────────────────");
+
+    try {
+        const ctx = new context();
+        // No env() called — should throw via _ensureReady()
+        try {
+            await ctx.saveChanges();
+            // saveChanges returns early if no tracked entities — that's OK
+            // The _ensureReady check happens before the tracked-entities check
+            assert(false, "", "saveChanges() did not throw when engine is null");
+        } catch (err) {
+            assert(
+                err.name === 'DatabaseConnectionError',
+                `Throws DatabaseConnectionError (got: ${err.name})`,
+                `Expected DatabaseConnectionError, got: ${err.name}`
+            );
+        }
+    } catch (err) {
+        console.log(`   ✗ Unexpected error: ${err.message}`);
+        failed++;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Summary
+    // ---------------------------------------------------------------------------
+    console.log("\n══════════════════════════════════════════════════════════════════");
+    console.log(`Results: ${passed} passed, ${failed} failed out of ${passed + failed} assertions`);
+    console.log("══════════════════════════════════════════════════════════════════\n");
+
+    process.exit(failed > 0 ? 1 : 0);
+})();