@gscdump/engine 1.4.0 → 1.4.2

package/dist/_chunks/registry.d.mts

@@ -1,213 +0,0 @@
-import { Row as Row$1 } from "./storage.mjs";
-import { AnalysisParams } from "./analysis-types.mjs";
-import { ResolverAdapter } from "./types.mjs";
-import { PlannerCapabilities } from "gscdump/query/plan";
-import { BuilderState } from "gscdump/query";
-import { TableName } from "@gscdump/contracts";
-type QueryRow = Record<string, unknown>;
-interface FileSet {
-  table: TableName;
-  partitions: string[];
-}
-interface ExecuteSqlOptions {
-  fileSets?: Record<string, FileSet>;
-}
-/**
- * Flat capability bag: planner-side flags (`regex`, `comparisonJoin`, ...)
- * mixed with storage-side flags. SQL execution is not a capability flag —
- * callers probe `typeof source.executeSql === 'function'`.
- */
-interface SourceCapabilities extends PlannerCapabilities {
-  attachedTables?: boolean;
-  fileSets?: boolean;
-  /**
-   * true iff the source provides a `ResolverAdapter` for analyzers that
-   * compose SQL from a typed `BuilderState` at plan-build time.
-   */
-  adapter?: boolean;
-}
-type AnalysisSourceKind = 'local' | 'browser' | 'live' | 'in-memory' | 'composite' | 'attached-table';
-interface AnalysisQuerySource {
-  name?: string;
-  /** Telemetry tag stamped onto analyzer result meta; not used for routing. */
-  kind?: AnalysisSourceKind;
-  capabilities: SourceCapabilities;
-  /**
-   * Dialect adapter surfaced for analyzers that compose SQL from a
-   * `BuilderState` at plan-build time. Optional for pure row sources.
-   */
-  adapter?: ResolverAdapter<any>;
-  /** Tenant scope; multi-tenant dialects (sqlite/D1) require it, parquet omits it. */
-  siteId?: string | number;
-  queryRows: (state: BuilderState) => Promise<QueryRow[]>;
-  /**
-   * Optional raw-SQL escape hatch. Receives the compiled SQL plan with
-   * `{{FILES}}` placeholders; sources that advertise `capabilities.fileSets`
-   * consume `opts.fileSets`, others ignore them. Implementations MUST coerce
-   * BigInts to numbers before returning (see Source invariant above).
-   */
-  executeSql?: (sql: string, params?: unknown[], opts?: ExecuteSqlOptions) => Promise<QueryRow[]>;
-}
-/**
- * Capabilities a Plan may require of its host. Dispatch matches `requires`
- * against the source's declared `capabilities` (and the presence of
- * `executeSql`) and rejects mismatches.
- *
- * `'executeSql'` checks for the method on the source; the rest are flag keys
- * on `SourceCapabilities`. Single source of truth — adding a new capability
- * is one line in `SourceCapabilities`.
- */
-type RequiredCapability = 'executeSql' | keyof SourceCapabilities;
-interface SqlExtraQuery {
-  name: string;
-  sql: string;
-  params: unknown[];
-}
-/**
- * SQL-native plan: SQL string + placeholders, with optional extra file sets
- * and follow-up queries.
- */
-interface SqlPlan {
-  kind: 'sql';
-  sql: string;
-  params: unknown[];
-  current: FileSet;
-  previous?: FileSet;
-  extraFiles?: Record<string, FileSet>;
-  extraQueries?: SqlExtraQuery[];
-}
-interface TypedRowQuery<T extends Row$1 = Row$1> {
-  state: BuilderState;
-  /** Optional type tag for downstream narrowing. */
-  rowType?: (row: Row$1) => T;
-}
-/**
- * Row-queries plan: a named set of typed `BuilderState` queries. A portable
- * dispatcher runs each against a source's `queryRows` and hands the row
- * collection to `reduce`.
- */
-interface RowQueriesPlan {
-  kind: 'rows';
-  queries: Record<string, TypedRowQuery>;
-}
-type Plan = SqlPlan | RowQueriesPlan;
-/**
- * Plan-build context. Surfaced from the source at dispatch time so analyzers
- * that compose SQL from a typed `BuilderState` can pick up the right dialect
- * adapter without importing one directly. Most SQL analyzers emit static SQL
- * and ignore this; only the BuilderState-driven `data-query` / `data-detail`
- * analyzers consume it today.
- *
- * `adapter` is optional on the type; analyzers that need it should call
- * `requireAdapter(ctx, id)` rather than non-null-asserting. Capability
- * declaration (`'adapter'` in `requires`) is the runtime guarantee; the
- * helper makes the failure mode loud if the contract is broken.
- */
-interface BuildContext {
-  adapter?: ResolverAdapter<any>;
-  siteId?: string | number;
-}
-/**
- * Throw a uniform error if a SQL analyzer declared the `'adapter'` capability
- * but the dispatcher handed it a context without one. Centralizes the assert
- * so analyzers don't repeat `ctx.adapter!` with explanatory comments.
- */
-declare function requireAdapter(ctx: BuildContext, analyzerId: string): ResolverAdapter<any>;
-interface ReduceContext<TRow extends Row$1 = Row$1> {
-  params: AnalysisParams;
-  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
-  extras?: Record<string, TRow[]>;
-}
-/**
- * Unified analyzer contract. `TRow` lets authors narrow from the default
- * `Row = Record<string, unknown>` to a typed row shape (e.g. `QueriesRow`)
- * when their reducer assumes specific columns exist — catches drift between
- * `build` (SELECT list) and `reduce` (column access) at compile time.
- */
-interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row$1 = Row$1> {
-  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
-  id: string;
-  /** Capabilities a host source must provide. */
-  requires: readonly RequiredCapability[];
-  /** Pure: params → plan. Snapshot-testable. `ctx` carries the source's dialect adapter when one is available. */
-  build: (params: P, ctx?: BuildContext) => Plan;
-  /** Pure: rows + context → typed result + meta. */
-  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
-    results: R;
-    meta?: Record<string, unknown>;
-  };
-}
-interface SqlPlanSpec {
-  sql: string;
-  params: unknown[];
-  current: FileSet;
-  previous?: FileSet;
-  extraFiles?: Record<string, FileSet>;
-  extraQueries?: SqlExtraQuery[];
-}
-interface ReduceCtx<InputRow> {
-  /** Extra SQL-query results keyed by `SqlExtraQuery.name` (SQL path only). */
-  extras?: Record<string, InputRow[]>;
-}
-type Reducer<Params, InputRow, Result> = (rows: InputRow[] | Record<string, InputRow[]>, params: Params, ctx: ReduceCtx<InputRow>) => {
-  results: Result;
-  meta?: Record<string, unknown>;
-};
-interface DefineAnalyzerOptions<Params extends AnalysisParams, InputRow, Result> {
-  id: string;
-  /**
-   * Shared reducer used by both SQL and row paths. Use this when the
-   * post-aggregation row count is small and filter/sort/derive can live in
-   * one place. Mutually exclusive with `reduceSql` / `reduceRows`.
-   */
-  reduce?: Reducer<Params, InputRow, Result>;
-  /** SQL-only reducer. Required when `buildSql` is set without `reduce`. */
-  reduceSql?: Reducer<Params, InputRow, Result>;
-  /** Row-only reducer. Required when `buildRows` is set without `reduce`. */
-  reduceRows?: Reducer<Params, InputRow, Result>;
-  /** SQL plan builder. Omit if the analyzer has no SQL path. */
-  buildSql?: (params: Params, ctx: BuildContext) => SqlPlanSpec;
-  /** Row plan builder. Omit if the analyzer has no row path. */
-  buildRows?: (params: Params, ctx: BuildContext) => Record<string, BuilderState>;
-  /** Capabilities required by the SQL plan. Defaults to `['executeSql', 'fileSets']`. */
-  sqlRequires?: readonly RequiredCapability[];
-  /** Capabilities required by the row plan. Defaults to `[]`. */
-  rowsRequires?: readonly RequiredCapability[];
-}
-interface DefinedAnalyzer {
-  id: string;
-  sql?: Analyzer;
-  rows?: Analyzer;
-}
-declare function defineAnalyzer<Params extends AnalysisParams, InputRow, Result>(opts: DefineAnalyzerOptions<Params, InputRow, Result>): DefinedAnalyzer;
-interface AnalyzerVariants {
-  sql?: Analyzer;
-  rows?: Analyzer;
-}
-interface AnalyzerRegistryInit {
-  /**
-   * Preferred for in-tree composition: pass `DefinedAnalyzer[]` directly so
-   * SQL/row variants can never drift apart from their `defineAnalyzer` site.
-   */
-  defined?: readonly DefinedAnalyzer[];
-  /** Flat-array path retained for narrow tree-shaken registry composition. */
-  rows?: readonly Analyzer[];
-  /** Flat-array path retained for narrow tree-shaken registry composition. */
-  sql?: readonly Analyzer[];
-}
-interface AnalyzerRegistry {
-  listAnalyzerIds: () => readonly string[];
-  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
-  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
-  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
-  listAnalyzerIdsFor: (source: {
-    executeSql?: unknown;
-  }) => readonly string[];
-}
-/**
- * Build an immutable registry from collections of row / SQL analyzers.
- * No global state; call this once per logical use (typically at startup
- * or per-request in a worker).
- */
-declare function createAnalyzerRegistry(init?: AnalyzerRegistryInit): AnalyzerRegistry;
-export { AnalysisQuerySource, AnalysisSourceKind, Analyzer, AnalyzerRegistry, AnalyzerRegistryInit, AnalyzerVariants, BuildContext, DefineAnalyzerOptions, DefinedAnalyzer, ExecuteSqlOptions, FileSet, Plan, QueryRow, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SourceCapabilities, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, requireAdapter };