dzql 0.6.2 → 0.6.5

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.2",
+  "version": "0.6.5",
   "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_sql.ts

@@ -223,7 +223,7 @@ function generateGetFunction(name: string, sub: SubscribableIR, entities: Record
   // Handle special @user_id root key
   const rootKey = sub.root.key;
   const isUserIdRoot = rootKey === '@user_id';
-  const rootWhereValue = isUserIdRoot ? 'p_user_id' : `v_${rootKey}`;
+  const isList = !rootKey; // No key means it's a list subscribable
 
   // Build root select expression excluding hidden fields
   const rootSelectExpr = buildVisibleRowJson('root', sub.root.entity, entities);
@@ -239,7 +239,67 @@ function generateGetFunction(name: string, sub: SubscribableIR, entities: Record
     scopeTables: sub.scopeTables
   }).replace(/'/g, "''"); // Escape single quotes for SQL
 
-  return `CREATE OR REPLACE FUNCTION dzql_v2.get_${name}(
+  // Build WHERE clause based on root filter and key
+  const whereConditions: string[] = [];
+  if (rootKey) {
+    const rootWhereValue = isUserIdRoot ? 'p_user_id' : `v_${rootKey}`;
+    whereConditions.push(`root.id = ${rootWhereValue}`);
+  }
+  if (sub.root.filter) {
+    for (const [field, value] of Object.entries(sub.root.filter)) {
+      if (typeof value === 'boolean') {
+        whereConditions.push(`root.${field} = ${value}`);
+      } else if (typeof value === 'string') {
+        whereConditions.push(`root.${field} = '${value}'`);
+      } else {
+        whereConditions.push(`root.${field} = ${value}`);
+      }
+    }
+  }
+  const whereClause = whereConditions.length > 0
+    ? `WHERE ${whereConditions.join(' AND ')}`
+    : '';
+
+  if (isList) {
+    // List subscribable - return array of records with nested includes
+    return `CREATE OR REPLACE FUNCTION dzql_v2.get_${name}(
+  p_params JSONB,
+  p_user_id INT
+) RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = dzql_v2, public
+AS $$
+DECLARE
+${paramDecls}
+  v_data JSONB;
+BEGIN
+  -- Extract parameters
+${paramExtracts}
+
+  -- Check access control
+  IF NOT dzql_v2.${name}_can_subscribe(p_user_id, p_params) THEN
+    RAISE EXCEPTION 'permission_denied';
+  END IF;
+
+  -- Build list of documents with nested relations
+  SELECT COALESCE(jsonb_agg(
+    to_jsonb(root.*) || jsonb_build_object(${relationSelects ? relationSelects.slice(1) : ''})
+  ), '[]'::jsonb)
+  INTO v_data
+  FROM ${sub.root.entity} root
+  ${whereClause};
+
+  -- Return data with embedded schema for atomic updates
+  RETURN jsonb_build_object(
+    '${sub.root.entity}', v_data,
+    'schema', '${schemaJson}'::jsonb
+  );
+END;
+$$;`;
+  } else {
+    // Single record subscribable
+    return `CREATE OR REPLACE FUNCTION dzql_v2.get_${name}(
   p_params JSONB,
   p_user_id INT
 ) RETURNS JSONB
@@ -265,7 +325,7 @@ ${paramExtracts}
   )
   INTO v_data
   FROM ${sub.root.entity} root
-  WHERE root.id = ${rootWhereValue};
+  ${whereClause};
 
   -- Return data with embedded schema for atomic updates
   RETURN jsonb_build_object(
@@ -274,6 +334,7 @@ ${paramExtracts}
   );
 END;
 $$;`;
+  }
 }
 
 function singularize(name: string): string {

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;
@@ -148,6 +160,8 @@ export class WebSocketServer {
              // Auto-generate token for auth methods
              if (req.method === 'login_user' || req.method === 'register_user') {
                  const token = await signToken({ user_id: result.user_id, role: 'user' });
+                 // Update connection's userId for subsequent calls
+                 ws.data.userId = result.user_id;
                  // Return profile + token
                  ws.send(JSON.stringify({ id: req.id, result: { ...result, token } }));
              } else {
@@ -171,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/examples/blog.ts

@@ -1,50 +0,0 @@
-// TZQL Entity Definition Example
-
-export const entities = {
-  posts: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      title: 'text NOT NULL',
-      content: 'text',
-      author_id: 'int NOT NULL', // In a real app, this would reference users(id)
-      created_at: 'timestamptz DEFAULT now()'
-    },
-    permissions: {
-      view: [], // Public
-      create: ['@author_id == @user_id'], // Only create for self
-      update: ['@author_id == @user_id'], // Only owner
-      delete: ['@author_id == @user_id']  // Only owner
-    },
-    graphRules: {
-      on_create: {
-        actions: [
-          { type: 'reactor', name: 'notify_subscribers', params: { post_id: '@id' } }
-        ]
-      }
-    }
-  },
-  comments: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      post_id: 'int NOT NULL REFERENCES posts(id) ON DELETE CASCADE',
-      content: 'text NOT NULL',
-      author_id: 'int NOT NULL'
-    },
-    permissions: {
-      view: [],
-      create: [],
-      delete: ['@author_id == @user_id']
-    }
-  }
-};
-
-export const subscribables = {
-  post_detail: {
-    params: { post_id: 'int' },
-    root: { entity: 'posts', key: 'post_id' },
-    includes: {
-      comments: { entity: 'comments', filter: { post_id: '@id' } }
-    },
-    scopeTables: ['posts', 'comments']
-  }
-};

package/examples/invalid.ts

@@ -1,18 +0,0 @@
-// TZQL Entity Definition Example (INVALID)
-
-export const entities = {
-  posts: {
-    schema: { id: 'serial PRIMARY KEY' },
-    permissions: {}
-  }
-};
-
-export const subscribables = {
-  broken_feed: {
-    params: {},
-    root: { entity: 'posts' },
-    includes: {
-      comments: { entity: 'missing_table' } // <--- Error: 'missing_table' does not exist
-    }
-  }
-};