dzql 0.6.22 → 0.6.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.6.22",
+  "version": "0.6.24",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",

package/src/cli/codegen/sql.ts

@@ -179,9 +179,23 @@ $$;
 `;
 }
 
-export function generateSchemaSQL(name: string, entityIR: EntityIR): string {
+/**
+ * Generate CREATE TABLE SQL for an entity.
+ * @param name - Entity/table name
+ * @param entityIR - Entity IR definition
+ * @param circularFKs - Set of "table.column" strings for circular FK columns to defer
+ */
+export function generateSchemaSQL(name: string, entityIR: EntityIR, circularFKs?: Set<string>): string {
   const columns = entityIR.columns.map((c: ColumnInfo) => {
-    return `${c.name} ${c.type}`;
+    let colType = c.type;
+
+    // If this column is part of a circular FK, strip the REFERENCES clause
+    // The constraint will be added later via ALTER TABLE
+    if (circularFKs && circularFKs.has(`${name}.${c.name}`)) {
+      colType = stripFKReferences(colType);
+    }
+
+    return `${c.name} ${colType}`;
   }).join(',\n  ');
 
   return `
@@ -191,6 +205,17 @@ CREATE TABLE IF NOT EXISTS ${name} (
 `;
 }
 
+/**
+ * Remove REFERENCES clause from a column type for deferred FK creation.
+ * Preserves NOT NULL, DEFAULT, and other modifiers.
+ * e.g., "int NOT NULL REFERENCES users(id) ON DELETE CASCADE" -> "int NOT NULL"
+ */
+function stripFKReferences(columnType: string): string {
+  return columnType
+    .replace(/\s*REFERENCES\s+\w+(\([^)]+\))?(\s+ON\s+(DELETE|UPDATE)\s+(CASCADE|SET NULL|SET DEFAULT|RESTRICT|NO ACTION))*/gi, '')
+    .trim();
+}
+
 // === SAVE FUNCTION (Upsert) ===
 export function generateSaveFunction(name: string, entityIR: EntityIR): string {
   const cols = entityIR.columns.map((c: ColumnInfo) => c.name);

package/src/cli/compiler/graph_rules.ts

@@ -1,5 +1,36 @@
 import type { GraphRuleIR } from "../../shared/ir.js";
 
+/**
+ * Parses params that may be a string or object into a normalized object.
+ * String format: "field1=source1,field2,field3=source3"
+ * - "field=source" maps field to @source
+ * - "field" alone maps field to @field (or @id for the new record's id)
+ */
+function parseParams(params: Record<string, string> | string | undefined): Record<string, string> {
+  if (!params) return {};
+
+  if (typeof params === 'object') {
+    return params;
+  }
+
+  // Parse string format: "org_id=@id,user_id=@user_id" or "organisation_id=sponsor_id,campaign_id"
+  const result: Record<string, string> = {};
+  for (const part of params.split(',')) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.includes('=')) {
+      const [field, source] = trimmed.split('=').map(s => s.trim());
+      // Ensure source starts with @ for variable references
+      result[field] = source.startsWith('@') ? source : `@${source}`;
+    } else {
+      // Field alone means use @field as source (or @id for 'id')
+      result[trimmed] = `@${trimmed}`;
+    }
+  }
+  return result;
+}
+
 /**
  * Resolves a value reference (like @id, @user_id, @before.field, @after.field)
  * into the appropriate SQL expression based on the trigger context.
@@ -110,7 +141,7 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === REACTOR ===
     if (rule.action === 'reactor') {
       const name = rule.target;
-      const params = rule.params || {};
+      const params = parseParams(rule.params);
 
       // Build JSON object using jsonb_build_object
       const jsonArgs: string[] = [];
@@ -139,7 +170,7 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === CREATE SIDE EFFECT ===
     if (rule.action === 'create') {
       const target = rule.target;
-      const data = rule.params || {};
+      const data = parseParams(rule.params);
       const cols: string[] = [];
       const vals: string[] = [];
 
@@ -159,8 +190,8 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === UPDATE SIDE EFFECT ===
     if (rule.action === 'update') {
       const target = rule.target;
-      const data = rule.params || {};
-      const match = rule.match || {};
+      const data = parseParams(rule.params);
+      const match = parseParams(rule.match);
 
       const setClauses: string[] = [];
       for (const [key, val] of Object.entries(data)) {
@@ -186,7 +217,11 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === DELETE CASCADE ===
     if (rule.action === 'delete') {
       const target = rule.target;
-      const match = rule.match || rule.params || {};
+      // Try match first, fall back to params
+      let match = parseParams(rule.match);
+      if (Object.keys(match).length === 0) {
+        match = parseParams(rule.params);
+      }
       const whereClauses: string[] = [];
 
       for (const [key, val] of Object.entries(match)) {
@@ -204,7 +239,7 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === VALIDATE ===
     if (rule.action === 'validate') {
       const functionName = rule.target;
-      const params = rule.params || {};
+      const params = parseParams(rule.params);
       const errorMessage = rule.error_message || 'Validation failed';
 
       const paramList: string[] = [];
@@ -224,7 +259,7 @@ export function compileGraphRules(entity: string, trigger: string, rules: GraphR
     // === EXECUTE ===
     if (rule.action === 'execute') {
       const functionName = rule.target;
-      const params = rule.params || {};
+      const params = parseParams(rule.params);
 
       const paramList: string[] = [];
       for (const [key, val] of Object.entries(params)) {

package/src/cli/index.ts

@@ -70,12 +70,17 @@ async function main() {
 
       // Topologically sort entities by FK dependencies
       // Entities must be created before entities that reference them
-      const sortedEntityNames = topologicalSortEntities(ir.entities);
+      // Also detects circular FKs that need deferred constraint creation
+      const { sorted: sortedEntityNames, circularFKs } = topologicalSortEntities(ir.entities);
+
+      // Build set of circular FK columns for stripping during schema generation
+      const circularFKSet = new Set(circularFKs.map(fk => `${fk.table}.${fk.column}`));
 
       const entitySQL: string[] = [];
       for (const name of sortedEntityNames) {
         const entityIR = ir.entities[name];
-        entitySQL.push(generateSchemaSQL(name, entityIR));
+        // Pass circular FK info so schema generation can strip those constraints
+        entitySQL.push(generateSchemaSQL(name, entityIR, circularFKSet));
         // Skip CRUD generation for unmanaged entities (e.g., junction tables)
         if (entityIR.managed !== false) {
           entitySQL.push(generateEntitySQL(name, entityIR));
@@ -84,6 +89,11 @@ async function main() {
         }
       }
 
+      // Add deferred FK constraints at the end (for circular dependencies)
+      if (circularFKs.length > 0) {
+        entitySQL.push(generateDeferredFKConstraints(circularFKs));
+      }
+
       // Generate subscribable SQL functions
       const subscribableSQL: string[] = [];
       const subscribableNames = Object.keys(ir.subscribables);
@@ -178,18 +188,36 @@ async function main() {
 
 main();
 
+/** FK info for dependency analysis */
+interface FKInfo {
+  table: string;
+  column: string;
+  referencedTable: string;
+  fullConstraint: string; // e.g., "int NOT NULL REFERENCES users(id)"
+}
+
+/** Result of topological sort with cycle detection */
+interface SortResult {
+  sorted: string[];
+  circularFKs: FKInfo[];
+}
+
 /**
  * Topologically sort entities based on FK dependencies.
  * Entities that are referenced by others come first.
  * Uses Kahn's algorithm for topological sorting.
+ * Returns both sorted order and any circular FK constraints that need deferred creation.
  */
-function topologicalSortEntities(entities: Record<string, any>): string[] {
+function topologicalSortEntities(entities: Record<string, any>): SortResult {
   const entityNames = Object.keys(entities);
 
   // Build dependency graph: entity -> entities it depends on (references)
   const dependencies: Record<string, Set<string>> = {};
   const dependents: Record<string, Set<string>> = {};
 
+  // Track all FK info for cycle detection
+  const allFKs: FKInfo[] = [];
+
   for (const name of entityNames) {
     dependencies[name] = new Set();
     dependents[name] = new Set();
@@ -206,6 +234,12 @@ function topologicalSortEntities(entities: Record<string, any>): string[] {
         if (entityNames.includes(referencedEntity)) {
           dependencies[name].add(referencedEntity);
           dependents[referencedEntity].add(name);
+          allFKs.push({
+            table: name,
+            column: col.name,
+            referencedTable: referencedEntity,
+            fullConstraint: col.type
+          });
         }
       }
     }
@@ -214,10 +248,16 @@ function topologicalSortEntities(entities: Record<string, any>): string[] {
   // Kahn's algorithm
   const result: string[] = [];
   const noIncoming: string[] = [];
+  const remainingDeps: Record<string, Set<string>> = {};
+
+  // Copy dependencies for mutation
+  for (const name of entityNames) {
+    remainingDeps[name] = new Set(dependencies[name]);
+  }
 
   // Find entities with no dependencies (no incoming edges)
   for (const name of entityNames) {
-    if (dependencies[name].size === 0) {
+    if (remainingDeps[name].size === 0) {
       noIncoming.push(name);
     }
   }
@@ -228,20 +268,67 @@ function topologicalSortEntities(entities: Record<string, any>): string[] {
 
     // Remove this node from the graph
     for (const dependent of dependents[node]) {
-      dependencies[dependent].delete(node);
-      if (dependencies[dependent].size === 0) {
+      remainingDeps[dependent].delete(node);
+      if (remainingDeps[dependent].size === 0) {
         noIncoming.push(dependent);
       }
     }
   }
 
-  // Check for cycles
+  // Detect circular FKs
+  const circularFKs: FKInfo[] = [];
   if (result.length !== entityNames.length) {
-    const remaining = entityNames.filter(n => !result.includes(n));
-    console.warn(`[Compiler] Warning: Circular FK dependencies detected among: ${remaining.join(', ')}`);
-    // Add remaining entities anyway (they may have circular refs)
-    result.push(...remaining);
+    const cycleEntities = new Set(entityNames.filter(n => !result.includes(n)));
+    console.warn(`[Compiler] Warning: Circular FK dependencies detected among: ${[...cycleEntities].join(', ')}`);
+
+    // Find FKs that are part of the cycle - these need deferred creation
+    for (const fk of allFKs) {
+      if (cycleEntities.has(fk.table) && cycleEntities.has(fk.referencedTable)) {
+        circularFKs.push(fk);
+        console.log(`[Compiler] Deferring circular FK: ${fk.table}.${fk.column} -> ${fk.referencedTable}`);
+      }
+    }
+
+    // Add remaining entities (cycle members) to result
+    result.push(...cycleEntities);
+  }
+
+  return { sorted: result, circularFKs };
+}
+
+/**
+ * Generate ALTER TABLE statements for deferred circular FK constraints.
+ */
+function generateDeferredFKConstraints(circularFKs: FKInfo[]): string {
+  if (circularFKs.length === 0) return '';
+
+  const statements: string[] = [
+    '\n-- === DEFERRED FK CONSTRAINTS (for circular dependencies) ===\n'
+  ];
+
+  for (const fk of circularFKs) {
+    // Extract the REFERENCES part from the full constraint
+    const refMatch = fk.fullConstraint.match(/REFERENCES\s+(\w+)(\([^)]+\))?(\s+ON\s+.+)?/i);
+    if (refMatch) {
+      const targetTable = refMatch[1];
+      const targetCol = refMatch[2] || '(id)';
+      const cascadeClause = refMatch[3] || '';
+      const constraintName = `fk_${fk.table}_${fk.column}`;
+
+      statements.push(`ALTER TABLE ${fk.table} ADD CONSTRAINT ${constraintName} FOREIGN KEY (${fk.column}) REFERENCES ${targetTable}${targetCol}${cascadeClause};`);
+    }
   }
 
-  return result;
+  return statements.join('\n');
+}
+
+/**
+ * Remove REFERENCES clause from a column type for deferred FK creation.
+ * Preserves NOT NULL and other modifiers.
+ */
+function stripReferences(columnType: string): string {
+  // Remove REFERENCES clause and any ON DELETE/UPDATE clauses
+  return columnType
+    .replace(/\s*REFERENCES\s+\w+(\([^)]+\))?(\s+ON\s+(DELETE|UPDATE)\s+(CASCADE|SET NULL|SET DEFAULT|RESTRICT|NO ACTION))*\s*/gi, ' ')
+    .trim();
 }