dzql 0.1.6 → 0.2.1

package/docs/SUBSCRIPTIONS_QUICK_START.md

@@ -0,0 +1,203 @@
+# Live Query Subscriptions - Quick Start
+
+Get up and running with live query subscriptions in 5 minutes.
+
+## Step 1: Create a Subscribable (2 min)
+
+Create `my_subscribable.sql`:
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_detail',                                               -- Name (use in API)
+  '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,  -- Who can subscribe
+  '{"venue_id": "int"}'::jsonb,                                -- Subscription parameters
+  'venues',                                                     -- Root table
+  '{"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb  -- Related data
+);
+```
+
+## Step 2: Compile and Deploy (1 min)
+
+```bash
+# Compile to PostgreSQL functions
+bun packages/dzql/src/compiler/cli/compile-subscribable.js my_subscribable.sql | psql $DATABASE_URL
+```
+
+This creates 3 functions:
+- `venue_detail_can_subscribe(user_id, params)` - permission check
+- `get_venue_detail(params, user_id)` - query builder
+- `venue_detail_affected_documents(table, op, old, new)` - change detector
+
+## Step 3: Subscribe from Client (2 min)
+
+```javascript
+import { WebSocketManager } from '@dzql/client';
+
+const ws = new WebSocketManager('ws://localhost:3000/ws');
+await ws.connect();
+
+// Subscribe - get initial data + live updates
+const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
+  { venue_id: 123 },
+  (updatedData) => {
+    console.log('Venue changed!', updatedData);
+  }
+);
+
+console.log('Initial data:', data);
+
+// Later: cleanup
+await unsubscribe();
+```
+
+## That's It!
+
+Your client now receives real-time updates whenever:
+- The venue record changes
+- Related organisation changes
+- Related sites change
+
+All change detection happens in PostgreSQL - zero configuration needed on the server!
+
+## Next Steps
+
+- [Full Documentation](./LIVE_QUERY_SUBSCRIPTIONS.md)
+- [Permission Paths Guide](./PATH_DSL.md)
+- [Example Subscribables](../packages/dzql/examples/subscribables/)
+
+## Common Patterns
+
+### Simple Document (Single Table)
+
+```sql
+SELECT dzql.register_subscribable(
+  'user_settings',
+  '{"subscribe": ["@user_id"]}'::jsonb,  -- Only owner
+  '{"user_id": "int"}'::jsonb,
+  'user_settings',
+  '{}'::jsonb  -- No relations
+);
+```
+
+### With One Relation
+
+```sql
+SELECT dzql.register_subscribable(
+  'booking_summary',
+  '{"subscribe": ["@user_id"]}'::jsonb,
+  '{"booking_id": "int"}'::jsonb,
+  'bookings',
+  '{"venue": "venues"}'::jsonb  -- Include venue
+);
+```
+
+### With Filtered Relations
+
+```sql
+SELECT dzql.register_subscribable(
+  'organisation_dashboard',
+  '{"subscribe": ["@id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
+  '{"org_id": "int"}'::jsonb,
+  'organisations',
+  '{
+    "members": {
+      "entity": "acts_for",
+      "filter": "org_id=$org_id AND valid_to IS NULL"
+    },
+    "venues": {
+      "entity": "venues",
+      "filter": "org_id=$org_id"
+    }
+  }'::jsonb
+);
+```
+
+### Multiple Permission Paths (OR logic)
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_admin',
+  '{
+    "subscribe": [
+      "@owner_id",                                    -- Direct owner
+      "@org_id->acts_for[org_id=$]{active}.user_id"  -- OR org member
+    ]
+  }'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',
+  '{"sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb
+);
+```
+
+## Debugging Tips
+
+### Test the functions manually:
+
+```sql
+-- Check permission
+SELECT venue_detail_can_subscribe(1, '{"venue_id": 123}'::jsonb);
+
+-- Get data
+SELECT get_venue_detail('{"venue_id": 123}'::jsonb, 1);
+
+-- Test change detection
+SELECT venue_detail_affected_documents(
+  'venues',
+  'update',
+  '{"id": 123}'::jsonb,
+  '{"id": 123, "name": "New"}'::jsonb
+);
+```
+
+### Check active subscriptions:
+
+```javascript
+// Client-side
+console.log('My subscriptions:', ws.subscriptions.size);
+```
+
+## FAQ
+
+**Q: When should I use subscriptions vs. simple queries?**
+A: Use subscriptions when data changes frequently and client needs to stay in sync. Use simple queries for one-time lookups.
+
+**Q: What happens when client disconnects?**
+A: Server automatically cleans up all subscriptions for that connection.
+
+**Q: Can multiple clients subscribe to the same data?**
+A: Yes! Each subscription is independent. All will receive updates.
+
+**Q: How do I update the subscribable definition?**
+A: Re-compile and deploy. The `register_subscribable()` call uses `ON CONFLICT UPDATE`, so it's safe to run repeatedly.
+
+**Q: What if the underlying data is deleted?**
+A: The `get_<name>()` function returns `null`. Handle this in your callback:
+```javascript
+(data) => {
+  if (!data) {
+    console.log('Record was deleted');
+    return;
+  }
+  updateUI(data);
+}
+```
+
+**Q: How do I subscribe to a list of items?**
+A: Create a subscribable with array parameters or use multiple subscriptions. For dashboard-style views, consider a single subscribable that returns an array.
+
+## Performance Tips
+
+1. **Index your joins**: Make sure foreign keys are indexed
+2. **Keep _affected_documents() simple**: Early return for unrelated tables
+3. **Limit relation depth**: Avoid deeply nested relations (max 2-3 levels)
+4. **Use specific subscription keys**: `venue_id` is better than `org_id` (fewer false positives)
+5. **Unsubscribe when done**: Always cleanup to free server resources
+
+## Architecture Benefits
+
+- ✅ **PostgreSQL-First**: All logic in database, not application code
+- ✅ **Zero Configuration**: No server changes needed for new subscribables
+- ✅ **Type Safe**: Compiled functions validated at deploy time
+- ✅ **Efficient**: In-memory registry, PostgreSQL does matching
+- ✅ **Secure**: Permission paths enforced at database level
+- ✅ **Scalable**: Stateless server, can add instances freely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -22,13 +22,12 @@
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.1.5...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.2.1...'"
   },
   "dependencies": {
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
-
   "keywords": [
     "postgresql",
     "postgres",

package/src/client/ws.js

@@ -59,12 +59,11 @@ class WebSocketManager {
     this.pendingRequests = new Map();
     this.broadcastCallbacks = new Set();
     this.sidRequestHandlers = new Set();
+    this.subscriptions = new Map(); // subscription_id -> { callback, unsubscribe }
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
     this.isShuttingDown = false;
 
-    // Ad
-
     // DZQL nested proxy API - matches server-side db.api pattern
     // Proxy handles both DZQL operations and custom functions
     const dzqlOps = {
@@ -137,6 +136,18 @@ class WebSocketManager {
         if (prop in target) {
           return target[prop];
         }
+        // Handle subscribe_* methods specially
+        if (prop.startsWith('subscribe_')) {
+          return (params = {}, callback) => {
+            return this.subscribe(prop, params, callback);
+          };
+        }
+        // Handle unsubscribe_* methods
+        if (prop.startsWith('unsubscribe_')) {
+          return (params = {}) => {
+            return this.unsubscribe(prop, params);
+          };
+        }
         // All other properties are treated as custom function calls
         return (params = {}) => {
           return this.call(prop, params);
@@ -314,6 +325,16 @@ class WebSocketManager {
         resolve(message.result);
       }
     } else {
+      // Handle subscription updates
+      if (message.method === "subscription:update") {
+        const { subscription_id, data } = message.params;
+        const sub = this.subscriptions.get(subscription_id);
+        if (sub && sub.callback) {
+          sub.callback(data);
+        }
+        return;
+      }
+
       // Handle broadcasts and SID requests
 
       // Check if this is a SID request from server
@@ -376,6 +397,70 @@ class WebSocketManager {
     });
   }
 
+  /**
+   * Subscribe to a live query
+   *
+   * @param {string} method - Method name (subscribe_<subscribable>)
+   * @param {object} params - Subscription parameters
+   * @param {function} callback - Callback function for updates
+   * @returns {Promise<{data, subscription_id, unsubscribe}>} Initial data and unsubscribe function
+   *
+   * @example
+   * const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
+   *   { venue_id: 1 },
+   *   (updated) => console.log('Updated:', updated)
+   * );
+   *
+   * // Use initial data
+   * console.log('Initial:', data);
+   *
+   * // Later: unsubscribe
+   * unsubscribe();
+   */
+  async subscribe(method, params = {}, callback) {
+    if (!callback || typeof callback !== 'function') {
+      throw new Error('Subscribe requires a callback function');
+    }
+
+    // Call server to register subscription
+    const result = await this.call(method, params);
+    const { subscription_id, data } = result;
+
+    // Create unsubscribe function
+    const unsubscribeFn = async () => {
+      const unsubMethod = method.replace('subscribe_', 'unsubscribe_');
+      await this.call(unsubMethod, params);
+      this.subscriptions.delete(subscription_id);
+    };
+
+    // Store callback for updates
+    this.subscriptions.set(subscription_id, {
+      callback,
+      unsubscribe: unsubscribeFn
+    });
+
+    // Return initial data and unsubscribe function
+    return {
+      data,
+      subscription_id,
+      unsubscribe: unsubscribeFn
+    };
+  }
+
+  /**
+   * Unsubscribe from a live query
+   *
+   * @param {string} method - Method name (unsubscribe_<subscribable>)
+   * @param {object} params - Subscription parameters
+   * @returns {Promise<{success: boolean}>}
+   *
+   * @example
+   * await ws.api.unsubscribe_venue_detail({ venue_id: 1 });
+   */
+  async unsubscribe(method, params = {}) {
+    return await this.call(method, params);
+  }
+
   /**
    * Register callback for real-time broadcast events
    *

package/src/compiler/cli/compile-example.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from 'fs';
+import { compileSubscribablesFromSQL } from '../compiler.js';
+
+const sqlContent = readFileSync('./examples/subscribables/venue_detail_simple.sql', 'utf-8');
+
+console.log('Compiling subscribable...\n');
+
+try {
+  const result = compileSubscribablesFromSQL(sqlContent);
+
+  console.log('Summary:', result.summary);
+
+  if (result.errors.length > 0) {
+    console.log('\nErrors:');
+    result.errors.forEach(err => {
+      console.log(`  ${err.subscribable}: ${err.error}`);
+    });
+  }
+
+  if (result.results.length > 0) {
+    const compiled = result.results[0];
+    console.log(`\n✓ Compiled '${compiled.name}' successfully!`);
+    console.log(`  Checksum: ${compiled.checksum.substring(0, 16)}...`);
+    console.log(`  Time: ${compiled.compilationTime}ms`);
+    console.log('\nGenerated SQL:\n');
+    console.log(compiled.sql);
+  }
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}

package/src/compiler/cli/compile-subscribable.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+
+/**
+ * Compile subscribable and output SQL only (for piping to psql)
+ */
+
+import { readFileSync } from 'fs';
+import { compileSubscribablesFromSQL } from '../compiler.js';
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error('Usage: compile-subscribable.js <sql-file>');
+  process.exit(1);
+}
+
+const sqlFile = args[0];
+
+try {
+  const sqlContent = readFileSync(sqlFile, 'utf-8');
+  const result = compileSubscribablesFromSQL(sqlContent);
+
+  if (result.errors.length > 0) {
+    console.error('Compilation errors:');
+    result.errors.forEach(err => {
+      console.error(`  ${err.subscribable}: ${err.error}`);
+    });
+    process.exit(1);
+  }
+
+  if (result.results.length === 0) {
+    console.error('No subscribables found in', sqlFile);
+    process.exit(1);
+  }
+
+  // Output just the SQL
+  for (const compiled of result.results) {
+    console.log(compiled.sql);
+    console.log(''); // Blank line between subscribables
+  }
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}

package/src/compiler/cli/debug-compile.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+
+/**
+ * Test script for subscribable compilation
+ */
+
+import { readFileSync } from 'fs';
+import { compileSubscribablesFromSQL } from './src/compiler/compiler.js';
+
+// Read the example subscribable
+const sqlContent = readFileSync('./examples/subscribables/venue_detail_subscribable.sql', 'utf-8');
+
+console.log('Compiling subscribable...\n');
+
+try {
+  const result = compileSubscribablesFromSQL(sqlContent);
+
+  console.log('Compilation Summary:');
+  console.log(`  Total: ${result.summary.total}`);
+  console.log(`  Successful: ${result.summary.successful}`);
+  console.log(`  Failed: ${result.summary.failed}\n`);
+
+  if (result.errors.length > 0) {
+    console.log('Errors:');
+    result.errors.forEach(err => {
+      console.log(`  - ${err.subscribable}: ${err.error}`);
+    });
+    console.log('');
+  }
+
+  if (result.results.length > 0) {
+    const compiled = result.results[0];
+    console.log(`Generated SQL for '${compiled.name}':`);
+    console.log('='.repeat(80));
+    console.log(compiled.sql);
+    console.log('='.repeat(80));
+    console.log(`\nChecksum: ${compiled.checksum}`);
+    console.log(`Compilation time: ${compiled.compilationTime}ms`);
+  }
+} catch (error) {
+  console.error('Compilation failed:', error.message);
+  console.error(error.stack);
+  process.exit(1);
+}

package/src/compiler/cli/debug-parse.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+
+/**
+ * Test script for subscribable parsing (debug)
+ */
+
+import { readFileSync } from 'fs';
+import { SubscribableParser } from './src/compiler/parser/subscribable-parser.js';
+
+// Read the example subscribable
+const sqlContent = readFileSync('./examples/subscribables/venue_detail_subscribable.sql', 'utf-8');
+
+console.log('Parsing subscribable...\n');
+
+const parser = new SubscribableParser();
+const subscribables = parser.parseAllFromSQL(sqlContent);
+
+console.log('Found', subscribables.length, 'subscribables\n');
+
+for (const sub of subscribables) {
+  console.log('Subscribable:', sub.name);
+  console.log('Root Entity:', sub.rootEntity);
+  console.log('Permission Paths:', JSON.stringify(sub.permissionPaths, null, 2));
+  console.log('Param Schema:', JSON.stringify(sub.paramSchema, null, 2));
+  console.log('Relations:', JSON.stringify(sub.relations, null, 2));
+}

package/src/compiler/cli/debug-path-parser.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+
+import { PathParser } from './src/compiler/parser/path-parser.js';
+
+const parser = new PathParser();
+
+const testPath = '@org_id->acts_for[org_id=$]{active}.user_id';
+
+console.log('Parsing path:', testPath);
+console.log('');
+
+try {
+  const ast = parser.parse(testPath);
+  console.log('AST:', JSON.stringify(ast, null, 2));
+} catch (error) {
+  console.error('Error:', error.message);
+  console.error(error.stack);
+}

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+
+import { SubscribableParser } from '../parser/subscribable-parser.js';
+import { readFileSync } from 'fs';
+
+const sqlContent = readFileSync('./examples/subscribables/venue_detail_simple.sql', 'utf-8');
+
+console.log('Parsing subscribable...\n');
+
+const parser = new SubscribableParser();
+const subscribables = parser.parseAllFromSQL(sqlContent);
+
+console.log('Found:', subscribables.length, 'subscribables\n');
+
+for (const sub of subscribables) {
+  console.log('Name:', sub.name);
+  console.log('Root Entity:', sub.rootEntity);
+  console.log('Permission Paths:', JSON.stringify(sub.permissionPaths, null, 2));
+  console.log('Param Schema:', JSON.stringify(sub.paramSchema, null, 2));
+  console.log('Relations:', JSON.stringify(sub.relations, null, 2));
+}