dzql 0.5.33 → 0.6.1

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}`;
+}

package/src/runtime/namespace.ts

@@ -0,0 +1,483 @@
+/**
+ * TZQL Namespace for invokej integration
+ *
+ * Provides CLI-style access to TZQL operations via the compiled manifest.
+ * Each method outputs JSON to console and closes the connection before returning.
+ *
+ * Setup - add to your tasks.js:
+ * ```js
+ * import { TzqlNamespace } from 'tzql/namespace';
+ *
+ * export class Tasks {
+ *   constructor() {
+ *     this.tzql = new TzqlNamespace();
+ *   }
+ * }
+ * ```
+ *
+ * Available Commands:
+ *
+ * Discovery:
+ *   invj tzql:entities                              # List all entities
+ *   invj tzql:subscribables                         # List all subscribables
+ *   invj tzql:functions                             # List all manifest functions
+ *
+ * Entity CRUD:
+ *   invj tzql:search venues '{"query": "test"}'     # Search with filters
+ *   invj tzql:get venues '{"id": 1}'                # Get by primary key
+ *   invj tzql:save venues '{"name": "New", "org_id": 1}'  # Create (no id)
+ *   invj tzql:save venues '{"id": 1, "name": "Updated"}'  # Update (with id)
+ *   invj tzql:delete venues '{"id": 1}'             # Delete by primary key
+ *   invj tzql:lookup venues '{"query": "test"}'     # Lookup for dropdowns
+ *
+ * Subscribables:
+ *   invj tzql:subscribe venue_detail '{"venue_id": 1}'  # Get snapshot
+ *
+ * Ad-hoc Function Calls:
+ *   invj tzql:call login_user '{"email": "x", "password": "y"}'
+ *   invj tzql:call register_user '{"email": "x", "password": "y"}'
+ *   invj tzql:call get_venue_detail '{"venue_id": 1}'
+ *   invj tzql:call save_venues '{"name": "Test", "org_id": 1}'
+ *
+ * Environment:
+ *   DATABASE_URL - PostgreSQL connection string (default: postgres://localhost:5432/dzql)
+ *
+ * Requirements:
+ *   - Run 'tzql compile' first to generate dist/runtime/manifest.json
+ */
+
+import postgres from "postgres";
+import { readFileSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import type { Manifest, FunctionDef } from "../cli/codegen/manifest.js";
+
+// Default user for CLI operations
+const DEFAULT_USER_ID = 1;
+
+/**
+ * Load manifest from MANIFEST_PATH env var or default locations
+ */
+function loadManifestFromDisk(): Manifest {
+  // First check MANIFEST_PATH env var (like the runtime does)
+  const envPath = process.env.MANIFEST_PATH;
+  if (envPath) {
+    const resolvedPath = resolve(process.cwd(), envPath);
+    if (existsSync(resolvedPath)) {
+      const content = readFileSync(resolvedPath, "utf-8");
+      return JSON.parse(content);
+    }
+    throw new Error(
+      `Manifest not found at MANIFEST_PATH: ${resolvedPath}`
+    );
+  }
+
+  // Fall back to default paths
+  const paths = [
+    join(process.cwd(), "dist/runtime/manifest.json"),
+    join(process.cwd(), "packages/tzql/dist/runtime/manifest.json"),
+  ];
+
+  for (const path of paths) {
+    if (existsSync(path)) {
+      const content = readFileSync(path, "utf-8");
+      return JSON.parse(content);
+    }
+  }
+
+  throw new Error(
+    "Manifest not found. Set MANIFEST_PATH env var or run 'tzql compile' to generate dist/runtime/manifest.json"
+  );
+}
+
+/**
+ * Discover available entities from the manifest
+ */
+function discoverEntities(manifest: Manifest): Record<string, { label: string; description: string }> {
+  const entities: Record<string, { label: string; description: string }> = {};
+
+  for (const [name, entity] of Object.entries(manifest.entities || {})) {
+    entities[name] = {
+      label: (entity as any).labelField || "id",
+      description: `Entity: ${name} (compiled mode)`,
+    };
+  }
+
+  return entities;
+}
+
+/**
+ * Discover available subscribables from the manifest
+ */
+function discoverSubscribables(manifest: Manifest): Record<string, { params: Record<string, string>; description: string }> {
+  const subscribables: Record<string, { params: Record<string, string>; description: string }> = {};
+
+  for (const [name, sub] of Object.entries(manifest.subscribables || {})) {
+    subscribables[name] = {
+      params: (sub as any).params || {},
+      description: `Subscribable: ${name}`,
+    };
+  }
+
+  return subscribables;
+}
+
+/**
+ * TZQL operations namespace for invokej
+ */
+export class TzqlNamespace {
+  private userId: number;
+  private sql: postgres.Sql | null = null;
+  private manifest: Manifest | null = null;
+
+  constructor(userId: number = DEFAULT_USER_ID) {
+    this.userId = userId;
+  }
+
+  private async init(): Promise<{ sql: postgres.Sql; manifest: Manifest }> {
+    if (!this.sql) {
+      const connectionString = process.env.DATABASE_URL || "postgres://localhost:5432/dzql";
+      this.sql = postgres(connectionString, {
+        max: 1,
+        idle_timeout: 5,
+        onnotice: () => {},
+      });
+    }
+    if (!this.manifest) {
+      this.manifest = loadManifestFromDisk();
+    }
+    return { sql: this.sql, manifest: this.manifest };
+  }
+
+  private async cleanup(): Promise<void> {
+    if (this.sql) {
+      await this.sql.end();
+      this.sql = null;
+    }
+  }
+
+  private async executeFunction(
+    fnName: string,
+    params: any
+  ): Promise<any> {
+    const { sql, manifest } = await this.init();
+
+    const fnDef = manifest.functions[fnName];
+    if (!fnDef) {
+      throw new Error(`Function '${fnName}' not found in manifest`);
+    }
+
+    const qualifiedName = `${fnDef.schema}.${fnDef.name}`;
+
+    // Build SQL params based on function signature
+    const dbParams: any[] = [];
+    const sqlArgs: string[] = [];
+
+    for (const arg of fnDef.args) {
+      if (arg === "p_user_id") {
+        dbParams.push(this.userId);
+        sqlArgs.push(`$${dbParams.length}`);
+      } else if (["p_data", "p_pk", "p_query", "p_params"].includes(arg)) {
+        // Pass the object directly - postgres.js will handle JSON serialization
+        dbParams.push(params);
+        sqlArgs.push(`$${dbParams.length}::jsonb`);
+      } else {
+        dbParams.push(null);
+        sqlArgs.push(`$${dbParams.length}`);
+      }
+    }
+
+    const query = `SELECT ${qualifiedName}(${sqlArgs.join(", ")}) as result`;
+    const rows = await sql.unsafe(query, dbParams);
+    return rows[0]?.result;
+  }
+
+  /**
+   * List all available entities
+   */
+  async entities(_context?: any): Promise<void> {
+    try {
+      const { manifest } = await this.init();
+      const entities = discoverEntities(manifest);
+      console.log(JSON.stringify({ success: true, entities }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * List all available subscribables
+   */
+  async subscribables(_context?: any): Promise<void> {
+    try {
+      const { manifest } = await this.init();
+      const subscribables = discoverSubscribables(manifest);
+      console.log(JSON.stringify({ success: true, subscribables }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Search an entity
+   * @example invj tzql:search venues '{"query": "test"}'
+   */
+  async search(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
+    if (!entity) {
+      console.error("Error: entity name required");
+      console.error("Usage: invj tzql:search <entity> '<json_args>'");
+      console.error('Example: invj tzql:search venues \'{"query": "test"}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`search_${entity}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Get entity by ID
+   * @example invj tzql:get venues '{"id": 1}'
+   */
+  async get(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
+    if (!entity) {
+      console.error("Error: entity name required");
+      console.error("Usage: invj tzql:get <entity> '<json_args>'");
+      console.error('Example: invj tzql:get venues \'{"id": 1}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`get_${entity}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Save (create or update) entity
+   * @example invj tzql:save venues '{"name": "New Venue", "org_id": 1}'
+   */
+  async save(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
+    if (!entity) {
+      console.error("Error: entity name required");
+      console.error("Usage: invj tzql:save <entity> '<json_args>'");
+      console.error('Example: invj tzql:save venues \'{"name": "Test Venue", "org_id": 1}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`save_${entity}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Delete entity by ID
+   * @example invj tzql:delete venues '{"id": 1}'
+   */
+  async delete(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
+    if (!entity) {
+      console.error("Error: entity name required");
+      console.error("Usage: invj tzql:delete <entity> '<json_args>'");
+      console.error('Example: invj tzql:delete venues \'{"id": 1}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`delete_${entity}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Lookup entity (for dropdowns/autocomplete)
+   * @example invj tzql:lookup organisations '{"query": "acme"}'
+   */
+  async lookup(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
+    if (!entity) {
+      console.error("Error: entity name required");
+      console.error("Usage: invj tzql:lookup <entity> '<json_args>'");
+      console.error('Example: invj tzql:lookup organisations \'{"query": "acme"}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`lookup_${entity}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Get subscribable snapshot
+   * @example invj tzql:subscribe venue_detail '{"venue_id": 1}'
+   */
+  async subscribe(_context: any, name?: string, argsJson: string = "{}"): Promise<void> {
+    if (!name) {
+      console.error("Error: subscribable name required");
+      console.error("Usage: invj tzql:subscribe <name> '<json_args>'");
+      console.error('Example: invj tzql:subscribe venue_detail \'{"venue_id": 1}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(`get_${name}`, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Call any function in the manifest by name
+   * @example invj tzql:call login_user '{"email": "test@example.com", "password": "secret"}'
+   * @example invj tzql:call get_venue_detail '{"venue_id": 1}'
+   */
+  async call(_context: any, funcName?: string, argsJson: string = "{}"): Promise<void> {
+    if (!funcName) {
+      console.error("Error: function name required");
+      console.error("Usage: invj tzql:call <function_name> '<json_args>'");
+      console.error('Example: invj tzql:call login_user \'{"email": "test@example.com", "password": "secret"}\'');
+      console.error('Example: invj tzql:call get_venue_detail \'{"venue_id": 1}\'');
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    let args: any;
+    try {
+      args = JSON.parse(argsJson);
+    } catch {
+      console.error("Error: arguments must be valid JSON");
+      await this.cleanup();
+      process.exit(1);
+    }
+
+    try {
+      const result = await this.executeFunction(funcName, args);
+      console.log(JSON.stringify({ success: true, result }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  /**
+   * List all available functions in the manifest
+   * @example invj tzql:functions
+   */
+  async functions(_context?: any): Promise<void> {
+    try {
+      const { manifest } = await this.init();
+      const functions: Record<string, { args: string[]; returnType: string }> = {};
+
+      for (const [name, fn] of Object.entries(manifest.functions)) {
+        functions[name] = {
+          args: fn.args,
+          returnType: fn.returnType,
+        };
+      }
+
+      console.log(JSON.stringify({ success: true, functions }, null, 2));
+      await this.cleanup();
+    } catch (error: any) {
+      console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+}

package/src/runtime/server.ts

@@ -0,0 +1,87 @@
+import { resolveFunction, getManifest } from "./manifest_loader.js";
+import { mapDatabaseError } from "./errors.js";
+import { getJsFunction, hasJsFunction } from "./js_functions.js";
+
+// Mock DB client interface
+interface DBClient {
+  query(text: string, params: any[]): Promise<any>;
+}
+
+export async function handleRequest(
+  db: DBClient,
+  method: string,
+  params: any,
+  userId: number
+) {
+  // 1. Check for JS function handler first (takes precedence)
+  if (hasJsFunction(method)) {
+    const handler = getJsFunction(method)!;
+    console.log(`[Runtime] Executing JS function: ${method}`);
+
+    try {
+      const result = await handler({
+        userId,
+        params,
+        db: {
+          query: (sql: string, sqlParams?: any[]) => db.query(sql, sqlParams || [])
+        }
+      });
+      return result;
+    } catch (err: any) {
+      console.error(`[Runtime] JS Error executing ${method}:`, err);
+      throw err;
+    }
+  }
+
+  // 2. Strict Allowlist Check (O(1) Lookup)
+  const manifest = getManifest();
+  const fnDef = manifest.functions[method];
+
+  if (!fnDef) {
+    throw new Error(`[Runtime] Method '${method}' not found in manifest.`);
+  }
+
+  const qualifiedName = `${fnDef.schema}.${fnDef.name}`;
+
+  // 3. Argument Validation (Basic)
+  // We assume all functions take (p_user_id, p_data/p_pk) for now
+  // In reality, we'd check manifest.functions[method].args
+
+  // 4. Secure Execution
+  console.log(`[Runtime] Executing ${qualifiedName}`);
+
+  try {
+    // Construct params array based on manifest definition
+    // args: ["p_user_id", "p_data"] -> [$1, $2]
+    // args: ["p_params"] -> [$2] (since $2 is the data param)
+    // We map: p_user_id -> userId ($1), p_data/p_pk/p_params -> params ($2)
+
+    const dbParams = [];
+    const sqlArgs = [];
+
+    // We strictly map our known runtime values (userId, params) to the function signature
+    // This assumes the function signature follows our conventions
+    for (const arg of fnDef.args) {
+        if (arg === 'p_user_id') {
+            dbParams.push(userId);
+            sqlArgs.push(`$${dbParams.length}`);
+        } else if (arg === 'p_data' || arg === 'p_pk' || arg === 'p_query' || arg === 'p_params') {
+            dbParams.push(params);
+            sqlArgs.push(`$${dbParams.length}`);
+        } else {
+            // Unknown arg? Pass null
+            dbParams.push(null);
+            sqlArgs.push(`$${dbParams.length}`);
+        }
+    }
+
+    const sql = `SELECT ${qualifiedName}(${sqlArgs.join(', ')}) as result`;
+    const rows = await db.query(sql, dbParams);
+    return rows[0].result;
+  } catch (err: any) {
+    // 5. Error Sanitization
+    console.error(`[Runtime] DB Error executing ${method}:`, err);
+    const appError = mapDatabaseError(err);
+    throw appError;
+  }
+}