dzql 0.2.3 → 0.3.1

package/docs/reference/api.md

@@ -235,7 +235,8 @@ SELECT dzql.register_entity(
   p_temporal_fields JSONB DEFAULT '{}'::jsonb,
   p_notification_paths JSONB DEFAULT '{}'::jsonb,
   p_permission_paths JSONB DEFAULT '{}'::jsonb,
-  p_graph_rules JSONB DEFAULT '{}'::jsonb
+  p_graph_rules JSONB DEFAULT '{}'::jsonb,
+  p_field_defaults JSONB DEFAULT '{}'::jsonb
 );
 ```
 
@@ -251,7 +252,8 @@ 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 |
+| `p_graph_rules` | JSONB | no | Automatic relationship management + M2M |
+| `p_field_defaults` | JSONB | no | Auto-populate fields on INSERT |
 
 ### FK Includes
 
@@ -302,7 +304,76 @@ const rights = await ws.api.get.contractor_rights({id: 1});
 const past = await ws.api.get.contractor_rights({id: 1, on_date: '2023-01-01'});
 ```
 
-### Example Registration
+### Field Defaults
+
+Auto-populate fields on INSERT with values or variables:
+
+```sql
+'{
+  "owner_id": "@user_id",     -- Current user ID
+  "created_by": "@user_id",   -- Current user ID
+  "created_at": "@now",       -- Current timestamp
+  "status": "draft"           -- Literal value
+}'
+```
+
+**Available variables:**
+- `@user_id` - Current user ID from `p_user_id`
+- `@now` - Current timestamp
+- `@today` - Current date
+- Literal values - Any JSON value (`"draft"`, `0`, `true`)
+
+**Behavior:**
+- Only applied on INSERT (not UPDATE)
+- Explicit values override defaults
+- Reduces client boilerplate
+
+See [Field Defaults Guide](../guides/field-defaults.md) for details.
+
+### Many-to-Many Relationships
+
+Configure M2M relationships via `graph_rules.many_to_many`:
+
+```sql
+'{
+  "many_to_many": {
+    "tags": {
+      "junction_table": "brand_tags",
+      "local_key": "brand_id",
+      "foreign_key": "tag_id",
+      "target_entity": "tags",
+      "id_field": "tag_ids",
+      "expand": false
+    }
+  }
+}'
+```
+
+**Client usage:**
+```javascript
+// Save with relationships in single call
+await api.save_brands({
+  data: {
+    name: "My Brand",
+    tag_ids: [1, 2, 3]  // Junction table synced atomically
+  }
+})
+
+// Response includes tag_ids array
+{ id: 5, name: "My Brand", tag_ids: [1, 2, 3] }
+```
+
+**Configuration:**
+- `junction_table` - Name of junction table
+- `local_key` - FK to this entity
+- `foreign_key` - FK to target entity
+- `target_entity` - Target table name
+- `id_field` - Field name for ID array
+- `expand` - Include full objects (default: false)
+
+See [Many-to-Many Guide](../guides/many-to-many.md) for details.
+
+### Example Registration (Basic)
 
 ```sql
 SELECT dzql.register_entity(
@@ -332,10 +403,83 @@ SELECT dzql.register_entity(
         }]
       }
     }
+  }',
+  '{}'                                   -- field defaults (none)
+);
+```
+
+### Example Registration (With All Features)
+
+```sql
+SELECT dzql.register_entity(
+  'resources',
+  'title',
+  ARRAY['title', 'description'],
+  '{"org": "organisations"}',            -- FK includes
+  false,                                 -- soft delete
+  '{}',                                  -- temporal
+  '{}',                                  -- notifications
+  '{                                     -- permissions
+    "view": [],
+    "create": [],
+    "update": ["@owner_id"],
+    "delete": ["@owner_id"]
+  }',
+  '{                                     -- graph rules
+    "many_to_many": {
+      "tags": {
+        "junction_table": "resource_tags",
+        "local_key": "resource_id",
+        "foreign_key": "tag_id",
+        "target_entity": "tags",
+        "id_field": "tag_ids",
+        "expand": false
+      },
+      "collaborators": {
+        "junction_table": "resource_collaborators",
+        "local_key": "resource_id",
+        "foreign_key": "user_id",
+        "target_entity": "users",
+        "id_field": "collaborator_ids",
+        "expand": true
+      }
+    }
+  }',
+  '{                                     -- field defaults
+    "owner_id": "@user_id",
+    "created_by": "@user_id",
+    "created_at": "@now",
+    "status": "draft"
   }'
 );
 ```
 
+**Client usage:**
+```javascript
+// Single call with all features!
+const resource = await api.save_resources({
+  data: {
+    title: "My Resource",
+    tag_ids: [1, 2, 3],
+    collaborator_ids: [10, 20]
+    // owner_id, created_by, created_at, status auto-populated
+  }
+})
+
+// Response
+{
+  id: 1,
+  title: "My Resource",
+  owner_id: 123,              // From field defaults
+  created_by: 123,            // From field defaults
+  created_at: "2025-11-20...", // From field defaults
+  status: "draft",            // From field defaults
+  tag_ids: [1, 2, 3],         // M2M IDs
+  collaborator_ids: [10, 20], // M2M IDs
+  collaborators: [...]        // Full objects (expand: true)
+}
+```
+
 ---
 
 ## Search Operators

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -22,7 +22,7 @@
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.2.3...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.1...'"
   },
   "dependencies": {
     "jose": "^6.1.0",

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

@@ -28,6 +28,7 @@ export class OperationCodegen {
    */
   generateGetFunction() {
     const fkExpansions = this._generateFKExpansions();
+    const m2mExpansionForGet = this._generateM2MExpansionForGet();
     const filterSensitiveFields = this._generateSensitiveFieldFilter();
 
     return `-- GET operation for ${this.tableName}
@@ -58,6 +59,7 @@ BEGIN
   END IF;
 
 ${fkExpansions}
+${m2mExpansionForGet}
 ${filterSensitiveFields}
 
   RETURN v_result;
@@ -72,6 +74,10 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const graphRulesCall = this._generateGraphRulesCall();
     const notificationSQL = this._generateNotificationSQL();
     const filterSensitiveFields = this._generateSensitiveFieldFilter('v_output');
+    const m2mVariables = this._generateM2MVariableDeclarations();
+    const m2mExtraction = this._generateM2MExtraction();
+    const m2mSync = this._generateM2MSync();
+    const m2mExpansion = this._generateM2MExpansion();
 
     return `-- SAVE operation for ${this.tableName}
 CREATE OR REPLACE FUNCTION save_${this.tableName}(
@@ -84,7 +90,9 @@ DECLARE
   v_output JSONB;
   v_is_insert BOOLEAN := false;
   v_notify_users INT[];
+${m2mVariables}
 BEGIN
+${m2mExtraction}
   -- Determine if this is insert or update
   IF p_data->>'id' IS NULL THEN
     v_is_insert := true;
@@ -120,23 +128,32 @@ BEGIN
       FROM jsonb_each_text(p_data) kv(key, value)
     ) INTO v_result;
   ELSE
-    -- Dynamic UPDATE from JSONB
-    EXECUTE (
-      SELECT format(
-        'UPDATE ${this.tableName} SET %s WHERE id = %L RETURNING *',
-        string_agg(quote_ident(key) || ' = ' || quote_nullable(value), ', '),
-        (p_data->>'id')::int
-      )
-      FROM jsonb_each_text(p_data) kv(key, value)
-      WHERE key != 'id'
-    ) INTO v_result;
+    -- Dynamic UPDATE from JSONB (only if there are fields to update)
+    IF (SELECT COUNT(*) FROM jsonb_object_keys(p_data) WHERE jsonb_object_keys != 'id') > 0 THEN
+      EXECUTE (
+        SELECT format(
+          'UPDATE ${this.tableName} SET %s WHERE id = %L RETURNING *',
+          string_agg(quote_ident(key) || ' = ' || quote_nullable(value), ', '),
+          (p_data->>'id')::int
+        )
+        FROM jsonb_each_text(p_data) kv(key, value)
+        WHERE key != 'id'
+      ) INTO v_result;
+    ELSE
+      -- No fields to update (only M2M fields were provided), just fetch existing
+      v_result := v_existing;
+    END IF;
   END IF;
 
+${m2mSync}
+
+  -- Prepare output with M2M fields (BEFORE event creation for real-time notifications!)
+  v_output := to_jsonb(v_result);
+${m2mExpansion}
+
 ${graphRulesCall}
 ${notificationSQL}
 
-  -- Prepare output (removing sensitive fields)
-  v_output := to_jsonb(v_result);
 ${filterSensitiveFields}
 
   RETURN v_output;
@@ -233,6 +250,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
       `${field} ILIKE '%' || p_search || '%'`
     ).join(' OR ');
     const filterSensitiveFieldsArray = this._generateSensitiveFieldFilterArray();
+    const m2mSearchExpansion = this._generateM2MExpansionForSearch();
 
     return `-- SEARCH operation for ${this.tableName}
 CREATE OR REPLACE FUNCTION search_${this.tableName}(
@@ -311,8 +329,8 @@ BEGIN
 
   -- Get data
   EXECUTE format('
-    SELECT COALESCE(jsonb_agg(to_jsonb(t.*) ORDER BY %I %s), ''[]''::jsonb)
-    FROM ${this.tableName} t
+    SELECT COALESCE(jsonb_agg(${m2mSearchExpansion.selectExpression} ORDER BY %I %s), ''[]''::jsonb)
+    FROM ${this.tableName} t${m2mSearchExpansion.lateralJoins}
     WHERE %s
     LIMIT %L OFFSET %L
   ', v_sort_field, v_sort_order, v_where_clause, p_limit, v_offset) INTO v_data;
@@ -329,6 +347,251 @@ END;
 $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   }
 
+  /**
+   * Generate M2M variable declarations
+   * COMPILE TIME: Loop to generate static variable declarations
+   * RUNTIME: No loops, just variables
+   * @private
+   */
+  _generateM2MVariableDeclarations() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const declarations = [];
+
+    // COMPILE TIME LOOP: Generate separate variable for each M2M relationship
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+      declarations.push(`  v_${idField} INT[];  -- M2M: ${relationKey}`);
+    }
+
+    return declarations.join('\n');
+  }
+
+  /**
+   * Generate M2M extraction logic
+   * COMPILE TIME: Loop to generate code
+   * RUNTIME: Separate IF blocks (NO loops!)
+   * @private
+   */
+  _generateM2MExtraction() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const extractions = [];
+
+    // COMPILE TIME LOOP: Generate separate extraction block for each M2M
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+
+      // Each M2M gets its own static IF block (no runtime loops!)
+      extractions.push(`
+  -- Extract M2M field: ${idField} (${relationKey})
+  IF p_data ? '${idField}' THEN
+    v_${idField} := ARRAY(SELECT jsonb_array_elements_text(p_data->'${idField}')::int);
+    p_data := p_data - '${idField}';  -- Remove from data (not a table column)
+  END IF;`);
+    }
+
+    return extractions.join('');
+  }
+
+  /**
+   * Generate M2M junction table sync logic
+   * COMPILE TIME: Loop to generate code
+   * RUNTIME: Direct SQL execution (NO loops!)
+   * @private
+   */
+  _generateM2MSync() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const syncs = [];
+
+    // COMPILE TIME LOOP: Generate separate sync block for EACH relationship
+    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;
+
+      // Static SQL - all names known at compile time!
+      syncs.push(`
+  -- ============================================================================
+  -- M2M Sync: ${relationKey} (junction: ${junctionTable})
+  -- ============================================================================
+  IF v_${idField} IS NOT NULL THEN
+    -- Delete relationships not in new list
+    DELETE FROM ${junctionTable}
+    WHERE ${localKey} = v_result.id
+      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.id, unnest(v_${idField})
+      ON CONFLICT (${localKey}, ${foreignKey}) DO NOTHING;
+    END IF;
+  END IF;`);
+    }
+
+    return syncs.join('');
+  }
+
+  /**
+   * Generate M2M expansion in output (for SAVE function)
+   * COMPILE TIME: Loop to generate code
+   * RUNTIME: Direct SQL queries (NO loops!)
+   * Expands M2M fields into v_output BEFORE event creation (for real-time notifications)
+   * @private
+   */
+  _generateM2MExpansion() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const expansions = [];
+
+    // COMPILE TIME LOOP: Generate code for each M2M relationship
+    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;
+
+      // Always add ID array (static SQL) - use v_result.id since v_output is v_result as jsonb
+      expansions.push(`
+  -- Add M2M IDs: ${idField}
+  v_output := v_output || jsonb_build_object('${idField}',
+    (SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), '[]'::jsonb)
+     FROM ${junctionTable} WHERE ${localKey} = v_result.id)
+  );`);
+
+      // Conditionally expand full objects (known at compile time!)
+      if (expand) {
+        expansions.push(`
+  -- Expand M2M objects: ${relationKey} (expand=true)
+  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.id)
+  );`);
+      }
+    }
+
+    return expansions.join('');
+  }
+
+  /**
+   * Generate M2M expansion for SEARCH operation
+   * COMPILE TIME: Loop to generate LATERAL joins
+   * RUNTIME: Static joins (NO loops!)
+   * @private
+   */
+  _generateM2MExpansionForSearch() {
+    const manyToMany = this.entity.manyToMany || {};
+
+    if (Object.keys(manyToMany).length === 0) {
+      return {
+        lateralJoins: '',
+        selectExpression: 'to_jsonb(t.*)'
+      };
+    }
+
+    const lateralJoins = [];
+    const mergeExpressions = [];
+
+    // COMPILE TIME LOOP: Generate LATERAL join for each M2M relationship
+    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;
+
+      // LATERAL join for ID array (static SQL)
+      lateralJoins.push(`
+    LEFT JOIN LATERAL (
+      SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), ''[]''::jsonb) as ${idField}
+      FROM ${junctionTable}
+      WHERE ${localKey} = t.id
+    ) m2m_${idField} ON true`);
+
+      mergeExpressions.push(`jsonb_build_object(''${idField}'', m2m_${idField}.${idField})`);
+
+      // Optionally expand full objects
+      if (expand) {
+        lateralJoins.push(`
+    LEFT JOIN LATERAL (
+      SELECT COALESCE(jsonb_agg(to_jsonb(target.*) ORDER BY target.id), ''[]''::jsonb) as ${relationKey}
+      FROM ${junctionTable} jt
+      JOIN ${targetEntity} target ON target.id = jt.${foreignKey}
+      WHERE jt.${localKey} = t.id
+    ) m2m_${relationKey} ON true`);
+
+        mergeExpressions.push(`jsonb_build_object(''${relationKey}'', m2m_${relationKey}.${relationKey})`);
+      }
+    }
+
+    // Build the select expression that merges M2M fields
+    const selectExpression = mergeExpressions.length > 0
+      ? `to_jsonb(t.*) || ${mergeExpressions.join(' || ')}`
+      : 'to_jsonb(t.*)';
+
+    return {
+      lateralJoins: lateralJoins.join(''),
+      selectExpression
+    };
+  }
+
+  /**
+   * Generate M2M expansion for GET operation
+   * COMPILE TIME: Loop to generate code
+   * RUNTIME: Direct SQL queries (NO loops!)
+   * @private
+   */
+  _generateM2MExpansionForGet() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const expansions = [];
+
+    // COMPILE TIME LOOP: Generate code for each M2M relationship
+    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;
+
+      // Always add ID array (static SQL)
+      expansions.push(`
+  -- Add M2M IDs: ${idField}
+  v_result := v_result || jsonb_build_object('${idField}',
+    (SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), '[]'::jsonb)
+     FROM ${junctionTable} WHERE ${localKey} = v_record.id)
+  );`);
+
+      // Conditionally expand full objects (known at compile time!)
+      if (expand) {
+        expansions.push(`
+  -- Expand M2M objects: ${relationKey} (expand=true)
+  v_result := v_result || 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_record.id)
+  );`);
+      }
+    }
+
+    return expansions.join('');
+  }
+
   /**
    * Generate FK expansions for GET
    * @private
@@ -460,10 +723,10 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
 
     if (operation === 'save') {
       return `
-  -- Resolve notification recipients
-  ${hasNotificationPaths ? `v_notify_users := _resolve_notification_paths_${this.tableName}(p_user_id, to_jsonb(v_result));` : 'v_notify_users := ARRAY[]::INT[];'}
+  -- Resolve notification recipients (use v_output with M2M fields!)
+  ${hasNotificationPaths ? `v_notify_users := _resolve_notification_paths_${this.tableName}(p_user_id, v_output);` : 'v_notify_users := ARRAY[]::INT[];'}
 
-  -- Create event for real-time notifications
+  -- Create event for real-time notifications (v_output includes M2M fields!)
   INSERT INTO dzql.events (
     table_name,
     op,
@@ -477,7 +740,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     CASE WHEN v_is_insert THEN 'insert' ELSE 'update' END,
     jsonb_build_object('id', v_result.id),
     CASE WHEN NOT v_is_insert THEN to_jsonb(v_existing) ELSE NULL END,
-    to_jsonb(v_result),
+    v_output,
     p_user_id,
     v_notify_users
   );`;

package/src/compiler/compiler.js

@@ -3,7 +3,7 @@
  * Main compiler class that orchestrates parsing and code generation
  */
 
-import { EntityParser } from './parser/entity-parser.js';
+import { EntityParser, parseEntitiesFromSQL } from './parser/entity-parser.js';
 import { SubscribableParser } from './parser/subscribable-parser.js';
 import { generatePermissionFunctions } from './codegen/permission-codegen.js';
 import { generateOperations } from './codegen/operation-codegen.js';
@@ -65,6 +65,12 @@ export class DZQLCompiler {
       sections.push(this._generateGraphRuleFunctions(normalizedEntity));
     }
 
+    // Custom functions (pass-through from entity definition)
+    if (normalizedEntity.customFunctions &&
+        normalizedEntity.customFunctions.length > 0) {
+      sections.push(this._generateCustomFunctionsSection(normalizedEntity));
+    }
+
     // Combine all sections
     const sql = sections.join('\n\n');
 
@@ -180,9 +186,10 @@ export class DZQLCompiler {
    * @returns {Object} Compilation results
    */
   compileFromSQL(sqlContent) {
-    const registerCalls = sqlContent.match(/dzql\.register_entity\s*\([\s\S]*?\);/gi);
+    // Use parseEntitiesFromSQL to properly extract custom functions
+    const entities = parseEntitiesFromSQL(sqlContent);
 
-    if (!registerCalls) {
+    if (entities.length === 0) {
       return {
         results: [],
         errors: [],
@@ -190,16 +197,6 @@ export class DZQLCompiler {
       };
     }
 
-    const entities = [];
-    for (const call of registerCalls) {
-      try {
-        const entity = this.parser.parseFromSQL(call);
-        entities.push(entity);
-      } catch (error) {
-        console.warn('Failed to parse entity:', error.message);
-      }
-    }
-
     return this.compileAll(entities);
   }
 
@@ -258,6 +255,19 @@ export class DZQLCompiler {
     );
   }
 
+  /**
+   * Generate custom functions section (pass-through from entity definition)
+   * @private
+   */
+  _generateCustomFunctionsSection(entity) {
+    const header = `-- ============================================================================
+-- Custom Functions for: ${entity.tableName}
+-- Pass-through from entity definition
+-- ============================================================================`;
+
+    return header + '\n\n' + entity.customFunctions.join('\n\n');
+  }
+
   /**
    * Calculate SHA-256 checksum of SQL
    * @private