drizzle-cube 0.6.0 → 0.6.2

package/dist/cjs/client/shared/types.d.ts

@@ -0,0 +1,184 @@
+import { CubeQuery, FilterOperator } from '../types.js';
+export interface MetaField {
+    name: string;
+    title: string;
+    shortTitle: string;
+    type: string;
+    description?: string;
+}
+export interface MetaCubeRelationship {
+    targetCube: string;
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    joinFields?: Array<{
+        sourceField: string;
+        targetField: string;
+    }>;
+}
+export interface MetaCube {
+    name: string;
+    title: string;
+    description: string;
+    measures: MetaField[];
+    dimensions: MetaField[];
+    segments: MetaField[];
+    relationships?: MetaCubeRelationship[];
+}
+export interface MetaResponse {
+    cubes: MetaCube[];
+}
+/**
+ * Severity level for query warnings
+ */
+export type QueryWarningSeverity = 'info' | 'warning' | 'error';
+/**
+ * Warning emitted during query planning or execution
+ * Provides user-facing feedback about potential query issues
+ */
+export interface QueryWarning {
+    /** Unique code for programmatic handling (e.g., 'FAN_OUT_NO_DIMENSIONS') */
+    code: string;
+    /** Human-readable warning message */
+    message: string;
+    /** Severity level for UI styling */
+    severity: QueryWarningSeverity;
+    /** Cubes involved in the warning (if applicable) */
+    cubes?: string[];
+    /** Measures involved in the warning (if applicable) */
+    measures?: string[];
+    /** Actionable suggestion for the user */
+    suggestion?: string;
+}
+export type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
+export interface PrimaryCubeCandidate {
+    cubeName: string;
+    dimensionCount: number;
+    joinCount: number;
+    canReachAll: boolean;
+}
+export interface PrimaryCubeAnalysis {
+    selectedCube: string;
+    reason: PrimaryCubeSelectionReason;
+    explanation: string;
+    candidates?: PrimaryCubeCandidate[];
+}
+export interface JoinPathStep {
+    fromCube: string;
+    toCube: string;
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    joinColumns: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    junctionTable?: {
+        tableName: string;
+        sourceColumns: string[];
+        targetColumns: string[];
+    };
+}
+export interface JoinPathAnalysis {
+    targetCube: string;
+    pathFound: boolean;
+    path?: JoinPathStep[];
+    pathLength?: number;
+    error?: string;
+    visitedCubes?: string[];
+    selection?: {
+        strategy: 'shortest' | 'preferred' | 'fallbackShortest';
+        preferredCubes?: string[];
+        selectedRank?: number;
+        selectedScore?: number;
+        candidates?: Array<{
+            rank: number;
+            score: number;
+            usesPreferredJoin: boolean;
+            preferredCubesInPath: number;
+            usesProcessed: boolean;
+            scoreBreakdown: {
+                preferredJoinBonus: number;
+                preferredCubeBonus: number;
+                lengthPenalty: number;
+            };
+            path: JoinPathStep[];
+        }>;
+    };
+}
+/**
+ * Reason why a cube requires a CTE
+ */
+export type CTEReason = 'hasMany' | 'fanOutPrevention';
+export interface PreAggregationAnalysis {
+    cubeName: string;
+    cteAlias: string;
+    /** Why this cube needs a CTE (human-readable explanation) */
+    reason: string;
+    /** Typed reason for programmatic use */
+    reasonType?: CTEReason;
+    measures: string[];
+    joinKeys: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+}
+export interface QuerySummary {
+    queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    measureStrategy?: 'simple' | 'keysDeduplication' | 'ctePreAggregateFallback' | 'multiFactMerge';
+    joinCount: number;
+    cteCount: number;
+    hasPreAggregation: boolean;
+}
+export interface QueryAnalysis {
+    timestamp: string;
+    cubeCount: number;
+    cubesInvolved: string[];
+    primaryCube: PrimaryCubeAnalysis;
+    joinPaths: JoinPathAnalysis[];
+    preAggregations: PreAggregationAnalysis[];
+    querySummary: QuerySummary;
+    warnings?: string[];
+    planningTrace?: {
+        steps: Array<{
+            phase: 'cube_usage' | 'primary_cube_selection' | 'join_planning' | 'cte_planning' | 'measure_strategy' | 'warnings';
+            decision: string;
+            details?: Record<string, unknown>;
+        }>;
+    };
+}
+export interface ValidationResult {
+    valid?: boolean;
+    error?: string;
+    query?: CubeQuery;
+    sql?: {
+        sql: string[];
+        params: any[];
+    };
+    queryType?: string;
+    normalizedQueries?: any[];
+    queryOrder?: string[];
+    transformedQueries?: any[];
+    pivotQuery?: any;
+    complexity?: string;
+    cubesUsed?: string[];
+    joinType?: string;
+    analysis?: QueryAnalysis;
+}
+export interface FilterOperatorMeta {
+    label: string;
+    description: string;
+    requiresValues: boolean;
+    supportsMultipleValues: boolean;
+    valueType: 'string' | 'number' | 'date' | 'boolean' | 'any';
+    fieldTypes: string[];
+}
+export declare const FILTER_OPERATORS: Record<FilterOperator, FilterOperatorMeta>;
+export type DateRangeType = 'custom' | 'today' | 'yesterday' | 'this_week' | 'this_month' | 'this_quarter' | 'this_year' | 'last_7_days' | 'last_30_days' | 'last_week' | 'last_month' | 'last_quarter' | 'last_year' | 'last_12_months' | 'last_n_days' | 'last_n_weeks' | 'last_n_months' | 'last_n_quarters' | 'last_n_years';
+export interface DateRangeOption {
+    value: DateRangeType;
+    label: string;
+}
+export declare const DATE_RANGE_OPTIONS: DateRangeOption[];
+export declare const TIME_GRANULARITIES: {
+    value: string;
+    label: string;
+}[];
+export type TimeGranularity = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';

package/dist/cjs/client/shared/utils.d.ts

@@ -0,0 +1,104 @@
+import { CubeQuery, Filter, SimpleFilter, GroupFilter } from '../types.js';
+import { MetaField, MetaResponse } from './types.js';
+import { cleanQuery } from './queryTransforms.js';
+export { cleanQuery };
+/**
+ * Check if a filter is a simple filter
+ */
+export declare function isSimpleFilter(filter: Filter): filter is SimpleFilter;
+/**
+ * Check if a filter is a group filter
+ */
+export declare function isGroupFilter(filter: Filter): filter is GroupFilter;
+/**
+ * Check if a filter is an AND filter
+ */
+export declare function isAndFilter(filter: Filter): filter is GroupFilter;
+/**
+ * Check if a filter is an OR filter
+ */
+export declare function isOrFilter(filter: Filter): filter is GroupFilter;
+/**
+ * Flatten all simple filters from a hierarchical filter structure
+ */
+export declare function flattenFilters(filters: Filter[]): SimpleFilter[];
+/**
+ * Count total filters in hierarchical structure
+ */
+export declare function countFilters(filters: Filter[]): number;
+/**
+ * Create a new simple filter
+ */
+export declare function createSimpleFilter(member: string, operator?: string, values?: any[]): SimpleFilter;
+/**
+ * Create a new AND filter group
+ */
+export declare function createAndFilter(filters?: Filter[]): GroupFilter;
+/**
+ * Create a new OR filter group
+ */
+export declare function createOrFilter(filters?: Filter[]): GroupFilter;
+/**
+ * Clean up filters - backward compatible (returns filters unchanged)
+ * @deprecated This function is no longer used as we now support filtering on any schema field
+ */
+export declare function cleanupFilters(filters: Filter[], _query?: CubeQuery): Filter[];
+/**
+ * Transform filters from new GroupFilter format to legacy server format
+ * Server expects { and: [...] } and { or: [...] } instead of { type: 'and', filters: [...] }
+ */
+export declare function transformFiltersForServer(filters: Filter[]): any[];
+/**
+ * Transform filters from server/API format to UI format
+ * Converts {and: [...]} and {or: [...]} to {type: 'and', filters: [...]} format
+ */
+export declare function transformFiltersFromServer(filters: any[]): Filter[];
+/**
+ * Check if query has any content (measures, dimensions, or timeDimensions)
+ */
+export declare function hasQueryContent(query: CubeQuery): boolean;
+/**
+ * Clean a query and transform filters for server compatibility
+ * This version transforms GroupFilter to legacy and/or format
+ */
+export declare function cleanQueryForServer(query: CubeQuery): CubeQuery;
+/**
+ * Transform a Cube.js query from external format to UI internal format
+ * This handles format differences between server/API queries and QueryBuilder state
+ */
+export declare function transformQueryForUI(query: any): CubeQuery;
+/**
+ * Get cube name from field name (e.g., "Employees.count" -> "Employees")
+ */
+export declare function getCubeNameFromField(fieldName: string): string;
+/**
+ * Get field type from schema
+ */
+export declare function getFieldType(fieldName: string, schema: MetaResponse): string;
+/**
+ * Get field title from schema metadata, falling back to field name
+ */
+export declare function getFieldTitle(fieldName: string, schema: MetaResponse | null): string;
+/**
+ * Get available operators for a field type
+ */
+export declare function getAvailableOperators(fieldType: string): Array<{
+    operator: string;
+    label: string;
+}>;
+/**
+ * Get ALL filterable fields from schema
+ */
+export declare function getAllFilterableFields(schema: MetaResponse): MetaField[];
+/**
+ * Convert DateRangeType to Cube.js compatible date range format
+ */
+export declare function convertDateRangeTypeToValue(rangeType: string, number?: number): string;
+/**
+ * Check if a date range type requires a number input
+ */
+export declare function requiresNumberInput(rangeType: string): boolean;
+/**
+ * Format date for Cube.js (YYYY-MM-DD)
+ */
+export declare function formatDateForCube(date: Date): string;