@minnowdb/core 0.6.9 → 0.7.1

package/dist/engine/point-read.d.ts

@@ -9,10 +9,11 @@ export interface PointReadShape {
     /** Conjunctive equalities, in predicate order; may repeat a column. */
     equalities: PointReadEquality[];
     /** Plain column projections, in select order. */
+    /** Projected columns, or "*" for a bare wildcard the catalog expands at execution. */
     select: Array<{
         column: string;
         alias: string;
-    }>;
+    }> | "*";
 }
 /** The statement-shaped half of the analysis, computed once per cached plan. */
 interface PointReadTemplate {
@@ -24,10 +25,11 @@ interface PointReadTemplate {
         column: string;
         parameter: number;
     }>;
+    /** Projected columns, or "*" for a bare wildcard the catalog expands at execution. */
     select: Array<{
         column: string;
         alias: string;
-    }>;
+    }> | "*";
 }
 /**
  * Test-only escape hatch and counters. Not exported from any public entry point: in-repo

package/dist/engine/point-read.js

@@ -1,190 +1,140 @@
-/**
- * Shape analysis for the keyed point-read fast path: a single-table conjunction of
- * column-equals-literal predicates that covers the table's unique key, projecting bare
- * columns — plain or logical-domain typed, since domain scalars externalize through the
- * same result boundary. Such a statement addresses at most one row, so execution can skip parameter
- * binding, plan cloning, streamed-view construction, and the vector pipeline entirely and
- * answer from cached decoded blocks. Anything this module cannot prove eligible falls back to
- * the ordinary executor, which stays the authority on errors and semantics.
- */
 import { dateMilliseconds } from "../date-value.js";
-/**
- * Test-only escape hatch and counters. Not exported from any public entry point: in-repo
- * differential suites import this module directly to force the ordinary executor and to
- * assert the fast path actually served eligible statements.
- */
-export const pointReadTestHooks = {
-    disabled: false,
-    attempted: 0,
-    served: 0,
+const pointReadTestHooks = {
+  disabled: false,
+  attempted: 0,
+  served: 0
 };
 const DUAL_TABLE = "(dual)";
-/** A base-table column reference: bare, or qualified by the base source's alias. */
 function baseColumnReference(expression, alias) {
-    if (expression.kind !== "column")
-        return undefined;
-    const reference = expression.reference;
-    const dot = reference.indexOf(".");
-    if (dot < 0)
-        return reference;
-    if (reference.slice(0, dot) !== alias)
-        return undefined;
-    const column = reference.slice(dot + 1);
-    // A nested qualifier ("a.b.c") is not a base-table column.
-    return column.includes(".") ? undefined : column;
+  if (expression.kind !== "column")
+    return void 0;
+  const reference = expression.reference;
+  const dot = reference.indexOf(".");
+  if (dot < 0)
+    return reference;
+  if (reference.slice(0, dot) !== alias)
+    return void 0;
+  const column = reference.slice(dot + 1);
+  return column.includes(".") ? void 0 : column;
 }
-/** A usable equality operand: a plain non-null literal of a storage type, verified exactly. */
 function equalityValue(value) {
-    if (value === null)
-        return undefined;
-    if (typeof value === "number" && !Number.isFinite(value))
-        return undefined;
-    // Strings in the engine's protected NUL namespace are wrapped at the write boundary, so a
-    // raw comparison against stored bytes would not reproduce the ordinary path's answer.
-    if (typeof value === "string" && value.startsWith("\u0000"))
-        return undefined;
-    // The internal-slot read never invokes caller-controlled Date methods.
-    if (value instanceof Date && Number.isNaN(dateMilliseconds(value)))
-        return undefined;
-    return value;
+  if (value === null)
+    return void 0;
+  if (typeof value === "number" && !Number.isFinite(value))
+    return void 0;
+  if (typeof value === "string" && value.startsWith("\0"))
+    return void 0;
+  if (value instanceof Date && Number.isNaN(dateMilliseconds(value)))
+    return void 0;
+  return value;
 }
 function templateEquality(expression) {
-    if (expression.kind === "parameter")
-        return { parameter: expression.index };
-    if (expression.kind !== "literal")
-        return undefined;
-    // Tagged internal values and logical-domain literals compare under domain rules the fast
-    // path does not implement; a NULL literal never equals anything.
-    if (expression.internalSqlValue === true || expression.sqlDomain !== undefined)
-        return undefined;
-    const value = equalityValue(expression.value);
-    return value === undefined ? undefined : { value };
+  if (expression.kind === "parameter")
+    return { parameter: expression.index };
+  if (expression.kind !== "literal")
+    return void 0;
+  if (expression.internalSqlValue === true || expression.sqlDomain !== void 0)
+    return void 0;
+  const value = equalityValue(expression.value);
+  return value === void 0 ? void 0 : { value };
 }
-/**
- * Recognizes the eligible statement shape. Purely syntactic: catalog checks (column existence,
- * types, key coverage, view expansion, physical history) belong to the caller, which falls
- * back to the ordinary executor whenever they cannot be proven.
- */
 function pointReadTemplate(plan) {
-    const base = plan.base;
-    if (base.table === DUAL_TABLE ||
-        base.derived !== undefined ||
-        base.union !== undefined ||
-        base.recursive !== undefined ||
-        base.windowed !== undefined ||
-        base.lateral === true ||
-        base.columnAliases !== undefined ||
-        plan.joins.length > 0 ||
-        plan.groupBy.length > 0 ||
-        plan.having.length > 0 ||
-        plan.orderBy.length > 0 ||
-        plan.select.length === 0 ||
-        plan.predicates.length === 0 ||
-        plan.limit !== undefined ||
-        plan.offset !== undefined ||
-        plan.limitParameter !== undefined ||
-        plan.offsetParameter !== undefined ||
-        (plan.limitValidationParameters?.length ?? 0) > 0 ||
-        (plan.offsetValidationParameters?.length ?? 0) > 0 ||
-        plan.limitWithTies === true ||
-        plan.distinctWildcard === true ||
-        plan.usesStatementDatetime === true ||
-        plan.usesSequenceCalls === true ||
-        plan.usesVolatileFunctions === true) {
-        return undefined;
-    }
-    const select = [];
+  const base = plan.base;
+  if (base.table === DUAL_TABLE || base.derived !== void 0 || base.union !== void 0 || base.recursive !== void 0 || base.windowed !== void 0 || base.lateral === true || base.columnAliases !== void 0 || plan.joins.length > 0 || plan.groupBy.length > 0 || plan.having.length > 0 || plan.orderBy.length > 0 || plan.select.length === 0 || plan.predicates.length === 0 || plan.limit !== void 0 || plan.offset !== void 0 || plan.limitParameter !== void 0 || plan.offsetParameter !== void 0 || (plan.limitValidationParameters?.length ?? 0) > 0 || (plan.offsetValidationParameters?.length ?? 0) > 0 || plan.limitWithTies === true || plan.distinctWildcard === true || plan.usesStatementDatetime === true || plan.usesSequenceCalls === true || plan.usesVolatileFunctions === true) {
+    return void 0;
+  }
+  let select = [];
+  const first = plan.select[0];
+  if (plan.select.length === 1 && first?.expression.kind === "wildcard" && (first.expression.table === void 0 || first.expression.table === base.alias)) {
+    select = "*";
+  } else {
     for (const item of plan.select) {
-        const column = baseColumnReference(item.expression, base.alias);
-        if (column === undefined)
-            return undefined;
-        select.push({ column, alias: item.alias });
-    }
-    const equalities = [];
-    for (const predicate of plan.predicates) {
-        if (predicate.operator !== "=" || predicate.escape !== undefined)
-            return undefined;
-        const leftColumn = baseColumnReference(predicate.left, base.alias);
-        const rightColumn = baseColumnReference(predicate.right, base.alias);
-        const operand = leftColumn !== undefined && rightColumn === undefined
-            ? templateEquality(predicate.right)
-            : rightColumn !== undefined && leftColumn === undefined
-                ? templateEquality(predicate.left)
-                : undefined;
-        const column = leftColumn ?? rightColumn;
-        if (operand === undefined || column === undefined)
-            return undefined;
-        equalities.push({ column, ...operand });
+      const column = baseColumnReference(item.expression, base.alias);
+      if (column === void 0)
+        return void 0;
+      select.push({ column, alias: item.alias });
     }
-    return { table: base.table, equalities, select };
+  }
+  const equalities = [];
+  for (const predicate of plan.predicates) {
+    if (predicate.operator !== "=" || predicate.escape !== void 0)
+      return void 0;
+    const leftColumn = baseColumnReference(predicate.left, base.alias);
+    const rightColumn = baseColumnReference(predicate.right, base.alias);
+    const operand = leftColumn !== void 0 && rightColumn === void 0 ? templateEquality(predicate.right) : rightColumn !== void 0 && leftColumn === void 0 ? templateEquality(predicate.left) : void 0;
+    const column = leftColumn ?? rightColumn;
+    if (operand === void 0 || column === void 0)
+      return void 0;
+    equalities.push({ column, ...operand });
+  }
+  return { table: base.table, equalities, select };
 }
-const templates = new WeakMap();
-/** The template for a cached compiled plan, analyzed once per statement. */
-export function cachedPointReadTemplate(plan) {
-    const cached = templates.get(plan);
-    if (cached !== undefined)
-        return cached;
-    const template = pointReadTemplate(plan) ?? null;
-    templates.set(plan, template);
-    return template;
+const templates = /* @__PURE__ */ new WeakMap();
+function cachedPointReadTemplate(plan) {
+  const cached = templates.get(plan);
+  if (cached !== void 0)
+    return cached;
+  const template = pointReadTemplate(plan) ?? null;
+  templates.set(plan, template);
+  return template;
 }
-/**
- * Substitutes this call's parameters into the statement template. Undefined means a parameter
- * carries a value the fast path cannot compare exactly (NULL, a non-finite number, an invalid
- * Date, or a non-storage value), and the ordinary executor must decide what it means.
- */
-export function resolvePointReadShape(template, params) {
-    const equalities = [];
-    for (const entry of template.equalities) {
-        if ("value" in entry) {
-            equalities.push(entry);
-            continue;
-        }
-        const raw = params[entry.parameter];
-        if (raw === undefined)
-            return undefined;
-        const value = equalityValue(raw);
-        if (value === undefined)
-            return undefined;
-        equalities.push({ column: entry.column, value });
+function resolvePointReadShape(template, params) {
+  const equalities = [];
+  for (const entry of template.equalities) {
+    if ("value" in entry) {
+      equalities.push(entry);
+      continue;
     }
-    return { table: template.table, equalities, select: template.select };
+    const raw = params[entry.parameter];
+    if (raw === void 0)
+      return void 0;
+    const value = equalityValue(raw);
+    if (value === void 0)
+      return void 0;
+    equalities.push({ column: entry.column, value });
+  }
+  return { table: template.table, equalities, select: template.select };
 }
-const ascendingRuns = new WeakMap();
-/** Whether the array is non-strictly ascending; memoized per immutable decoded array. */
-export function valuesAreAscending(values) {
-    const cached = ascendingRuns.get(values);
-    if (cached !== undefined)
-        return cached;
-    let ascending = true;
-    for (let index = 1; index < values.length; index += 1) {
-        if ((values[index] ?? 0) < (values[index - 1] ?? 0)) {
-            ascending = false;
-            break;
-        }
+const ascendingRuns = /* @__PURE__ */ new WeakMap();
+function valuesAreAscending(values) {
+  const cached = ascendingRuns.get(values);
+  if (cached !== void 0)
+    return cached;
+  let ascending = true;
+  for (let index = 1; index < values.length; index += 1) {
+    if ((values[index] ?? 0) < (values[index - 1] ?? 0)) {
+      ascending = false;
+      break;
     }
-    ascendingRuns.set(values, ascending);
-    return ascending;
+  }
+  ascendingRuns.set(values, ascending);
+  return ascending;
 }
-/** The [begin, end) run of slots equal to `target` over an ascending array. */
-export function equalRunRange(values, target) {
-    let low = 0;
-    let high = values.length;
-    while (low < high) {
-        const middle = (low + high) >>> 1;
-        if ((values[middle] ?? 0) < target)
-            low = middle + 1;
-        else
-            high = middle;
-    }
-    const begin = low;
-    high = values.length;
-    while (low < high) {
-        const middle = (low + high) >>> 1;
-        if ((values[middle] ?? 0) <= target)
-            low = middle + 1;
-        else
-            high = middle;
-    }
-    return { begin, end: low };
+function equalRunRange(values, target) {
+  let low = 0;
+  let high = values.length;
+  while (low < high) {
+    const middle = low + high >>> 1;
+    if ((values[middle] ?? 0) < target)
+      low = middle + 1;
+    else
+      high = middle;
+  }
+  const begin = low;
+  high = values.length;
+  while (low < high) {
+    const middle = low + high >>> 1;
+    if ((values[middle] ?? 0) <= target)
+      low = middle + 1;
+    else
+      high = middle;
+  }
+  return { begin, end: low };
 }
+export {
+  cachedPointReadTemplate,
+  equalRunRange,
+  pointReadTestHooks,
+  resolvePointReadShape,
+  valuesAreAscending
+};

package/dist/engine/query-api.js

@@ -1,3 +1,12 @@
-/** 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";
+import { bindPlanParameters, bindStatementParameters, compileQuery, compileStatement, executeQuery, referencedColumns } from "./query.js";
+import { optimizePlan, renderPlan } from "./optimizer.js";
+export {
+  bindPlanParameters,
+  bindStatementParameters,
+  compileQuery,
+  compileStatement,
+  executeQuery,
+  optimizePlan,
+  referencedColumns,
+  renderPlan
+};

package/dist/engine/query-cache.js

@@ -2,78 +2,70 @@ import { copyDate, dateMilliseconds } from "../date-value.js";
 import { estimateValuesBytes } from "./byte-estimates.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;
-/** Stable, collision-free memo-key encoding for bound SQL parameters. */
-export function queryResultMemoKey(sql, params) {
-    return JSON.stringify([sql, params.map(encodeParameter)]);
+const RESULT_MEMO_MAX_BYTES = 4 * 1024 * 1024;
+function queryResultMemoKey(sql, params) {
+  return JSON.stringify([sql, params.map(encodeParameter)]);
 }
-/**
- * A memo key for a compiled plan: its JSON with the values JSON cannot tell apart made
- * distinct — a Date from its ISO string, -0 from 0, NaN and the infinities from null — so two
- * plans with the same key are the same query over the same literals.
- */
-export function planMemoKey(plan) {
-    return JSON.stringify(plan, (_key, value) => {
-        if (value instanceof Date)
-            return { $date: dateMilliseconds(value) };
-        if (typeof value === "bigint")
-            return { $bigint: value.toString() };
-        if (typeof value === "number") {
-            if (Object.is(value, -0))
-                return { $number: "-0" };
-            if (!Number.isFinite(value))
-                return { $number: String(value) };
-        }
-        return value;
-    });
+function planMemoKey(plan) {
+  return JSON.stringify(plan, (_key, value) => {
+    if (value instanceof Date)
+      return { $date: dateMilliseconds(value) };
+    if (typeof value === "bigint")
+      return { $bigint: value.toString() };
+    if (typeof value === "number") {
+      if (Object.is(value, -0))
+        return { $number: "-0" };
+      if (!Number.isFinite(value))
+        return { $number: String(value) };
+    }
+    return value;
+  });
 }
-/**
- * Defensive copy because callers own query results and may mutate both rows and Dates. Object
- * spread copies own enumerable properties with define semantics, so a column named `__proto__`
- * stays an own property; only a Date cell needs the explicit define, and only because its
- * value is replaced. This used to define every cell, which made a memo hit on a result of a
- * few thousand rows cost more than re-executing the query.
- */
-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) {
-                const value = copy[name];
-                if (value instanceof Date)
-                    defineSqlResultProperty(copy, name, copyDate(value));
-            }
-            return copy;
-        }),
-    };
-    return copyQueryResultExternalization(result, copy);
+function copyQueryResult(result) {
+  const columns = result.columns;
+  const copy = {
+    columns: [...columns],
+    columnDomains: structuredClone(result.columnDomains),
+    rows: result.rows.map((row) => {
+      const copy2 = { ...row };
+      for (const name of columns) {
+        const value = copy2[name];
+        if (value instanceof Date)
+          defineSqlResultProperty(copy2, name, copyDate(value));
+      }
+      return copy2;
+    })
+  };
+  return copyQueryResultExternalization(result, copy);
 }
-/** Modeled retained payload for one cached query result. */
-export function queryResultRetainedBytes(result) {
-    let bytes = 64;
-    for (const column of result.columns)
-        bytes += 16 + column.length * 2;
-    for (const row of result.rows)
-        bytes += estimateValuesBytes(Object.values(row));
-    return bytes;
+function queryResultRetainedBytes(result) {
+  let bytes = 64;
+  for (const column of result.columns)
+    bytes += 16 + column.length * 2;
+  for (const row of result.rows)
+    bytes += estimateValuesBytes(Object.values(row));
+  return bytes;
 }
 function encodeParameter(value) {
-    if (value === null)
-        return [0];
-    if (typeof value === "boolean")
-        return [1, value];
-    if (typeof value === "number") {
-        if (Object.is(value, -0))
-            return [2, "-0"];
-        return [2, String(value)];
-    }
-    if (typeof value === "string")
-        return [3, value];
-    if (value instanceof Date)
-        return [4, dateMilliseconds(value)];
-    throw new TypeError("Query parameter has an unsupported value");
+  if (value === null)
+    return [0];
+  if (typeof value === "boolean")
+    return [1, value];
+  if (typeof value === "number") {
+    if (Object.is(value, -0))
+      return [2, "-0"];
+    return [2, String(value)];
+  }
+  if (typeof value === "string")
+    return [3, value];
+  if (value instanceof Date)
+    return [4, dateMilliseconds(value)];
+  throw new TypeError("Query parameter has an unsupported value");
 }
+export {
+  RESULT_MEMO_MAX_BYTES,
+  copyQueryResult,
+  planMemoKey,
+  queryResultMemoKey,
+  queryResultRetainedBytes
+};

package/dist/engine/query.d.ts

@@ -31,6 +31,12 @@ export interface QueryExecutionOptions {
 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
+ * 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
@@ -40,6 +46,14 @@ export declare function isScalarFunctionName(name: AggregateName | ScalarFunctio
  * SUBSTR count characters, not UTF-16 units, matching SQLite and PostgreSQL.
  */
 export declare function scalarFunctionValue(name: Exclude<ScalarFunctionName, "COALESCE">, values: readonly unknown[]): unknown;
+export type ScalarFunctionEvaluator = (values: readonly unknown[]) => unknown;
+/**
+ * The evaluator for one function name, resolved once. A call site that keeps the evaluator
+ * skips the name dispatch on every row; the registry functions and the hottest built-ins get
+ * a closure of their own, everything else a closure over the general dispatch.
+ */
+export declare function scalarFunctionEvaluator(name: Exclude<ScalarFunctionName, "COALESCE">): ScalarFunctionEvaluator;
+export declare function dateTruncValue(unit: unknown, value: unknown): Date | null;
 /** 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. */
@@ -56,6 +70,14 @@ interface CompileQueryOptions {
     /** Set false to skip deterministic plan rewrites, for example to snapshot the raw plan. */
     readonly optimize?: boolean;
 }
+/** One RETURNING item beyond a plain column: its statement text, output name, and the column it names when it is one. */
+export interface ReturningItem {
+    sql: string;
+    alias: string;
+    expression: Expression;
+    /** The target column the item names, when it is a bare column reference. */
+    column?: string;
+}
 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
@@ -135,6 +157,11 @@ export type CompiledStatement = {
         column: string;
         /** The full PostgreSQL conflict target; `column` remains the scalar fast-path name. */
         columns?: string[];
+        /**
+         * `ON CONFLICT DO NOTHING` with no target: the statement names no columns, and the
+         * table's unique key is resolved at execution, where the catalog is known.
+         */
+        anyTarget?: true;
         action: "nothing" | "replace" | "update";
         /** Expressions evaluated against the stored target row and the proposed EXCLUDED row. */
         assignments?: Array<{
@@ -145,10 +172,14 @@ export type CompiledStatement = {
         where?: Expression;
     };
     returning?: string[] | "*";
+    /** RETURNING items that are not plain columns, evaluated over the affected rows. */
+    returningItems?: ReturningItem[];
     parameterCount?: number;
 } | {
     kind: "update";
     table: string;
+    /** `UPDATE t AS u`: the name the assignments, predicates, and RETURNING may qualify by. */
+    alias?: string;
     assignments: Array<{
         column: string;
         expression: Expression;
@@ -159,16 +190,21 @@ export type CompiledStatement = {
         right: Expression;
     }>;
     returning?: string[] | "*";
+    /** RETURNING items that are not plain columns, evaluated over the affected rows. */
+    returningItems?: ReturningItem[];
     parameterCount?: number;
 } | {
     kind: "delete";
     table: string;
+    alias?: string;
     predicates: Array<{
         left: Expression;
         operator: PredicateOperator;
         right: Expression;
     }>;
     returning?: string[] | "*";
+    /** RETURNING items that are not plain columns, evaluated over the affected rows. */
+    returningItems?: ReturningItem[];
     parameterCount?: number;
 } | {
     kind: "create-table";
@@ -535,6 +571,8 @@ export declare function orderOutputName(expression: Expression, select: readonly
 interface ListMembership {
     set: ReadonlySet<unknown>;
     hasNull: boolean;
+    /** Whether any member is text, which a typed left value may read in its own type. */
+    hasText: boolean;
 }
 /**
  * IN lists produced by subquery materialization can hold many thousands of literals, and
@@ -668,6 +706,13 @@ 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;
+/**
+ * Reads datetime text the way the TIMESTAMP literal does — a zoneless `2026-01-02 03:04:05` is
+ * UTC, never the host's zone — and falls back to the JavaScript parser for other spellings.
+ * `new Date("2026-01-02 03:04:05")` alone would read the same text in local time, so a CAST
+ * would answer differently on two machines.
+ */
+export declare function datetimeText(text: string): Date;
 /** The parser's OFFSET range contract, shared with the typed builder. */
 export declare function validateOffset(offset: number): number;
 /**