dzql 0.6.3 → 0.6.6

package/README.md

@@ -0,0 +1,33 @@
+# DZQL
+
+Database-first real-time framework with TypeScript support.
+
+## Quick Start
+
+```bash
+bun create dzql my-app
+cd my-app
+bun install
+bun run db:rebuild
+bun run dev
+```
+
+## Documentation
+
+See the [full documentation](./docs/README.md) for:
+
+- [Project Setup Guide](./docs/project-setup.md)
+- [AI Assistant Guide](./docs/for_ai.md)
+
+## Package Exports
+
+```typescript
+import { createServer } from 'dzql';           // Runtime server
+import { ws } from 'dzql/client';              // WebSocket client  
+import { compile } from 'dzql/compiler';       // CLI compiler
+import { DzqlNamespace } from 'dzql/namespace'; // Direct DB access
+```
+
+## License
+
+MIT

package/docs/for_ai.md

@@ -535,28 +535,24 @@ When a client connects to the WebSocket server, it immediately receives a `conne
 ### WebSocketManager API
 
 ```typescript
-import { WebSocketManager } from 'dzql/client';
+import { ws } from '@generated/client/ws';
 
-const ws = new WebSocketManager();
-await ws.connect('ws://localhost:3000/ws');
+await ws.connect('/ws');
 
-// Connection state properties
-ws.ready  // boolean - true after connection:ready received
-ws.user   // user profile object or null if anonymous
+// Authentication via typed API
+const user = await ws.api.login_user({ email: '...', password: '...' });
+// Token is returned in response - store in localStorage
+if (user.token) {
+  localStorage.setItem('dzql_token', user.token);
+}
 
-// Register callback for ready state (called immediately if already ready)
-const unsubscribe = ws.onReady((user) => {
-  if (user) {
-    console.log('Authenticated as:', user.email);
-  } else {
-    console.log('Anonymous connection');
-  }
-});
+const newUser = await ws.api.register_user({ name: '...', email: '...', password: '...' });
+// Token is returned in response
 
-// Authentication methods
-await ws.login({ email: '...', password: '...' });   // Stores token in localStorage
-await ws.register({ email: '...', password: '...' }); // Stores token in localStorage
-await ws.logout();  // Clears token, user state, and reconnects
+// Logout - clear token and disconnect
+localStorage.removeItem('dzql_token');
+ws.disconnect();
+await ws.connect('/ws');  // Reconnect without token
 ```
 
 ### Vue/Pinia Usage Pattern

package/docs/project-setup.md

@@ -231,7 +231,7 @@ export default defineConfig({
 
 ```typescript
 import { ref } from 'vue'
-import { ws } from '@generated/client'
+import { ws } from '@generated/client/ws'
 
 const ready = ref(false)
 const user = ref<any>(null)
@@ -242,16 +242,9 @@ export function useDzql() {
     try {
       connectionError.value = null
       ready.value = false
-      
-      ws.onReady((profile: any) => {
-        if (!profile && localStorage.getItem('token')) {
-          localStorage.removeItem('token')
-        }
-        user.value = profile
-        ready.value = true
-      })
-      
-      await ws.connect(url)
+
+      await ws.connect(url || '/ws')
+      ready.value = true
     } catch (e: any) {
       connectionError.value = e.message
       throw e
@@ -259,24 +252,32 @@ export function useDzql() {
   }
 
   async function login(email: string, password: string) {
-    const result = await ws.login({ email, password })
+    const result = await ws.api.login_user({ email, password }) as any
     if (result?.user_id) {
       user.value = result
+      if (result.token) {
+        localStorage.setItem('dzql_token', result.token)
+      }
     }
     return result
   }
 
   async function register(name: string, email: string, password: string) {
-    const result = await ws.register({ name, email, password })
+    const result = await ws.api.register_user({ name, email, password }) as any
     if (result?.user_id) {
       user.value = result
+      if (result.token) {
+        localStorage.setItem('dzql_token', result.token)
+      }
     }
     return result
   }
 
   async function logout() {
-    await ws.logout()
+    localStorage.removeItem('dzql_token')
     user.value = null
+    ws.disconnect()
+    await connect()
   }
 
   return { ws, ready, user, connectionError, connect, login, register, logout }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.6.3",
+  "version": "0.6.6",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",
@@ -10,17 +10,36 @@
   "bin": {
     "dzql": "./src/cli/index.ts"
   },
-  "scripts": {
-    "dev": "bun run src/cli/index.ts",
-    "test": "bun test",
-    "build": "bun build ./src/cli/index.ts --outdir ./dist/cli --target node"
-  },
   "exports": {
     ".": "./src/runtime/index.ts",
     "./client": "./src/client/index.ts",
     "./compiler": "./src/cli/index.ts",
     "./namespace": "./src/runtime/namespace.ts"
   },
+  "files": [
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "postgresql",
+    "postgres",
+    "websocket",
+    "real-time",
+    "realtime",
+    "database",
+    "bun",
+    "vue",
+    "pinia",
+    "typescript",
+    "compiler",
+    "codegen"
+  ],
+  "author": "Peter Bunyan",
+  "license": "MIT",
   "dependencies": {
     "postgres": "^3.4.3",
     "dotenv": "^16.4.5",
@@ -34,5 +53,8 @@
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   }
 }

package/src/cli/codegen/client.ts

@@ -35,8 +35,7 @@ export function generateClientSDK(manifest: Manifest): string {
     if (isSubscription) {
       // subscribe_venue_detail -> VenueDetailParams
       paramType = `${pascalEntity}Params`;
-      returnType = 'void';
-      return `  ${funcName}: (params: ${paramType}, callback: (data: unknown) => void) => Promise<() => ${returnType}>;`;
+      return `  ${funcName}: (params: ${paramType}, callback: (data: unknown) => void) => Promise<{ data: unknown; subscription_id: string; schema: unknown; unsubscribe: () => Promise<void> }>;`;
     } else if (op === 'get' && entityExists) {
       // get_venue_detail (subscribable getter) vs get_venues (entity getter)
       if (manifest.subscribables?.[entity]) {
@@ -78,16 +77,16 @@ ${apiMethods}
 
 /** Extended WebSocket manager with typed API */
 export class GeneratedWebSocketManager extends WebSocketManager {
-  api: DzqlAPI;
+  declare api: DzqlAPI;
 
-  constructor(options: { url?: string; reconnect?: boolean } = {}) {
+  constructor(options: { maxReconnectAttempts?: number; tokenName?: string } = {}) {
     super(options);
     this.api = {
 ${regularFunctions.map(([funcName]) =>
-      `      ${funcName}: (params: Record<string, unknown>) => this.call('${funcName}', params),`
+      `      ${funcName}: (params: any) => this.call('${funcName}', params),`
 ).join('\n')}
 ${subscriptionFunctions.map(([funcName]) =>
-      `      ${funcName}: (params: Record<string, unknown>, callback: (data: unknown) => void) => this.subscribe('${funcName}', params, callback),`
+      `      ${funcName}: (params: any, callback: (data: any) => void) => this.subscribe('${funcName}', params, callback),`
 ).join('\n')}
     } as DzqlAPI;
   }

package/src/cli/codegen/subscribable_store.ts

@@ -59,8 +59,8 @@ export function generateSubscribableStore(manifest: Manifest, subName: string):
 
           cases.push(
             `      case '${entityName}':\n` +
-            `        if (event.data && event.data.${fkField}) {\n` +
-            `          const parent = doc.${level1Rel}?.find((p: { id: number }) => p.id === event.data.${fkField});\n` +
+            `        if (event.data && (event.data as any).${fkField}) {\n` +
+            `          const parent = (doc.${level1Rel} as any[])?.find((p: any) => p.id === (event.data as any).${fkField});\n` +
             `          if (parent && parent.${key}) {\n` +
             `            handleArrayPatch(parent.${key}, event);\n` +
             `          }\n` +
@@ -164,15 +164,15 @@ ${patchCases}
     }
   }
 
-  function handleArrayPatch(arr: unknown[] | undefined, event: PatchEvent): void {
+  function handleArrayPatch(arr: any, event: PatchEvent): void {
     if (!arr || !Array.isArray(arr)) return;
     const pkValue = event.pk?.id;
-    const idx = arr.findIndex((i: unknown) => (i as { id: number }).id === pkValue);
+    const idx = arr.findIndex((i: any) => i?.id === pkValue);
 
     if (event.op === 'insert') {
       if (idx === -1 && event.data) arr.push(event.data);
     } else if (event.op === 'update') {
-      if (idx !== -1 && event.data) Object.assign(arr[idx] as object, event.data);
+      if (idx !== -1 && event.data) Object.assign(arr[idx], event.data);
     } else if (event.op === 'delete') {
       if (idx !== -1) arr.splice(idx, 1);
     }

package/src/runtime/ws.ts

@@ -3,6 +3,9 @@ import { handleRequest } from "./server.js"; // The secure router
 import { verifyToken, signToken } from "./auth.js";
 import { Database } from "./db.js";
 
+// WebSocket configuration
+const WS_MAX_MESSAGE_SIZE = parseInt(process.env.WS_MAX_MESSAGE_SIZE || "1048576", 10); // 1MB default
+
 interface WSContext {
   id: string;
   userId?: number;
@@ -17,13 +20,17 @@ export class WebSocketServer {
 
   constructor(db: Database) {
     this.db = db;
-    // Start heartbeat interval
-    setInterval(() => this.heartbeat(), 30000);
   }
 
-  // Bun.serve websocket handler hooks
-  get handlers() {
+  // Bun.serve websocket configuration object
+  get websocket() {
     return {
+      // WebSocket options for Bun
+      perMessageDeflate: true,
+      maxPayloadLength: WS_MAX_MESSAGE_SIZE,
+      idleTimeout: 0, // No idle timeout - realtime connections stay open indefinitely
+
+      // Handler hooks
       open: (ws: ServerWebSocket<WSContext>) => this.handleOpen(ws),
       message: (ws: ServerWebSocket<WSContext>, message: string) => this.handleMessage(ws, message),
       close: (ws: ServerWebSocket<WSContext>) => this.handleClose(ws),
@@ -31,6 +38,11 @@ export class WebSocketServer {
     };
   }
 
+  // Legacy alias for backwards compatibility
+  get handlers() {
+    return this.websocket;
+  }
+
   private async handleOpen(ws: ServerWebSocket<WSContext>) {
     const id = Math.random().toString(36).slice(2);
     const token = ws.data?.token;
@@ -173,17 +185,6 @@ export class WebSocketServer {
     console.log(`[WS] Client ${ws.data.id} disconnected`);
   }
 
-  private heartbeat() {
-    const now = Date.now();
-    for (const [id, ws] of this.connections) {
-        if (now - ws.data.lastPing > 60000) {
-            console.log(`[WS] Client ${id} timed out`);
-            ws.close();
-            this.connections.delete(id);
-        }
-    }
-  }
-
   public broadcast(message: string) {
       // Use Bun's native publish for efficiency
       // 'broadcast' topic is subscribed by all on connect

package/.env.sample

@@ -1,28 +0,0 @@
-# TZQL Environment Variables
-# Copy this file to .env and modify as needed
-
-# ===================
-# Server (Runtime)
-# ===================
-
-# PostgreSQL connection string
-DATABASE_URL=postgres://user:password@localhost:5432/database
-
-# Server port
-PORT=3000
-
-# Path to compiled manifest (relative to working directory)
-MANIFEST_PATH=./dist/runtime/manifest.json
-
-# JWT secret for authentication (CHANGE IN PRODUCTION!)
-JWT_SECRET=your-secure-secret-key-here
-
-# ===================
-# Client (Browser)
-# ===================
-# These are injected at build time by your bundler (Vite, Webpack, etc.)
-
-# Token name for localStorage (Vite: prefix with VITE_)
-# VITE_TZQL_TOKEN_NAME=myapp_token
-# Or for other bundlers:
-# TZQL_TOKEN_NAME=myapp_token

package/compose.yml

@@ -1,28 +0,0 @@
-services:
-  postgres:
-    image: postgres:16-alpine
-    container_name: tzql-test-db
-    environment:
-      POSTGRES_USER: dzql_test
-      POSTGRES_PASSWORD: dzql_test
-      POSTGRES_DB: dzql_test
-    ports:
-      - "5433:5432" # Map container's 5432 to host's 5433
-    volumes:
-      - tzql-test-data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U dzql_test -d dzql_test"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-    command:
-      - "postgres"
-      - "-c"
-      - "log_statement=all"
-      - "-c"
-      - "log_destination=stderr"
-      - "-c"
-      - "logging_collector=off"
-
-volumes:
-  tzql-test-data:

package/dist/client/index.ts

@@ -1 +0,0 @@
-export * from './ws.js';

package/dist/client/stores/useMyProfileStore.ts

@@ -1,114 +0,0 @@
-// Generated by DZQL Compiler v2.0.0
-// Do not edit this file directly.
-
-import { defineStore } from 'pinia';
-import { ref, type Ref } from 'vue';
-import { ws } from '../index.js';
-
-/** Parameters for my_profile subscription */
-export interface MyProfileParams {
-  [key: string]: unknown;
-}
-
-/** Event from server for patching */
-export interface PatchEvent {
-  table: string;
-  op: 'insert' | 'update' | 'delete';
-  pk: { id: number };
-  data: Record<string, unknown> | null;
-}
-
-/** Document wrapper with loading state */
-export interface DocumentWrapper<T> {
-  data: T;
-  loading: boolean;
-  ready: Promise<void>;
-}
-
-export const useMyProfileStore = defineStore('sub-my_profile', () => {
-  const documents: Ref<Record<string, DocumentWrapper<Record<string, unknown>>>> = ref({});
-  const unsubscribers = new Map<string, () => void>();
-
-  async function bind(params: MyProfileParams): Promise<DocumentWrapper<Record<string, unknown>>> {
-    const key = JSON.stringify(params);
-
-    if (documents.value[key]) {
-      const existing = documents.value[key];
-      if (existing.loading) {
-        await existing.ready;
-      }
-      return existing;
-    }
-
-    let resolveReady!: () => void;
-    const ready = new Promise<void>((resolve) => { resolveReady = resolve; });
-
-    documents.value[key] = { data: {}, loading: true, ready };
-    let isFirst = true;
-
-    const unsubscribe = await ws.api.subscribe_my_profile(params, (eventData: unknown) => {
-      if (isFirst) {
-        // Initial data - merge into existing object to preserve reactivity
-        Object.assign(documents.value[key].data, eventData as Record<string, unknown>);
-        documents.value[key].loading = false;
-        isFirst = false;
-        resolveReady();
-      } else {
-        // Patch event
-        applyPatch(documents.value[key].data, eventData as PatchEvent);
-      }
-    });
-
-    unsubscribers.set(key, unsubscribe as () => void);
-    await ready;
-    return documents.value[key];
-  }
-
-  function unbind(params: MyProfileParams): void {
-    const key = JSON.stringify(params);
-    const unsubscribe = unsubscribers.get(key);
-    if (unsubscribe) {
-      unsubscribe();
-      unsubscribers.delete(key);
-      delete documents.value[key];
-    }
-  }
-
-  function applyPatch(doc: Record<string, unknown>, event: PatchEvent): void {
-    if (!doc) return;
-    switch (event.table) {
-      case 'users':
-        if (event.op === 'update' && doc.users) {
-          Object.assign(doc.users, event.data);
-        }
-        break;
-      case 'acts_for':
-        handleArrayPatch(doc.memberships, event);
-        break;
-      case 'organisations':
-        if (event.data && event.data.membership_id) {
-          const parent = doc.memberships?.find((p: { id: number }) => p.id === event.data.membership_id);
-          if (parent && parent.org) {
-            handleArrayPatch(parent.org, event);
-          }
-        }
-        break;
-    }
-  }
-
-  function handleArrayPatch(arr: unknown[] | undefined, event: PatchEvent): void {
-    if (!arr || !Array.isArray(arr)) return;
-    const pkValue = event.pk?.id;
-    const idx = arr.findIndex((i: unknown) => (i as { id: number }).id === pkValue);
-
-    if (event.op === 'insert') {
-      if (idx === -1 && event.data) arr.push(event.data);
-    } else if (event.op === 'update') {
-      if (idx !== -1 && event.data) Object.assign(arr[idx] as object, event.data);
-    } else if (event.op === 'delete') {
-      if (idx !== -1) arr.splice(idx, 1);
-    }
-  }
-
-  return { bind, unbind, documents };
-});

package/dist/client/stores/useOrgDashboardStore.ts

@@ -1,131 +0,0 @@
-// Generated by DZQL Compiler v2.0.0
-// Do not edit this file directly.
-
-import { defineStore } from 'pinia';
-import { ref, type Ref } from 'vue';
-import { ws } from '../index.js';
-
-/** Parameters for org_dashboard subscription */
-export interface OrgDashboardParams {
-  org_id: number;
-}
-
-/** Event from server for patching */
-export interface PatchEvent {
-  table: string;
-  op: 'insert' | 'update' | 'delete';
-  pk: { id: number };
-  data: Record<string, unknown> | null;
-}
-
-/** Document wrapper with loading state */
-export interface DocumentWrapper<T> {
-  data: T;
-  loading: boolean;
-  ready: Promise<void>;
-}
-
-export const useOrgDashboardStore = defineStore('sub-org_dashboard', () => {
-  const documents: Ref<Record<string, DocumentWrapper<Record<string, unknown>>>> = ref({});
-  const unsubscribers = new Map<string, () => void>();
-
-  async function bind(params: OrgDashboardParams): Promise<DocumentWrapper<Record<string, unknown>>> {
-    const key = JSON.stringify(params);
-
-    if (documents.value[key]) {
-      const existing = documents.value[key];
-      if (existing.loading) {
-        await existing.ready;
-      }
-      return existing;
-    }
-
-    let resolveReady!: () => void;
-    const ready = new Promise<void>((resolve) => { resolveReady = resolve; });
-
-    documents.value[key] = { data: {}, loading: true, ready };
-    let isFirst = true;
-
-    const unsubscribe = await ws.api.subscribe_org_dashboard(params, (eventData: unknown) => {
-      if (isFirst) {
-        // Initial data - merge into existing object to preserve reactivity
-        Object.assign(documents.value[key].data, eventData as Record<string, unknown>);
-        documents.value[key].loading = false;
-        isFirst = false;
-        resolveReady();
-      } else {
-        // Patch event
-        applyPatch(documents.value[key].data, eventData as PatchEvent);
-      }
-    });
-
-    unsubscribers.set(key, unsubscribe as () => void);
-    await ready;
-    return documents.value[key];
-  }
-
-  function unbind(params: OrgDashboardParams): void {
-    const key = JSON.stringify(params);
-    const unsubscribe = unsubscribers.get(key);
-    if (unsubscribe) {
-      unsubscribe();
-      unsubscribers.delete(key);
-      delete documents.value[key];
-    }
-  }
-
-  function applyPatch(doc: Record<string, unknown>, event: PatchEvent): void {
-    if (!doc) return;
-    switch (event.table) {
-      case 'organisations':
-        if (event.op === 'update' && doc.organisations) {
-          Object.assign(doc.organisations, event.data);
-        }
-        break;
-      case 'venues':
-        handleArrayPatch(doc.venues, event);
-        break;
-      case 'sites':
-        if (event.data && event.data.venue_id) {
-          const parent = doc.venues?.find((p: { id: number }) => p.id === event.data.venue_id);
-          if (parent && parent.sites) {
-            handleArrayPatch(parent.sites, event);
-          }
-        }
-        break;
-      case 'products':
-        handleArrayPatch(doc.products, event);
-        break;
-      case 'packages':
-        handleArrayPatch(doc.packages, event);
-        break;
-      case 'brands':
-        handleArrayPatch(doc.brands, event);
-        break;
-      case 'artwork':
-        if (event.data && event.data.brand_id) {
-          const parent = doc.brands?.find((p: { id: number }) => p.id === event.data.brand_id);
-          if (parent && parent.artwork) {
-            handleArrayPatch(parent.artwork, event);
-          }
-        }
-        break;
-    }
-  }
-
-  function handleArrayPatch(arr: unknown[] | undefined, event: PatchEvent): void {
-    if (!arr || !Array.isArray(arr)) return;
-    const pkValue = event.pk?.id;
-    const idx = arr.findIndex((i: unknown) => (i as { id: number }).id === pkValue);
-
-    if (event.op === 'insert') {
-      if (idx === -1 && event.data) arr.push(event.data);
-    } else if (event.op === 'update') {
-      if (idx !== -1 && event.data) Object.assign(arr[idx] as object, event.data);
-    } else if (event.op === 'delete') {
-      if (idx !== -1) arr.splice(idx, 1);
-    }
-  }
-
-  return { bind, unbind, documents };
-});