dzql 0.5.32 → 0.6.0

package/src/cli/index.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+import { loadDomain } from "./compiler/loader.js";
+import { analyzeDomain } from "./compiler/analyzer.js";
+import { generateIR } from "./compiler/ir.js";
+import { generateCoreSQL, generateEntitySQL, generateSchemaSQL } from "./codegen/sql.js";
+import { generateSubscribableSQL } from "./codegen/subscribable_sql.js";
+import { generateManifest } from "./codegen/manifest.js";
+import { generateSubscribableStore } from "./codegen/subscribable_store.js";
+import { generateClientSDK } from "./codegen/client.js";
+import { writeFileSync, mkdirSync, copyFileSync, rmSync } from "fs";
+import { resolve, dirname } from "path";
+
+const args = process.argv.slice(2);
+const command = args[0];
+const input = args[1];
+let outputDir = "dist"; // Default output directory
+
+// Parse optional output directory flag
+const outputFlagIndex = args.indexOf('-o');
+const longOutputFlagIndex = args.indexOf('--output');
+
+if (outputFlagIndex > -1 && args[outputFlagIndex + 1]) {
+  outputDir = args[outputFlagIndex + 1];
+} else if (longOutputFlagIndex > -1 && args[longOutputFlagIndex + 1]) {
+  outputDir = args[longOutputFlagIndex + 1];
+}
+
+async function main() {
+  console.log("TZQL Compiler v0.0.1");
+
+  if (command === "compile") {
+    if (!input) {
+      console.error("Usage: tzql compile <file>");
+      process.exit(1);
+    }
+
+    try {
+      // Phase 1: Load & Analyze
+      const fullInputPath = resolve(process.cwd(), input);
+
+      // Clean Output Directory
+      const absOutputDir = resolve(process.cwd(), outputDir);
+      console.log(`[Compiler] Cleaning ${absOutputDir}...`);
+      try {
+        rmSync(absOutputDir, { recursive: true, force: true });
+      } catch (e) { /* ignore */ }
+
+      const domain = await loadDomain(fullInputPath);
+      console.log("[Compiler] Domain loaded.");
+
+      const errors = analyzeDomain(domain);
+      if (errors.length > 0) {
+        console.error("[Compiler] Validation Failed:");
+        errors.forEach(err => console.error(`  - ${err}`));
+        process.exit(1);
+      }
+
+      // Phase 2: Generate IR
+      const ir = generateIR(domain);
+      console.log(`[Compiler] IR Generated. Subscribables: ${Object.keys(ir.subscribables).join(', ')}`);
+
+      // Phase 3: Generate SQL
+      const coreSQL = generateCoreSQL();
+      const entitySQL: string[] = [];
+      for (const [name, entityIR] of Object.entries(ir.entities)) {
+        entitySQL.push(generateSchemaSQL(name, entityIR));
+        // Skip CRUD generation for unmanaged entities (e.g., junction tables)
+        if (entityIR.managed !== false) {
+          entitySQL.push(generateEntitySQL(name, entityIR));
+        } else {
+          console.log(`[Compiler] Skipping CRUD for unmanaged entity: ${name}`);
+        }
+      }
+
+      // Generate subscribable SQL functions
+      const subscribableSQL: string[] = [];
+      for (const [name, subIR] of Object.entries(ir.subscribables)) {
+        console.log(`[Compiler] Generating SQL for subscribable: ${name}`);
+        subscribableSQL.push(generateSubscribableSQL(name, subIR as any, ir.entities));
+      }
+
+      // Collect custom functions SQL
+      const customFunctionSQL: string[] = [];
+      for (const fn of ir.customFunctions) {
+        console.log(`[Compiler] Adding custom function: ${fn.name}`);
+        customFunctionSQL.push(fn.sql);
+      }
+
+      // Phase 4: Generate Manifest
+      const manifest = generateManifest(ir);
+      console.log(`[Compiler] Manifest functions: ${Object.keys(manifest.functions).length}`);
+      if (!manifest.functions['subscribe_venue_detail']) {
+          console.error("[Compiler] ERROR: subscribe_venue_detail missing from manifest functions!");
+      }
+
+      // --- OUTPUT GENERATION ---
+
+      // 1. Database
+      const dbDir = resolve(outputDir, "db/migrations");
+      mkdirSync(dbDir, { recursive: true });
+
+      writeFileSync(resolve(dbDir, `000_core.sql`), coreSQL);
+      const timestamp = new Date().toISOString().replace(/[:.-]/g, '');
+
+      // Combine entity SQL with custom functions
+      const schemaContent = customFunctionSQL.length > 0
+        ? entitySQL.join('\n') + '\n\n-- Custom Functions\n' + customFunctionSQL.join('\n\n')
+        : entitySQL.join('\n');
+      writeFileSync(resolve(dbDir, `${timestamp}_schema.sql`), schemaContent);
+
+      if (customFunctionSQL.length > 0) {
+        console.log(`[Generated] ${customFunctionSQL.length} Custom Functions`);
+      }
+
+      // Write subscribable SQL
+      if (subscribableSQL.length > 0) {
+        writeFileSync(resolve(dbDir, `${timestamp}_subscribables.sql`), subscribableSQL.join('\n\n'));
+        console.log(`[Generated] ${subscribableSQL.length} Subscribable SQL functions`);
+      }
+
+      console.log(`[Generated] DB Migrations in ${dbDir}`);
+
+      // 2. Runtime
+      const runtimeDir = resolve(outputDir, "runtime");
+      mkdirSync(runtimeDir, { recursive: true });
+      writeFileSync(resolve(runtimeDir, `manifest.json`), JSON.stringify(manifest, null, 2));
+      console.log(`[Generated] Runtime Manifest in ${runtimeDir}`);
+
+      // 3. Client SDK (TypeScript)
+      const clientDir = resolve(outputDir, "client");
+      mkdirSync(clientDir, { recursive: true });
+
+      // Generate Core SDK as TypeScript
+      const clientCode = generateClientSDK(manifest);
+      writeFileSync(resolve(clientDir, `ws.ts`), clientCode);
+
+      // Generate Index
+      writeFileSync(resolve(clientDir, `index.ts`), `export * from './ws.js';`);
+
+      console.log(`[Generated] Client SDK in ${clientDir}`);
+
+      // 4. Stores (TypeScript)
+      const storeDir = resolve(clientDir, "stores");
+      mkdirSync(storeDir, { recursive: true });
+
+      for (const subName of Object.keys(ir.subscribables)) {
+          const storeCode = generateSubscribableStore(manifest, subName);
+          const fileName = `use${subName.replace(/(^|_)([a-z])/g, (g) => g.at(-1)!.toUpperCase())}Store.ts`;
+          writeFileSync(resolve(storeDir, fileName), storeCode);
+      }
+      console.log(`[Generated] ${Object.keys(ir.subscribables).length} Pinia Stores in ${storeDir}`);
+
+      console.log("[Compiler] Build Complete.");
+
+    } catch (e) {
+      console.error(e);
+      process.exit(1);
+    }
+  } else {
+    console.log("Unknown command. Try 'compile'.");
+  }
+}
+
+main();

package/src/client/index.ts

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

package/src/client/ws.ts

@@ -0,0 +1,286 @@
+// Core WebSocket Manager for TZQL 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;
+  maxReconnectAttempts?: number;
+  tokenName?: string;
+}
+
+// Get default token name from environment (build-time injection)
+function getDefaultTokenName(): string {
+  // Vite: import.meta.env.VITE_TZQL_TOKEN_NAME
+  // @ts-ignore
+  if (typeof import.meta !== 'undefined' && import.meta.env?.VITE_TZQL_TOKEN_NAME) {
+    // @ts-ignore
+    return import.meta.env.VITE_TZQL_TOKEN_NAME;
+  }
+  // Node/bundlers: process.env.TZQL_TOKEN_NAME
+  if (typeof process !== 'undefined' && process.env?.TZQL_TOKEN_NAME) {
+    return process.env.TZQL_TOKEN_NAME;
+  }
+  return 'tzql_token';
+}
+
+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 readyCallbacks = new Set<(user: any) => void>();
+  protected reconnectAttempts = 0;
+  protected maxReconnectAttempts = 5;
+  protected tokenName = 'tzql_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 = {}) {
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+    this.tokenName = options.tokenName ?? getDefaultTokenName();
+  }
+
+  async login(credentials: any) {
+    try {
+      const result = await this.call('login_user', credentials);
+      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;
+    }
+  }
+
+  async authenticate(token: string) {
+    return this.call('auth', { token });
+  }
+
+  async register(credentials: any, options: any = {}) {
+    try {
+      const params = { ...credentials, options };
+      const result = await this.call('register_user', params);
+      if (result && result.token) {
+        if (typeof localStorage !== 'undefined') {
+          localStorage.setItem(this.tokenName, result.token);
+        }
+      }
+      return result;
+    } catch (e) {
+      throw e;
+    }
+  }
+
+  async logout() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem(this.tokenName);
+    }
+    this.user = null;
+    this.ready = false;
+    try { await this.call('logout'); } catch(e) {}
+    this.ws?.close();
+  }
+
+  connect(url: string | null = null, timeout = 5000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ready = false;
+      this.user = null;
+
+      let wsUrl = url;
+      if (!wsUrl) {
+        if (typeof window !== "undefined") {
+          const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+          wsUrl = protocol + "//" + window.location.host + "/ws";
+        } else {
+          wsUrl = "ws://localhost:3000/ws";
+        }
+      }
+
+      if (typeof localStorage !== 'undefined') {
+        const token = localStorage.getItem(this.tokenName);
+        if (token) {
+          if (wsUrl.includes('?')) wsUrl += '&token=' + encodeURIComponent(token);
+          else wsUrl += '?token=' + encodeURIComponent(token);
+        }
+      }
+
+      const connectionTimeout = setTimeout(() => {
+        if (this.ws) this.ws.close();
+        reject(new Error('WebSocket connection timed out after ' + timeout + 'ms'));
+      }, timeout);
+
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.onopen = () => {
+        clearTimeout(connectionTimeout);
+        console.log('[TZQL] Connected to ' + wsUrl);
+        this.reconnectAttempts = 0;
+        resolve();
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data);
+          this.handleMessage(message);
+        } catch (error) {
+          console.error("[TZQL] Failed to parse message:", error);
+        }
+      };
+
+      this.ws.onclose = () => {
+        console.log("[TZQL] Disconnected");
+        if (!this.isShuttingDown) {
+          this.attemptReconnect();
+        }
+      };
+
+      this.ws.onerror = (error) => {
+        clearTimeout(connectionTimeout);
+        console.error("[TZQL] Connection error:", error);
+        reject(error);
+      };
+    });
+  }
+
+  attemptReconnect() {
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++;
+      const delay = 1000 * this.reconnectAttempts;
+      setTimeout(() => {
+        console.log('[TZQL] Reconnecting (' + this.reconnectAttempts + ')...');
+        this.connect();
+      }, delay);
+    }
+  }
+
+  handleMessage(message: any) {
+    // Handle connection:ready message
+    if (message.method === "connection:ready") {
+      this.user = message.params?.user || null;
+      this.ready = true;
+      this.readyCallbacks.forEach((cb) => cb(this.user));
+      return;
+    }
+
+    // Handle RPC responses (messages with id)
+    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);
+        }
+      }
+      return;
+    }
+
+    // Handle subscription events - dispatch to registered subscription callbacks
+    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);
+        }
+      }
+      return;
+    }
+
+    // Handle other server-initiated messages (broadcasts) - route to registered handlers
+    if (message.method) {
+      const handlers = this.methodHandlers.get(message.method);
+      if (handlers) {
+        handlers.forEach((cb) => cb(message.params));
+      }
+    }
+  }
+
+  call(method: string, params: any = {}) {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        reject(new Error("WebSocket not connected"));
+        return;
+      }
+      const id = ++this.messageId;
+      this.pendingRequests.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ jsonrpc: "2.0", method, params, id }));
+    });
+  }
+
+  /**
+   * 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());
+    }
+    this.methodHandlers.get(method)!.add(callback);
+    return () => {
+      const handlers = this.methodHandlers.get(method);
+      if (handlers) {
+        handlers.delete(callback);
+        if (handlers.size === 0) {
+          this.methodHandlers.delete(method);
+        }
+      }
+    };
+  }
+
+  /**
+   * Register a callback to be called when connection is ready
+   * @param callback - Called with user profile (or null if not authenticated)
+   * @returns Unsubscribe function
+   */
+  onReady(callback: (user: any) => void) {
+    if (this.ready) {
+      callback(this.user);
+    }
+    this.readyCallbacks.add(callback);
+    return () => this.readyCallbacks.delete(callback);
+  }
+
+  /**
+   * 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;
+    };
+
+    // Register callback for subscription events
+    this.subscriptionCallbacks.set(result.subscription_id, callback);
+
+    // 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(() => {});
+    };
+  }
+}

package/src/create/.env.example

@@ -0,0 +1,8 @@
+# Database connection
+DATABASE_URL=postgres://{{name}}:{{name}}@localhost:5432/{{name}}
+
+# JWT Secret (change in production!)
+JWT_SECRET=dev-secret-change-in-production
+
+# Server port
+PORT=3000

package/src/create/README.md

@@ -0,0 +1,101 @@
+# {{name}}
+
+A real-time database application powered by [DZQL](https://github.com/blueshed/dzql).
+
+## Quick Start
+
+```bash
+# Start PostgreSQL
+bun run db:up
+
+# Copy environment file
+cp .env.example .env
+
+# Compile domain and generate SQL
+bun run compile
+
+# Run migrations
+bun run db:migrate
+
+# Start development server
+bun run dev
+```
+
+## Project Structure
+
+```
+├── domain.ts        # Entity definitions and subscriptions
+├── server.ts        # Runtime server configuration
+├── compose.yml      # Docker Compose for PostgreSQL
+├── dist/            # Generated output (after compile)
+│   ├── db/          # SQL migrations
+│   ├── runtime/     # Server manifest
+│   └── client/      # TypeScript SDK & Pinia stores
+└── .env             # Environment variables
+```
+
+## Domain Definition
+
+Edit `domain.ts` to define your entities:
+
+```typescript
+export const entities = {
+  posts: {
+    schema: {
+      id: 'serial PRIMARY KEY',
+      title: 'text NOT NULL',
+      content: 'text'
+    },
+    permissions: {
+      view: [],
+      create: [],
+      update: ['@author_id'],
+      delete: ['@author_id']
+    }
+  }
+};
+```
+
+## API Endpoints
+
+After starting the server:
+
+- **WebSocket**: `ws://localhost:3000/ws`
+- **Health**: `GET http://localhost:3000/health`
+
+## Client Usage
+
+```typescript
+import { TzqlClient } from './dist/client';
+
+const client = new TzqlClient('ws://localhost:3000/ws');
+
+// Register
+await client.api.register_user({ 
+  email: 'user@example.com', 
+  password: 'secret' 
+});
+
+// Login
+const { token } = await client.api.login_user({ 
+  email: 'user@example.com', 
+  password: 'secret' 
+});
+
+// CRUD operations
+const post = await client.api.save_posts({ 
+  title: 'Hello World' 
+});
+
+// Real-time subscription
+await client.api.subscribe_post_detail(
+  { post_id: post.id }, 
+  (data) => console.log('Updated:', data)
+);
+```
+
+## Learn More
+
+- [DZQL Documentation](https://github.com/blueshed/dzql)
+- [Graph Rules](https://github.com/blueshed/dzql/docs/guides/graph-rules.md)
+- [Subscriptions](https://github.com/blueshed/dzql/docs/guides/subscriptions.md)

package/src/create/compose.yml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: {{name}}
+      POSTGRES_PASSWORD: {{name}}
+      POSTGRES_DB: {{name}}
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata: