All files server/types/core.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
/**
 * Core types for Drizzle Cube semantic layer
 * Fundamental interfaces used throughout the system
 */
 
import type { SQL, AnyColumn } from 'drizzle-orm'
import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js'
import type { MySql2Database } from 'drizzle-orm/mysql2'
import type { 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
}
 
/**
 * 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
  }
}
 
/**
 * 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[]>  // PostgreSQL/MySQL async
  run?: (query: SQL) => unknown              // SQLite sync
  all?: (query: SQL) => unknown[]            // SQLite sync
  get?: (query: SQL) => unknown              // SQLite sync
  $with: (alias: string) => { as: (query: any) => any }
  with: (...args: any[]) => any
  schema?: unknown
}
 
/**
 * 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'
  // Statistical functions (Phase 1)
  | 'stddev'         // Standard deviation (population)
  | 'stddevSamp'     // Standard deviation (sample)
  | 'variance'       // Variance (population)
  | 'varianceSamp'   // Variance (sample)
  | 'percentile'     // Configurable percentile (0-100)
  | 'median'         // Shorthand for P50
  | 'p95'            // 95th percentile
  | 'p99'            // 99th percentile
  // Window functions (Phase 2)
  | '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'