@gscdump/engine 0.4.0

package/dist/resolver/index.d.mts

@@ -0,0 +1,207 @@
+import { SQL } from "drizzle-orm";
+import { LogicalDataset, LogicalDataset as LogicalDataset$1, PlannerCapabilities } from "gscdump/query/plan";
+import { BuilderState, Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
+import { TableName } from "gscdump/contracts";
+type DimensionSurface = 'api' | 'stored' | 'derived';
+interface DimensionBinding {
+  column: string;
+  surfaces: readonly DimensionSurface[];
+}
+interface LogicalDatasetDefinition {
+  dimensions: Partial<Record<Dimension, DimensionBinding>>;
+}
+declare const DIMENSION_SURFACES: Record<Dimension, readonly DimensionSurface[]>;
+declare const LOGICAL_DATASETS: Record<LogicalDataset, LogicalDatasetDefinition>;
+declare function inferLogicalDataset(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): LogicalDataset;
+declare function dimensionColumn(dim: Dimension, dataset: LogicalDataset): string;
+declare function supportsDimensionOnSurface(dim: Dimension, surface: DimensionSurface): boolean;
+declare function assertDimensionsSupported(dimensions: readonly Dimension[], surface: DimensionSurface, context: string): void;
+interface SqlFragmentsConfig<TableKey extends string> {
+  schema: Record<TableKey, unknown>;
+  datasetToTableKey: Record<keyof typeof LOGICAL_DATASETS, TableKey>;
+  metricCast: 'REAL' | 'DOUBLE';
+  regexPredicate: (expr: SQL, pattern: string, negate: boolean) => SQL;
+  tableLabel: string;
+  includeSiteId: boolean;
+  urlToPathExpr?: (col: string) => string;
+  /**
+   * Override the FROM-clause table reference. Default emits the bound drizzle
+   * table (e.g. `"pages"`). Parquet/R2 adapter overrides this to emit
+   * `read_parquet({{FILES}}, ...) AS "${tk}"` so the runSQL pipeline can swap
+   * in an object-key list while column refs (`"pages"."url"`) still resolve
+   * against the alias.
+   */
+  tableRef?: (tableKey: TableKey) => SQL;
+}
+interface SqlFragments<TableKey extends string> {
+  METRIC_NAMES: Metric[];
+  DIM_COLUMN_MAP: Record<TableKey, Record<string, string>>;
+  isMetricDimension: (dim: string) => dim is Metric;
+  tableKeyForDataset: (dataset: LogicalDataset$1) => TableKey;
+  dimColumn: (dim: Dimension, table: TableKey) => string;
+  inferTable: (dimensions: Dimension[], filterDims?: Dimension[]) => TableKey;
+  urlToPathExpr: (col: string) => string;
+  colRef: (tableKey: TableKey, colName: string) => SQL;
+  tableRef: (tableKey: TableKey) => SQL;
+  dateColRef: (tableKey: TableKey) => SQL;
+  siteIdColRef?: (tableKey: TableKey) => SQL;
+  dimExprSql: (dim: Dimension, tableKey: TableKey) => SQL;
+  metricSql: (metric: Metric, tableKey: TableKey) => SQL;
+  havingPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
+  dimensionPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
+  topLevelPredicate: (filters: InternalFilter[], tableKey: TableKey) => SQL | undefined;
+}
+declare function createSqlFragments<TableKey extends string>(config: SqlFragmentsConfig<TableKey>): SqlFragments<TableKey>;
+interface ResolverAdapter<TableKey extends string = string> {
+  readonly METRIC_NAMES: readonly Metric[];
+  readonly capabilities: PlannerCapabilities;
+  readonly schema: Record<TableKey, unknown>;
+  tableKeyForDataset: (dataset: LogicalDataset$1) => TableKey;
+  inferTable: (dimensions: Dimension[], filterDims?: Dimension[]) => TableKey;
+  dimColumn: (dim: Dimension, tableKey: TableKey) => string;
+  isMetricDimension: (dim: string) => dim is Metric;
+  tableRef: (tableKey: TableKey) => SQL;
+  dateColRef: (tableKey: TableKey) => SQL;
+  urlToPathExpr: (col: string) => string;
+  siteIdColRef?: (tableKey: TableKey) => SQL;
+  dimExprSql: (dim: Dimension, tableKey: TableKey) => SQL;
+  metricSql: (metric: Metric, tableKey: TableKey) => SQL;
+  dimensionPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
+  havingPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
+  topLevelPredicate: (filters: InternalFilter[], tableKey: TableKey) => SQL | undefined;
+  compile: (query: SQL) => {
+    sql: string;
+    params: unknown[];
+  };
+}
+type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
+interface ResolverOptions<TableKey extends string = string> {
+  adapter: ResolverAdapter<TableKey>;
+  /** Optional site scope. Required for multi-tenant D1; omitted for parquet. */
+  siteId?: string | number;
+}
+interface ResolvedSQL {
+  sql: string;
+  params: unknown[];
+  countSql: string;
+  countParams: unknown[];
+}
+interface ResolvedSQLOptimized {
+  sql: string;
+  params: unknown[];
+}
+interface ResolvedComparisonSQL {
+  sql: string;
+  params: unknown[];
+  countSql: string;
+  countParams: unknown[];
+}
+interface ExtraQuery {
+  key: string;
+  sql: string;
+  params: unknown[];
+}
+interface CreateResolverAdapterConfig<TableKey extends string> extends SqlFragmentsConfig<TableKey> {
+  compile: (query: SQL) => {
+    sql: string;
+    params: unknown[];
+  };
+  capabilities: PlannerCapabilities;
+}
+declare function createResolverAdapter<TableKey extends string>(config: CreateResolverAdapterConfig<TableKey>): ResolverAdapter<TableKey>;
+declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
+declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
+declare function buildTotalsSql<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): {
+  sql: string;
+  params: unknown[];
+};
+declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
+declare function buildExtrasQueries<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ExtraQuery[];
+declare function mergeExtras(rows: Record<string, unknown>[], extrasResults: {
+  key: string;
+  results: Record<string, unknown>[];
+}[]): Record<string, unknown>[];
+type QueryRow = Record<string, unknown>;
+interface FileSet {
+  table: TableName;
+  partitions: string[];
+}
+interface ExecuteSqlOptions {
+  fileSets?: Record<string, FileSet>;
+}
+interface SourceCapabilities extends PlannerCapabilities {
+  attachedTables?: boolean;
+  fileSets?: boolean;
+  localSource?: boolean;
+}
+interface RowQuerySource {
+  name?: string;
+  capabilities: SourceCapabilities;
+  queryRows: (state: BuilderState) => Promise<QueryRow[]>;
+  readonly executeSql?: undefined;
+}
+interface SqlQuerySource {
+  name?: string;
+  capabilities: SourceCapabilities;
+  queryRows: (state: BuilderState) => Promise<QueryRow[]>;
+  executeSql: (sql: string, params?: unknown[], opts?: ExecuteSqlOptions) => Promise<QueryRow[]>;
+}
+type AnalysisQuerySource = RowQuerySource | SqlQuerySource;
+declare function isSqlQuerySource(s: AnalysisQuerySource): s is SqlQuerySource;
+interface CreateSqlQuerySourceOptions<TKey extends string> {
+  /** Debug-only identifier surfaced on the source for error messages. */
+  name: string;
+  /** Dialect-specific adapter; compiles `BuilderState` → `{ sql, params }`. */
+  adapter: ResolverAdapter<TKey>;
+  /** Drives the underlying DB. Called for both typed queries and raw SQL. */
+  execute: (sql: string, params: unknown[]) => Promise<QueryRow[]>;
+  /** Tenant id for multi-tenant dialects; forwarded to `resolveToSQL`. */
+  siteId?: string | number;
+  /** Additional capability flags merged on top of `adapter.capabilities`. */
+  extraCapabilities?: Partial<SourceCapabilities>;
+}
+declare function createSqlQuerySource<TKey extends string>(options: CreateSqlQuerySourceOptions<TKey>): SqlQuerySource;
+declare function compilePg(query: SQL): {
+  sql: string;
+  params: unknown[];
+};
+declare function compileSqlite(query: SQL): {
+  sql: string;
+  params: unknown[];
+};
+declare function getInternalFilters(filter: FilterInput | undefined): InternalFilter[];
+declare function getDimensionFilters(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): InternalFilter[];
+declare function getFilterDimensions(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): Dimension[];
+declare function metricValue(row: Record<string, unknown>, metric: string): number;
+declare function dimensionValue(row: Record<string, unknown>, dimension: string): string;
+declare function matchesDimensionFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+declare function matchesMetricFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+declare function matchesTopLevelPage(row: Record<string, unknown>): boolean;
+type PgTableKey = TableName;
+declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
+/**
+ * Parquet-aware variant of {@link pgResolverAdapter}. Identical SQL output
+ * except FROM clauses emit `read_parquet({{FILES}}, union_by_name = true) AS
+ * "${tk}"`. The runSQL pipeline substitutes `{{FILES}}` with R2 object keys
+ * resolved from the manifest. The `AS "${tk}"` alias is mandatory — drizzle
+ * compiles `colRef` to table-qualified `"pages"."url"`, which would not
+ * resolve against an unaliased FROM.
+ *
+ * Single-use: build a fresh adapter per query. Cheap (no I/O) and avoids
+ * accidental adapter caching that would lock in a stale `{{FILES}}` set.
+ */
+declare function createParquetResolverAdapter(): ResolverAdapter<PgTableKey>;
+interface AssertSchemaInSyncOptions {
+  /** Label used in the thrown error (e.g. 'browser', 'sqlite'). */
+  label: string;
+  /** Drizzle schema keyed by table name. For sqlite, strip the `gsc_` prefix before passing. */
+  schema: Record<string, unknown>;
+  /**
+   * Map drizzle table key → canonical `TableName`. For browser this is identity;
+   * for sqlite this strips the `gsc_` prefix.
+   */
+  tableKeyToName: (key: string) => TableName;
+  mode: 'exact' | 'superset';
+}
+declare function assertSchemaInSync(options: AssertSchemaInSyncOptions): void;
+export { type AnalysisQuerySource, type AssertSchemaInSyncOptions, type ComparisonFilter, type CreateResolverAdapterConfig, type CreateSqlQuerySourceOptions, DIMENSION_SURFACES, type DimensionBinding, type DimensionSurface, type ExecuteSqlOptions, type ExtraQuery, type FileSet, LOGICAL_DATASETS, type LogicalDataset, type LogicalDatasetDefinition, type PgTableKey, type QueryRow, type ResolvedComparisonSQL, type ResolvedSQL, type ResolvedSQLOptimized, type ResolverAdapter, type ResolverOptions, type RowQuerySource, type SourceCapabilities, type SqlFragments, type SqlFragmentsConfig, type SqlQuerySource, assertDimensionsSupported, assertSchemaInSync, buildExtrasQueries, buildTotalsSql, compilePg, compileSqlite, createParquetResolverAdapter, createResolverAdapter, createSqlFragments, createSqlQuerySource, dimensionColumn, dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, inferLogicalDataset, isSqlQuerySource, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, mergeExtras, metricValue, pgResolverAdapter, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized, supportsDimensionOnSurface };