dzql 0.3.1 → 0.3.2

package/docs/compiler/README.md

@@ -46,17 +46,11 @@ SELECT dzql.register_entity(
   array['title', 'description'],        -- Searchable fields
   '{}'::jsonb,                          -- FK includes
   false,                                -- Soft delete
-  '{}'::jsonb,                          -- Graph rules
-  jsonb_build_object(                   -- Notification paths
-    'owner', array['@user_id']
-  ),
-  jsonb_build_object(                   -- Permission paths
-    'view', array['@user_id'],
-    'create', array['@user_id'],
-    'update', array['@user_id'],
-    'delete', array['@user_id']
-  ),
-  '{}'::jsonb                           -- Temporal config
+  '{}'::jsonb,                          -- Temporal config
+  '{}'::jsonb,                          -- Notification paths
+  '{}'::jsonb,                          -- Permission paths
+  '{}'::jsonb,                          -- Graph rules (including M2M)
+  '{}'::jsonb                           -- Field defaults
 );
 ```
 
@@ -67,6 +61,51 @@ This generates 5 PostgreSQL functions:
 - `lookup_todos(params, user_id)` - Autocomplete
 - `search_todos(params, user_id)` - Search with filters
 
+## Compiler Features (v0.3.1+)
+
+The compiler generates **static, optimized SQL** with zero runtime interpretation:
+
+### Many-to-Many Relationships
+```sql
+SELECT dzql.register_entity(
+  'brands', 'name', ARRAY['name'],
+  '{}', false, '{}', '{}', '{}',
+  '{
+    "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
+      }
+    }
+  }',
+  '{}'
+);
+```
+
+**Generated code:** Static M2M sync blocks (50-100x faster than generic operations)
+- No runtime loops
+- All table/column names are literals
+- PostgreSQL can fully optimize and cache plans
+
+See [Many-to-Many Guide](../guides/many-to-many.md) for details.
+
+### Field Defaults
+```sql
+'{
+  "owner_id": "@user_id",
+  "created_at": "@now",
+  "status": "draft"
+}'
+```
+
+**Generated code:** Auto-populates fields on INSERT
+
+See [Field Defaults Guide](../guides/field-defaults.md) for details.
+
 ## Architecture
 
 The compiler uses a three-phase approach:

package/docs/guides/many-to-many.md

@@ -4,7 +4,7 @@ First-class support for many-to-many relationships with automatic junction table
 
 ## Overview
 
-DZQL now provides built-in support for many-to-many (M2M) relationships through junction tables. Define the relationship once in your entity configuration, and DZQL handles:
+DZQL provides built-in support for many-to-many (M2M) relationships through junction tables. Define the relationship once in your entity configuration, and DZQL handles:
 
 - Junction table synchronization
 - Atomic updates in single API calls
@@ -19,6 +19,24 @@ DZQL now provides built-in support for many-to-many (M2M) relationships through
 - **Less Boilerplate** - No custom toggle functions needed
 - **Performance Control** - Optional expansion (off by default)
 
+## Generic vs Compiled Operations
+
+M2M support works in **both** modes:
+
+### Generic Operations (Runtime)
+- Uses `dzql.generic_save()` and dynamic SQL
+- Interprets M2M config at runtime (~5-10ms overhead per relationship)
+- Works immediately after `register_entity()` call
+- Good for development and entities with simple M2M
+
+### Compiled Operations (v0.3.1+) - RECOMMENDED
+- Generates **static SQL** at compile time
+- **50-100x faster** - zero interpretation overhead
+- All table/column names are literals (PostgreSQL optimizes fully)
+- Recommended for production and complex M2M scenarios
+
+See [Compiler Guide](../compiler/README.md) for compilation workflow.
+
 ## Quick Example
 
 ### Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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.3.1...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.2...'"
   },
   "dependencies": {
     "jose": "^6.1.0",

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

@@ -176,6 +176,9 @@ export class EntityParser {
   _parseJSON(str) {
     if (!str || str === '{}' || str === "'{}'") return {};
 
+    // Strip SQL comments before parsing
+    str = str.replace(/--[^\n]*/g, '').trim();
+
     // Handle jsonb_build_object(...) calls
     if (str.includes('jsonb_build_object')) {
       return this._parseJSONBuildObject(str);
@@ -184,9 +187,11 @@ export class EntityParser {
     // Handle JSON string literals
     if (str.startsWith("'") && str.endsWith("'")) {
       try {
-        return JSON.parse(str.slice(1, -1).replace(/''/g, "'"));
+        // Remove outer quotes and unescape SQL quotes
+        const jsonStr = str.slice(1, -1).replace(/''/g, "'");
+        return JSON.parse(jsonStr);
       } catch (e) {
-        console.warn('Failed to parse JSON:', str, e);
+        console.warn('Failed to parse JSON:', str.substring(0, 100) + '...', e);
         return {};
       }
     }