dzql 0.5.3 → 0.5.5

package/docs/reference/api.md

@@ -368,6 +368,31 @@ jsonb_build_object('template_id', v_result.template_id, 'depends_on_template_id'
 jsonb_build_object('id', v_result.id)
 ```
 
+**API Usage with Composite Keys:**
+
+For entities with composite primary keys, the `get` and `delete` operations accept a JSONB object instead of an integer `id`:
+
+```javascript
+// Get by composite key
+const dependency = await ws.api.get.product_task_template_dependencies({
+  template_id: 1,
+  depends_on_template_id: 2
+});
+
+// Delete by composite key
+await ws.api.delete.product_task_template_dependencies({
+  template_id: 1,
+  depends_on_template_id: 2
+});
+
+// Or using explicit pk object
+await ws.api.delete.product_task_template_dependencies({
+  pk: { template_id: 1, depends_on_template_id: 2 }
+});
+```
+
+**Note:** Entities with simple `id` primary keys continue to use `{id: 1}` for backwards compatibility.
+
 ### Many-to-Many Relationships
 
 Configure M2M relationships via `graph_rules.many_to_many`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

package/src/compiler/codegen/operation-codegen.js

@@ -7,6 +7,8 @@ export class OperationCodegen {
   constructor(entity) {
     this.entity = entity;
     this.tableName = entity.tableName;
+    this.primaryKey = entity.primaryKey || ['id'];
+    this.isCompositePK = this.primaryKey.length > 1 || this.primaryKey[0] !== 'id';
   }
 
   /**
@@ -31,6 +33,49 @@ export class OperationCodegen {
     const m2mExpansionForGet = this._generateM2MExpansionForGet();
     const filterSensitiveFields = this._generateSensitiveFieldFilter();
 
+    // For composite PKs, accept JSONB containing all PK fields
+    // For simple PKs, accept INT for backwards compatibility
+    if (this.isCompositePK) {
+      const whereClause = this.primaryKey.map(col => `${col} = (p_pk->>'${col}')::int`).join(' AND ');
+      const pkDescription = this.primaryKey.join(', ');
+
+      return `-- GET operation for ${this.tableName} (composite primary key: ${pkDescription})
+CREATE OR REPLACE FUNCTION get_${this.tableName}(
+  p_user_id INT,
+  p_pk JSONB,
+  p_on_date TIMESTAMPTZ DEFAULT NULL
+) RETURNS JSONB AS $$
+DECLARE
+  v_result JSONB;
+  v_record ${this.tableName}%ROWTYPE;
+BEGIN
+  -- Fetch the record by composite primary key
+  SELECT * INTO v_record
+  FROM ${this.tableName}
+  WHERE ${whereClause}${this._generateTemporalFilter()};
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Record not found: % with pk=%', '${this.tableName}', p_pk;
+  END IF;
+
+  -- Convert to JSONB
+  v_result := to_jsonb(v_record);
+
+  -- Check view permission
+  IF NOT can_view_${this.tableName}(p_user_id, v_result) THEN
+    RAISE EXCEPTION 'Permission denied: view on ${this.tableName}';
+  END IF;
+
+${fkExpansions}
+${m2mExpansionForGet}
+${filterSensitiveFields}
+
+  RETURN v_result;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;`;
+    }
+
+    // Simple PK (id column) - original signature for backwards compatibility
     return `-- GET operation for ${this.tableName}
 CREATE OR REPLACE FUNCTION get_${this.tableName}(
   p_user_id INT,
@@ -177,6 +222,56 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const notificationSQL = this._generateNotificationSQL('delete');
     const filterSensitiveFields = this._generateSensitiveFieldFilter('v_output');
 
+    // For composite PKs, accept JSONB containing all PK fields
+    if (this.isCompositePK) {
+      const whereClause = this.primaryKey.map(col => `${col} = (p_pk->>'${col}')::int`).join(' AND ');
+      const pkDescription = this.primaryKey.join(', ');
+
+      const deleteSQL = this.entity.softDelete
+        ? `UPDATE ${this.tableName} SET deleted_at = NOW() WHERE ${whereClause} RETURNING * INTO v_result;`
+        : `DELETE FROM ${this.tableName} WHERE ${whereClause} RETURNING * INTO v_result;`;
+
+      return `-- DELETE operation for ${this.tableName} (composite primary key: ${pkDescription})
+CREATE OR REPLACE FUNCTION delete_${this.tableName}(
+  p_user_id INT,
+  p_pk JSONB
+) RETURNS JSONB AS $$
+DECLARE
+  v_result ${this.tableName}%ROWTYPE;
+  v_output JSONB;
+  v_notify_users INT[];
+BEGIN
+  -- Fetch record first by composite primary key
+  SELECT * INTO v_result
+  FROM ${this.tableName}
+  WHERE ${whereClause};
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Record not found: % with pk=%', '${this.tableName}', p_pk;
+  END IF;
+
+  -- Check delete permission
+  IF NOT can_delete_${this.tableName}(p_user_id, to_jsonb(v_result)) THEN
+    RAISE EXCEPTION 'Permission denied: delete on ${this.tableName}';
+  END IF;
+
+${graphRulesCall}
+
+  -- Perform delete
+  ${deleteSQL}
+
+${notificationSQL}
+
+  -- Prepare output (removing sensitive fields)
+  v_output := to_jsonb(v_result);
+${filterSensitiveFields}
+
+  RETURN v_output;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;`;
+    }
+
+    // Simple PK (id column) - original signature for backwards compatibility
     const deleteSQL = this.entity.softDelete
       ? `UPDATE ${this.tableName} SET deleted_at = NOW() WHERE id = p_id RETURNING * INTO v_result;`
       : `DELETE FROM ${this.tableName} WHERE id = p_id RETURNING * INTO v_result;`;

package/src/compiler/codegen/permission-codegen.js

@@ -171,55 +171,62 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
 
   /**
    * Generate traversal check: @org_id->acts_for[org_id=$]{active}.user_id
+   * Supports multi-hop paths like: @product_id->products.organisation_id->acts_for[organisation_id=$].user_id
    * @private
    */
   _generateTraversalCheck(ast) {
     const steps = ast.steps;
 
-    // Extract components from the path
-    let sourceField = null;
-    let targetTable = null;
-    let targetField = null;
-    let filters = [];
-    let temporal = false;
-
-    for (const step of steps) {
-      if (step.type === 'field_ref') {
-        if (!sourceField) {
-          // First field reference is the source
-          sourceField = step.field;
-        } else {
-          // Last field reference is the target
-          targetField = step.field;
-        }
-      } else if (step.type === 'table_ref') {
-        targetTable = step.table;
+    // First step should be the source field reference
+    if (steps.length === 0 || steps[0].type !== 'field_ref') {
+      return 'false';
+    }
 
-        // Collect filter conditions
-        if (step.filter) {
-          filters = step.filter;
-        }
+    const sourceField = steps[0].field;
 
-        // Check for temporal marker
-        if (step.temporal) {
-          temporal = true;
-        }
+    // Collect all table_ref steps (these are the hops)
+    const tableSteps = steps.filter(s => s.type === 'table_ref');
 
-        // Get target field if specified in table ref
-        if (step.targetField) {
-          targetField = step.targetField;
-        }
+    if (tableSteps.length === 0) {
+      return 'false';
+    }
+
+    // Build the value expression that resolves through intermediate tables
+    // Start with the record's source field
+    let valueExpr = `(p_record->>'${sourceField}')::int`;
+
+    // Process intermediate hops (all but the last table_ref)
+    // Each intermediate hop needs a subquery to resolve to the next field
+    for (let i = 0; i < tableSteps.length - 1; i++) {
+      const hop = tableSteps[i];
+      const table = hop.table;
+      const targetField = hop.targetField;
+
+      if (!targetField) {
+        // If no target field specified, assume 'id' for the lookup
+        // This shouldn't normally happen in well-formed paths
+        continue;
       }
+
+      // Build subquery: (SELECT targetField FROM table WHERE id = previousValue)
+      valueExpr = `(SELECT ${targetField} FROM ${table} WHERE id = ${valueExpr})`;
     }
 
-    // Build WHERE conditions
+    // The last table_ref is where we do the EXISTS check
+    const finalStep = tableSteps[tableSteps.length - 1];
+    const targetTable = finalStep.table;
+    const targetField = finalStep.targetField;
+    const filters = finalStep.filter || [];
+    const temporal = finalStep.temporal || false;
+
+    // Build WHERE conditions for the final EXISTS query
     const conditions = [];
 
     // Add filter conditions
     for (const filter of filters) {
       if (filter.operator === '=' && filter.value.type === 'param') {
-        // field=$ means match the record's field value
-        conditions.push(`${targetTable}.${filter.field} = (p_record->>'${sourceField}')::int`);
+        // field=$ means match the resolved value from the path
+        conditions.push(`${targetTable}.${filter.field} = ${valueExpr}`);
       } else if (filter.operator === '=') {
         const value = this._formatValue(filter.value);
         conditions.push(`${targetTable}.${filter.field} = ${value}`);
@@ -228,9 +235,6 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
 
     // Add temporal condition
     if (temporal) {
-      // Add temporal filtering for {active} marker
-      // Assumes standard field names: valid_from and valid_to
-      // This matches the interpreter's behavior in resolve_path_segment (002_functions.sql:316)
       conditions.push(`${targetTable}.valid_from <= NOW()`);
       conditions.push(`(${targetTable}.valid_to > NOW() OR ${targetTable}.valid_to IS NULL)`);
     }

package/src/server/db.js

@@ -179,6 +179,20 @@ export async function setupListeners(callback) {
   }
 }
 
+// Helper to detect if args contains a composite primary key (pk object or multiple PK fields, no 'id')
+function isCompositePK(args) {
+  // If args has a 'pk' object, it's explicitly a composite PK call
+  if (args.pk && typeof args.pk === 'object') {
+    return true;
+  }
+  // If args has no 'id' field but has other fields, assume composite PK
+  // (the compiled function will validate the actual PK fields)
+  if (args.id === undefined && Object.keys(args).length > 0) {
+    return true;
+  }
+  return false;
+}
+
 // DZQL Generic Operations - Try compiled functions first, fall back to generic_exec
 export async function callDZQLOperation(operation, entity, args, userId) {
   dbLogger.trace(`DZQL ${operation}.${entity} for user ${userId}`);
@@ -189,9 +203,9 @@ export async function callDZQLOperation(operation, entity, args, userId) {
     // Try compiled function first
     // Different operations have different signatures:
     // - search: search_entity(p_user_id, p_filters, p_search, p_sort, p_page, p_limit)
-    // - get: get_entity(p_user_id, p_id, p_on_date)
+    // - get: get_entity(p_user_id, p_id, p_on_date) OR get_entity(p_user_id, p_pk, p_on_date) for composite PKs
     // - save: save_entity(p_user_id, p_data, p_on_date)
-    // - delete: delete_entity(p_user_id, p_id)
+    // - delete: delete_entity(p_user_id, p_id) OR delete_entity(p_user_id, p_pk) for composite PKs
     // - lookup: lookup_entity(p_user_id, p_term, p_limit)
 
     if (operation === 'search') {
@@ -207,6 +221,15 @@ export async function callDZQLOperation(operation, entity, args, userId) {
       `, [userId, filters, search, sort, page, limit]);
       return result[0].result;
     } else if (operation === 'get') {
+      // Support composite primary keys: pass pk object or full args as JSONB
+      if (isCompositePK(args)) {
+        const pk = args.pk || args;  // Use explicit pk object or treat all args as PK fields
+        const result = await sql.unsafe(`
+          SELECT ${compiledFunctionName}($1::int, $2::jsonb, NULL) as result
+        `, [userId, pk]);
+        return result[0].result;
+      }
+      // Simple PK (id)
       const result = await sql.unsafe(`
         SELECT ${compiledFunctionName}($1::int, $2::int, NULL) as result
       `, [userId, args.id]);
@@ -217,6 +240,15 @@ export async function callDZQLOperation(operation, entity, args, userId) {
       `, [userId, args]);
       return result[0].result;
     } else if (operation === 'delete') {
+      // Support composite primary keys: pass pk object or full args as JSONB
+      if (isCompositePK(args)) {
+        const pk = args.pk || args;  // Use explicit pk object or treat all args as PK fields
+        const result = await sql.unsafe(`
+          SELECT ${compiledFunctionName}($1::int, $2::jsonb) as result
+        `, [userId, pk]);
+        return result[0].result;
+      }
+      // Simple PK (id)
       const result = await sql.unsafe(`
         SELECT ${compiledFunctionName}($1::int, $2::int) as result
       `, [userId, args.id]);