dzql 0.2.2 → 0.3.0

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.2",
+  "version": "0.3.0",
   "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.2...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.0...'"
   },
   "dependencies": {
     "jose": "^6.1.0",

package/src/client/ws.js

@@ -52,6 +52,7 @@ class WebSocketManager {
    *
    * @param {Object} [options={}] - Configuration options
    * @param {number} [options.maxReconnectAttempts=5] - Maximum reconnection attempts before giving up
+   * @param {string} [options.tokenName='dzql_token'] - Name of the localStorage key for JWT token
    */
   constructor(options = {}) {
     this.ws = null;
@@ -62,6 +63,7 @@ class WebSocketManager {
     this.subscriptions = new Map(); // subscription_id -> { callback, unsubscribe }
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+    this.tokenName = options.tokenName ?? 'dzql_token';
     this.isShuttingDown = false;
 
     // DZQL nested proxy API - matches server-side db.api pattern
@@ -265,7 +267,7 @@ class WebSocketManager {
 
       // Add JWT token as query parameter if available
       if (typeof localStorage !== 'undefined'){
-        const storedToken = localStorage.getItem("dzql_token");
+        const storedToken = localStorage.getItem(this.tokenName);
         if (storedToken) {
           wsUrl += `?token=${encodeURIComponent(storedToken)}`;
         }

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

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

@@ -7,18 +7,25 @@ export class EntityParser {
   /**
    * Parse a dzql.register_entity() call from SQL
    * @param {string} sql - SQL containing register_entity call
-   * @returns {Object} Parsed entity configuration
+   * @param {number} startOffset - Optional starting position in SQL
+   * @returns {Object} Parsed entity configuration with custom functions
    */
-  parseFromSQL(sql) {
+  parseFromSQL(sql, startOffset = 0) {
     // Extract the register_entity call
-    const registerMatch = sql.match(/dzql\.register_entity\s*\(([\s\S]*?)\);/i);
+    const searchSql = sql.substring(startOffset);
+    const registerMatch = searchSql.match(/dzql\.register_entity\s*\(([\s\S]*?)\);/i);
     if (!registerMatch) {
       throw new Error('No register_entity call found in SQL');
     }
 
     const params = this._parseParameters(registerMatch[1]);
+    const config = this._buildEntityConfig(params);
 
-    return this._buildEntityConfig(params);
+    // Extract custom functions after this register_entity call
+    const registerEndPos = startOffset + registerMatch.index + registerMatch[0].length;
+    config.customFunctions = this._extractCustomFunctions(sql, registerEndPos);
+
+    return config;
   }
 
   /**
@@ -73,6 +80,11 @@ export class EntityParser {
    * @private
    */
   _buildEntityConfig(params) {
+    const graphRules = params[8] ? this._parseJSON(params[8]) : {};
+
+    // Extract many_to_many from graph_rules if present
+    const manyToMany = graphRules.many_to_many || {};
+
     const config = {
       tableName: this._cleanString(params[0]),
       labelField: this._cleanString(params[1]),
@@ -82,7 +94,9 @@ export class EntityParser {
       temporalFields: params[5] ? this._parseJSON(params[5]) : {},
       notificationPaths: params[6] ? this._parseJSON(params[6]) : {},
       permissionPaths: params[7] ? this._parseJSON(params[7]) : {},
-      graphRules: params[8] ? this._parseJSON(params[8]) : {}
+      graphRules: graphRules,
+      fieldDefaults: params[9] ? this._parseJSON(params[9]) : {},
+      manyToMany: manyToMany
     };
 
     return config;
@@ -250,12 +264,56 @@ export class EntityParser {
     return cleaned === 'true' || cleaned === 't';
   }
 
+  /**
+   * Extract custom functions defined after register_entity() call
+   * @private
+   * @param {string} sql - Full SQL content
+   * @param {number} startPos - Position after register_entity call
+   * @returns {Array<string>} Array of custom function SQL statements
+   */
+  _extractCustomFunctions(sql, startPos) {
+    // Find the next register_entity call or end of file
+    const nextEntityMatch = sql.substring(startPos).match(/dzql\.register_entity\s*\(/i);
+    const endPos = nextEntityMatch ? startPos + nextEntityMatch.index : sql.length;
+
+    // Extract the SQL between this entity and the next
+    const customSql = sql.substring(startPos, endPos).trim();
+    if (!customSql) return [];
+
+    const functions = [];
+
+    // Extract CREATE [OR REPLACE] FUNCTION statements
+    // Match from CREATE to the final semicolon of the function (including $$ delimiters)
+    const functionPattern = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+[\s\S]*?(?:\$\$|\$[A-Za-z_][A-Za-z0-9_]*\$)\s*(?:LANGUAGE|;)[\s\S]*?;/gi;
+    let match;
+    while ((match = functionPattern.exec(customSql)) !== null) {
+      functions.push(match[0].trim());
+    }
+
+    // Extract INSERT INTO dzql.registry statements
+    const registryPattern = /INSERT\s+INTO\s+dzql\.registry\s+[\s\S]*?;/gi;
+    while ((match = registryPattern.exec(customSql)) !== null) {
+      functions.push(match[0].trim());
+    }
+
+    // Extract SELECT dzql.register_function() calls
+    const registerFunctionPattern = /SELECT\s+dzql\.register_function\s*\([\s\S]*?\)\s*;/gi;
+    while ((match = registerFunctionPattern.exec(customSql)) !== null) {
+      functions.push(match[0].trim());
+    }
+
+    return functions;
+  }
+
   /**
    * Parse entity definition from JS object (for programmatic use)
    * @param {Object} entity - Entity definition object
    * @returns {Object} Normalized entity configuration
    */
   parseFromObject(entity) {
+    const graphRules = entity.graphRules || {};
+    const manyToMany = entity.manyToMany || graphRules.many_to_many || {};
+
     return {
       tableName: entity.tableName || entity.table,
       labelField: entity.labelField || 'name',
@@ -265,7 +323,10 @@ export class EntityParser {
       temporalFields: entity.temporalFields || {},
       notificationPaths: entity.notificationPaths || {},
       permissionPaths: entity.permissionPaths || {},
-      graphRules: entity.graphRules || {}
+      graphRules: graphRules,
+      fieldDefaults: entity.fieldDefaults || {},
+      manyToMany: manyToMany,
+      customFunctions: entity.customFunctions || []
     };
   }
 }
@@ -279,17 +340,16 @@ export function parseEntitiesFromSQL(sql) {
   const parser = new EntityParser();
   const entities = [];
 
-  // Find all register_entity calls
-  const registerCalls = sql.match(/dzql\.register_entity\s*\([\s\S]*?\);/gi);
-
-  if (!registerCalls) {
-    return entities;
-  }
+  // Find all register_entity calls with their positions
+  const registerPattern = /dzql\.register_entity\s*\(/gi;
+  let match;
+  let currentPos = 0;
 
-  for (const call of registerCalls) {
+  while ((match = registerPattern.exec(sql)) !== null) {
     try {
-      const entity = parser.parseFromSQL(call);
+      const entity = parser.parseFromSQL(sql, match.index);
       entities.push(entity);
+      currentPos = match.index + 1; // Move past this match
     } catch (error) {
       console.warn('Failed to parse entity:', error.message);
     }

package/src/database/migrations/001_schema.sql

@@ -23,7 +23,9 @@ CREATE TABLE IF NOT EXISTS dzql.entities (
   temporal_fields jsonb DEFAULT '{}',    -- valid_from/valid_to field names for temporal filtering
   notification_paths jsonb DEFAULT '{}', -- paths to determine who gets notified
   permission_paths jsonb DEFAULT '{}',   -- paths to determine who has permission for operations
-  graph_rules jsonb DEFAULT '{}'         -- graph evolution rules for automatic relationship management
+  graph_rules jsonb DEFAULT '{}',        -- graph evolution rules for automatic relationship management
+  field_defaults jsonb DEFAULT '{}',     -- default values to auto-populate on INSERT
+  many_to_many jsonb DEFAULT '{}'        -- many-to-many relationship configurations
 );
 
 -- === Registry (allowlist of callable functions) ===

package/src/database/migrations/002_functions.sql

@@ -744,6 +744,11 @@ BEGIN
   -- Validate top-level trigger types
   FOR l_trigger_key, l_trigger_rules IN SELECT * FROM jsonb_each(p_rules)
   LOOP
+    -- Skip validation for many_to_many (different structure)
+    IF l_trigger_key = 'many_to_many' THEN
+      CONTINUE;
+    END IF;
+
     -- Check valid trigger types
     IF l_trigger_key NOT IN ('on_create', 'on_update', 'on_delete', 'on_field_change') THEN
       RAISE WARNING 'Invalid trigger type: %', l_trigger_key;