business-as-code/dist/queries.d.ts

Primitives for expressing business logic and processes as code

/**
 * Live Queries & Views
 *
 * Query definitions for real-time analytics against ai-database (ClickHouse-backed).
 * These are NOT batch reports - they're live, composable queries that execute
 * in real-time against a performant OLAP database.
 *
 * @packageDocumentation
 */
/**
 * Time granularity for aggregations
 */
export type Granularity = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
/**
 * Aggregation function
 */
export type AggregateFunction = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'first' | 'last' | 'median' | 'p50' | 'p90' | 'p95' | 'p99' | 'stddev' | 'variance';
/**
 * Comparison operator
 */
export type Operator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like' | 'notLike' | 'between' | 'isNull' | 'isNotNull';
/**
 * Sort direction
 */
export type SortDirection = 'asc' | 'desc';
/**
 * Dimension - categorical attribute for grouping/filtering
 */
export interface Dimension {
    name: string;
    field: string;
    type: 'string' | 'number' | 'date' | 'boolean';
    description?: string;
    granularity?: Granularity;
    format?: string;
}
/**
 * Measure - numeric value to aggregate
 */
export interface Measure {
    name: string;
    field: string;
    aggregate: AggregateFunction;
    type?: 'number' | 'currency' | 'percent';
    description?: string;
    format?: string;
    currency?: string;
}
/**
 * Calculated measure - derived from other measures
 */
export interface CalculatedMeasure {
    name: string;
    expression: string;
    measures: string[];
    type?: 'number' | 'currency' | 'percent';
    description?: string;
    format?: string;
}
/**
 * Filter condition
 */
export interface Filter {
    field: string;
    operator: Operator;
    value: unknown;
    and?: Filter[];
    or?: Filter[];
}
/**
 * Sort specification
 */
export interface Sort {
    field: string;
    direction: SortDirection;
}
/**
 * Time range filter
 */
export interface TimeRange {
    field: string;
    start?: Date | string;
    end?: Date | string;
    granularity?: Granularity;
}
/**
 * Query definition - a composable, reusable query
 */
export interface Query {
    name: string;
    description?: string;
    source: string;
    dimensions?: string[];
    measures?: string[];
    filters?: Filter[];
    timeRange?: TimeRange;
    sort?: Sort[];
    limit?: number;
    offset?: number;
    tags?: string[];
    owner?: string;
}
/**
 * Query with resolved schema
 */
export interface ResolvedQuery extends Query {
    resolvedDimensions: Dimension[];
    resolvedMeasures: (Measure | CalculatedMeasure)[];
}
/**
 * View - a saved query with optional materialization
 */
export interface View {
    name: string;
    description?: string;
    query: Query;
    materialized?: boolean;
    refreshInterval?: string;
    retention?: string;
    public?: boolean;
    owner?: string;
    tags?: string[];
}
/**
 * Dashboard - collection of related views
 */
export interface Dashboard {
    name: string;
    description?: string;
    views: View[];
    layout?: DashboardLayout;
    refreshInterval?: string;
    owner?: string;
    tags?: string[];
}
/**
 * Dashboard layout
 */
export interface DashboardLayout {
    columns: number;
    rows: number;
    items: DashboardItem[];
}
/**
 * Dashboard item position
 */
export interface DashboardItem {
    viewName: string;
    x: number;
    y: number;
    width: number;
    height: number;
    visualization?: Visualization;
}
/**
 * Visualization type
 */
export type Visualization = 'number' | 'trend' | 'table' | 'bar' | 'line' | 'area' | 'pie' | 'funnel' | 'cohort' | 'heatmap';
/**
 * Standard SaaS metric dimensions
 */
export declare const StandardDimensions: Record<string, Dimension>;
/**
 * Standard SaaS metric measures
 */
export declare const StandardMeasures: Record<string, Measure>;
/**
 * Calculated SaaS metrics
 */
export declare const CalculatedMetrics: Record<string, CalculatedMeasure>;
/**
 * Create a query
 */
export declare function query(name: string, source: string): QueryBuilder;
/**
 * Fluent query builder
 */
export declare class QueryBuilder {
    private _query;
    constructor(name: string, source: string);
    describe(description: string): this;
    dimensions(...dims: string[]): this;
    measures(...measures: string[]): this;
    filter(field: string, operator: Operator, value: unknown): this;
    where(filters: Filter[]): this;
    timeRange(field: string, start?: Date | string, end?: Date | string, granularity?: Granularity): this;
    last(duration: string, field?: string): this;
    sort(field: string, direction?: SortDirection): this;
    limit(n: number): this;
    offset(n: number): this;
    tags(...tags: string[]): this;
    owner(owner: string): this;
    build(): Query;
}
/**
 * MRR Overview query
 */
export declare const MrrOverview: Query;
/**
 * ARR by segment query
 */
export declare const ArrBySegment: Query;
/**
 * Customer cohort retention query
 */
export declare const CohortRetention: Query;
/**
 * Unit economics query
 */
export declare const UnitEconomics: Query;
/**
 * Revenue by channel query
 */
export declare const RevenueByChannel: Query;
/**
 * Growth metrics query
 */
export declare const GrowthMetrics: Query;
/**
 * Create a view from a query
 */
export declare function view(name: string, queryDef: Query): ViewBuilder;
/**
 * Fluent view builder
 */
export declare class ViewBuilder {
    private _view;
    constructor(name: string, queryDef: Query);
    describe(description: string): this;
    materialize(refreshInterval?: string, retention?: string): this;
    public(): this;
    owner(owner: string): this;
    tags(...tags: string[]): this;
    build(): View;
}
/**
 * Create a dashboard
 */
export declare function dashboard(name: string): DashboardBuilder;
/**
 * Fluent dashboard builder
 */
export declare class DashboardBuilder {
    private _dashboard;
    constructor(name: string);
    describe(description: string): this;
    add(viewDef: View, options?: {
        x?: number;
        y?: number;
        width?: number;
        height?: number;
        visualization?: Visualization;
    }): this;
    layout(columns: number, rows: number): this;
    refresh(interval: string): this;
    owner(owner: string): this;
    tags(...tags: string[]): this;
    build(): Dashboard;
}
/**
 * Executive SaaS Dashboard
 */
export declare const ExecutiveDashboard: Dashboard;
/**
 * Query result row
 */
export type QueryRow = Record<string, unknown>;
/**
 * Query result
 */
export interface QueryResult {
    query: Query;
    rows: QueryRow[];
    rowCount: number;
    executionTimeMs: number;
    cached?: boolean;
    metadata?: Record<string, unknown>;
}
/**
 * Query executor interface (implemented by ai-database)
 */
export interface QueryExecutor {
    execute(query: Query): Promise<QueryResult>;
    explain(query: Query): Promise<string>;
    validate(query: Query): Promise<{
        valid: boolean;
        errors?: string[];
    }>;
}
/**
 * Streaming query result
 */
export interface StreamingQueryResult {
    query: Query;
    stream: AsyncIterable<QueryRow>;
    cancel: () => void;
}
/**
 * Streaming query executor interface
 */
export interface StreamingQueryExecutor extends QueryExecutor {
    stream(query: Query): StreamingQueryResult;
}
//# sourceMappingURL=queries.d.ts.map