dzql 0.5.27 → 0.5.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.27",
+  "version": "0.5.29",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

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

@@ -247,7 +247,39 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
       scopeTables: scopeTables
     });
 
-    // Dashboard mode: empty paramSchema means aggregate root as array
+    // Pure collection mode: no rootEntity, only relations
+    if (!this.rootEntity) {
+      // Build relation-only selects (strip leading comma)
+      const collectionSelects = this._generateCollectionOnlySelects();
+
+      return `CREATE OR REPLACE FUNCTION get_${this.name}(
+  p_params JSONB,
+  p_user_id INT
+) RETURNS JSONB AS $$
+DECLARE
+  v_data JSONB;
+BEGIN
+  -- Check access control
+  IF NOT ${this.name}_can_subscribe(p_user_id, p_params) THEN
+    RAISE EXCEPTION 'Permission denied';
+  END IF;
+
+  -- Build document with collections only (no root entity)
+  SELECT jsonb_build_object(
+    ${collectionSelects}
+  )
+  INTO v_data;
+
+  -- Return data with embedded schema for atomic updates
+  RETURN jsonb_build_object(
+    'data', v_data,
+    'schema', '${schemaJson}'::jsonb
+  );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;`;
+    }
+
+    // Dashboard mode: empty paramSchema with rootEntity means aggregate root as array
     if (params.length === 0) {
       return `CREATE OR REPLACE FUNCTION get_${this.name}(
   p_params JSONB,
@@ -388,6 +420,33 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     return selects;
   }
 
+  /**
+   * Generate collection-only selects (no root entity)
+   * Used when rootEntity is null/empty - pure collection mode
+   * @private
+   */
+  _generateCollectionOnlySelects() {
+    if (Object.keys(this.relations).length === 0) {
+      return "'_empty', '{}'::jsonb";
+    }
+
+    const selects = Object.entries(this.relations).map(([relName, relConfig]) => {
+      const relEntity = typeof relConfig === 'string' ? relConfig : relConfig.entity;
+      const relFilter = typeof relConfig === 'object' ? relConfig.filter : null;
+
+      // For collection mode, filter should be TRUE or we fetch all
+      const filterSQL = relFilter === 'TRUE' ? 'TRUE' : 'TRUE';
+
+      return `'${relName}', COALESCE((
+      SELECT jsonb_agg(row_to_json(rel.*))
+      FROM ${relEntity} rel
+      WHERE ${filterSQL}
+    ), '[]'::jsonb)`;
+    });
+
+    return selects.join(',\n    ');
+  }
+
   /**
    * Generate JOIN clause for via relations
    * Handles multi-hop via chains by looking up each intermediate table
@@ -512,9 +571,11 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const cases = [];
     const seenEntities = new Set();
 
-    // Case 1: Root entity changed
-    cases.push(this._generateRootAffectedCase());
-    seenEntities.add(this.rootEntity);
+    // Case 1: Root entity changed (only if rootEntity exists)
+    if (this.rootEntity) {
+      cases.push(this._generateRootAffectedCase());
+      seenEntities.add(this.rootEntity);
+    }
 
     // Case 2: Related entities changed (skip duplicates)
     for (const [relName, relConfig] of Object.entries(this.relations)) {
@@ -664,7 +725,10 @@ $$ LANGUAGE plpgsql IMMUTABLE;`;
    * @returns {string[]} Array of table names
    */
   extractScopeTables() {
-    const tables = new Set([this.rootEntity]);
+    const tables = new Set();
+    if (this.rootEntity) {
+      tables.add(this.rootEntity);
+    }
 
     const extractFromRelations = (relations) => {
       for (const [relName, relConfig] of Object.entries(relations || {})) {
@@ -701,8 +765,10 @@ $$ LANGUAGE plpgsql IMMUTABLE;`;
   buildPathMapping() {
     const paths = {};
 
-    // Root entity maps to top level
-    paths[this.rootEntity] = '.';
+    // Root entity maps to top level (only if it exists)
+    if (this.rootEntity) {
+      paths[this.rootEntity] = '.';
+    }
 
     const buildPaths = (relations, parentPath = '') => {
       for (const [relName, relConfig] of Object.entries(relations || {})) {

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

@@ -129,6 +129,8 @@ export class SubscribableParser {
    */
   _cleanString(str) {
     if (!str) return '';
+    // Handle SQL NULL keyword - return empty string for null values
+    if (str.trim().toUpperCase() === 'NULL') 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

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

@@ -11,7 +11,7 @@ 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,
+  root_entity TEXT,  -- NULL allowed for dashboard mode (pure collections)
   relations JSONB NOT NULL DEFAULT '{}'::jsonb,
   scope_tables TEXT[] NOT NULL DEFAULT '{}',
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -31,7 +31,7 @@ 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';
+  'Root table for the subscribable document. NULL for dashboard mode (pure collections).';
 
 COMMENT ON COLUMN dzql.subscribables.relations IS
   'Related entities to include (e.g., {"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}})';

package/src/database/migrations/010_atomic_updates.sql

@@ -16,8 +16,12 @@ DECLARE
   v_entity TEXT;
   v_nested JSONB;
 BEGIN
-  -- Start with root entity
-  v_tables := ARRAY[p_root_entity];
+  -- Start with root entity (may be NULL for dashboard mode)
+  IF p_root_entity IS NOT NULL AND p_root_entity != '' THEN
+    v_tables := ARRAY[p_root_entity];
+  ELSE
+    v_tables := ARRAY[]::TEXT[];
+  END IF;
 
   -- Return early if no relations
   IF p_relations IS NULL OR p_relations = '{}'::jsonb THEN
@@ -85,8 +89,11 @@ BEGIN
     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';
+  -- NULL root_entity is allowed for dashboard mode (pure collections)
+  -- But if relations is also empty, that's an error
+  IF (p_root_entity IS NULL OR p_root_entity = '') AND
+     (p_relations IS NULL OR p_relations = '{}'::jsonb) THEN
+    RAISE EXCEPTION 'Subscribable must have either a root entity or relations';
   END IF;
 
   -- Extract scope tables from root entity and relations
@@ -106,7 +113,7 @@ BEGIN
     p_name,
     COALESCE(p_permission_paths, '{}'::jsonb),
     COALESCE(p_param_schema, '{}'::jsonb),
-    p_root_entity,
+    NULLIF(p_root_entity, ''),  -- Store empty string as NULL
     COALESCE(p_relations, '{}'::jsonb),
     v_scope_tables,
     NOW(),