@minnowdb/core 0.7.8 → 0.8.0

package/dist/engine/sql-domains.d.ts

@@ -91,3 +91,7 @@ export declare function concatenatedSqlValue(leftValue: unknown, rightValue: unk
  */
 export declare function intervalDomainCompare(left: unknown, right: unknown): number | undefined;
 export declare function isSqlDomainValue(value: unknown): value is string;
+/** SQL extraction from TIME and INTERVAL without collapsing calendar months into a timestamp. */
+export declare function temporalDomainPart(field: string, value: unknown): number | undefined;
+/** Structural ordering for shipped JSONB and one-dimensional ARRAY values. */
+export declare function structuredDomainCompare(left: unknown, right: unknown): number | undefined;

package/dist/engine/sql-domains.js

@@ -722,6 +722,125 @@ function intervalDomainCompare(left, right) {
 function isSqlDomainValue(value) {
   return typeof value === "string" && value.startsWith(PREFIX);
 }
+function temporalDomainPart(field, value) {
+  if (typeof value !== "string")
+    return void 0;
+  let months = 0;
+  let days = 0;
+  let usecs;
+  const interval = value.startsWith(INTERVAL_VALUE);
+  if (interval) {
+    [months, days, usecs] = JSON.parse(value.slice(INTERVAL_VALUE.length));
+  } else if (value.startsWith(TIME_VALUE)) {
+    const [hour = "0", minute = "0", second = "0"] = value.slice(TIME_VALUE.length).split(":");
+    usecs = Number(hour) * 36e8 + Number(minute) * 6e7 + Math.round(Number(second) * 1e6);
+  } else
+    return void 0;
+  switch (field) {
+    case "hour":
+      return Math.trunc(usecs / 36e8);
+    case "minute":
+      return Math.trunc(usecs / 6e7) % 60;
+    case "second":
+      return usecs % 6e7 / 1e6;
+    case "milliseconds":
+      return usecs % 6e7 / 1e3;
+    case "microseconds":
+      return usecs % 6e7;
+    case "epoch":
+      return interval ? (Math.trunc(months / 12) * 365.25 + months % 12 * 30 + days) * 86400 + usecs / 1e6 : usecs / 1e6;
+  }
+  if (interval) {
+    const years = Math.trunc(months / 12);
+    switch (field) {
+      case "year":
+        return years;
+      case "month":
+        return months % 12;
+      case "day":
+        return days;
+      case "quarter":
+        return Math.trunc(months % 12 / 3) + 1;
+      case "decade":
+        return Math.trunc(years / 10);
+      case "century":
+        return Math.trunc(years / 100);
+      case "millennium":
+        return Math.trunc(years / 1e3);
+    }
+  }
+  throw new TypeError(`Cannot extract ${field} from ${interval ? "INTERVAL" : "TIME"}`);
+}
+function structuredDomainCompare(left, right) {
+  if (typeof left !== "string" || typeof right !== "string")
+    return void 0;
+  const array = left.startsWith(ARRAY_VALUE) && right.startsWith(ARRAY_VALUE);
+  const jsonb = left.startsWith(JSONB_VALUE) && right.startsWith(JSONB_VALUE);
+  if (!array && !jsonb)
+    return void 0;
+  if (left === right)
+    return 0;
+  const prefix = array ? ARRAY_VALUE : JSONB_VALUE;
+  const a = JSON.parse(left.slice(prefix.length));
+  const b = JSON.parse(right.slice(prefix.length));
+  if (array && Array.isArray(a) && Array.isArray(b)) {
+    for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+      const x = a[index];
+      const y = b[index];
+      const order = x === null || y === null ? x === y ? 0 : x === null ? 1 : -1 : compareJsonStructure(x, y);
+      if (order !== 0)
+        return order;
+    }
+    return a.length - b.length;
+  }
+  if (Array.isArray(a) && a.length === 0)
+    return Array.isArray(b) && b.length === 0 ? 0 : -1;
+  if (Array.isArray(b) && b.length === 0)
+    return 1;
+  return compareJsonStructure(a, b);
+}
+function compareJsonStructure(left, right) {
+  if (left === right)
+    return 0;
+  const rank = (value) => value === null ? 0 : typeof value === "string" ? 1 : typeof value === "number" ? 2 : typeof value === "boolean" ? 3 : Array.isArray(value) ? 4 : 5;
+  const difference = rank(left) - rank(right);
+  if (difference !== 0)
+    return difference;
+  if (typeof left === "number" && typeof right === "number")
+    return left - right;
+  if (typeof left === "string" && typeof right === "string")
+    return left < right ? -1 : 1;
+  if (typeof left === "boolean" && typeof right === "boolean")
+    return Number(left) - Number(right);
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length)
+      return left.length - right.length;
+    for (let index = 0; index < left.length; index += 1) {
+      const order = compareJsonStructure(left[index], right[index]);
+      if (order !== 0)
+        return order;
+    }
+    return 0;
+  }
+  const a = left;
+  const b = right;
+  const encoder = new TextEncoder();
+  const keyOrder = (x, y) => encoder.encode(x).length - encoder.encode(y).length || (x === y ? 0 : x < y ? -1 : 1);
+  const keysA = Object.keys(a).sort(keyOrder);
+  const keysB = Object.keys(b).sort(keyOrder);
+  if (keysA.length !== keysB.length)
+    return keysA.length - keysB.length;
+  for (let index = 0; index < keysA.length; index += 1) {
+    const x = keysA[index] ?? "";
+    const y = keysB[index] ?? "";
+    if (x !== y)
+      return x < y ? -1 : 1;
+    const order = compareJsonStructure(a[x], b[y]);
+    if (order !== 0)
+      return order;
+  }
+  return 0;
+}
 export {
   arrayDomainValue,
   boundedJsonText,
@@ -751,6 +870,8 @@ export {
   normalizeSqlDomainValue,
   preservedJsonDomainValue,
   protectedSqlTextValue,
+  structuredDomainCompare,
+  temporalDomainPart,
   timeDomainValue,
   uuidDomainValue
 };

package/dist/engine/sql-semantics.js

@@ -1,7 +1,7 @@
 import { dateMilliseconds } from "../date-value.js";
 import { assertWellFormedString } from "../block-format/unicode.js";
 import { MAX_SQL_NESTING_DEPTH, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS } from "./cache-limits.js";
-import { collatedDomainCompare, enumDomainCompare, exactNumericCompare, externalSqlDomainValue, externalSqlTextValue, intervalDomainCompare, isDateDomainValue, isSqlDomainValue } from "./sql-domains.js";
+import { structuredDomainCompare, collatedDomainCompare, enumDomainCompare, exactNumericCompare, externalSqlDomainValue, externalSqlTextValue, intervalDomainCompare, isDateDomainValue, isSqlDomainValue } from "./sql-domains.js";
 const SQL_TIMESTAMP_TEXT = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?))?(Z|[+-]\d{2}:?\d{2})?$/;
 function parseSqlTimestampText(text) {
   const match = SQL_TIMESTAMP_TEXT.exec(text.trim());
@@ -33,9 +33,9 @@ function readUntypedText(type, text) {
   }
   if (type === "boolean") {
     const lowered = text.trim().toLowerCase();
-    if (lowered === "t" || lowered === "true" || lowered === "1")
+    if (/^(?:t(?:r(?:u(?:e)?)?)?|y(?:e(?:s)?)?|on|1)$/.test(lowered))
       return true;
-    if (lowered === "f" || lowered === "false" || lowered === "0")
+    if (/^(?:f(?:a(?:l(?:s(?:e)?)?)?)?|n(?:o)?|of(?:f)?|0)$/.test(lowered))
       return false;
   }
   return text;
@@ -72,6 +72,9 @@ function compareSqlValues(left, right) {
     }
     return compareSqlStrings(plainLeft, plainRight);
   }
+  const structured = structuredDomainCompare(left, right);
+  if (structured !== void 0)
+    return structured;
   const collated = collatedDomainCompare(left, right);
   if (collated !== void 0)
     return collated;
@@ -347,7 +350,7 @@ function generalLikeMatcher(tokens, caseInsensitive) {
 }
 function compileLikePattern(pattern, caseInsensitive = false, escape) {
   assertBoundedPattern(pattern, "LIKE pattern");
-  const exactEscape = escape === void 0 ? void 0 : exactSingleCharacter(escape, "LIKE escape");
+  const exactEscape = escape === void 0 || escape === "" ? void 0 : exactSingleCharacter(escape, "LIKE escape");
   const key = JSON.stringify([caseInsensitive, exactEscape ?? null, pattern]);
   const cached = cachedPattern(likeCache, key);
   if (cached !== void 0)

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

@@ -1,7 +1,10 @@
-import type { LiveQueryInput, LiveQueryObserveOptions } from "./live.js";
+import type { LiveQueryInput, LiveQueryObserveOptions, LiveQuerySubscribeOptions } from "./live.js";
+import type { QueryResult } from "./query.js";
 /** The structural live-query surface shared by MinnowDatabase and its worker client. */
 export interface LiveQueryBackend {
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscriptionLike>;
+    /** Result delivery, used when the source can decode the engine's result itself. */
+    subscribe?(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscriptionLike>;
     refresh(): Promise<void>;
     close(): void | Promise<void>;
 }
@@ -22,6 +25,14 @@ export interface LiveQueryDriver {
 export interface LiveQuerySource<out TRow> {
     readonly query: LiveQueryInput;
     execute(signal?: AbortSignal): Promise<readonly TRow[]>;
+    /**
+     * Turns a result the engine delivered into the adapter's rows. With it, the query subscribes
+     * for results rather than invalidations: the engine executes or patches the statement where
+     * the data is, compares, and hands over a changed result once — over a worker channel, as
+     * one columnar transfer — and `execute` is never called after the statement is registered.
+     * Without it, an invalidation is followed by `execute`, which the engine's memo serves.
+     */
+    decode?(result: QueryResult): readonly TRow[] | Promise<readonly TRow[]>;
 }
 export type LiveSnapshot<TRow> = {
     readonly status: "loading";

package/dist/engine/typed-live.js

@@ -1,6 +1,26 @@
 import { sameLiveValue } from "./live-equal.js";
-function immutableRows(rows) {
-  return Object.freeze([...rows]);
+function reconcileRows(previous, next, retained) {
+  const rows = new Array(next.length);
+  let changed = previous.length !== next.length;
+  const provenance = retained?.length === next.length ? retained : void 0;
+  for (let index = 0; index < next.length; index += 1) {
+    const row = next[index];
+    const was = provenance?.[index] ?? -1;
+    if (was >= 0 && was < previous.length && sameLiveValue(previous[was], row)) {
+      rows[index] = previous[was];
+      if (was !== index)
+        changed = true;
+      continue;
+    }
+    const before = previous[index];
+    if (index < previous.length && sameLiveValue(before, row))
+      rows[index] = before;
+    else {
+      rows[index] = row;
+      changed = true;
+    }
+  }
+  return changed ? Object.freeze(rows) : void 0;
 }
 class LiveQuery {
   #listeners = /* @__PURE__ */ new Set();
@@ -11,10 +31,14 @@ class LiveQuery {
   #subscription;
   #observationGeneration = 0;
   #queued;
+  #lastDelivered;
+  #deliveriesReceived = 0;
+  #rowsFromDelivery = 0;
   #execution;
   #executionAbort;
   #invalidationSequence = 0;
   #closed = false;
+  #refreshLeases = 0;
   constructor(backend, source, onClose) {
     this.#backend = backend;
     this.#source = source;
@@ -34,27 +58,48 @@ class LiveQuery {
         return;
       subscribed = false;
       this.#listeners.delete(registered);
-      if (this.#listeners.size === 0)
+      if (this.#listeners.size === 0 && this.#refreshLeases === 0)
         this.#stopObservation();
     };
   };
   async refresh() {
     if (this.#closed)
       throw new Error("Live query is closed");
-    const sequence = this.#invalidationSequence;
-    if (this.#listeners.size > 0) {
-      if (this.#subscription === void 0)
-        this.#startObservation();
-      const opening = this.#subscription;
-      if (opening !== void 0)
-        await opening.catch(() => void 0);
-      await this.#backend.refresh();
-    }
-    if (this.#invalidationSequence === sequence) {
-      const version = this.#snapshot.status === "loading" ? null : this.#snapshot.version;
-      this.#schedule({ manifestVersion: version, catalogEpoch: 0, initial: false });
+    this.#refreshLeases += 1;
+    try {
+      const sequence = this.#invalidationSequence;
+      if (this.#listeners.size > 0 || this.#decodes()) {
+        if (this.#subscription === void 0)
+          this.#startObservation();
+        const opening = this.#subscription;
+        if (opening !== void 0)
+          await opening.catch(() => void 0);
+        await this.#backend.refresh();
+      }
+      if (this.#invalidationSequence === sequence) {
+        const version = this.#snapshot.status === "loading" ? null : this.#snapshot.version;
+        if (this.#decodes()) {
+          const last = this.#lastDelivered;
+          if (this.#snapshot.status === "error" && last !== void 0)
+            this.#schedule(last);
+        } else
+          this.#schedule({ manifestVersion: version, catalogEpoch: 0, initial: false });
+      }
+      await this.#waitForIdle();
+    } finally {
+      this.#refreshLeases -= 1;
+      if (this.#refreshLeases === 0 && this.#listeners.size === 0)
+        this.#stopObservation();
     }
-    await this.#waitForIdle();
+  }
+  #decodes() {
+    return this.#source.decode !== void 0 && this.#backend.subscribe !== void 0;
+  }
+  async #decodeDelivered(result) {
+    const source = this.#source;
+    if (source.decode === void 0)
+      throw new TypeError("Live query source lost its decoder");
+    return source.decode(result);
   }
   close() {
     if (this.#closed)
@@ -75,7 +120,36 @@ class LiveQuery {
     if (this.#subscription !== void 0 || this.#closed)
       return;
     const generation = this.#observationGeneration += 1;
+    if (this.#source.decode !== void 0 && this.#backend.subscribe !== void 0) {
+      const subscription2 = this.#backend.subscribe(this.#source.query, {
+        onChange: (result, delivery) => {
+          if (generation !== this.#observationGeneration || this.#closed)
+            return;
+          this.#deliveriesReceived += 1;
+          this.#schedule({ result, delivery, sequence: this.#deliveriesReceived });
+        },
+        onError: (error) => {
+          if (generation !== this.#observationGeneration || this.#closed)
+            return;
+          this.#setError(error, this.#currentVersion());
+        },
+        onComplete: () => {
+          if (generation !== this.#observationGeneration)
+            return;
+          this.#subscription = void 0;
+        }
+      });
+      this.#subscription = subscription2;
+      subscription2.catch((error) => {
+        if (generation !== this.#observationGeneration || this.#closed)
+          return;
+        this.#subscription = void 0;
+        this.#setError(error, this.#currentVersion());
+      });
+      return;
+    }
     const subscription = this.#backend.observe(this.#source.query, {
+      suppressUnchanged: true,
       onInvalidate: (invalidation) => {
         if (generation !== this.#observationGeneration || this.#closed)
           return;
@@ -109,9 +183,9 @@ class LiveQuery {
       void subscription.then((handle) => handle.close()).catch(() => void 0);
     }
   }
-  #schedule(invalidation) {
+  #schedule(work) {
     this.#invalidationSequence += 1;
-    this.#queued = invalidation;
+    this.#queued = work;
     if (this.#execution !== void 0)
       return;
     const execution = this.#drain();
@@ -125,24 +199,35 @@ class LiveQuery {
   }
   async #drain() {
     while (this.#queued !== void 0 && !this.#closed) {
-      const invalidation = this.#queued;
+      const work = this.#queued;
       this.#queued = void 0;
       const abort = new AbortController();
       this.#executionAbort = abort;
+      const invalidation = "result" in work ? work.delivery : work;
       try {
-        const rows = immutableRows(await this.#source.execute(abort.signal));
+        let executed;
+        if ("result" in work) {
+          this.#lastDelivered = work;
+          executed = await this.#decodeDelivered(work.result);
+          this.#lastDelivered = void 0;
+        } else
+          executed = await this.#source.execute(abort.signal);
         if (this.#executionWasCancelled(abort))
           continue;
         if (this.#hasQueuedInvalidation())
           continue;
         const previous = this.#snapshot.rows;
-        if (this.#snapshot.status === "ready" && this.#snapshot.version === invalidation.manifestVersion && sameLiveValue(previous, rows)) {
-          continue;
-        }
-        if (sameLiveValue(previous, rows) && this.#snapshot.status !== "loading") {
+        const provenance = "result" in work && this.#rowsFromDelivery === work.sequence - 1 ? work.delivery.retained : void 0;
+        const rows = reconcileRows(previous, executed, provenance);
+        if ("result" in work)
+          this.#rowsFromDelivery = work.sequence;
+        if (rows === void 0) {
+          if (this.#snapshot.status === "ready" && this.#snapshot.version === invalidation.manifestVersion) {
+            continue;
+          }
           this.#snapshot = {
             status: "ready",
-            rows: previous,
+            rows: this.#snapshot.status === "loading" ? Object.freeze([...previous]) : previous,
             version: invalidation.manifestVersion
           };
         } else {

package/dist/engine/windows.d.ts

@@ -0,0 +1,12 @@
+import type { QueryResult, WindowSpec } from "../plan/model.js";
+import { QueryMemoryContext } from "./memory.js";
+interface WindowOptions {
+    copyRows?: boolean;
+    memoryContext?: QueryMemoryContext;
+    signal?: AbortSignal;
+}
+/** Synchronous executor used by standalone queries; shares every kernel with asynchronous reads. */
+export declare function applyWindowFunctions(result: QueryResult, windows: readonly WindowSpec[], options?: WindowOptions): QueryResult;
+/** Cooperatively runs window passes so cancellation can arrive while a large partition is active. */
+export declare function applyWindowFunctionsAsync(result: QueryResult, windows: readonly WindowSpec[], options?: WindowOptions): Promise<QueryResult>;
+export {};