@minnowdb/core 0.4.1 → 0.6.0

package/dist/engine/query-cache.js

@@ -38,6 +38,7 @@ export function copyQueryResult(result) {
     const columns = result.columns;
     const copy = {
         columns: [...columns],
+        columnDomains: structuredClone(result.columnDomains),
         rows: result.rows.map((row) => {
             const copy = { ...row };
             for (const name of columns) {

package/dist/engine/query.d.ts

@@ -1,14 +1,11 @@
 import type { DatabaseRow } from "./database.js";
-import type { ColumnDefault, SqlDomain } from "../storage/types.js";
-import { type FtsStats } from "./fts.js";
+import type { ColumnDefault, ColumnGenerated, SqlDomain } from "../storage/types.js";
+import type { AggregateName, ComparisonOperator, CompiledQuery, Expression, FtsStats, JoinPlan, Predicate, PredicateOperator, QueryResult, QueryRow, QueryValue, ScalarFunctionName, SelectItem, SelectTail, SetOperator, TableSource, WindowSpec } from "../plan/model.js";
+export type { AggregateName, BinaryOperator, ComparisonOperator, CompiledQuery, Expression, JoinPlan, Predicate, PredicateOperator, QueryResult, QueryRow, QueryValue, RecursiveCte, ScalarFunctionName, SelectItem, SelectTail, SetOperator, TableSource, WindowFrame, WindowFrameBound, WindowFrameExclusion, WindowFunctionName, WindowSpec, } from "../plan/model.js";
 import { QueryMemoryContext, type QueryMemoryUsage } from "./memory.js";
 import { type ColumnarTable, type AsyncQueryExecutionOptions, type QueryBatchExecutionOptions } from "./vector.js";
-export type QueryValue = boolean | number | string | Date | null;
-export type QueryRow = Record<string, QueryValue>;
-export interface QueryResult {
-    columns: string[];
-    rows: QueryRow[];
-}
+/** Domain metadata for an execution path that has no catalog-backed type information. */
+export declare function unknownColumnDomains(columns: readonly string[]): null[];
 export interface PreparedQuery {
     readonly sql: string;
     readonly tables: string[];
@@ -31,14 +28,6 @@ export interface QueryExecutionOptions {
      */
     readonly executionMemoryBudgetBytes?: number;
 }
-export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "||";
-export type ComparisonOperator = "=" | "!=" | "<>" | ">" | ">=" | "<" | "<=";
-export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX" | "JSON_ARRAYAGG" | "STRING_AGG";
-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" | "ARRAY"
-/** Optimizer-only, prefix-free equality key for hashable multi-column decorrelation. */
- | "MINNOW_TUPLE_KEY"
-/** Parser-produced wrapper carrying one explicit collation through ordering/comparison. */
- | "MINNOW_COLLATE" | "NEXTVAL" | "CURRVAL" | "RANDOM" | "GEN_RANDOM_UUID";
 export declare const scalarFunctionNames: ReadonlySet<string>;
 /** Functions whose answer can change without any catalog or input-row change. */
 export declare const volatileScalarFunctionNames: ReadonlySet<string>;
@@ -72,271 +61,12 @@ export declare function intervalLiteral(text: string): {
  * 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 dateAddValue(value: unknown, months: unknown, milliseconds: unknown): Date | string | null;
 export declare function dateTruncValue(unit: unknown, value: unknown): Date | null;
-export type Expression = {
-    kind: "literal";
-    value: QueryValue;
-    internalSqlValue?: true;
-    sqlDomain?: SqlDomain;
-}
-/** 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;
-    aggregateOrderBy?: Array<{
-        expression: Expression;
-        direction: "asc" | "desc";
-        nulls?: "first" | "last";
-    }>;
-} | {
-    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;
-    /** Placeholder used by parameterized SQL; replaced with `query` before execution. */
-    queryParameter?: number;
-    /**
-     * 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;
 /** Logical domain carried or produced by a window result, when its physical type is not enough. */
 export declare function windowOutputDomain(window: WindowSpec, innerSchema: readonly SqlColumnSchema[]): SqlDomain | undefined;
-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[];
-    /** Parser marker for a derived source allowed to reference sources to its left. */
-    lateral?: true;
-}
-export interface JoinPlan extends TableSource {
-    kind: "inner" | "left" | "semi" | "anti";
-    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" | "SIMILAR TO" | "NOT SIMILAR TO" | "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 PostgreSQL's
-         * default: NULLS LAST for ASC and NULLS FIRST for DESC.
-         */
-        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;
-    /** NEXTVAL/CURRVAL appear in this parsed statement and need connection-local resolution. */
-    usesSequenceCalls?: boolean;
-    /** RANDOM/GEN_RANDOM_UUID appear and make result memoization unsafe. */
-    usesVolatileFunctions?: 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
@@ -387,6 +117,8 @@ export interface ForeignKeyDefinition {
     parentColumn?: string;
     parentColumns?: string[];
     onDelete: "restrict" | "cascade" | "set null";
+    /** False is reserved for schema/catalog declarations; SQL-created keys are enforced. */
+    enforced?: boolean;
 }
 export interface UniqueConstraintDefinition {
     name: string;
@@ -467,6 +199,7 @@ export type CompiledStatement = {
         sqlDomain?: SqlDomain;
         nullable?: boolean;
         defaultValue?: ColumnDefault;
+        generatedValue?: ColumnGenerated;
         enumValues?: readonly string[];
         backfill?: Exclude<QueryValue, null>;
     }>;
@@ -591,6 +324,7 @@ export type CompiledStatement = {
         sqlDomain?: SqlDomain;
         nullable?: boolean;
         defaultValue?: ColumnDefault;
+        generatedValue?: ColumnGenerated;
         enumValues?: readonly string[];
         backfill?: Exclude<QueryValue, null>;
     };
@@ -687,15 +421,19 @@ export interface SqlColumnSchema {
  * 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[];
+/** Best-effort logical domains for a public result without making execution a new typecheck. */
+export declare function inferResultColumnDomains(plan: CompiledQuery, schemas: ReadonlyMap<string, readonly SqlColumnSchema[]>): Array<SqlDomain | null>;
 /** Whether a final result can contain one of the engine's tagged string-domain values. */
 export declare function queryResultNeedsExternalization(plan: CompiledQuery, schemas: ReadonlyMap<string, readonly SqlColumnSchema[]>): boolean;
 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?: {
+export declare function createPreparedColumnarQuery(plan: CompiledQuery, tables: ReadonlyMap<string, ColumnarTable>, memory?: QueryMemoryContext, preparedOptions?: {
     ftsStats?: ReadonlyMap<string, FtsStats>;
     /** False only when catalog-backed schema inference proves every output is already public. */
     outputNeedsExternalization?: boolean;
+    /** Catalog-inferred logical domains, positionally aligned with the visible output. */
+    outputColumnDomains?: ReadonlyArray<SqlDomain | null>;
 }): PreparedQuery;
 export declare function executeQuery(plan: CompiledQuery, tables: ReadonlyMap<string, DatabaseRow[]>, options?: QueryExecutionOptions): QueryResult;
 /**
@@ -843,6 +581,7 @@ export declare function distinctFromComparison(left: unknown, right: unknown): b
  * 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 comparisonHolds(operator: PredicateOperator, leftValue: unknown, rightValue: unknown): boolean;
 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[];
@@ -958,4 +697,3 @@ export declare function validateOffset(offset: number): number;
  * boolean expression becomes a single IS TRUE predicate evaluated with three-valued logic.
  */
 export declare function splitCondition(expression: Expression): Predicate[];
-export {};