drizzle-cube 0.5.7 → 0.6.0

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

@@ -0,0 +1,145 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { FunnelQueryConfig, FunnelResultRow } from '../types/funnel';
+import { Cube, QueryContext, SemanticQuery, AnalysisConfigValidationResult } from '../types';
+export declare class FunnelQueryBuilder {
+    private databaseAdapter;
+    private filterBuilder;
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains funnel configuration
+     */
+    hasFunnel(query: SemanticQuery): boolean;
+    /**
+     * Validate funnel configuration
+     */
+    validateConfig(config: FunnelQueryConfig, cubes: Map<string, Cube>): AnalysisConfigValidationResult;
+    /** Validate the funnel binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate the funnel time dimension member. */
+    private validateTimeDimension;
+    /** Validate a single funnel step (name, cube, filters, timeToConvert). */
+    private validateStep;
+    /** Validate the member filters of a single funnel step. */
+    private validateStepFilters;
+    /**
+     * Build complete funnel query using Drizzle's query builder pattern
+     *
+     * Uses the industry-standard "sequential CTEs" pattern where each step
+     * joins to the previous step CTE. This automatically enforces funnel
+     * constraints (monotonically decreasing counts).
+     *
+     * Returns a Drizzle query builder that supports .toSQL() for dry-run
+     * and can be executed directly for results.
+     */
+    buildFunnelQuery(config: FunnelQueryConfig, cubes: Map<string, Cube>, context: QueryContext): ReturnType<typeof context.db.select>;
+    /**
+     * Transform raw SQL result to FunnelResultRow[]
+     */
+    transformResult(rawResult: Record<string, unknown>[], config: FunnelQueryConfig): FunnelResultRow[];
+    /** Attach the per-step conversion-time metrics to a funnel result row. */
+    private applyTimeMetrics;
+    /**
+     * Extract cube names referenced in step filters
+     */
+    private extractFilterCubeNames;
+    /**
+     * Resolve steps with their cube, SQL expressions, and filter conditions
+     */
+    private resolveSteps;
+    /**
+     * Resolve the cube for a step
+     */
+    private resolveCubeForStep;
+    /**
+     * Resolve binding key expression for a cube
+     */
+    private resolveBindingKey;
+    /**
+     * Resolve time dimension expression for a cube
+     */
+    private resolveTimeDimension;
+    /**
+     * Build filter conditions for a step
+     * @param step - The funnel step
+     * @param baseCube - The step's primary cube
+     * @param cubes - All cubes available for cross-cube filtering
+     * @param context - Query context with security context
+     */
+    private buildStepFilters;
+    /**
+     * Build a single filter condition
+     * @param filter - The filter to build
+     * @param baseCube - The step's primary cube
+     * @param cubes - All cubes available for cross-cube filtering
+     * @param context - Query context with security context
+     */
+    private buildFilterCondition;
+    /** Combine a logical/group filter's sub-conditions into a single SQL condition. */
+    private buildLogicalFilterCondition;
+    /** Build a simple (member) filter condition, validating values and cross-cube join paths. */
+    private buildSimpleFilterCondition;
+    /**
+     * Build CTE for a single step using Drizzle's $with() pattern
+     *
+     * For step 0 (entry point): queries raw data directly
+     * For subsequent steps: joins to the previous step CTE to enforce sequential progression
+     *
+     * This implements the industry-standard "sequential CTEs" pattern where each step
+     * only includes binding_keys that successfully completed the previous step.
+     *
+     * @param step - The resolved step configuration
+     * @param context - Query context with security context
+     * @param previousStepCTE - Reference to the previous step's CTE (undefined for step 0)
+     */
+    private buildStepCTE;
+    /**
+     * Build CTE for the first step (step 0) - entry point
+     *
+     * Queries raw data directly with security context and step filters.
+     * Gets the first occurrence per binding key.
+     */
+    private buildFirstStepCTE;
+    /**
+     * Build CTE for subsequent steps (step 1+) - joins to previous step
+     *
+     * This is the key to the sequential funnel pattern:
+     * - INNER JOINs to the previous step CTE (only includes binding_keys that completed previous step)
+     * - Applies temporal constraints (must occur after previous step)
+     * - Applies step-specific filters and time-to-convert windows
+     *
+     * This automatically ensures monotonically decreasing counts.
+     */
+    private buildSubsequentStepCTE;
+    /**
+     * Helper to add cross-cube JOINs to a step query
+     * Extracted to avoid duplication between first and subsequent step methods
+     */
+    private addCrossJoinsToQuery;
+    /**
+     * Build funnel results CTE that joins all step times for time metric calculation
+     *
+     * With the sequential CTE pattern, each step CTE already contains only the
+     * binding_keys that successfully completed that step. This CTE simply joins
+     * them together to enable time difference calculations.
+     *
+     * No CASE expressions needed - the temporal filtering is already done in each step CTE.
+     */
+    private buildFunnelResultsCTE;
+    /**
+     * Build aggregation CTE with counts and optional time metrics
+     *
+     * OPTIMIZATION: Uses single-pass aggregation over funnel_joined CTE instead of
+     * multiple scalar subqueries. This reduces table scans from 13+ to 1 for a typical
+     * 3-step funnel with time metrics.
+     *
+     * - Step counts: COUNT(*) for step_0, COUNT(step_N_time) for subsequent steps
+     * - Time metrics: Uses database-specific conditional aggregation (FILTER clause for
+     *   PostgreSQL, CASE WHEN for MySQL/SQLite)
+     * - Percentiles: Still use subqueries since PERCENTILE_CONT with FILTER is non-standard
+     *
+     * Important: All SQL fields must have explicit aliases via .as() for Drizzle
+     * to properly reference them when selecting from the CTE
+     */
+    private buildAggregationCTE;
+}

package/dist/server/server/builders/group-by-builder.d.ts

@@ -0,0 +1,38 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { Cube, SemanticQuery, QueryContext, PhysicalQueryPlan } from '../types';
+import { DateTimeBuilder } from './date-time-builder';
+export declare class GroupByBuilder {
+    private dateTimeBuilder;
+    constructor(dateTimeBuilder: DateTimeBuilder);
+    /**
+     * Check if a measure type is a window function
+     */
+    isWindowFunctionType(measureType: string): boolean;
+    /**
+     * Check if a measure type is an aggregate function (requires GROUP BY)
+     *
+     * Note: 'number' is included because users commonly define measures with raw SQL
+     * aggregations (e.g., sql`COUNT(DISTINCT ...)`) and set type: 'number' for the output.
+     * These measures still require GROUP BY when used with time dimensions.
+     */
+    isAggregateFunctionType(measureType: string): boolean;
+    /**
+     * Build GROUP BY fields from dimensions and time dimensions
+     * Works for both single and multi-cube queries
+     *
+     * NOTE: GROUP BY is only added when there are AGGREGATE measures.
+     * Window functions do not require GROUP BY and operate on individual rows.
+     */
+    buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan): (SQL | AnyColumn)[];
+    /**
+     * Determine whether the query contains at least one aggregate (or calculated,
+     * or post-aggregation window over an aggregate) measure — which forces GROUP BY.
+     */
+    private hasAggregateMeasures;
+    /** True when `measure` is a post-aggregation window over an aggregate base measure. */
+    private isWindowOverAggregate;
+    /** Resolve a single dimension into its GROUP BY expression (CTE-aware). */
+    private resolveDimensionGroupField;
+    /** Resolve a single time dimension into its GROUP BY expression (CTE-aware). */
+    private resolveTimeDimensionGroupField;
+}

package/dist/server/server/builders/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Builders Index
+ * Re-exports all query builder components for modular imports
+ */
+export { DateTimeBuilder } from './date-time-builder';
+export { FilterBuilder } from './filter-builder';
+export { GroupByBuilder } from './group-by-builder';
+export { MeasureBuilder } from './measure-builder';
+export { CTEBuilder } from './cte-builder';
+export { ComparisonQueryBuilder } from './comparison-query-builder';
+export { FunnelQueryBuilder } from './funnel-query-builder';
+export { FlowQueryBuilder } from './flow-query-builder';
+export { RetentionQueryBuilder } from './retention-query-builder';

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

@@ -0,0 +1,185 @@
+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;
+    /**
+     * First-pass classification of a user-requested measure: sorts it into the
+     * regular/calculated buckets and seeds `allMeasuresToResolve` with its
+     * (transitive) dependencies. Post-aggregation windows only contribute their
+     * base measure as a dependency.
+     */
+    private classifyRequestedMeasure;
+    /** Seed `allMeasuresToResolve` with the direct + transitive deps of a calculated measure. */
+    private collectCalculatedDependencies;
+    /** Second-pass classification of a dependency measure into the regular/calculated buckets. */
+    private classifyDependencyMeasure;
+    /**
+     * 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;
+    /**
+     * Re-aggregate a pre-aggregated CTE column based on the original measure type.
+     * For pre-aggregated values in CTEs we re-aggregate properly:
+     * - count/sum/number → SUM
+     * - avg → AVG (ideally a weighted average, but simple AVG for now)
+     * - min/max → MIN/MAX
+     * - anything else → SUM
+     */
+    private reAggregateCteColumn;
+    /**
+     * Build measure expression for HAVING clause, handling CTE references correctly
+     */
+    buildHavingMeasureExpression(cubeName: string, fieldKey: string, measure: any, context: QueryContext, queryPlan?: PhysicalQueryPlan): SQL;
+    /** Build a HAVING measure expression that references a pre-aggregation CTE column. */
+    private buildHavingCteMeasure;
+    /**
+     * 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;
+    /**
+     * Wrap a base expression in a CASE WHEN for measures carrying `filters`,
+     * producing conditional aggregation. Returns the original expression when
+     * there are no filters.
+     */
+    private applyMeasureFilters;
+    /** Apply the aggregation function implied by `measure.type` to `baseExpr`. */
+    private applyAggregation;
+    /**
+     * Run a statistical-function builder, falling back to MAX(NULL) with a warning
+     * when the engine doesn't support it (shared by stddev/variance/percentile).
+     */
+    private buildStatistical;
+    /** Resolve the percentile value implied by a percentile-family measure type. */
+    private resolvePercentile;
+    /** Build a (per-row) window-function measure expression. */
+    private buildWindowMeasure;
+    /** Resolve a window function's partitionBy dimension references to SQL expressions. */
+    private resolveWindowPartitions;
+    /** Resolve a window function's orderBy dimension/measure references to SQL expressions. */
+    private resolveWindowOrder;
+    /**
+     * 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,98 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { RetentionQueryConfig, RetentionResultRow } from '../types/retention';
+import { Cube, QueryContext, SemanticQuery, AnalysisConfigValidationResult } 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>): AnalysisConfigValidationResult;
+    /** Validate the retention time dimension (used for cohort entry and activity). */
+    private validateTimeDimension;
+    /** Validate the retention binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate optional retention breakdown dimensions. */
+    private validateBreakdownDimensions;
+    /** Validate retention period bounds, granularity, and retention type. */
+    private validatePeriodsAndEnums;
+    /** Validate the (required) retention date range: presence, parseability, ordering. */
+    private validateDateRange;
+    /**
+     * 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;
+    /**
+     * 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;
+}

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,85 @@
+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 a 128-bit FNV-1a-based hash (see {@link strongHash}) for both the query
+ * and the security context. A 128-bit digest is required here for correctness,
+ * not just speed: the security-context hash provides tenant isolation, and a
+ * collision serves one tenant's cached result to another. The full input is
+ * hashed (no truncation) so large queries cannot collide on a shared prefix.
+ *
+ * @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 32-bit hash function
+ * Returns hex string for cache key readability
+ *
+ * Properties:
+ * - O(n) time complexity
+ * - Low collision rate for similar strings
+ * - Deterministic across runs
+ *
+ * Note: a 32-bit digest is too narrow to isolate tenants by itself — use
+ * {@link strongHash} for cache keys. Retained for backwards compatibility.
+ *
+ * @param str - String to hash
+ * @returns 8-character hex string
+ */
+export declare function fnv1aHash(str: string): string;
+/**
+ * 128-bit FNV-1a-based hash for cache keys.
+ *
+ * Computes four independent 32-bit FNV-1a lanes (distinct offset bases, each
+ * mixed with the byte position) and concatenates them into a 32-character hex
+ * digest. This widens the key space from 2^32 to 2^128 so security-context and
+ * query collisions are vanishingly unlikely — collisions here are not merely a
+ * cache miss, they are a cross-tenant data-disclosure risk.
+ *
+ * The entire input is hashed (no truncation), and the input length is mixed in
+ * to disambiguate shared prefixes. `Math.imul` performs a true 32-bit multiply.
+ *
+ * @param str - String to hash
+ * @returns 32-character hex string (128 bits)
+ */
+export declare function strongHash(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;