dzql 0.5.22 → 0.5.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.22",
+  "version": "0.5.24",
   "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

@@ -11,6 +11,18 @@ export class OperationCodegen {
     this.isCompositePK = this.primaryKey.length > 1 || this.primaryKey[0] !== 'id';
   }
 
+  /**
+   * Determine appropriate type cast for a column name
+   * Only casts to int if column is 'id' or ends with '_id'
+   * @private
+   */
+  _getTypeCast(columnName) {
+    if (columnName === 'id' || columnName.endsWith('_id')) {
+      return '::int';
+    }
+    return '';
+  }
+
   /**
    * Generate all operation functions
    * @returns {string} SQL for all operations
@@ -36,7 +48,7 @@ export class OperationCodegen {
     // 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 whereClause = this.primaryKey.map(col => `${col} = (p_pk->>'${col}')${this._getTypeCast(col)}`).join(' AND ');
       const pkDescription = this.primaryKey.join(', ');
 
       return `-- GET operation for ${this.tableName} (composite primary key: ${pkDescription})
@@ -125,6 +137,21 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const m2mExpansion = this._generateM2MExpansion();
     const fieldDefaults = this._generateFieldDefaults();
 
+    // For composite PKs, generate a different function signature and logic
+    if (this.isCompositePK) {
+      return this._generateCompositePKSaveFunction({
+        graphRulesCall,
+        notificationSQL,
+        filterSensitiveFields,
+        m2mVariables,
+        m2mExtraction,
+        m2mSync,
+        m2mExpansion,
+        fieldDefaults
+      });
+    }
+
+    // Simple PK (id column) - original implementation for backwards compatibility
     return `-- SAVE operation for ${this.tableName}
 CREATE OR REPLACE FUNCTION save_${this.tableName}(
   p_user_id INT,
@@ -207,6 +234,141 @@ ${m2mExpansion}
 ${graphRulesCall}
 ${notificationSQL}
 
+${filterSensitiveFields}
+
+  RETURN v_output;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;`;
+  }
+
+  /**
+   * Generate SAVE function for composite primary keys
+   * @private
+   */
+  _generateCompositePKSaveFunction(helpers) {
+    const {
+      graphRulesCall,
+      notificationSQL,
+      filterSensitiveFields,
+      m2mVariables,
+      m2mExtraction,
+      m2mSync,
+      m2mExpansion,
+      fieldDefaults
+    } = helpers;
+
+    const pkDescription = this.primaryKey.join(', ');
+
+    // Generate WHERE clause for composite PK lookup
+    // e.g., "entity_type = (p_data->>'entity_type') AND entity_id = (p_data->>'entity_id')::int"
+    const whereClause = this.primaryKey.map(col => {
+      return `${col} = (p_data->>'${col}')${this._getTypeCast(col)}`;
+    }).join(' AND ');
+
+    // For use inside format() string literal with %L placeholders
+    // e.g., "entity_type = %L AND entity_id = %L"
+    const whereClauseForFormat = this.primaryKey.map(col => `${col} = %L`).join(' AND ');
+
+    // Format arguments for the WHERE clause (to be passed to format())
+    // e.g., "(p_data->>'entity_type'), (p_data->>'entity_id')::int"
+    const whereClauseFormatArgs = this.primaryKey.map(col => {
+      return `(p_data->>'${col}')${this._getTypeCast(col)}`;
+    }).join(', ');
+
+    // Check if all PK fields are present in p_data
+    const pkNullCheck = this.primaryKey.map(col => `p_data->>'${col}' IS NULL`).join(' OR ');
+
+    // Build the list of PK field names for exclusion from SET clause
+    const pkFieldsExclusion = this.primaryKey.map(col => `jsonb_object_keys != '${col}'`).join(' AND ');
+
+    // For M2M sync and expansion, we need to reference the PK fields from v_result
+    const m2mSyncCompositePK = this._generateM2MSyncCompositePK();
+    const m2mExpansionCompositePK = this._generateM2MExpansionCompositePK();
+    const m2mExpansionForBeforeCompositePK = this._generateM2MExpansionForBeforeCompositePK();
+
+    return `-- SAVE operation for ${this.tableName} (composite primary key: ${pkDescription})
+CREATE OR REPLACE FUNCTION save_${this.tableName}(
+  p_user_id INT,
+  p_data JSONB
+) RETURNS JSONB AS $$
+DECLARE
+  v_result ${this.tableName}%ROWTYPE;
+  v_existing ${this.tableName}%ROWTYPE;
+  v_output JSONB;
+  v_before JSONB;
+  v_is_insert BOOLEAN := false;
+  v_notify_users INT[];
+${m2mVariables}
+BEGIN
+${m2mExtraction}
+  -- Determine if this is insert or update (composite PK: ${pkDescription})
+  IF ${pkNullCheck} THEN
+    -- Missing one or more PK fields - this is an insert
+    v_is_insert := true;
+  ELSE
+    -- Try to fetch existing record by composite PK
+    SELECT * INTO v_existing
+    FROM ${this.tableName}
+    WHERE ${whereClause};
+
+    v_is_insert := NOT FOUND;
+  END IF;
+
+  -- Check permissions
+  IF v_is_insert THEN
+    IF NOT can_create_${this.tableName}(p_user_id, p_data) THEN
+      RAISE EXCEPTION 'Permission denied: create on ${this.tableName}';
+    END IF;
+  ELSE
+    IF NOT can_update_${this.tableName}(p_user_id, to_jsonb(v_existing)) THEN
+      RAISE EXCEPTION 'Permission denied: update on ${this.tableName}';
+    END IF;
+  END IF;
+
+  -- Expand M2M for existing record (for UPDATE events "before" field)
+  IF NOT v_is_insert THEN
+    v_before := to_jsonb(v_existing);
+${m2mExpansionForBeforeCompositePK}
+  END IF;
+${fieldDefaults}
+  -- Perform UPSERT
+  IF v_is_insert THEN
+    -- Dynamic INSERT from JSONB
+    EXECUTE (
+      SELECT format(
+        'INSERT INTO ${this.tableName} (%s) VALUES (%s) RETURNING *',
+        string_agg(quote_ident(key), ', '),
+        string_agg(quote_nullable(value), ', ')
+      )
+      FROM jsonb_each_text(p_data) kv(key, value)
+    ) INTO v_result;
+  ELSE
+    -- Dynamic UPDATE from JSONB (only if there are non-PK fields to update)
+    IF (SELECT COUNT(*) FROM jsonb_object_keys(p_data) WHERE ${pkFieldsExclusion}) > 0 THEN
+      EXECUTE (
+        SELECT format(
+          'UPDATE ${this.tableName} SET %s WHERE ${whereClauseForFormat} RETURNING *',
+          string_agg(quote_ident(key) || ' = ' || quote_nullable(value), ', '),
+          ${whereClauseFormatArgs}
+        )
+        FROM jsonb_each_text(p_data) kv(key, value)
+        WHERE ${this.primaryKey.map(col => `key != '${col}'`).join(' AND ')}
+      ) INTO v_result;
+    ELSE
+      -- No fields to update (only M2M fields were provided), just fetch existing
+      v_result := v_existing;
+    END IF;
+  END IF;
+
+${m2mSyncCompositePK}
+
+  -- Prepare output with M2M fields (BEFORE event creation for real-time notifications!)
+  v_output := to_jsonb(v_result);
+${m2mExpansionCompositePK}
+
+${graphRulesCall}
+${notificationSQL}
+
 ${filterSensitiveFields}
 
   RETURN v_output;
@@ -224,7 +386,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
 
     // 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 whereClause = this.primaryKey.map(col => `${col} = (p_pk->>'${col}')${this._getTypeCast(col)}`).join(' AND ');
       const pkDescription = this.primaryKey.join(', ');
 
       const deleteSQL = this.entity.softDelete
@@ -740,6 +902,129 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     return expansions.join('');
   }
 
+  /**
+   * Generate M2M sync for composite primary keys
+   * For tables with composite PKs, M2M relationships are rare but possible
+   * @private
+   */
+  _generateM2MSyncCompositePK() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    // For composite PKs, we need to build a composite key reference
+    // This is a rare case - most tables with composite PKs are junction tables themselves
+    const syncs = [];
+
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+      const junctionTable = config.junction_table;
+      const localKey = config.local_key;
+      const foreignKey = config.foreign_key;
+
+      // For composite PK tables with M2M, we'd need a different junction table structure
+      // This is an edge case - log a warning comment in the generated SQL
+      syncs.push(`
+  -- ============================================================================
+  -- M2M Sync: ${relationKey} (junction: ${junctionTable}) - COMPOSITE PK
+  -- Note: M2M on composite PK tables requires junction table to reference all PK columns
+  -- ============================================================================
+  IF v_${idField} IS NOT NULL THEN
+    -- Delete relationships not in new list (using first PK column as reference)
+    DELETE FROM ${junctionTable}
+    WHERE ${localKey} = v_result.${this.primaryKey[0]}
+      AND (${foreignKey} <> ALL(v_${idField}) OR v_${idField} = '{}');
+
+    -- Insert new relationships (idempotent)
+    IF array_length(v_${idField}, 1) > 0 THEN
+      INSERT INTO ${junctionTable} (${localKey}, ${foreignKey})
+      SELECT v_result.${this.primaryKey[0]}, unnest(v_${idField})
+      ON CONFLICT (${localKey}, ${foreignKey}) DO NOTHING;
+    END IF;
+  END IF;`);
+    }
+
+    return syncs.join('');
+  }
+
+  /**
+   * Generate M2M expansion for composite primary keys (for SAVE output)
+   * @private
+   */
+  _generateM2MExpansionCompositePK() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const expansions = [];
+
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+      const junctionTable = config.junction_table;
+      const localKey = config.local_key;
+      const foreignKey = config.foreign_key;
+      const targetEntity = config.target_entity;
+      const expand = config.expand || false;
+
+      // Use first PK column for M2M lookups
+      expansions.push(`
+  -- Add M2M IDs: ${idField} (composite PK table)
+  v_output := v_output || jsonb_build_object('${idField}',
+    (SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), '[]'::jsonb)
+     FROM ${junctionTable} WHERE ${localKey} = v_result.${this.primaryKey[0]})
+  );`);
+
+      if (expand) {
+        expansions.push(`
+  -- Expand M2M objects: ${relationKey} (expand=true, composite PK table)
+  v_output := v_output || jsonb_build_object('${relationKey}',
+    (SELECT COALESCE(jsonb_agg(to_jsonb(t.*) ORDER BY t.id), '[]'::jsonb)
+     FROM ${junctionTable} jt
+     JOIN ${targetEntity} t ON t.id = jt.${foreignKey}
+     WHERE jt.${localKey} = v_result.${this.primaryKey[0]})
+  );`);
+      }
+    }
+
+    return expansions.join('');
+  }
+
+  /**
+   * Generate M2M expansion for "before" record with composite primary keys
+   * @private
+   */
+  _generateM2MExpansionForBeforeCompositePK() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const expansions = [];
+
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+      const junctionTable = config.junction_table;
+      const localKey = config.local_key;
+      const foreignKey = config.foreign_key;
+      const targetEntity = config.target_entity;
+      const expand = config.expand || false;
+
+      expansions.push(`
+    v_before := v_before || jsonb_build_object('${idField}',
+      (SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), '[]'::jsonb)
+       FROM ${junctionTable} WHERE ${localKey} = v_existing.${this.primaryKey[0]})
+    );`);
+
+      if (expand) {
+        expansions.push(`
+    v_before := v_before || jsonb_build_object('${relationKey}',
+      (SELECT COALESCE(jsonb_agg(to_jsonb(t.*) ORDER BY t.id), '[]'::jsonb)
+       FROM ${junctionTable} jt
+       JOIN ${targetEntity} t ON t.id = jt.${foreignKey}
+       WHERE jt.${localKey} = v_existing.${this.primaryKey[0]})
+    );`);
+      }
+    }
+
+    return expansions.join('');
+  }
+
   /**
    * Generate FK expansions for GET
    * @private
@@ -1001,6 +1286,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   ${hasNotificationPaths ? `v_notify_users := _resolve_notification_paths_${this.tableName}(p_user_id, to_jsonb(v_result));` : 'v_notify_users := ARRAY[]::INT[];'}
 
   -- Create event for real-time notifications
+  -- Include full record data so _affected_documents can resolve subscription FKs
   INSERT INTO dzql.events (
     table_name,
     op,
@@ -1012,7 +1298,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     '${this.tableName}',
     'delete',
     ${pkBuildObject},
-    NULL,
+    to_jsonb(v_result),
     p_user_id,
     v_notify_users
   );`;

package/src/server/namespace.js

@@ -10,6 +10,7 @@ const DEFAULT_USER_ID = 1;
 
 /**
  * Discover available entities from dzql.entities table or compiled functions
+ * @returns {Promise<Object>} Map of entity name to {label, searchable, description}
  */
 async function discoverEntities() {
   // First try dzql.entities table (runtime mode)
@@ -58,6 +59,9 @@ async function discoverEntities() {
 /**
  * DZQL operations namespace - provides CLI-style access to DZQL operations
  *
+ * Each method outputs JSON to console and calls sql.end() before returning,
+ * making instances single-use. On error, methods call process.exit(1).
+ *
  * Usage in tasks.js:
  * ```js
  * import { DzqlNamespace } from 'dzql/namespace';
@@ -70,11 +74,17 @@ async function discoverEntities() {
  * ```
  */
 export class DzqlNamespace {
+  /**
+   * @param {number} [userId=1] - User ID for permission checks
+   */
   constructor(userId = DEFAULT_USER_ID) {
     this.userId = userId;
   }
 
-  /** List all available entities */
+  /**
+   * List all available entities
+   * @returns {Promise<void>} Outputs JSON to console
+   */
   async entities(c) {
     try {
       const entities = await discoverEntities();
@@ -89,7 +99,12 @@ export class DzqlNamespace {
     }
   }
 
-  /** Search an entity */
+  /**
+   * Search an entity
+   * @example invj dzql:search venues '{"query": "test"}'
+   * @param {string} entity - Entity/table name to search
+   * @param {string} [argsJson] - JSON string with search args (query, limit, offset, filters)
+   */
   async search(c, entity, argsJson = "{}") {
     if (!entity) {
       console.error("Error: entity name required");
@@ -123,7 +138,12 @@ export class DzqlNamespace {
     }
   }
 
-  /** Get entity by ID */
+  /**
+   * Get entity by ID
+   * @example invj dzql:get venues '{"id": 1}'
+   * @param {string} entity - Entity/table name
+   * @param {string} [argsJson] - JSON string with {id: number}
+   */
   async get(c, entity, argsJson = "{}") {
     if (!entity) {
       console.error("Error: entity name required");
@@ -155,7 +175,12 @@ export class DzqlNamespace {
     }
   }
 
-  /** Save (create or update) entity */
+  /**
+   * Save (create or update) entity
+   * @example invj dzql:save venues '{"name": "New Venue", "org_id": 1}'
+   * @param {string} entity - Entity/table name
+   * @param {string} [argsJson] - JSON string with entity data (include id to update, omit to create)
+   */
   async save(c, entity, argsJson = "{}") {
     if (!entity) {
       console.error("Error: entity name required");
@@ -189,7 +214,12 @@ export class DzqlNamespace {
     }
   }
 
-  /** Delete entity by ID */
+  /**
+   * Delete entity by ID
+   * @example invj dzql:delete venues '{"id": 1}'
+   * @param {string} entity - Entity/table name
+   * @param {string} [argsJson] - JSON string with {id: number}
+   */
   async delete(c, entity, argsJson = "{}") {
     if (!entity) {
       console.error("Error: entity name required");
@@ -221,7 +251,12 @@ export class DzqlNamespace {
     }
   }
 
-  /** Lookup entity (for dropdowns/autocomplete) */
+  /**
+   * Lookup entity (for dropdowns/autocomplete)
+   * @example invj dzql:lookup organisations '{"query": "acme"}'
+   * @param {string} entity - Entity/table name
+   * @param {string} [argsJson] - JSON string with {query: string, limit?: number}
+   */
   async lookup(c, entity, argsJson = "{}") {
     if (!entity) {
       console.error("Error: entity name required");