@minnowdb/core 0.0.1 → 0.1.0

package/dist/engine/query.d.ts

@@ -0,0 +1,844 @@
+import type { DatabaseRow } from "./database.js";
+import type { ColumnDefault } from "../storage/types.js";
+import { type FtsStats } from "./fts.js";
+import { QueryMemoryContext, type QueryMemoryUsage } from "./memory.js";
+import { type ColumnarTable, type AsyncQueryExecutionOptions } from "./vector.js";
+export type QueryValue = boolean | number | string | Date | null;
+export type QueryRow = Record<string, QueryValue>;
+export interface QueryResult {
+    columns: string[];
+    rows: QueryRow[];
+}
+export interface PreparedQuery {
+    readonly sql: string;
+    readonly tables: string[];
+    /**
+     * Current retained and high-water byte counts for the documented modeled query-memory scope.
+     * Result-construction bytes affect the peak but transfer out of the context when execute returns.
+     */
+    readonly memoryUsage: QueryMemoryUsage;
+    execute(): QueryResult;
+    executeAsync(options?: AsyncQueryExecutionOptions): Promise<QueryResult>;
+    close(): void;
+}
+export interface QueryExecutionOptions {
+    /**
+     * Bounds the modeled vector, row-index, group/result payload, and ordering buffers. This is not a
+     * total JavaScript heap limit; input preparation, container/allocator overhead, and returned-result
+     * lifetime are excluded. The schema-less empty-table row adapter rejects configured budgets;
+     * MinnowDatabase retains catalog types and does not use that fallback.
+     */
+    readonly executionMemoryBudgetBytes?: number;
+}
+export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "||";
+export type ComparisonOperator = "=" | "!=" | "<>" | ">" | ">=" | "<" | "<=";
+export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX";
+export type ScalarFunctionName = "ROUND" | "COALESCE" | "DATE_TRUNC" | "DATE_ADD" | "UPPER" | "LOWER" | "LENGTH" | "ABS" | "TRIM" | "LTRIM" | "RTRIM" | "SUBSTR" | "REPLACE" | "INSTR" | "NULLIF" | "GREATEST" | "LEAST" | "FLOOR" | "CEIL" | "MOD" | "POWER" | "SQRT" | "EXTRACT" | "CAST" | "OCTET_LENGTH" | "LPAD" | "RPAD" | "OVERLAY" | "CURRENT_DATE" | "CURRENT_TIMESTAMP" | "LOCALTIME" | "GROUPING" | "JSON_VALUE" | "JSON_QUERY" | "JSON_EXISTS" | "JSON_OBJECT" | "JSON_ARRAY" | "IS_JSON";
+export declare const scalarFunctionNames: ReadonlySet<string>;
+/**
+ * The niladic datetime functions (F051-06/07/08). Their value is the statement's own clock
+ * reading, so they are resolved once per execution rather than evaluated per row: every row of
+ * one statement sees one instant, both executors agree, and constant folding leaves them alone.
+ */
+export declare const statementDatetimeNames: ReadonlySet<string>;
+export declare function isScalarFunctionName(name: AggregateName | ScalarFunctionName): name is ScalarFunctionName;
+/**
+ * Evaluates one scalar function over already-evaluated argument values. Every executor calls
+ * through here, so a function behaves identically in the row executor, the vectorized executor,
+ * and constant folding. COALESCE is not handled here — it short-circuits, so each call site
+ * evaluates it lazily. A NULL first argument returns NULL (SQL scalar semantics); LENGTH and
+ * SUBSTR count characters, not UTF-16 units, matching SQLite and PostgreSQL.
+ */
+export declare function scalarFunctionValue(name: Exclude<ScalarFunctionName, "COALESCE">, values: readonly unknown[]): unknown;
+export declare const dateTruncUnits: ReadonlySet<string>;
+/**
+ * `INTERVAL '1 month'`, `INTERVAL '2 years 3 days'`. Months are kept apart from milliseconds
+ * rather than converted, because a month is not a fixed number of them: adding one to January 31
+ * has to land on the end of February, which only calendar arithmetic can do.
+ */
+export declare function intervalLiteral(text: string): {
+    months: number;
+    milliseconds: number;
+};
+/**
+ * A datetime shifted by a calendar interval: whole months first, then milliseconds. A day that
+ * does not exist in the target month clamps to that month's last day, which is what both SQLite
+ * and PostgreSQL do with 31 January plus a month.
+ */
+export declare function dateAddValue(value: unknown, months: unknown, milliseconds: unknown): Date | null;
+export declare function dateTruncValue(unit: unknown, value: unknown): Date | null;
+export type Expression = {
+    kind: "literal";
+    value: QueryValue;
+}
+/** A `?` or `$n` placeholder; `index` is 0-based. Replaced by a literal at bind time. */
+ | {
+    kind: "parameter";
+    index: number;
+} | {
+    kind: "column";
+    reference: string;
+}
+/**
+ * `*`, or `alias.*` when `table` is set (E051-07). A qualified wildcard names one source and
+ * may sit beside other select items; every executor entry expands it into that source's
+ * columns, so past the entry only a bare wildcard — the whole-row projection — survives.
+ */
+ | {
+    kind: "wildcard";
+    table?: string;
+} | {
+    kind: "binary";
+    operator: BinaryOperator;
+    left: Expression;
+    right: Expression;
+} | {
+    kind: "call";
+    name: AggregateName | ScalarFunctionName;
+    arguments: Expression[];
+    distinct?: boolean;
+} | {
+    kind: "list";
+    items: Expression[];
+} | {
+    kind: "subquery";
+    block: CompiledQuery;
+} | {
+    kind: "condition";
+    operator: PredicateOperator;
+    left: Expression;
+    right: Expression;
+    /** LIKE/ILIKE escape character, from LIKE ... ESCAPE 'c'. */
+    escape?: string;
+} | {
+    kind: "logical";
+    operator: "and" | "or";
+    left: Expression;
+    right: Expression;
+} | {
+    kind: "not";
+    operand: Expression;
+} | {
+    kind: "exists";
+    block: CompiledQuery;
+    negated: boolean;
+} | {
+    kind: "case";
+    branches: Array<{
+        when: Expression;
+        then: Expression;
+    }>;
+    otherwise?: Expression;
+} | {
+    kind: "window";
+    name: WindowFunctionName;
+    partitionBy: Expression[];
+    orderBy: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+    argument?: Expression;
+    /** LAG/LEAD row distance; parsed as a literal non-negative integer, defaulting to 1. */
+    offset?: number;
+    /** LAG/LEAD default when the offset row falls outside the partition; NULL when absent. */
+    fallback?: QueryValue;
+    frame?: WindowFrame;
+} | {
+    kind: "fts";
+    op: "match" | "bm25";
+    /**
+     * Column references forming the document, or "*" for every searchable column of the
+     * single scan source. "*" stays unexpanded through compilation (both front ends emit the
+     * identical node — plan parity), and the engine expands it against the catalog at
+     * prepare time via expandFtsColumns.
+     */
+    columns: Expression[] | "*";
+    query: string;
+    /**
+     * Corpus statistics for BM25, annotated by the executor onto its cloned plan before
+     * evaluation; never set by compilation.
+     */
+    stats?: FtsStats;
+};
+export type WindowFunctionName = "ROW_NUMBER" | "RANK" | "DENSE_RANK" | "PERCENT_RANK" | "CUME_DIST" | "NTILE" | "LAG" | "LEAD" | "FIRST_VALUE" | "LAST_VALUE" | "NTH_VALUE" | AggregateName;
+export interface WindowFrameBound {
+    kind: "unbounded-preceding" | "preceding" | "current-row" | "following" | "unbounded-following";
+    /** Row distance for preceding/following bounds (ROWS unit only). */
+    offset?: number;
+}
+/** How a frame's rows are excluded around the current row (T612). */
+export type WindowFrameExclusion = "no-others" | "current-row" | "group" | "ties";
+/** An explicit frame clause; absent means the SQL default for the window's ordering. */
+export interface WindowFrame {
+    unit: "rows" | "range" | "groups";
+    start: WindowFrameBound;
+    end: WindowFrameBound;
+    /** Rows excluded around the current row; absent means EXCLUDE NO OTHERS. */
+    exclude?: WindowFrameExclusion;
+}
+export interface WindowSpec {
+    alias: string;
+    name: WindowFunctionName;
+    partitionAliases: string[];
+    orderAliases: Array<{
+        alias: string;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+    /** Hidden inner alias of an aggregate window's argument; absent for COUNT(*) and rankings. */
+    argumentAlias?: string;
+    /** LAG/LEAD row distance. */
+    offset?: number;
+    /** LAG/LEAD default when the offset row falls outside the partition. */
+    fallback?: QueryValue;
+    frame?: WindowFrame;
+}
+/** The output column type of one window: rankings and most aggregates count, MIN/MAX carry. */
+export declare function windowOutputType(window: WindowSpec, innerSchema: readonly SqlColumnSchema[]): SqlColumnType;
+export interface SelectItem {
+    expression: Expression;
+    alias: string;
+}
+export interface TableSource {
+    table: string;
+    alias: string;
+    /** A parenthesized SELECT or expanded CTE body; `table` is then a unique synthetic name. */
+    derived?: CompiledQuery;
+    /** A top-level set operation; members combine positionally under the first member's schema. */
+    union?: {
+        blocks: CompiledQuery[];
+        ops: SetOperator[];
+    };
+    recursive?: RecursiveCte;
+    /** A window-function desugar: the inner block executes, then window columns append. */
+    windowed?: {
+        block: CompiledQuery;
+        windows: WindowSpec[];
+    };
+    /**
+     * `FROM t AS y(a, b)`: positional new names for a base table's columns (E051-09). Every
+     * executor entry turns the source into a derived projection, so past that point the rename
+     * is an ordinary select list and nothing else has to know about it.
+     */
+    columnAliases?: string[];
+}
+export interface JoinPlan extends TableSource {
+    kind: "inner" | "left";
+    left: Expression;
+    right: Expression;
+    /** General ON condition for non-equi or multi-key joins; left/right are inert placeholders. */
+    on?: Expression;
+    /** Parser marker: FULL OUTER JOIN. Assembly desugars it into a union of two left joins. */
+    full?: boolean;
+    /**
+     * Parser marker: NATURAL JOIN. Every execution entry replaces it with the equality
+     * conjunction over the columns this source shares with the ones before it, so no executor
+     * ever sees the marker (F401-01).
+     */
+    natural?: boolean;
+}
+export type SetOperator = "union" | "union all" | "intersect" | "intersect all" | "except" | "except all";
+/**
+ * A WITH RECURSIVE source: the base block seeds the working set, then the step block re-executes
+ * with `reference` bound to the previous iteration's new rows (linear delta recursion) until no
+ * new rows appear. UNION deduplicates against everything seen; UNION ALL appends raw.
+ */
+export interface RecursiveCte {
+    reference: string;
+    base: CompiledQuery;
+    step: CompiledQuery;
+    all: boolean;
+}
+export type PredicateOperator = ComparisonOperator | `${ComparisonOperator} ANY` | `${ComparisonOperator} ALL` | "IN" | "NOT IN" | "IS NULL" | "IS NOT NULL" | "LIKE" | "NOT LIKE" | "ILIKE" | "NOT ILIKE" | "IS DISTINCT FROM" | "IS NOT DISTINCT FROM" | "IS TRUE";
+export interface Predicate {
+    left: Expression;
+    operator: PredicateOperator;
+    right: Expression;
+    /** LIKE/ILIKE escape character, carried from the parsed condition. */
+    escape?: string;
+}
+export interface CompiledQuery {
+    sql: string;
+    base: TableSource;
+    joins: JoinPlan[];
+    select: SelectItem[];
+    predicates: Predicate[];
+    groupBy: Expression[];
+    having: Predicate[];
+    orderBy: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        /**
+         * Explicit NULL placement, absolute regardless of direction. Absent keeps the default:
+         * NULL sorts smallest, so ASC puts NULLs first and DESC puts them last (SQLite's default).
+         */
+        nulls?: "first" | "last";
+    }>;
+    limit?: number;
+    offset?: number;
+    /**
+     * SELECT DISTINCT * awaiting expansion: the wildcard's columns are unknown until input
+     * schemas exist, so every executor entry expands this into a concrete select list plus a
+     * matching GROUP BY exactly once (see expandDistinctWildcard), like MATCH(*).
+     */
+    distinctWildcard?: boolean;
+    /** Parameter slots for LIMIT ? / OFFSET ?; binding resolves them into limit/offset. */
+    limitParameter?: number;
+    offsetParameter?: number;
+    /**
+     * FETCH FIRST n ROWS WITH TIES (F866): rows tying with the last retained row under the
+     * ORDER BY are kept too. The limit cannot be pushed into a scan then, so every execution
+     * entry runs the query unlimited and trims the ordered result.
+     */
+    limitWithTies?: boolean;
+    /**
+     * Number of `?`/`$n` placeholders in the whole statement; set only on the top-level plan.
+     * A plan with placeholders must pass through bindPlanParameters before it prepares.
+     */
+    parameterCount?: number;
+    /**
+     * CURRENT_DATE / CURRENT_TIMESTAMP / LOCALTIME appear somewhere in the statement. Every
+     * executor entry replaces them with one instant per execution, and results never memoize,
+     * because the answer depends on the clock rather than on the data.
+     */
+    usesStatementDatetime?: boolean;
+}
+/** ORDER BY / LIMIT / OFFSET tail of a select or set operation. */
+export interface SelectTail {
+    orderBy: CompiledQuery["orderBy"];
+    limit?: number;
+    offset?: number;
+    limitParameter?: number;
+    offsetParameter?: number;
+    limitWithTies?: boolean;
+}
+/**
+ * The virtual one-row source behind a FROM-less SELECT. The name cannot collide with a real
+ * table (parentheses never survive identifier parsing unquoted), and its single hidden column
+ * keeps the row alive through columnar conversion, which derives row count from column vectors.
+ */
+export declare const DUAL_TABLE = "(dual)";
+/** The dual source's single row, shared by every resolution path. */
+export declare function dualTableRows(): DatabaseRow[];
+export interface CompileQueryOptions {
+    /** Set false to skip deterministic plan rewrites, for example to snapshot the raw plan. */
+    readonly optimize?: boolean;
+}
+export declare function compileQuery(sql: string, options?: CompileQueryOptions): CompiledQuery;
+/**
+ * One WHEN clause of a MERGE (F312). Branches are tried in order for each source row, and the
+ * first whose match state and optional condition hold decides what happens to that row.
+ */
+export type MergeBranch = {
+    when: "matched";
+    condition?: Expression;
+    action: {
+        kind: "update";
+        assignments: Array<{
+            column: string;
+            expression: Expression;
+        }>;
+    } | {
+        kind: "delete";
+    };
+} | {
+    when: "not-matched";
+    condition?: Expression;
+    action: {
+        kind: "insert";
+        columns: string[];
+        values: Expression[];
+    };
+};
+/**
+ * One FOREIGN KEY as written (E141-04). The parent column is optional in the text and defaults
+ * to the parent's unique key, which is the only column this engine can reference.
+ */
+export interface ForeignKeyDefinition {
+    name: string;
+    column: string;
+    parentTable: string;
+    parentColumn?: string;
+    onDelete: "restrict" | "cascade" | "set null";
+}
+/** An INSERT value: a constant, or an unbound `?`/`$n` placeholder awaiting its parameter. */
+export type InsertValue = QueryValue | {
+    parameter: number;
+};
+export type CompiledStatement = {
+    kind: "select";
+    sql: string;
+    parameterCount?: number;
+} | {
+    kind: "insert";
+    table: string;
+    columns: string[];
+    rows: InsertValue[][];
+    /** INSERT ... SELECT source; `rows` is then empty and fills at execution. */
+    query?: CompiledQuery;
+    /**
+     * ON CONFLICT (column) DO NOTHING skips rows whose key exists. DO UPDATE SET with every
+     * inserted column drawn from EXCLUDED is "replace" (whole-row upsert); a subset is
+     * "update", which merges only the listed columns into existing rows.
+     */
+    onConflict?: {
+        column: string;
+        action: "nothing" | "replace" | "update";
+        /** The EXCLUDED columns a partial DO UPDATE merges; present only for "update". */
+        columns?: string[];
+    };
+    returning?: string[] | "*";
+    parameterCount?: number;
+} | {
+    kind: "update";
+    table: string;
+    assignments: Array<{
+        column: string;
+        expression: Expression;
+    }>;
+    predicates: Array<{
+        left: Expression;
+        operator: PredicateOperator;
+        right: Expression;
+    }>;
+    returning?: string[] | "*";
+    parameterCount?: number;
+} | {
+    kind: "delete";
+    table: string;
+    predicates: Array<{
+        left: Expression;
+        operator: PredicateOperator;
+        right: Expression;
+    }>;
+    returning?: string[] | "*";
+    parameterCount?: number;
+} | {
+    kind: "create-table";
+    table: string;
+    columns: Array<{
+        name: string;
+        type: SqlColumnType;
+        nullable?: boolean;
+        defaultValue?: ColumnDefault;
+    }>;
+    checks?: Array<{
+        name: string;
+        sql: string;
+    }>;
+    foreignKeys?: ForeignKeyDefinition[];
+    uniqueKey?: string;
+    /** CREATE TABLE IF NOT EXISTS: an existing table of that name is left alone. */
+    ifNotExists?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "create-trigger";
+    table: string;
+    trigger: {
+        name: string;
+        event: "insert" | "update" | "delete";
+        timing: "before" | "after";
+        statements: Array<{
+            /** Body INSERT with every NEW.col / OLD.col rewritten to a positional placeholder. */
+            sql: string;
+            bindings: Array<{
+                source: "new" | "old";
+                column: string;
+            }>;
+        }>;
+    };
+    parameterCount?: number;
+} | {
+    kind: "drop-trigger";
+    name: string;
+    parameterCount?: number;
+} | {
+    kind: "create-table-as";
+    table: string;
+    query: CompiledQuery;
+    ifNotExists?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "drop-table";
+    table: string;
+    ifExists?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "create-view";
+    view: string;
+    sql: string;
+    orReplace?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "drop-view";
+    view: string;
+    ifExists?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "transaction";
+    action: "begin" | "commit" | "rollback";
+    parameterCount?: number;
+} | {
+    kind: "merge";
+    /** The target table, and the correlation name its columns are read under. */
+    table: string;
+    alias: string;
+    /**
+     * The source: a table or view by name, or a parenthesized query kept as its own text —
+     * the statement re-reads it through the ordinary query pipeline, so a source query sees
+     * views, CTEs, and joins exactly as it would on its own.
+     */
+    source: {
+        alias: string;
+        table?: string;
+        sql?: string;
+    };
+    /**
+     * The match condition. The engine requires it to equate the target's unique key with a
+     * source expression, which is also what makes each source row match at most one target
+     * row — the standard's cardinality violation cannot arise.
+     */
+    on: Expression;
+    branches: MergeBranch[];
+    parameterCount?: number;
+} | {
+    kind: "add-column";
+    table: string;
+    column: {
+        name: string;
+        type: SqlColumnType;
+        nullable?: boolean;
+        defaultValue?: ColumnDefault;
+    };
+    parameterCount?: number;
+};
+/**
+ * Compiles one CHECK constraint's stored text into the expression the writer evaluates per row.
+ * Kept beside the parser because the same restrictions apply wherever a constraint is read: a
+ * row condition over this table's columns, with no aggregate, window, subquery, or parameter.
+ */
+export declare function compileCheckExpression(sql: string, name: string): Expression;
+/**
+ * Routes one SQL statement: SELECT and WITH compile through the read-only query pipeline, while
+ * INSERT ... VALUES, UPDATE ... SET, and DELETE FROM parse into mutation statements. Any other
+ * leading keyword fails explicitly.
+ */
+export declare function compileStatement(sql: string): CompiledStatement;
+/**
+ * Evaluates an expression against several named rows — the shape MERGE works in, where one
+ * condition or assignment reads the target and the source at once.
+ */
+export declare function evaluateJoinedRowExpression(expression: Expression, rows: Readonly<Record<string, DatabaseRow | undefined>>): QueryValue;
+/** Evaluates an expression against one row, for UPDATE SET assignment computation. */
+export declare function evaluateRowExpression(expression: Expression, alias: string, row: DatabaseRow): QueryValue;
+export interface SubqueryResolutionStep {
+    /** The uncorrelated block to execute; earlier steps have already substituted inside it. */
+    readonly block: CompiledQuery;
+    /** Replaces the subquery node with the executed result as literals. */
+    substitute(result: QueryResult): void;
+}
+/**
+ * Clones a plan and returns its subquery sites in post-order: executing each step's block and
+ * substituting its result leaves the returned plan free of subquery nodes. A scalar subquery must
+ * select one column and return at most one row (empty is NULL); an IN subquery must select one
+ * column and becomes a literal membership list. Correlated references fail inside the subquery's
+ * own scope as unknown aliases.
+ */
+export declare function subqueryResolutionSteps(plan: CompiledQuery): {
+    plan: CompiledQuery;
+    steps: SubqueryResolutionStep[];
+};
+export declare function blockHasSubqueries(plan: CompiledQuery): boolean;
+/** True when any `?`/`$n` placeholder remains anywhere in the expression tree. */
+export declare function containsParameter(expression: Expression): boolean;
+export declare function blockHasParameters(block: CompiledQuery): boolean;
+/**
+ * Replaces every placeholder with its parameter value as a literal. The input plan is never
+ * modified — plans come from the compile cache, so binding is copy-on-write. The parameter list
+ * must match the statement's placeholder count exactly; a plan without placeholders passes
+ * through untouched (and rejects a non-empty parameter list explicitly).
+ */
+export declare function bindPlanParameters(plan: CompiledQuery, params: readonly QueryValue[] | undefined): CompiledQuery;
+/** The mutation-statement counterpart of bindPlanParameters; SELECTs bind through their plan. */
+export declare function bindStatementParameters(statement: CompiledStatement, params: readonly QueryValue[] | undefined): CompiledStatement;
+export type SqlColumnType = "boolean" | "number" | "string" | "datetime";
+export interface SqlColumnSchema {
+    name: string;
+    type: SqlColumnType;
+}
+/**
+ * Infers the typed output schema of one select block from typed source schemas. A column whose
+ * type cannot be established (for example a bare NULL literal) is rejected explicitly, so a
+ * derived table always has concrete column types even when its result is empty.
+ */
+export declare function inferBlockSchema(plan: CompiledQuery, schemas: ReadonlyMap<string, readonly SqlColumnSchema[]>): SqlColumnSchema[];
+export declare function referencedColumns(plan: CompiledQuery, schemas: ReadonlyMap<string, readonly string[]>): Map<string, string[]>;
+export declare function createPreparedQuery(plan: CompiledQuery, tables: ReadonlyMap<string, DatabaseRow[]>, options?: QueryExecutionOptions): PreparedQuery;
+/** Internal columnar entry point used after MinnowDatabase materializes a stable snapshot. */
+export declare function createPreparedColumnarQuery(plan: CompiledQuery, tables: ReadonlyMap<string, ColumnarTable>, memory?: QueryMemoryContext, options?: {
+    ftsStats?: ReadonlyMap<string, FtsStats>;
+}): PreparedQuery;
+export declare function executeQuery(plan: CompiledQuery, tables: ReadonlyMap<string, DatabaseRow[]>, options?: QueryExecutionOptions): QueryResult;
+/**
+ * Combines set-operation member results positionally under the first member's column names,
+ * folding left: UNION deduplicates the entire accumulated set, UNION ALL concatenates. Values
+ * compare with SQL grouping semantics (NULLs equal, dates by instant, signed zeros equal).
+ */
+export declare function combineUnionResults(results: readonly QueryResult[], ops: readonly SetOperator[]): QueryResult;
+interface RecursiveCteState {
+    readonly columns: readonly string[];
+    readonly rows: QueryRow[];
+    frontier: QueryRow[];
+    iterations: number;
+    absorb(step: QueryResult): void;
+}
+/**
+ * Drives one recursive CTE to its fixpoint: absorb() renames a step result positionally onto the
+ * base columns, appends what is new (all rows for UNION ALL, unseen rows for UNION), and refreshes
+ * the frontier. Hard caps bound runaway recursions explicitly instead of exhausting memory.
+ */
+export declare function createRecursiveCteState(base: QueryResult, all: boolean): RecursiveCteState;
+/** The direct child expressions of a node; subqueries and EXISTS scope their own blocks. */
+export declare function childExpressions(expression: Expression): Expression[];
+/**
+ * `childExpressions` in reverse: the same node with each child replaced by `map(child)`. A node
+ * with no children — or one whose children are positions this cannot rebuild, like a window's
+ * own clauses — comes back untouched, so a caller that rewrites a subtree has to reach those
+ * itself. Kept beside `childExpressions` because the two have to agree about what a child is.
+ */
+export declare function mapChildExpressions(expression: Expression, map: (child: Expression) => Expression): Expression;
+/**
+ * Visits every expression position of one block — select, predicates, HAVING, GROUP BY,
+ * ORDER BY, and join conditions — without descending into nested blocks. Every plan feature
+ * that scans "all expressions of a block" goes through here, so a future clause is added to
+ * one list instead of one per feature.
+ */
+export declare function forEachBlockExpression(block: CompiledQuery, visit: (expression: Expression) => void): void;
+/** Visits every nested block of one block's sources (derived, union, windowed, recursive). */
+export declare function forEachNestedBlock(block: CompiledQuery, visit: (nested: CompiledQuery) => void): void;
+/**
+ * Rewrites every expression slot of one block in place, the writing counterpart to
+ * `forEachBlockExpression`. The mapper receives each root expression and returns its
+ * replacement; returning the same object leaves the slot untouched.
+ */
+export declare function mapBlockExpressions(block: CompiledQuery, map: (expression: Expression) => Expression): void;
+/**
+ * Replaces CURRENT_DATE / CURRENT_TIMESTAMP / LOCALTIME with one reading of the clock, so that
+ * every row of one execution — and both executors — see a single instant. Plans that never
+ * mention them are returned untouched, which is every plan the parser did not flag.
+ */
+export declare function resolveStatementDatetimes(plan: CompiledQuery, now?: Date): CompiledQuery;
+/** One top-level full-text MATCH conjunct of a plan, with its resolved column expressions. */
+export interface FtsMatchConjunct {
+    columns: Expression[];
+    query: string;
+}
+/**
+ * The plan's top-level `MATCH ... AGAINST` conjuncts — the ones index pruning may exploit,
+ * because every result row must satisfy them. This is the sole authority on how a bare MATCH
+ * appears in `plan.predicates`: `splitCondition` wraps non-comparison booleans as
+ * `IS TRUE` predicates, and a test pins that pairing so an optimizer or parser change that
+ * rewraps the conjunct fails loudly instead of silently disabling pruning. Unexpanded `"*"`
+ * documents and negated/OR-wrapped matches are deliberately excluded.
+ */
+export declare function topLevelFtsMatchConjuncts(plan: CompiledQuery): FtsMatchConjunct[];
+/**
+ * True when the plan reads anything beyond its single flat base scan: a nested block (derived
+ * table, set-operation branch, windowed or recursive source) or a subquery/EXISTS expression.
+ * Selectivity proofs that reason only about the base scan's predicates (the live-query zone
+ * gate) are unsound for such plans — a change the base predicates reject can still shift a
+ * value the nested read produces — so they must widen to "can affect".
+ */
+export declare function planReadsBeyondSingleScan(plan: CompiledQuery): boolean;
+/** True when any expression in the plan or its nested blocks is a full-text node. */
+export declare function planContainsFts(plan: CompiledQuery, op?: "match" | "bm25"): boolean;
+/**
+ * Expands every `MATCH(*)`/`BM25(*)` in the plan into the single scan source's searchable
+ * columns (string, number, datetime — booleans are excluded from documents), and enforces the
+ * v1 restriction that a full-text document draws from exactly one base table source. Runs at
+ * prepare time when the catalog is known. Copy-on-write: plans without full-text nodes pass
+ * through untouched, and full-text plans are cloned before rewriting — the input is often the
+ * compile cache's own copy (subquery resolution returns the original plan when it has nothing
+ * to resolve), and freezing an expansion into the cache would pin a stale column list across
+ * later migrations.
+ */
+export declare function expandFtsColumns(plan: CompiledQuery, searchableColumnsFor: (tableName: string) => readonly string[] | undefined): CompiledQuery;
+/**
+ * Appends window-function columns to an executed inner-block result. Rows sort stably by the
+ * hidden partition and ordering aliases with the same comparison semantics as ORDER BY;
+ * ROW_NUMBER numbers rows per partition, RANK shares ranks across ordering ties with gaps, and
+ * DENSE_RANK shares without gaps. Without OVER ordering every partition row is a peer.
+ */
+export declare function applyWindowFunctions(result: QueryResult, windows: readonly WindowSpec[]): QueryResult;
+/** Correctness reference retained while the vector executor matures. */
+export declare function executeRowQuery(plan: CompiledQuery, tables: ReadonlyMap<string, DatabaseRow[]>): QueryResult;
+/** One ORDER BY resolution source: an alias and the columns a wildcard select exposes from it. */
+export interface OrderSourceShape {
+    readonly alias: string;
+    readonly columns: readonly string[];
+}
+/**
+ * Resolves one ORDER BY reference to the output column that carries its values, throwing when
+ * nothing matches. Dropping an unresolved sort key silently would return rows in an arbitrary
+ * order with no sign of the problem, which paging built on ORDER BY turns into skipped and
+ * repeated rows.
+ */
+export declare function orderOutputName(expression: Expression, select: readonly SelectItem[], sources: readonly OrderSourceShape[]): string;
+export interface ListMembership {
+    set: ReadonlySet<unknown>;
+    hasNull: boolean;
+}
+/**
+ * IN lists produced by subquery materialization can hold many thousands of literals, and
+ * probing them per row makes membership quadratic. A list whose items are all literals
+ * gets one hash set of comparable values (plus a null flag), cached weakly on the list
+ * node so repeated executions of a prepared plan reuse it. Lists with non-literal items
+ * return null and take the general per-row path.
+ */
+export declare function cachedListMembership(node: object, items: ReadonlyArray<{
+    kind: string;
+}>): ListMembership | null;
+/** Compiles a LIKE pattern (% = any run, _ = any character) to an anchored RegExp, cached. */
+export declare function likeRegExp(pattern: string, caseInsensitive?: boolean, escape?: string): RegExp;
+/**
+ * A compiled LIKE matcher. Patterns shaped `abc%`, `%abc`, `%abc%`, and `abc` skip the regular
+ * expression entirely — prefix/suffix/containment string scans are several times faster and
+ * dominate real workloads — and everything else falls back to the anchored RegExp.
+ */
+export declare function likeMatches(pattern: string, value: string, caseInsensitive?: boolean, escape?: string): boolean;
+/** Splits a quantified operator like "> ANY" into its comparison and quantifier. */
+export declare function parseQuantified(operator: PredicateOperator): {
+    comparison: ComparisonOperator;
+    quantifier: "any" | "all";
+} | undefined;
+/**
+ * SQL quantified comparison over a resolved value list, with three-valued logic: an empty list
+ * is false for ANY and true for ALL before any comparison happens; otherwise NULL operands make
+ * the result unknown unless a definite answer exists.
+ */
+export declare function quantifiedComparison(comparison: ComparisonOperator, quantifier: "any" | "all", left: unknown, values: readonly unknown[]): boolean | null;
+/** Null-safe distinctness: NULL is not distinct from NULL, and distinct from every value. */
+export declare function distinctFromComparison(left: unknown, right: unknown): boolean;
+/**
+ * Evaluates a boolean expression tree with SQL three-valued logic: comparisons over NULL are
+ * unknown (null), AND/OR/NOT propagate unknown, and only the caller collapses unknown to false.
+ * Leaf values come from the executor-specific callback so both executors share these semantics.
+ */
+export declare function evaluateBooleanExpression(expression: Expression, evaluateValue: (expression: Expression) => unknown): boolean | null;
+export declare function hasAggregate(expression: Expression): boolean;
+/** The column references inside one expression; a subquery contributes none (its own scope). */
+export declare function expressionColumnNames(expression: Expression): string[];
+export declare function expressionColumns(expression: Expression): string[];
+export declare function expressionAliases(expression: Expression): Set<string>;
+/**
+ * Resolves an explicit NULLS FIRST/LAST placement for one order term. Returns undefined when
+ * no explicit placement applies (either none was requested or neither side is NULL); otherwise
+ * the signed placement, which is absolute — direction negation must not apply to it. Two NULLs
+ * return 0 so the comparison falls through to the next term.
+ */
+export declare function explicitNullOrder(left: unknown, right: unknown, nulls: "first" | "last" | undefined): number | undefined;
+export interface SelectBlockParts {
+    sql: string;
+    base: TableSource;
+    joins: JoinPlan[];
+    select: SelectItem[];
+    distinct: boolean;
+    predicates: Predicate[];
+    /** Raw GROUP BY expressions; DISTINCT desugaring appends to a copy here. */
+    groupBy: Expression[];
+    having: Predicate[];
+    orderBy: CompiledQuery["orderBy"];
+    limit?: number;
+    offset?: number;
+    limitParameter?: number;
+    offsetParameter?: number;
+    limitWithTies?: boolean;
+    /** GROUP BY GROUPING SETS/ROLLUP/CUBE: the grouping lists to union; groupBy is then unused. */
+    groupingSets?: Expression[][];
+}
+export declare function assembleSelectBlock(parts: SelectBlockParts, nextSequence: () => number): CompiledQuery;
+/**
+ * Expands a pending SELECT DISTINCT * against known input columns: the select list becomes
+ * every wildcard output (alias-qualified when more than one source contributes), and GROUP BY
+ * over those same columns provides the deduplication through the grouped executor. Runs
+ * exactly once per execution entry, like MATCH(*) expansion.
+ */
+export declare function expandDistinctWildcard(plan: CompiledQuery, columnsOf: (tableName: string) => readonly string[] | undefined): CompiledQuery;
+/**
+ * Turns every source carrying a column alias list into a derived projection that renames the
+ * table's columns positionally (E051-09). The table's own column order is only known here, so
+ * the parser records the names and this pass — one per execution entry — applies them.
+ */
+/** Whether any block of the plan reads a table name the catalog answers with a view. */
+export declare function planReadsViews(plan: CompiledQuery, isView: (name: string) => boolean): boolean;
+/**
+ * Replaces every reference to a view with the query it stands for, as a derived table under the
+ * reference's own alias (F031-02). A view whose body reads another view expands too, up to a
+ * depth that stops a cycle from recursing forever — a view cannot be defined in terms of itself,
+ * but two views can be redefined into a loop after the fact.
+ */
+export declare function expandViewSources(plan: CompiledQuery, viewFor: (tableName: string) => CompiledQuery | undefined, maxDepth?: number): CompiledQuery;
+export declare function planHasSourceColumnAliases(plan: CompiledQuery): boolean;
+/**
+ * FETCH FIRST n ROWS WITH TIES (F866). The plan runs without its limit — a limit pushed into a
+ * scan cannot know whether the next row ties — and the ordered result is trimmed here: rows up
+ * to the limit, plus every following row equal to the last one on all ORDER BY columns.
+ */
+export declare function withTiesPlan(plan: CompiledQuery): {
+    plan: CompiledQuery;
+    trim: (result: QueryResult) => QueryResult;
+};
+/** Whether any block of the plan still carries an unresolved NATURAL join marker. */
+export declare function planHasNaturalJoins(plan: CompiledQuery): boolean;
+/**
+ * Resolves NATURAL joins into ordinary equality conditions (F401-01): the join columns are the
+ * names the new source shares with the sources already joined, compared in the order they are
+ * declared. A pair with no shared column is a cross join, which is what the standard says.
+ */
+export declare function expandNaturalJoins(plan: CompiledQuery, columnsOf: (tableName: string) => readonly string[] | undefined): CompiledQuery;
+export declare function expandSourceColumnAliases(plan: CompiledQuery, columnsOf: (tableName: string) => readonly string[] | undefined): CompiledQuery;
+/**
+ * Expands `alias.*` select items into that source's columns (E051-07), at every nesting depth.
+ * Output names follow the same rule as a bare `*`: the column's own name when the block reads
+ * one source, and `alias.column` when it reads several, so two sources cannot collide.
+ * Runs once per execution entry, like MATCH(*) and DISTINCT * expansion.
+ */
+export declare function expandQualifiedWildcards(plan: CompiledQuery, columnsOf: (tableName: string) => readonly string[] | undefined): CompiledQuery;
+/** Wraps compound members into the set-operation source the executor folds left to right. */
+export declare function compoundSelectBlock(sql: string, blocks: CompiledQuery[], ops: SetOperator[], tail: SelectTail, nextSequence: () => number): CompiledQuery;
+/**
+ * Detects a pure projection wrapper over one derived block — the shape the ORDER-BY-expression
+ * desugar emits: no joins, filters, grouping, ordering, or paging of its own, and every select
+ * item passing an inner output alias through under the same name. Whole-plan strategies (the
+ * streamed scan today) run the inner block and project its result, so a hidden ordering column
+ * never changes which execution paths a query is eligible for — `.search()` performs the same
+ * whether or not the caller also selects the score.
+ */
+export declare function transparentProjectionSource(plan: CompiledQuery): {
+    inner: CompiledQuery;
+    aliases: string[];
+} | undefined;
+/** Projects a result to a wrapper's visible aliases, preserving row order. */
+export declare function projectResultColumns(result: QueryResult, aliases: readonly string[]): QueryResult;
+/** Names a derived (subquery or expanded CTE) source under the shared sequence. */
+export declare function derivedTableSource(derived: CompiledQuery, alias: string, nextSequence: () => number): TableSource;
+/** The parser's LIMIT range contract, shared with the typed builder. */
+export declare function validateLimit(limit: number): number;
+/**
+ * `TIMESTAMP '2026-01-02 03:04:05'` — the standard's spelling, which writes a space where ISO
+ * writes a T and leaves the time off entirely for midnight. A literal without a zone is UTC, the
+ * same reading `DATE` already takes and the same one every datetime in a Minnow database has.
+ */
+export declare function timestampLiteral(text: string): Date;
+/** The parser's OFFSET range contract, shared with the typed builder. */
+export declare function validateOffset(offset: number): number;
+/**
+ * Splits a parsed boolean expression into the plan's AND-list of predicates. Top-level ANDs and
+ * plain comparisons keep the classic {left, operator, right} shape (so predicate pushdown, zone
+ * maps, and the dictionary fast path see exactly what they always saw); any OR/NOT subtree or bare
+ * boolean expression becomes a single IS TRUE predicate evaluated with three-valued logic.
+ */
+export declare function splitCondition(expression: Expression): Predicate[];
+export {};
+//# sourceMappingURL=query.d.ts.map