drizzle-cube 0.1.36 → 0.1.38

package/dist/server/index.d.ts

@@ -285,6 +285,13 @@ declare interface DatabaseAdapter {
      * @returns Date object or original value if not a time dimension
      */
     convertTimeDimensionResult(value: any): any;
+    /**
+     * Preprocess calculated measure template for database-specific transformations
+     * This allows each adapter to modify the template before substitution occurs
+     * @param calculatedSql - The template string with {member} references
+     * @returns Preprocessed template string
+     */
+    preprocessCalculatedTemplate(calculatedSql: string): string;
 }
 
 /**
@@ -413,6 +420,21 @@ export declare type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notC
  */
 export declare function getJoinType(relationship: string, override?: string): string;
 
+/**
+ * Join key information for CTE joins
+ * Describes how a CTE should be joined to the main query
+ */
+export declare interface JoinKeyInfo {
+    /** Column name in the source table */
+    sourceColumn: string;
+    /** Column name in the target table (CTE) */
+    targetColumn: string;
+    /** Optional Drizzle column object for source */
+    sourceColumnObj?: AnyColumn;
+    /** Optional Drizzle column object for target */
+    targetColumnObj?: AnyColumn;
+}
+
 export declare type JoinType = 'left' | 'right' | 'inner' | 'full';
 
 export declare interface LogicalFilter {
@@ -442,6 +464,18 @@ declare interface Measure {
         leading?: string;
         offset?: string;
     };
+    /**
+     * Calculated measure template with {member} references
+     * Only used when type === 'calculated'
+     * Example: "1.0 * {completed} / NULLIF({total}, 0)"
+     */
+    calculatedSql?: string;
+    /**
+     * List of measure dependencies for calculated measures
+     * Auto-detected from calculatedSql if not provided
+     * Example: ['completed', 'total']
+     */
+    dependencies?: string[];
     /** Additional metadata */
     meta?: Record<string, any>;
 }
@@ -475,7 +509,7 @@ export declare interface MeasureMetadata {
 /**
  * Type enums and constants
  */
-export declare type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number';
+export declare type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number' | 'calculated';
 
 /**
  * Multi-cube query context for cross-cube operations
@@ -520,6 +554,23 @@ export declare class PostgresExecutor extends BaseDatabaseExecutor {
     getEngineType(): 'postgres';
 }
 
+/**
+ * Pre-aggregation CTE information
+ * Describes a Common Table Expression used for pre-aggregating hasMany relationships
+ */
+export declare interface PreAggregationCTEInfo {
+    /** The cube being pre-aggregated */
+    cube: Cube;
+    /** Table alias for this cube in the main query */
+    alias: string;
+    /** CTE alias (WITH clause name) */
+    cteAlias: string;
+    /** Join keys to connect CTE back to main query */
+    joinKeys: JoinKeyInfo[];
+    /** List of measure names included in this CTE */
+    measures: string[];
+}
+
 /**
  * Any queryable relation that can be used in FROM/JOIN clauses
  * Supports tables, views, subqueries, and raw SQL expressions
@@ -529,17 +580,55 @@ export declare type QueryableRelation = Table | View | Subquery | SQL;
 export declare class QueryBuilder {
     private databaseAdapter;
     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
+     */
+    buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
     /**
      * Build dynamic selections for measures, dimensions, and time dimensions
      * Works for both single and multi-cube queries
+     * Handles calculated measures with dependency resolution
      */
     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
+     */
+    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
+     */
+    buildCTECalculatedMeasure(measure: any, cube: Cube, cteInfo: {
+        cteAlias: string;
+        measures: string[];
+        cube: Cube;
+    }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
     /**
      * Build measure expression for HAVING clause, handling CTE references correctly
      */
     private buildHavingMeasureExpression;
     /**
      * Build measure expression with aggregation and filters
+     * Note: This should NOT be called for calculated measures
      */
     buildMeasureExpression(measure: any, context: QueryContext): SQL;
     /**
@@ -576,8 +665,8 @@ export declare class QueryBuilder {
     private parseRelativeDateRange;
     /**
      * Normalize date values to handle strings, numbers, and Date objects
-     * Always returns a JavaScript Date object or null
-     * Database-agnostic - just ensures we have a valid Date
+     * 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;
     /**
@@ -706,18 +795,7 @@ export declare interface QueryPlan {
     /** GROUP BY fields if aggregations are present (built by QueryBuilder) */
     groupByFields: (SQL | AnyColumn)[];
     /** Pre-aggregation CTEs for hasMany relationships to prevent fan-out */
-    preAggregationCTEs?: Array<{
-        cube: Cube;
-        alias: string;
-        cteAlias: string;
-        joinKeys: Array<{
-            sourceColumn: string;
-            targetColumn: string;
-            sourceColumnObj?: AnyColumn;
-            targetColumnObj?: AnyColumn;
-        }>;
-        measures: string[];
-    }>;
+    preAggregationCTEs?: PreAggregationCTEInfo[];
 }
 
 /**
@@ -743,7 +821,7 @@ export declare class QueryPlanner {
     /**
      * Create a unified query plan that works for both single and multi-cube queries
      */
-    createQueryPlan(cubes: Map<string, Cube>, query: SemanticQuery, _ctx: QueryContext): QueryPlan;
+    createQueryPlan(cubes: Map<string, Cube>, query: SemanticQuery, ctx: QueryContext): QueryPlan;
     /**
      * Choose the primary cube based on query analysis
      * Uses a consistent strategy to avoid measure order dependencies
@@ -769,8 +847,18 @@ export declare class QueryPlanner {
     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
+     * and don't require CTEs - the two-hop join with the junction table provides natural grouping
      */
     private planPreAggregationCTEs;
+    /**
+     * Expand calculated measures to include their dependencies
+     */
+    private expandCalculatedMeasureDependencies;
+    /**
+     * Extract measure references from calculatedSql template
+     */
+    private extractDependenciesFromTemplate;
     /**
      * Find hasMany join definition from primary cube to target cube
      */
@@ -796,7 +884,21 @@ export declare interface QueryResult {
 export declare function resolveCubeReference(ref: Cube | (() => Cube)): Cube;
 
 /**
- * Helper to resolve SQL expressions
+ * Resolved measure SQL builders
+ * Maps full measure names (e.g., "Cube.measure") to functions that build their SQL
+ * Using functions instead of SQL objects avoids mutation and shared reference issues
+ */
+declare type ResolvedMeasures = Map<string, () => SQL>;
+
+/**
+ * Helper to resolve SQL expressions with mutation protection
+ *
+ * Evaluates function-based SQL expressions and applies isolation to prevent
+ * Drizzle's internal mutation from corrupting reused SQL objects.
+ *
+ * @param expr - Column, SQL object, or function that returns one
+ * @param ctx - Query context for function evaluation
+ * @returns Isolated SQL expression safe for reuse
  */
 export declare function resolveSqlExpression(expr: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL), ctx: QueryContext): AnyColumn | SQL;
 
@@ -840,8 +942,14 @@ export declare class SemanticLayerCompiler {
     hasExecutor(): boolean;
     /**
      * Register a simplified cube with dynamic query building
+     * Validates calculated measures during registration
      */
     registerCube(cube: Cube): void;
+    /**
+     * Validate calculated measures in a cube
+     * Checks template syntax, dependency existence, and circular dependencies
+     */
+    private validateCalculatedMeasures;
     /**
      * Get a cube by name
      */