@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/query.d.ts

@@ -1,8 +1,8 @@
 import type { DatabaseRow } from "./database.js";
-import type { ColumnDefault } from "../storage/types.js";
+import type { ColumnDefault, SqlDomain } 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";
+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 {
@@ -19,6 +19,7 @@ export interface PreparedQuery {
     readonly memoryUsage: QueryMemoryUsage;
     execute(): QueryResult;
     executeAsync(options?: AsyncQueryExecutionOptions): Promise<QueryResult>;
+    executeBatches(options: QueryBatchExecutionOptions, consume: (batch: QueryResult) => void | Promise<void>): Promise<readonly string[]>;
     close(): void;
 }
 export interface QueryExecutionOptions {
@@ -32,9 +33,15 @@ export interface QueryExecutionOptions {
 }
 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 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>;
 /**
  * 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
@@ -70,6 +77,8 @@ export declare function dateTruncValue(unit: unknown, value: unknown): Date | nu
 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. */
  | {
@@ -97,6 +106,11 @@ export type Expression = {
     name: AggregateName | ScalarFunctionName;
     arguments: Expression[];
     distinct?: boolean;
+    aggregateOrderBy?: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
 } | {
     kind: "list";
     items: Expression[];
@@ -198,6 +212,8 @@ export interface WindowSpec {
 }
 /** 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;
@@ -224,9 +240,11 @@ export interface TableSource {
      * 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";
+    kind: "inner" | "left" | "semi" | "anti";
     left: Expression;
     right: Expression;
     /** General ON condition for non-equi or multi-key joins; left/right are inert placeholders. */
@@ -252,7 +270,7 @@ export interface RecursiveCte {
     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 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;
@@ -272,8 +290,8 @@ export interface CompiledQuery {
         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).
+         * Explicit NULL placement, absolute regardless of direction. Absent keeps PostgreSQL's
+         * default: NULLS LAST for ASC and NULLS FIRST for DESC.
          */
         nulls?: "first" | "last";
     }>;
@@ -305,6 +323,10 @@ export interface CompiledQuery {
      * 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 {
@@ -360,14 +382,24 @@ export type MergeBranch = {
 export interface ForeignKeyDefinition {
     name: string;
     column: string;
+    columns?: string[];
     parentTable: string;
     parentColumn?: string;
+    parentColumns?: string[];
     onDelete: "restrict" | "cascade" | "set null";
 }
-/** An INSERT value: a constant, or an unbound `?`/`$n` placeholder awaiting its parameter. */
-export type InsertValue = QueryValue | {
+export interface UniqueConstraintDefinition {
+    name: string;
+    columns: string[];
+}
+/** An INSERT value: a constant, SQL DEFAULT, or an unbound placeholder. */
+export interface DefaultInsertValue {
+    readonly default: true;
+}
+export type InsertValue = QueryValue | DefaultInsertValue | {
     parameter: number;
 };
+export declare function isDefaultInsertValue(value: InsertValue): value is DefaultInsertValue;
 export type CompiledStatement = {
     kind: "select";
     sql: string;
@@ -377,6 +409,8 @@ export type CompiledStatement = {
     table: string;
     columns: string[];
     rows: InsertValue[][];
+    /** PostgreSQL's one-row `DEFAULT VALUES` form; execution expands it to omitted columns. */
+    defaultValues?: true;
     /** INSERT ... SELECT source; `rows` is then empty and fills at execution. */
     query?: CompiledQuery;
     /**
@@ -386,9 +420,16 @@ export type CompiledStatement = {
      */
     onConflict?: {
         column: string;
-        action: "nothing" | "replace" | "update";
-        /** The EXCLUDED columns a partial DO UPDATE merges; present only for "update". */
+        /** The full PostgreSQL conflict target; `column` remains the scalar fast-path name. */
         columns?: string[];
+        action: "nothing" | "replace" | "update";
+        /** Expressions evaluated against the stored target row and the proposed EXCLUDED row. */
+        assignments?: Array<{
+            column: string;
+            expression: Expression;
+        }>;
+        /** PostgreSQL's post-conflict filter: false or unknown leaves the stored row untouched. */
+        where?: Expression;
     };
     returning?: string[] | "*";
     parameterCount?: number;
@@ -422,8 +463,12 @@ export type CompiledStatement = {
     columns: Array<{
         name: string;
         type: SqlColumnType;
+        integer?: true;
+        sqlDomain?: SqlDomain;
         nullable?: boolean;
         defaultValue?: ColumnDefault;
+        enumValues?: readonly string[];
+        backfill?: Exclude<QueryValue, null>;
     }>;
     checks?: Array<{
         name: string;
@@ -431,8 +476,37 @@ export type CompiledStatement = {
     }>;
     foreignKeys?: ForeignKeyDefinition[];
     uniqueKey?: string;
+    compositePrimaryKey?: string[];
+    uniqueConstraints?: UniqueConstraintDefinition[];
     /** CREATE TABLE IF NOT EXISTS: an existing table of that name is left alone. */
     ifNotExists?: boolean;
+    /** Schema-owned objects carry this bit atomically with creation. */
+    managed?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "create-enum";
+    name: string;
+    values: string[];
+    parameterCount?: number;
+} | {
+    kind: "create-sequence";
+    name: string;
+    parameterCount?: number;
+} | {
+    kind: "create-index";
+    index: string;
+    table: string;
+    columns: Array<{
+        name: string;
+        direction: "asc" | "desc";
+    }>;
+    unique?: true;
+    ifNotExists?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "drop-index";
+    index: string;
+    ifExists?: boolean;
     parameterCount?: number;
 } | {
     kind: "create-trigger";
@@ -471,6 +545,8 @@ export type CompiledStatement = {
     view: string;
     sql: string;
     orReplace?: boolean;
+    /** Schema-owned objects carry this bit atomically with creation. */
+    managed?: boolean;
     parameterCount?: number;
 } | {
     kind: "drop-view";
@@ -479,7 +555,8 @@ export type CompiledStatement = {
     parameterCount?: number;
 } | {
     kind: "transaction";
-    action: "begin" | "commit" | "rollback";
+    action: "begin" | "commit" | "rollback" | "savepoint" | "rollback-to" | "release";
+    name?: string;
     parameterCount?: number;
 } | {
     kind: "merge";
@@ -510,9 +587,21 @@ export type CompiledStatement = {
     column: {
         name: string;
         type: SqlColumnType;
+        integer?: true;
+        sqlDomain?: SqlDomain;
         nullable?: boolean;
         defaultValue?: ColumnDefault;
+        enumValues?: readonly string[];
+        backfill?: Exclude<QueryValue, null>;
     };
+    /** Schema migrations may add a proven non-null column by supplying a backfill. */
+    allowNonNullableWithBackfill?: boolean;
+    parameterCount?: number;
+} | {
+    kind: "drop-column";
+    table: string;
+    column: string;
+    ifExists?: true;
     parameterCount?: number;
 };
 /**
@@ -521,6 +610,17 @@ export type CompiledStatement = {
  * row condition over this table's columns, with no aggregate, window, subquery, or parameter.
  */
 export declare function compileCheckExpression(sql: string, name: string): Expression;
+export interface DefaultExpressionTarget {
+    readonly name: string;
+    readonly type: SqlColumnType;
+    readonly sqlDomain?: SqlDomain;
+}
+/**
+ * Parses and type-checks one catalog default. PostgreSQL defaults are variable-free scalar
+ * expressions: functions and operators are allowed, while row references, parameters,
+ * aggregates, windows, and subqueries are not.
+ */
+export declare function validateDefaultExpression(sql: string, target: DefaultExpressionTarget): void;
 /**
  * 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
@@ -576,6 +676,10 @@ export type SqlColumnType = "boolean" | "number" | "string" | "datetime";
 export interface SqlColumnSchema {
     name: string;
     type: SqlColumnType;
+    /** Exact SQL whole-number domain, physically stored as a safe JavaScript number. */
+    integer?: true;
+    /** Logical SQL domain when the stable physical representation alone is not semantic. */
+    sqlDomain?: SqlDomain;
 }
 /**
  * Infers the typed output schema of one select block from typed source schemas. A column whose
@@ -583,11 +687,15 @@ 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[];
+/** 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?: {
     ftsStats?: ReadonlyMap<string, FtsStats>;
+    /** False only when catalog-backed schema inference proves every output is already public. */
+    outputNeedsExternalization?: boolean;
 }): PreparedQuery;
 export declare function executeQuery(plan: CompiledQuery, tables: ReadonlyMap<string, DatabaseRow[]>, options?: QueryExecutionOptions): QueryResult;
 /**
@@ -711,12 +819,9 @@ export interface ListMembership {
 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.
+ * Shared bounded LIKE matcher. Compilation and the common literal prefix/suffix/containment
+ * fast paths are cached in sql-semantics; complex wildcard shapes have deterministic work caps.
  */
 export declare function likeMatches(pattern: string, value: string, caseInsensitive?: boolean, escape?: string): boolean;
 /** Splits a quantified operator like "> ANY" into its comparison and quantifier. */
@@ -744,12 +849,16 @@ 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.
+ * Resolves NULL placement for one order term. An omitted placement follows PostgreSQL: NULLS LAST
+ * for ASC and NULLS FIRST for DESC. Returns undefined when neither side is NULL; otherwise the
+ * signed placement is absolute, so direction negation must not apply to it. Two NULLs return 0
+ * so comparison falls through to the next term.
  */
-export declare function explicitNullOrder(left: unknown, right: unknown, nulls: "first" | "last" | undefined): number | undefined;
+export declare function nullOrder(left: unknown, right: unknown, nulls: "first" | "last" | undefined, direction: "asc" | "desc"): number | undefined;
+/** Carries the internal no-conversion proof across a defensive result copy. */
+export declare function copyQueryResultExternalization(source: QueryResult, copy: QueryResult): QueryResult;
+/** Removes internal domain tags only after every comparison, group, join, and sort is complete. */
+export declare function externalizeQueryResult(result: QueryResult): QueryResult;
 export interface SelectBlockParts {
     sql: string;
     base: TableSource;
@@ -782,6 +891,8 @@ export declare function expandDistinctWildcard(plan: CompiledQuery, columnsOf: (
  * 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 accepted by the supplied catalog predicate. */
+export declare function planReadsTable(plan: CompiledQuery, matches: (name: string) => boolean): boolean;
 /** 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;
 /**
@@ -837,11 +948,6 @@ export declare function projectResultColumns(result: QueryResult, aliases: reado
 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;
@@ -853,4 +959,3 @@ export declare function validateOffset(offset: number): number;
  */
 export declare function splitCondition(expression: Expression): Predicate[];
 export {};
-//# sourceMappingURL=query.d.ts.map