dzql 0.1.6 → 0.2.0

package/src/compiler/compiler.js

@@ -4,10 +4,12 @@
  */
 
 import { EntityParser } 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';
 import { generateNotificationFunction } from './codegen/notification-codegen.js';
 import { generateGraphRuleFunctions } from './codegen/graph-rules-codegen.js';
+import { generateSubscribable } from './codegen/subscribable-codegen.js';
 import crypto from 'crypto';
 
 export class DZQLCompiler {
@@ -18,6 +20,7 @@ export class DZQLCompiler {
       ...options
     };
     this.parser = new EntityParser();
+    this.subscribableParser = new SubscribableParser();
   }
 
   /**
@@ -79,6 +82,34 @@ export class DZQLCompiler {
     return result;
   }
 
+  /**
+   * Compile a subscribable definition to SQL
+   * @param {Object} subscribable - Subscribable configuration
+   * @returns {Object} Compilation result
+   */
+  compileSubscribable(subscribable) {
+    const startTime = Date.now();
+
+    // Normalize subscribable configuration
+    const normalized = typeof subscribable.name === 'string'
+      ? subscribable
+      : this.subscribableParser.parseFromObject(subscribable);
+
+    // Generate SQL
+    const sql = generateSubscribable(normalized);
+
+    // Calculate checksum
+    const checksum = this._calculateChecksum(sql);
+
+    return {
+      name: normalized.name,
+      sql,
+      checksum,
+      compilationTime: Date.now() - startTime,
+      generatedAt: new Date().toISOString()
+    };
+  }
+
   /**
    * Compile multiple entities
    * @param {Array} entities - Array of entity configurations
@@ -111,6 +142,38 @@ export class DZQLCompiler {
     };
   }
 
+  /**
+   * Compile multiple subscribables
+   * @param {Array} subscribables - Array of subscribable configurations
+   * @returns {Object} Compilation results
+   */
+  compileAllSubscribables(subscribables) {
+    const results = [];
+    const errors = [];
+
+    for (const subscribable of subscribables) {
+      try {
+        const result = this.compileSubscribable(subscribable);
+        results.push(result);
+      } catch (error) {
+        errors.push({
+          subscribable: subscribable.name || 'unknown',
+          error: error.message
+        });
+      }
+    }
+
+    return {
+      results,
+      errors,
+      summary: {
+        total: subscribables.length,
+        successful: results.length,
+        failed: errors.length
+      }
+    };
+  }
+
   /**
    * Compile from SQL file
    * @param {string} sqlContent - SQL file content
@@ -140,6 +203,25 @@ export class DZQLCompiler {
     return this.compileAll(entities);
   }
 
+  /**
+   * Compile subscribables from SQL file
+   * @param {string} sqlContent - SQL file content
+   * @returns {Object} Compilation results
+   */
+  compileSubscribablesFromSQL(sqlContent) {
+    const subscribables = this.subscribableParser.parseAllFromSQL(sqlContent);
+
+    if (subscribables.length === 0) {
+      return {
+        results: [],
+        errors: [],
+        summary: { total: 0, successful: 0, failed: 0 }
+      };
+    }
+
+    return this.compileAllSubscribables(subscribables);
+  }
+
   /**
    * Generate file header
    * @private
@@ -226,3 +308,36 @@ export function compileFromSQL(sqlContent, options = {}) {
   const compiler = new DZQLCompiler(options);
   return compiler.compileFromSQL(sqlContent);
 }
+
+/**
+ * Compile a single subscribable
+ * @param {Object} subscribable - Subscribable configuration
+ * @param {Object} options - Compiler options
+ * @returns {Object} Compilation result
+ */
+export function compileSubscribable(subscribable, options = {}) {
+  const compiler = new DZQLCompiler(options);
+  return compiler.compileSubscribable(subscribable);
+}
+
+/**
+ * Compile multiple subscribables
+ * @param {Array} subscribables - Array of subscribable configurations
+ * @param {Object} options - Compiler options
+ * @returns {Object} Compilation results
+ */
+export function compileAllSubscribables(subscribables, options = {}) {
+  const compiler = new DZQLCompiler(options);
+  return compiler.compileAllSubscribables(subscribables);
+}
+
+/**
+ * Compile subscribables from SQL file content
+ * @param {string} sqlContent - SQL file content
+ * @param {Object} options - Compiler options
+ * @returns {Object} Compilation results
+ */
+export function compileSubscribablesFromSQL(sqlContent, options = {}) {
+  const compiler = new DZQLCompiler(options);
+  return compiler.compileSubscribablesFromSQL(sqlContent);
+}

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

@@ -0,0 +1,242 @@
+/**
+ * Subscribable Definition Parser
+ * Parses register_subscribable() calls and extracts configuration
+ */
+
+export class SubscribableParser {
+  /**
+   * Parse a dzql.register_subscribable() call from SQL
+   * @param {string} sql - SQL containing register_subscribable call
+   * @returns {Object} Parsed subscribable configuration
+   */
+  parseFromSQL(sql) {
+    // Extract the register_subscribable call
+    const registerMatch = sql.match(/dzql\.register_subscribable\s*\(([\s\S]*?)\);/i);
+    if (!registerMatch) {
+      throw new Error('No register_subscribable call found in SQL');
+    }
+
+    const params = this._parseParameters(registerMatch[1]);
+
+    return this._buildSubscribableConfig(params);
+  }
+
+  /**
+   * Parse parameters from register_subscribable call
+   * @private
+   */
+  _parseParameters(paramsString) {
+    // Split by commas that are not inside quotes, parentheses, or brackets
+    const params = [];
+    let currentParam = '';
+    let depth = 0;
+    let inString = false;
+    let stringChar = null;
+
+    for (let i = 0; i < paramsString.length; i++) {
+      const char = paramsString[i];
+      const prevChar = i > 0 ? paramsString[i - 1] : '';
+
+      if ((char === "'" || char === '"') && prevChar !== '\\') {
+        if (!inString) {
+          inString = true;
+          stringChar = char;
+        } else if (char === stringChar) {
+          inString = false;
+          stringChar = null;
+        }
+      }
+
+      if (!inString) {
+        if (char === '(' || char === '{' || char === '[') depth++;
+        if (char === ')' || char === '}' || char === ']') depth--;
+
+        if (char === ',' && depth === 0) {
+          params.push(currentParam.trim());
+          currentParam = '';
+          continue;
+        }
+      }
+
+      currentParam += char;
+    }
+
+    if (currentParam.trim()) {
+      params.push(currentParam.trim());
+    }
+
+    return params;
+  }
+
+  /**
+   * Build subscribable configuration from parsed parameters
+   * register_subscribable(name, permission_paths, param_schema, root_entity, relations)
+   * @private
+   */
+  _buildSubscribableConfig(params) {
+    const config = {
+      name: this._cleanString(params[0]),
+      permissionPaths: params[1] ? this._parseJSON(params[1]) : {},
+      paramSchema: params[2] ? this._parseJSON(params[2]) : {},
+      rootEntity: this._cleanString(params[3]),
+      relations: params[4] ? this._parseJSON(params[4]) : {}
+    };
+
+    return config;
+  }
+
+  /**
+   * Parse from JavaScript object (for programmatic usage)
+   * @param {Object} obj - Subscribable configuration object
+   * @returns {Object} Normalized configuration
+   */
+  parseFromObject(obj) {
+    return {
+      name: obj.name,
+      permissionPaths: obj.permissionPaths || obj.permissions || {},
+      paramSchema: obj.paramSchema || obj.params || {},
+      rootEntity: obj.rootEntity || obj.root,
+      relations: obj.relations || {}
+    };
+  }
+
+  /**
+   * Parse multiple subscribables from SQL file
+   * @param {string} sql - SQL file content
+   * @returns {Array} Array of subscribable configurations
+   */
+  parseAllFromSQL(sql) {
+    const subscribables = [];
+    const regex = /dzql\.register_subscribable\s*\(([\s\S]*?)\);/gi;
+    let match;
+
+    while ((match = regex.exec(sql)) !== null) {
+      try {
+        const params = this._parseParameters(match[1]);
+        const config = this._buildSubscribableConfig(params);
+        subscribables.push(config);
+      } catch (error) {
+        console.error('Failed to parse subscribable:', error.message);
+      }
+    }
+
+    return subscribables;
+  }
+
+  /**
+   * Clean a string parameter (remove quotes)
+   * @private
+   */
+  _cleanString(str) {
+    if (!str) return '';
+    // Remove outer quotes, SQL comments, then any remaining quotes and whitespace
+    let cleaned = str.replace(/^['"]|['"]$/g, '');  // Remove outer quotes
+    cleaned = cleaned.replace(/--[^\n]*/g, '');     // Remove SQL comments
+    cleaned = cleaned.replace(/['"\s]+$/g, '');     // Remove trailing quotes/whitespace
+    return cleaned.trim();
+  }
+
+  /**
+   * Parse JSONB object parameter
+   * @private
+   */
+  _parseJSON(str) {
+    if (!str || str === '{}' || str === "'{}'::jsonb") {
+      return {};
+    }
+
+    // Handle jsonb_build_object() syntax
+    if (str.includes('jsonb_build_object')) {
+      return this._parseJSONBuildObject(str);
+    }
+
+    // Handle plain JSON string
+    try {
+      // Remove ::jsonb cast
+      let cleaned = str.replace(/::jsonb$/i, '');
+      // Remove outer quotes if it's a string literal
+      cleaned = cleaned.replace(/^'(.*)'$/, '$1');
+      // Unescape internal quotes
+      cleaned = cleaned.replace(/''/g, "'");
+
+      return JSON.parse(cleaned);
+    } catch (error) {
+      console.error('Failed to parse JSON:', str, error);
+      return {};
+    }
+  }
+
+  /**
+   * Parse jsonb_build_object() calls
+   * @private
+   */
+  _parseJSONBuildObject(str) {
+    const result = {};
+
+    // Extract content between jsonb_build_object( and )
+    const match = str.match(/jsonb_build_object\s*\(([\s\S]*)\)/i);
+    if (!match) return result;
+
+    // Parse key-value pairs
+    const params = this._parseParameters(match[1]);
+
+    for (let i = 0; i < params.length; i += 2) {
+      if (i + 1 < params.length) {
+        const key = this._cleanString(params[i]);
+        let value = params[i + 1];
+
+        // Check if value is nested jsonb_build_object or array
+        if (value.includes('jsonb_build_object')) {
+          value = this._parseJSONBuildObject(value);
+        } else if (value.includes('jsonb_build_array')) {
+          value = this._parseJSONBArray(value);
+        } else if (value.includes('ARRAY[')) {
+          value = this._parseArray(value);
+        } else {
+          value = this._cleanString(value);
+        }
+
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse jsonb_build_array() calls
+   * @private
+   */
+  _parseJSONBArray(str) {
+    const match = str.match(/jsonb_build_array\s*\(([\s\S]*)\)/i);
+    if (!match) return [];
+
+    const params = this._parseParameters(match[1]);
+    return params.map(p => {
+      if (p.includes('jsonb_build_object')) {
+        return this._parseJSONBuildObject(p);
+      }
+      return this._cleanString(p);
+    });
+  }
+
+  /**
+   * Parse ARRAY[...] syntax
+   * @private
+   */
+  _parseArray(str) {
+    if (!str || str === 'ARRAY[]::text[]') {
+      return [];
+    }
+
+    // Extract content between ARRAY[ and ]
+    const match = str.match(/ARRAY\[(.*?)\]/i);
+    if (!match) return [];
+
+    // Split by comma and clean each element
+    return match[1]
+      .split(',')
+      .map(s => this._cleanString(s))
+      .filter(s => s.length > 0);
+  }
+}

package/src/database/migrations/009_subscriptions.sql

@@ -0,0 +1,230 @@
+-- Migration 009: Live Query Subscriptions Infrastructure
+-- Adds support for subscribable documents (Pattern 1 from vision.md)
+
+-- ============================================================================
+-- Subscribables Registry (Metadata Only)
+-- ============================================================================
+
+-- Stores metadata for registered subscribables
+-- Note: Active subscriptions are held in-memory on the server
+CREATE TABLE IF NOT EXISTS dzql.subscribables (
+  name TEXT PRIMARY KEY,
+  permission_paths JSONB NOT NULL DEFAULT '{}'::jsonb,
+  param_schema JSONB NOT NULL DEFAULT '{}'::jsonb,
+  root_entity TEXT NOT NULL,
+  relations JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+COMMENT ON TABLE dzql.subscribables IS
+  'Registry of subscribable documents. Subscribables define denormalized views that clients can subscribe to for real-time updates.';
+
+COMMENT ON COLUMN dzql.subscribables.name IS
+  'Subscribable identifier (used in subscribe_<name> RPC calls)';
+
+COMMENT ON COLUMN dzql.subscribables.permission_paths IS
+  'Access control paths (e.g., {"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]})';
+
+COMMENT ON COLUMN dzql.subscribables.param_schema IS
+  'Parameter schema defining subscription key (e.g., {"venue_id": "int"})';
+
+COMMENT ON COLUMN dzql.subscribables.root_entity IS
+  'Root table for the subscribable document';
+
+COMMENT ON COLUMN dzql.subscribables.relations IS
+  'Related entities to include (e.g., {"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}})';
+
+-- Index for quick lookups
+CREATE INDEX IF NOT EXISTS idx_subscribables_root_entity
+  ON dzql.subscribables(root_entity);
+
+-- ============================================================================
+-- Register Subscribable Function
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION dzql.register_subscribable(
+  p_name TEXT,
+  p_permission_paths JSONB,
+  p_param_schema JSONB,
+  p_root_entity TEXT,
+  p_relations JSONB
+) RETURNS TEXT AS $$
+DECLARE
+  v_result TEXT;
+BEGIN
+  -- Validate inputs
+  IF p_name IS NULL OR p_name = '' THEN
+    RAISE EXCEPTION 'Subscribable name cannot be empty';
+  END IF;
+
+  IF p_root_entity IS NULL OR p_root_entity = '' THEN
+    RAISE EXCEPTION 'Root entity cannot be empty';
+  END IF;
+
+  -- Insert or update subscribable
+  INSERT INTO dzql.subscribables (
+    name,
+    permission_paths,
+    param_schema,
+    root_entity,
+    relations,
+    created_at,
+    updated_at
+  ) VALUES (
+    p_name,
+    COALESCE(p_permission_paths, '{}'::jsonb),
+    COALESCE(p_param_schema, '{}'::jsonb),
+    p_root_entity,
+    COALESCE(p_relations, '{}'::jsonb),
+    NOW(),
+    NOW()
+  )
+  ON CONFLICT (name) DO UPDATE SET
+    permission_paths = EXCLUDED.permission_paths,
+    param_schema = EXCLUDED.param_schema,
+    root_entity = EXCLUDED.root_entity,
+    relations = EXCLUDED.relations,
+    updated_at = NOW();
+
+  v_result := format('Subscribable "%s" registered successfully', p_name);
+
+  RAISE NOTICE '%', v_result;
+
+  RETURN v_result;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION dzql.register_subscribable IS
+  'Register a subscribable document definition. Used by the compiler to store subscribable metadata.';
+
+-- ============================================================================
+-- Helper Functions
+-- ============================================================================
+
+-- Get all registered subscribables
+CREATE OR REPLACE FUNCTION dzql.get_subscribables()
+RETURNS TABLE (
+  name TEXT,
+  permission_paths JSONB,
+  param_schema JSONB,
+  root_entity TEXT,
+  relations JSONB,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    s.name,
+    s.permission_paths,
+    s.param_schema,
+    s.root_entity,
+    s.relations,
+    s.created_at,
+    s.updated_at
+  FROM dzql.subscribables s
+  ORDER BY s.name;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+COMMENT ON FUNCTION dzql.get_subscribables IS
+  'Retrieve all registered subscribables';
+
+-- Get subscribable by name
+CREATE OR REPLACE FUNCTION dzql.get_subscribable(p_name TEXT)
+RETURNS TABLE (
+  name TEXT,
+  permission_paths JSONB,
+  param_schema JSONB,
+  root_entity TEXT,
+  relations JSONB,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    s.name,
+    s.permission_paths,
+    s.param_schema,
+    s.root_entity,
+    s.relations,
+    s.created_at,
+    s.updated_at
+  FROM dzql.subscribables s
+  WHERE s.name = p_name;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+COMMENT ON FUNCTION dzql.get_subscribable IS
+  'Retrieve a specific subscribable by name';
+
+-- Get subscribables by root entity
+CREATE OR REPLACE FUNCTION dzql.get_subscribables_by_entity(p_entity TEXT)
+RETURNS TABLE (
+  name TEXT,
+  permission_paths JSONB,
+  param_schema JSONB,
+  root_entity TEXT,
+  relations JSONB,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    s.name,
+    s.permission_paths,
+    s.param_schema,
+    s.root_entity,
+    s.relations,
+    s.created_at,
+    s.updated_at
+  FROM dzql.subscribables s
+  WHERE s.root_entity = p_entity
+  ORDER BY s.name;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+COMMENT ON FUNCTION dzql.get_subscribables_by_entity IS
+  'Retrieve all subscribables for a given root entity';
+
+-- Delete subscribable
+CREATE OR REPLACE FUNCTION dzql.delete_subscribable(p_name TEXT)
+RETURNS TEXT AS $$
+DECLARE
+  v_result TEXT;
+BEGIN
+  DELETE FROM dzql.subscribables
+  WHERE name = p_name;
+
+  IF FOUND THEN
+    v_result := format('Subscribable "%s" deleted successfully', p_name);
+  ELSE
+    v_result := format('Subscribable "%s" not found', p_name);
+  END IF;
+
+  RAISE NOTICE '%', v_result;
+
+  RETURN v_result;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION dzql.delete_subscribable IS
+  'Delete a subscribable by name';
+
+-- ============================================================================
+-- Verification
+-- ============================================================================
+
+DO $$
+BEGIN
+  RAISE NOTICE 'Migration 009: Live Query Subscriptions - Complete';
+  RAISE NOTICE 'Subscribables table created';
+  RAISE NOTICE 'Helper functions installed';
+  RAISE NOTICE '';
+  RAISE NOTICE 'Usage:';
+  RAISE NOTICE '  SELECT dzql.register_subscribable(''name'', permissions, params, root, relations);';
+  RAISE NOTICE '  SELECT * FROM dzql.get_subscribables();';
+END $$;