dzql 0.5.2 → 0.5.4

package/docs/compiler/README.md

@@ -87,6 +87,23 @@ SELECT dzql.register_entity(
 
 See [Many-to-Many Guide](../guides/many-to-many.md) for details.
 
+### Composite Primary Keys
+```sql
+SELECT dzql.register_entity(
+  'product_task_template_dependencies', 'template_id', ARRAY[]::text[],
+  '{}', false, '{}', '{}', '{}',
+  '{
+    "primary_key": ["template_id", "depends_on_template_id"]
+  }',
+  '{}'
+);
+```
+
+**Generated code:** Event records use all primary key columns
+- Default assumes `id` column
+- Composite keys generate `jsonb_build_object('col1', v_result.col1, 'col2', v_result.col2)`
+- Required for junction tables and other composite PK scenarios
+
 ### Field Defaults
 ```sql
 '{

package/docs/reference/api.md

@@ -252,9 +252,14 @@ SELECT dzql.register_entity(
 | `p_temporal_fields` | JSONB | no | Temporal field config (valid_from/valid_to) |
 | `p_notification_paths` | JSONB | no | Who receives real-time updates |
 | `p_permission_paths` | JSONB | no | CRUD permission rules |
-| `p_graph_rules` | JSONB | no | Automatic relationship management + M2M |
+| `p_graph_rules` | JSONB | no | Automatic relationship management, M2M, and primary_key |
 | `p_field_defaults` | JSONB | no | Auto-populate fields on INSERT |
 
+**Note:** `p_graph_rules` can include:
+- `primary_key` - Array of column names for composite primary keys (default: `["id"]`)
+- `many_to_many` - M2M relationship configurations
+- `on_create`, `on_update`, `on_delete` - Graph rule triggers
+
 ### FK Includes
 
 Configure which foreign keys to dereference in GET operations:
@@ -330,6 +335,64 @@ Auto-populate fields on INSERT with values or variables:
 
 See [Field Defaults Guide](../guides/field-defaults.md) for details.
 
+### Composite Primary Keys
+
+For tables with composite primary keys (not just `id`), specify the primary key columns via `graph_rules.primary_key`:
+
+```sql
+'{
+  "primary_key": ["template_id", "depends_on_template_id"]
+}'
+```
+
+**Or in JavaScript:**
+```javascript
+{
+  tableName: "product_task_template_dependencies",
+  primaryKey: ["template_id", "depends_on_template_id"],
+  // ...
+}
+```
+
+**Default:** `["id"]` - assumes a single `id` column as primary key.
+
+**Why this matters:** The compiler generates event records with a `pk` field containing the primary key values. Without this configuration, tables with composite primary keys would fail with "record has no field id" errors.
+
+**Generated SQL (composite):**
+```sql
+jsonb_build_object('template_id', v_result.template_id, 'depends_on_template_id', v_result.depends_on_template_id)
+```
+
+**Generated SQL (simple, default):**
+```sql
+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.2",
+  "version": "0.5.4",
   "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/graph-rules-codegen.js

@@ -4,9 +4,10 @@
  */
 
 export class GraphRulesCodegen {
-  constructor(tableName, graphRules) {
+  constructor(tableName, graphRules, primaryKey = ['id']) {
     this.tableName = tableName;
     this.graphRules = graphRules;
+    this.primaryKey = Array.isArray(primaryKey) ? primaryKey : [primaryKey];
   }
 
   /**
@@ -233,6 +234,20 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   PERFORM ${functionName}(${paramSQL});`;
   }
 
+  /**
+   * Generate jsonb_build_object for primary key columns from a JSONB record variable
+   * Supports composite primary keys
+   * @param {string} recordVar - The JSONB record variable name (e.g., 'p_record')
+   * @private
+   */
+  _generatePKBuildObject(recordVar = 'p_record') {
+    // Build jsonb_build_object with all primary key columns
+    // e.g., jsonb_build_object('id', (p_record->>'id')::int)
+    // or    jsonb_build_object('template_id', (p_record->>'template_id')::int, 'depends_on_template_id', (p_record->>'depends_on_template_id')::int)
+    const pairs = this.primaryKey.map(col => `'${col}', (${recordVar}->>'${col}')::int`);
+    return `jsonb_build_object(${pairs.join(', ')})`;
+  }
+
   /**
    * Generate NOTIFY action
    * Creates an event that will be broadcast to specified users
@@ -298,6 +313,8 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
       ? `jsonb_build_object(${dataFields.join(', ')})`
       : "'{}'::jsonb";
 
+    const pkBuildObject = this._generatePKBuildObject('p_record');
+
     return `${comment}
   -- Create notification event
   INSERT INTO dzql.events (
@@ -310,7 +327,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   ) VALUES (
     '${this.tableName}',
     'notify',
-    jsonb_build_object('id', (p_record->>'id')::int),
+    ${pkBuildObject},
     ${dataSQL},
     p_user_id,
     ${userIdSQL}
@@ -407,9 +424,10 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
  * Generate graph rule functions for an entity
  * @param {string} tableName - Table name
  * @param {Object} graphRules - Graph rules object
+ * @param {Array<string>} primaryKey - Primary key column(s) (defaults to ['id'])
  * @returns {string} SQL for graph rule functions
  */
-export function generateGraphRuleFunctions(tableName, graphRules) {
-  const codegen = new GraphRulesCodegen(tableName, graphRules);
+export function generateGraphRuleFunctions(tableName, graphRules, primaryKey = ['id']) {
+  const codegen = new GraphRulesCodegen(tableName, graphRules, primaryKey);
   return codegen.generate();
 }

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;`;
@@ -855,12 +950,29 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     return calls.join('');
   }
 
+  /**
+   * Generate jsonb_build_object for primary key columns
+   * Supports composite primary keys by building an object with all pk columns
+   * @param {string} recordVar - The record variable name (e.g., 'v_result', 'v_existing')
+   * @private
+   */
+  _generatePKBuildObject(recordVar = 'v_result') {
+    const primaryKey = this.entity.primaryKey || ['id'];
+
+    // Build jsonb_build_object with all primary key columns
+    // e.g., jsonb_build_object('id', v_result.id)
+    // or    jsonb_build_object('template_id', v_result.template_id, 'depends_on_template_id', v_result.depends_on_template_id)
+    const pairs = primaryKey.map(col => `'${col}', ${recordVar}.${col}`);
+    return `jsonb_build_object(${pairs.join(', ')})`;
+  }
+
   /**
    * Generate notification SQL
    * @private
    */
   _generateNotificationSQL(operation = 'save') {
     const hasNotificationPaths = this.entity.notificationPaths && Object.keys(this.entity.notificationPaths).length > 0;
+    const pkBuildObject = this._generatePKBuildObject('v_result');
 
     if (operation === 'save') {
       return `
@@ -878,7 +990,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   ) VALUES (
     '${this.tableName}',
     CASE WHEN v_is_insert THEN 'insert' ELSE 'update' END,
-    jsonb_build_object('id', v_result.id),
+    ${pkBuildObject},
     v_output,
     p_user_id,
     v_notify_users
@@ -899,7 +1011,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   ) VALUES (
     '${this.tableName}',
     'delete',
-    jsonb_build_object('id', v_result.id),
+    ${pkBuildObject},
     NULL,
     p_user_id,
     v_notify_users

package/src/compiler/compiler.js

@@ -258,7 +258,8 @@ export class DZQLCompiler {
   _generateGraphRuleFunctions(entity) {
     return generateGraphRuleFunctions(
       entity.tableName,
-      entity.graphRules
+      entity.graphRules,
+      entity.primaryKey
     );
   }
 

package/src/compiler/parser/entity-parser.js

@@ -95,6 +95,9 @@ export class EntityParser {
     // Extract many_to_many from graph_rules if present
     const manyToMany = graphRules.many_to_many || {};
 
+    // Extract primary_key from graph_rules if present (defaults to ['id'])
+    const primaryKey = graphRules.primary_key || ['id'];
+
     const config = {
       tableName: this._cleanString(params[0]),
       labelField: this._cleanString(params[1]),
@@ -106,7 +109,8 @@ export class EntityParser {
       permissionPaths: params[7] ? this._parseJSON(params[7]) : {},
       graphRules: graphRules,
       fieldDefaults: params[9] ? this._parseJSON(params[9]) : {},
-      manyToMany: manyToMany
+      manyToMany: manyToMany,
+      primaryKey: Array.isArray(primaryKey) ? primaryKey : [primaryKey]
     };
 
     return config;
@@ -328,6 +332,8 @@ export class EntityParser {
   parseFromObject(entity) {
     const graphRules = entity.graphRules || {};
     const manyToMany = entity.manyToMany || graphRules.many_to_many || {};
+    // Primary key can be specified directly on entity or in graphRules (defaults to ['id'])
+    const primaryKey = entity.primaryKey || graphRules.primary_key || ['id'];
 
     return {
       tableName: entity.tableName || entity.table,
@@ -341,6 +347,7 @@ export class EntityParser {
       graphRules: graphRules,
       fieldDefaults: entity.fieldDefaults || {},
       manyToMany: manyToMany,
+      primaryKey: Array.isArray(primaryKey) ? primaryKey : [primaryKey],
       customFunctions: entity.customFunctions || []
     };
   }

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]);