dzql 0.5.0 → 0.5.3

package/bin/cli.js

@@ -240,7 +240,7 @@ CREATE EXTENSION IF NOT EXISTS pgcrypto;
 
 -- Register new user
 -- p_options: optional JSON object with additional fields to set on the user record
-CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSONB DEFAULT NULL)
+CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
 RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -256,9 +256,10 @@ BEGIN
   v_hash := crypt(p_password, v_salt);
 
   -- Build insert data: options fields + email + password_hash
+  -- Cast p_options to JSONB for internal operations (JSON type is for API boundary convenience)
   v_insert_data := jsonb_build_object('email', p_email, 'password_hash', v_hash);
   IF p_options IS NOT NULL THEN
-    v_insert_data := (p_options - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
+    v_insert_data := (p_options::jsonb - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
   END IF;
 
   -- Dynamic INSERT from JSONB

package/docs/compiler/CODING_STANDARDS.md

@@ -72,6 +72,72 @@ CREATE FUNCTION lookup_users(p_user_id INT, p_filter TEXT, ...)
 CREATE FUNCTION search_users(p_user_id INT, p_filters JSONB, ...)
 ```
 
+## JSON vs JSONB for Function Parameters
+
+### External API Parameters: Use JSON
+
+When defining function parameters that accept JSON from external callers (API boundary), use `JSON` type (text-based) rather than `JSONB`. This allows callers to pass `JSON.stringify(options)` as a plain string without needing special serialization like `sql.json()`.
+
+```sql
+-- ✅ CORRECT - JSON for external input parameters
+CREATE FUNCTION register_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSON DEFAULT NULL  -- Accepts plain JSON string from API
+)
+
+-- ❌ WRONG - JSONB requires special serialization from clients
+CREATE FUNCTION register_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSONB DEFAULT NULL  -- Harder to call from JavaScript
+)
+```
+
+### Internal Operations: Cast to JSONB
+
+Inside the function, cast to JSONB if you need JSONB operators (`->`, `->>`, `-`, `||`, `?`, etc.):
+
+```sql
+CREATE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
+RETURNS JSONB AS $$
+DECLARE
+  v_insert_data JSONB;
+BEGIN
+  v_insert_data := jsonb_build_object('email', p_email);
+  
+  IF p_options IS NOT NULL THEN
+    -- Cast to JSONB for internal operations
+    v_insert_data := (p_options::jsonb - 'id' - 'password') || v_insert_data;
+  END IF;
+  
+  -- ...
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### Table Columns: Use JSONB
+
+Table columns should still use `JSONB` for efficient storage and indexing:
+
+```sql
+-- ✅ CORRECT - JSONB for table columns
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  metadata JSONB DEFAULT '{}'  -- Efficient storage & indexing
+);
+```
+
+### Summary
+
+| Context | Type | Reason |
+|---------|------|--------|
+| Function input parameters | `JSON` | Easy to pass from JavaScript (`JSON.stringify()`) |
+| Internal function operations | `::jsonb` cast | Access to JSONB operators |
+| Table columns | `JSONB` | Efficient storage and indexing |
+
+This pattern - **JSON for input parameters, JSONB for storage** - eliminates serialization confusion at the API boundary.
+
 ## Function Categories
 
 ### Public API Functions (No underscore)

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,39 @@ 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)
+```
+
 ### 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.0",
+  "version": "0.5.3",
   "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/auth-codegen.js

@@ -69,7 +69,7 @@ $$;`;
 -- p_options: optional JSON object with additional fields to set on the user record
 -- Example: register_user('test@example.com', 'password', '{"name": "Test User"}')
 -- ============================================================================
-CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSONB DEFAULT NULL)
+CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
 RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -85,9 +85,10 @@ BEGIN
   v_hash := crypt(p_password, v_salt);
 
   -- Build insert data: options fields + email + password_hash (options cannot override core fields)
+  -- Cast p_options to JSONB for internal operations (JSON type is for API boundary convenience)
   v_insert_data := jsonb_build_object('email', p_email, 'password_hash', v_hash);
   IF p_options IS NOT NULL THEN
-    v_insert_data := (p_options - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
+    v_insert_data := (p_options::jsonb - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
   END IF;
 
   -- Dynamic INSERT from JSONB (same pattern as compiled save functions)

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

@@ -855,12 +855,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 +895,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 +916,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 || []
     };
   }