drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/types/analysis.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Query Analysis Types
+ * Provides transparency into query planning decisions for debugging
+ */
+/**
+ * Reason why a cube was selected as primary (FROM table)
+ */
+export type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
+/**
+ * Candidate cube considered for primary selection
+ */
+export interface PrimaryCubeCandidate {
+    /** Cube name */
+    cubeName: string;
+    /** Number of dimensions from this cube in the query */
+    dimensionCount: number;
+    /** Number of join definitions on this cube */
+    joinCount: number;
+    /** Whether this cube can reach all other required cubes */
+    canReachAll: boolean;
+}
+/**
+ * Primary cube selection analysis
+ */
+export interface PrimaryCubeAnalysis {
+    /** Name of the selected primary cube */
+    selectedCube: string;
+    /** Reason for selection */
+    reason: PrimaryCubeSelectionReason;
+    /** Human-readable explanation */
+    explanation: string;
+    /** Other candidates that were considered */
+    candidates?: PrimaryCubeCandidate[];
+}
+/**
+ * Single step in a join path
+ */
+export interface JoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** Relationship type used (effective, after reversal if applicable) */
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /** SQL join type that will be used */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /** Join condition columns */
+    joinColumns: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    /** Junction table info for belongsToMany */
+    junctionTable?: {
+        tableName: string;
+        sourceColumns: string[];
+        targetColumns: string[];
+    };
+    /** True when this step was discovered via a reversed edge */
+    reversed?: boolean;
+}
+/**
+ * Complete join path from primary to target cube
+ */
+export interface JoinPathAnalysis {
+    /** Target cube name */
+    targetCube: string;
+    /** Whether a path was found */
+    pathFound: boolean;
+    /** The join steps (if found) */
+    path?: JoinPathStep[];
+    /** Total path length */
+    pathLength?: number;
+    /** Error message if path not found */
+    error?: string;
+    /** Cubes that were visited during BFS search */
+    visitedCubes?: string[];
+    /** Path selection decision and scoring details (when preferred routing is used) */
+    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[];
+        }>;
+    };
+}
+/**
+ * Pre-aggregation CTE analysis
+ */
+/**
+ * Reason why a cube requires a CTE
+ */
+export type CTEReason = 'hasMany' | 'fanOutPrevention';
+export interface PreAggregationAnalysis {
+    /** Cube being pre-aggregated */
+    cubeName: string;
+    /** CTE alias in the query */
+    cteAlias: string;
+    /** Why this cube needs a CTE (human-readable explanation) */
+    reason: string;
+    /** Typed reason for programmatic use */
+    reasonType?: CTEReason;
+    /** Measures included in CTE (aggregate measures + window base measures) */
+    measures: string[];
+    /** Join keys used */
+    joinKeys: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    /**
+     * Type of CTE:
+     * - 'aggregate': Standard CTE with GROUP BY (count, sum, avg, etc.)
+     *
+     * Note: Window function CTEs are no longer used. Post-aggregation window
+     * functions are applied in the outer query after data is aggregated.
+     */
+    cteType?: 'aggregate';
+}
+/**
+ * Query structure summary
+ */
+export interface QuerySummary {
+    /** Query type: 'single_cube', 'multi_cube_join', or 'multi_cube_cte' */
+    queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    /** Strategy selected for multiplied-measure handling / multi-fact merge */
+    measureStrategy?: 'simple' | 'keysDeduplication' | 'ctePreAggregateFallback' | 'multiFactMerge';
+    /** Total number of joins */
+    joinCount: number;
+    /** Total number of CTEs */
+    cteCount: number;
+    /** Has hasMany relationships requiring aggregation */
+    hasPreAggregation: boolean;
+    /**
+     * Whether query contains post-aggregation window function measures.
+     * These window functions (lag, lead, rank, etc.) operate on aggregated
+     * data and are applied in the outer query after CTEs.
+     */
+    hasWindowFunctions?: boolean;
+}
+/**
+ * Structured planner trace for explain/dry-run UIs.
+ * Captures key decisions made during logical planning.
+ */
+export interface PlanningTraceStep {
+    /** Pipeline phase name */
+    phase: 'cube_usage' | 'primary_cube_selection' | 'join_planning' | 'cte_planning' | 'measure_strategy' | 'warnings';
+    /** Short summary of what was decided */
+    decision: string;
+    /** Optional machine-readable details */
+    details?: Record<string, unknown>;
+}
+export interface PlanningTrace {
+    /** Ordered decision trace */
+    steps: PlanningTraceStep[];
+}
+/**
+ * Complete query analysis result
+ */
+export interface QueryAnalysis {
+    /** Timestamp of analysis */
+    timestamp: string;
+    /** Number of cubes involved */
+    cubeCount: number;
+    /** List of all cubes used */
+    cubesInvolved: string[];
+    /** Primary cube selection details */
+    primaryCube: PrimaryCubeAnalysis;
+    /** Join path analysis for each joined cube */
+    joinPaths: JoinPathAnalysis[];
+    /** Pre-aggregation CTE details */
+    preAggregations: PreAggregationAnalysis[];
+    /** Overall query structure summary */
+    querySummary: QuerySummary;
+    /** Warnings or potential issues */
+    warnings?: string[];
+    /** Structured decision trace for debugging and dry-run UIs */
+    planningTrace?: PlanningTrace;
+}

package/dist/server/server/types/cache.d.ts

@@ -0,0 +1,132 @@
+import { SecurityContext } from './core';
+/**
+ * Return type for cache get operations
+ * Includes value and optional metadata for TTL tracking
+ */
+export interface CacheGetResult<T> {
+    value: T;
+    metadata?: CacheEntryMetadata;
+}
+/**
+ * Metadata about a cached entry
+ * Used to provide cache information in query responses
+ */
+export interface CacheEntryMetadata {
+    /** Unix timestamp (ms) when the entry was cached */
+    cachedAt: number;
+    /** Original TTL in milliseconds */
+    ttlMs: number;
+    /** Remaining TTL in milliseconds */
+    ttlRemainingMs: number;
+}
+/**
+ * Cache provider interface that users implement for their preferred backend
+ * All methods use async/Promise to support network-based caches (Redis, etc.)
+ */
+export interface CacheProvider {
+    /**
+     * Get a cached value by key
+     * @returns The cached value with metadata, or null/undefined if not found or expired
+     */
+    get<T = unknown>(key: string): Promise<CacheGetResult<T> | null | undefined>;
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache (must be JSON-serializable)
+     * @param ttlMs - Time-to-live in milliseconds (optional, uses default if not provided)
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a specific key from the cache
+     * @returns true if key existed and was deleted, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete all keys matching a pattern (for cache invalidation)
+     * Pattern uses glob-style matching: 'prefix:*' matches all keys starting with 'prefix:'
+     * @returns Number of keys deleted
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Optional: Called when the cache provider is no longer needed
+     * Use for cleanup (e.g., closing Redis connections)
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Cache event for monitoring and debugging
+ */
+export interface CacheEvent {
+    /** Type of cache event */
+    type: 'hit' | 'miss' | 'set' | 'error';
+    /** Cache key involved */
+    key: string;
+    /** Duration of the cache operation in milliseconds */
+    durationMs: number;
+}
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    /**
+     * Cache provider implementation
+     * Required if caching is enabled
+     */
+    provider: CacheProvider;
+    /**
+     * Default TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Prefix for all cache keys
+     * Useful for multi-environment setups (e.g., 'prod:', 'dev:')
+     * @default 'drizzle-cube:'
+     */
+    keyPrefix?: string;
+    /**
+     * Enable/disable caching globally
+     * Allows disabling without removing configuration
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to include security context in cache key
+     * CRITICAL for multi-tenant applications - should almost always be true
+     * @default true
+     */
+    includeSecurityContext?: boolean;
+    /**
+     * Custom function to extract cacheable parts of security context
+     * Use when security context contains non-serializable values
+     * @default Uses JSON.stringify on entire security context
+     */
+    securityContextSerializer?: (ctx: SecurityContext) => string;
+    /**
+     * Callback for cache errors (get/set failures)
+     * Cache errors are non-fatal by default - queries still execute
+     */
+    onError?: (error: Error, operation: 'get' | 'set' | 'delete') => void;
+    /**
+     * Callback for cache events (hits, misses, sets)
+     * Useful for monitoring and debugging
+     */
+    onCacheEvent?: (event: CacheEvent) => void;
+}
+/**
+ * Cache metadata included in QueryResult when served from cache
+ */
+export interface QueryCacheMetadata {
+    /** Always true when this object is present */
+    hit: true;
+    /** ISO timestamp when the result was cached */
+    cachedAt: string;
+    /** Original TTL in milliseconds */
+    ttlMs: number;
+    /** Remaining TTL in milliseconds */
+    ttlRemainingMs: number;
+}

package/dist/server/server/types/core.d.ts

@@ -0,0 +1,164 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { MySql2Database } from 'drizzle-orm/mysql2';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+/**
+ * Security context passed to cube SQL functions
+ * Contains user/tenant-specific data for filtering
+ */
+export interface SecurityContext {
+    [key: string]: unknown;
+}
+/**
+ * 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;
+}
+/**
+ * Query execution result
+ */
+export interface QueryResult {
+    data: Record<string, unknown>[];
+    annotation: {
+        measures: Record<string, MeasureAnnotation>;
+        dimensions: Record<string, DimensionAnnotation>;
+        segments: Record<string, unknown>;
+        timeDimensions: Record<string, TimeDimensionAnnotation>;
+        /** Period comparison metadata (present when compareDateRange is used) */
+        periods?: PeriodComparisonMetadata;
+    };
+    /** Cache metadata - indicates whether result was served from cache */
+    cache?: {
+        /** True if result was served from cache, false if freshly computed */
+        hit: boolean;
+        /** ISO timestamp when the result was cached (only present on cache hit) */
+        cachedAt?: string;
+        /** Original TTL in milliseconds (only present on cache hit) */
+        ttlMs?: number;
+        /** Remaining TTL in milliseconds (only present on cache hit) */
+        ttlRemainingMs?: number;
+    };
+    /** Warnings about potential query issues (e.g., fan-out without dimensions) */
+    warnings?: QueryWarning[];
+}
+/**
+ * Period comparison metadata for compareDateRange queries
+ * Provides information about the periods being compared
+ */
+export interface PeriodComparisonMetadata {
+    /** The date ranges being compared */
+    ranges: [string, string][];
+    /** Human-readable labels for each period */
+    labels: string[];
+    /** The time dimension used for comparison */
+    timeDimension: string;
+    /** Granularity used for the comparison */
+    granularity?: TimeGranularity;
+}
+/**
+ * SQL generation result
+ */
+export interface SqlResult {
+    sql: string;
+    params?: unknown[];
+}
+/**
+ * Options for query execution
+ */
+export interface ExecutionOptions {
+    /** Skip the cache lookup (but still cache the result for future requests) */
+    skipCache?: boolean;
+}
+/**
+ * Core database interface that supports all Drizzle instances
+ * Uses flexible typing for maximum compatibility across different database drivers
+ */
+export interface DrizzleDatabase {
+    select: (fields?: any) => any;
+    insert: (table: any) => any;
+    update: (table: any) => any;
+    delete: (table: any) => any;
+    execute?: (query: SQL) => Promise<unknown[]>;
+    run?: (query: SQL) => unknown;
+    all?: (query: SQL) => unknown[];
+    get?: (query: SQL) => unknown;
+    $with: (alias: string) => {
+        as: (query: any) => any;
+    };
+    with: (...args: any[]) => any;
+    schema?: unknown;
+    transaction?: <T>(fn: (tx: any) => Promise<T>, ...args: any[]) => Promise<T>;
+}
+/**
+ * Transaction-scoped database instance passed to RLS setup.
+ * Structurally identical to DrizzleDatabase — the alias communicates
+ * that the value lives inside a transaction, not the root connection.
+ */
+export type DrizzleTransaction = DrizzleDatabase;
+/**
+ * Row-Level Security setup function.
+ * Called inside a transaction before query execution to configure
+ * database-level RLS (e.g., setting JWT claims and switching roles in Postgres).
+ *
+ * @param tx - The transaction-scoped Drizzle database instance
+ * @param securityContext - The security context extracted from the request
+ */
+export type RLSSetupFn = (tx: DrizzleTransaction, securityContext: SecurityContext) => Promise<void>;
+/**
+ * Type helpers for specific database types
+ */
+export type PostgresDatabase = PostgresJsDatabase<any>;
+export type MySQLDatabase = MySql2Database<any>;
+export type SQLiteDatabase = BetterSQLite3Database<any>;
+/**
+ * Drizzle column reference type
+ * Use native Drizzle AnyColumn type for better type safety
+ */
+export type DrizzleColumn = AnyColumn;
+/**
+ * Annotation interfaces for UI metadata
+ */
+export interface MeasureAnnotation {
+    title: string;
+    shortTitle: string;
+    type: MeasureType;
+    format?: MeasureFormat;
+}
+export interface DimensionAnnotation {
+    title: string;
+    shortTitle: string;
+    type: string;
+    format?: DimensionFormat;
+}
+export interface TimeDimensionAnnotation {
+    title: string;
+    shortTitle: string;
+    type: string;
+    granularity?: TimeGranularity;
+}
+/**
+ * Type enums and constants
+ */
+export type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number' | 'calculated' | 'stddev' | 'stddevSamp' | 'variance' | 'varianceSamp' | 'percentile' | 'median' | 'p95' | 'p99' | 'lag' | 'lead' | 'rank' | 'denseRank' | 'rowNumber' | 'ntile' | 'firstValue' | 'lastValue' | 'movingAvg' | 'movingSum';
+export type MeasureFormat = 'currency' | 'percent' | 'number' | 'integer';
+export type DimensionFormat = 'currency' | 'percent' | 'number' | 'date' | 'datetime' | 'id' | 'link';
+export type DimensionType = 'string' | 'number' | 'time' | 'boolean';
+export type JoinType = 'left' | 'right' | 'inner' | 'full';
+export type TimeGranularity = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';