dzql 0.6.34 → 0.6.36

package/docs/README.md

@@ -109,6 +109,7 @@ generated/
 
 - [Domain Modeling Guide](./for_ai.md) - Entity and permission patterns
 - [Project Setup](./project-setup.md) - Manual setup and configuration
+- [Architecture Roadmap](./futures.md) - Performance and scaling plan
 - [Feature Requests](./feature-requests/) - Roadmap and proposals
 
 ## Package Exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",

package/src/cli/codegen/sql/index.ts

@@ -18,6 +18,7 @@ export { generateSaveFunction } from "./save.js";
 export { generateDeleteFunction } from "./delete.js";
 export { generateGetFunction, generateHistoryFunction } from "./get.js";
 export { generateSearchFunction } from "./search.js";
+export { generateLookupFunction } from "./lookup.js";
 export { buildVisibleJsonb, getCastForType, stripFKReferences } from "./utils.js";
 export type { ColumnInfo, EntityIR, ManyToManyIR, IncludeIR } from "./types.js";
 
@@ -26,6 +27,7 @@ import { generateSaveFunction } from "./save.js";
 import { generateDeleteFunction } from "./delete.js";
 import { generateGetFunction, generateHistoryFunction } from "./get.js";
 import { generateSearchFunction } from "./search.js";
+import { generateLookupFunction } from "./lookup.js";
 
 // === AGGREGATE GENERATOR ===
 export function generateEntitySQL(name: string, entityIR: EntityIR): string {
@@ -37,7 +39,8 @@ export function generateEntitySQL(name: string, entityIR: EntityIR): string {
     generateSaveFunction(name, entityIR),
     generateDeleteFunction(name, entityIR),
     generateGetFunction(name, entityIR),
-    generateSearchFunction(name, entityIR)
+    generateSearchFunction(name, entityIR),
+    generateLookupFunction(name, entityIR)
   ];
 
   // Add history function for temporal entities with refField

package/src/cli/codegen/sql/lookup.ts

@@ -0,0 +1,62 @@
+import { compilePermission } from "../../compiler/permissions.js";
+import type { EntityIR } from "./types.js";
+
+/**
+ * Generate Lookup Function
+ * Returns a set of { label: text, value: any } for autocomplete.
+ * Uses the entity's 'label' configuration for the display text.
+ */
+export function generateLookupFunction(name: string, entityIR: EntityIR): string {
+  const pk = entityIR.primaryKey[0] || 'id';
+  const labelField = entityIR.labelField || pk;
+  const searchable = entityIR.searchable || [labelField];
+  const softDelete = entityIR.softDelete || false;
+  const temporal = entityIR.temporal;
+
+  const viewPermRaw = entityIR.permissions?.view?.length > 0
+    ? entityIR.permissions.view.map((rule: string) => compilePermission(name, rule, null, name)).join(' OR ')
+    : 'TRUE';
+  const viewPerm = viewPermRaw.replace(/p_user_id/g, '$1');
+
+  const softDeleteFilter = softDelete ? ' AND deleted_at IS NULL' : '';
+  const temporalFilter = temporal ? ` AND ${temporal.validTo} IS NULL` : '';
+
+  // Build ILIKE conditions for searchable fields
+  const searchConditions = searchable
+    .map((field: string) => `t.${field}::TEXT ILIKE $2`)
+    .join(' OR ');
+
+  return `
+CREATE OR REPLACE FUNCTION dzql_v2.lookup_${name}(p_user_id int, p_query jsonb)
+RETURNS SETOF jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = dzql_v2, public
+AS $$
+DECLARE
+  v_q text;
+  v_limit int;
+BEGIN
+  v_q := COALESCE(p_query->>'q', '');
+  v_limit := COALESCE((p_query->>'limit')::int, 20);
+
+  IF v_q = '' THEN
+    RETURN QUERY
+    SELECT jsonb_build_object('label', t.${labelField}, 'value', t.${pk})
+    FROM ${name} t
+    WHERE (${viewPerm})${softDeleteFilter}${temporalFilter}
+    ORDER BY t.${labelField} ASC
+    LIMIT v_limit;
+  ELSE
+    RETURN QUERY
+    SELECT jsonb_build_object('label', t.${labelField}, 'value', t.${pk})
+    FROM ${name} t
+    WHERE (${viewPerm})${softDeleteFilter}${temporalFilter}
+      AND (${searchConditions.replace(/\$2/g, "LOWER('%' || v_q || '%')")})
+    ORDER BY t.${labelField} ASC
+    LIMIT v_limit;
+  END IF;
+END;
+$$;
+`;
+}

package/src/cli/codegen/sql/search.ts

@@ -66,13 +66,12 @@ export function generateSearchFunction(name: string, entityIR: EntityIR): string
 
   return `
 CREATE OR REPLACE FUNCTION dzql_v2.search_${name}(p_user_id int, p_query jsonb)
-RETURNS jsonb
+RETURNS SETOF jsonb
 LANGUAGE plpgsql
 SECURITY DEFINER
 SET search_path = dzql_v2, public
 AS $$
 DECLARE
-  v_results jsonb;
   v_filters jsonb;
   v_sort_field text;
   v_sort_order text;
@@ -175,9 +174,9 @@ BEGIN
     END IF;
   END LOOP;
 
-  -- Execute dynamic query
-  EXECUTE format('
-    SELECT COALESCE(jsonb_agg(${selectExpr}), ''[]''::jsonb)
+  -- Execute dynamic query and return set of jsonb
+  RETURN QUERY EXECUTE format('
+    SELECT ${selectExpr}
     FROM (
       SELECT * FROM ${name}
       WHERE (${viewPerm})${softDeleteFilter}${temporalFilter} %s
@@ -187,10 +186,7 @@ BEGIN
   ', v_where_clause, v_sort_field, v_sort_order,
      COALESCE((p_query->>'limit')::int, 10),
      COALESCE((p_query->>'offset')::int, 0))
-  INTO v_results
   USING p_user_id;
-
-  RETURN v_results;
 END;
 $$;
 `;

package/src/cli/codegen/subscribable_sql.ts

@@ -312,18 +312,19 @@ function generateGetFunction(name: string, sub: SubscribableIR, entities: Record
     : '';
 
   if (isList) {
-    // List subscribable - return array of records with nested includes
+    // List subscribable - return set of documents (STREAMING compatible)
+    // The Runtime will aggregate these or stream them.
+    // Schema metadata should be attached by the Runtime from the manifest.
     return `CREATE OR REPLACE FUNCTION dzql_v2.get_${name}(
   p_params JSONB,
   p_user_id INT
-) RETURNS JSONB
+) RETURNS SETOF JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
 SET search_path = dzql_v2, public
 AS $$
 DECLARE
 ${paramDecls}
-  v_data JSONB;
 BEGIN
   -- Extract parameters
 ${paramExtracts}
@@ -333,23 +334,15 @@ ${paramExtracts}
     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
+  -- Return stream of documents
+  RETURN QUERY
+  SELECT to_jsonb(root.*) || jsonb_build_object(${relationSelects ? relationSelects.slice(1) : ''})
   FROM ${sub.root.entity} root
   ${whereClause};
-
-  -- Return data with embedded schema for atomic updates
-  RETURN jsonb_build_object(
-    'data', jsonb_build_object('${sub.root.entity}', v_data),
-    'schema', '${schemaJson}'::jsonb
-  );
 END;
 $$;`;
   } else {
-    // Single record subscribable
+    // Single record subscribable - return single JSONB
     return `CREATE OR REPLACE FUNCTION dzql_v2.get_${name}(
   p_params JSONB,
   p_user_id INT
@@ -378,11 +371,8 @@ ${paramExtracts}
   FROM ${sub.root.entity} root
   ${whereClause};
 
-  -- Return data with embedded schema for atomic updates
-  RETURN jsonb_build_object(
-    'data', v_data,
-    'schema', '${schemaJson}'::jsonb
-  );
+  -- Return data
+  RETURN v_data;
 END;
 $$;`;
   }

package/src/cli/compiler/ir.ts

@@ -185,6 +185,7 @@ export function generateIR(domain: DomainConfig): DomainIR {
       primaryKey: pk,
       columns,
       labelField: config.label || 'id',
+      searchable: config.searchable,
       softDelete: config.softDelete || false,
       managed: config.managed !== false, // Default to true, only false if explicitly set
       hidden: config.hidden || [],

package/src/runtime/server.ts

@@ -85,7 +85,56 @@ export async function handleRequest(
 
     const sql = `SELECT ${qualifiedName}(${sqlArgs.join(', ')}) as result`;
     const rows = await db.query(sql, dbParams);
-    return rows[0].result;
+
+    // 5. Post-Processing & Schema Attachment (for Subscribables)
+    const subName = method.startsWith('get_') ? method.slice(4) : null;
+    const subscribable = subName ? manifest.subscribables[subName] : null;
+
+    if (subscribable) {
+      // ... (existing code) ...
+      // It's a subscribable getter!
+      const pathMapping: Record<string, string> = {};
+      pathMapping[subscribable.root.entity] = '.';
+      
+      const buildPaths = (incl: any, parent: string) => {
+        for (const [relName, relConfig] of Object.entries(incl || {})) {
+          const currentPath = parent ? `${parent}.${relName}` : relName;
+          pathMapping[(relConfig as any).entity] = currentPath;
+          if ((relConfig as any).includes) buildPaths((relConfig as any).includes, currentPath);
+        }
+      };
+      buildPaths(subscribable.includes, '');
+
+      const schema = {
+        root: subscribable.root.entity,
+        paths: pathMapping,
+        scopeTables: subscribable.scopeTables
+      };
+
+      let data: any;
+      if (!subscribable.root.key) {
+        // List Subscribable: Aggregate rows in Bun
+        const items = rows.map((r: any) => r.result).filter((i: any) => i !== null);
+        data = { [subscribable.root.entity]: items };
+      } else {
+        // Single Item Subscribable
+        data = rows[0]?.result || null;
+      }
+
+      return { data, schema };
+    }
+
+    // 6. Handle Search/Lookup (List results)
+    if (method.startsWith('search_') || method.startsWith('lookup_')) {
+        console.log(`[Runtime] Handling search/lookup: ${method}, rows:`, rows.length);
+        const results = rows.map((r: any) => r.result).filter((i: any) => i !== null);
+        console.log(`[Runtime] Mapped results type:`, Array.isArray(results) ? 'Array' : typeof results);
+        return results;
+    }
+
+    // Standard CRUD (get/save/delete) -> return single row result
+    return rows[0]?.result;
+
   } catch (err: any) {
     // 5. Error Sanitization
     console.error(`[Runtime] DB Error executing ${method}:`, err);

package/src/shared/ir.ts

@@ -136,6 +136,7 @@ export interface EntityIR {
   primaryKey: string[];
   columns: Array<{ name: string; type: string; isArray: boolean }>;
   labelField?: string;
+  searchable?: string[];
   softDelete?: boolean;
   managed?: boolean; // If false, skip CRUD function generation (for junction tables)
   hidden?: string[]; // Fields to exclude from query results (e.g., password_hash)