dzql 0.1.5 → 0.2.0

package/docs/REFERENCE.md

@@ -12,6 +12,7 @@ Complete API documentation for DZQL framework. For tutorials, see [GETTING_START
 - [Custom Functions](#custom-functions)
 - [Authentication](#authentication)
 - [Real-time Events](#real-time-events)
+- [Live Query Subscriptions](#live-query-subscriptions)
 - [Temporal Relationships](#temporal-relationships)
 - [Error Messages](#error-messages)
 
@@ -864,6 +865,144 @@ ws.onBroadcast((method, params) => {
 
 ---
 
+## Live Query Subscriptions
+
+Subscribe to denormalized documents and receive automatic updates when underlying data changes. Subscriptions use a PostgreSQL-first architecture where all change detection happens in the database.
+
+For complete documentation, see **[Live Query Subscriptions Guide](../../../docs/LIVE_QUERY_SUBSCRIPTIONS.md)** and **[Quick Start](../../../docs/SUBSCRIPTIONS_QUICK_START.md)**.
+
+### Quick Example
+
+```javascript
+// Subscribe to venue with all related data
+const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
+  { venue_id: 123 },
+  (updatedVenue) => {
+    // Called automatically when venue, org, or sites change
+    console.log('Updated:', updatedVenue);
+    // updatedVenue = { id: 123, name: '...', org: {...}, sites: [...] }
+  }
+);
+
+// Initial data available immediately
+console.log('Initial:', data);
+
+// Later: cleanup
+await unsubscribe();
+```
+
+### Creating a Subscribable
+
+Define subscribables in SQL:
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_detail',                                               -- Name
+  '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,  -- Permissions
+  '{"venue_id": "int"}'::jsonb,                                -- Parameters
+  'venues',                                                     -- Root table
+  '{
+    "org": "organisations",
+    "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}
+  }'::jsonb                                                     -- Relations
+);
+```
+
+### Compile and Deploy
+
+```bash
+# Compile subscribable to PostgreSQL functions
+node packages/dzql/compile-subscribable.js venue.sql | psql $DATABASE_URL
+```
+
+This generates three 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
+
+### Subscription Lifecycle
+
+1. **Subscribe**: Client calls `ws.api.subscribe_<name>(params, callback)`
+2. **Permission Check**: `<name>_can_subscribe()` validates access
+3. **Initial Query**: `get_<name>()` returns denormalized document
+4. **Register**: Server stores subscription in-memory
+5. **Database Change**: Any relevant table modification
+6. **Detect**: `<name>_affected_documents()` identifies affected subscriptions
+7. **Re-query**: `get_<name>()` fetches fresh data
+8. **Update**: Callback invoked with new data
+
+### Unsubscribe
+
+```javascript
+// Method 1: Use returned unsubscribe function
+const { unsubscribe } = await ws.api.subscribe_venue_detail(...);
+await unsubscribe();
+
+// Method 2: Direct unsubscribe call
+await ws.api.unsubscribe_venue_detail({ venue_id: 123 });
+```
+
+### Architecture Benefits
+
+- **PostgreSQL-First**: All logic executes in database, not application code
+- **Zero Configuration**: Pattern matching on method names - no server changes needed
+- **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
+
+### Common Patterns
+
+**Single Table:**
+```sql
+SELECT dzql.register_subscribable(
+  'user_settings',
+  '{"subscribe": ["@user_id"]}'::jsonb,
+  '{"user_id": "int"}'::jsonb,
+  'user_settings',
+  '{}'::jsonb
+);
+```
+
+**With Relations:**
+```sql
+SELECT dzql.register_subscribable(
+  'booking_detail',
+  '{"subscribe": ["@user_id"]}'::jsonb,
+  '{"booking_id": "int"}'::jsonb,
+  'bookings',
+  '{
+    "venue": "venues",
+    "customer": "users",
+    "items": {"entity": "booking_items", "filter": "booking_id=$booking_id"}
+  }'::jsonb
+);
+```
+
+**Multiple Permission Paths (OR logic):**
+```sql
+SELECT dzql.register_subscribable(
+  'venue_admin',
+  '{
+    "subscribe": [
+      "@owner_id",
+      "@org_id->acts_for[org_id=$]{active}.user_id"
+    ]
+  }'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',
+  '{"sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb
+);
+```
+
+### See Also
+
+- **[Live Query Subscriptions Guide](../../../docs/LIVE_QUERY_SUBSCRIPTIONS.md)** - Complete reference
+- **[Quick Start Guide](../../../docs/SUBSCRIPTIONS_QUICK_START.md)** - 5-minute tutorial
+- **[Permission Paths](#permission--notification-paths)** - Path DSL syntax
+
+---
+
 ## Temporal Relationships
 
 Handle time-based relationships with `valid_from`/`valid_to` fields.

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "dzql",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
   "exports": {
     ".": "./src/server/index.js",
     "./client": "./src/client/ws.js",
+    "./client/stores": "./src/client/stores/index.js",
+    "./client/templates": "./src/client/templates/App.vue",
     "./server": "./src/server/index.js",
     "./db": "./src/server/db.js",
     "./compiler": "./src/compiler/index.js"
@@ -20,12 +22,13 @@
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.1.5...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.2.0...'"
   },
   "dependencies": {
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
+
   "keywords": [
     "postgresql",
     "postgres",

package/src/client/stores/README.md

@@ -0,0 +1,95 @@
+# 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

package/src/client/stores/index.js

@@ -0,0 +1,8 @@
+/**
+ * DZQL Client Stores
+ *
+ * Canonical Pinia stores for DZQL applications
+ */
+
+export { useWsStore } from './useWsStore.js'
+export { useAppStore } from './useAppStore.js'

package/src/client/stores/useAppStore.js

@@ -0,0 +1,285 @@
+/**
+ * Canonical DZQL App Pinia Store
+ *
+ * Manages application-level state including:
+ * - App initialization
+ * - Router integration
+ * - Global UI state
+ * - Entity metadata caching
+ *
+ * Works with useWsStore to provide complete app lifecycle management.
+ *
+ * @example
+ * // In main.js
+ * import { createApp } from 'vue'
+ * import { createPinia } from 'pinia'
+ * import { useAppStore } from 'dzql/client/stores'
+ * import App from './App.vue'
+ *
+ * const pinia = createPinia()
+ * const app = createApp(App)
+ * app.use(pinia)
+ *
+ * const appStore = useAppStore()
+ * await appStore.initialize()
+ *
+ * app.mount('#app')
+ */
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import { useWsStore } from './useWsStore.js'
+
+export const useAppStore = defineStore('dzql-app', () => {
+  // ===== State =====
+
+  /**
+   * App title
+   */
+  const title = ref('DZQL App')
+
+  /**
+   * Current route/entity context
+   */
+  const currentEntity = ref(null)
+  const currentId = ref(null)
+
+  /**
+   * Entity metadata cache
+   * Maps entity name -> metadata object
+   */
+  const entityMetadata = ref({})
+
+  /**
+   * Loading states
+   */
+  const isLoadingMetadata = ref(false)
+
+  /**
+   * UI state
+   */
+  const sidebarOpen = ref(true)
+  const propertiesPanelOpen = ref(true)
+
+  /**
+   * Router instance (set via setRouter)
+   */
+  let routerInstance = null
+
+  // ===== Computed =====
+
+  const hasMetadata = computed(() => Object.keys(entityMetadata.value).length > 0)
+
+  const entityList = computed(() => {
+    return Object.keys(entityMetadata.value).sort()
+  })
+
+  const currentEntityMeta = computed(() => {
+    if (!currentEntity.value) return null
+    return entityMetadata.value[currentEntity.value] || null
+  })
+
+  // ===== Actions =====
+
+  /**
+   * Initialize the app
+   *
+   * Connects to WebSocket and sets up app lifecycle.
+   *
+   * @param {Object} options
+   * @param {string} [options.wsUrl] - WebSocket URL (auto-detected if not provided)
+   * @param {string} [options.title] - App title
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await appStore.initialize()
+   *
+   * @example
+   * await appStore.initialize({
+   *   wsUrl: 'ws://localhost:3000/ws',
+   *   title: 'My DZQL App'
+   * })
+   */
+  async function initialize(options = {}) {
+    const wsStore = useWsStore()
+
+    // Set app title if provided
+    if (options.title) {
+      title.value = options.title
+    }
+
+    // Connect to WebSocket
+    await wsStore.connect(options.wsUrl)
+
+    // If authenticated, fetch metadata
+    if (wsStore.isAuthenticated) {
+      await fetchMetadata()
+    }
+
+    console.log('[AppStore] Initialized')
+  }
+
+  /**
+   * Fetch entity metadata from server
+   *
+   * Called automatically after authentication.
+   *
+   * @returns {Promise<void>}
+   */
+  async function fetchMetadata() {
+    const wsStore = useWsStore()
+    const ws = wsStore.getWs()
+
+    if (!wsStore.isConnected) {
+      console.warn('[AppStore] Cannot fetch metadata: not connected')
+      return
+    }
+
+    try {
+      isLoadingMetadata.value = true
+
+      // Call the meta endpoint
+      const result = await ws.call('meta')
+
+      if (result && result.entities) {
+        entityMetadata.value = result.entities
+        console.log('[AppStore] Metadata loaded:', Object.keys(result.entities))
+      }
+
+    } catch (err) {
+      console.error('[AppStore] Failed to fetch metadata:', err)
+    } finally {
+      isLoadingMetadata.value = false
+    }
+  }
+
+  /**
+   * Set the router instance
+   *
+   * Call this in main.js after creating the router to enable
+   * programmatic navigation from the store.
+   *
+   * @param {Router} router - Vue Router instance
+   *
+   * @example
+   * import { createRouter } from 'vue-router'
+   * import { useAppStore } from 'dzql/client/stores'
+   *
+   * const router = createRouter({ ... })
+   * const appStore = useAppStore()
+   * appStore.setRouter(router)
+   */
+  function setRouter(router) {
+    routerInstance = router
+
+    // Watch route changes to update current context
+    if (router) {
+      router.afterEach((to) => {
+        currentEntity.value = to.params.entity || null
+        currentId.value = to.params.id || null
+      })
+    }
+  }
+
+  /**
+   * Navigate to entity list
+   *
+   * @param {string} entity - Entity name
+   *
+   * @example
+   * appStore.navigateToEntity('venues')
+   */
+  function navigateToEntity(entity) {
+    if (routerInstance) {
+      routerInstance.push({ name: 'entity-list', params: { entity } })
+    }
+    currentEntity.value = entity
+    currentId.value = null
+  }
+
+  /**
+   * Navigate to entity detail/edit
+   *
+   * @param {string} entity - Entity name
+   * @param {number|string} id - Record ID or 'new'
+   *
+   * @example
+   * appStore.navigateToEntityDetail('venues', 123)
+   * appStore.navigateToEntityDetail('venues', 'new')
+   */
+  function navigateToEntityDetail(entity, id) {
+    if (routerInstance) {
+      const routeName = id === 'new' ? 'entity-create' : 'entity-edit'
+      routerInstance.push({ name: routeName, params: { entity, id } })
+    }
+    currentEntity.value = entity
+    currentId.value = id
+  }
+
+  /**
+   * Navigate to home
+   *
+   * @example
+   * appStore.navigateToHome()
+   */
+  function navigateToHome() {
+    if (routerInstance) {
+      routerInstance.push({ name: 'home' })
+    }
+    currentEntity.value = null
+    currentId.value = null
+  }
+
+  /**
+   * Toggle sidebar
+   */
+  function toggleSidebar() {
+    sidebarOpen.value = !sidebarOpen.value
+  }
+
+  /**
+   * Toggle properties panel
+   */
+  function togglePropertiesPanel() {
+    propertiesPanelOpen.value = !propertiesPanelOpen.value
+  }
+
+  /**
+   * Set current context (useful for manual navigation)
+   *
+   * @param {string|null} entity - Entity name
+   * @param {number|string|null} id - Record ID
+   */
+  function setContext(entity, id = null) {
+    currentEntity.value = entity
+    currentId.value = id
+  }
+
+  // ===== Return Public API =====
+
+  return {
+    // State
+    title,
+    currentEntity,
+    currentId,
+    entityMetadata,
+    isLoadingMetadata,
+    sidebarOpen,
+    propertiesPanelOpen,
+
+    // Computed
+    hasMetadata,
+    entityList,
+    currentEntityMeta,
+
+    // Actions
+    initialize,
+    fetchMetadata,
+    setRouter,
+    navigateToEntity,
+    navigateToEntityDetail,
+    navigateToHome,
+    toggleSidebar,
+    togglePropertiesPanel,
+    setContext
+  }
+})