drizzle-cube 0.5.8 → 0.6.1

package/dist/server/{server/agent → agent}/handler.d.ts

@@ -1,6 +1,6 @@
-import { SemanticLayerCompiler } from '../compiler';
-import { SecurityContext } from '../types';
-import { AgentConfig, AgentSSEEvent, AgentHistoryMessage } from './types';
+import { SemanticLayerCompiler } from '../compiler.js';
+import { SecurityContext } from '../types/index.js';
+import { AgentConfig, AgentSSEEvent, AgentHistoryMessage } from './types.js';
 /**
  * Handle an agent chat request, yielding SSE events as the agent works.
  *

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

@@ -0,0 +1,11 @@
+/**
+ * Agent Module - Public Exports
+ * Agentic AI notebook handler for drizzle-cube
+ */
+export { handleAgentChat } from './handler.js';
+export { getToolDefinitions, createToolExecutor } from './tools.js';
+export type { ToolExecutionResult } from './tools.js';
+export { buildAgentSystemPrompt } from './system-prompt.js';
+export { createProvider } from './providers/index.js';
+export type { LLMProvider, ProviderName } from './providers/index.js';
+export type { AgentChatRequest, AgentConfig, AgentObservabilityHooks, AgentSSEEvent, AgentHistoryMessage, AgentHistoryToolCall, PortletBlockData, MarkdownBlockData, DashboardSavedData } from './types.js';

package/dist/server/{server/agent → agent}/providers/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
 export declare class AnthropicProvider implements LLMProvider {
     private client;
     constructor(apiKey: string);

package/dist/server/{server/agent → agent}/providers/factory.d.ts

@@ -1,4 +1,4 @@
-import { LLMProvider } from './types';
+import { LLMProvider } from './types.js';
 export type ProviderName = 'anthropic' | 'openai' | 'google';
 /**
  * Create an LLM provider instance.

package/dist/server/{server/agent → agent}/providers/google.d.ts

@@ -1,4 +1,4 @@
-import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
 export declare class GoogleProvider implements LLMProvider {
     private apiKey;
     private sdk;

package/dist/server/agent/providers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LLM Provider exports
+ */
+export type { LLMProvider, ToolDefinition, InternalMessage, ContentBlock, ToolResult, NormalizedEvent } from './types.js';
+export type { ProviderName } from './factory.js';
+export { createProvider } from './factory.js';

package/dist/server/{server/agent → agent}/providers/openai.d.ts

@@ -1,4 +1,4 @@
-import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
 export declare class OpenAIProvider implements LLMProvider {
     private client;
     private apiKey;

package/dist/server/{server/agent → agent}/system-prompt.d.ts

@@ -1,4 +1,4 @@
-import { CubeMetadata } from '../types';
+import { CubeMetadata } from '../types/index.js';
 /**
  * Build the full system prompt for the agent
  */

package/dist/server/{server/agent → agent}/tools.d.ts

@@ -1,7 +1,7 @@
-import { SemanticLayerCompiler } from '../compiler';
-import { SecurityContext } from '../types';
-import { AgentSSEEvent } from './types';
-import { ToolDefinition } from './providers/types';
+import { SemanticLayerCompiler } from '../compiler.js';
+import { SecurityContext } from '../types/index.js';
+import { AgentSSEEvent } from './types.js';
+import { ToolDefinition } from './providers/types.js';
 /**
  * Result of executing a tool call
  */

package/dist/server/{server/agent → agent}/types.d.ts

@@ -1,4 +1,4 @@
-import { ChartType, ChartAxisConfig, ChartDisplayConfig, DashboardConfig } from '../../client/types';
+import { ChartType, ChartAxisConfig, ChartDisplayConfig, DashboardConfig } from '../../client/types.js';
 /**
  * A tool call from a prior conversation turn (for history replay)
  */

package/dist/server/ai/discovery-helpers.d.ts

@@ -0,0 +1,29 @@
+import { CubeMetadata } from '../types/metadata.js';
+/** A measure or dimension as carried in cube metadata. */
+type Field = CubeMetadata['measures'][number] | CubeMetadata['dimensions'][number];
+/** Scoring callbacks shared with discovery.ts (avoids a circular import). */
+export interface ScoreFns {
+    fuzzyMatchScore: (query: string, target: string) => number;
+    matchAgainstArray: (query: string, targets: string[]) => number;
+}
+/**
+ * Score a single field (measure or dimension) against a keyword.
+ * Returns the best score across name, title, description and synonyms.
+ */
+export declare function scoreField(keyword: string, field: Field, fns: ScoreFns): number;
+/**
+ * Accumulate field scores for a keyword into a running totals map.
+ * Adds to `totalScore` (returned) and records the per-field best score when the
+ * field clears the relevance threshold, mutating `scores` and `matchedOn`.
+ */
+export declare function accumulateFieldScores(keyword: string, fields: Field[], fns: ScoreFns, scores: Map<string, number>, matchedOn: {
+    hit: boolean;
+}): number;
+/** Return the top-N field names from a score map, highest score first. */
+export declare function topScoredFields(scores: Map<string, number>, limit: number): string[];
+/**
+ * Score a single field as a best-match candidate (used by findBestFieldMatch).
+ * Returns the best score across name, title and synonyms (no description match).
+ */
+export declare function scoreFieldForBestMatch(fieldName: string, field: Field, fns: ScoreFns): number;
+export {};

package/dist/server/{server/ai → ai}/discovery.d.ts

@@ -1,5 +1,5 @@
-import { CubeMetadata } from '../types/metadata';
-import { QUERY_SCHEMAS } from './schemas';
+import { CubeMetadata } from '../types/metadata.js';
+import { QUERY_SCHEMAS } from './schemas.js';
 /**
  * Discovery result for a cube
  */
@@ -47,6 +47,10 @@ export interface DiscoveryOptions {
     /** Minimum relevance score (0-1) */
     minScore?: number;
 }
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
 /**
  * Discover relevant cubes based on topic or intent
  */

package/dist/server/{server/ai → ai}/index.d.ts

@@ -2,9 +2,9 @@
  * AI-Ready Data Layer Utilities
  * Schema-aware intelligence for AI agents - no server-side LLM required
  */
-export { discoverCubes, findBestFieldMatch, type CubeDiscoveryResult, type DiscoveryOptions } from './discovery';
-export { suggestQuery, type QuerySuggestion } from './suggestion';
-export { validateQuery, type ValidationResult, type ValidationError, type ValidationWarning } from './validation';
-export { QUERY_SCHEMAS, type QuerySchemas } from './schemas';
-export { QUERY_PARAMS_SCHEMA, QUERY_LANGUAGE_REFERENCE } from './query-schema';
-export { MCP_PROMPTS, MCP_GUIDE_PROMPT, QUERY_LANGUAGE_PROMPT, QUERY_RULES_PROMPT, QUERY_BUILDING_PROMPT, DATE_FILTERING_PROMPT, DEFAULT_MCP_INSTRUCTIONS, getDefaultMCPPrompts, getDefaultMcpInstructions, type MCPPrompt } from './mcp-prompts';
+export { discoverCubes, findBestFieldMatch, type CubeDiscoveryResult, type DiscoveryOptions } from './discovery.js';
+export { suggestQuery, type QuerySuggestion } from './suggestion.js';
+export { validateQuery, type ValidationResult, type ValidationError, type ValidationWarning } from './validation.js';
+export { QUERY_SCHEMAS, type QuerySchemas } from './schemas.js';
+export { QUERY_PARAMS_SCHEMA, QUERY_LANGUAGE_REFERENCE } from './query-schema.js';
+export { MCP_PROMPTS, MCP_GUIDE_PROMPT, QUERY_LANGUAGE_PROMPT, QUERY_RULES_PROMPT, QUERY_BUILDING_PROMPT, DATE_FILTERING_PROMPT, DEFAULT_MCP_INSTRUCTIONS, getDefaultMCPPrompts, getDefaultMcpInstructions, type MCPPrompt } from './mcp-prompts.js';

package/dist/server/ai/suggestion-helpers.d.ts

@@ -0,0 +1,33 @@
+import { CubeMetadata } from '../types/metadata.js';
+/** Format a Date as a YYYY-MM-DD string (UTC). */
+export declare function formatDate(d: Date): string;
+/** Resolve a numeric "last N days/weeks/months" expression. */
+export declare function parseRelativeNExpression(n: number, lowerText: string): {
+    dateRange: [string, string];
+    granularity?: string;
+} | null;
+/** Resolve a "Q1".."Q4" quarter expression for the current year. */
+export declare function parseQuarterExpression(quarterMatch: string): {
+    dateRange: [string, string];
+    granularity?: string;
+};
+/**
+ * Match measures in the primary cube against keywords in the text.
+ * Mutates `measures`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchMeasuresInText(primaryCube: CubeMetadata, lowerText: string, measures: string[], reasoning: string[]): number;
+/** Aggregation intent shape produced by detectAggregationIntent. */
+export interface AggregationIntent {
+    type: 'sum' | 'count' | 'avg' | 'max' | 'min';
+    confidence: number;
+}
+/**
+ * Backfill measures when none matched directly, using the aggregation intent.
+ * Mutates `measures`/`reasoning`.
+ */
+export declare function applyAggregationFallback(primaryCube: CubeMetadata, aggregationIntent: AggregationIntent, measures: string[], reasoning: string[]): void;
+/**
+ * Resolve grouping dimensions from grouping keywords and explicit "by/per X" text.
+ * Mutates `dimensions`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchDimensions(relevantCubes: CubeMetadata[], groupingKeywords: string[], lowerText: string, dimensions: string[], reasoning: string[]): number;

package/dist/server/{server/ai → ai}/suggestion.d.ts

@@ -1,5 +1,5 @@
-import { CubeMetadata } from '../types/metadata';
-import { SemanticQuery } from '../types/query';
+import { CubeMetadata } from '../types/metadata.js';
+import { SemanticQuery } from '../types/query.js';
 /**
  * Suggested query result
  */
@@ -13,7 +13,4 @@ export interface QuerySuggestion {
     /** Next steps when mode != 'query' */
     nextSteps?: string[];
 }
-/**
- * Suggest a query based on natural language input
- */
 export declare function suggestQuery(metadata: CubeMetadata[], naturalLanguage: string, targetCube?: string): QuerySuggestion;

package/dist/server/ai/validation-helpers.d.ts

@@ -0,0 +1,21 @@
+import { TranslationKey } from '../../i18n/types.js';
+import { CubeMetadata } from '../types/metadata.js';
+import { SemanticQuery, Filter } from '../types/query.js';
+import { ValidationError, ValidationWarning } from './validation.js';
+/** Validate that a required event-stream field is present and (if a string) a valid dimension. */
+export declare function validateRequiredDimensionField(value: unknown, missingMessageKey: TranslationKey, validateDimension: (dimension: string, errors: ValidationError[]) => void, errors: ValidationError[]): void;
+/** Apply field-name corrections to a measures/dimensions string array. */
+export declare function applyCorrectionsToList(list: string[], corrections: Map<string, string>): string[];
+/** Build the corrected query by applying field corrections (returns undefined if none). */
+export declare function buildCorrectedQuery(query: SemanticQuery, corrections: Map<string, string>): SemanticQuery | undefined;
+/** Push performance/best-practice warnings for an oversized standard query. */
+export declare function collectPerformanceWarnings(query: SemanticQuery, warnings: ValidationWarning[]): void;
+/** Warn when a declared time dimension is not actually of time type. */
+export declare function checkTimeDimensionType(dimensionRef: string, metadata: CubeMetadata[], warnings: ValidationWarning[]): void;
+/** Validate a single member-style filter (cube + field existence). */
+export declare function validateMemberFilter(filter: Extract<Filter, {
+    member: string;
+}>, metadata: CubeMetadata[], errors: ValidationError[], corrections: Map<string, string>, findClosestField: (fieldName: string, available: string[]) => {
+    field: string;
+    distance: number;
+} | null): void;

package/dist/server/{server/ai → ai}/validation.d.ts

@@ -1,5 +1,5 @@
-import { CubeMetadata } from '../types/metadata';
-import { SemanticQuery } from '../types/query';
+import { CubeMetadata } from '../types/metadata.js';
+import { SemanticQuery } from '../types/query.js';
 /**
  * Validation result with corrections
  */
@@ -28,7 +28,4 @@ export interface ValidationWarning {
     field?: string;
     suggestion?: string;
 }
-/**
- * Validate a query with helpful corrections
- */
 export declare function validateQuery(query: SemanticQuery, metadata: CubeMetadata[]): ValidationResult;

package/dist/server/builders/analysis-utils.d.ts

@@ -0,0 +1,106 @@
+import { SQL } from 'drizzle-orm';
+import { Cube, Filter, QueryContext } from '../types/index.js';
+/**
+ * Type for CTE objects created by db.$with()
+ * These can be used with db.with(...ctes).select().from(cte)
+ */
+export type WithSubquery = ReturnType<ReturnType<any['$with']>['as']>;
+/**
+ * Combine an array of WHERE/JOIN conditions into a single SQL expression.
+ *
+ * - `[]`            → undefined (no condition)
+ * - single element  → that element verbatim
+ * - multiple        → `and(...conditions)`
+ *
+ * Mirrors the inline `conditions.length === 1 ? conditions[0] : and(...conditions) as SQL`
+ * pattern that was duplicated across the analysis builders.
+ */
+export declare function combineWhere(conditions: SQL[]): SQL | undefined;
+/** The combinator + children of a client-style group filter. */
+export interface GroupFilterParts {
+    /** True for an AND group, false for OR. */
+    isAnd: boolean;
+    filters: Filter[];
+}
+/**
+ * Normalise a client-style group filter.
+ *
+ * The analysis UIs sometimes emit groups as `{ type: 'and' | 'or', filters: [...] }`
+ * rather than the canonical `{ and: [...] }` / `{ or: [...] }` (this shape is not part
+ * of the `Filter` type; the builders accept it defensively). Returns the group's
+ * combinator + children, or `null` if `filter` isn't a client group filter.
+ */
+export declare function asGroupFilter(filter: Filter): GroupFilterParts | null;
+/**
+ * A single multi-cube field mapping (binding key or time dimension), e.g.
+ * `{ cube: 'Events', dimension: 'Events.userId' }`.
+ */
+type FieldMapping = {
+    cube: string;
+    dimension: string;
+};
+/**
+ * The i18n namespaces whose binding-key / time-dimension leaf keys are identical.
+ * Funnel and flow share the exact same leaf keys under these two prefixes, which
+ * is what lets the resolution logic below be shared. (Retention uses a different
+ * leaf-key set — see `bindingKeyErrorsForPrefix` vs the bespoke config it passes.)
+ */
+type AnalysisErrorPrefix = 'server.errors.funnel' | 'server.errors.flow';
+/**
+ * Extract the dimension name from a `'Cube.dim'` or bare `'dim'` reference.
+ * (`'Cube.dim'` → `'dim'`, `'dim'` → `'dim'`.) Funnel/flow only ever pass the
+ * qualified form, so this is a strict superset of their old `.split('.')[1]`.
+ */
+export declare function extractDimensionName(dimension: string): string;
+/**
+ * Builders of the i18n error strings thrown while resolving a binding key.
+ * Each builder receives the resolved context so callers can preserve their exact
+ * existing message keys/params (funnel/flow and retention use different leaf keys).
+ */
+export interface BindingKeyErrors {
+    /** Array form: no mapping in the array matched the current cube. */
+    noMapping: (ctx: {
+        cubeName: string;
+    }) => string;
+    /** The cube named in the key/mapping was not found in the `cubes` registry. */
+    cubeNotFound?: (ctx: {
+        cubeName: string;
+    }) => string;
+    /** String form: the binding-key dimension was not found on the resolved cube. */
+    keyDimNotFound: (ctx: {
+        bindingKey: string;
+        cubeName: string;
+        dimName: string;
+    }) => string;
+    /** Array form: the mapped dimension was not found on the resolved cube. */
+    mappingDimNotFound: (ctx: {
+        dimension: string;
+        cubeName: string;
+        dimName: string;
+    }) => string;
+}
+/**
+ * Build the binding-key error messages for funnel/flow from their shared i18n
+ * namespace (the leaf keys are identical across the two prefixes).
+ */
+export declare function bindingKeyErrorsForPrefix(errorPrefix: AnalysisErrorPrefix): BindingKeyErrors;
+/**
+ * Resolve a binding-key SQL expression for the analysis builders.
+ *
+ * Accepts a `'Cube.dim'` string or an array of `{ cube, dimension }` mappings.
+ * `errors` supplies the i18n messages (funnel/flow share one leaf-key set via
+ * `bindingKeyErrorsForPrefix`; retention passes its own). When `cubes` is given,
+ * the dimension is resolved on the cube named in the key (retention's multi-cube
+ * semantics); otherwise it is resolved on `cube` (funnel/flow).
+ */
+export declare function resolveBindingKeyExpr(bindingKey: string | FieldMapping[], cube: Cube, context: QueryContext, errors: BindingKeyErrors, cubes?: Map<string, Cube>): SQL;
+/**
+ * Resolve a time-dimension SQL expression for funnel/flow builders.
+ *
+ * Accepts a `'Cube.dim'` string or an array of `{ cube, dimension }` mappings.
+ * `errorPrefix` selects the i18n namespace (the leaf keys are identical across
+ * funnel and flow): `<prefix>.timeDimNotFound`, `<prefix>.noTimeDimMapping`,
+ * `<prefix>.timeDimMappingNotFound`.
+ */
+export declare function resolveTimeDimensionExpr(timeDimension: string | FieldMapping[], cube: Cube, context: QueryContext, errorPrefix: AnalysisErrorPrefix): SQL;
+export {};

package/dist/server/{server/builders → builders}/comparison-query-builder.d.ts

@@ -1,5 +1,5 @@
-import { SemanticQuery, TimeDimension, QueryResult, TimeGranularity } from '../types';
-import { DatabaseAdapter } from '../adapters/base-adapter';
+import { SemanticQuery, TimeDimension, QueryResult, TimeGranularity } from '../types/index.js';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
 /**
  * Normalized period range with start/end dates and metadata
  */

package/dist/server/{server/builders → builders}/cte-builder.d.ts

@@ -1,6 +1,6 @@
 import { SQL } from 'drizzle-orm';
-import { SemanticQuery, QueryContext, PhysicalQueryPlan, PropagatingFilter } from '../types';
-import { DrizzleSqlBuilder } from '../physical-plan/drizzle-sql-builder';
+import { SemanticQuery, QueryContext, PhysicalQueryPlan, PropagatingFilter } from '../types/index.js';
+import { DrizzleSqlBuilder } from '../physical-plan/drizzle-sql-builder.js';
 /**
  * CTE information type extracted from runtime physical plan context
  */
@@ -26,6 +26,52 @@ export declare class CTEBuilder {
      * 5. Handles multi-hop join paths by absorbing intermediate tables (fan-out prevention)
      */
     buildPreAggregationCTE(cteInfo: CTEInfo, query: SemanticQuery, context: QueryContext, queryPlan: PhysicalQueryPlan, preBuiltFilterMap?: Map<string, SQL[]>): any;
+    /**
+     * Build the SELECT map for a pre-aggregation CTE: join keys (or the
+     * intermediate primary-connected column), downstream join keys, aggregated
+     * measures, and requested dimensions / time dimensions from this cube.
+     */
+    private buildCTESelections;
+    /** Add join-key columns (or the intermediate primary-connected column) to the CTE SELECT. */
+    private addJoinKeySelections;
+    /** Add downstream join-key columns so downstream cubes can be joined through this CTE. */
+    private addDownstreamKeySelections;
+    /** Add aggregated measure expressions to the CTE SELECT. */
+    private addMeasureSelections;
+    /** Add requested dimensions and time dimensions (from this cube) to the CTE SELECT. */
+    private addDimensionSelections;
+    /**
+     * Add JOINs to intermediate tables inside the CTE (multi-hop fan-out
+     * prevention). Joins from CTE-nearest to primary-nearest so each ON clause
+     * only references tables already in scope.
+     */
+    private applyIntermediateJoins;
+    /**
+     * Assemble the full WHERE condition list for a pre-aggregation CTE: security
+     * context, regular dimension filters, time-dimension date filters, and
+     * propagating filters from related cubes.
+     *
+     * IMPORTANT: Only dimension filters are applied here; measure filters belong
+     * in the main query's HAVING clause.
+     */
+    private buildCTEWhereConditions;
+    /**
+     * Build the time-dimension date filters (from `timeDimensions.dateRange` and
+     * `inDateRange` simple filters) plus propagating-filter subqueries for a CTE.
+     */
+    private buildCTETimeFilters;
+    /**
+     * Build the GROUP BY fields for a pre-aggregation CTE: join keys (or the
+     * intermediate primary-connected column), downstream join keys, and requested
+     * dimensions / time dimensions. De-dupes named columns.
+     */
+    private buildCTEGroupByFields;
+    /**
+     * Add join keys (and downstream join keys) to the CTE GROUP BY via the de-dupe
+     * callback. For multi-hop paths uses the intermediate table's
+     * primary-connected column (e.g. employees.department_id).
+     */
+    private addJoinKeyGroupBy;
     /**
      * Build join condition for CTE
      *

package/dist/server/{server/builders → builders}/date-time-builder.d.ts

@@ -1,6 +1,6 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
-import { QueryContext } from '../types';
-import { DatabaseAdapter } from '../adapters/base-adapter';
+import { QueryContext } from '../types/index.js';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
 export declare class DateTimeBuilder {
     private databaseAdapter;
     constructor(databaseAdapter: DatabaseAdapter);
@@ -12,6 +12,11 @@ export declare class DateTimeBuilder {
      * Build date range condition for time dimensions
      */
     buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
+    private rangeBetween;
+    /** Shift a normalized end value to end-of-day when its source was a date-only string. */
+    private endOfDayValue;
+    private buildArrayDateRangeCondition;
+    private buildStringDateRangeCondition;
     /**
      * Parse relative date range expressions like "today", "yesterday", "last 7 days", "this month", etc.
      * Handles all 14 DATE_RANGE_OPTIONS from the client

package/dist/server/builders/date-time-helpers.d.ts

@@ -0,0 +1,34 @@
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+/**
+ * Convert a millisecond epoch to the engine's wire format:
+ * - SQLite: Unix seconds (integer)
+ * - other integer-timestamp engines: Unix milliseconds (integer)
+ * - PostgreSQL/MySQL: ISO string
+ */
+export declare function epochMsToEngineValue(databaseAdapter: DatabaseAdapter, timeMs: number): string | number;
+/**
+ * Convert a Date to the engine's wire format (see epochMsToEngineValue).
+ */
+export declare function dateToEngineValue(databaseAdapter: DatabaseAdapter, date: Date): string | number;
+/**
+ * Reconstruct a Date from a normalized value (the output of normalizeDate):
+ * a SQLite Unix-seconds integer, a millisecond integer, or an ISO string.
+ */
+export declare function engineValueToDate(databaseAdapter: DatabaseAdapter, value: string | number): Date;
+/** Detect a date-only string (YYYY-MM-DD). */
+export declare function isDateOnlyString(value: unknown): value is string;
+/**
+ * Normalize a date value to the engine's wire format, or null when falsy or
+ * unparseable.
+ */
+export declare function normalizeDateValue(databaseAdapter: DatabaseAdapter, value: any): string | number | null;
+type DateRange = {
+    start: Date;
+    end: Date;
+};
+/**
+ * Parse relative date range expressions like "today", "yesterday",
+ * "last 7 days", "this month", etc. Handles all 14 DATE_RANGE_OPTIONS.
+ */
+export declare function parseRelativeDateRangeValue(dateRange: string): DateRange | null;
+export {};

package/dist/server/{server/builders → builders}/filter-builder.d.ts

@@ -1,7 +1,7 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
-import { FilterOperator, Filter, Cube, QueryContext } from '../types';
-import { DatabaseAdapter } from '../adapters/base-adapter';
-import { DateTimeBuilder } from './date-time-builder';
+import { FilterOperator, Filter, Cube, QueryContext } from '../types/index.js';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { DateTimeBuilder } from './date-time-builder.js';
 export declare class FilterBuilder {
     private databaseAdapter;
     private dateTimeBuilder;
@@ -15,6 +15,8 @@ export declare class FilterBuilder {
      * This handles nested filter structures and builds combined SQL
      */
     buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+    /** Build + AND/OR-combine a list of sub-filters, collapsing the 0- and 1-element cases. */
+    private combineFilters;
     /**
      * Build SQL for a single filter condition (simple or logical)
      * Used for cache preloading to build filters independently of query context

package/dist/server/builders/filter-operators.d.ts

@@ -0,0 +1,23 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { FilterOperator } from '../types/index.js';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { DateTimeBuilder } from './date-time-builder.js';
+/**
+ * Context passed to every operator handler. Carries the resolved field
+ * expression, the (already filtered/converted) value list, plus the
+ * collaborators a handler may need.
+ */
+export interface FilterOperatorContext {
+    fieldExpr: AnyColumn | SQL;
+    values: any[];
+    filteredValues: any[];
+    value: any;
+    field?: any;
+    databaseAdapter: DatabaseAdapter;
+    dateTimeBuilder: DateTimeBuilder;
+}
+/**
+ * Dispatch a single filter operator to its handler. Returns null for any
+ * unknown operator (matching the original `default` case).
+ */
+export declare function applyFilterOperator(operator: FilterOperator, ctx: FilterOperatorContext): SQL | null;