drizzle-cube 0.5.6 → 0.5.8

package/dist/server/server/builders/measure-builder.d.ts

@@ -0,0 +1,142 @@
+import { SQL } from 'drizzle-orm';
+import { Cube, QueryContext, PhysicalQueryPlan } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { ResolvedMeasures } from '../template-substitution';
+export declare class MeasureBuilder {
+    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 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
+     */
+    buildHavingMeasureExpression(cubeName: string, fieldKey: string, measure: any, context: QueryContext, queryPlan?: PhysicalQueryPlan): SQL;
+    /**
+     * 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)
+     */
+    buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
+    /**
+     * List of measure types that are window functions
+     * Window functions require special handling in CTEs:
+     * - No GROUP BY in the CTE
+     * - No re-aggregation in outer query
+     * - Return individual rows, not grouped results
+     */
+    static WINDOW_FUNCTION_TYPES: readonly ["lag", "lead", "rank", "denseRank", "rowNumber", "ntile", "firstValue", "lastValue", "movingAvg", "movingSum"];
+    /**
+     * Check if a measure type is a window function
+     * @param measureType - The measure type string
+     * @returns true if this is a window function type
+     */
+    static isWindowFunction(measureType: string): boolean;
+    /**
+     * Categorize measures into window functions and regular aggregates
+     * Used by query planner to create separate CTEs for each category
+     *
+     * @param measureNames - Array of measure names (e.g., ["Productivity.rank", "Productivity.totalLines"])
+     * @param cubeMap - Map of cubes to look up measure definitions
+     * @returns Object with windowMeasures and aggregateMeasures arrays
+     */
+    static categorizeMeasures(measureNames: string[], cubeMap: Map<string, Cube>): {
+        windowMeasures: string[];
+        aggregateMeasures: string[];
+    };
+    /**
+     * Check if a query contains any window function measures
+     * @param measureNames - Array of measure names
+     * @param cubeMap - Map of cubes
+     * @returns true if any measure is a window function
+     */
+    static hasWindowFunctions(measureNames: string[], cubeMap: Map<string, Cube>): boolean;
+    /**
+     * Check if a measure is a post-aggregation window function.
+     * Post-aggregation windows have a `measure` reference in their windowConfig,
+     * indicating they should operate on aggregated data rather than raw rows.
+     *
+     * @param measure - The measure definition
+     * @returns true if this is a post-aggregation window function
+     */
+    static isPostAggregationWindow(measure: any): boolean;
+    /**
+     * Get the base measure reference for a post-aggregation window function.
+     * Resolves simple names (e.g., 'totalRevenue') to fully qualified names ('Sales.totalRevenue').
+     *
+     * @param measure - The measure definition
+     * @param cubeName - The name of the cube containing this measure
+     * @returns Fully qualified base measure name, or null if not a post-agg window
+     */
+    static getWindowBaseMeasure(measure: any, cubeName: string): string | null;
+    /**
+     * Get the default operation for a window function type.
+     * - lag/lead default to 'difference' (compare current vs previous/next)
+     * - rank/rowNumber/ntile/firstValue/lastValue default to 'raw'
+     * - movingAvg/movingSum default to 'raw'
+     *
+     * @param windowType - The window function type
+     * @returns Default operation for the window type
+     */
+    static getDefaultWindowOperation(windowType: string): 'raw' | 'difference' | 'ratio' | 'percentChange';
+    /**
+     * Categorize measures for post-aggregation window function handling.
+     * Separates measures into:
+     * - aggregateMeasures: Regular aggregates (count, sum, avg, etc.)
+     * - postAggWindowMeasures: Window functions that reference a base measure
+     * - requiredBaseMeasures: Base measures needed by window functions (auto-added to query)
+     *
+     * @param measureNames - Array of measure names from the query
+     * @param cubeMap - Map of cubes to look up measure definitions
+     * @returns Categorized measures with base measure dependencies
+     */
+    static categorizeForPostAggregation(measureNames: string[], cubeMap: Map<string, Cube>): {
+        aggregateMeasures: string[];
+        postAggWindowMeasures: string[];
+        requiredBaseMeasures: Set<string>;
+    };
+    /**
+     * Check if any measures in the query are post-aggregation window functions.
+     *
+     * @param measureNames - Array of measure names
+     * @param cubeMap - Map of cubes
+     * @returns true if any measure is a post-aggregation window function
+     */
+    static hasPostAggregationWindows(measureNames: string[], cubeMap: Map<string, Cube>): boolean;
+}

package/dist/server/server/builders/retention-query-builder.d.ts

@@ -0,0 +1,100 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { RetentionQueryConfig, RetentionResultRow } from '../types/retention';
+import { Cube, QueryContext, SemanticQuery } from '../types';
+export declare class RetentionQueryBuilder {
+    private databaseAdapter;
+    private filterBuilder;
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains retention configuration
+     */
+    hasRetention(query: SemanticQuery): boolean;
+    /**
+     * Validate retention configuration against registered cubes
+     */
+    validateConfig(config: RetentionQueryConfig, cubes: Map<string, Cube>): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Build the retention SQL query using CTEs
+     *
+     * CTE Structure (Simplified Mixpanel-style):
+     * 1. cohort_base - Users entering the cohort (first event in date range)
+     *    - When breakdown is specified, includes breakdown_value
+     * 2. activity_periods - All activity with period_number relative to cohort entry
+     * 3. cohort_sizes - Aggregate cohort sizes (per breakdown value if applicable)
+     * 4. retention_counts - Retained users per period (and breakdown value)
+     * 5. Final SELECT - Join with retention rate calculation
+     */
+    buildRetentionQuery(config: RetentionQueryConfig, cubes: Map<string, Cube>, context: QueryContext): any;
+    /**
+     * Transform raw SQL results to RetentionResultRow[]
+     */
+    transformResult(rawResult: unknown[], config: RetentionQueryConfig): RetentionResultRow[];
+    /**
+     * Resolve retention configuration with SQL expressions
+     * Same cube/dimension used for both cohort entry and activity detection
+     */
+    private resolveConfig;
+    /**
+     * Resolve binding key expression for a cube
+     */
+    private resolveBindingKey;
+    /**
+     * Build filter conditions from config filters
+     */
+    private buildFilterConditions;
+    /**
+     * Build a single filter condition
+     */
+    private buildSingleFilterCondition;
+    /**
+     * Build cohort_base CTE
+     * Groups users by their first activity (cohort entry) within the date range.
+     * When breakdowns are specified, includes breakdown values for each dimension.
+     */
+    private buildCohortBaseCTE;
+    /**
+     * Build date range condition for WHERE clause
+     * Filters records to those within the specified date range
+     */
+    private buildDateRangeCondition;
+    /**
+     * Build date range condition for HAVING clause
+     * Used to filter aggregated cohort_period values
+     */
+    private buildDateRangeHavingCondition;
+    /**
+     * Build activity_periods CTE
+     * Joins activity events to cohort_base and calculates period_number.
+     * Includes breakdown values from cohort_base when breakdowns are specified.
+     */
+    private buildActivityPeriodsCTE;
+    /**
+     * Build cohort_sizes CTE
+     * Aggregates the size of the cohort (or per breakdown combination if specified).
+     */
+    private buildCohortSizesCTE;
+    /**
+     * Build retention_counts CTE
+     * Aggregates retained users per period (and breakdown combination if specified).
+     */
+    private buildRetentionCountsCTE;
+    /**
+     * Build rolling retention counts query
+     * For rolling retention, a user is retained in period N if they were active
+     * in period N or any later period
+     */
+    private buildRollingRetentionCountsQuery;
+    /**
+     * Build period number expression using database-specific DATE_DIFF
+     */
+    private buildPeriodNumberExpression;
+    /**
+     * Extract dimension name from a dimension reference
+     * Handles both 'CubeName.dimName' and just 'dimName' formats
+     */
+    private extractDimensionName;
+}

package/dist/server/server/cache-providers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache providers for Drizzle Cube
+ */
+export { MemoryCacheProvider } from './memory';
+export type { MemoryCacheProviderOptions } from './memory';

package/dist/server/server/cache-providers/memory.d.ts

@@ -0,0 +1,105 @@
+import { CacheProvider, CacheGetResult } from '../types';
+/**
+ * Options for MemoryCacheProvider
+ */
+export interface MemoryCacheProviderOptions {
+    /**
+     * Default TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Maximum number of entries in the cache
+     * When exceeded, oldest entries are evicted (LRU)
+     * @default undefined (unlimited)
+     */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds to run automatic cleanup
+     * Set to 0 to disable automatic cleanup
+     * @default 60000 (1 minute)
+     */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Simple in-memory cache provider implementing the CacheProvider interface
+ *
+ * Features:
+ * - TTL support with automatic expiration on read
+ * - Optional automatic cleanup of expired entries
+ * - Optional max entries limit with LRU eviction
+ * - Full metadata support for TTL tracking
+ *
+ * Limitations:
+ * - Not shared across processes/instances
+ * - Data lost on process restart
+ * - Not suitable for distributed deployments
+ */
+export declare class MemoryCacheProvider implements CacheProvider {
+    private cache;
+    private defaultTtlMs;
+    private maxEntries?;
+    private cleanupIntervalId?;
+    private accessOrder;
+    constructor(options?: MemoryCacheProviderOptions);
+    /**
+     * Get a cached value by key
+     * Returns null if not found or expired
+     * Automatically removes expired entries on access
+     */
+    get<T>(key: string): Promise<CacheGetResult<T> | null>;
+    /**
+     * Set a value in the cache
+     * Respects maxEntries limit with LRU eviction
+     */
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a specific key from the cache
+     * Returns true if key existed and was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete all keys matching a pattern
+     * Supports glob-style patterns with trailing '*'
+     * Returns number of keys deleted
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Check if a key exists in the cache
+     * Returns false for expired entries
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Stop automatic cleanup and clear the cache
+     * Call this when the cache provider is no longer needed
+     */
+    close(): Promise<void>;
+    /**
+     * Remove all expired entries from the cache
+     * Called automatically by cleanup interval
+     * Can also be called manually
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Get current cache size (number of entries)
+     * Note: May include expired entries that haven't been cleaned up yet
+     */
+    size(): number;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    stats(): {
+        size: number;
+        maxEntries?: number;
+        defaultTtlMs: number;
+    };
+    private touchAccessOrder;
+    private removeFromAccessOrder;
+    private evictOldest;
+}

package/dist/server/server/cache-utils.d.ts

@@ -0,0 +1,65 @@
+import { SemanticQuery, SecurityContext } from './types';
+/**
+ * Configuration for cache key generation
+ */
+export interface CacheKeyConfig {
+    /** Prefix for all cache keys */
+    keyPrefix?: string;
+    /** Whether to include security context in cache key */
+    includeSecurityContext?: boolean;
+    /** Custom serializer for security context */
+    securityContextSerializer?: (ctx: SecurityContext) => string;
+}
+/**
+ * Generate a deterministic cache key from query and security context
+ *
+ * Key structure: {prefix}query:{queryHash}:ctx:{securityHash}
+ *
+ * Uses FNV-1a hash for:
+ * - Speed: ~3x faster than SHA-256
+ * - Simplicity: No dependencies required
+ * - Sufficient collision resistance for cache keys
+ *
+ * @param query - The semantic query to cache
+ * @param securityContext - Security context for tenant isolation
+ * @param config - Cache key configuration
+ * @returns Deterministic cache key string
+ */
+export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig): string;
+/**
+ * Normalize query for consistent hashing
+ * Sorts arrays and object keys to ensure same query = same hash
+ *
+ * @param query - The semantic query to normalize
+ * @returns Normalized query with sorted arrays and keys
+ */
+export declare function normalizeQuery(query: SemanticQuery): SemanticQuery;
+/**
+ * Recursively sort object keys for deterministic serialization
+ *
+ * @param obj - Object to sort
+ * @returns Object with sorted keys (recursively)
+ */
+export declare function sortObject<T>(obj: T): T;
+/**
+ * FNV-1a hash - fast, non-cryptographic hash function
+ * Returns hex string for cache key readability
+ *
+ * Properties:
+ * - O(n) time complexity
+ * - Low collision rate for similar strings
+ * - Deterministic across runs
+ *
+ * @param str - String to hash
+ * @returns 8-character hex string
+ */
+export declare function fnv1aHash(str: string): string;
+/**
+ * Generate invalidation pattern for a cube
+ * Used when cube data changes and all related cache entries need clearing
+ *
+ * @param cubeName - Name of the cube to invalidate
+ * @param keyPrefix - Cache key prefix
+ * @returns Glob pattern for cache invalidation
+ */
+export declare function getCubeInvalidationPattern(cubeName: string, keyPrefix?: string): string;

package/dist/server/server/compiler.d.ts

@@ -0,0 +1,218 @@
+import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types';
+export declare class SemanticLayerCompiler {
+    private cubes;
+    private metadataCache?;
+    private cacheConfig?;
+    private rlsSetup?;
+    private db?;
+    private schema?;
+    private engineType?;
+    constructor(options?: {
+        drizzle?: DatabaseExecutor['db'];
+        schema?: any;
+        databaseExecutor?: DatabaseExecutor;
+        engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+        /** Cache configuration for query result caching */
+        cache?: CacheConfig;
+        /**
+         * Row-Level Security setup function.
+         * When provided, every query execution opens a transaction, calls this function
+         * to configure RLS (e.g., set JWT claims and switch roles), then runs the query.
+         * Dry-run/SQL generation is NOT wrapped in a transaction.
+         */
+        rlsSetup?: RLSSetupFn;
+    });
+    /**
+     * Set or update the database connection
+     */
+    setDatabaseExecutor(executor: DatabaseExecutor): void;
+    /**
+     * Get the database engine type for SQL formatting
+     */
+    getEngineType(): 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake' | undefined;
+    /**
+     * Set Drizzle instance and schema directly
+     */
+    setDrizzle(db: DatabaseExecutor['db'], schema?: any, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): void;
+    /**
+     * Check if database executor is configured
+     */
+    hasExecutor(): boolean;
+    /**
+     * Create a fresh DatabaseExecutor from stored ingredients, or throw.
+     */
+    private createDbExecutor;
+    /**
+     * Create a query executor with optional cache integration.
+     * Each call creates a fresh DatabaseExecutor so concurrent requests
+     * never share mutable state.
+     */
+    private createQueryExecutor;
+    /**
+     * Format SQL result using current engine dialect.
+     */
+    private formatSqlResult;
+    /**
+     * Register a simplified cube with dynamic query building
+     * Validates calculated measures during registration
+     */
+    registerCube(cube: Cube): void;
+    /**
+     * Validate that all string-based cube references in joins resolve to registered cubes.
+     * Call after all cubes are registered for strict startup validation.
+     * Throws an error listing all unresolved references.
+     */
+    validateCubeReferences(): void;
+    /**
+     * Validate calculated measures in a cube
+     * Checks template syntax, dependency existence, and circular dependencies
+     */
+    private validateCalculatedMeasures;
+    /**
+     * Get a cube by name
+     */
+    getCube(name: string): Cube | undefined;
+    /**
+     * Get all registered cubes
+     */
+    getAllCubes(): Cube[];
+    /**
+     * Get all cubes as a Map for multi-cube queries
+     */
+    getAllCubesMap(): Map<string, Cube>;
+    /**
+     * Unified query execution method that handles both single and multi-cube queries
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    execute(query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Execute a multi-cube query
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    executeMultiCubeQuery(query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Execute a single cube query
+     */
+    executeQuery(cubeName: string, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * 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[];
+    /**
+     * Extract column name from Drizzle column reference
+     * Handles different column types and extracts the actual column name
+     */
+    private getColumnName;
+    /**
+     * Default time granularities for time dimensions (ordered from least to most granular)
+     * Used when dimension.granularities is not specified
+     */
+    private static readonly DEFAULT_TIME_GRANULARITIES;
+    /**
+     * Generate cube metadata for API responses from cubes
+     * Optimized version that minimizes object iterations
+     * Includes drill-down support: drillMembers on measures, granularities on time dimensions, hierarchies
+     */
+    private generateCubeMetadata;
+    /**
+     * Get SQL for a query without executing it (debugging)
+     */
+    generateSQL(cubeName: string, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a multi-cube query without executing it (debugging)
+     */
+    generateMultiCubeSQL(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Canonical dry-run SQL generation entrypoint for all query modes.
+     */
+    dryRun(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a funnel query without executing it (debugging)
+     * Returns the actual CTE-based SQL that would be executed for funnel queries
+     */
+    dryRunFunnel(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a flow query without executing it (debugging)
+     * Returns the actual CTE-based SQL that would be executed for flow queries
+     */
+    dryRunFlow(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the CTE-based SQL that would be executed for retention analysis
+     */
+    dryRunRetention(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Execute EXPLAIN on a query to get the execution plan
+     * Uses the same secure path as execute/dryRun to generate SQL,
+     * then runs database EXPLAIN on it.
+     */
+    explainQuery(query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Check if a cube exists
+     */
+    hasCube(name: string): boolean;
+    /**
+     * Unregister a cube by name.
+     * Returns true if the cube existed and was removed, false if not found.
+     */
+    unregisterCube(name: string): boolean;
+    /**
+     * Remove a cube
+     */
+    removeCube(name: string): boolean;
+    /**
+     * Clear all cubes
+     */
+    clearCubes(): void;
+    /**
+     * Invalidate the metadata cache
+     * Called whenever cubes are modified
+     */
+    private invalidateMetadataCache;
+    /**
+     * Get cube names
+     */
+    getCubeNames(): string[];
+    /**
+     * Validate a query against registered cubes
+     * Ensures all referenced cubes and fields exist
+     */
+    validateQuery(query: SemanticQuery): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Analyze query planning decisions for debugging and transparency
+     * Returns detailed metadata about how the query would be planned
+     * Used by the playground UI to help users understand query structure
+     */
+    analyzeQuery(query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
+}
+/**
+ * Validate a query against a cubes map
+ * Standalone function that can be used by both compiler and executor
+ */
+export declare function validateQueryAgainstCubes(cubes: Map<string, Cube>, query: SemanticQuery): {
+    isValid: boolean;
+    errors: string[];
+};