dzql 0.1.0-alpha.1

package/src/database/migrations/007_events.sql

@@ -0,0 +1,136 @@
+-- DZQL Framework - Event System and Real-time Notifications
+-- Events are created ONLY by API operations (generic_save, generic_delete)
+-- This ensures proper user context and security
+
+-- ============================================================================
+-- NOTIFY EVENT FUNCTION
+-- ============================================================================
+-- Event notification trigger - handles all real-time notifications
+CREATE OR REPLACE FUNCTION dzql.notify_event()
+RETURNS TRIGGER LANGUAGE plpgsql AS $$
+BEGIN
+  -- Send real-time notification to single channel
+  -- For DELETE operations, send the 'before' data since 'after' is NULL
+  PERFORM pg_notify('dzql', jsonb_build_object(
+    'event_id', NEW.event_id,
+    'table', NEW.table_name,
+    'op', NEW.op,
+    'pk', NEW.pk,
+    'data', COALESCE(NEW.after, NEW.before),
+    'before', NEW.before,
+    'after', NEW.after,
+    'user_id', NEW.user_id,
+    'at', NEW.at,
+    'notify_users', NEW.notify_users
+  )::text);
+
+  RETURN NULL;
+END $$;
+
+-- ============================================================================
+-- CREATE TRIGGER ON EVENTS TABLE
+-- ============================================================================
+-- Create trigger on events table to handle notifications
+DROP TRIGGER IF EXISTS dzql_events_notify ON dzql.events;
+CREATE TRIGGER dzql_events_notify
+  AFTER INSERT ON dzql.events
+  FOR EACH ROW EXECUTE FUNCTION dzql.notify_event();
+
+-- ============================================================================
+-- HELPER FUNCTIONS
+-- ============================================================================
+
+-- Get event history for a specific record (audit trail)
+CREATE OR REPLACE FUNCTION dzql.get_record_history(
+  p_table_name text,
+  p_record_id text,
+  p_limit int DEFAULT 50
+) RETURNS jsonb
+LANGUAGE sql STABLE AS $$
+  SELECT COALESCE(jsonb_agg(
+    to_jsonb(e) ORDER BY e.at DESC
+  ), '[]'::jsonb)
+  FROM (
+    SELECT * FROM dzql.events e
+    WHERE e.table_name = p_table_name
+      AND e.pk->>'id' = p_record_id
+    ORDER BY e.at DESC
+    LIMIT p_limit
+  ) e;
+$$;
+
+-- Get recent actions by a user
+CREATE OR REPLACE FUNCTION dzql.get_user_actions(
+  p_user_id int,
+  p_limit int DEFAULT 100
+) RETURNS jsonb
+LANGUAGE sql STABLE AS $$
+  SELECT COALESCE(jsonb_agg(
+    to_jsonb(e) ORDER BY e.at DESC
+  ), '[]'::jsonb)
+  FROM (
+    SELECT * FROM dzql.events e
+    WHERE e.user_id = p_user_id
+    ORDER BY e.at DESC
+    LIMIT p_limit
+  ) e;
+$$;
+
+-- Get event catchup data for synchronization
+CREATE OR REPLACE FUNCTION dzql.catchup(p_context_id text, p_since_event_id bigint)
+RETURNS jsonb LANGUAGE sql STABLE AS $$
+  SELECT coalesce(jsonb_agg(to_jsonb(e) order by e.event_id), '[]'::jsonb)
+  FROM dzql.events e
+  WHERE e.event_id > p_since_event_id;
+$$;
+
+-- Get single event by ID
+CREATE OR REPLACE FUNCTION dzql.get_event(p_event_id bigint)
+RETURNS jsonb LANGUAGE sql STABLE AS $$
+  SELECT to_jsonb(e) FROM dzql.events e WHERE e.event_id = p_event_id;
+$$;
+
+-- Get recent events on a table
+CREATE OR REPLACE FUNCTION dzql.get_table_events(
+  p_table_name text,
+  p_limit int DEFAULT 100
+) RETURNS jsonb
+LANGUAGE sql STABLE AS $$
+  SELECT COALESCE(jsonb_agg(
+    to_jsonb(e) ORDER BY e.at DESC
+  ), '[]'::jsonb)
+  FROM (
+    SELECT * FROM dzql.events e
+    WHERE e.table_name = p_table_name
+    ORDER BY e.at DESC
+    LIMIT p_limit
+  ) e;
+$$;
+
+-- Comments
+COMMENT ON FUNCTION dzql.notify_event() IS 'Broadcasts event notifications via PostgreSQL NOTIFY for real-time updates';
+COMMENT ON FUNCTION dzql.get_record_history(text, text, int) IS 'Returns audit trail for a specific record';
+COMMENT ON FUNCTION dzql.get_user_actions(int, int) IS 'Returns recent actions performed by a user';
+COMMENT ON FUNCTION dzql.get_table_events(text, int) IS 'Returns recent events for a table';
+
+-- ============================================================================
+-- CLEANUP OLD TRIGGER SYSTEM
+-- ============================================================================
+-- Remove any table triggers that were created by the old system
+DO $$
+DECLARE
+  l_table_name text;
+BEGIN
+  -- Remove old emit_row_change function if it exists
+  DROP FUNCTION IF EXISTS dzql.emit_row_change() CASCADE;
+
+  -- Clean up any existing table triggers from registered entities
+  FOR l_table_name IN
+    SELECT table_name FROM dzql.entities
+  LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I',
+      l_table_name || '_dzql_events', l_table_name);
+  END LOOP;
+
+  RAISE NOTICE 'Cleaned up old table trigger system';
+END $$;

package/src/database/migrations/008_hello.sql

@@ -0,0 +1,18 @@
+-- Hello World Function for Testing DZQL's Function Proxy
+
+-- Create a simple hello world function
+-- First parameter must be p_user_id for DZQL compatibility
+create or replace function hello(p_user_id int, p_name text default 'World')
+returns jsonb
+language plpgsql
+security definer
+as $$
+begin
+  return jsonb_build_object(
+    'message', 'Hello, ' || coalesce(p_name, 'World') || '!',
+    'timestamp', now(),
+    'from', 'PostgreSQL',
+    'user_id', p_user_id
+  );
+end;
+$$;

package/src/database/migrations/008a_meta.sql

@@ -0,0 +1,165 @@
+-- === Entity Metadata Function ===
+-- Returns complete metadata for all registered entities in the DZQL system
+-- Includes entity config, schema information, and relationship graph
+-- Used by UI to dynamically configure based on registered entities
+
+create or replace function get_entities_metadata(p_user_id int)
+returns jsonb
+language plpgsql
+security definer
+as $$
+declare
+  v_entities jsonb;
+  v_relations jsonb;
+  v_junction_tables text[];
+  v_entity_names text[];
+begin
+  -- Get list of registered entity names
+  select array_agg(table_name) into v_entity_names
+  from dzql.entities;
+
+  -- Build entities object with schema information
+  select jsonb_object_agg(
+    e.table_name,
+    jsonb_build_object(
+      'table_name', e.table_name,
+      'label_field', e.label_field,
+      'searchable_fields', e.searchable_fields,
+      'fk_includes', e.fk_includes,
+      'soft_delete', e.soft_delete,
+      'temporal_fields', e.temporal_fields,
+      'notification_paths', e.notification_paths,
+      'permission_paths', e.permission_paths,
+      'schema', (
+        -- Get column schema from information_schema
+        select jsonb_agg(
+          jsonb_build_object(
+            'column_name', c.column_name,
+            'data_type', c.data_type,
+            'is_nullable', c.is_nullable = 'YES',
+            'column_default', c.column_default,
+            'character_maximum_length', c.character_maximum_length,
+            'numeric_precision', c.numeric_precision,
+            'numeric_scale', c.numeric_scale,
+            'ordinal_position', c.ordinal_position
+          ) order by c.ordinal_position
+        )
+        from information_schema.columns c
+        where c.table_schema = 'public'
+          and c.table_name = e.table_name
+      )
+    )
+  ) into v_entities
+  from dzql.entities e;
+
+  -- Identify junction tables (2+ foreign keys, minimal searchable fields)
+  select array_agg(distinct tc.table_name) into v_junction_tables
+  from information_schema.table_constraints tc
+  where tc.constraint_type = 'FOREIGN KEY'
+    and tc.table_schema = 'public'
+    and tc.table_name = any(v_entity_names)
+  group by tc.table_name
+  having count(*) >= 2
+    and (
+      select count(*)
+      from unnest((
+        select searchable_fields
+        from dzql.entities
+        where table_name = tc.table_name
+      )) as sf
+      where sf not in (
+        select kcu.column_name
+        from information_schema.key_column_usage kcu
+        where kcu.table_name = tc.table_name
+          and kcu.constraint_name in (
+            select constraint_name
+            from information_schema.table_constraints
+            where table_name = tc.table_name
+              and constraint_type = 'FOREIGN KEY'
+          )
+      )
+    ) <= 1;
+
+  -- Build relations array
+  with fk_relations as (
+    -- Get all foreign key relationships
+    select
+      tc.table_name,
+      kcu.column_name,
+      ccu.table_name as foreign_table_name,
+      ccu.column_name as foreign_column_name
+    from information_schema.table_constraints tc
+    join information_schema.key_column_usage kcu
+      on tc.constraint_name = kcu.constraint_name
+      and tc.table_schema = kcu.table_schema
+    join information_schema.constraint_column_usage ccu
+      on ccu.constraint_name = tc.constraint_name
+      and ccu.table_schema = tc.table_schema
+    where tc.constraint_type = 'FOREIGN KEY'
+      and tc.table_schema = 'public'
+      and tc.table_name = any(v_entity_names)
+      and ccu.table_name = any(v_entity_names)
+  ),
+  simple_relations as (
+    -- Many-to-one and one-to-many for non-junction tables
+    select jsonb_build_object(
+      'type', 'many_to_one',
+      'from', fk.table_name || '.' || fk.column_name,
+      'to', fk.foreign_table_name || '.' || fk.foreign_column_name
+    ) as relation
+    from fk_relations fk
+    where not (fk.table_name = any(v_junction_tables))
+
+    union all
+
+    select jsonb_build_object(
+      'type', 'one_to_many',
+      'from', fk.foreign_table_name || '.' || fk.foreign_column_name,
+      'to', fk.table_name || '.' || fk.column_name
+    ) as relation
+    from fk_relations fk
+    where not (fk.table_name = any(v_junction_tables))
+  ),
+  junction_relations as (
+    -- Many-to-many through junction tables
+    select jsonb_build_object(
+      'type', 'many_to_many',
+      'from', fk1.foreign_table_name || '.' || fk1.foreign_column_name,
+      'to', fk2.foreign_table_name || '.' || fk2.foreign_column_name,
+      'via', fk1.table_name || '.' || fk1.column_name || '.' || fk2.column_name
+    ) as relation
+    from fk_relations fk1
+    join fk_relations fk2
+      on fk1.table_name = fk2.table_name
+      and fk1.column_name < fk2.column_name  -- avoid duplicates
+    where fk1.table_name = any(v_junction_tables)
+
+    union all
+
+    select jsonb_build_object(
+      'type', 'many_to_many',
+      'from', fk2.foreign_table_name || '.' || fk2.foreign_column_name,
+      'to', fk1.foreign_table_name || '.' || fk1.foreign_column_name,
+      'via', fk1.table_name || '.' || fk2.column_name || '.' || fk1.column_name
+    ) as relation
+    from fk_relations fk1
+    join fk_relations fk2
+      on fk1.table_name = fk2.table_name
+      and fk1.column_name < fk2.column_name
+    where fk1.table_name = any(v_junction_tables)
+  )
+  select jsonb_agg(relation) into v_relations
+  from (
+    select relation from simple_relations
+    union all
+    select relation from junction_relations
+  ) all_relations;
+
+  -- Return complete metadata structure
+  return jsonb_build_object(
+    'entities', v_entities,
+    'relations', coalesce(v_relations, '[]'::jsonb),
+    'operations', jsonb_build_array('get', 'save', 'delete', 'lookup', 'search')
+  );
+end;
+$$;

package/src/index.js

@@ -0,0 +1,19 @@
+// ZeroQL Framework - Main Entry Point
+export { createServer } from './server/index.js';
+
+// Re-export client utilities
+export { WebSocketManager, useWs } from './client/ws.js';
+
+// Re-export UI framework
+export { mount, state, Component } from './client/ui.js';
+export { loadUI, loadEntityUI } from './client/ui-loader.js';
+
+// Re-export database utilities for tests and custom functions
+export { sql, listen_sql, db } from './server/db.js';
+export { createWebSocketHandlers, verify_jwt_token } from './server/ws.js';
+
+// Re-export meta route for applications
+export { metaRoute } from './server/meta-route.js';
+
+// Re-export MCP route for Claude Code integration
+export { createMCPRoute } from './server/mcp.js';

package/src/server/api.js

@@ -0,0 +1,9 @@
+export async function goodbye(userId, params = {}) {
+  const { name = "World" } = params;
+
+  return {
+    message: `Goodbye, ${name}!`,
+    from: "Bun",
+    user_id: userId,
+  };
+}

package/src/server/db.js

@@ -0,0 +1,261 @@
+import postgres from "postgres";
+import { dbLogger, notifyLogger } from "./logger.js";
+
+// Environment configuration
+const DATABASE_URL =
+  process.env.DATABASE_URL ||
+  "postgresql://dzql:dzql@localhost:5432/dzql";
+
+const DB_MAX_CONNECTIONS = parseInt(process.env.DB_MAX_CONNECTIONS || "10", 10);
+const DB_IDLE_TIMEOUT = parseInt(process.env.DB_IDLE_TIMEOUT || "20", 10);
+const DB_CONNECT_TIMEOUT = parseInt(process.env.DB_CONNECT_TIMEOUT || "10", 10);
+
+// Main PostgreSQL connection for queries
+export const sql = postgres(DATABASE_URL, {
+  max: DB_MAX_CONNECTIONS,
+  idle_timeout: DB_IDLE_TIMEOUT,
+  connect_timeout: DB_CONNECT_TIMEOUT,
+  // Suppress NOTICE messages in test environment
+  onnotice: process.env.NODE_ENV === 'test' ? () => {} : undefined,
+});
+
+// Separate PostgreSQL connection for NOTIFY/LISTEN
+export const listen_sql = postgres(DATABASE_URL, {
+  max: 1,
+  idle_timeout: 0,
+  connect_timeout: DB_CONNECT_TIMEOUT,
+  // Suppress NOTICE messages in test environment
+  onnotice: process.env.NODE_ENV === 'test' ? () => {} : undefined,
+});
+
+dbLogger.info(`Database connected: ${DATABASE_URL.replace(/\/\/.*@/, '//***@')}`);
+
+// Cache for function parameter metadata
+const functionParamCache = new Map();
+
+// Cache helpers
+export async function getCache(key, ttlHours) {
+  const result = await sql`SELECT app._get_cache(${key}, ${ttlHours}) as data`;
+  return result[0]?.data ? JSON.parse(result[0].data) : null;
+}
+
+export async function setCache(key, data) {
+  await sql`SELECT app._set_cache(${key}, ${JSON.stringify(data)})`;
+}
+
+// Auth helpers
+export async function callAuthFunction(method, email, password) {
+  const result = await sql`
+    SELECT ${sql(method)}(${email}, ${password}) as result
+  `;
+  return result[0].result;
+}
+
+// Get function parameter metadata
+async function getFunctionParams(functionName) {
+  if (functionParamCache.has(functionName)) {
+    return functionParamCache.get(functionName);
+  }
+
+  const result = await sql`
+    SELECT
+      p.parameter_name,
+      p.parameter_default,
+      p.data_type,
+      p.ordinal_position
+    FROM information_schema.parameters p
+    WHERE p.specific_name IN (
+      SELECT r.specific_name
+      FROM information_schema.routines r
+      WHERE r.routine_name = ${functionName}
+      AND r.routine_type = 'FUNCTION'
+    )
+    AND (p.parameter_mode = 'IN' OR p.parameter_mode IS NULL)
+    ORDER BY p.ordinal_position
+  `;
+
+  const params = result.map((row) => ({
+    name: row.parameter_name,
+    type: row.data_type,
+    position: row.ordinal_position,
+    hasDefault: row.parameter_default !== null,
+  }));
+
+  functionParamCache.set(functionName, params);
+  return params;
+}
+
+// Generic stored function call with user_id
+export async function callUserFunction(method, userId, params) {
+  // Validate function name format (only alphanumeric and underscore, no special chars)
+  // This prevents SQL injection via function names like "foo(); DROP TABLE users--"
+  if (!/^[a-z_][a-z0-9_]*$/i.test(method)) {
+    throw new Error(`Invalid function name: ${method}`);
+  }
+
+  const functionParams = await getFunctionParams(method);
+
+  if (functionParams.length === 0) {
+    throw new Error(`Function ${method} not found`);
+  }
+
+  // Build ordered parameter array
+  const orderedParams = [];
+
+  for (const param of functionParams) {
+    if (param.position === 1) {
+      // First parameter is always user_id
+      orderedParams.push(userId);
+    } else {
+      // Strip p_ prefix from parameter name for client API matching
+      const clientParamName = param.name.startsWith("p_")
+        ? param.name.substring(2)
+        : param.name;
+
+      if (params && params[clientParamName] !== undefined) {
+        // Parameter exists in the params object
+        orderedParams.push(params[clientParamName]);
+      } else if (param.hasDefault) {
+        // Parameter has a default value, skip it
+        break;
+      } else {
+        // Required parameter missing
+        throw new Error(`Missing required parameter: ${clientParamName}`);
+      }
+    }
+  }
+
+  // Try table format first - works for both single and multiple results
+  const query = `SELECT * FROM ${method}(${orderedParams.map((_, i) => `$${i + 1}`).join(", ")})`;
+  const result = await sql.unsafe(query, orderedParams);
+
+  // If single row with single column, return just the value
+  if (result.length === 1 && Object.keys(result[0]).length === 1) {
+    return Object.values(result[0])[0];
+  }
+
+  // Otherwise return the full result set
+  return result;
+}
+
+// Get user profile
+export async function getUserProfile(userId) {
+  const result = await sql`
+    SELECT _profile(${userId}::integer) as profile
+  `;
+  return result[0].profile;
+}
+
+// Setup NOTIFY listeners
+export async function setupListeners(callback) {
+  try {
+    // Listen to single dzql channel for all events
+    await listen_sql.listen("dzql", (payload) => {
+      const event = JSON.parse(payload);
+      notifyLogger.debug(`Received NOTIFY event:`, event.table, event.op);
+      callback(event);
+    });
+    notifyLogger.info("NOTIFY listener established on 'dzql' channel");
+    return true;
+  } catch (error) {
+    notifyLogger.error("Failed to setup listeners:", error.message);
+    return false;
+  }
+}
+
+// DZQL Generic Operations
+export async function callDZQLOperation(operation, entity, args, userId) {
+  dbLogger.trace(`DZQL ${operation}.${entity} for user ${userId}`);
+  const result = await sql`
+    SELECT dzql.generic_exec(${operation}, ${entity}, ${args}, ${userId}) as result
+  `;
+  return result[0].result;
+}
+
+// DZQL nested proxy factory
+function createEntityProxy(operation) {
+  return new Proxy(
+    {},
+    {
+      get(target, entityName) {
+        return async (args = {}, userId) => {
+          // userId is required for DZQL operations
+          if (!userId) {
+            throw new Error("userId is required for DZQL operations");
+          }
+          return callDZQLOperation(operation, entityName, args, userId);
+        };
+      },
+    },
+  );
+}
+
+// DZQL database API proxy with custom function support
+export const db = {
+  api: new Proxy(
+    {
+      get: createEntityProxy("get"),
+      save: createEntityProxy("save"),
+      delete: createEntityProxy("delete"),
+      lookup: createEntityProxy("lookup"),
+      search: createEntityProxy("search"),
+      exec: async (functionName, args, userId) => {
+        if (!userId) {
+          throw new Error("userId is required for function calls");
+        }
+        return callUserFunction(functionName, userId, args);
+      },
+      // Permission and path resolution utilities
+      checkPermission: async (userId, operation, entity, record) => {
+        const result = await sql`
+          SELECT dzql.check_permission(${userId}, ${operation}, ${entity}, ${JSON.stringify(record)}) as allowed
+        `;
+        return result[0].allowed;
+      },
+      resolveNotificationPath: async (tableName, record, path) => {
+        const result = await sql`
+          SELECT dzql.resolve_notification_path(${tableName}, ${JSON.stringify(record)}, ${path}) as user_ids
+        `;
+        return result[0].user_ids;
+      },
+      resolveNotificationPaths: async (tableName, record) => {
+        const result = await sql`
+          SELECT dzql.resolve_notification_paths(${tableName}, ${JSON.stringify(record)}) as user_ids
+        `;
+        return result[0].user_ids;
+      },
+    },
+    {
+      get(target, prop) {
+        // Return existing DZQL operations
+        if (target[prop]) {
+          return target[prop];
+        }
+
+        // Handle custom functions
+        return async (userIdOrArgs, args = {}) => {
+          // Special handling for auth functions that don't require userId
+          if (prop === 'register_user' || prop === 'login_user') {
+            // For auth functions, first param is the args object
+            return callAuthFunction(prop, userIdOrArgs.email, userIdOrArgs.password);
+          }
+
+          // For other functions, userId is required as first parameter
+          if (!userIdOrArgs) {
+            throw new Error(`userId is required for function ${prop}`);
+          }
+
+          return callUserFunction(prop, userIdOrArgs, args);
+        };
+      },
+    }
+  ),
+};
+
+// Graceful shutdown
+export async function closeConnections() {
+  dbLogger.info("Closing database connections...");
+  await sql.end();
+  await listen_sql.end();
+  dbLogger.info("Database connections closed");
+}