mindoodb 0.0.63 → 0.0.64

package/dist/core/query/queryInternals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryInternals.js","sourceRoot":"","sources":["../../../src/core/query/queryInternals.ts"],"names":[],"mappings":"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"}

package/dist/core/query/queryLive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryLive.d.ts","sourceRoot":"","sources":["../../../src/core/query/queryLive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAErF,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAElF,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,WAAW,IAAI,IAAI,CAAC;IACpB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,EAC7C,OAAO,CAAC,EAAE,kBAAkB,GAAG;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,GACpE,uBAAuB,CAwEzB"}
+{"version":3,"file":"queryLive.d.ts","sourceRoot":"","sources":["../../../src/core/query/queryLive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAErF,OAAO,KAAK,EACV,WAAW,EAEX,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAEjB,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,WAAW,IAAI,IAAI,CAAC;IACpB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAgFD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,EAC7C,OAAO,CAAC,EAAE,kBAAkB,GAAG;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,GACpE,uBAAuB,CAkFzB"}

package/dist/core/query/queryLive.js

@@ -12,16 +12,67 @@ const executeQuery_1 = require("./executeQuery");
  * or removing documents shifts BM25 statistics slightly for every other
  * match, and re-pushing an unchanged result list over marginal score
  * drift would spam subscribers.
+ *
+ * Included rows participate recursively. Without that, editing a line
+ * item would leave the invoice's own `lastModified` untouched and the
+ * subscriber would never hear about a change to data it was handed.
  */
 function fingerprintResult(result) {
     const parts = [String(result.total)];
     for (const row of result.rows) {
-        parts.push(row.textScore === undefined
-            ? `${row.docId}:${row.lastModified}`
-            : `${row.docId}:${row.lastModified}:${row.textScore.toFixed(2)}`);
+        appendRowFingerprint(parts, row);
     }
     return parts.join("|");
 }
+function appendRowFingerprint(parts, row) {
+    parts.push(row.textScore === undefined
+        ? `${row.docId}:${row.lastModified}`
+        : `${row.docId}:${row.lastModified}:${row.textScore.toFixed(2)}`);
+    if (!row.includes) {
+        return;
+    }
+    for (const [slot, slotValue] of Object.entries(row.includes)) {
+        if (slotValue === null) {
+            parts.push(`${slot}:-`);
+            continue;
+        }
+        if (Array.isArray(slotValue)) {
+            parts.push(`${slot}:${slotValue.length}`);
+            for (const child of slotValue) {
+                appendRowFingerprint(parts, child);
+            }
+            continue;
+        }
+        parts.push(`${slot}:1`);
+        appendRowFingerprint(parts, slotValue);
+    }
+}
+/**
+ * Every database a query reads from: the root plus each `include.db`
+ * (recursively; an include without one stays on its parent's database).
+ * Deduplicated by instance, so two slots on the same database do not
+ * install two listeners.
+ */
+function collectQueryDatabases(db, query) {
+    const databases = [db];
+    const seen = new Set([db]);
+    const walk = (includes, parentDb) => {
+        for (const include of Object.values(includes)) {
+            const target = include.db ?? parentDb;
+            if (!seen.has(target)) {
+                seen.add(target);
+                databases.push(target);
+            }
+            if (include.include) {
+                walk(include.include, target);
+            }
+        }
+    };
+    if (query.include) {
+        walk(query.include, db);
+    }
+    return databases;
+}
 /**
  * Live query: delivers the initial result, keeps the summary current via
  * the database's change listener, and re-evaluates the query after every
@@ -33,8 +84,14 @@ function fingerprintResult(result) {
  * errors are reported through `onError` (or logged to the console).
  */
 function executeQueryLive(db, summary, query, onResult, options) {
-    if (!db.addChangeListener) {
-        throw new Error("This MindooDB instance does not support change listeners.");
+    // A live query with includes is only live if it watches every database
+    // it reads from — a changed customer must push just like a changed
+    // invoice does.
+    const databases = collectQueryDatabases(db, query);
+    for (const database of databases) {
+        if (!database.addChangeListener) {
+            throw new Error("This MindooDB instance does not support change listeners.");
+        }
     }
     let lastFingerprint = null;
     let unsubscribed = false;
@@ -81,17 +138,19 @@ function executeQueryLive(db, summary, query, onResult, options) {
             running = false;
         }
     };
-    const removeListener = db.addChangeListener(() => {
+    const removeListeners = databases.map((database) => database.addChangeListener(() => {
         if (!unsubscribed) {
             void run(false);
         }
-    });
+    }));
     // Deliver the initial result asynchronously.
     void run(true);
     return {
         unsubscribe() {
             unsubscribed = true;
-            removeListener();
+            for (const removeListener of removeListeners) {
+                removeListener();
+            }
         },
         async refresh() {
             if (unsubscribed) {

package/dist/core/query/queryLive.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryLive.js","sourceRoot":"","sources":["../../../src/core/query/queryLive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queryLive.js","sourceRoot":"","sources":["../../../src/core/query/queryLive.ts"],"names":[],"mappings":";;AA8GA,4CAwFC;AApMD,iDAA8C;AAoB9C;;;;;;;;;;;;;;GAcG;AACH,SAAS,iBAAiB,CAAC,MAAyB;IAClD,MAAM,KAAK,GAAa,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,oBAAoB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAe,EAAE,GAAmB;IAChE,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,SAAS,KAAK,SAAS;QACzB,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,YAAY,EAAE;QACpC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACnE,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClB,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7D,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC9B,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACrC,CAAC;YACD,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QACxB,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAAC,EAAY,EAAE,KAAkB;IAC7D,MAAM,SAAS,GAAe,CAAC,EAAE,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAW,CAAC,EAAE,CAAC,CAAC,CAAC;IAErC,MAAM,IAAI,GAAG,CAAC,QAA4C,EAAE,QAAkB,EAAQ,EAAE;QACtF,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,QAAQ,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAC9B,EAAY,EACZ,OAA6B,EAC7B,KAAkB,EAClB,QAA6C,EAC7C,OAAqE;IAErE,uEAAuE;IACvE,mEAAmE;IACnE,gBAAgB;IAChB,MAAM,SAAS,GAAG,qBAAqB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACnD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED,IAAI,eAAe,GAAkB,IAAI,CAAC;IAC1C,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,WAAW,GAAG,CAAC,KAAc,EAAQ,EAAE;QAC3C,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;QACjE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,EAAE,KAAc,EAAiB,EAAE;QACvD,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAY,EAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,KAAK,IAAI,WAAW,KAAK,eAAe,EAAE,CAAC;YAC7C,eAAe,GAAG,WAAW,CAAC;YAC9B,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,KAAK,EAAE,KAAc,EAAiB,EAAE;QAClD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,IAAI,CAAC;YACf,OAAO;QACT,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC;YACH,GAAG,CAAC;gBACF,OAAO,GAAG,KAAK,CAAC;gBAChB,IAAI,CAAC;oBACH,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACxB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,WAAW,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;gBACD,KAAK,GAAG,KAAK,CAAC;YAChB,CAAC,QAAQ,OAAO,IAAI,CAAC,YAAY,EAAE;QACrC,CAAC;gBAAS,CAAC;YACT,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,eAAe,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CACjD,QAAQ,CAAC,iBAAkB,CAAC,GAAG,EAAE;QAC/B,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,6CAA6C;IAC7C,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IAEf,OAAO;QACL,WAAW;YACT,YAAY,GAAG,IAAI,CAAC;YACpB,KAAK,MAAM,cAAc,IAAI,eAAe,EAAE,CAAC;gBAC7C,cAAc,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,YAAY,EAAE,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/query/queryView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryView.d.ts","sourceRoot":"","sources":["../../../src/core/query/queryView.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queryView.d.ts","sourceRoot":"","sources":["../../../src/core/query/queryView.ts"],"names":[],"mappings":"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"}

package/dist/core/query/queryView.js

@@ -171,6 +171,23 @@ exports.EphemeralSummaryView = EphemeralSummaryView;
  * the match, `_textScoreRaw` the engine's raw score.
  */
 const TEXT_SCORE_FIELDS = new Set(["_textScore", "_textScoreRaw"]);
+/**
+ * Reject an expression the evaluator does not define.
+ *
+ * Same trap as in `db.query()`: an unrecognized node evaluates to
+ * `undefined`, which silently drops every row (in a filter) or blanks a
+ * column instead of reporting the mistake. View definitions take expressions
+ * only — formula source text has to be parsed by the caller, and saying so
+ * is more useful than an empty view.
+ */
+function assertKnownExpression(expression, role) {
+    const unknown = (0, expressions_1.findUnknownExpressionNode)(expression);
+    if (unknown !== null) {
+        throw new types_1.MindooQueryError(`View ${role} contains ${unknown}, which the expression language does not define ` +
+            `(build it with createViewLanguage(), or parse formula text with ` +
+            `parseMindooDBFormulaBooleanExpression()).`);
+    }
+}
 /**
  * Guardrails mirroring `db.query()`: expressions must be answerable from
  * the summary buffers (no decrypt, no view-tree operations in filters,
@@ -185,6 +202,7 @@ function validateViewDefinition(sources, definition) {
         if (!expression) {
             continue;
         }
+        assertKnownExpression(expression, "column");
         const requirements = (0, expressions_1.analyzeExpressionRequirements)(expression);
         if (requirements.needsDecryption) {
             throw new types_1.MindooQueryError("View columns cannot use decrypt expressions: encrypted fields are not stored in the summary buffer.");
@@ -197,6 +215,7 @@ function validateViewDefinition(sources, definition) {
         const referencedPaths = new Set(columnPaths);
         const filter = source.filter ?? definition.filter;
         if (filter) {
+            assertKnownExpression(filter, "filter");
             const requirements = (0, expressions_1.analyzeExpressionRequirements)(filter);
             if (requirements.needsViewContext) {
                 throw new types_1.MindooQueryError(`View filters cannot use view-tree operations (${requirements.viewContextOperations.join(", ")}).`);

package/dist/core/query/queryView.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryView.js","sourceRoot":"","sources":["../../../src/core/query/queryView.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queryView.js","sourceRoot":"","sources":["../../../src/core/query/queryView.ts"],"names":[],"mappings":"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"}

package/dist/core/query/types.d.ts

@@ -1,6 +1,7 @@
 import type { MindooDBAppBooleanExpression, MindooDBAppExpression } from "../expressions/types";
 import type { SummaryCoverage } from "../indexing/summary/types";
 import type { VirtualViewUpdateOptions } from "../indexing/virtualviews/IVirtualViewDataProvider";
+import type { MindooDB } from "../types";
 /**
  * One sort key of a {@link MindooQuery}. Either a plain summary field
  * path, a computed expression (evaluated per row before comparison), or a
@@ -43,17 +44,83 @@ export interface MindooQueryTextClause {
     /** How multiple terms combine: `"AND"` (default) or `"OR"`. */
     combineWith?: "AND" | "OR";
 }
+/**
+ * Whether an include slot resolves to a single related row or a list of
+ * them. Always explicit: a lookup that happens to match exactly one
+ * document today must not silently change shape tomorrow, so `"one"`
+ * with more than one match is an error rather than an implicit array.
+ */
+export type MindooQueryIncludeCardinality = "one" | "many";
+/**
+ * Default `limit` of a `"many"` include slot — the cap that keeps one
+ * pathological parent (a customer with 50k invoices) from dominating a
+ * result. Raise it per slot when you really want more.
+ */
+export declare const DEFAULT_INCLUDE_LIMIT = 200;
+/**
+ * Maximum include nesting, counting the query's own `include` as level 1
+ * (so `invoice → customer → address` is level 2). A guard against
+ * accidentally exponential join plans, not a fundamental limit.
+ */
+export declare const MAX_INCLUDE_DEPTH = 3;
+/**
+ * One nested lookup of a {@link MindooQuery} (see docs/adhoc-queries.md).
+ *
+ * Related documents are joined onto every paged result row under
+ * `MindooQueryRow.includes[slot]`. The join runs as ONE additional
+ * summary scan per slot, never a query per parent row.
+ */
+export interface MindooQueryInclude {
+    /**
+     * Database to look the related documents up in. Omit for the same
+     * database as the parent query. This is a runtime handle, not an id —
+     * the only part of a query object that is not plain JSON.
+     */
+    db?: MindooDB;
+    /** Required: `"one"` yields a row or `null`, `"many"` yields an array. */
+    cardinality: MindooQueryIncludeCardinality;
+    /**
+     * Shorthand join: match children whose `docId` equals this PARENT field
+     * (or, when the parent value is an array, is contained in it). Sugar for
+     * `filter: v.eq(v.field("docId"), v.parent(localKey))`; combined with an
+     * explicit `filter` via logical AND.
+     */
+    localKey?: string;
+    /**
+     * Join condition, or its formula source text. Must contain exactly one
+     * parent equality — `v.eq(v.field(childPath), v.parent(parentPath))`
+     * in either operand order — optionally ANDed with conditions that do
+     * not reference the parent (those are applied as plain child
+     * predicates). Everything else is rejected: the equality is what lets
+     * the engine answer the slot with a single indexed scan instead of a
+     * nested loop over parents x children.
+     */
+    filter?: MindooDBAppBooleanExpression | string;
+    /** Projection for the related rows; defaults to all summary fields. */
+    fields?: string[];
+    /** Ordering within one parent's list. `"many"` only; defaults to `docId`. */
+    sortBy?: MindooQuerySortKey[];
+    /** Max related rows per parent. `"many"` only; defaults to {@link DEFAULT_INCLUDE_LIMIT}. */
+    limit?: number;
+    /** Nested lookups on the related rows (see {@link MAX_INCLUDE_DEPTH}). */
+    include?: Record<string, MindooQueryInclude>;
+}
 /**
  * An ad-hoc query over the document summary buffer (see
  * docs/adhoc-queries.md).
  *
  * The filter IS an expression of the MindooDB expression language — built
- * with `createViewLanguage()` or parsed from formula text with
- * `parseMindooDBFormulaBooleanExpression()` — so query definitions are
- * plain JSON and travel safely across process boundaries.
+ * with `createViewLanguage()` — so query definitions are plain JSON and
+ * travel safely across process boundaries.
  */
 export interface MindooQuery {
-    filter?: MindooDBAppBooleanExpression;
+    /**
+     * Boolean expression, or the formula source text of one (e.g.
+     * `'v.eq(v.field("type"), "invoice")'`), which `query()` parses for you —
+     * the same convenience the app SDK offers, so a query object written for
+     * one works with the other.
+     */
+    filter?: MindooDBAppBooleanExpression | string;
     /**
      * Full-text clause: additionally require documents to match this
      * full-text search (combined with `filter` as a logical AND). Adds a
@@ -69,7 +136,28 @@ export interface MindooQuery {
      * summary fields of the matching document.
      */
     fields?: string[];
+    /**
+     * Nested lookups: related documents joined onto every returned row
+     * under {@link MindooQueryRow.includes}, keyed by slot name. Slot names
+     * are free-form — they live in their own object, so none of them can
+     * collide with `docId` / `fields` / `lastModified`.
+     *
+     * Hydration happens AFTER `sortBy`/`limit`/`offset`, so only the rows
+     * actually returned are joined; `total` stays the unpaged match count
+     * of the root query.
+     */
+    include?: Record<string, MindooQueryInclude>;
 }
+/** A {@link MindooQueryInclude} whose formula-source filter has been parsed. */
+export type ParsedMindooQueryInclude = Omit<MindooQueryInclude, "filter" | "include"> & {
+    filter?: MindooDBAppBooleanExpression;
+    include?: Record<string, ParsedMindooQueryInclude>;
+};
+/** A {@link MindooQuery} whose formula-source filters have been parsed. */
+export type ParsedMindooQuery = Omit<MindooQuery, "filter" | "include"> & {
+    filter?: MindooDBAppBooleanExpression;
+    include?: Record<string, ParsedMindooQueryInclude>;
+};
 export interface MindooQueryOptions extends VirtualViewUpdateOptions {
     /**
      * Escape hatch: materialize every document via the changefeed instead of
@@ -79,7 +167,13 @@ export interface MindooQueryOptions extends VirtualViewUpdateOptions {
      */
     allowFullScan?: boolean;
 }
-export interface MindooQueryRow {
+/**
+ * The related rows joined onto one result row, keyed by include slot
+ * name: a row (or `null`) for `cardinality: "one"`, an array for
+ * `"many"`.
+ */
+export type MindooQueryIncludeSlots = Record<string, MindooQueryRow | MindooQueryRow[] | null>;
+export interface MindooQueryRow<TIncludes extends MindooQueryIncludeSlots = MindooQueryIncludeSlots> {
     docId: string;
     fields: Record<string, unknown>;
     lastModified: number;
@@ -88,6 +182,22 @@ export interface MindooQueryRow {
      * match). Only present when the query had a `text` clause.
      */
     textScore?: number;
+    /**
+     * Related rows from the query's {@link MindooQuery.include} lookups.
+     * Absent when the query had no `include`, so results of plain queries
+     * keep exactly the shape they always had.
+     *
+     * Included rows are ordinary rows, so a nested lookup reads as
+     * `row.includes.customer.includes.address` — the same rule at every
+     * level. The slots live in their own object rather than next to
+     * `docId`/`fields` so that no relation name can collide with the
+     * protocol and this row's top level stays free for future engine data.
+     *
+     * The generic parameter is a convenience for callers who want precise
+     * slot types (`db.query<{ lines: MindooQueryRow[] }>({…})`); it is not
+     * inferred from the `include` object.
+     */
+    includes?: TIncludes;
 }
 /**
  * Which data answered the query: `"full"`/`"rebuilding"` from the summary
@@ -95,10 +205,15 @@ export interface MindooQueryRow {
  * materialized via `allowFullScan`.
  */
 export type MindooQueryCoverage = SummaryCoverage | "full-scan";
-export interface MindooQueryResult {
-    rows: MindooQueryRow[];
+export interface MindooQueryResult<TIncludes extends MindooQueryIncludeSlots = MindooQueryIncludeSlots> {
+    rows: MindooQueryRow<TIncludes>[];
     /** Number of matching documents before `offset`/`limit` were applied. */
     total: number;
+    /**
+     * Which data answered the query. With `include` lookups this is the
+     * MINIMUM over every involved summary — one child summary still
+     * backfilling makes the whole result `"rebuilding"`.
+     */
     coverage: MindooQueryCoverage;
 }
 /**

package/dist/core/query/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/query/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAC;AAElG;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,WAAW,GAAG,YAAY,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,4BAA4B,CAAC;IACtC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAClE;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,WAAW,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,mBAAmB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,oBAAoB;CAKzD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/query/types.ts"],"names":[],"mappings":"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"}

package/dist/core/query/types.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MindooQueryError = void 0;
+exports.MindooQueryError = exports.MAX_INCLUDE_DEPTH = exports.DEFAULT_INCLUDE_LIMIT = void 0;
+/**
+ * Default `limit` of a `"many"` include slot — the cap that keeps one
+ * pathological parent (a customer with 50k invoices) from dominating a
+ * result. Raise it per slot when you really want more.
+ */
+exports.DEFAULT_INCLUDE_LIMIT = 200;
+/**
+ * Maximum include nesting, counting the query's own `include` as level 1
+ * (so `invoice → customer → address` is level 2). A guard against
+ * accidentally exponential join plans, not a fundamental limit.
+ */
+exports.MAX_INCLUDE_DEPTH = 3;
 /**
  * Thrown for queries that cannot be answered: referenced fields outside the
  * summary coverage, `decrypt`/view-tree expressions without

package/dist/core/query/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/query/types.ts"],"names":[],"mappings":";;;AAsHA;;;;;GAKG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IAIzC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AATD,4CASC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/query/types.ts"],"names":[],"mappings":";;;AAyDA;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,CAAC,CAAC;AA2KnC;;;;;GAKG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IAIzC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AATD,4CASC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "engines": {
     "node": ">=22.13.0"
   },