dzql 0.6.15 → 0.6.17

package/package.json

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

package/src/cli/codegen/client.ts

@@ -15,8 +15,27 @@ export function generateClientSDK(manifest: Manifest): string {
   const subscriptionFunctions = Object.entries(manifest.functions)
     .filter(([_, def]) => def.isSubscription);
 
-  // Generate entity types
-  const typeDefs = generateTypeDefinitions(manifest.entities, manifest.subscribables);
+  // Build a map of custom functions with typed params/returns
+  const typedCustomFunctions = new Map<string, { hasParams: boolean; hasReturns: boolean; returnsScalar: boolean }>();
+  if (manifest.customFunctions) {
+    for (const fn of manifest.customFunctions) {
+      const hasParams = fn.params && Object.keys(fn.params).length > 0;
+      const hasReturns = fn.returns !== undefined;
+      const returnsScalar = typeof fn.returns === 'string';
+      typedCustomFunctions.set(fn.name, { hasParams: !!hasParams, hasReturns, returnsScalar });
+    }
+  }
+
+  // Generate entity types (now with auth, subscribable results, and custom function types)
+  const typeDefs = generateTypeDefinitions(
+    manifest.entities,
+    manifest.subscribables,
+    manifest.auth,
+    manifest.customFunctions
+  );
+
+  // Check if we have auth types
+  const hasAuth = manifest.auth !== undefined;
 
   // Generate API interface with proper types
   const apiMethods = Object.entries(manifest.functions).map(([funcName, def]) => {
@@ -29,18 +48,34 @@ export function generateClientSDK(manifest: Manifest): string {
     // Check if this entity exists in manifest
     const entityExists = manifest.entities[entity];
 
+    // Check if this is a subscribable
+    const subscribableExists = manifest.subscribables?.[entity];
+
     let paramType = 'Record<string, unknown>';
     let returnType = 'unknown';
 
+    // Handle auth functions
+    if (funcName === 'login_user' && hasAuth) {
+      return `  ${funcName}: (params: LoginParams) => Promise<LoginResult>;`;
+    }
+    if (funcName === 'register_user' && hasAuth) {
+      return `  ${funcName}: (params: RegisterParams) => Promise<RegisterResult>;`;
+    }
+
+    // Handle subscriptions
     if (isSubscription) {
-      // subscribe_venue_detail -> VenueDetailParams
+      // subscribe_venue_detail -> VenueDetailParams, VenueDetailResult
       paramType = `${pascalEntity}Params`;
-      return `  ${funcName}: (params: ${paramType}, callback: (data: unknown) => void) => Promise<{ data: unknown; subscription_id: string; schema: unknown; unsubscribe: () => Promise<void> }>;`;
-    } else if (op === 'get' && entityExists) {
+      const resultType = subscribableExists ? `${pascalEntity}Result` : 'unknown';
+      return `  ${funcName}: (params: ${paramType}, callback: (data: ${resultType}) => void) => Promise<{ data: ${resultType}; subscription_id: string; schema: unknown; unsubscribe: () => Promise<void> }>;`;
+    }
+
+    // Handle entity CRUD operations
+    if (op === 'get' && entityExists) {
       // get_venue_detail (subscribable getter) vs get_venues (entity getter)
-      if (manifest.subscribables?.[entity]) {
+      if (subscribableExists) {
         paramType = `${pascalEntity}Params`;
-        returnType = 'unknown';
+        returnType = `${pascalEntity}Result`;
       } else {
         paramType = `${pascalEntity}PK`;
         returnType = `${pascalEntity} | null`;
@@ -58,7 +93,24 @@ export function generateClientSDK(manifest: Manifest): string {
       paramType = `Lookup${pascalEntity}Params`;
       returnType = `${pascalEntity}[]`;
     }
-    // Custom functions and auth functions stay as Record<string, unknown>
+
+    // Handle custom functions with typed params/returns
+    const customFnInfo = typedCustomFunctions.get(funcName);
+    if (customFnInfo) {
+      const pascalFuncName = toPascalCase(funcName);
+      if (customFnInfo.hasParams) {
+        paramType = `${pascalFuncName}Params`;
+      }
+      if (customFnInfo.hasReturns) {
+        if (customFnInfo.returnsScalar) {
+          // Find the scalar type from the manifest
+          const fn = manifest.customFunctions?.find(f => f.name === funcName);
+          returnType = fn?.returns as string || 'unknown';
+        } else {
+          returnType = `${pascalFuncName}Result`;
+        }
+      }
+    }
 
     return `  ${funcName}: (params: ${paramType}) => Promise<${returnType}>;`;
   }).join('\n');

package/src/cli/codegen/manifest.ts

@@ -1,10 +1,12 @@
-import { DomainIR, EntityIR, SubscribableIR } from "../../shared/ir.js";
+import { DomainIR, EntityIR, SubscribableIR, AuthIR, CustomFunctionIR } from "../../shared/ir.js";
 
 export interface Manifest {
   version: string;
   functions: Record<string, FunctionDef>;
   entities: Record<string, EntityIR>;
   subscribables: Record<string, SubscribableIR>;
+  auth?: AuthIR;
+  customFunctions?: CustomFunctionIR[];
 }
 
 export interface FunctionDef {
@@ -90,6 +92,8 @@ export function generateManifest(ir: DomainIR): Manifest {
     version: "2.0.0",
     functions,
     entities: ir.entities, // Pass through for client generator
-    subscribables: ir.subscribables
+    subscribables: ir.subscribables,
+    auth: ir.auth,
+    customFunctions: ir.customFunctions
   };
 }

package/src/cli/codegen/sql.ts

@@ -1,6 +1,6 @@
 import { compilePermission } from "../compiler/permissions.js";
 import { compileGraphRules } from "../compiler/graph_rules.js";
-import type { EntityIR, ManyToManyIR } from "../../shared/ir.js";
+import type { EntityIR, ManyToManyIR, IncludeIR } from "../../shared/ir.js";
 
 /** Column info from EntityIR */
 interface ColumnInfo {
@@ -313,6 +313,32 @@ export function generateSaveFunction(name: string, entityIR: EntityIR): string {
     return sql;
   }).join('\n');
 
+  // FK expansion (add related objects to output for real-time events)
+  // Only expand direct FKs (where key_id column exists), not reverse FKs (child arrays)
+  const includes: Record<string, IncludeIR> = entityIR.includes || {};
+  const includeKeys = Object.keys(includes);
+  const fkExpansion = includeKeys.map(key => {
+    const config: IncludeIR = includes[key];
+    const targetEntity = config.entity;
+    const fkField = `${key}_id`; // Convention: author -> author_id
+
+    // Only expand if this is a direct FK (key_id column exists)
+    const hasFkColumn = entityIR.columns.some((c: ColumnInfo) => c.name === fkField);
+
+    if (hasFkColumn) {
+      // Direct FK: single object expansion (e.g., author_id -> author object)
+      return `
+  -- FK: Add ${key} to output (from ${fkField})
+  IF (v_result->>'${fkField}') IS NOT NULL THEN
+    v_result := v_result || jsonb_build_object('${key}',
+      (SELECT to_jsonb(t.*) FROM ${targetEntity} t WHERE t.id = (v_result->>'${fkField}')::int));
+  END IF;`;
+    }
+    // Skip reverse FKs - they would require querying child tables which may not exist
+    // and are not needed for the primary use case of expanding the saved record
+    return '';
+  }).filter(s => s).join('\n');
+
   return `
 CREATE OR REPLACE FUNCTION dzql_v2.save_${name}(p_user_id int, p_data jsonb)
 RETURNS jsonb
@@ -365,6 +391,7 @@ ${m2mExtraction}
   END IF;
 ${m2mSync}
 ${m2mExpansion}
+${fkExpansion}
 
   -- Resolve notification recipients
   v_notify_users := dzql_v2.${name}_notify_users(p_user_id, v_result);

package/src/cli/codegen/types.ts

@@ -1,4 +1,4 @@
-import { EntityIR, SubscribableIR } from "../../shared/ir.js";
+import { EntityIR, SubscribableIR, AuthIR, CustomFunctionIR } from "../../shared/ir.js";
 
 const TYPE_MAP: Record<string, string> = {
   'text': 'string',
@@ -19,6 +19,7 @@ const PARAM_TYPE_MAP: Record<string, string> = {
   'integer': 'number',
   'text': 'string',
   'string': 'string',
+  'number': 'number',
   'boolean': 'boolean',
   'date': 'string',
   'timestamptz': 'string'
@@ -26,7 +27,9 @@ const PARAM_TYPE_MAP: Record<string, string> = {
 
 export function generateTypeDefinitions(
   entities: Record<string, EntityIR>,
-  subscribables?: Record<string, SubscribableIR>
+  subscribables?: Record<string, SubscribableIR>,
+  auth?: AuthIR,
+  customFunctions?: CustomFunctionIR[]
 ): string {
   let output = "";
 
@@ -49,6 +52,7 @@ export type FilterValue<T> = T | FilterOperators<T>;
 
 `;
 
+  // --- Entity Types ---
   for (const [name, entity] of Object.entries(entities)) {
     const pascalName = toPascalCase(name);
 
@@ -106,17 +110,107 @@ export type FilterValue<T> = T | FilterOperators<T>;
 }\n\n`;
   }
 
-  // --- Subscribable Params ---
+  // --- Subscribable Params and Result Types ---
   if (subscribables) {
     for (const [name, sub] of Object.entries(subscribables)) {
       const pascalName = toPascalCase(name);
 
+      // Params interface
       output += `export interface ${pascalName}Params {\n`;
       for (const [paramName, paramType] of Object.entries(sub.params)) {
         const tsType = PARAM_TYPE_MAP[paramType as string] || 'any';
         output += `  ${paramName}: ${tsType};\n`;
       }
       output += `}\n\n`;
+
+      // Result interface (extends root entity with includes)
+      const rootEntity = sub.root?.entity;
+      const rootEntityPascal = rootEntity ? toPascalCase(rootEntity) : null;
+
+      if (rootEntityPascal && entities[rootEntity]) {
+        output += `export interface ${pascalName}Result extends ${rootEntityPascal} {\n`;
+
+        // Add includes as optional fields
+        if (sub.includes) {
+          for (const [includeKey, includeIR] of Object.entries(sub.includes)) {
+            const includeEntity = includeIR.entity;
+            const includeEntityPascal = toPascalCase(includeEntity);
+
+            // Determine if it's an array (one-to-many) or single (many-to-one)
+            // For now, assume arrays unless the include key matches a FK pattern
+            const isArray = !includeKey.endsWith('_id') && includeKey !== rootEntity;
+            const includeType = isArray ? `${includeEntityPascal}[]` : includeEntityPascal;
+
+            output += `  ${includeKey}?: ${includeType};\n`;
+          }
+        }
+
+        output += `}\n\n`;
+      }
+    }
+  }
+
+  // --- Auth Types ---
+  if (auth) {
+    // AuthUser interface
+    output += `export interface AuthUser {\n`;
+    for (const [fieldName, fieldType] of Object.entries(auth.userFields)) {
+      const tsType = PARAM_TYPE_MAP[fieldType] || fieldType;
+      output += `  ${fieldName}: ${tsType};\n`;
+    }
+    output += `}\n\n`;
+
+    // LoginParams interface
+    output += `export interface LoginParams {\n`;
+    for (const [paramName, paramType] of Object.entries(auth.loginParams)) {
+      const tsType = PARAM_TYPE_MAP[paramType] || paramType;
+      output += `  ${paramName}: ${tsType};\n`;
+    }
+    output += `}\n\n`;
+
+    // LoginResult interface
+    output += `export interface LoginResult extends AuthUser {\n`;
+    output += `  token: string;\n`;
+    output += `}\n\n`;
+
+    // RegisterParams interface
+    output += `export interface RegisterParams {\n`;
+    for (const [paramName, paramType] of Object.entries(auth.registerParams)) {
+      const tsType = PARAM_TYPE_MAP[paramType] || paramType;
+      output += `  ${paramName}: ${tsType};\n`;
+    }
+    output += `}\n\n`;
+
+    // RegisterResult interface
+    output += `export interface RegisterResult extends AuthUser {\n`;
+    output += `  token: string;\n`;
+    output += `}\n\n`;
+  }
+
+  // --- Custom Function Types ---
+  if (customFunctions) {
+    for (const fn of customFunctions) {
+      const pascalName = toPascalCase(fn.name);
+
+      // Generate params interface if params are defined
+      if (fn.params && Object.keys(fn.params).length > 0) {
+        output += `export interface ${pascalName}Params {\n`;
+        for (const [paramName, paramType] of Object.entries(fn.params)) {
+          const tsType = PARAM_TYPE_MAP[paramType] || paramType;
+          output += `  ${paramName}: ${tsType};\n`;
+        }
+        output += `}\n\n`;
+      }
+
+      // Generate result interface if returns is an object
+      if (fn.returns && typeof fn.returns === 'object') {
+        output += `export interface ${pascalName}Result {\n`;
+        for (const [fieldName, fieldType] of Object.entries(fn.returns)) {
+          const tsType = PARAM_TYPE_MAP[fieldType] || fieldType;
+          output += `  ${fieldName}: ${tsType};\n`;
+        }
+        output += `}\n\n`;
+      }
     }
   }
 

package/src/cli/compiler/ir.ts

@@ -12,7 +12,8 @@ import type {
   IncludeIR,
   CustomFunctionIR,
   ManyToManyIR,
-  GraphRuleIR
+  GraphRuleIR,
+  AuthIR
 } from "../../shared/ir.js";
 
 /**
@@ -175,6 +176,9 @@ export function generateIR(domain: DomainConfig): DomainIR {
       };
     }
 
+    // Parse includes (FK expansions)
+    const includes = parseIncludes(config.includes as Record<string, string | IncludeConfig> | undefined);
+
     entities[name] = {
       name,
       table: name,
@@ -187,6 +191,7 @@ export function generateIR(domain: DomainConfig): DomainIR {
       fieldDefaults: config.fieldDefaults || {},
       permissions,
       relationships: {},
+      includes,
       manyToMany,
       graphRules: {
         onCreate: onCreateRules,
@@ -220,14 +225,68 @@ export function generateIR(domain: DomainConfig): DomainIR {
       customFunctions.push({
         name: fn.name,
         sql: fn.sql,
-        args: fn.args || ['p_user_id', 'p_params']
+        args: fn.args || ['p_user_id', 'p_params'],
+        params: fn.params,
+        returns: fn.returns
       });
     }
   }
 
+  // --- AUTH CONFIG ---
+  // Generate default auth config based on users entity if not provided
+  let auth: AuthIR | undefined;
+
+  if (domain.auth) {
+    // Use explicit auth config
+    auth = {
+      userFields: domain.auth.userFields || {},
+      loginParams: domain.auth.loginParams || { email: 'string', password: 'string' },
+      registerParams: domain.auth.registerParams || { email: 'string', password: 'string' }
+    };
+  } else if (entities['users']) {
+    // Derive auth config from users entity
+    const usersEntity = entities['users'];
+    const hiddenFields = new Set(usersEntity.hidden || []);
+    hiddenFields.add('password_hash');
+    hiddenFields.add('password');
+
+    // Map user columns to TypeScript types (excluding hidden fields)
+    const userFields: Record<string, string> = {
+      user_id: 'number'  // Always include user_id
+    };
+
+    for (const col of usersEntity.columns) {
+      if (!hiddenFields.has(col.name) && col.name !== 'id') {
+        userFields[col.name] = mapPgTypeToTsType(col.type);
+      }
+    }
+
+    auth = {
+      userFields,
+      loginParams: { email: 'string', password: 'string' },
+      registerParams: { email: 'string', password: 'string' }
+    };
+  }
+
   return {
     entities,
     subscribables,
-    customFunctions
+    customFunctions,
+    auth
   };
 }
+
+/**
+ * Maps PostgreSQL column type to TypeScript type string
+ */
+function mapPgTypeToTsType(pgType: string): string {
+  const lower = pgType.toLowerCase();
+  if (lower.includes('int') || lower.includes('serial') || lower.includes('decimal') || lower.includes('numeric')) {
+    return 'number';
+  }
+  if (lower.includes('bool')) {
+    return 'boolean';
+  }
+  // Default to string for text, timestamps, etc.
+  return 'string';
+}

package/src/shared/ir.ts

@@ -100,6 +100,20 @@ export interface CustomFunctionConfig {
   name: string;
   sql: string;
   args?: string[];
+  /** Parameter types for TypeScript generation: { paramName: 'number' | 'string' | ... } */
+  params?: Record<string, string>;
+  /** Return type: either an object shape or a scalar type name */
+  returns?: Record<string, string> | string;
+}
+
+/** Auth configuration for TypeScript type generation */
+export interface AuthConfig {
+  /** Fields returned by auth functions (user profile shape) */
+  userFields?: Record<string, string>;
+  /** Login function parameter types */
+  loginParams?: Record<string, string>;
+  /** Register function parameter types */
+  registerParams?: Record<string, string>;
 }
 
 /** Complete domain configuration as provided in domain file */
@@ -107,6 +121,7 @@ export interface DomainConfig {
   entities: Record<string, EntityConfig>;
   subscribables?: Record<string, SubscribableConfig>;
   customFunctions?: CustomFunctionConfig[];
+  auth?: AuthConfig;
 }
 
 // ============================================
@@ -130,6 +145,7 @@ export interface EntityIR {
     delete: string[];
   };
   relationships: Record<string, RelationshipIR>;
+  includes: Record<string, IncludeIR>; // FK expansions (e.g., author: users)
   manyToMany: Record<string, ManyToManyIR>;
   graphRules: {
     onCreate: GraphRuleIR[];
@@ -190,10 +206,25 @@ export interface CustomFunctionIR {
   name: string;
   sql: string;
   args?: string[];  // For manifest allowlist
+  /** Parameter types for TypeScript generation */
+  params?: Record<string, string>;
+  /** Return type: either an object shape or a scalar type name */
+  returns?: Record<string, string> | string;
+}
+
+/** Auth IR for TypeScript type generation */
+export interface AuthIR {
+  /** Fields returned by auth functions (user profile shape) */
+  userFields: Record<string, string>;
+  /** Login function parameter types */
+  loginParams: Record<string, string>;
+  /** Register function parameter types */
+  registerParams: Record<string, string>;
 }
 
 export interface DomainIR {
   entities: Record<string, EntityIR>;
   subscribables: Record<string, SubscribableIR>;
   customFunctions: CustomFunctionIR[];
+  auth?: AuthIR;
 }