dzql 0.3.1 → 0.3.3

package/bin/cli.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env bun
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { DZQLCompiler } from '../src/compiler/compiler.js';
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+switch (command) {
+  case 'create':
+    console.log('🚧 Create command coming soon');
+    console.log(`Would create project: ${args[0]}`);
+    break;
+  case 'dev':
+    console.log('🚧 Dev command coming soon');
+    break;
+  case 'db:up':
+    console.log('🚧 Database commands coming soon');
+    break;
+  case 'compile':
+    await runCompile(args);
+    break;
+  case '--version':
+  case '-v':
+    const pkg = await import('../package.json', { assert: { type: 'json' } });
+    console.log(pkg.default.version);
+    break;
+  default:
+    console.log(`
+DZQL CLI
+
+Usage:
+  dzql create <app-name>     Create a new DZQL application
+  dzql dev                   Start development server
+  dzql db:up                 Start PostgreSQL database
+  dzql db:down               Stop PostgreSQL database
+  dzql compile <input>       Compile entity definitions to SQL
+  dzql --version             Show version
+
+Examples:
+  dzql create my-venue-app
+  dzql dev
+  dzql compile database/init_db/009_venues_domain.sql -o compiled/
+`);
+}
+
+async function runCompile(args) {
+  const options = {
+    output: './compiled',
+    verbose: false
+  };
+
+  // Parse args
+  let inputFile = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '-o' || arg === '--output') {
+      options.output = args[++i];
+    } else if (arg === '-v' || arg === '--verbose') {
+      options.verbose = true;
+    } else if (arg === '-h' || arg === '--help') {
+      console.log(`
+DZQL Compiler - Transform entity definitions into PostgreSQL functions
+
+Usage:
+  dzql compile <input-file> [options]
+
+Options:
+  -o, --output <dir>       Output directory (default: ./compiled)
+  -v, --verbose            Verbose output
+  -h, --help               Show this help message
+
+Examples:
+  dzql compile entities/venues.sql
+  dzql compile database/init_db/009_venues_domain.sql -o compiled/
+`);
+      return;
+    } else if (!inputFile) {
+      inputFile = arg;
+    }
+  }
+
+  if (!inputFile) {
+    console.error('Error: No input file specified');
+    console.log('Run "dzql compile --help" for usage information');
+    process.exit(1);
+  }
+
+  if (!existsSync(inputFile)) {
+    console.error(`Error: File not found: ${inputFile}`);
+    process.exit(1);
+  }
+
+  try {
+    console.log(`\n🔨 Compiling: ${inputFile}`);
+
+    // Read input file
+    const sqlContent = readFileSync(inputFile, 'utf-8');
+
+    // Compile
+    const compiler = new DZQLCompiler();
+    const result = compiler.compileFromSQL(sqlContent);
+
+    // Display results
+    console.log(`\n📊 Compilation Summary:`);
+    console.log(`   Total entities: ${result.summary.total}`);
+    console.log(`   Successful: ${result.summary.successful}`);
+    console.log(`   Failed: ${result.summary.failed}`);
+
+    if (result.errors.length > 0) {
+      console.log(`\n❌ Errors:`);
+      for (const error of result.errors) {
+        console.log(`   - ${error.entity}: ${error.error}`);
+      }
+    }
+
+    // Write output files
+    if (result.results.length > 0) {
+      // Ensure output directory exists
+      if (!existsSync(options.output)) {
+        mkdirSync(options.output, { recursive: true });
+      }
+
+      console.log(`\n📝 Writing compiled files to: ${options.output}`);
+
+      // Write core DZQL infrastructure
+      const coreSQL = `-- DZQL Core Schema and Events System
+
+CREATE SCHEMA IF NOT EXISTS dzql;
+
+-- Event Audit Table for real-time notifications
+CREATE TABLE IF NOT EXISTS dzql.events (
+  event_id bigserial PRIMARY KEY,
+  table_name text NOT NULL,
+  op text NOT NULL,              -- 'insert', 'update', 'delete'
+  pk jsonb NOT NULL,             -- primary key of affected record
+  before jsonb,                  -- old values (NULL for insert)
+  after jsonb,                   -- new values (NULL for delete)
+  user_id int,                   -- who made the change
+  notify_users int[],            -- who should be notified
+  at timestamptz DEFAULT now()   -- when the change occurred
+);
+
+CREATE INDEX IF NOT EXISTS dzql_events_table_pk_idx ON dzql.events (table_name, pk, at);
+CREATE INDEX IF NOT EXISTS dzql_events_event_id_idx ON dzql.events (event_id);
+
+-- Event notification trigger - sends real-time notifications via pg_notify
+CREATE OR REPLACE FUNCTION dzql.notify_event()
+RETURNS TRIGGER LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM pg_notify('dzql', jsonb_build_object(
+    'event_id', NEW.event_id,
+    'table', NEW.table_name,
+    'op', NEW.op,
+    'pk', NEW.pk,
+    'data', COALESCE(NEW.after, NEW.before),
+    'before', NEW.before,
+    'after', NEW.after,
+    'user_id', NEW.user_id,
+    'at', NEW.at,
+    'notify_users', NEW.notify_users
+  )::text);
+
+  RETURN NULL;
+END $$;
+
+DROP TRIGGER IF EXISTS dzql_events_notify ON dzql.events;
+CREATE TRIGGER dzql_events_notify
+  AFTER INSERT ON dzql.events
+  FOR EACH ROW EXECUTE FUNCTION dzql.notify_event();
+`;
+
+      writeFileSync(resolve(options.output, '000_dzql_core.sql'), coreSQL, 'utf-8');
+      console.log(`   ✓ 000_dzql_core.sql`);
+
+      // Extract schema SQL (everything before DZQL entity registrations)
+      const schemaSQL = sqlContent.split(/-- DZQL Entity Registrations|select dzql\.register_entity/i)[0].trim();
+      if (schemaSQL) {
+        writeFileSync(resolve(options.output, '001_schema.sql'), schemaSQL + '\n', 'utf-8');
+        console.log(`   ✓ 001_schema.sql`);
+      }
+
+      // Generate auth functions (required for WebSocket server)
+      const authSQL = `-- Authentication Functions
+-- Required for DZQL WebSocket server
+
+-- Enable pgcrypto extension for password hashing
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- Register new user
+CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+  user_id INT;
+  salt TEXT;
+  hash TEXT;
+BEGIN
+  -- Generate salt and hash password
+  salt := gen_salt('bf', 10);
+  hash := crypt(p_password, salt);
+
+  -- Insert user (assumes users table has: id, email, name, password_hash)
+  INSERT INTO users (email, name, password_hash)
+  VALUES (p_email, split_part(p_email, '@', 1), hash)
+  RETURNING id INTO user_id;
+
+  RETURN _profile(user_id);
+EXCEPTION
+  WHEN unique_violation THEN
+    RAISE EXCEPTION 'Email already exists' USING errcode = '23505';
+END $$;
+
+-- Login user
+CREATE OR REPLACE FUNCTION login_user(p_email TEXT, p_password TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+  user_record RECORD;
+BEGIN
+  SELECT id, email, name, password_hash
+  INTO user_record
+  FROM users
+  WHERE email = p_email;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Invalid credentials' USING errcode = '28000';
+  END IF;
+
+  IF NOT (user_record.password_hash = crypt(p_password, user_record.password_hash)) THEN
+    RAISE EXCEPTION 'Invalid credentials' USING errcode = '28000';
+  END IF;
+
+  RETURN _profile(user_record.id);
+END $$;
+
+-- Get user profile (private function, called after login/register)
+CREATE OR REPLACE FUNCTION _profile(p_user_id INT)
+RETURNS JSONB
+LANGUAGE sql
+SECURITY DEFINER
+AS $$
+  SELECT jsonb_build_object(
+    'user_id', id,
+    'email', email,
+    'name', name,
+    'created_at', created_at
+  )
+  FROM users
+  WHERE id = p_user_id;
+$$;
+`;
+
+      writeFileSync(resolve(options.output, '002_auth.sql'), authSQL, 'utf-8');
+      console.log(`   ✓ 002_auth.sql`);
+
+      const checksums = {};
+
+      for (const compiledResult of result.results) {
+        const outputFile = resolve(options.output, `${compiledResult.tableName}.sql`);
+
+        // Write SQL file
+        writeFileSync(outputFile, compiledResult.sql, 'utf-8');
+
+        // Store checksum
+        checksums[compiledResult.tableName] = {
+          checksum: compiledResult.checksum,
+          generatedAt: compiledResult.generatedAt,
+          compilationTime: compiledResult.compilationTime
+        };
+
+        console.log(`   ✓ ${compiledResult.tableName}.sql (${compiledResult.checksum.substring(0, 8)}...)`);
+      }
+
+      // Write checksums file
+      const checksumsFile = resolve(options.output, 'checksums.json');
+      writeFileSync(checksumsFile, JSON.stringify(checksums, null, 2), 'utf-8');
+
+      console.log(`   ✓ checksums.json`);
+    }
+
+    console.log(`\n✅ Compilation complete!\n`);
+  } catch (error) {
+    console.error(`\n❌ Compilation failed:`, error.message);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}

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.3",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -14,6 +14,7 @@
     "./compiler": "./src/compiler/index.js"
   },
   "files": [
+    "bin/**/*.js",
     "src/**/*.js",
     "src/database/migrations/**/*.sql",
     "docs/**/*.md",
@@ -22,7 +23,7 @@
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.1...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.3...'"
   },
   "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 {};
       }
     }