@minnowdb/core 0.7.10 → 0.9.0

package/dist/engine/errors.d.ts

@@ -3,6 +3,25 @@
  * them (name, fields, instanceof) without bundling the executor.
  */
 type ErrorValue = boolean | number | string | Date;
+/** An idle SQL transaction rolled back; later statements must not become autocommits. */
+export declare class TransactionExpiredError extends Error {
+    readonly name = "TransactionExpiredError";
+    constructor();
+}
+/** The worker stopped responding within the configured request deadline. */
+export declare class DatabaseWorkerTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    readonly name = "DatabaseWorkerTimeoutError";
+    constructor(method: string, timeoutMs: number);
+}
+/** A transport failure cannot prove whether this operation published before its reply was lost. */
+export declare class DatabaseWorkerOutcomeUnknownError extends Error {
+    readonly method: string;
+    readonly requestId: string;
+    readonly name = "DatabaseWorkerOutcomeUnknownError";
+    constructor(method: string, requestId: string, options?: ErrorOptions);
+}
 /** A database operation named a table that is not present in the current catalog. */
 export declare class UnknownTableError extends TypeError {
     readonly tableName: string;
@@ -17,10 +36,10 @@ export declare class DatabaseReadBacklogError extends Error {
 }
 /** A live-query owner reached one of its documented resident-resource ceilings. */
 export declare class LiveQueryLimitError extends Error {
-    readonly resource: "set" | "group" | "subscription";
+    readonly resource: "set" | "group" | "subscription" | "byte";
     readonly limit: number;
     readonly name = "LiveQueryLimitError";
-    constructor(resource: "set" | "group" | "subscription", limit: number);
+    constructor(resource: "set" | "group" | "subscription" | "byte", limit: number);
 }
 export declare class UniqueConstraintError extends Error {
     readonly tableName: string;

package/dist/engine/errors.js

@@ -1,3 +1,29 @@
+class TransactionExpiredError extends Error {
+  name = "TransactionExpiredError";
+  constructor() {
+    super("The SQL transaction expired and rolled back; issue ROLLBACK or BEGIN before continuing");
+  }
+}
+class DatabaseWorkerTimeoutError extends Error {
+  method;
+  timeoutMs;
+  name = "DatabaseWorkerTimeoutError";
+  constructor(method, timeoutMs) {
+    super(`Database worker ${method} did not respond within ${String(timeoutMs)}ms`);
+    this.method = method;
+    this.timeoutMs = timeoutMs;
+  }
+}
+class DatabaseWorkerOutcomeUnknownError extends Error {
+  method;
+  requestId;
+  name = "DatabaseWorkerOutcomeUnknownError";
+  constructor(method, requestId, options) {
+    super(`Database worker outcome is unknown for ${method}; reconcile durable application IDs before retrying`, options);
+    this.method = method;
+    this.requestId = requestId;
+  }
+}
 function formatValue(value) {
   return value instanceof Date ? dateIsoString(value) : String(value);
 }
@@ -22,7 +48,7 @@ class LiveQueryLimitError extends Error {
   limit;
   name = "LiveQueryLimitError";
   constructor(resource, limit) {
-    super(resource === "set" ? `A database cannot retain more than ${String(limit)} live-query sets` : `A live-query set cannot retain more than ${String(limit)} ${resource} records`);
+    super(resource === "set" ? `A database cannot retain more than ${String(limit)} live-query sets` : resource === "byte" ? `A live-query set cannot retain more than ${String(limit)} modeled bytes` : `A live-query set cannot retain more than ${String(limit)} ${resource} records`);
     this.resource = resource;
     this.limit = limit;
   }
@@ -117,10 +143,13 @@ export {
   CompactionMemoryBudgetError,
   CompactionWriteAmplificationError,
   DatabaseReadBacklogError,
+  DatabaseWorkerOutcomeUnknownError,
+  DatabaseWorkerTimeoutError,
   LiveQueryLimitError,
   MaintenanceBacklogError,
   MissingKeyError,
   SqlCompileError,
+  TransactionExpiredError,
   UniqueConstraintError,
   UnknownTableError,
   VisibleSegmentCursorStaleError

package/dist/engine/index.d.ts

@@ -17,3 +17,4 @@ export type * from "./schema.js";
 export type { InsertValue, CompiledQuery, CompiledStatement, QueryResult, QueryRow, QueryExecutionOptions, QueryValue, SqlColumnSchema, SqlColumnType, } from "./query.js";
 export type { AsyncQueryExecutionOptions, QueryBatchExecutionOptions, QuerySpillStore, } from "./vector.js";
 export type { MinnowSqlDriver, MinnowSqlExecutor } from "./sql-driver.js";
+export { OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, } from "../storage/types.js";

package/dist/engine/index.js

@@ -4,6 +4,7 @@ export * from "./errors.js";
 import { QueryMemoryBudgetError } from "./memory.js";
 import { MAX_SQL_NESTING_DEPTH, MAX_SQL_NUMERIC_DIGITS, MAX_SQL_PARAMETERS, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, MAX_SQL_SCALAR_RESULT_CHARACTERS, MAX_SQL_STRUCTURED_VALUE_DEPTH, MAX_SQL_STRUCTURED_VALUE_ITEMS, MAX_SQL_TEXT_CHARACTERS, MAX_SQL_TOKENS } from "./cache-limits.js";
 import { column, foreignKeyName, isDestructiveStep, planMigration, schema, table, view } from "./schema.js";
+import { OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError } from "../storage/types.js";
 export {
   MAX_SQL_NESTING_DEPTH,
   MAX_SQL_NUMERIC_DIGITS,
@@ -15,6 +16,9 @@ export {
   MAX_SQL_STRUCTURED_VALUE_ITEMS,
   MAX_SQL_TEXT_CHARACTERS,
   MAX_SQL_TOKENS,
+  OpfsCoordinationError,
+  OpfsDatabaseInUseError,
+  OpfsUncertainOutcomeError,
   QueryMemoryBudgetError,
   column,
   foreignKeyName,

package/dist/engine/live-accept.js

@@ -0,0 +1,13 @@
+const publications = /* @__PURE__ */ new WeakMap();
+function stageLiveExecution(execution, publish) {
+  publications.set(execution, publish);
+  return execution;
+}
+function acceptLiveExecution(execution) {
+  publications.get(execution)?.();
+  publications.delete(execution);
+}
+export {
+  acceptLiveExecution,
+  stageLiveExecution
+};

package/dist/engine/live-aggregate.js

@@ -0,0 +1,264 @@
+import { childExpressions, hasAggregate, mapChildExpressions, executeRowQueryInternal, inferResultColumnDomains, externalizeQueryResult } from "./query.js";
+import { encodeQueryIdentity } from "./query-identity.js";
+import { exactNumericBinary, exactNumericValue, externalSqlDomainValue, isExactNumeric } from "./sql-domains.js";
+import { encodeSqlEqualityValue } from "./sql-semantics.js";
+function contributionBytes(key, row) {
+  return 64 + key.length * 2 + row.group.length * 2 + row.values.reduce((sum, value) => sum + (typeof value === "string" ? value.length * 2 + 16 : 16), 0);
+}
+function groupBytes(key, group) {
+  return 96 + key.length * 2 + group.sums.reduce((sum, value) => sum + value.length * 2 + 24, 0);
+}
+class LiveAggregate {
+  inputPlan;
+  #outputPlan;
+  #aggregates;
+  #groupAliases;
+  #contributions;
+  #revision;
+  #pending;
+  #bytes;
+  #groups;
+  #domains;
+  keyAlias;
+  #schema;
+  constructor(inputPlan, outputPlan, aggregates, groupAliases, keyAlias, contributions = { rows: /* @__PURE__ */ new Map(), revision: 0 }, groups = /* @__PURE__ */ new Map(), domains = [], schema = [], bytes = 256 + encodeQueryIdentity(inputPlan).length * 2 + encodeQueryIdentity(outputPlan).length * 2, pending) {
+    this.inputPlan = inputPlan;
+    this.#outputPlan = outputPlan;
+    this.#aggregates = aggregates;
+    this.#groupAliases = groupAliases;
+    this.keyAlias = keyAlias;
+    this.#contributions = contributions;
+    this.#revision = contributions.revision;
+    this.#pending = pending;
+    this.#bytes = bytes;
+    this.#groups = groups;
+    this.#domains = domains;
+    this.#schema = schema;
+  }
+  static plan(plan, qualifiedKey) {
+    const aggregates = [];
+    const groupAliases = plan.groupBy.map((_, index) => `__minnow_live_group_${String(index)}`);
+    const groupKeys = new Map(plan.groupBy.map((expression, index) => [
+      encodeQueryIdentity(expression),
+      groupAliases[index] ?? ""
+    ]));
+    const rowLocal = (expression) => !hasAggregate(expression) && !["subquery", "exists", "window", "parameter", "wildcard"].includes(expression.kind) && childExpressions(expression).every(rowLocal);
+    if (!plan.groupBy.every(rowLocal))
+      return void 0;
+    const rewrite = (expression) => {
+      const grouped = groupKeys.get(encodeQueryIdentity(expression));
+      if (grouped !== void 0)
+        return { kind: "column", reference: grouped };
+      if (expression.kind === "call" && hasAggregate(expression)) {
+        if (!["COUNT", "SUM", "AVG"].includes(expression.name) || expression.arguments.length !== 1 || expression.distinct === true)
+          throw new TypeError("Not an additive live aggregate");
+        const argument = expression.arguments[0];
+        if (argument === void 0 || !(rowLocal(argument) || expression.name === "COUNT" && argument.kind === "wildcard"))
+          throw new TypeError("Not a row-local aggregate argument");
+        const alias = `__minnow_live_value_${String(aggregates.length)}`;
+        aggregates.push({
+          name: expression.name,
+          alias,
+          argument: argument.kind === "wildcard" ? { kind: "literal", value: 1 } : argument
+        });
+        return { kind: "column", reference: alias };
+      }
+      if (expression.kind === "column" || expression.kind === "window" || expression.kind === "subquery" || expression.kind === "exists")
+        throw new TypeError("Not a grouped live expression");
+      return mapChildExpressions(expression, rewrite);
+    };
+    try {
+      const select = plan.select.map((item) => ({ ...item, expression: rewrite(item.expression) }));
+      const having = plan.having.map((predicate) => ({
+        ...predicate,
+        left: rewrite(predicate.left),
+        right: rewrite(predicate.right)
+      }));
+      const outputAliases = new Set(select.map((item) => item.alias));
+      const orderBy = plan.orderBy.map((term) => ({
+        ...term,
+        expression: term.expression.kind === "column" && outputAliases.has(term.expression.reference) ? term.expression : rewrite(term.expression)
+      }));
+      if (aggregates.length === 0)
+        return void 0;
+      const keyAlias = "__minnow_live_aggregate_key";
+      const inputPlan = {
+        ...plan,
+        select: [
+          { alias: keyAlias, expression: { kind: "column", reference: qualifiedKey } },
+          ...plan.groupBy.map((expression, index) => ({
+            alias: groupAliases[index] ?? "",
+            expression
+          })),
+          ...aggregates.map(({ alias, argument }) => ({ alias, expression: argument }))
+        ],
+        groupBy: [],
+        having: [],
+        orderBy: []
+      };
+      delete inputPlan.limit;
+      delete inputPlan.offset;
+      const outputPlan = {
+        ...plan,
+        base: { table: "__minnow_live_groups", alias: "__minnow_live_groups" },
+        joins: [],
+        select,
+        predicates: having,
+        groupBy: [],
+        having: [],
+        orderBy
+      };
+      return new LiveAggregate(inputPlan, outputPlan, aggregates, groupAliases, keyAlias);
+    } catch {
+      return void 0;
+    }
+  }
+  patch(result, changed, token) {
+    if (this.#pending !== void 0 || this.#revision !== this.#contributions.revision)
+      throw new Error("Unaccepted or stale aggregate");
+    const rows = this.#contributions.rows;
+    const pending = /* @__PURE__ */ new Map();
+    let bytes = this.#bytes;
+    const groups = new Map(this.#groups);
+    const touched = /* @__PURE__ */ new Set();
+    const groupFor = (key, keys = []) => {
+      let group = groups.get(key);
+      if (group !== void 0 && !touched.has(key))
+        bytes -= groupBytes(key, group);
+      if (group === void 0) {
+        group = {
+          keys,
+          members: 0,
+          counts: this.#aggregates.map(() => 0),
+          sums: this.#aggregates.map(() => exactNumericValue(0) ?? ""),
+          absolute: this.#aggregates.map(() => 0)
+        };
+        groups.set(key, group);
+        touched.add(key);
+      } else if (!touched.has(key)) {
+        group = {
+          ...group,
+          counts: [...group.counts],
+          sums: [...group.sums],
+          absolute: [...group.absolute]
+        };
+        groups.set(key, group);
+        touched.add(key);
+      }
+      return group;
+    };
+    const apply = (group, values, sign) => {
+      group.members += sign;
+      for (const [index, aggregate] of this.#aggregates.entries()) {
+        const value = values[index] ?? null;
+        if (value === null)
+          continue;
+        group.counts[index] = (group.counts[index] ?? 0) + sign;
+        if (aggregate.name !== "COUNT") {
+          if (typeof value !== "number" && !isExactNumeric(value))
+            throw new TypeError("Live SUM requires numeric values");
+          if (typeof value === "number") {
+            if (!Number.isSafeInteger(value))
+              throw new TypeError("Floating-point aggregates require full execution");
+            group.absolute[index] = (group.absolute[index] ?? 0) + sign * Math.abs(value);
+            if (!Number.isSafeInteger(group.absolute[index]))
+              throw new TypeError("Aggregate sum may round; requires full execution");
+          }
+          const sum = exactNumericBinary(sign === 1 ? "+" : "-", group.sums[index] ?? exactNumericValue(0), exactNumericValue(value));
+          if (sum === null || sum === void 0)
+            throw new TypeError("Invalid numeric aggregate contribution");
+          group.sums[index] = sum;
+        }
+      }
+    };
+    for (const key of changed) {
+      const old = rows.get(key);
+      if (old === void 0)
+        continue;
+      apply(groupFor(old.group), old.values, -1);
+      pending.set(key, void 0);
+      bytes -= contributionBytes(key, old);
+    }
+    for (const row of result.rows) {
+      const key = token(row[this.keyAlias] ?? null);
+      if (pending.get(key) !== void 0 || rows.has(key) && !changed.has(key))
+        throw new TypeError("Duplicate live input key");
+      const keys = this.#groupAliases.map((alias) => row[alias] ?? null);
+      const group = JSON.stringify(keys.map(encodeSqlEqualityValue));
+      const values = this.#aggregates.map(({ alias }) => row[alias] ?? null);
+      apply(groupFor(group, keys), values, 1);
+      const contribution = { group, values };
+      pending.set(key, contribution);
+      bytes += contributionBytes(key, contribution);
+    }
+    if (this.#groupAliases.length === 0)
+      groupFor("[]");
+    else
+      for (const key of touched)
+        if (groups.get(key)?.members === 0)
+          groups.delete(key);
+    for (const key of touched) {
+      const group = groups.get(key);
+      if (group !== void 0)
+        bytes += groupBytes(key, group);
+    }
+    const domains = this.#aggregates.map(({ alias }, index) => result.columnDomains[result.columns.indexOf(alias)] ?? this.#domains[index] ?? null);
+    return new LiveAggregate(this.inputPlan, this.#outputPlan, this.#aggregates, this.#groupAliases, this.keyAlias, this.#contributions, groups, domains, result.columns.map((name, index) => {
+      const domain = result.columnDomains[index];
+      const value = result.rows.find((row) => row[name] !== null)?.[name];
+      const aggregate = this.#aggregates.find((item) => item.alias === name);
+      return {
+        name,
+        type: aggregate?.name === "COUNT" ? "number" : domain !== null && domain !== void 0 ? "string" : typeof value === "number" ? "number" : typeof value === "boolean" ? "boolean" : value instanceof Date ? "datetime" : value === void 0 || value === null ? this.#schema[index]?.type ?? "string" : "string",
+        ...domain === null || domain === void 0 || aggregate?.name === "COUNT" ? {} : { sqlDomain: domain }
+      };
+    }), bytes, pending);
+  }
+  accept() {
+    const pending = this.#pending;
+    if (pending === void 0)
+      return;
+    if (this.#revision !== this.#contributions.revision)
+      throw new Error("Stale aggregate");
+    for (const [key, contribution] of pending) {
+      if (contribution === void 0)
+        this.#contributions.rows.delete(key);
+      else
+        this.#contributions.rows.set(key, contribution);
+    }
+    this.#revision = ++this.#contributions.revision;
+    this.#pending = void 0;
+  }
+  result() {
+    const rows = [];
+    for (const group of this.#groups.values()) {
+      const row = {};
+      for (const [index, alias] of this.#groupAliases.entries())
+        row[alias] = group.keys[index] ?? null;
+      for (const [index, aggregate] of this.#aggregates.entries()) {
+        const count = group.counts[index] ?? 0;
+        const domain = this.#domains[index];
+        let value = aggregate.name === "COUNT" ? count : count === 0 ? null : group.sums[index] ?? null;
+        if (value !== null && aggregate.name !== "COUNT") {
+          if (domain?.kind !== "numeric") {
+            value = Number(externalSqlDomainValue(value));
+            if (aggregate.name === "AVG")
+              value /= count;
+          } else if (aggregate.name === "AVG")
+            value = exactNumericBinary("/", value, count, domain.scale) ?? null;
+        }
+        row[aggregate.alias] = value;
+      }
+      rows.push(row);
+    }
+    const result = executeRowQueryInternal(this.#outputPlan, /* @__PURE__ */ new Map([["__minnow_live_groups", rows]]));
+    result.columnDomains = inferResultColumnDomains(this.#outputPlan, /* @__PURE__ */ new Map([["__minnow_live_groups", this.#schema]]));
+    return externalizeQueryResult(result);
+  }
+  get retainedBytes() {
+    return this.#bytes;
+  }
+}
+export {
+  LiveAggregate
+};

package/dist/engine/live-patch.d.ts

@@ -0,0 +1,21 @@
+import type { QueryResult, QueryRow } from "../plan/model.js";
+import type { LiveQueryDelivery } from "./live.js";
+export type LiveQueryPatch = {
+    readonly type: "reset";
+    readonly result: QueryResult;
+} | {
+    readonly type: "patch";
+    /** Each next position's previous position, or -1 for a changed/new row. */
+    readonly retained: Int32Array;
+    readonly changedRows: ReadonlyArray<{
+        readonly index: number;
+        readonly row: QueryRow;
+    }>;
+};
+export interface LiveQueryPatchOptions {
+    onPatch(patch: LiveQueryPatch, delivery: LiveQueryDelivery): void;
+    onError?(error: unknown): void;
+    onComplete?(): void;
+}
+/** Copy only changed payloads when provenance is available; resets establish a fresh baseline. */
+export declare function createLiveQueryPatch(result: QueryResult, delivery: LiveQueryDelivery): LiveQueryPatch;

package/dist/engine/live-patch.js

@@ -0,0 +1,31 @@
+import { copyDate } from "../date-value.js";
+function copyRow(row) {
+  const copy = { ...row };
+  for (const key of Object.keys(copy)) {
+    const value = copy[key];
+    if (value instanceof Date)
+      copy[key] = copyDate(value);
+  }
+  return copy;
+}
+function createLiveQueryPatch(result, delivery) {
+  if (delivery.retained === void 0 || delivery.initial)
+    return {
+      type: "reset",
+      result: {
+        columns: [...result.columns],
+        columnDomains: structuredClone(result.columnDomains),
+        rows: result.rows.map(copyRow)
+      }
+    };
+  const changedRows = [];
+  for (let index = 0; index < result.rows.length; index += 1) {
+    const row = result.rows[index];
+    if (row !== void 0 && (delivery.retained[index] ?? -1) < 0)
+      changedRows.push({ index, row: copyRow(row) });
+  }
+  return { type: "patch", retained: new Int32Array(delivery.retained), changedRows };
+}
+export {
+  createLiveQueryPatch
+};

package/dist/engine/live.d.ts

@@ -1,3 +1,5 @@
+import { type LiveQueryPatchOptions } from "./live-patch.js";
+export type { LiveQueryPatch, LiveQueryPatchOptions } from "./live-patch.js";
 import { type CatalogProbe, type Manifest, type StoragePage } from "../storage/types.js";
 import { type CompiledQuery, type QueryResult, type QueryValue } from "./query.js";
 /**
@@ -27,6 +29,8 @@ export interface LiveQuerySetOptions {
     readonly maxGroups?: number;
     /** Maximum result/observer subscriptions retained by this set. Defaults to 1,024. */
     readonly maxSubscriptions?: number;
+    /** Maximum modeled resident result and maintenance bytes per set. Defaults to 64 MiB. */
+    readonly maxRetainedBytes?: number;
     /**
      * Hand `onChange` the set's retained result instead of a private copy. The result is shared
      * with every equal subscription and with the next change comparison, so a subscriber must
@@ -64,6 +68,8 @@ export interface LiveQueryDelivery {
     readonly retained?: Int32Array;
 }
 export interface LiveQuerySubscribeOptions {
+    /** Borrow the read-only retained result for this subscription instead of copying it. */
+    readonly sharedResults?: boolean;
     onChange(result: QueryResult, delivery: LiveQueryDelivery): void;
     onError?(error: unknown): void;
     /** Called once when the subscription ends because the subscription or its set closed. */
@@ -114,6 +120,8 @@ export interface LiveQueryStats {
      * bounded by the engine at 64 rows and is not included.
      */
     retainedRows: number;
+    /** Modeled resident result and incremental maintenance bytes, counted once per group. */
+    retainedBytes: number;
     /** Work avoided because equal statements shared one query group or in-flight execution. */
     sharedExecutions: number;
     lastSweepMs: number;
@@ -146,6 +154,8 @@ export interface LiveQueryExecuteContext {
 export interface LiveMaintainedExecution {
     readonly result: QueryResult;
     readonly state: unknown;
+    /** Modeled total bytes retained by the result and opaque maintenance state. */
+    readonly retainedBytes?: number;
 }
 export interface LiveMaintainedChange extends LiveMaintainedExecution {
     readonly changed: boolean;
@@ -159,6 +169,8 @@ export interface LiveQueryHost {
     dependencyTableIds(query: LiveQueryInput, probe?: CatalogProbe): Promise<Set<string>>;
     /** Executes the statement; the returned result belongs to the set and is never shared. */
     execute(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<QueryResult>;
+    /** Optionally publishes an accepted result for adapters that re-execute after invalidation. */
+    memoize?(query: LiveQueryInput, result: QueryResult, probe: CatalogProbe): Promise<void>;
     /**
      * Executes a statement the host can later maintain incrementally, or returns undefined when
      * the statement's shape rules that out; the set then executes it in full from then on.
@@ -178,6 +190,8 @@ export declare class LiveQuerySet {
     get stats(): LiveQueryStats;
     /** Registers a query, delivers its current result, and shares work with equal statements. */
     subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscription>;
+    /** Delivers resets or changed row payloads without constructing a private full row array per patch. */
+    subscribePatches(query: LiveQueryInput, options: LiveQueryPatchOptions): Promise<LiveQuerySubscription>;
     /** Observes invalidation; the statement executes inside the set only when asked to compare. */
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscription>;
     /** Called by the owning database after each local write commit; also hints other tabs. */