dzql 0.1.6 → 0.2.1

package/src/server/subscriptions.js

@@ -0,0 +1,209 @@
+/**
+ * Subscription Manager for Live Query Subscriptions
+ * Manages in-memory subscription registry and matching
+ */
+
+import crypto from 'crypto';
+import { wsLogger } from './logger.js';
+
+/**
+ * In-memory subscription registry
+ * Structure: subscription_id -> { subscribable, user_id, connection_id, params }
+ */
+const subscriptions = new Map();
+
+/**
+ * Track subscriptions by connection for cleanup
+ * Structure: connection_id -> Set<subscription_id>
+ */
+const connectionSubscriptions = new Map();
+
+/**
+ * Register a new subscription
+ * @param {string} subscribableName - Name of the subscribable
+ * @param {number} userId - User ID
+ * @param {string} connectionId - WebSocket connection ID
+ * @param {object} params - Subscription parameters
+ * @returns {string} - Subscription ID
+ */
+export function registerSubscription(subscribableName, userId, connectionId, params) {
+  const subscriptionId = crypto.randomUUID();
+
+  // Store subscription
+  subscriptions.set(subscriptionId, {
+    subscribable: subscribableName,
+    user_id: userId,
+    connection_id: connectionId,
+    params,
+    created_at: new Date()
+  });
+
+  // Track by connection
+  if (!connectionSubscriptions.has(connectionId)) {
+    connectionSubscriptions.set(connectionId, new Set());
+  }
+  connectionSubscriptions.get(connectionId).add(subscriptionId);
+
+  wsLogger.debug(`Subscription registered: ${subscriptionId.slice(0, 8)}... (${subscribableName})`, {
+    user_id: userId,
+    params
+  });
+
+  return subscriptionId;
+}
+
+/**
+ * Unregister a subscription
+ * @param {string} subscriptionId - Subscription ID to remove
+ * @returns {boolean} - True if subscription was found and removed
+ */
+export function unregisterSubscription(subscriptionId) {
+  const sub = subscriptions.get(subscriptionId);
+
+  if (!sub) {
+    wsLogger.debug(`Subscription not found: ${subscriptionId}`);
+    return false;
+  }
+
+  // Remove from connection tracking
+  const connSubs = connectionSubscriptions.get(sub.connection_id);
+  if (connSubs) {
+    connSubs.delete(subscriptionId);
+    if (connSubs.size === 0) {
+      connectionSubscriptions.delete(sub.connection_id);
+    }
+  }
+
+  // Remove subscription
+  subscriptions.delete(subscriptionId);
+
+  wsLogger.debug(`Subscription removed: ${subscriptionId.slice(0, 8)}...`);
+  return true;
+}
+
+/**
+ * Unregister subscription by params
+ * Useful for unsubscribe_* methods that specify params instead of subscription ID
+ * @param {string} subscribableName - Name of the subscribable
+ * @param {string} connectionId - WebSocket connection ID
+ * @param {object} params - Subscription parameters to match
+ * @returns {boolean} - True if subscription was found and removed
+ */
+export function unregisterSubscriptionByParams(subscribableName, connectionId, params) {
+  const paramsStr = JSON.stringify(params);
+
+  // Find matching subscription
+  for (const [subId, sub] of subscriptions.entries()) {
+    if (
+      sub.subscribable === subscribableName &&
+      sub.connection_id === connectionId &&
+      JSON.stringify(sub.params) === paramsStr
+    ) {
+      return unregisterSubscription(subId);
+    }
+  }
+
+  wsLogger.debug(`No matching subscription found for ${subscribableName} with params`, params);
+  return false;
+}
+
+/**
+ * Remove all subscriptions for a connection
+ * Called when WebSocket connection closes
+ * @param {string} connectionId - Connection ID
+ * @returns {number} - Number of subscriptions removed
+ */
+export function removeConnectionSubscriptions(connectionId) {
+  const subIds = connectionSubscriptions.get(connectionId);
+
+  if (!subIds) {
+    return 0;
+  }
+
+  let count = 0;
+  for (const subId of subIds) {
+    if (subscriptions.delete(subId)) {
+      count++;
+    }
+  }
+
+  connectionSubscriptions.delete(connectionId);
+
+  if (count > 0) {
+    wsLogger.info(`Removed ${count} subscription(s) for connection ${connectionId.slice(0, 8)}...`);
+  }
+
+  return count;
+}
+
+/**
+ * Get all subscriptions for a specific subscribable
+ * @param {string} subscribableName - Name of the subscribable
+ * @returns {Array} - Array of {subscriptionId, subscription} objects
+ */
+export function getSubscriptionsByName(subscribableName) {
+  const result = [];
+
+  for (const [subId, sub] of subscriptions.entries()) {
+    if (sub.subscribable === subscribableName) {
+      result.push({ subscriptionId: subId, ...sub });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get all subscriptions grouped by subscribable name
+ * @returns {Map<string, Array>} - Map of subscribable name to array of subscriptions
+ */
+export function getSubscriptionsBySubscribable() {
+  const grouped = new Map();
+
+  for (const [subId, sub] of subscriptions.entries()) {
+    if (!grouped.has(sub.subscribable)) {
+      grouped.set(sub.subscribable, []);
+    }
+    grouped.get(sub.subscribable).push({ subscriptionId: subId, ...sub });
+  }
+
+  return grouped;
+}
+
+/**
+ * Check if params match (deep equality)
+ * @param {object} a - First params object
+ * @param {object} b - Second params object
+ * @returns {boolean} - True if params match
+ */
+export function paramsMatch(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Get subscription statistics
+ * @returns {object} - Stats object
+ */
+export function getStats() {
+  return {
+    total_subscriptions: subscriptions.size,
+    active_connections: connectionSubscriptions.size,
+    subscriptions_by_subscribable: Array.from(getSubscriptionsBySubscribable().entries()).map(
+      ([name, subs]) => ({
+        name,
+        count: subs.length
+      })
+    )
+  };
+}
+
+/**
+ * Get all active subscriptions (for debugging)
+ * @returns {Array} - Array of all subscriptions
+ */
+export function getAllSubscriptions() {
+  return Array.from(subscriptions.entries()).map(([id, sub]) => ({
+    id,
+    ...sub
+  }));
+}

package/src/server/ws.js

@@ -6,6 +6,12 @@ import {
   db,
 } from "./db.js";
 import { wsLogger, authLogger } from "./logger.js";
+import {
+  registerSubscription,
+  unregisterSubscription,
+  unregisterSubscriptionByParams,
+  removeConnectionSubscriptions
+} from "./subscriptions.js";
 
 // Environment configuration
 const JWT_SECRET_STRING = process.env.JWT_SECRET;
@@ -304,6 +310,57 @@ export function createRPCHandler(customHandlers = {}) {
         return create_rpc_response(id, result);
       }
 
+      // SUBSCRIPTION HANDLERS - Pattern match on method name
+      if (method.startsWith("subscribe_")) {
+        const subscribableName = method.replace("subscribe_", "");
+        wsLogger.debug(`Subscribe request: ${subscribableName}`, params);
+
+        try {
+          // Execute initial query (this also checks permissions)
+          const queryResult = await db.query(
+            `SELECT get_${subscribableName}($1, $2) as data`,
+            [params, ws.data.user_id]
+          );
+
+          const data = queryResult.rows[0]?.data;
+
+          // Register subscription in memory
+          const subscriptionId = registerSubscription(
+            subscribableName,
+            ws.data.user_id,
+            ws.data.connection_id,
+            params
+          );
+
+          const result = {
+            subscription_id: subscriptionId,
+            data
+          };
+
+          wsLogger.response(method, result, Date.now() - startTime);
+          return create_rpc_response(id, result);
+        } catch (error) {
+          wsLogger.error(`Subscribe failed for ${subscribableName}:`, error.message);
+          return create_rpc_error(id, -32603, error.message);
+        }
+      }
+
+      if (method.startsWith("unsubscribe_")) {
+        const subscribableName = method.replace("unsubscribe_", "");
+        wsLogger.debug(`Unsubscribe request: ${subscribableName}`, params);
+
+        // Remove subscription by params
+        const removed = unregisterSubscriptionByParams(
+          subscribableName,
+          ws.data.connection_id,
+          params
+        );
+
+        const result = { success: removed };
+        wsLogger.response(method, result, Date.now() - startTime);
+        return create_rpc_response(id, result);
+      }
+
       // Check for custom handlers
       if (customHandlers[method]) {
         wsLogger.debug(`Calling custom handler: ${method}`);
@@ -417,7 +474,14 @@ export function createWebSocketHandlers(options = {}) {
     close(ws) {
       const id = ws.data.connection_id;
       connections.delete(id);
-      wsLogger.info(`Connection closed: ${id?.slice(0, 8)}...`);
+
+      // Clean up all subscriptions for this connection
+      const removedCount = removeConnectionSubscriptions(id);
+      if (removedCount > 0) {
+        wsLogger.info(`Connection closed: ${id?.slice(0, 8)}... (${removedCount} subscriptions removed)`);
+      } else {
+        wsLogger.info(`Connection closed: ${id?.slice(0, 8)}...`);
+      }
 
       // Call custom disconnection handler
       if (onDisconnection) {
@@ -434,7 +498,7 @@ export function createWebSocketHandlers(options = {}) {
 
 // Broadcast message to all authenticated connections or specific client_ids
 export function createBroadcaster(connections) {
-  return function broadcastToConnections(message, client_ids = null) {
+  const broadcastToConnections = function(message, client_ids = null) {
     if (client_ids && Array.isArray(client_ids)) {
       // Send to specific user_ids
       for (const [id, ws] of connections) {
@@ -451,6 +515,18 @@ export function createBroadcaster(connections) {
       }
     }
   };
+
+  // Add helper function to send to a specific connection
+  broadcastToConnections.toConnection = function(connectionId, message) {
+    const ws = connections.get(connectionId);
+    if (ws && ws.readyState === 1) { // 1 = OPEN
+      ws.send(message);
+      return true;
+    }
+    return false;
+  };
+
+  return broadcastToConnections;
 }
 
 // Legacy export for backward compatibility

package/src/client/stores/README.md

@@ -1,95 +0,0 @@
-# DZQL Canonical Pinia Stores
-
-**The official, AI-friendly Pinia stores for DZQL Vue.js applications.**
-
-## Why These Stores Exist
-
-When building DZQL apps, developers (and AI assistants) often struggle with:
-
-1. **Three-phase lifecycle** - connecting → login → ready
-2. **WebSocket connection management** - reconnection, error handling
-3. **Authentication flow** - token storage, profile management  
-4. **Router integration** - navigation, state synchronization
-5. **Inconsistent patterns** - every project does it differently
-
-These canonical stores solve all of these problems with a **simple, consistent pattern** that AI can easily understand and replicate.
-
-## The Stores
-
-### `useWsStore` - WebSocket & Auth
-
-Manages:
-- WebSocket connection (with auto-reconnect)
-- User authentication (login/register/logout)
-- Connection state tracking
-- Three-phase app lifecycle
-
-### `useAppStore` - Application State
-
-Manages:
-- App initialization
-- Router integration
-- Entity metadata caching
-- Navigation helpers
-- UI state (sidebars, panels)
-
-## Quick Example
-
-```vue
-<script setup>
-import { computed } from 'vue'
-import { useWsStore, useAppStore } from 'dzql/client/stores'
-
-const wsStore = useWsStore()
-const appStore = useAppStore()
-
-const state = computed(() => wsStore.appState)
-const ws = wsStore.getWs()
-
-// Use DZQL API
-const venues = await ws.api.search.venues({ limit: 50 })
-</script>
-
-<template>
-  <!-- Three-phase lifecycle -->
-  <div v-if="state === 'connecting'">Connecting...</div>
-  <LoginView v-else-if="state === 'login'" />
-  <MainApp v-else-if="state === 'ready'" />
-</template>
-```
-
-## Documentation
-
-- **[Quick Start](../../../docs/CLIENT-QUICK-START.md)** - Get running in 5 minutes
-- **[Complete Guide](../../../docs/CLIENT-STORES.md)** - Full API reference and patterns
-
-## Files
-
-- `useWsStore.js` - WebSocket connection and authentication
-- `useAppStore.js` - Application state and navigation
-- `index.js` - Exports both stores
-
-## For AI Assistants
-
-When helping users with DZQL apps:
-
-1. **Always use these stores** - Don't create custom connection logic
-2. **Follow the three-phase lifecycle** - connecting → login → ready
-3. **Use computed for reactive state** - `const profile = computed(() => wsStore.profile)`
-4. **Get WS instance for API calls** - `const ws = wsStore.getWs()`
-
-**Example prompt for AI:**
-
-> "I'm using the canonical DZQL stores from `dzql/client/stores`. The pattern is:
-> 1. useWsStore for WebSocket connection (three phases: connecting, login, ready)
-> 2. useAppStore for app state and navigation
-> 3. Access DZQL API via `wsStore.getWs().api.get.venues({ id: 1 })`
-> Please follow this pattern."
-
-## Version
-
-These stores are available in DZQL v0.1.6+
-
-## License
-
-MIT