masterrecord 0.2.36 → 0.3.1

package/context.js

@@ -5,6 +5,7 @@ var query = require('masterrecord/QueryLanguage/queryMethods');
 var tools =  require('./Tools');
 var SQLLiteEngine = require('masterrecord/SQLLiteEngine');
 var MYSQLEngine = require('masterrecord/mySQLEngine');
+var PostgresEngine = require('masterrecord/postgresEngine');
 var insertManager = require('./insertManager');
 var deleteManager = require('./deleteManager');
 var globSearch = require("glob");
@@ -12,6 +13,7 @@ var fs = require('fs');
 var path = require('path');
 const appRoot = require('app-root-path');
 const MySQLClient = require('masterrecord/mySQLSyncConnect');
+const PostgresClient = require('masterrecord/postgresSyncConnect');
 
 class context {
     _isModelValid = {
@@ -72,7 +74,7 @@ class context {
           */
     __mysqlInit(env, sqlName){
         try{
- 
+
             //const mysql = require(sqlName);
             const connection = new MySQLClient(env);
             this._SQLEngine = new MYSQLEngine();
@@ -85,6 +87,31 @@ class context {
         }
     }
 
+    /*
+    postgres expected model
+         {
+             "type": "postgres",
+            host     : 'localhost',
+            port     : 5432,
+            user     : 'me',
+            password : 'secret',
+            database : 'my_db'
+          }
+          */
+    async __postgresInit(env, sqlName){
+        try{
+            const connection = new PostgresClient();
+            await connection.connect(env);
+            this._SQLEngine = connection.getEngine();
+            this._SQLEngine.__name = sqlName;
+            return connection.getPool();
+        }
+        catch (e) {
+            console.log("error PostgreSQL", e);
+            throw e;
+        }
+    }
+
     __clearErrorHandler(){
         this._isModelValid = {
             isValid: true,
@@ -212,13 +239,23 @@ class context {
             }
 
             if(type === 'mysql'){
-                this.isMySQL = true; this.isSQLite = false;
+                this.isMySQL = true; this.isSQLite = false; this.isPostgres = false;
                 this.db = this.__mysqlInit(options, 'mysql2');
                 this._SQLEngine.setDB(this.db, 'mysql');
                 return this;
             }
 
-            throw new Error(`Unsupported database type '${options.type}'. Expected 'sqlite' or 'mysql'.`);
+            if(type === 'postgres' || type === 'postgresql'){
+                this.isPostgres = true; this.isMySQL = false; this.isSQLite = false;
+                // Postgres is async, so we need to handle promises
+                (async () => {
+                    this.db = await this.__postgresInit(options, 'pg');
+                    // Note: engine is already set in __postgresInit
+                })();
+                return this;
+            }
+
+            throw new Error(`Unsupported database type '${options.type}'. Expected 'sqlite', 'mysql', or 'postgres'.`);
         }
         catch(err){
             console.log("error:", err);
@@ -385,9 +422,9 @@ class context {
                                 break;
                                 case "modified":
                                     if(currentModel.__dirtyFields.length > 0){
-                                        var cleanCurrentModel = tools.removePrimarykeyandVirtual(currentModel, currentModel._entity); 
-                                        // build columns equal to value string 
-                                        var argu = this._SQLEngine._buildSQLEqualTo(cleanCurrentModel);
+                                        var cleanCurrentModel = tools.removePrimarykeyandVirtual(currentModel, currentModel._entity);
+                                        // Use NEW SECURE parameterized version
+                                        var argu = this._SQLEngine._buildSQLEqualToParameterized(cleanCurrentModel);
                                         if(argu !== -1 ){
                                             var primaryKey  = tools.getPrimaryKeyObject(cleanCurrentModel.__entity);
                                             var sqlUpdate = {tableName: cleanCurrentModel.__entity.__name, arg: argu, primaryKey : primaryKey, primaryKeyValue : cleanCurrentModel[primaryKey] };
@@ -396,7 +433,7 @@ class context {
                                         else{
                                             console.log("Nothing has been tracked, modified, created or added");
                                         }
-                                        
+
                                     }
                                     else{
                                         console.log("Tracked entity modified with no values being changed");
@@ -419,16 +456,16 @@ class context {
                     for (var model in tracked) {
                         var currentModel = tracked[model];
                             switch(currentModel.__state) {
-                                case "insert": 
+                                case "insert":
                                     var insert = new insertManager(this._SQLEngine, this._isModelValid, this.__entities);
                                     insert.init(currentModel);
-                                    
+
                                 break;
                                 case "modified":
                                     if(currentModel.__dirtyFields.length > 0){
                                         var cleanCurrentModel = tools.removePrimarykeyandVirtual(currentModel, currentModel._entity);
-                                        // build columns equal to value string 
-                                        var argu = this._SQLEngine._buildSQLEqualTo(cleanCurrentModel);
+                                        // Use NEW SECURE parameterized version
+                                        var argu = this._SQLEngine._buildSQLEqualToParameterized(cleanCurrentModel);
                                         if(argu !== -1 ){
                                             var primaryKey  = tools.getPrimaryKeyObject(cleanCurrentModel.__entity);
                                             var sqlUpdate = {tableName: cleanCurrentModel.__entity.__name, arg: argu, primaryKey : primaryKey, primaryKeyValue : cleanCurrentModel[primaryKey] };
@@ -437,7 +474,7 @@ class context {
                                         else{
                                             console.log("Nothing has been tracked, modified, created or added");
                                         }
-                                       
+
                                     }
                                     else{
                                         console.log("Tracked entity modified with no values being changed");
@@ -448,13 +485,53 @@ class context {
                                 case "delete":
                                     var deleteObject = new deleteManager(this._SQLEngine, this.__entities);
                                     deleteObject.init(currentModel);
-                                    
+
                                 break;
-                            } 
+                            }
                     }
                     this.__clearErrorHandler();
                     //this._SQLEngine.endTransaction();
                 }
+                if(this.isPostgres){
+                    // PostgreSQL async operations (no transaction control here)
+                    for (var model in tracked) {
+                        var currentModel = tracked[model];
+                            switch(currentModel.__state) {
+                                case "insert":
+                                    var insert = new insertManager(this._SQLEngine, this._isModelValid, this.__entities);
+                                    insert.init(currentModel);
+
+                                break;
+                                case "modified":
+                                    if(currentModel.__dirtyFields.length > 0){
+                                        var cleanCurrentModel = tools.removePrimarykeyandVirtual(currentModel, currentModel._entity);
+                                        // Use NEW SECURE parameterized version
+                                        var argu = this._SQLEngine._buildSQLEqualToParameterized(cleanCurrentModel);
+                                        if(argu !== -1 ){
+                                            var primaryKey  = tools.getPrimaryKeyObject(cleanCurrentModel.__entity);
+                                            var sqlUpdate = {tableName: cleanCurrentModel.__entity.__name, arg: argu, primaryKey : primaryKey, primaryKeyValue : cleanCurrentModel[primaryKey] };
+                                            this._SQLEngine.update(sqlUpdate);
+                                        }
+                                        else{
+                                            console.log("Nothing has been tracked, modified, created or added");
+                                        }
+
+                                    }
+                                    else{
+                                        console.log("Tracked entity modified with no values being changed");
+                                    }
+
+                                // code block
+                                break;
+                                case "delete":
+                                    var deleteObject = new deleteManager(this._SQLEngine, this.__entities);
+                                    deleteObject.init(currentModel);
+
+                                break;
+                            }
+                    }
+                    this.__clearErrorHandler();
+                }
             }
             else{
                 console.log("save changes has no tracked entities");

package/docs/INCLUDES_CLARIFICATION.md

@@ -0,0 +1,202 @@
+# .includes() Syntax Clarification
+
+## Common Confusion: Two Different `.includes()` Methods
+
+There are **two different** `.includes()` methods that developers confuse:
+
+### 1. JavaScript's Native `.includes()` ❌ NOT SUPPORTED
+```javascript
+// ❌ WRONG - This is JavaScript's array.includes()
+const ids = [1, 2, 3];
+context.User.where(u => ids.includes(u.id)).toList();
+//                      ^^^ JavaScript variable reference
+```
+
+**Why it doesn't work:**
+- The lambda `u => ...` is parsed as a **string**, not executed as JavaScript
+- Cannot access JavaScript variables (`ids`) from inside the lambda string
+- Cannot call JavaScript methods on those variables
+
+**Error:**
+```
+ReferenceError: ids is not defined
+```
+
+---
+
+### 2. MasterRecord's `.includes()` ✅ FULLY SUPPORTED
+```javascript
+// ✅ CORRECT - This is MasterRecord's special syntax
+const ids = [1, 2, 3];
+context.User.where(u => $$.includes(u.id), ids).toList();
+//                      ^^ MasterRecord placeholder
+//                                          ^^^ Pass array as argument
+```
+
+**Why it works:**
+- `$$` is a **placeholder** that MasterRecord recognizes
+- The array `ids` is passed as a **separate argument**
+- MasterRecord transforms `$$.includes(u.id)` → `u.id.any($$)` internally
+- Generates proper SQL: `WHERE id IN (?, ?, ?)`
+
+**Generated SQL:**
+```sql
+SELECT * FROM User WHERE id IN (?, ?, ?)
+-- Parameters: [1, 2, 3]
+```
+
+---
+
+## Side-by-Side Comparison
+
+| Feature | JavaScript `.includes()` | MasterRecord `.includes()` |
+|---------|-------------------------|---------------------------|
+| Syntax | `array.includes(field)` | `$$.includes(field)` |
+| Where used | JavaScript code | MasterRecord lambda strings |
+| Array location | Inside lambda | Separate argument |
+| Supported | ❌ No | ✅ Yes |
+
+---
+
+## Examples: Wrong vs Right
+
+### ❌ Wrong: JavaScript Syntax
+```javascript
+// Trying to use JavaScript's includes() - WON'T WORK
+const userIds = [1, 2, 3];
+const roleIds = [10, 20];
+
+// ❌ Wrong
+context.User
+    .where(u => userIds.includes(u.id) && roleIds.includes(u.role_id))
+    .toList();
+
+// Error: userIds is not defined
+```
+
+### ✅ Right: MasterRecord Syntax
+```javascript
+// Using MasterRecord's includes() - WORKS
+const userIds = [1, 2, 3];
+const roleIds = [10, 20];
+
+// ✅ Correct
+context.User
+    .where(u => $$.includes(u.id), userIds)
+    .and(u => $$.includes(u.role_id), roleIds)
+    .toList();
+
+// Generates: WHERE id IN (?, ?, ?) AND role_id IN (?, ?)
+// Params: [1, 2, 3, 10, 20]
+```
+
+---
+
+## Alternative Syntax: `.any()`
+
+You can also use `.any()` directly (it's what `.includes()` transforms to):
+
+```javascript
+// Option 1: .includes() (modern, readable)
+context.User.where(u => $$.includes(u.id), [1, 2, 3]).toList();
+
+// Option 2: .any() (classic syntax)
+context.User.where(u => u.id.any($$), [1, 2, 3]).toList();
+
+// Option 3: .any() with comma string (also works)
+context.User.where(u => u.id.any($$), "1,2,3").toList();
+
+// All three generate the same SQL:
+// WHERE id IN (?, ?, ?)
+// Params: [1, 2, 3]
+```
+
+---
+
+## Why The Lambda is a String
+
+MasterRecord's lambda expressions are **not executed as JavaScript**. They are:
+
+1. **Converted to strings**: `r => r.id == $` becomes the string `"r => r.id == $"`
+2. **Parsed**: MasterRecord extracts entity name (`r`), field name (`id`), operator (`==`), placeholder (`$`)
+3. **Converted to SQL**: Generates `WHERE id = ?`
+
+**This means:**
+- ✅ Can use: MasterRecord syntax (`$$`, `$`, `.any()`, `.includes()`, `.like()`)
+- ❌ Cannot use: JavaScript variables, JavaScript methods, JavaScript operators beyond basic comparison
+
+---
+
+## Common Mistakes and Solutions
+
+### Mistake 1: Referencing JavaScript Variables
+```javascript
+// ❌ Wrong
+const minAge = 18;
+context.User.where(u => u.age > minAge).toList();
+// Error: minAge is not defined
+
+// ✅ Right
+const minAge = 18;
+context.User.where(u => u.age > $, minAge).toList();
+```
+
+### Mistake 2: Using JavaScript Array Methods
+```javascript
+// ❌ Wrong
+const ids = [1, 2, 3];
+context.User.where(u => ids.includes(u.id)).toList();
+// Error: ids is not defined
+
+// ✅ Right
+const ids = [1, 2, 3];
+context.User.where(u => $$.includes(u.id), ids).toList();
+```
+
+### Mistake 3: Calling JavaScript String Methods
+```javascript
+// ❌ Wrong
+context.User.where(u => u.name.startsWith("John")).toList();
+// Error: startsWith is not defined
+
+// ✅ Right - Use SQL LIKE
+context.User.where(u => u.name.like($$), "John%").toList();
+```
+
+---
+
+## Quick Reference
+
+**When writing MasterRecord queries:**
+
+✅ **DO use:**
+- `$$` - Placeholder for parameters
+- `$` - Single placeholder (backwards compatibility)
+- `$$.includes(field)` - IN clause with arrays
+- `field.any($$)` - Alternative IN clause syntax
+- `field.like($$)` - LIKE clause
+- Basic operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`
+
+❌ **DON'T use:**
+- JavaScript variables directly (use `$$` placeholders instead)
+- JavaScript methods (`.includes()`, `.startsWith()`, etc.)
+- Complex JavaScript expressions
+
+---
+
+## Summary
+
+**MasterRecord's `.includes()` is fully supported and works great!**
+
+Just remember:
+1. Use `$$.includes(field)` not `array.includes(field)`
+2. Pass the array as a separate argument
+3. The lambda is a string, not JavaScript code
+
+**Correct Pattern:**
+```javascript
+const values = [1, 2, 3];
+context.Model.where(m => $$.includes(m.field), values).toList();
+```
+
+This is **not a bug** - it's working as designed. The confusion comes from developers trying to use JavaScript's native `.includes()` method inside the lambda string, which isn't possible because lambdas are parsed, not executed.

package/docs/METHODS_REFERENCE.md

@@ -0,0 +1,184 @@
+# MasterRecord Methods Reference
+
+## Common Confusion: Dbset Methods vs Lambda Functions
+
+MasterRecord has two types of methods that are often confused:
+
+### 1. Dbset Methods (Called on context.EntityName)
+
+These are methods you call **directly on the dbset**:
+
+```javascript
+const user = context.User.new();              // ✅ Dbset method
+context.User.add(user);                        // ✅ Dbset method
+context.User.where(u => u.id == $, 1);        // ✅ Dbset method
+context.User.toList();                         // ✅ Dbset method
+context.User.single();                         // ✅ Dbset method
+context.User.remove(user);                     // ✅ Dbset method
+```
+
+**Location**: `QueryLanguage/queryMethods.js`
+
+### 2. Lambda Expression Functions (Used inside WHERE/AND clauses)
+
+These are **functions used INSIDE the lambda expression string**:
+
+```javascript
+// ✅ .any() - Used inside lambda
+context.User.where(u => u.id.any($$), "1,2,3").toList();
+
+// ✅ .like() - Used inside lambda
+context.User.where(u => u.name.like($$), "John%").toList();
+
+// ✅ .includes() - Used inside lambda (transforms to .any())
+context.User.where(u => $$.includes(u.id), [1, 2, 3]).toList();
+```
+
+**Location**: `QueryLanguage/queryScript.js` (parsed from lambda string)
+
+---
+
+## Complete Method List
+
+### Dbset Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `.new()` | Create new entity instance | `const user = context.User.new();` |
+| `.add(entity)` | Track entity for INSERT | `context.User.add(user);` |
+| `.remove(entity)` | Track entity for DELETE | `context.User.remove(user);` |
+| `.where(lambda, ...args)` | Filter query | `context.User.where(u => u.id == $, 1)` |
+| `.and(lambda, ...args)` | Add AND condition | `.where(...).and(u => u.active == true)` |
+| `.orderBy(lambda)` | Sort ascending | `.orderBy(u => u.name)` |
+| `.orderByDescending(lambda)` | Sort descending | `.orderByDescending(u => u.created_at)` |
+| `.take(n)` | Limit results | `.take(10)` |
+| `.skip(n)` | Offset results | `.skip(20)` |
+| `.toList()` | Execute and return array | `.where(...).toList()` |
+| `.single()` | Execute and return one | `.where(...).single()` |
+| `.first()` | Execute and return first | `.where(...).first()` |
+| `.include(lambda)` | Eager load relationships | `.include(u => u.Posts)` |
+| `.raw(sql)` | Execute raw SQL | `.raw("SELECT * FROM User")` |
+
+### Lambda Expression Functions
+
+| Function | Used Inside | Description | Example |
+|----------|-------------|-------------|---------|
+| `.any($$)` | WHERE/AND | IN clause (comma-separated) | `u => u.id.any($$), "1,2,3"` |
+| `.like($$)` | WHERE/AND | LIKE clause | `u => u.name.like($$), "John%"` |
+| `.includes()` | WHERE/AND | IN clause (array) | `$$.includes(u.id), [1,2,3]` |
+
+---
+
+## Common Patterns
+
+### Creating and Inserting Entities
+
+```javascript
+// Create new entity
+const user = context.User.new();
+user.name = "John Doe";
+user.email = "john@example.com";
+user.age = 30;
+
+// Track for insert
+context.User.add(user); // Optional - .new() auto-tracks
+
+// Save to database
+context.saveChanges();
+```
+
+### IN Clause Queries
+
+```javascript
+// Option 1: .any() with comma-separated string
+context.User.where(u => u.id.any($$), "1,2,3").toList();
+
+// Option 2: .includes() with array (Recommended)
+const ids = [1, 2, 3];
+context.User.where(u => $$.includes(u.id), ids).toList();
+
+// Both produce: SELECT * FROM User WHERE id IN (?, ?, ?)
+```
+
+### LIKE Queries
+
+```javascript
+// Starts with
+context.User.where(u => u.name.like($$), "John%").toList();
+
+// Contains
+context.User.where(u => u.email.like($$), "%@example.com%").toList();
+
+// Produces: SELECT * FROM User WHERE name LIKE ?
+```
+
+### Complex Queries
+
+```javascript
+const activeUsers = context.User
+    .where(u => $$.includes(u.role_id), [1, 2, 3])
+    .and(u => u.active == true)
+    .and(u => u.created_at > $, lastWeek)
+    .orderByDescending(u => u.created_at)
+    .take(50)
+    .toList();
+```
+
+---
+
+## Why Your LLM Might Be Confused
+
+### ❌ Common Misunderstanding
+
+```javascript
+// ❌ WRONG - Trying to call .any() on the dbset
+context.User.any(...)  // Error: .any is not a function
+
+// ✅ CORRECT - Use .any() inside the lambda expression
+context.User.where(u => u.id.any($$), "1,2,3")
+```
+
+### Key Difference
+
+- **Dbset methods**: Called on `context.EntityName` (e.g., `.new()`, `.add()`)
+- **Lambda functions**: Used inside the `where()` lambda string (e.g., `.any()`, `.like()`)
+
+---
+
+## Implementation Details
+
+### Dbset Methods
+- **File**: `QueryLanguage/queryMethods.js`
+- **Class**: `queryMethods`
+- **Instance**: Created via `context.dbset(Model)`
+- **Methods**: Prototype methods on `queryMethods` class
+
+### Lambda Functions
+- **File**: `QueryLanguage/queryScript.js`
+- **Parsing**: `describeExpressionPartsFunctions()` (lines 304-388)
+- **Whitelist**: `isFunction()` method (lines 505-513)
+- **Recognized**: `any`, `like`, `include`
+
+---
+
+## Quick Reference
+
+| What You Want | Correct Syntax |
+|---------------|----------------|
+| Create entity | `context.User.new()` |
+| Add to context | `context.User.add(entity)` |
+| Find by ID | `context.User.where(u => u.id == $, 1).single()` |
+| Find multiple IDs | `context.User.where(u => $$.includes(u.id), [1,2,3]).toList()` |
+| Search text | `context.User.where(u => u.name.like($$), "John%").toList()` |
+| Complex filter | `context.User.where(u => u.active == true).and(u => u.age > $, 18).toList()` |
+
+---
+
+## Summary
+
+✅ **`.new()` is a dbset method** - Added in latest version
+✅ **`.any()` is a lambda function** - Already existed
+✅ **`.includes()` is a lambda function** - Transforms to `.any()`
+✅ **Both are different types of methods used in different places**
+
+If your LLM says `.any()` doesn't exist, clarify that it's looking for a **dbset method** when it should be looking for a **lambda expression function**.