masterrecord 0.3.8 → 0.3.10

package/deleteManager.js

@@ -1,60 +1,157 @@
-// version 0.0.3
-var tools =  require('./Tools');
-class DeleteManager{
-    constructor(sqlEngine, entities){
+// version 1.0.0 - FAANG-Level Refactored
+const tools = require('./Tools');
+
+// Constants for relationship types
+const RELATIONSHIP_TYPES = {
+    HAS_ONE: 'hasOne',
+    HAS_MANY: 'hasMany',
+    HAS_MANY_THROUGH: 'hasManyThrough'
+};
+
+/**
+ * Manages cascade deletion of entities and their relationships
+ * @class DeleteManager
+ */
+class DeleteManager {
+    constructor(sqlEngine, entities) {
+        if (!sqlEngine) {
+            throw new Error('DeleteManager requires a valid SQL engine');
+        }
         this._SQLEngine = sqlEngine;
-        this._allEntities = entities;
+        this._allEntities = entities || [];
     }
 
-    init(currentModel){
-        var $that = this;
-        try{
-           this.cascadeDelete(currentModel);
+    /**
+     * Initialize deletion for an entity or array of entities
+     * @param {Object|Array} currentModel - Entity or entities to delete
+     * @throws {Error} If deletion fails
+     */
+    init(currentModel) {
+        // Input validation
+        if (!currentModel) {
+            throw new Error('DeleteManager.init() requires a valid model');
         }
-        catch(error){
-            throw error;
+
+        try {
+            this.cascadeDelete(currentModel);
+        } catch (error) {
+            // Add context to error
+            const entityName = currentModel.__entity?.__name || 'unknown';
+            throw new Error(`Failed to delete ${entityName}: ${error.message}`, { cause: error });
         }
     }
 
-    cascadeDelete(currentModel){
-        var $that = this;
-        if(!Array.isArray(currentModel)){
-            const entityKeys = Object.keys(currentModel.__entity);
-            // loop though all entity properties
-            for (const property of entityKeys) {
-                // cascade delete
-                if(currentModel.__entity[property].type === "hasOne" || currentModel.__entity[property].type === "hasMany" || currentModel.__entity[property].type === "hasManyThrough"){
-                    var curModel = currentModel[property];
-                    if(curModel === null){
-                     // check if state is nullable - if so and nothing comes back dont call cascadeDelete
-                     var prp = currentModel.__entity[property];
-                     if(!prp.nullable){
-                        throw "No relationship record found - please set hasOne or hasMany to nullable. "
-                     }
-                    }
-                    else{
-                        $that.cascadeDelete( currentModel[property]);
+    /**
+     * Recursively cascade delete an entity and its relationships
+     * @param {Object|Array} currentModel - Entity or entities to delete
+     * @throws {Error} If cascade deletion fails
+     */
+    cascadeDelete(currentModel) {
+        if (!currentModel) {
+            return; // Nothing to delete
+        }
+
+        if (!Array.isArray(currentModel)) {
+            this._deleteSingleEntity(currentModel);
+        } else {
+            this._deleteMultipleEntities(currentModel);
+        }
+    }
+
+    /**
+     * Delete a single entity with cascade
+     * @private
+     * @param {Object} entity - Entity to delete
+     */
+    _deleteSingleEntity(entity) {
+        // Validate entity structure
+        if (!entity.__entity) {
+            throw new Error('Entity missing __entity metadata');
+        }
+
+        const entityKeys = Object.keys(entity.__entity);
+
+        // Loop through all entity properties to find relationships
+        for (const property of entityKeys) {
+            const propertyConfig = entity.__entity[property];
+
+            // Check if this is a relationship that needs cascade deletion
+            if (this._isRelationshipType(propertyConfig.type)) {
+                const relatedModel = entity[property];
+
+                if (relatedModel === null || relatedModel === undefined) {
+                    // Check if relationship is required (not nullable)
+                    if (!propertyConfig.nullable) {
+                        throw new Error(
+                            `Cannot delete ${entity.__entity.__name}: ` +
+                            `required relationship '${property}' is null. ` +
+                            `Set nullable: true if this is intentional.`
+                        );
                     }
+                } else {
+                    // Recursively delete related entities
+                    this.cascadeDelete(relatedModel);
                 }
             }
-            this._SQLEngine.delete(currentModel);
         }
-        else{
 
-            for(let i = 0 ; i < currentModel.length; i++) {
-                const entityKeys = Object.keys(currentModel[i].__entity);
-                // loop though all entity properties
-                for (const property of entityKeys) {
-                    // cascade delete
-                    if(currentModel[i].__entity[property].type === "hasOne" || currentModel[i].__entity[property].type === "hasMany" || currentModel[i].__entity[property].type === "hasManyThrough"){
-                        $that.cascadeDelete( currentModel[i][property]);
+        // Delete the entity itself after cascading
+        this._SQLEngine.delete(entity);
+    }
+
+    /**
+     * Delete multiple entities with cascade
+     * @private
+     * @param {Array} entities - Array of entities to delete
+     */
+    _deleteMultipleEntities(entities) {
+        if (entities.length === 0) {
+            return; // Nothing to delete
+        }
+
+        // Process each entity
+        for (let i = 0; i < entities.length; i++) {
+            const entity = entities[i];
+
+            if (!entity) {
+                console.warn(`DeleteManager: Skipping null entity at index ${i}`);
+                continue;
+            }
+
+            if (!entity.__entity) {
+                throw new Error(`Entity at index ${i} missing __entity metadata`);
+            }
+
+            const entityKeys = Object.keys(entity.__entity);
+
+            // Loop through relationships for cascade
+            for (const property of entityKeys) {
+                const propertyConfig = entity.__entity[property];
+
+                if (this._isRelationshipType(propertyConfig.type)) {
+                    const relatedModel = entity[property];
+
+                    if (relatedModel !== null && relatedModel !== undefined) {
+                        this.cascadeDelete(relatedModel);
                     }
                 }
-                this._SQLEngine.delete(currentModel[i]);
             }
+
+            // Delete the entity
+            this._SQLEngine.delete(entity);
         }
-        
+    }
 
+    /**
+     * Check if a property type is a relationship that requires cascade deletion
+     * @private
+     * @param {string} type - Property type
+     * @returns {boolean} True if relationship type
+     */
+    _isRelationshipType(type) {
+        return type === RELATIONSHIP_TYPES.HAS_ONE ||
+               type === RELATIONSHIP_TYPES.HAS_MANY ||
+               type === RELATIONSHIP_TYPES.HAS_MANY_THROUGH;
     }
 }
 

package/docs/ACTIVE_RECORD_PATTERN.md

@@ -0,0 +1,477 @@
+# Active Record Pattern - entity.save()
+
+MasterRecord now supports **both** patterns:
+
+1. **Entity Framework style** - `context.saveChanges()`
+2. **Active Record style** - `entity.save()` ✨ NEW!
+
+---
+
+## Active Record Style (NEW)
+
+### Basic Usage
+
+```javascript
+// Load entity
+const task = db.Task.findById(1);
+
+// Modify
+task.status = 'completed';
+task.completed_at = new Date();
+
+// Save (like Active Record!)
+await task.save();  // ✅ Entity saves itself!
+```
+
+### Create New Entity
+
+```javascript
+// Create
+const task = db.Task.new();
+task.name = 'New Task';
+task.status = 'pending';
+
+// Save
+await task.save();  // ✅ Like Active Record!
+
+console.log(task.id);  // Auto-generated ID
+```
+
+### Update Multiple Fields
+
+```javascript
+const user = db.User.findById(userId);
+user.name = 'Updated Name';
+user.email = 'new@example.com';
+user.updated_at = new Date();
+
+await user.save();  // ✅ All changes saved
+```
+
+---
+
+## Solving the Detached Entity Problem
+
+### Before (Manual attach)
+
+```javascript
+// ❌ Required manual attach
+const task = await taskService.getTask(taskId);
+task.status = 'completed';
+db.attach(task);  // Manual attach
+await db.saveChanges();
+```
+
+### After (Active Record style)
+
+```javascript
+// ✅ Just call .save()!
+const task = await taskService.getTask(taskId);
+task.status = 'completed';
+await task.save();  // Entity saves itself!
+```
+
+**Why this works:**
+- Entity has `__context` reference
+- `.save()` automatically tracks the entity
+- No manual `attach()` needed!
+
+---
+
+## Your Original Problem - SOLVED
+
+### Your Original Code (BROKEN)
+
+```javascript
+class AnnotationService {
+    async createAnnotation(taskId, data) {
+        const task = await this._taskService.getTask(taskId);
+
+        const annotation = this._qaContext.Annotation.new();
+        annotation.task_id = taskId;
+        this._qaContext.Annotation.add(annotation);
+
+        task.status = 'completed';  // ❌ Not tracked
+
+        await this._qaContext.saveChanges();  // ❌ Task not saved
+    }
+}
+```
+
+### Solution 1: Active Record Style (EASIEST) ✨
+
+```javascript
+class AnnotationService {
+    async createAnnotation(taskId, data) {
+        const task = await this._taskService.getTask(taskId);
+
+        const annotation = this._qaContext.Annotation.new();
+        annotation.task_id = taskId;
+        annotation.data = data;
+
+        task.status = 'completed';
+
+        // Save both (Active Record style!)
+        await annotation.save();  // ✅ Saves annotation
+        await task.save();         // ✅ Saves task
+
+        return annotation;
+    }
+}
+```
+
+### Solution 2: Entity Framework Style
+
+```javascript
+class AnnotationService {
+    async createAnnotation(taskId, data) {
+        const task = await this._taskService.getTask(taskId);
+
+        const annotation = this._qaContext.Annotation.new();
+        annotation.task_id = taskId;
+        this._qaContext.Annotation.add(annotation);
+
+        task.status = 'completed';
+        this._qaContext.attach(task);  // Attach detached entity
+
+        await this._qaContext.saveChanges();  // Save all
+        return annotation;
+    }
+}
+```
+
+### Solution 3: Pure Active Record
+
+```javascript
+class AnnotationService {
+    async createAnnotation(taskId, data) {
+        const task = await this._taskService.getTask(taskId);
+        task.status = 'completed';
+        await task.save();  // Save task first
+
+        const annotation = this._qaContext.Annotation.new();
+        annotation.task_id = taskId;
+        annotation.data = data;
+        await annotation.save();  // Save annotation
+
+        return annotation;
+    }
+}
+```
+
+---
+
+## Comparison: Both Patterns
+
+### Entity Framework Style
+
+```javascript
+// Load entities
+const user = db.User.findById(1);
+const task = db.Task.findById(2);
+
+// Modify both
+user.name = 'Updated';
+task.status = 'completed';
+
+// Save all at once
+await db.saveChanges();  // Batch save
+```
+
+**Pros:**
+- ✅ Batch operations (efficient)
+- ✅ Transaction-like behavior
+- ✅ One save call for multiple entities
+
+**Cons:**
+- ❌ Less intuitive
+- ❌ Need to track which context has which entities
+
+### Active Record Style (NEW)
+
+```javascript
+// Load entities
+const user = db.User.findById(1);
+const task = db.Task.findById(2);
+
+// Modify and save individually
+user.name = 'Updated';
+await user.save();  // Save user
+
+task.status = 'completed';
+await task.save();  // Save task
+```
+
+**Pros:**
+- ✅ More intuitive (entity saves itself)
+- ✅ No detached entity issues
+- ✅ Works across contexts
+- ✅ Familiar to Rails developers
+
+**Cons:**
+- ❌ Multiple database calls
+- ❌ No automatic batching
+
+---
+
+## When to Use Each Pattern
+
+### Use `entity.save()` when:
+
+✅ Working with single entities
+✅ Entity from external service (detached)
+✅ Quick updates to one entity
+✅ Familiar with Active Record (Rails)
+✅ Want explicit control
+
+```javascript
+// Single entity updates
+const user = db.User.findById(userId);
+user.last_login = new Date();
+await user.save();  // Clear and simple
+```
+
+### Use `context.saveChanges()` when:
+
+✅ Batch operations (multiple entities)
+✅ Need transaction-like behavior
+✅ Performance critical (fewer DB calls)
+✅ Familiar with Entity Framework
+
+```javascript
+// Batch updates
+const users = db.User.where(u => u.active == false).toList();
+users.forEach(u => u.deleted_at = new Date());
+await db.saveChanges();  // One batch save
+```
+
+---
+
+## Complete Examples
+
+### Example 1: User Registration
+
+```javascript
+async function registerUser(data) {
+    const db = new AppContext();
+
+    // Create user
+    const user = db.User.new();
+    user.email = data.email;
+    user.name = data.name;
+    user.password_hash = await hash(data.password);
+
+    // Save (Active Record style)
+    await user.save();  // ✅
+
+    // Send welcome email
+    await sendWelcomeEmail(user);
+
+    return user;
+}
+```
+
+### Example 2: Task Completion
+
+```javascript
+async function completeTask(taskId) {
+    const db = new AppContext();
+
+    const task = db.Task.findById(taskId);
+    task.status = 'completed';
+    task.completed_at = new Date();
+
+    // Save (Active Record style)
+    await task.save();  // ✅
+
+    // Notify user
+    await notifyUser(task.user_id, 'Task completed');
+
+    return task;
+}
+```
+
+### Example 3: Bulk Update (Entity Framework style)
+
+```javascript
+async function archiveOldTasks() {
+    const db = new AppContext();
+
+    const oldTasks = db.Task
+        .where(t => t.status == $$, 'completed')
+        .where(t => t.completed_at < $$, thirtyDaysAgo)
+        .toList();
+
+    oldTasks.forEach(task => {
+        task.archived = true;
+        task.archived_at = new Date();
+    });
+
+    // Batch save (Entity Framework style)
+    await db.saveChanges();  // ✅ Efficient batch update
+
+    return oldTasks.length;
+}
+```
+
+### Example 4: Mixed Pattern
+
+```javascript
+async function processOrder(orderId) {
+    const db = new AppContext();
+
+    // Load order
+    const order = db.Order.findById(orderId);
+    order.status = 'processing';
+    await order.save();  // Save immediately (Active Record)
+
+    // Create line items
+    const items = order.items.map(item => {
+        const lineItem = db.LineItem.new();
+        lineItem.order_id = orderId;
+        lineItem.product_id = item.productId;
+        lineItem.quantity = item.quantity;
+        return lineItem;
+    });
+
+    // Batch save line items (Entity Framework)
+    await db.saveChanges();  // ✅ Efficient for multiple items
+
+    return order;
+}
+```
+
+---
+
+## Rails vs MasterRecord
+
+### Rails (Active Record)
+
+```ruby
+# Create
+user = User.new
+user.name = 'John'
+user.save
+
+# Update
+user = User.find(1)
+user.name = 'Jane'
+user.save
+
+# Delete
+user.destroy
+```
+
+### MasterRecord (Active Record style)
+
+```javascript
+// Create
+const user = db.User.new();
+user.name = 'John';
+await user.save();
+
+// Update
+const user = db.User.findById(1);
+user.name = 'Jane';
+await user.save();
+
+// Delete
+db.remove(user);
+await db.saveChanges();  // Or await user.save()
+```
+
+---
+
+## Important Notes
+
+### 1. `.save()` saves ALL tracked changes
+
+```javascript
+const db = new AppContext();
+
+const user1 = db.User.findById(1);
+user1.name = 'Updated 1';
+
+const user2 = db.User.findById(2);
+user2.name = 'Updated 2';
+
+// Calling save() on either entity saves BOTH
+await user1.save();  // Saves user1 AND user2!
+```
+
+**Why?** `.save()` calls `context.saveChanges()`, which saves all tracked entities in that context.
+
+**To save only one entity:** Use separate contexts or save immediately:
+
+```javascript
+// Option 1: Separate contexts
+const db1 = new AppContext();
+const user1 = db1.User.findById(1);
+user1.name = 'Updated 1';
+await user1.save();  // Only saves user1
+
+const db2 = new AppContext();
+const user2 = db2.User.findById(2);
+user2.name = 'Updated 2';
+await user2.save();  // Only saves user2
+
+// Option 2: Save immediately
+const db = new AppContext();
+const user1 = db.User.findById(1);
+user1.name = 'Updated 1';
+await user1.save();  // Saves and clears tracking
+
+const user2 = db.User.findById(2);
+user2.name = 'Updated 2';
+await user2.save();  // Only user2 tracked at this point
+```
+
+### 2. Entity must have `__context`
+
+```javascript
+// ✅ WORKS: Entity loaded through MasterRecord
+const user = db.User.findById(1);
+await user.save();  // Has __context reference
+
+// ❌ ERROR: Plain object
+const user = { id: 1, name: 'Test' };
+await user.save();  // Error: no __context
+```
+
+### 3. Async/await required
+
+```javascript
+// ✅ GOOD
+await user.save();
+
+// ❌ BAD: Doesn't wait for save
+user.save();
+```
+
+---
+
+## Summary
+
+**MasterRecord now supports Active Record style!** 🎉
+
+```javascript
+// Both patterns work:
+
+// Active Record (NEW)
+await entity.save();
+
+// Entity Framework
+await context.saveChanges();
+
+// Choose what feels natural for your use case!
+```
+
+**Solves the detached entity problem:**
+- No need for manual `attach()`
+- Entity knows its context
+- Just call `.save()`!
+
+**Best of both worlds:** ✨
+- Active Record: Intuitive entity-level saves
+- Entity Framework: Efficient batch operations
+- You choose which to use!