masterrecord 0.2.34 → 0.3.0

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**.