drizzle-cube 0.1.35 → 0.1.37

package/dist/server/index.d.ts

@@ -145,7 +145,7 @@ declare interface CubeJoin {
     /** Target cube reference - lazy loaded to avoid circular dependencies */
     targetCube: Cube | (() => Cube);
     /** Semantic relationship - determines join behavior */
-    relationship: 'belongsTo' | 'hasOne' | 'hasMany';
+    relationship: CubeRelationship;
     /** Array of join conditions - supports multi-column joins */
     on: Array<{
         /** Column from source cube */
@@ -157,6 +157,28 @@ declare interface CubeJoin {
     }>;
     /** Override default SQL join type (derived from relationship) */
     sqlJoinType?: 'inner' | 'left' | 'right' | 'full';
+    /**
+     * Many-to-many relationship configuration through a junction table
+     * Only used when relationship is 'belongsToMany'
+     */
+    through?: {
+        /** Junction/join table (Drizzle table reference) */
+        table: Table;
+        /** Join conditions from source cube to junction table */
+        sourceKey: Array<{
+            source: AnyColumn;
+            target: AnyColumn;
+            as?: (source: AnyColumn, target: AnyColumn) => SQL;
+        }>;
+        /** Join conditions from junction table to target cube */
+        targetKey: Array<{
+            source: AnyColumn;
+            target: AnyColumn;
+            as?: (source: AnyColumn, target: AnyColumn) => SQL;
+        }>;
+        /** Optional security context SQL for junction table */
+        securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
+    };
 }
 export { CubeJoin }
 export { CubeJoin as SemanticJoin }
@@ -174,12 +196,17 @@ export declare interface CubeMetadata {
     relationships?: CubeRelationshipMetadata[];
 }
 
+/**
+ * Relationship types supported by cube joins
+ */
+export declare type CubeRelationship = 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+
 /**
  * Cube relationship metadata for ERD visualization
  */
 export declare interface CubeRelationshipMetadata {
     targetCube: string;
-    relationship: 'belongsTo' | 'hasOne' | 'hasMany';
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
     joinFields: Array<{
         sourceField: string;
         targetField: string;
@@ -662,6 +689,15 @@ export declare interface QueryPlan {
         alias: string;
         joinType: 'inner' | 'left' | 'right' | 'full';
         joinCondition: SQL;
+        /** Junction table information for belongsToMany relationships */
+        junctionTable?: {
+            table: Table;
+            alias: string;
+            joinType: 'inner' | 'left' | 'right' | 'full';
+            joinCondition: SQL;
+            /** Optional security SQL function to apply to junction table */
+            securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
+        };
     }>;
     /** Combined field selections across all cubes (built by QueryBuilder) */
     selections: Record<string, SQL | AnyColumn>;
@@ -707,7 +743,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
@@ -733,6 +769,8 @@ 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;
     /**