@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/memory.d.ts

@@ -3,6 +3,8 @@ export interface QueryMemoryUsage {
     readonly usedBytes: number;
     readonly peakBytes: number;
 }
+/** Finite default for every public engine execution path. */
+export declare const DEFAULT_QUERY_MEMORY_BUDGET_BYTES: number;
 export declare class QueryMemoryBudgetError extends Error {
     readonly label: string;
     readonly requestedBytes: number;
@@ -34,4 +36,3 @@ export declare class QueryMemoryReservation {
     constructor(context: QueryMemoryContext, bytes: number);
     release(): void;
 }
-//# sourceMappingURL=memory.d.ts.map

package/dist/engine/memory.js

@@ -1,3 +1,5 @@
+/** Finite default for every public engine execution path. */
+export const DEFAULT_QUERY_MEMORY_BUDGET_BYTES = 64 * 1024 * 1024;
 export class QueryMemoryBudgetError extends Error {
     label;
     requestedBytes;
@@ -19,7 +21,7 @@ export class QueryMemoryContext {
     #reservations = new Set();
     #talliedBytes = 0;
     #closed = false;
-    constructor(budgetBytes = Number.MAX_SAFE_INTEGER, parent) {
+    constructor(budgetBytes = DEFAULT_QUERY_MEMORY_BUDGET_BYTES, parent) {
         if (!Number.isSafeInteger(budgetBytes) || budgetBytes < 0) {
             throw new RangeError("Query memory budget must be a non-negative safe integer");
         }
@@ -116,4 +118,3 @@ function validateMemoryBytes(bytes, label) {
         throw new RangeError(`${label} must be a non-negative safe integer`);
     }
 }
-//# sourceMappingURL=memory.js.map

package/dist/engine/optimizer.d.ts

@@ -17,4 +17,3 @@ export declare function chooseJoinOrder(plan: CompiledQuery, inputs: ReadonlyMap
 }>): CompiledQuery;
 /** Renders a stable, human-readable plan for snapshot tests and explain(). */
 export declare function renderPlan(plan: CompiledQuery): string;
-//# sourceMappingURL=optimizer.d.ts.map

package/dist/engine/optimizer.js

@@ -1,4 +1,6 @@
-import { childExpressions, expressionAliases, forEachBlockExpression, forEachNestedBlock, isScalarFunctionName, scalarFunctionNames, scalarFunctionValue, splitCondition, } from "./query.js";
+import { dateIsoString, dateMilliseconds } from "../date-value.js";
+import { childExpressions, expressionAliases, forEachBlockExpression, forEachNestedBlock, isScalarFunctionName, scalarFunctionNames, scalarFunctionValue, splitCondition, volatileScalarFunctionNames, } from "./query.js";
+import { isSqlDomainValue } from "./sql-domains.js";
 /**
  * Deterministic plan-to-plan rewrites over the shared compiled representation. Every rule
  * preserves result semantics exactly; rules that cannot prove safety leave the plan unchanged.
@@ -37,6 +39,7 @@ export function chooseJoinOrder(plan, inputs) {
     };
 }
 function optimizeBlock(block) {
+    decorrelateLateralSources(block);
     decorrelateBlock(block);
     for (const source of [block.base, ...block.joins]) {
         if (source.derived !== undefined)
@@ -57,6 +60,79 @@ function optimizeBlock(block) {
     pruneDerivedProjections(block);
     combineDerivedLimit(block);
 }
+/** Converts equality-correlated LATERAL derived tables into ordinary set-at-a-time joins. */
+function decorrelateLateralSources(block) {
+    if (block.base.lateral === true) {
+        throw new TypeError("LATERAL needs a source to its left");
+    }
+    const available = new Set([block.base.alias]);
+    for (const join of block.joins) {
+        if (join.lateral !== true) {
+            available.add(join.alias);
+            continue;
+        }
+        delete join.lateral;
+        const inner = join.derived;
+        if (inner === undefined)
+            throw new TypeError("LATERAL requires a derived query");
+        if (!blockReferencesOutside(inner)) {
+            available.add(join.alias);
+            continue;
+        }
+        if (inner.groupBy.length > 0 ||
+            inner.having.length > 0 ||
+            inner.orderBy.length > 0 ||
+            inner.limit !== undefined) {
+            throw new TypeError("Correlated LATERAL queries cannot use grouping, HAVING, ORDER BY, or LIMIT");
+        }
+        const keys = extractCorrelation(inner, available, "LATERAL");
+        const keyAliases = keys.map((_, index) => `\u0000lateral_key_${String(index + 1)}`);
+        keys.forEach((key, index) => {
+            inner.select.push({ expression: key.inner, alias: keyAliases[index] ?? "" });
+        });
+        const correlations = keys.map((key, index) => ({
+            kind: "condition",
+            operator: key.operator,
+            left: key.outer,
+            right: { kind: "column", reference: `${join.alias}.${keyAliases[index] ?? ""}` },
+        }));
+        const cross = join.on?.kind === "condition" &&
+            join.on.operator === "=" &&
+            join.on.left.kind === "literal" &&
+            join.on.left.value === 1 &&
+            join.on.right.kind === "literal" &&
+            join.on.right.value === 1;
+        const original = cross
+            ? undefined
+            : (join.on ?? {
+                kind: "condition",
+                operator: "=",
+                left: join.left,
+                right: join.right,
+            });
+        const conditions = [...correlations, ...(original === undefined ? [] : [original])];
+        const first = conditions[0];
+        if (conditions.length === 1 && first?.kind === "condition" && first.operator === "=") {
+            join.left = first.left;
+            join.right = first.right;
+            delete join.on;
+        }
+        else {
+            join.left = { kind: "literal", value: null };
+            join.right = { kind: "literal", value: null };
+            const seed = conditions[0];
+            if (seed === undefined)
+                throw new Error("LATERAL correlation condition is missing");
+            join.on = conditions.slice(1).reduce((combined, condition) => ({
+                kind: "logical",
+                operator: "and",
+                left: combined,
+                right: condition,
+            }), seed);
+        }
+        available.add(join.alias);
+    }
+}
 // --- Join key extraction ---------------------------------------------------------------------
 /**
  * Pulls a hash key out of a conjunctive ON clause.
@@ -391,7 +467,7 @@ function decorrelatePredicate(block, predicate, scope, nextAlias) {
             return undefined;
         rejectGroupedInner(inner, "EXISTS");
         guardWildcard(block);
-        const keys = extractCorrelation(inner, scope, "EXISTS");
+        const keys = extractCorrelation(inner, scope, "EXISTS", true);
         const alias = nextAlias();
         const derived = {
             sql: "(correlated exists)",
@@ -405,7 +481,10 @@ function decorrelatePredicate(block, predicate, scope, nextAlias) {
             having: [],
             orderBy: [],
         };
-        pushCorrelationJoin(block, alias, derived, keys, negated ? "left" : "inner");
+        const general = keys.some((key) => key.operator !== "=");
+        pushCorrelationJoin(block, alias, derived, keys, general ? (negated ? "anti" : "semi") : negated ? "left" : "inner");
+        if (general)
+            return "consumed";
         if (!negated)
             return "consumed";
         return {
@@ -414,15 +493,12 @@ function decorrelatePredicate(block, predicate, scope, nextAlias) {
             right: { kind: "literal", value: null },
         };
     }
-    // outer IN (correlated subquery)
+    // outer IN / NOT IN (correlated subquery)
     if ((predicate.operator === "IN" || predicate.operator === "NOT IN") &&
         predicate.right.kind === "subquery") {
         const inner = predicate.right.block;
         if (!blockReferencesOutside(inner))
             return undefined;
-        if (predicate.operator === "NOT IN") {
-            throw new TypeError("Correlated NOT IN subqueries are not supported; use NOT EXISTS");
-        }
         rejectGroupedInner(inner, "IN");
         const item = inner.select[0];
         if (inner.select.length !== 1 || item === undefined || item.expression.kind === "wildcard") {
@@ -430,6 +506,9 @@ function decorrelatePredicate(block, predicate, scope, nextAlias) {
         }
         guardWildcard(block);
         const keys = extractCorrelation(inner, scope, "IN");
+        if (predicate.operator === "NOT IN") {
+            return decorrelateNotIn(block, predicate.left, inner, item.expression, keys, nextAlias);
+        }
         const alias = nextAlias();
         const derived = {
             sql: "(correlated in)",
@@ -469,6 +548,106 @@ function decorrelatePredicate(block, predicate, scope, nextAlias) {
         ? { left: value, operator: predicate.operator, right: predicate.right }
         : { left: predicate.left, operator: predicate.operator, right: value };
 }
+/**
+ * Rewrites `probe NOT IN (correlated values)` without losing SQL's empty-set and NULL rules.
+ *
+ * One hash anti-join removes exact matches using a prefix-free composite key containing every
+ * correlation key plus the compared value. A grouped left join then carries two counts for the
+ * correlated set: total rows and non-null values. An absent group means the set is empty (true,
+ * even for a NULL probe); otherwise the probe must be non-null and the two counts equal. The two
+ * derived scans are bounded set-at-a-time work—no per-outer-row subquery or nested-loop join.
+ */
+function decorrelateNotIn(block, probe, inner, item, keys, nextAlias) {
+    const valuesAlias = nextAlias();
+    const values = {
+        sql: "(correlated not in values)",
+        base: structuredClone(inner.base),
+        joins: structuredClone(inner.joins),
+        select: [
+            ...keys.map((key, index) => ({
+                expression: structuredClone(key.inner),
+                alias: `k${String(index)}`,
+            })),
+            { expression: structuredClone(item), alias: "v" },
+        ],
+        predicates: structuredClone(inner.predicates),
+        groupBy: [...keys.map((key) => structuredClone(key.inner)), structuredClone(item)],
+        having: [],
+        orderBy: [],
+    };
+    const tuple = (arguments_) => ({
+        kind: "call",
+        name: "MINNOW_TUPLE_KEY",
+        arguments: arguments_,
+    });
+    block.joins.push({
+        table: valuesAlias,
+        alias: valuesAlias,
+        derived: values,
+        kind: "anti",
+        left: tuple([...keys.map((key) => structuredClone(key.outer)), structuredClone(probe)]),
+        right: tuple([
+            ...keys.map((_, index) => ({
+                kind: "column",
+                reference: `${valuesAlias}.k${String(index)}`,
+            })),
+            { kind: "column", reference: `${valuesAlias}.v` },
+        ]),
+    });
+    const flagsAlias = nextAlias();
+    const flags = {
+        sql: "(correlated not in flags)",
+        base: structuredClone(inner.base),
+        joins: structuredClone(inner.joins),
+        select: [
+            ...keys.map((key, index) => ({
+                expression: structuredClone(key.inner),
+                alias: `k${String(index)}`,
+            })),
+            {
+                expression: { kind: "call", name: "COUNT", arguments: [{ kind: "wildcard" }] },
+                alias: "n",
+            },
+            {
+                expression: { kind: "call", name: "COUNT", arguments: [structuredClone(item)] },
+                alias: "nn",
+            },
+        ],
+        predicates: structuredClone(inner.predicates),
+        groupBy: keys.map((key) => structuredClone(key.inner)),
+        having: [],
+        orderBy: [],
+    };
+    pushCorrelationJoin(block, flagsAlias, flags, keys, "left");
+    const total = { kind: "column", reference: `${flagsAlias}.n` };
+    const nonNull = { kind: "column", reference: `${flagsAlias}.nn` };
+    const safe = {
+        kind: "logical",
+        operator: "or",
+        left: {
+            kind: "condition",
+            operator: "IS NULL",
+            left: total,
+            right: { kind: "literal", value: null },
+        },
+        right: {
+            kind: "logical",
+            operator: "and",
+            left: {
+                kind: "condition",
+                operator: "IS NOT NULL",
+                left: structuredClone(probe),
+                right: { kind: "literal", value: null },
+            },
+            right: { kind: "condition", operator: "=", left: total, right: nonNull },
+        },
+    };
+    return {
+        left: safe,
+        operator: "IS TRUE",
+        right: { kind: "literal", value: true },
+    };
+}
 /**
  * Rewrites one correlated scalar-aggregate subquery into a left join against the grouped
  * aggregate, returning the expression that replaces the subquery node (COUNT wraps in COALESCE
@@ -518,20 +697,22 @@ function pushCorrelationJoin(block, alias, derived, keys, kind) {
         reference: `${alias}.k${String(index)}`,
     });
     const first = keys[0];
-    if (keys.length === 1 && first !== undefined) {
+    if (keys.length === 1 && first?.operator === "=") {
         block.joins.push({ ...source, kind, left: first.outer, right: keyReference(0) });
         return;
     }
     let on;
     keys.forEach((key, index) => {
-        const equality = {
+        const comparison = {
             kind: "condition",
-            operator: "=",
-            left: key.outer,
-            right: keyReference(index),
+            operator: key.operator,
+            left: keyReference(index),
+            right: key.outer,
         };
         on =
-            on === undefined ? equality : { kind: "logical", operator: "and", left: on, right: equality };
+            on === undefined
+                ? comparison
+                : { kind: "logical", operator: "and", left: on, right: comparison };
     });
     block.joins.push({
         ...source,
@@ -570,12 +751,12 @@ function collectOutsideReferences(block, outer, refs) {
         collectOutsideReferences(nested, scope, refs);
     });
 }
-function extractCorrelation(inner, outerScope, label) {
+function extractCorrelation(inner, outerScope, label, comparisons = false) {
     const innerScope = new Set([inner.base.alias, ...inner.joins.map((join) => join.alias)]);
     const keys = [];
     const kept = [];
     for (const predicate of inner.predicates) {
-        const key = correlationEquality(predicate, innerScope, outerScope);
+        const key = correlationComparison(predicate, innerScope, outerScope, comparisons);
         if (key === undefined)
             kept.push(predicate);
         else
@@ -592,9 +773,12 @@ function extractCorrelation(inner, outerScope, label) {
     }
     return keys;
 }
-function correlationEquality(predicate, innerScope, outerScope) {
-    if (predicate.operator !== "=")
+function correlationComparison(predicate, innerScope, outerScope, comparisons) {
+    if (predicate.operator !== "=" &&
+        (!comparisons || !comparisonOperators.has(predicate.operator))) {
         return undefined;
+    }
+    const operator = predicate.operator;
     const { left, right } = predicate;
     if (left.kind !== "column" || right.kind !== "column")
         return undefined;
@@ -613,11 +797,26 @@ function correlationEquality(predicate, innerScope, outerScope) {
     const leftSide = sideOf(left.reference);
     const rightSide = sideOf(right.reference);
     if (leftSide === "inner" && rightSide === "outer")
-        return { inner: left, outer: right };
-    if (leftSide === "outer" && rightSide === "inner")
-        return { inner: right, outer: left };
+        return { inner: left, outer: right, operator };
+    if (leftSide === "outer" && rightSide === "inner") {
+        return { inner: right, outer: left, operator: reverseComparison(operator) };
+    }
     return undefined;
 }
+function reverseComparison(operator) {
+    switch (operator) {
+        case ">":
+            return "<";
+        case ">=":
+            return "<=";
+        case "<":
+            return ">";
+        case "<=":
+            return ">=";
+        default:
+            return operator;
+    }
+}
 function rejectGroupedInner(inner, label) {
     if (inner.groupBy.length > 0 || inner.having.length > 0) {
         throw new TypeError(`Correlated ${label} subqueries cannot use GROUP BY or HAVING`);
@@ -661,8 +860,17 @@ function foldExpression(expression) {
         const right = foldExpression(expression.right);
         if (left.kind === "literal" && right.kind === "literal") {
             const folded = foldBinary(expression.operator, left.value, right.value);
-            if (folded !== undefined)
-                return { kind: "literal", value: folded };
+            if (folded !== undefined) {
+                const domain = left.sqlDomain?.kind === "numeric" || right.sqlDomain?.kind === "numeric"
+                    ? { kind: "numeric" }
+                    : undefined;
+                return {
+                    kind: "literal",
+                    value: folded,
+                    ...(isSqlDomainValue(folded) ? { internalSqlValue: true } : {}),
+                    ...(domain === undefined ? {} : { sqlDomain: domain }),
+                };
+            }
         }
         return { ...expression, left, right };
     }
@@ -670,6 +878,7 @@ function foldExpression(expression) {
         const foldedArguments = expression.arguments.map(foldExpression);
         const literalValues = foldedArguments.flatMap((argument) => argument.kind === "literal" ? [argument.value] : []);
         if (expression.name !== "COALESCE" &&
+            !volatileScalarFunctionNames.has(expression.name) &&
             isScalarFunctionName(expression.name) &&
             literalValues.length === foldedArguments.length) {
             try {
@@ -679,7 +888,34 @@ function foldExpression(expression) {
                     typeof folded === "boolean" ||
                     folded instanceof Date ||
                     (typeof folded === "number" && Number.isFinite(folded))) {
-                    return { kind: "literal", value: folded };
+                    const target = foldedArguments[1];
+                    const targetWord = expression.name === "CAST" &&
+                        target?.kind === "literal" &&
+                        typeof target.value === "string"
+                        ? target.value
+                        : undefined;
+                    const sqlDomain = targetWord?.startsWith("numeric:") === true
+                        ? (() => {
+                            const [, precisionWord = "", scaleWord = ""] = targetWord.split(":");
+                            return {
+                                kind: "numeric",
+                                ...(precisionWord === "" ? {} : { precision: Number(precisionWord) }),
+                                ...(scaleWord === "" ? {} : { scale: Number(scaleWord) }),
+                            };
+                        })()
+                        : targetWord === "json" ||
+                            targetWord === "jsonb" ||
+                            targetWord === "uuid" ||
+                            targetWord === "time" ||
+                            targetWord === "interval"
+                            ? { kind: targetWord }
+                            : undefined;
+                    return {
+                        kind: "literal",
+                        value: folded,
+                        ...(isSqlDomainValue(folded) ? { internalSqlValue: true } : {}),
+                        ...(sqlDomain === undefined ? {} : { sqlDomain }),
+                    };
                 }
             }
             catch {
@@ -741,8 +977,8 @@ function foldBinary(operator, leftValue, rightValue) {
         return undefined;
     if (typeof leftValue === "string" || typeof rightValue === "string")
         return undefined;
-    const left = leftValue instanceof Date ? leftValue.getTime() : leftValue;
-    const right = rightValue instanceof Date ? rightValue.getTime() : rightValue;
+    const left = leftValue instanceof Date ? dateMilliseconds(leftValue) : leftValue;
+    const right = rightValue instanceof Date ? dateMilliseconds(rightValue) : rightValue;
     if ((operator === "/" || operator === "%") && right === 0)
         return null;
     const result = operator === "+"
@@ -1125,7 +1361,7 @@ function renderExpression(expression) {
         if (value === null)
             return "null";
         if (value instanceof Date)
-            return `date ${value.toISOString()}`;
+            return `date ${dateIsoString(value)}`;
         if (typeof value === "string")
             return `'${value}'`;
         return String(value);
@@ -1167,4 +1403,3 @@ function renderExpression(expression) {
     }
     return `${expression.name}(...) over (...)`;
 }
-//# sourceMappingURL=optimizer.js.map

package/dist/engine/query-api.d.ts

@@ -0,0 +1,3 @@
+/** SQL compilation, standalone execution, and plan inspection for tooling and adapters. */
+export { bindPlanParameters, bindStatementParameters, compileQuery, compileStatement, executeQuery, referencedColumns, type InsertValue, type CompiledQuery, type CompiledStatement, type QueryResult, type QueryRow, type QueryExecutionOptions, type QueryValue, type SqlColumnSchema, type SqlColumnType, } from "./query.js";
+export { optimizePlan, renderPlan } from "./optimizer.js";

package/dist/engine/query-api.js

@@ -0,0 +1,3 @@
+/** SQL compilation, standalone execution, and plan inspection for tooling and adapters. */
+export { bindPlanParameters, bindStatementParameters, compileQuery, compileStatement, executeQuery, referencedColumns, } from "./query.js";
+export { optimizePlan, renderPlan } from "./optimizer.js";

package/dist/engine/query-cache.d.ts

@@ -1,4 +1,4 @@
-import type { QueryResult } from "./query.js";
+import { type QueryResult } from "./query.js";
 /** Modest per-entry cap so one giant result cannot thrash the shared artifact cache. */
 export declare const RESULT_MEMO_MAX_BYTES: number;
 /** Stable, collision-free memo-key encoding for bound SQL parameters. */
@@ -19,4 +19,3 @@ export declare function planMemoKey(plan: unknown): string;
 export declare function copyQueryResult(result: QueryResult): QueryResult;
 /** Modeled retained payload for one cached query result. */
 export declare function queryResultRetainedBytes(result: QueryResult): number;
-//# sourceMappingURL=query-cache.d.ts.map

package/dist/engine/query-cache.js

@@ -1,3 +1,5 @@
+import { copyDate, dateMilliseconds } from "../date-value.js";
+import { copyQueryResultExternalization } from "./query.js";
 import { defineSqlResultProperty } from "./sql-semantics.js";
 /** Modest per-entry cap so one giant result cannot thrash the shared artifact cache. */
 export const RESULT_MEMO_MAX_BYTES = 4 * 1024 * 1024;
@@ -13,7 +15,7 @@ export function queryResultMemoKey(sql, params) {
 export function planMemoKey(plan) {
     return JSON.stringify(plan, (_key, value) => {
         if (value instanceof Date)
-            return { $date: value.getTime() };
+            return { $date: dateMilliseconds(value) };
         if (typeof value === "bigint")
             return { $bigint: value.toString() };
         if (typeof value === "number") {
@@ -34,18 +36,19 @@ export function planMemoKey(plan) {
  */
 export function copyQueryResult(result) {
     const columns = result.columns;
-    return {
+    const copy = {
         columns: [...columns],
         rows: result.rows.map((row) => {
             const copy = { ...row };
             for (const name of columns) {
                 const value = copy[name];
                 if (value instanceof Date)
-                    defineSqlResultProperty(copy, name, new Date(value.getTime()));
+                    defineSqlResultProperty(copy, name, copyDate(value));
             }
             return copy;
         }),
     };
+    return copyQueryResultExternalization(result, copy);
 }
 /** Modeled retained payload for one cached query result. */
 export function queryResultRetainedBytes(result) {
@@ -81,7 +84,6 @@ function encodeParameter(value) {
     if (typeof value === "string")
         return [3, value];
     if (value instanceof Date)
-        return [4, value.getTime()];
+        return [4, dateMilliseconds(value)];
     throw new TypeError("Query parameter has an unsupported value");
 }
-//# sourceMappingURL=query-cache.js.map