drizzle-cube 0.2.16 → 0.2.17

package/dist/server/index.d.ts

@@ -535,6 +535,16 @@ export declare interface JoinKeyInfo {
     targetColumnObj?: AnyColumn;
 }
 
+/**
+ * Single join key pair for composite key support
+ */
+export declare interface JoinKeyPair {
+    /** Primary key column on source cube */
+    source: AnyColumn;
+    /** Foreign key column on target cube (CTE cube) */
+    target: AnyColumn;
+}
+
 /**
  * Complete join path from primary to target cube
  */
@@ -820,13 +830,8 @@ export declare interface PropagatingFilter {
     sourceCube: Cube;
     /** Filters from the source cube to apply */
     filters: Filter[];
-    /** Join condition linking source cube PK to target cube FK */
-    joinCondition: {
-        /** Primary key column on source cube */
-        source: AnyColumn;
-        /** Foreign key column on target cube (CTE cube) */
-        target: AnyColumn;
-    };
+    /** Join conditions linking source cube PK(s) to target cube FK(s) - supports composite keys */
+    joinConditions: JoinKeyPair[];
     /** Pre-built filter SQL for parameter deduplication (optional, built during query planning) */
     preBuiltFilterSQL?: SQL;
 }
@@ -860,18 +865,14 @@ export declare interface QueryAnalysis {
 }
 
 export declare class QueryBuilder {
-    private databaseAdapter;
+    private dateTimeBuilder;
+    private filterBuilder;
+    private groupByBuilder;
+    private measureBuilder;
     constructor(databaseAdapter: DatabaseAdapter);
     /**
      * Build resolvedMeasures map for a set of measures
-     * This centralizes the logic for building both regular and calculated measures
-     * in dependency order, avoiding duplication across main queries and CTEs
-     *
-     * @param measureNames - Array of measure names to resolve (e.g., ["Employees.count", "Employees.activePercentage"])
-     * @param cubeMap - Map of all cubes involved in the query
-     * @param context - Query context with database and security context
-     * @param customMeasureBuilder - Optional function to override how individual measures are built
-     * @returns Map of measure names to SQL builder functions
+     * Delegates to MeasureBuilder
      */
     buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
     /**
@@ -882,22 +883,12 @@ export declare class QueryBuilder {
     buildSelections(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext): Record<string, SQL | AnyColumn>;
     /**
      * Build calculated measure expression by substituting {member} references
-     * with resolved SQL expressions
+     * Delegates to MeasureBuilder
      */
     buildCalculatedMeasure(measure: any, cube: Cube, allCubes: Map<string, Cube>, resolvedMeasures: ResolvedMeasures, context: QueryContext): SQL;
     /**
      * Build resolved measures map for a calculated measure from CTE columns
-     * This handles re-aggregating pre-aggregated CTE columns for calculated measures
-     *
-     * IMPORTANT: For calculated measures in CTEs, we cannot sum/avg pre-computed ratios.
-     * We must recalculate from the base measures that were pre-aggregated in the CTE.
-     *
-     * @param measure - The calculated measure to build
-     * @param cube - The cube containing this measure
-     * @param cteInfo - CTE metadata (alias, measures, cube reference)
-     * @param allCubes - Map of all cubes in the query
-     * @param context - Query context
-     * @returns SQL expression for the calculated measure using CTE column references
+     * Delegates to MeasureBuilder
      */
     buildCTECalculatedMeasure(measure: any, cube: Cube, cteInfo: {
         cteAlias: string;
@@ -906,19 +897,17 @@ export declare class QueryBuilder {
     }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
     /**
      * Build measure expression for HAVING clause, handling CTE references correctly
+     * Delegates to MeasureBuilder
      */
     private buildHavingMeasureExpression;
     /**
      * Build measure expression with aggregation and filters
-     * Note: This should NOT be called for calculated measures
-     *
-     * @param measure - The measure definition
-     * @param context - Query context with security context and database info
-     * @param cube - Optional cube reference for resolving dimension references (window functions)
+     * Delegates to MeasureBuilder
      */
     buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
     /**
      * Build time dimension expression with granularity using database adapter
+     * Delegates to DateTimeBuilder
      */
     buildTimeDimensionExpression(dimensionSql: any, granularity: string | undefined, context: QueryContext): SQL;
     /**
@@ -939,37 +928,17 @@ export declare class QueryBuilder {
     private processFilter;
     /**
      * Build filter condition using Drizzle operators
+     * Delegates to FilterBuilder
      */
     private buildFilterCondition;
     /**
      * Build date range condition for time dimensions
+     * Delegates to DateTimeBuilder
      */
     buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
-    /**
-     * Parse relative date range expressions like "today", "yesterday", "last 7 days", "this month", etc.
-     * Handles all 14 DATE_RANGE_OPTIONS from the client
-     */
-    private parseRelativeDateRange;
-    /**
-     * Normalize date values to handle strings, numbers, and Date objects
-     * Returns ISO string for PostgreSQL/MySQL, Unix timestamp for SQLite, or null
-     * Ensures dates are in the correct format for each database engine
-     */
-    private normalizeDate;
-    /**
-     * Check if a measure type is a window function
-     */
-    private isWindowFunctionType;
-    /**
-     * Check if a measure type is an aggregate function (requires GROUP BY)
-     */
-    private isAggregateFunctionType;
     /**
      * Build GROUP BY fields from dimensions and time dimensions
-     * Works for both single and multi-cube queries
-     *
-     * NOTE: GROUP BY is only added when there are AGGREGATE measures.
-     * Window functions do not require GROUP BY and operate on individual rows.
+     * Delegates to GroupByBuilder
      */
     buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: any): (SQL | AnyColumn)[];
     /**
@@ -994,13 +963,9 @@ export declare class QueryBuilder {
     /**
      * Build a logical filter (AND/OR) - used by executor for cache preloading
      * This handles nested filter structures and builds combined SQL
+     * Delegates to FilterBuilder
      */
     buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
-    /**
-     * Build SQL for a single filter condition (simple or logical)
-     * Used for cache preloading to build filters independently of query context
-     */
-    private buildSingleFilter;
 }
 
 /**
@@ -1031,6 +996,7 @@ export declare class QueryExecutor {
     private dbExecutor;
     private queryBuilder;
     private queryPlanner;
+    private cteBuilder;
     private databaseAdapter;
     constructor(dbExecutor: DatabaseExecutor);
     /**
@@ -1042,21 +1008,13 @@ export declare class QueryExecutor {
      */
     executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
     /**
-     * Build pre-aggregation CTE for hasMany relationships
-     */
-    private buildPreAggregationCTE;
-    /**
-     * Build join condition for CTE
-     */
-    private buildCTEJoinCondition;
-    /**
-     * Build a subquery filter for propagating filters from related cubes.
-     * This generates: cteCube.FK IN (SELECT sourceCube.PK FROM sourceCube WHERE filters...)
+     * Validate that all cubes in the query plan have proper security filtering.
+     * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
      *
-     * Example: For Productivity CTE with Employees.createdAt filter:
-     * employee_id IN (SELECT id FROM employees WHERE organisation_id = $1 AND created_at >= $date)
+     * Security is critical in multi-tenant applications - this validation helps
+     * detect cubes that may leak data across tenants.
      */
-    private buildPropagatingFilterSubquery;
+    private validateSecurityContext;
     /**
      * Build unified query that works for both single and multi-cube queries
      */
@@ -1134,6 +1092,11 @@ export declare interface QueryPlan {
  * Pre-aggregation plan for handling hasMany relationships
  */
 export declare class QueryPlanner {
+    private resolverCache;
+    /**
+     * Get or create a JoinPathResolver for the given cubes map
+     */
+    private getResolver;
     /**
      * Analyze a semantic query to determine which cubes are involved
      */
@@ -1158,26 +1121,16 @@ export declare class QueryPlanner {
     /**
      * Choose the primary cube based on query analysis
      * Uses a consistent strategy to avoid measure order dependencies
+     *
+     * Delegates to analyzePrimaryCubeSelection() for the actual logic,
+     * ensuring a single source of truth for primary cube selection.
      */
     choosePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes?: Map<string, Cube>): string;
-    /**
-     * Check if a cube can reach all other cubes in the list via joins
-     */
-    private canReachAllCubes;
     /**
      * Build join plan for multi-cube query
      * Supports both direct joins and transitive joins through intermediate cubes
      */
     private buildJoinPlan;
-    /**
-     * Build join condition from new array-based join definition
-     */
-    private buildJoinCondition;
-    /**
-     * Find join path from source cube to target cube
-     * Returns array of join steps to reach target
-     */
-    private findJoinPath;
     /**
      * Plan pre-aggregation CTEs for hasMany relationships to prevent fan-out
      * Note: belongsToMany relationships handle fan-out differently through their junction table structure
@@ -1211,8 +1164,19 @@ export declare class QueryPlanner {
     private extractFilterCubeNamesToSet;
     /**
      * Extract filters for a specific cube from the filter array
+     *
+     * Logic for preserving filter semantics:
+     * - AND: Safe to extract only matching branches (AND of fewer conditions is more permissive)
+     * - OR: Must include ALL branches or skip entirely (partial OR changes semantics)
+     *       If any branch belongs to another cube, skip the entire OR to be safe
+     *       since we can't evaluate the other cube's conditions
      */
     private extractFiltersForCube;
+    /**
+     * Check if all simple filters in a filter array belong to the specified cube
+     * Recursively checks nested AND/OR filters
+     */
+    private allFiltersFromCube;
     /**
      * Extract time dimension date range filters as regular filters for a specific cube
      */
@@ -1229,6 +1193,9 @@ export declare class QueryPlanner {
     private analyzePrimaryCubeSelection;
     /**
      * Analyze the join path between two cubes with detailed step information
+     *
+     * Uses JoinPathResolver.findPath() for the actual path finding,
+     * then converts the result to human-readable analysis format.
      */
     private analyzeJoinPath;
     /**
@@ -1301,8 +1268,6 @@ export declare class SemanticLayerCompiler {
     private cubes;
     private dbExecutor?;
     private metadataCache?;
-    private metadataCacheTimestamp?;
-    private readonly METADATA_CACHE_TTL;
     constructor(options?: {
         drizzle?: DatabaseExecutor['db'];
         schema?: any;
@@ -1362,6 +1327,7 @@ export declare class SemanticLayerCompiler {
     /**
      * Get metadata for all cubes (for API responses)
      * Uses caching to improve performance for repeated requests
+     * Cache is invalidated when cubes are modified (registerCube, removeCube, clearCubes)
      */
     getMetadata(): CubeMetadata[];
     /**