dzql 0.1.2 → 0.1.4

package/README.md

@@ -4,12 +4,10 @@ PostgreSQL-powered framework with automatic CRUD operations and real-time WebSoc
 
 ## Documentation
 
-All documentation is maintained in the repository root:
-
-- **[README.md](../../README.md)** - Project overview and quick start
-- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Complete tutorial with working todo app
-- **[REFERENCE.md](REFERENCE.md)** - Complete API reference
-- **[CLAUDE.md](../../docs/CLAUDE.md)** - Development guide for AI assistants
+- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Complete tutorial with working todo app
+- **[API Reference](docs/REFERENCE.md)** - Complete API documentation
+- **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
+- **[Claude Guide](docs/CLAUDE.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
 
 ## Quick Install
@@ -33,6 +31,23 @@ const user = await ws.api.save.users({ name: 'Alice' });
 const results = await ws.api.search.users({ filters: { name: 'alice' } });
 ```
 
+## DZQL Compiler
+
+Transform declarative entity definitions into optimized PostgreSQL stored procedures:
+
+```bash
+# Via CLI
+dzql compile database/init_db/009_venues_domain.sql -o compiled/
+
+# Programmatically
+import { DZQLCompiler } from 'dzql/compiler';
+
+const compiler = new DZQLCompiler();
+const result = compiler.compileFromSQL(sqlContent);
+```
+
+See **[Compiler Documentation](docs/compiler/)** for complete usage guide, coding standards, and advanced features.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -8,7 +8,8 @@
     ".": "./src/server/index.js",
     "./client": "./src/client/ws.js",
     "./server": "./src/server/index.js",
-    "./db": "./src/server/db.js"
+    "./db": "./src/server/db.js",
+    "./compiler": "./src/compiler/index.js"
   },
   "files": [
     "src/**/*.js",
@@ -20,13 +21,12 @@
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.1.2...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.1.4...'"
   },
   "dependencies": {
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
-
   "keywords": [
     "postgresql",
     "postgres",

package/src/compiler/cli/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env bun
+/**
+ * DZQL Compiler CLI
+ * Command-line interface for compiling entity definitions
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+import { DZQLCompiler } from '../compiler.js';
+
+const USAGE = `
+DZQL Compiler - Transform entity definitions into PostgreSQL functions
+
+Usage:
+  dzql-compile <input-file> [options]
+
+Options:
+  -o, --output <dir>       Output directory (default: ./compiled)
+  -w, --watch              Watch for changes and recompile
+  -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/
+  dzql-compile entities/*.sql -o dist/compiled/
+
+Environment Variables:
+  DZQL_COMPILER_VERBOSE    Enable verbose output
+`;
+
+class CLI {
+  constructor() {
+    this.args = process.argv.slice(2);
+    this.options = {
+      output: './compiled',
+      watch: false,
+      verbose: process.env.DZQL_COMPILER_VERBOSE === 'true'
+    };
+    this.compiler = new DZQLCompiler();
+  }
+
+  run() {
+    this.parseArgs();
+
+    if (this.options.help || this.args.length === 0) {
+      console.log(USAGE);
+      process.exit(0);
+    }
+
+    const inputFile = this.args[0];
+
+    if (!existsSync(inputFile)) {
+      console.error(`Error: File not found: ${inputFile}`);
+      process.exit(1);
+    }
+
+    this.compileFile(inputFile);
+
+    if (this.options.watch) {
+      this.watchFile(inputFile);
+    }
+  }
+
+  parseArgs() {
+    for (let i = 0; i < this.args.length; i++) {
+      const arg = this.args[i];
+
+      switch (arg) {
+        case '-o':
+        case '--output':
+          this.options.output = this.args[++i];
+          break;
+
+        case '-w':
+        case '--watch':
+          this.options.watch = true;
+          break;
+
+        case '-v':
+        case '--verbose':
+          this.options.verbose = true;
+          break;
+
+        case '-h':
+        case '--help':
+          this.options.help = true;
+          break;
+      }
+    }
+  }
+
+  compileFile(inputFile) {
+    try {
+      console.log(`\n🔨 Compiling: ${inputFile}`);
+
+      // Read input file
+      const sqlContent = readFileSync(inputFile, 'utf-8');
+
+      // Compile
+      const result = this.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) {
+        this.writeOutputFiles(result.results);
+      }
+
+      console.log(`\n✅ Compilation complete!\n`);
+    } catch (error) {
+      console.error(`\n❌ Compilation failed:`, error.message);
+      if (this.options.verbose) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  }
+
+  writeOutputFiles(results) {
+    // Ensure output directory exists
+    if (!existsSync(this.options.output)) {
+      mkdirSync(this.options.output, { recursive: true });
+    }
+
+    console.log(`\n📝 Writing compiled files to: ${this.options.output}`);
+
+    const checksums = {};
+
+    for (const result of results) {
+      const outputFile = resolve(this.options.output, `${result.tableName}.sql`);
+
+      // Write SQL file
+      writeFileSync(outputFile, result.sql, 'utf-8');
+
+      // Store checksum
+      checksums[result.tableName] = {
+        checksum: result.checksum,
+        generatedAt: result.generatedAt,
+        compilationTime: result.compilationTime
+      };
+
+      console.log(`   ✓ ${result.tableName}.sql (${result.checksum.substring(0, 8)}...)`);
+    }
+
+    // Write checksums file
+    const checksumsFile = resolve(this.options.output, 'checksums.json');
+    writeFileSync(checksumsFile, JSON.stringify(checksums, null, 2), 'utf-8');
+
+    console.log(`   ✓ checksums.json`);
+  }
+
+  watchFile(inputFile) {
+    console.log(`\n👀 Watching for changes...`);
+
+    // TODO: Implement file watching
+    console.log(`   (Watch mode not yet implemented)`);
+  }
+}
+
+// Run CLI
+const cli = new CLI();
+cli.run();

package/src/compiler/codegen/graph-rules-codegen.js

@@ -0,0 +1,259 @@
+/**
+ * Graph Rules Code Generator
+ * Generates PostgreSQL functions for graph rule execution
+ */
+
+export class GraphRulesCodegen {
+  constructor(tableName, graphRules) {
+    this.tableName = tableName;
+    this.graphRules = graphRules;
+  }
+
+  /**
+   * Generate all graph rule functions
+   * @returns {string} SQL for graph rule functions
+   */
+  generate() {
+    if (!this.graphRules || Object.keys(this.graphRules).length === 0) {
+      return '';  // No functions if no rules
+    }
+
+    const functions = [];
+
+    // Generate function for each trigger (on_create, on_update, on_delete)
+    for (const [trigger, rules] of Object.entries(this.graphRules)) {
+      const functionSQL = this._generateTriggerFunction(trigger, rules);
+      if (functionSQL) {
+        functions.push(functionSQL);
+      }
+    }
+
+    return functions.join('\n\n');
+  }
+
+  /**
+   * Generate function for a specific trigger
+   * @private
+   */
+  _generateTriggerFunction(trigger, rules) {
+    const operation = trigger.replace('on_', '');  // on_create -> create
+    const functionName = `_graph_${this.tableName}_${trigger}`;
+
+    const actionBlocks = [];
+
+    // Process each rule
+    for (const [ruleName, ruleConfig] of Object.entries(rules)) {
+      const description = ruleConfig.description || ruleName;
+      const actions = Array.isArray(ruleConfig.actions)
+        ? ruleConfig.actions
+        : (ruleConfig.actions ? [ruleConfig.actions] : []);
+
+      for (const action of actions) {
+        const actionSQL = this._generateAction(action, ruleName, description);
+        if (actionSQL) {
+          actionBlocks.push(actionSQL);
+        }
+      }
+    }
+
+    if (actionBlocks.length === 0) {
+      return null;  // No actions, no function
+    }
+
+    // Determine parameters based on operation - p_user_id ALWAYS FIRST
+    const params = operation === 'delete'
+      ? `p_user_id INT,\n  p_old_record JSONB`
+      : operation === 'update'
+      ? `p_user_id INT,\n  p_old_record JSONB,\n  p_new_record JSONB`
+      : `p_user_id INT,\n  p_record JSONB`;
+
+    return `-- Graph rules: ${trigger} on ${this.tableName}
+CREATE OR REPLACE FUNCTION ${functionName}(
+  ${params}
+) RETURNS VOID AS $$
+BEGIN
+${actionBlocks.join('\n\n')}
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;`;
+  }
+
+  /**
+   * Generate SQL for a single action
+   * @private
+   */
+  _generateAction(action, ruleName, description) {
+    const comment = `  -- ${description}`;
+
+    switch (action.type) {
+      case 'create':
+        return this._generateCreateAction(action, comment);
+
+      case 'update':
+        return this._generateUpdateAction(action, comment);
+
+      case 'delete':
+        return this._generateDeleteAction(action, comment);
+
+      case 'validate':
+        return this._generateValidateAction(action, comment);
+
+      case 'execute':
+        return this._generateExecuteAction(action, comment);
+
+      default:
+        console.warn('Unknown action type:', action.type);
+        return null;
+    }
+  }
+
+  /**
+   * Generate CREATE action
+   * @private
+   */
+  _generateCreateAction(action, comment) {
+    const entity = action.entity;
+    const data = action.data;
+
+    const fields = [];
+    const values = [];
+
+    for (const [field, value] of Object.entries(data)) {
+      fields.push(field);
+      values.push(this._resolveValue(value));
+    }
+
+    return `${comment}
+  INSERT INTO ${entity} (${fields.join(', ')})
+  VALUES (${values.join(', ')});`;
+  }
+
+  /**
+   * Generate UPDATE action
+   * @private
+   */
+  _generateUpdateAction(action, comment) {
+    const entity = action.entity;
+    const data = action.data;
+    const match = action.match;
+
+    const setClauses = [];
+    for (const [field, value] of Object.entries(data)) {
+      setClauses.push(`${field} = ${this._resolveValue(value)}`);
+    }
+
+    const whereClauses = [];
+    for (const [field, value] of Object.entries(match)) {
+      whereClauses.push(`${field} = ${this._resolveValue(value)}`);
+    }
+
+    return `${comment}
+  UPDATE ${entity}
+  SET ${setClauses.join(', ')}
+  WHERE ${whereClauses.join(' AND ')};`;
+  }
+
+  /**
+   * Generate DELETE action
+   * @private
+   */
+  _generateDeleteAction(action, comment) {
+    const entity = action.entity;
+    const match = action.match;
+
+    const whereClauses = [];
+    for (const [field, value] of Object.entries(match)) {
+      whereClauses.push(`${field} = ${this._resolveValue(value)}`);
+    }
+
+    return `${comment}
+  DELETE FROM ${entity}
+  WHERE ${whereClauses.join(' AND ')};`;
+  }
+
+  /**
+   * Generate VALIDATE action
+   * @private
+   */
+  _generateValidateAction(action, comment) {
+    const functionName = action.function;
+    const params = action.params || {};
+    const errorMessage = action.error_message || 'Validation failed';
+
+    const paramList = [];
+    for (const [key, value] of Object.entries(params)) {
+      paramList.push(`${key} => ${this._resolveValue(value)}`);
+    }
+
+    const paramSQL = paramList.length > 0 ? paramList.join(', ') : '';
+
+    return `${comment}
+  IF NOT ${functionName}(${paramSQL}) THEN
+    RAISE EXCEPTION '${errorMessage}';
+  END IF;`;
+  }
+
+  /**
+   * Generate EXECUTE action
+   * @private
+   */
+  _generateExecuteAction(action, comment) {
+    const functionName = action.function;
+    const params = action.params || {};
+
+    const paramList = [];
+    for (const [key, value] of Object.entries(params)) {
+      paramList.push(`${key} => ${this._resolveValue(value)}`);
+    }
+
+    const paramSQL = paramList.length > 0 ? paramList.join(', ') : '';
+
+    return `${comment}
+  PERFORM ${functionName}(${paramSQL});`;
+  }
+
+  /**
+   * Resolve a value (variable reference or literal)
+   * @private
+   */
+  _resolveValue(value) {
+    if (typeof value !== 'string') {
+      // Number or other type
+      return value;
+    }
+
+    // Handle special variables
+    if (value.startsWith('@')) {
+      const varName = value.substring(1);
+
+      // Special keywords
+      switch (varName) {
+        case 'user_id':
+          return 'p_user_id';
+
+        case 'today':
+          return 'CURRENT_DATE';
+
+        case 'now':
+          return 'NOW()';
+
+        default:
+          // Field reference from record
+          return `(p_record->>'${varName}')`;
+      }
+    }
+
+    // String literal
+    return `'${value}'`;
+  }
+}
+
+/**
+ * Generate graph rule functions for an entity
+ * @param {string} tableName - Table name
+ * @param {Object} graphRules - Graph rules object
+ * @returns {string} SQL for graph rule functions
+ */
+export function generateGraphRuleFunctions(tableName, graphRules) {
+  const codegen = new GraphRulesCodegen(tableName, graphRules);
+  return codegen.generate();
+}