drizzle-cube 0.2.28 → 0.2.29

package/dist/client/utils/funnelExecution.d.ts

@@ -0,0 +1,111 @@
+import { CubeQuery } from '../types';
+import { FunnelBindingKey, FunnelConfig, FunnelStep, FunnelStepResult, FunnelExecutionResult, FunnelChartData } from '../types/funnel';
+/**
+ * Default maximum number of binding key values to pass between funnel steps.
+ * Limits the size of the IN clause to prevent performance issues.
+ */
+export declare const DEFAULT_BINDING_KEY_LIMIT = 500;
+/**
+ * Extract the binding key field name for a specific query/cube.
+ *
+ * For simple binding keys (string), returns the dimension directly.
+ * For cross-cube mappings, finds the mapping for the cube used in the query.
+ *
+ * @param bindingKey - The funnel binding key configuration
+ * @param query - The cube query (used to determine which cube is being queried)
+ * @returns The binding key field name (e.g., "Users.userId")
+ */
+export declare function getBindingKeyField(bindingKey: FunnelBindingKey, query: CubeQuery): string;
+/**
+ * Extract the cube name from a query by looking at measures/dimensions
+ */
+export declare function getCubeNameFromQuery(query: CubeQuery): string | null;
+/**
+ * Result from extracting binding key values
+ */
+export interface ExtractedBindingKeyValues {
+    /** Binding key values (limited to max if specified) */
+    values: (string | number)[];
+    /** Total count of unique values before limiting */
+    totalCount: number;
+    /** Whether values were truncated due to limit */
+    wasTruncated: boolean;
+}
+/**
+ * Extract unique values for the binding key from query result data
+ *
+ * @param data - Raw data from query result
+ * @param bindingKeyField - The field name to extract values from
+ * @param limit - Maximum number of values to return (default: DEFAULT_BINDING_KEY_LIMIT)
+ * @returns Object with values array, total count, and truncation flag
+ */
+export declare function extractBindingKeyValues(data: unknown[], bindingKeyField: string, limit?: number): ExtractedBindingKeyValues;
+/**
+ * Build a step query with binding key filter applied.
+ *
+ * For the first step (no previous values), returns the original query
+ * with the binding key dimension ensured.
+ *
+ * For subsequent steps, adds an IN filter for the previous step's
+ * binding key values.
+ *
+ * @param step - The funnel step configuration
+ * @param bindingKey - The funnel binding key configuration
+ * @param previousBindingKeyValues - Binding key values from previous step (null for first step)
+ * @returns Modified CubeQuery with binding key filter
+ */
+export declare function buildStepQuery(step: FunnelStep, bindingKey: FunnelBindingKey, previousBindingKeyValues: (string | number)[] | null): CubeQuery;
+/**
+ * Calculate conversion metrics for a step
+ */
+export declare function calculateStepMetrics(currentCount: number, previousCount: number | null, firstStepCount: number): {
+    conversionRate: number | null;
+    cumulativeConversionRate: number;
+};
+/**
+ * Build a funnel step result from query execution
+ */
+export declare function buildStepResult(step: FunnelStep, stepIndex: number, data: unknown[], bindingKeyField: string, countUnique: boolean, previousCount: number | null, firstStepCount: number, executionTime: number, error?: Error | null, bindingKeyLimit?: number): FunnelStepResult;
+/**
+ * Convert step results to chart-ready data format
+ */
+export declare function buildFunnelChartData(stepResults: FunnelStepResult[]): FunnelChartData[];
+/**
+ * Build the complete funnel execution result
+ */
+export declare function buildFunnelResult(config: FunnelConfig, stepResults: FunnelStepResult[], status: FunnelExecutionResult['status'], error?: Error | null, currentStepIndex?: number | null): FunnelExecutionResult;
+/**
+ * Create an empty/initial funnel result
+ */
+export declare function createEmptyFunnelResult(config: FunnelConfig): FunnelExecutionResult;
+/**
+ * Build a FunnelConfig from multi-query config state.
+ * Used to convert AnalysisBuilder state to funnel configuration.
+ *
+ * @param queries - Array of CubeQuery objects (one per step)
+ * @param bindingKey - The binding key configuration
+ * @param stepLabels - Optional labels for each step
+ * @param stepTimeToConvert - Optional time window for each step
+ * @returns FunnelConfig ready for execution
+ */
+export declare function buildFunnelConfigFromQueries(queries: CubeQuery[], bindingKey: FunnelBindingKey, stepLabels?: string[], stepTimeToConvert?: (string | null)[]): FunnelConfig;
+/**
+ * Check if funnel execution should stop early
+ * (e.g., when no binding key values remain)
+ */
+export declare function shouldStopFunnelExecution(stepResult: FunnelStepResult): boolean;
+/**
+ * Metadata fields injected into funnel result data
+ * (for compatibility with existing chart/table components)
+ */
+export interface FunnelMetadata {
+    __stepIndex: number;
+    __stepName: string;
+    __stepId: string;
+    __conversionRate: number | null;
+    __cumulativeRate: number;
+}
+/**
+ * Check if data contains funnel metadata
+ */
+export declare function isFunnelData(data: unknown[]): boolean;

package/dist/client/utils/funnelValidation.d.ts

@@ -0,0 +1,46 @@
+import { CubeQuery, CubeMeta } from '../types';
+import { FunnelBindingKey, FunnelConfig, FunnelStep, FunnelValidationError, FunnelValidationResult } from '../types/funnel';
+/**
+ * Validate that a binding key dimension exists in the given cubes
+ */
+export declare function validateBindingKeyExists(bindingKey: FunnelBindingKey, meta: CubeMeta | null): FunnelValidationError[];
+/**
+ * Validate that each step has a valid query
+ */
+export declare function validateStepQueries(steps: FunnelStep[]): FunnelValidationError[];
+/**
+ * Check if binding key can be resolved for a given query
+ */
+export declare function canResolveBindingKey(bindingKey: FunnelBindingKey, query: CubeQuery): boolean;
+/**
+ * Validate binding key for all funnel steps
+ */
+export declare function validateBindingKeyForSteps(bindingKey: FunnelBindingKey, steps: FunnelStep[]): FunnelValidationError[];
+/**
+ * Validate time window format (ISO 8601 duration)
+ */
+export declare function validateTimeWindow(duration: string | undefined): FunnelValidationError | null;
+/**
+ * Validate complete funnel configuration
+ */
+export declare function validateFunnelConfig(config: FunnelConfig, meta: CubeMeta | null): FunnelValidationResult;
+/**
+ * Quick check if minimum funnel requirements are met
+ */
+export declare function isMinimumFunnelConfigValid(bindingKey: FunnelBindingKey | null, queryCount: number): {
+    isValid: boolean;
+    message?: string;
+};
+/**
+ * Get available dimensions that can serve as binding keys
+ * These should be dimensions that identify entities (e.g., user IDs, order IDs)
+ */
+export declare function getAvailableBindingKeyDimensions(meta: CubeMeta | null): Array<{
+    cube: string;
+    dimension: string;
+    label: string;
+}>;
+/**
+ * Get the display label for a binding key
+ */
+export declare function getBindingKeyLabel(bindingKey: FunnelBindingKey | null): string;

package/dist/client/utils/multiQueryValidation.d.ts

@@ -1,4 +1,4 @@
-import { CubeQuery } from '../types';
+import { CubeQuery, QueryMergeStrategy } from '../types';
 type TimeDimension = NonNullable<CubeQuery['timeDimensions']>[number];
 /**
  * Validation error for multi-query configuration
@@ -55,9 +55,9 @@ export declare function detectAsymmetricDateRanges(queries: CubeQuery[]): MultiQ
 /**
  * Validate a multi-query configuration
  * For 'merge' strategy: strict validation (errors block execution)
- * For 'concat' strategy: only warnings
+ * For 'concat' and 'funnel' strategies: only warnings
  */
-export declare function validateMultiQueryConfig(queries: CubeQuery[], mergeStrategy: 'concat' | 'merge', mergeKeys?: string[]): MultiQueryValidationResult;
+export declare function validateMultiQueryConfig(queries: CubeQuery[], mergeStrategy: QueryMergeStrategy, mergeKeys?: string[]): MultiQueryValidationResult;
 /**
  * Check if a multi-query configuration is valid for execution
  */