dzql 0.6.13 → 0.6.15

package/src/client/ws.ts

@@ -1,6 +1,5 @@
 // Core WebSocket Manager for DZQL Client
 // Handles connection, auth, reconnects, and message dispatching.
-// This is a pure transport layer - it does not manage or cache data.
 
 export interface WebSocketOptions {
   url?: string;
@@ -8,38 +7,50 @@ export interface WebSocketOptions {
   tokenName?: string;
 }
 
-// Get default token name from environment (build-time injection)
 function getDefaultTokenName(): string {
-  // Vite: import.meta.env.VITE_DZQL_TOKEN_NAME
   // @ts-ignore
   if (typeof import.meta !== 'undefined' && import.meta.env?.VITE_DZQL_TOKEN_NAME) {
     // @ts-ignore
     return import.meta.env.VITE_DZQL_TOKEN_NAME;
   }
-  // Node/bundlers: process.env.DZQL_TOKEN_NAME
   if (typeof process !== 'undefined' && process.env?.DZQL_TOKEN_NAME) {
     return process.env.DZQL_TOKEN_NAME;
   }
   return 'dzql_token';
 }
 
+/** Schema returned from subscription */
+interface SubscriptionSchema {
+  root?: string;
+  paths?: Record<string, string>;
+  scopeTables?: string[];
+}
+
+/** Subscription entry stored on client */
+interface SubscriptionEntry {
+  callback: (data: any) => void;
+  schema: SubscriptionSchema;
+  localData: any;
+}
+
+/** Handler signature for store table_changed methods */
+export type TableChangedHandler = (table: string, op: string, pk: Record<string, unknown>, data: unknown) => void;
+
 export class WebSocketManager {
   protected ws: WebSocket | null = null;
   protected messageId = 0;
   protected pendingRequests = new Map<number, { resolve: (val: any) => void; reject: (err: any) => void }>();
   protected methodHandlers = new Map<string, Set<(params: any) => void>>();
-  protected subscriptionCallbacks = new Map<string, (event: any) => void>();
+  protected subscriptions = new Map<string, SubscriptionEntry>();
   protected readyCallbacks = new Set<(user: any) => void>();
+  protected storeHandlers = new Set<TableChangedHandler>();
   protected reconnectAttempts = 0;
   protected maxReconnectAttempts = 5;
   protected tokenName = 'dzql_token';
   protected isShuttingDown = false;
 
-  // Connection state
   public user: any = null;
   public ready: boolean = false;
-
-  // To be populated by generated code
   public api: any = {};
 
   constructor(options: WebSocketOptions = {}) {
@@ -48,18 +59,11 @@ export class WebSocketManager {
   }
 
   async login(credentials: any) {
-    try {
-      const result = await this.call('login_user', credentials) as { token?: string };
-      if (result && result.token) {
-        if (typeof localStorage !== 'undefined') {
-          localStorage.setItem(this.tokenName, result.token);
-        }
-        await this.authenticate(result.token);
-      }
-      return result;
-    } catch (e) {
-      throw e;
+    const result = await this.call('login_user', credentials) as { token?: string };
+    if (result?.token && typeof localStorage !== 'undefined') {
+      localStorage.setItem(this.tokenName, result.token);
     }
+    return result;
   }
 
   async authenticate(token: string) {
@@ -67,18 +71,12 @@ export class WebSocketManager {
   }
 
   async register(credentials: any, options: any = {}) {
-    try {
-      const params = { ...credentials, options };
-      const result = await this.call('register_user', params) as { token?: string };
-      if (result && result.token) {
-        if (typeof localStorage !== 'undefined') {
-          localStorage.setItem(this.tokenName, result.token);
-        }
-      }
-      return result;
-    } catch (e) {
-      throw e;
+    const params = { ...credentials, options };
+    const result = await this.call('register_user', params) as { token?: string };
+    if (result?.token && typeof localStorage !== 'undefined') {
+      localStorage.setItem(this.tokenName, result.token);
     }
+    return result;
   }
 
   async logout() {
@@ -110,36 +108,32 @@ export class WebSocketManager {
       if (typeof localStorage !== 'undefined') {
         const token = localStorage.getItem(this.tokenName);
         if (token) {
-          if (wsUrl.includes('?')) wsUrl += '&token=' + encodeURIComponent(token);
-          else wsUrl += '?token=' + encodeURIComponent(token);
+          wsUrl += (wsUrl.includes('?') ? '&' : '?') + 'token=' + encodeURIComponent(token);
         }
       }
 
       const connectionTimeout = setTimeout(() => {
-        if (this.ws) this.ws.close();
-        reject(new Error('WebSocket connection timed out after ' + timeout + 'ms'));
+        this.ws?.close();
+        reject(new Error('WebSocket connection timed out'));
       }, timeout);
 
       this.ws = new WebSocket(wsUrl);
 
       this.ws.onopen = () => {
         clearTimeout(connectionTimeout);
-        console.log('[DZQL] Connected to ' + wsUrl);
         this.reconnectAttempts = 0;
         resolve();
       };
 
       this.ws.onmessage = (event) => {
         try {
-          const message = JSON.parse(event.data);
-          this.handleMessage(message);
+          this.handleMessage(JSON.parse(event.data));
         } catch (error) {
           console.error("[DZQL] Failed to parse message:", error);
         }
       };
 
       this.ws.onclose = () => {
-        console.log("[DZQL] Disconnected");
         if (!this.isShuttingDown) {
           this.attemptReconnect();
         }
@@ -147,7 +141,6 @@ export class WebSocketManager {
 
       this.ws.onerror = (error) => {
         clearTimeout(connectionTimeout);
-        console.error("[DZQL] Connection error:", error);
         reject(error);
       };
     });
@@ -156,16 +149,12 @@ export class WebSocketManager {
   attemptReconnect() {
     if (this.reconnectAttempts < this.maxReconnectAttempts) {
       this.reconnectAttempts++;
-      const delay = 1000 * this.reconnectAttempts;
-      setTimeout(() => {
-        console.log('[DZQL] Reconnecting (' + this.reconnectAttempts + ')...');
-        this.connect();
-      }, delay);
+      setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
     }
   }
 
   handleMessage(message: any) {
-    // Handle connection:ready message
+    // Handle connection:ready
     if (message.method === "connection:ready") {
       this.user = message.params?.user || null;
       this.ready = true;
@@ -173,44 +162,111 @@ export class WebSocketManager {
       return;
     }
 
-    // Handle RPC responses (messages with id)
+    // Handle RPC responses
     if (message.id && this.pendingRequests.has(message.id)) {
-      const resolver = this.pendingRequests.get(message.id);
-      if (resolver) {
-        this.pendingRequests.delete(message.id);
-        if (message.error) {
-          const err: any = new Error(message.error.message || 'Unknown error');
-          err.code = message.error.code;
-          resolver.reject(err);
-        } else {
-          resolver.resolve(message.result);
-        }
+      const resolver = this.pendingRequests.get(message.id)!;
+      this.pendingRequests.delete(message.id);
+      if (message.error) {
+        const err: any = new Error(message.error.message || 'Unknown error');
+        err.code = message.error.code;
+        resolver.reject(err);
+      } else {
+        resolver.resolve(message.result);
       }
       return;
     }
 
-    // Handle subscription events - dispatch to registered subscription callbacks
+    // Handle subscription events - dispatch by subscription_id
     if (message.method === "subscription:event") {
-      const event = message.params?.event;
-      if (event) {
-        // Dispatch to all subscription handlers - they filter by table/scope
-        for (const [subId, callback] of this.subscriptionCallbacks) {
-          callback(event);
-        }
+      const { subscription_id, event } = message.params || {};
+      const sub = this.subscriptions.get(subscription_id);
+      if (sub && event) {
+        this.applyAtomicUpdate(sub, event);
       }
       return;
     }
 
-    // Handle other server-initiated messages (broadcasts) - route to registered handlers
+    // Handle entity broadcasts (e.g. "venues:update", "users:insert")
+    if (message.method && message.method.includes(':')) {
+      const [table, op] = message.method.split(':');
+      const { pk, data } = message.params || {};
+
+      // Dispatch to registered store handlers
+      this.storeHandlers.forEach(handler => handler(table, op, pk, data));
+
+      // Also dispatch to legacy broadcast handlers
+      this.dispatchBroadcast(message.method, message.params);
+    }
+
+    // Handle other broadcasts via methodHandlers
     if (message.method) {
       const handlers = this.methodHandlers.get(message.method);
-      if (handlers) {
-        handlers.forEach((cb) => cb(message.params));
+      handlers?.forEach((cb) => cb(message.params));
+    }
+  }
+
+  /**
+   * Apply an atomic update to a subscription's local data
+   */
+  private applyAtomicUpdate(sub: SubscriptionEntry, event: { table: string; op: string; pk: any; data: any }) {
+    const { table, op, pk, data } = event;
+    const { schema, localData, callback } = sub;
+
+    if (!schema || !localData) {
+      if (data) callback(data);
+      return;
+    }
+
+    const path = schema.paths?.[table];
+    if (!path) {
+      console.warn(`Unknown table ${table} in subscription`);
+      return;
+    }
+
+    if (path === '.' || table === schema.root) {
+      // Root entity changed
+      if (op === 'update' && data) {
+        Object.assign(localData[schema.root!] || localData, data);
       }
+    } else {
+      // Relation changed - find and update in nested structure
+      this.applyRelationUpdate(localData, path, op, pk, data);
     }
+
+    callback(localData);
   }
 
-  call(method: string, params: any = {}) {
+  /**
+   * Apply update to a nested relation
+   */
+  private applyRelationUpdate(doc: any, path: string, op: string, pk: any, data: any) {
+    const parts = path.split('.');
+    let target = doc;
+
+    // Navigate to parent
+    for (let i = 0; i < parts.length - 1; i++) {
+      target = target?.[parts[i]];
+      if (!target) return;
+    }
+
+    const key = parts[parts.length - 1];
+    const arr = target[key];
+
+    if (!Array.isArray(arr)) return;
+
+    const pkValue = pk?.id;
+    const idx = arr.findIndex((item: any) => item?.id === pkValue);
+
+    if (op === 'insert' && idx === -1 && data) {
+      arr.push(data);
+    } else if (op === 'update' && idx !== -1 && data) {
+      Object.assign(arr[idx], data);
+    } else if (op === 'delete' && idx !== -1) {
+      arr.splice(idx, 1);
+    }
+  }
+
+  call(method: string, params: any = {}): Promise<any> {
     return new Promise((resolve, reject) => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
         reject(new Error("WebSocket not connected"));
@@ -222,12 +278,6 @@ export class WebSocketManager {
     });
   }
 
-  /**
-   * Register a callback for a server-initiated method
-   * @param method - The method name to listen for
-   * @param callback - Called with params when server sends this method
-   * @returns Unsubscribe function
-   */
   on(method: string, callback: (params: any) => void) {
     if (!this.methodHandlers.has(method)) {
       this.methodHandlers.set(method, new Set());
@@ -237,51 +287,85 @@ export class WebSocketManager {
       const handlers = this.methodHandlers.get(method);
       if (handlers) {
         handlers.delete(callback);
-        if (handlers.size === 0) {
-          this.methodHandlers.delete(method);
-        }
+        if (handlers.size === 0) this.methodHandlers.delete(method);
       }
     };
   }
 
+  onReady(callback: (user: any) => void) {
+    if (this.ready) callback(this.user);
+    this.readyCallbacks.add(callback);
+    return () => this.readyCallbacks.delete(callback);
+  }
+
+  /**
+   * Register a store's table_changed handler.
+   * Called automatically by generated stores.
+   * @returns Unregister function
+   */
+  registerStore(handler: TableChangedHandler): () => void {
+    this.storeHandlers.add(handler);
+    return () => this.storeHandlers.delete(handler);
+  }
+
   /**
-   * Register a callback to be called when connection is ready
-   * @param callback - Called with user profile (or null if not authenticated)
+   * Register a callback for entity broadcast events.
+   * Called when entities you have permission to view are created/updated/deleted.
+   * The method format is "table:op" (e.g. "venues:update", "users:insert").
+   *
+   * @param callback - Function called with (method, params) for each broadcast
    * @returns Unsubscribe function
    */
-  onReady(callback: (user: any) => void) {
-    if (this.ready) {
-      callback(this.user);
+  onBroadcast(callback: (method: string, params: { pk: any; data: any }) => void): () => void {
+    const handler = (params: any) => {
+      // The method name is stored on the callback context
+    };
+
+    // Use a special marker to track broadcast handlers
+    const broadcastHandler = { callback, marker: 'broadcast' as const };
+    if (!this._broadcastHandlers) {
+      this._broadcastHandlers = new Set();
     }
-    this.readyCallbacks.add(callback);
-    return () => this.readyCallbacks.delete(callback);
+    this._broadcastHandlers.add(broadcastHandler);
+
+    return () => {
+      this._broadcastHandlers?.delete(broadcastHandler);
+    };
+  }
+
+  protected _broadcastHandlers?: Set<{ callback: (method: string, params: any) => void; marker: 'broadcast' }>;
+
+  /**
+   * Dispatch a broadcast event to all broadcast handlers
+   */
+  protected dispatchBroadcast(method: string, params: any) {
+    this._broadcastHandlers?.forEach(h => h.callback(method, params));
   }
 
   /**
    * Subscribe to a subscribable document
-   * @param method - The subscribe method name (e.g., "subscribe_venue_detail")
-   * @param params - Subscription parameters
-   * @param callback - Called with initial data and on updates
-   * @returns Promise that resolves to an unsubscribe function
    */
   async subscribe(method: string, params: any, callback: (data: any) => void): Promise<() => void> {
-    // Call server to get initial snapshot and subscription_id
     const result = await this.call(method, params) as {
       subscription_id: string;
       data: any;
+      schema?: SubscriptionSchema;
     };
 
-    // Register callback for subscription events
-    this.subscriptionCallbacks.set(result.subscription_id, callback);
+    // Store subscription with local data for atomic updates
+    this.subscriptions.set(result.subscription_id, {
+      callback,
+      schema: result.schema || {},
+      localData: result.data
+    });
 
     // Call callback with initial data
     callback(result.data);
 
     // Return unsubscribe function
     return () => {
-      this.subscriptionCallbacks.delete(result.subscription_id);
-      // Notify server
-      this.call(`unsubscribe_${method.replace('subscribe_', '')}`, { subscription_id: result.subscription_id }).catch(() => {});
+      this.subscriptions.delete(result.subscription_id);
+      this.call(`unsubscribe_${method.replace('subscribe_', '')}`, params).catch(() => {});
     };
   }
 }

package/src/runtime/index.ts

@@ -6,6 +6,7 @@ import { loadManifest } from "./manifest_loader.js";
 import { readFileSync } from "fs";
 import { resolve } from "path";
 import { runtimeLogger, notifyLogger, serverLogger } from "./logger.js";
+import { getSubscriptionsBySubscribable } from "./subscriptions.js";
 
 // Re-export JS function registration API for custom functions
 export { registerJsFunction, type JsFunctionHandler, type JsFunctionContext } from "./js_functions.js";
@@ -35,6 +36,86 @@ try {
 // 3. Initialize WebSocket Server
 const wsServer = new WebSocketServer(db);
 
+/**
+ * Process event notifications.
+ * Sends events to connections based on:
+ * 1. Subscriptions matched by affected_keys
+ * 2. Users in notify_users (from entity notification paths)
+ *
+ * Each connection receives the event at most once, even if matched by both.
+ */
+function processEventNotifications(event: {
+  table: string;
+  op: string;
+  pk: Record<string, unknown>;
+  data: Record<string, unknown>;
+  user_id: number | null;
+  affected_keys: string[];
+  notify_users: number[];
+}) {
+  const { table, op, pk, data, affected_keys, notify_users } = event;
+
+  notifyLogger.debug(`processEventNotifications called for ${table}:${op}`);
+  notifyLogger.debug(`affected_keys: ${JSON.stringify(affected_keys)}`);
+  notifyLogger.debug(`notify_users: ${JSON.stringify(notify_users)}`);
+
+  // Track which connections we've already notified to avoid duplicates
+  const notifiedConnections = new Set<string>();
+
+  // Build the event message for entity broadcasts
+  const entityEventMessage = JSON.stringify({
+    jsonrpc: "2.0",
+    method: `${table}:${op}`,
+    params: { table, op, pk, data }
+  });
+
+  // 1. Send to users in notify_users list (entity notifications)
+  if (notify_users && notify_users.length > 0) {
+    for (const userId of notify_users) {
+      const connectionIds = wsServer.getConnectionsByUserId(userId);
+      for (const connectionId of connectionIds) {
+        if (!notifiedConnections.has(connectionId)) {
+          const sent = wsServer.toConnection(connectionId, entityEventMessage);
+          if (sent) {
+            notifiedConnections.add(connectionId);
+            notifyLogger.debug(`Sent entity event to user ${userId} connection ${connectionId.slice(0, 8)}...`);
+          }
+        }
+      }
+    }
+  }
+
+  // 2. Send entity broadcasts to connections with matching subscriptions
+  // Connections that have bound to a subscribable whose affected_key matches get the broadcast
+  if (affected_keys && affected_keys.length > 0) {
+    const subscriptionsByName = getSubscriptionsBySubscribable();
+
+    for (const [subscribableName, subs] of subscriptionsByName.entries()) {
+      for (const sub of subs) {
+        const paramValues = Object.values(sub.params);
+        // For subscribables with no params, the key is just the name
+        // For subscribables with params, the key is name:param1:param2:...
+        const subKey = paramValues.length > 0
+          ? `${subscribableName}:${paramValues.join(':')}`
+          : subscribableName;
+
+        if (affected_keys.includes(subKey)) {
+          // Send entity broadcast (not subscription:event) so global dispatcher can route it
+          if (!notifiedConnections.has(sub.connection_id)) {
+            const sent = wsServer.toConnection(sub.connection_id, entityEventMessage);
+            if (sent) {
+              notifiedConnections.add(sub.connection_id);
+              notifyLogger.debug(`Sent entity broadcast to ${sub.connection_id.slice(0, 8)}... via ${subscribableName} (${table}:${op})`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  notifyLogger.debug(`Notified ${notifiedConnections.size} connection(s) with entity event`);
+}
+
 // 4. Start Commit Listener (Realtime)
 async function startListener() {
   runtimeLogger.info("Setting up LISTEN on dzql_v2 channel...");
@@ -51,24 +132,18 @@ async function startListener() {
         ORDER BY id ASC
       `, [commit_id]);
 
+      notifyLogger.debug(`Fetched ${events.length} events for commit ${commit_id}`);
       for (const event of events) {
-        // Broadcast
-        const message = JSON.stringify({
-          jsonrpc: "2.0",
-          method: "subscription:event",
-          params: {
-            event: {
-              table: event.table_name,
-              op: event.op,
-              pk: event.pk,
-              data: event.data,
-              // old_data is filtered out
-              user_id: event.user_id
-            }
-          }
+        notifyLogger.debug(`Processing event: ${event.table_name}:${event.op}`);
+        processEventNotifications({
+          table: event.table_name,
+          op: event.op,
+          pk: event.pk,
+          data: event.data,
+          user_id: event.user_id,
+          affected_keys: event.affected_keys || [],
+          notify_users: event.notify_users || []
         });
-        wsServer.broadcast(message);
-        notifyLogger.trace(`Broadcast ${event.op} on ${event.table_name}`);
       }
     } catch (e: any) {
       notifyLogger.error("Listener Error:", e.message);
@@ -85,8 +160,6 @@ const server = serve({
   port: PORT,
   async fetch(req, server) {
     const url = new URL(req.url);
-
-    // Extract token from query params for WebSocket connections
     const token = url.searchParams.get("token") ?? undefined;
 
     if (server.upgrade(req, { data: { token } })) {