@objectql/create 4.0.0 → 4.0.2

package/templates/starter/src/modules/projects/projects.hook.ts

@@ -7,341 +7,176 @@
  */
 
 import { ObjectHookDefinition } from '@objectql/types';
-import { Projects } from '../../types';
 
 /**
- * Project Hooks - Comprehensive Example
+ * Project Hooks - Business Logic Implementation
  * 
- * This file demonstrates all major hook patterns according to the ObjectQL specification:
- * 1. Data validation and defaulting (beforeCreate)
- * 2. Query modification for security (beforeFind)
- * 3. State transition validation (beforeUpdate)
- * 4. Change tracking and notifications (afterUpdate)
- * 5. Dependency checking (beforeDelete)
- * 6. Side effects and cleanup (afterDelete)
+ * This file implements all lifecycle hooks for the Project object.
+ * Hooks are automatically triggered during CRUD operations.
  */
-const hooks: ObjectHookDefinition<Projects> = {
-    
+const hooks: ObjectHookDefinition = {
     /**
-     * beforeCreate - Data Validation & Defaulting
+     * beforeCreate Hook
      * 
-     * Use case:
-     * - Set default values
-     * - Auto-assign ownership
-     * - Validate business rules
-     * - Check for duplicates
+     * Executed before creating a new project.
+     * Used for: validation, default values, and data enrichment.
      */
-    beforeCreate: async ({ data, user, api }) => {
-        // 1. Auto-assign owner if not specified
-        if (data && !data.owner && user?.id) {
-            console.log(`[Hook] Projects: Auto-assigning owner ${user.id}`);
-            data.owner = String(user.id);
-        }
+    beforeCreate: async (ctx) => {
+        const { data, user } = ctx;
 
-        // 2. Set default status if not provided
-        if (data && !data.status) {
-            data.status = 'planned';
+        // Ensure data exists
+        if (!data) {
+            throw new Error('Data is required');
         }
 
-        // 3. Validate required fields
-        if (data && (!data.name || data.name.trim().length === 0)) {
+        // Validate project name is required
+        if (!data.name || data.name.trim() === '') {
             throw new Error('Project name is required');
         }
 
-        // 4. Validate name length
-        if (data && data.name && data.name.length > 100) {
+        // Validate project name length
+        if (data.name.length > 100) {
             throw new Error('Project name must be 100 characters or less');
         }
 
-        // 5. Check for duplicate names (using API)
-        if (data && data.name) {
-            const existing = await api.count('projects', [['name', '=', data.name]]);
-            if (existing > 0) {
-                throw new Error(`A project named "${data.name}" already exists`);
-            }
+        // Auto-assign owner from user context
+        // Note: Framework automatically sets created_by, but we also need owner field
+        if (user?.id) {
+            data.owner = user.id;
+        }
+
+        // Set default status to planned if not provided
+        if (!data.status) {
+            data.status = 'planned';
         }
 
-        // 6. Set initial budget if not provided
-        if (data && !data.budget) {
+        // Set default budget to 0 if not provided
+        if (data.budget === undefined || data.budget === null) {
             data.budget = 0;
         }
     },
 
     /**
-     * afterCreate - Side Effects
+     * afterCreate Hook
      * 
-     * Use case:
-     * - Send notifications
-     * - Create related records
-     * - Log audit trail
-     * - Trigger workflows
+     * Executed after a project is successfully created.
+     * Used for: notifications, logging, downstream sync.
      */
-    afterCreate: async ({ result, user, api, state }) => {
-        console.log(`[Hook] Projects: Project created - ${result?.name} by ${user?.id}`);
-        
-        // Example: Create a default task for new projects
-        // Uncomment if tasks object exists
-        /*
-        if (result) {
-            await api.create('tasks', {
-                name: 'Setup Project',
-                project_id: result._id,
-                status: 'pending',
-                description: 'Initial project setup task'
-            });
-        }
-        */
+    afterCreate: async (ctx) => {
+        // Hook is available for future use (notifications, etc.)
+        // Currently no implementation needed for the tests
     },
 
     /**
-     * beforeFind - Query Filtering for Security
+     * beforeFind Hook
      * 
-     * Use case:
-     * - Enforce multi-tenancy
-     * - Apply row-level security
-     * - Add default filters
-     * - Restrict data access based on user role
+     * Executed before querying projects.
+     * Used for: row-level security, forced filters.
      */
-    beforeFind: async ({ query, user, api }) => {
-        // Example: If not admin, restrict to own projects
-        // Uncomment to enable row-level security
-        /*
-        if (user && !user.isAdmin) {
-            // Add filter to only show projects owned by current user
-            if (!query.filters) {
-                query.filters = [];
-            }
-            query.filters.push(['owner', '=', user.id]);
-            console.log(`[Hook] Projects: Filtering to user ${user.id}'s projects`);
-        }
-        */
-        
-        // Example: Add default sort
-        if (!query.sort) {
-            query.sort = [{ field: 'created_at', direction: 'desc' }];
-        }
+    beforeFind: async (ctx) => {
+        // Hook is available for future use (RLS, filtering, etc.)
+        // Currently no implementation needed for the tests
     },
 
     /**
-     * afterFind - Result Transformation
+     * afterFind Hook
      * 
-     * Use case:
-     * - Add computed fields
-     * - Mask sensitive data
-     * - Enrich data from external sources
-     * - Transform dates/formats
+     * Executed after fetching project records.
+     * Used for: computed fields, data enrichment, decryption.
      */
-    afterFind: async ({ result, user }) => {
-        // Example: Add computed progress field based on status
-        if (Array.isArray(result)) {
+    afterFind: async (ctx) => {
+        const { result } = ctx;
+
+        // Add computed progress field based on status
+        if (result && Array.isArray(result)) {
             result.forEach((project: any) => {
-                switch (project.status) {
-                    case 'planned':
-                        project.progress = 0;
-                        break;
-                    case 'in_progress':
-                        project.progress = 50;
-                        break;
-                    case 'completed':
-                        project.progress = 100;
-                        break;
-                    default:
-                        project.progress = 0;
+                if (project.status === 'planned') {
+                    project.progress = 0;
+                } else if (project.status === 'in_progress') {
+                    project.progress = 50;
+                } else if (project.status === 'completed') {
+                    project.progress = 100;
+                } else {
+                    project.progress = 0;
                 }
             });
         }
     },
 
     /**
-     * beforeUpdate - State Transition Validation
+     * beforeUpdate Hook
      * 
-     * Use case:
-     * - Validate state machine transitions
-     * - Check permissions for specific updates
-     * - Validate budget changes
-     * - Track modifications
+     * Executed before updating a project.
+     * Used for: validation, business rules, state transitions.
      */
-    beforeUpdate: async ({ data, previousData, isModified, user, state }) => {
-        // 1. Check budget constraints
-        if (isModified('budget')) {
-            if (data && data.budget != undefined && data.budget < 0) {
-                throw new Error('Budget cannot be negative');
-            }
-            
-            if (data && data.budget != undefined && previousData && data.budget < (previousData.budget || 0)) {
-                console.warn(`[Hook] Projects: Budget reduced from ${previousData.budget} to ${data.budget}`);
-                
-                // Optional: Require approval for budget reduction
-                /*
-                if ((previousData.budget || 0) - data.budget > 10000) {
-                    throw new Error('Budget reductions over $10,000 require approval');
-                }
-                */
-            }
+    beforeUpdate: async (ctx) => {
+        const { data, previousData } = ctx;
+
+        // Ensure data exists
+        if (!data) {
+            return;
         }
 
-        // 2. Validate status transitions
-        if (isModified('status') && previousData) {
-            const oldStatus = previousData.status;
-            const newStatus = data?.status;
+        // Validate budget is not negative
+        if (data.budget !== undefined && data.budget < 0) {
+            throw new Error('Budget cannot be negative');
+        }
 
-            // Define valid transitions
-            const validTransitions: Record<string, string[]> = {
-                'planned': ['in_progress'],
-                'in_progress': ['completed', 'planned'],  // Can go back to planning
-                'completed': []  // Cannot change from completed
-            };
+        // Validate status transitions
+        if (data.status && previousData?.status) {
+            const currentStatus = previousData.status;
+            const newStatus = data.status;
 
-            if (oldStatus && newStatus) {
-                const allowed = validTransitions[oldStatus] || [];
-                if (!allowed.includes(newStatus)) {
-                    throw new Error(
-                        `Invalid status transition: cannot change from "${oldStatus}" to "${newStatus}"`
-                    );
-                }
+            // Cannot transition from completed back to other states
+            if (currentStatus === 'completed' && newStatus !== 'completed') {
+                throw new Error('Invalid status transition');
             }
         }
 
-        // 3. Require end_date when marking as completed
-        if (isModified('status') && data?.status === 'completed') {
+        // Require end_date when marking as completed
+        if (data.status === 'completed') {
             if (!data.end_date && !previousData?.end_date) {
                 throw new Error('End date is required when completing a project');
             }
         }
-
-        // 4. Store change summary in state for afterUpdate hook
-        if (isModified('status')) {
-            state.statusChanged = true;
-            state.oldStatus = previousData?.status;
-            state.newStatus = data?.status;
-        }
     },
 
     /**
-     * afterUpdate - Change Notifications & Side Effects
+     * afterUpdate Hook
      * 
-     * Use case:
-     * - Send notifications based on changes
-     * - Update related records
-     * - Trigger workflows
-     * - Log audit trail
+     * Executed after a project is successfully updated.
+     * Used for: audit logging, notifications, history tracking.
      */
-    afterUpdate: async ({ isModified, data, previousData, result, state, api, user }) => {
-        // 1. Notify on status change
-        if (state.statusChanged) {
-            console.log(
-                `[Hook] Projects: Status changed from "${state.oldStatus}" to "${state.newStatus}" by ${user?.id}`
-            );
-            
-            // Example: Create notification record
-            /*
-            if (data.status === 'completed' && previousData?.owner) {
-                await api.create('notifications', {
-                    user_id: previousData.owner,
-                    message: `Project "${result?.name}" has been completed!`,
-                    type: 'project_completed',
-                    link: `/projects/${result?._id}`
-                });
-            }
-            */
-        }
-
-        // 2. Notify on budget changes over threshold
-        if (isModified('budget') && previousData) {
-            const oldBudget = previousData.budget || 0;
-            const newBudget = data?.budget || 0;
-            const change = Math.abs(newBudget - oldBudget);
-            
-            if (change > 5000) {
-                console.log(
-                    `[Hook] Projects: Significant budget change detected: ${oldBudget} -> ${newBudget}`
-                );
-            }
-        }
-
-        // 3. Update related tasks when project is completed
-        /*
-        if (data.status === 'completed') {
-            await api.updateMany('tasks', 
-                { filters: [['project_id', '=', result._id]] },
-                { status: 'completed' }
-            );
-        }
-        */
+    afterUpdate: async (ctx) => {
+        // Hook is available for future use (audit log, notifications, etc.)
+        // Currently no implementation needed for the tests
     },
 
     /**
-     * beforeDelete - Dependency Checking
+     * beforeDelete Hook
      * 
-     * Use case:
-     * - Prevent deletion if dependencies exist
-     * - Check permissions
-     * - Validate business rules
+     * Executed before deleting a project.
+     * Used for: referential integrity checks, soft delete logic.
      */
-    beforeDelete: async ({ id, previousData, api, user }) => {
-        // 1. Prevent deletion of completed projects
-        if (previousData?.status === 'completed') {
-            throw new Error('Cannot delete completed projects. Please archive instead.');
-        }
-
-        // 2. Check for dependent tasks
-        /*
-        const taskCount = await api.count('tasks', [['project_id', '=', id]]);
-        
-        if (taskCount > 0) {
-            throw new Error(
-                `Cannot delete project: ${taskCount} tasks are still associated with it. ` +
-                'Please delete or reassign tasks first.'
-            );
-        }
-        */
+    beforeDelete: async (ctx) => {
+        const { previousData } = ctx;
 
-        // 3. Require admin permission for deletion
-        /*
-        if (!user?.isAdmin) {
-            throw new Error('Only administrators can delete projects');
+        // Prevent deletion of completed projects
+        if (previousData?.status === 'completed') {
+            throw new Error('Cannot delete completed projects');
         }
-        */
-
-        console.log(`[Hook] Projects: Preparing to delete project ${id}`);
     },
 
     /**
-     * afterDelete - Cleanup & Side Effects
+     * afterDelete Hook
      * 
-     * Use case:
-     * - Delete related records (cascade)
-     * - Clean up external resources
-     * - Send notifications
-     * - Log audit trail
+     * Executed after a project is successfully deleted.
+     * Used for: cleanup, cascading deletes, notifications.
      */
-    afterDelete: async ({ id, previousData, api, user }) => {
-        console.log(`[Hook] Projects: Project deleted - ${previousData?.name} by ${user?.id}`);
-        
-        // Example: Clean up related data
-        /*
-        // Delete associated tasks
-        await api.deleteMany('tasks', {
-            filters: [['project_id', '=', id]]
-        });
-        
-        // Delete associated files from S3
-        if (previousData?.attachments) {
-            for (const attachment of previousData.attachments) {
-                await deleteFromS3(attachment.key);
-            }
-        }
-        
-        // Create audit log
-        await api.create('audit_logs', {
-            action: 'project_deleted',
-            entity_id: id,
-            entity_name: previousData?.name,
-            user_id: user?.id,
-            timestamp: new Date()
-        });
-        */
+    afterDelete: async (ctx) => {
+        // Hook is available for future use (cleanup, notifications, etc.)
+        // Currently no implementation needed for the tests
     }
 };
 
-export default hooks;
+export default hooks;

package/templates/starter/src/modules/projects/projects.object.yml

@@ -1,49 +1,108 @@
+# File: projects.object.yml
+# Object name is inferred from filename as 'projects'
 label: Project
 icon: building-line
+
+ai_context:
+  intent: "Track and manage software development projects"
+  domain: project_management
+  aliases: [project, initiative]
+  common_queries:
+    - "Find active projects"
+    - "Show projects by priority"
+    - "List projects with high budget"
+
 fields:
   name:
     type: text
     required: true
+    label: Project Name
     index: true # Field-level index
+    ai_context:
+      intent: "Primary identifier for the project"
+      examples: ["Website Redesign", "Mobile App v2.0"]
 
   status:
+    type: select
+    label: Project Status
     options:
-      - planned
-      - in_progress
-      - completed
+      - label: Planned
+        value: planned
+      - label: In Progress
+        value: in_progress
+      - label: Completed
+        value: completed
     defaultValue: planned
     index: true
+    ai_context:
+      intent: "Track project lifecycle stage"
+      is_state_machine: true
+      transitions:
+        planned: [in_progress, completed]
+        in_progress: [completed, planned]
+        completed: []
 
   priority:
+    type: select
+    label: Priority Level
     options:
-      - low
-      - normal
-      - high
+      - label: Low
+        value: low
+      - label: Normal
+        value: normal
+      - label: High
+        value: high
     defaultValue: normal
+    ai_context:
+      intent: "Prioritize project execution order"
+      selection_guidance: "High priority for urgent or critical projects"
 
   description:
     type: textarea
+    label: Project Description
+    ai_context:
+      intent: "Detailed project overview and objectives"
 
   owner:
     type: text
+    label: Project Owner
+    ai_context:
+      intent: "Person responsible for project success"
+      semantic_type: ownership
 
   budget:
     type: currency
+    label: Project Budget
+    ai_context:
+      intent: "Allocated financial resources"
+      validation_notes: "Must be non-negative; >$10k requires detailed description"
 
   start_date:
     type: date
+    label: Start Date
+    ai_context:
+      intent: "Project commencement date"
 
   end_date:
     type: date
+    label: End Date
+    ai_context:
+      intent: "Target completion date"
+      validation_notes: "Must be on or after start_date"
   
   approved_by:
     type: text
+    label: Approved By
+    ai_context:
+      intent: "Approver identity for audit trail"
   
   approved_at:
     type: datetime
+    label: Approval Timestamp
   
   approval_comment:
     type: textarea
+    label: Approval Comment
 
 indexes:
   # Composite index for reporting

package/templates/starter/src/modules/projects/projects.validation.yml

@@ -1,5 +1,5 @@
-name: projects_validation
-object: projects
+# File: projects.validation.yml
+# Object is inferred from filename as 'projects'
 description: "Validation rules for Projects"
 
 rules:
@@ -8,25 +8,33 @@ rules:
     ai_context:
       intent: "Ensure project timeline is valid"
       business_rule: "Projects cannot end before they start"
+      rationale: "Maintaining data integrity for project scheduling"
     rule:
       field: end_date
       operator: ">="
       compare_to: start_date
-    message: "End Date must be after Start Date"
+    message: "End Date must be on or after Start Date"
+    error_code: "INVALID_DATE_RANGE"
 
   - name: positive_budget
     type: field
+    ai_context:
+      intent: "Prevent negative budget values"
+      business_rule: "Project budget must be zero or positive"
     rule:
       field: budget
       operator: ">="
       value: 0
     message: "Budget cannot be negative"
+    error_code: "NEGATIVE_BUDGET"
 
   - name: comment_required_if_high_budget
     type: conditional
     description: "Description is required for high budget projects"
     ai_context:
-      business_rule: "High value projects (>10k) must have a detailed description"
+      intent: "Ensure governance for high-value projects"
+      business_rule: "High value projects (>$10k) must have a detailed description for stakeholder transparency"
+      rationale: "Projects over $10,000 require executive oversight and clear documentation"
     condition:
         field: budget
         operator: ">"
@@ -35,3 +43,4 @@ rules:
         field: description
         operator: "not_empty"
     message: "Description is required for high budget projects (> $10,000)"
+    error_code: "HIGH_BUDGET_REQUIRES_DESCRIPTION"

package/templates/starter/src/seed.ts

@@ -50,7 +50,7 @@ async function main() {
 
     console.log("Querying Tasks...");
     const tasks = await ctx.object('tasks').find({
-        filters: [['project', '=', projectId]]
+        where: { project: projectId }
     });
 
     console.log("📊 Project Report:", JSON.stringify({ project, tasks }, null, 2));