dzql 0.5.33 → 0.6.0

package/src/create/domain.ts

@@ -0,0 +1,153 @@
+// domain.ts - DZQL Domain Definition
+// Run: bunx dzql domain.ts
+
+export const entities = {
+
+  // Users table with authentication
+  users: {
+    schema: {
+      id: 'serial PRIMARY KEY',
+      name: 'text NOT NULL',
+      email: 'text UNIQUE NOT NULL',
+      password_hash: 'text NOT NULL',
+      created_at: 'timestamptz DEFAULT now()'
+    },
+    label: 'name',
+    searchable: ['name', 'email'],
+    hidden: ['password_hash'],
+    permissions: {
+      view: [],
+      create: [],
+      update: ['@id'],  // Users can only update themselves
+      delete: []
+    }
+  },
+
+  // Posts table with author relationship
+  posts: {
+    schema: {
+      id: 'serial PRIMARY KEY',
+      author_id: 'int NOT NULL REFERENCES users(id)',
+      title: 'text NOT NULL',
+      content: 'text',
+      published: 'boolean DEFAULT false',
+      created_at: 'timestamptz DEFAULT now()',
+      updated_at: 'timestamptz'
+    },
+    label: 'title',
+    searchable: ['title', 'content'],
+    includes: {
+      author: 'users'
+    },
+    fieldDefaults: {
+      author_id: '@user_id',
+      created_at: '@now'
+    },
+    permissions: {
+      view: [],  // Anyone can view
+      create: [],  // Anyone logged in can create
+      update: ['@author_id'],  // Only author can update
+      delete: ['@author_id']   // Only author can delete
+    },
+    graphRules: {
+      on_create: {
+        notify_followers: {
+          description: 'Notify when new post is created',
+          actions: [
+            {
+              type: 'reactor',
+              name: 'new_post',
+              params: { post_id: '@id', author_id: '@author_id' }
+            }
+          ]
+        }
+      },
+      on_update: {
+        track_updates: {
+          description: 'Set updated_at on edit',
+          condition: "@before.title != @after.title OR @before.content != @after.content",
+          actions: [
+            {
+              type: 'update',
+              target: 'posts',
+              data: { updated_at: '@now' },
+              match: { id: '@id' }
+            }
+          ]
+        }
+      }
+    }
+  },
+
+  // Comments on posts
+  comments: {
+    schema: {
+      id: 'serial PRIMARY KEY',
+      post_id: 'int NOT NULL REFERENCES posts(id) ON DELETE CASCADE',
+      author_id: 'int NOT NULL REFERENCES users(id)',
+      content: 'text NOT NULL',
+      created_at: 'timestamptz DEFAULT now()'
+    },
+    label: 'content',
+    searchable: ['content'],
+    includes: {
+      post: 'posts',
+      author: 'users'
+    },
+    fieldDefaults: {
+      author_id: '@user_id',
+      created_at: '@now'
+    },
+    permissions: {
+      view: [],
+      create: [],
+      update: ['@author_id'],
+      delete: ['@author_id', '@post_id->posts.author_id']  // Author or post owner can delete
+    }
+  }
+
+};
+
+// Real-time subscriptions
+export const subscribables = {
+
+  // Post detail with comments
+  post_detail: {
+    params: {
+      post_id: 'int'
+    },
+    root: {
+      entity: 'posts',
+      key: 'post_id'
+    },
+    includes: {
+      author: 'users',
+      comments: {
+        entity: 'comments',
+        includes: {
+          author: 'users'
+        }
+      }
+    },
+    scopeTables: ['posts', 'users', 'comments'],
+    canSubscribe: []  // Anyone can subscribe
+  },
+
+  // User's posts feed
+  my_posts: {
+    params: {},
+    root: {
+      entity: 'users',
+      key: '@user_id'
+    },
+    includes: {
+      posts: {
+        entity: 'posts',
+        filter: { author_id: '@user_id' }
+      }
+    },
+    scopeTables: ['users', 'posts'],
+    canSubscribe: []
+  }
+
+};

package/src/create/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --watch server.ts",
+    "compile": "bunx dzql domain.ts",
+    "db:up": "docker compose up -d",
+    "db:down": "docker compose down",
+    "db:migrate": "bun run compile && psql $DATABASE_URL -f dist/db/migrations/*.sql"
+  },
+  "dependencies": {
+    "dzql": "^0.6.0",
+    "postgres": "^3.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "bun-create": {
+    "postinstall": ["./setup.sh", "rm setup.sh"],
+    "start": "bun run dev"
+  }
+}

package/src/create/server.ts

@@ -0,0 +1,18 @@
+// server.ts - DZQL Runtime Server
+import { createServer } from "dzql";
+
+const server = createServer({
+  manifestPath: "./dist/runtime/manifest.json",
+  jwtSecret: process.env.JWT_SECRET || "dev-secret-change-in-production",
+});
+
+const port = process.env.PORT || 3000;
+
+console.log(`DZQL Server running at http://localhost:${port}`);
+console.log(`WebSocket endpoint: ws://localhost:${port}/ws`);
+
+export default {
+  port,
+  fetch: server.fetch,
+  websocket: server.websocket,
+};

package/src/create/setup.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Replace {{name}} with project name from package.json
+NAME=$(grep -o '"name": *"[^"]*"' package.json | head -1 | cut -d'"' -f4)
+if [ -z "$NAME" ] || [ "$NAME" = "{{name}}" ]; then
+  NAME=$(basename "$PWD")
+fi
+sed -i.bak "s/{{name}}/$NAME/g" compose.yml .env.example README.md package.json 2>/dev/null || \
+sed -i "s/{{name}}/$NAME/g" compose.yml .env.example README.md package.json
+cp .env.example .env
+rm -f compose.yml.bak .env.example.bak README.md.bak package.json.bak
+echo "✓ Configured project: $NAME"

package/src/create/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "types": ["bun-types"]
+  },
+  "include": ["*.ts", "domain.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/runtime/auth.ts

@@ -0,0 +1,39 @@
+import { jwtVerify, SignJWT } from "jose";
+
+const JWT_SECRET = process.env.JWT_SECRET || "default_dev_secret";
+const SECRET_KEY = new TextEncoder().encode(JWT_SECRET);
+
+export interface UserSession {
+  userId: number;
+  role?: string;
+  [key: string]: any;
+}
+
+export async function verifyToken(token: string): Promise<UserSession> {
+  try {
+    const { payload } = await jwtVerify(token, SECRET_KEY);
+    
+    // Normalize user_id vs sub
+    const uid = payload.user_id || payload.sub;
+    
+    if (!uid) {
+        throw new Error("Invalid token: missing user_id");
+    }
+    
+    return {
+      userId: Number(uid),
+      role: payload.role as string,
+      ...payload
+    };
+  } catch (err: any) {
+    throw new Error(`Authentication failed: ${err.message}`);
+  }
+}
+
+export async function signToken(payload: any): Promise<string> {
+    return await new SignJWT(payload)
+      .setProtectedHeader({ alg: 'HS256' })
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(SECRET_KEY);
+}

package/src/runtime/db.ts

@@ -0,0 +1,33 @@
+import postgres from "postgres";
+
+export class Database {
+  sql: postgres.Sql;
+
+  constructor(connectionString: string, options: any = {}) {
+    this.sql = postgres(connectionString, {
+      max: options.max || 10,
+      idle_timeout: options.idleTimeout || 20,
+      connect_timeout: options.connectTimeout || 10,
+      onnotice: () => {}, // Suppress notices
+      ...options
+    });
+  }
+
+  async query(text: string, params: any[] = []) {
+    return this.sql.unsafe(text, params);
+  }
+
+  async listen(channel: string, callback: (payload: string) => void) {
+    console.log(`[DB] Setting up LISTEN on channel: ${channel}`);
+    const result = await this.sql.listen(channel, (payload) => {
+      console.log(`[DB] LISTEN callback triggered with payload:`, payload);
+      callback(payload);
+    });
+    console.log(`[DB] LISTEN setup complete, result:`, result);
+    return result;
+  }
+
+  async close() {
+    await this.sql.end();
+  }
+}

package/src/runtime/errors.ts

@@ -0,0 +1,51 @@
+export enum ErrorCode {
+  PERMISSION_DENIED = "PERMISSION_DENIED",
+  NOT_FOUND = "NOT_FOUND",
+  VALIDATION_ERROR = "VALIDATION_ERROR",
+  CONFLICT = "CONFLICT",
+  RATE_LIMITED = "RATE_LIMITED",
+  INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+
+export class AppError extends Error {
+  code: ErrorCode;
+  constructor(code: ErrorCode, message?: string) {
+    super(message || code);
+    this.code = code;
+  }
+}
+
+export function mapDatabaseError(err: any): AppError {
+  // If it's already an AppError (e.g. thrown explicitly from PL/pgSQL RAISE), pass it through
+  // Postgres RAISE EXCEPTION '...' usually comes as a generic error with a message
+  
+  const code = err.code; // SQLSTATE
+  const message = err.message || "";
+
+  // 1. Explicit RAISE EXCEPTION from our PL/pgSQL functions
+  if (message.includes("permission_denied")) {
+    return new AppError(ErrorCode.PERMISSION_DENIED);
+  }
+  if (message.includes("not_found")) {
+    return new AppError(ErrorCode.NOT_FOUND);
+  }
+  if (message.includes("validation_error")) {
+    return new AppError(ErrorCode.VALIDATION_ERROR, message);
+  }
+
+  // 2. Standard SQLSTATE Mapping
+  switch (code) {
+    case "23505": // Unique violation
+      return new AppError(ErrorCode.CONFLICT, "Unique constraint violation");
+    case "23503": // Foreign key violation
+      return new AppError(ErrorCode.VALIDATION_ERROR, "Invalid reference");
+    case "23502": // Not null violation
+      return new AppError(ErrorCode.VALIDATION_ERROR, "Missing required field");
+    case "42P01": // Undefined table (shouldn't happen in prod if manifest is correct)
+      return new AppError(ErrorCode.INTERNAL_ERROR, "Table not found");
+    default:
+      // Log the real error internally, return generic to client
+      // console.error(err); // Done in server.ts
+      return new AppError(ErrorCode.INTERNAL_ERROR);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,98 @@
+import { serve } from "bun";
+import { config } from "dotenv";
+import { Database } from "./db.js";
+import { WebSocketServer } from "./ws.js";
+import { loadManifest } from "./manifest_loader.js";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+// Re-export JS function registration API for custom functions
+export { registerJsFunction, type JsFunctionHandler, type JsFunctionContext } from "./js_functions.js";
+
+// Load .env file if present
+config();
+
+// Configuration
+const PORT = process.env.PORT || 3000;
+const DB_URL = process.env.DATABASE_URL || "postgres://dzql_test:dzql_test@localhost:5433/dzql_test";
+const MANIFEST_PATH = process.env.MANIFEST_PATH || "./dist/runtime/manifest.json";
+
+// 1. Initialize DB
+const db = new Database(DB_URL);
+
+// 2. Load Manifest
+try {
+  const manifestPath = resolve(process.cwd(), MANIFEST_PATH);
+  const manifestContent = readFileSync(manifestPath, "utf-8");
+  const manifest = JSON.parse(manifestContent);
+  loadManifest(manifest);
+  console.log(`[Runtime] Loaded Manifest v${manifest.version}`);
+} catch (e) {
+  console.warn(`[Runtime] Warning: Could not load manifest from ${MANIFEST_PATH}. Ensure you have compiled the project.`);
+}
+
+// 3. Initialize WebSocket Server
+const wsServer = new WebSocketServer(db);
+
+// 4. Start Commit Listener (Realtime)
+async function startListener() {
+  console.log("[Runtime] Setting up LISTEN on dzql_v2 channel...");
+  await db.listen("dzql_v2", async (payload) => {
+    console.log(`[Runtime] RAW NOTIFY received:`, payload);
+    try {
+      const { commit_id } = JSON.parse(payload);
+      console.log(`[Runtime] Received Commit: ${commit_id}`);
+
+      // Fetch events
+      const events = await db.query(`
+        SELECT * FROM dzql_v2.events
+        WHERE commit_id = $1
+        ORDER BY id ASC
+      `, [commit_id]);
+
+      for (const event of events) {
+        // Broadcast
+        const message = JSON.stringify({
+          jsonrpc: "2.0",
+          method: "subscription:event",
+          params: {
+            event: {
+              table: event.table_name,
+              op: event.op,
+              pk: event.pk,
+              data: event.data,
+              // old_data is filtered out
+              user_id: event.user_id
+            }
+          }
+        });
+        wsServer.broadcast(message);
+      }
+    } catch (e) {
+      console.error("[Runtime] Listener Error:", e);
+    }
+  });
+  console.log("[Runtime] Listening for DB Events...");
+}
+
+// Wait for listener to be ready before starting server
+await startListener();
+
+// 5. Start Web Server
+const server = serve({
+  port: PORT,
+  async fetch(req, server) {
+    const url = new URL(req.url);
+
+    // Extract token from query params for WebSocket connections
+    const token = url.searchParams.get("token");
+
+    if (server.upgrade(req, { data: { token } })) {
+        return;
+    }
+    return new Response("TZQL Runtime Active", { status: 200 });
+  },
+  websocket: wsServer.handlers
+});
+
+console.log(`[Runtime] Server listening on port ${PORT}`);

package/src/runtime/js_functions.ts

@@ -0,0 +1,63 @@
+// JavaScript Custom Function Registry
+// Allows registering JS/Bun functions that can be called via RPC
+
+export interface JsFunctionContext {
+  userId: number;
+  params: any;
+  db: {
+    query(sql: string, params?: any[]): Promise<any[]>;
+  };
+}
+
+export type JsFunctionHandler = (ctx: JsFunctionContext) => Promise<any>;
+
+// Registry of JS function handlers
+const jsHandlers: Map<string, JsFunctionHandler> = new Map();
+
+/**
+ * Register a JavaScript function that can be called via RPC.
+ * JS functions take precedence over SQL functions with the same name.
+ *
+ * @param name - The function name (used in RPC calls)
+ * @param handler - Async function that receives context and returns result
+ *
+ * @example
+ * registerJsFunction('calculate_stats', async (ctx) => {
+ *   const { userId, params, db } = ctx;
+ *   const rows = await db.query('SELECT COUNT(*) as cnt FROM venues WHERE org_id = $1', [params.org_id]);
+ *   return { venue_count: rows[0].cnt };
+ * });
+ */
+export function registerJsFunction(name: string, handler: JsFunctionHandler): void {
+  jsHandlers.set(name, handler);
+  console.log(`[Runtime] Registered JS function: ${name}`);
+}
+
+/**
+ * Get a registered JS function handler by name.
+ * @returns The handler function or undefined if not registered
+ */
+export function getJsFunction(name: string): JsFunctionHandler | undefined {
+  return jsHandlers.get(name);
+}
+
+/**
+ * Check if a JS function is registered.
+ */
+export function hasJsFunction(name: string): boolean {
+  return jsHandlers.has(name);
+}
+
+/**
+ * Clear all registered JS functions (useful for testing).
+ */
+export function clearJsFunctions(): void {
+  jsHandlers.clear();
+}
+
+/**
+ * Get all registered JS function names.
+ */
+export function getJsFunctionNames(): string[] {
+  return Array.from(jsHandlers.keys());
+}

package/src/runtime/manifest_loader.ts

@@ -0,0 +1,29 @@
+import { Manifest } from "../cli/codegen/manifest.js";
+
+// Global cache for the loaded manifest
+let activeManifest: Manifest | null = null;
+
+export function loadManifest(manifest: Manifest) {
+  console.log(`[Runtime] Loading manifest v${manifest.version}`);
+  activeManifest = manifest;
+}
+
+export function getManifest(): Manifest {
+  if (!activeManifest) {
+    throw new Error("[Runtime] Manifest not loaded.");
+  }
+  return activeManifest;
+}
+
+export function resolveFunction(name: string) {
+  const manifest = getManifest();
+  const fn = manifest.functions[name];
+  
+  if (!fn) {
+    return null;
+  }
+  
+  // In a real DB-connected runtime, we would resolve OID here.
+  // For now, we return the schema-qualified name.
+  return `${fn.schema}.${fn.name}`;
+}