mindoodb 0.0.24 → 0.0.32

package/dist/core/indexing/summary/extractSummaryFields.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACHMENTS_FIELD = void 0;
+exports.resolveFieldPath = resolveFieldPath;
+exports.estimateValueSize = estimateValueSize;
+exports.extractSummaryFields = extractSummaryFields;
+exports.getSummaryFieldValue = getSummaryFieldValue;
+exports.buildSummaryEvaluationDoc = buildSummaryEvaluationDoc;
+exports.isFieldPathCovered = isFieldPathCovered;
+/**
+ * Resolve a dot-separated path against a plain JS object. Only object
+ * traversal is supported (no array indices) — mirroring the field-path
+ * semantics of the expression language's `getFieldValue`.
+ */
+function resolveFieldPath(data, path) {
+    if (!path.includes(".")) {
+        return data[path];
+    }
+    let current = data;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function isScalar(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+/** Scalars and flat arrays of scalars qualify for auto-include. */
+function isAutoIncludableValue(value) {
+    if (isScalar(value)) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every((item) => isScalar(item));
+    }
+    return false;
+}
+/**
+ * Approximate serialized size of a value (JSON string length). Good enough
+ * as a guard against pathologically large summary values; not an exact
+ * byte count for multi-byte characters.
+ */
+function estimateValueSize(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    if (typeof value === "string") {
+        return value.length + 2;
+    }
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? 0 : json.length;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+function isExcluded(path, exclude) {
+    for (const excluded of exclude) {
+        if (path === excluded || path.startsWith(excluded + ".")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Fields following the encrypted-field convention (`*_encrypted` plus the
+ * `*_encrypted_key` companion). Their values are ciphertext — useless in
+ * the summary (evaluating them requires `decrypt`, which needs the
+ * materialized document anyway), so auto-include skips them. An explicit
+ * `include` still wins for callers who really want the raw ciphertext.
+ */
+function isEncryptedConventionField(key) {
+    return key.endsWith("_encrypted") || key.endsWith("_encrypted_key");
+}
+/** Attachment metadata field managed by MindooDB on every document. */
+exports.ATTACHMENTS_FIELD = "_attachments";
+function projectAttachments(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return undefined;
+    }
+    const projected = [];
+    for (const item of value) {
+        if (item === null || typeof item !== "object") {
+            continue;
+        }
+        const raw = item;
+        const info = {};
+        if (typeof raw.attachmentId === "string")
+            info.attachmentId = raw.attachmentId;
+        if (typeof raw.fileName === "string")
+            info.fileName = raw.fileName;
+        if (typeof raw.size === "number" && Number.isFinite(raw.size))
+            info.size = raw.size;
+        if (typeof raw.mimeType === "string")
+            info.mimeType = raw.mimeType;
+        if (typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)) {
+            info.createdAt = raw.createdAt;
+        }
+        if (typeof raw.extractedText === "string" && raw.extractedText.length > 0) {
+            info.hasExtractedText = true;
+        }
+        projected.push(info);
+    }
+    return projected.length > 0 ? projected : undefined;
+}
+/**
+ * Extract the summary field map for one document payload according to the
+ * resolved configuration:
+ *
+ * 1. auto-include (when enabled): every non-underscore top-level field with
+ *    a scalar (or scalar-array) value whose serialized size stays within
+ *    `maxValueBytes`
+ * 2. explicit `include` paths: any value type, no size cap, keyed by the
+ *    full dot-path
+ * 3. `exclude` wins over both (and covers nested paths)
+ */
+function extractSummaryFields(data, config) {
+    const fields = {};
+    if (config.autoInclude) {
+        for (const [key, value] of Object.entries(data)) {
+            if (key.startsWith("_")) {
+                continue;
+            }
+            if (isEncryptedConventionField(key)) {
+                continue;
+            }
+            if (isExcluded(key, config.exclude)) {
+                continue;
+            }
+            if (!isAutoIncludableValue(value)) {
+                continue;
+            }
+            if (estimateValueSize(value) > config.maxValueBytes) {
+                continue;
+            }
+            fields[key] = value;
+        }
+    }
+    for (const path of config.include) {
+        if (isExcluded(path, config.exclude)) {
+            continue;
+        }
+        const value = resolveFieldPath(data, path);
+        if (value !== undefined) {
+            fields[path] = value;
+        }
+    }
+    // Managed attachment metadata: stored as a slim projection so attachment
+    // expressions work on the summary path without dragging internal
+    // plumbing or the creator's signing key into every bucket.
+    if (config.includeAttachments && !isExcluded(exports.ATTACHMENTS_FIELD, config.exclude)) {
+        const attachments = projectAttachments(data[exports.ATTACHMENTS_FIELD]);
+        if (attachments !== undefined) {
+            fields[exports.ATTACHMENTS_FIELD] = attachments;
+        }
+    }
+    return fields;
+}
+/**
+ * Path-aware lookup on an extracted summary field map: explicit include
+ * entries are stored under their full dot-path, auto-included fields under
+ * the top-level name (so nested lookups traverse the stored value).
+ */
+function getSummaryFieldValue(fields, path) {
+    if (Object.prototype.hasOwnProperty.call(fields, path)) {
+        return fields[path];
+    }
+    return resolveFieldPath(fields, path);
+}
+/**
+ * Builds the document object expressions are evaluated against from a
+ * stored summary field map. Explicit include entries are stored flat under
+ * their full dot-path (`"meta.owner"`); expression evaluation resolves
+ * `field` paths by object traversal, so dot-keys are expanded into nested
+ * objects here. Maps without dot-keys are returned as-is (no copy).
+ *
+ * When `lastModified` is passed, it is mirrored as `_lastModified` (the
+ * managed timestamp field of the materialized document), so expressions
+ * referencing it behave identically on the summary and document paths.
+ */
+function buildSummaryEvaluationDoc(fields, lastModified) {
+    let hasDotKey = false;
+    for (const key of Object.keys(fields)) {
+        if (key.includes(".")) {
+            hasDotKey = true;
+            break;
+        }
+    }
+    if (!hasDotKey) {
+        if (lastModified === undefined) {
+            return fields;
+        }
+        return { ...fields, _lastModified: lastModified };
+    }
+    const doc = {};
+    if (lastModified !== undefined) {
+        doc._lastModified = lastModified;
+    }
+    for (const [key, value] of Object.entries(fields)) {
+        if (!key.includes(".")) {
+            doc[key] = value;
+            continue;
+        }
+        const parts = key.split(".");
+        let current = doc;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const next = current[parts[i]];
+            if (next !== null && typeof next === "object" && !Array.isArray(next)) {
+                current = next;
+            }
+            else {
+                const created = {};
+                current[parts[i]] = created;
+                current = created;
+            }
+        }
+        current[parts[parts.length - 1]] = value;
+    }
+    return doc;
+}
+/**
+ * Whether a field path is covered by the summary configuration, i.e.
+ * queries against it can be answered from the summary buffer.
+ *
+ * Top-level fields (and nested paths below them) are covered by
+ * auto-include; nested paths are additionally covered when explicitly
+ * included. Excluded paths are never covered. Note that coverage is a
+ * configuration-level statement — an individual document may still lack a
+ * value (missing field, non-scalar value, or above the size cap).
+ */
+function isFieldPathCovered(path, config) {
+    if (isExcluded(path, config.exclude)) {
+        return false;
+    }
+    for (const included of config.include) {
+        if (path === included || path.startsWith(included + ".")) {
+            return true;
+        }
+    }
+    const topLevel = path.includes(".") ? path.slice(0, path.indexOf(".")) : path;
+    // Managed fields with special handling: the slim attachment projection
+    // (when enabled) and the always-mirrored modification timestamp.
+    if (topLevel === exports.ATTACHMENTS_FIELD) {
+        return config.includeAttachments;
+    }
+    if (path === "_lastModified") {
+        return true;
+    }
+    if (config.autoInclude && !topLevel.startsWith("_")) {
+        // Encrypted-convention fields are skipped by auto-include (ciphertext
+        // is not queryable); only an explicit include covers them (above).
+        if (isEncryptedConventionField(topLevel)) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=extractSummaryFields.js.map

package/dist/core/indexing/summary/extractSummaryFields.js.map

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

package/dist/core/indexing/summary/index.d.ts

@@ -0,0 +1,5 @@
+export { DocumentSummaryStore } from "./DocumentSummaryStore";
+export { SummaryVirtualViewDataProvider, type SummaryVirtualViewDataProviderOptions, } from "./SummaryVirtualViewDataProvider";
+export { resolveSummaryConfig, computeSummaryConfigFingerprint, sanitizeSummaryConfig, DEFAULT_SUMMARY_MAX_VALUE_BYTES, DB_SETUP_DOC_ID, SUMMARY_SETUP_FIELD, type SummaryConfig, type ResolvedSummaryConfig, type DocumentSummaryEntry, type SummaryCoverage, } from "./types";
+export { extractSummaryFields, getSummaryFieldValue, isFieldPathCovered, resolveFieldPath, estimateValueSize, buildSummaryEvaluationDoc, ATTACHMENTS_FIELD, type SummaryAttachmentInfo, } from "./extractSummaryFields";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/indexing/summary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/indexing/summary/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAC9B,KAAK,qCAAqC,GAC3C,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,oBAAoB,EACpB,+BAA+B,EAC/B,qBAAqB,EACrB,+BAA+B,EAC/B,eAAe,EACf,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC"}

package/dist/core/indexing/summary/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACHMENTS_FIELD = exports.buildSummaryEvaluationDoc = exports.estimateValueSize = exports.resolveFieldPath = exports.isFieldPathCovered = exports.getSummaryFieldValue = exports.extractSummaryFields = exports.SUMMARY_SETUP_FIELD = exports.DB_SETUP_DOC_ID = exports.DEFAULT_SUMMARY_MAX_VALUE_BYTES = exports.sanitizeSummaryConfig = exports.computeSummaryConfigFingerprint = exports.resolveSummaryConfig = exports.SummaryVirtualViewDataProvider = exports.DocumentSummaryStore = void 0;
+var DocumentSummaryStore_1 = require("./DocumentSummaryStore");
+Object.defineProperty(exports, "DocumentSummaryStore", { enumerable: true, get: function () { return DocumentSummaryStore_1.DocumentSummaryStore; } });
+var SummaryVirtualViewDataProvider_1 = require("./SummaryVirtualViewDataProvider");
+Object.defineProperty(exports, "SummaryVirtualViewDataProvider", { enumerable: true, get: function () { return SummaryVirtualViewDataProvider_1.SummaryVirtualViewDataProvider; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "resolveSummaryConfig", { enumerable: true, get: function () { return types_1.resolveSummaryConfig; } });
+Object.defineProperty(exports, "computeSummaryConfigFingerprint", { enumerable: true, get: function () { return types_1.computeSummaryConfigFingerprint; } });
+Object.defineProperty(exports, "sanitizeSummaryConfig", { enumerable: true, get: function () { return types_1.sanitizeSummaryConfig; } });
+Object.defineProperty(exports, "DEFAULT_SUMMARY_MAX_VALUE_BYTES", { enumerable: true, get: function () { return types_1.DEFAULT_SUMMARY_MAX_VALUE_BYTES; } });
+Object.defineProperty(exports, "DB_SETUP_DOC_ID", { enumerable: true, get: function () { return types_1.DB_SETUP_DOC_ID; } });
+Object.defineProperty(exports, "SUMMARY_SETUP_FIELD", { enumerable: true, get: function () { return types_1.SUMMARY_SETUP_FIELD; } });
+var extractSummaryFields_1 = require("./extractSummaryFields");
+Object.defineProperty(exports, "extractSummaryFields", { enumerable: true, get: function () { return extractSummaryFields_1.extractSummaryFields; } });
+Object.defineProperty(exports, "getSummaryFieldValue", { enumerable: true, get: function () { return extractSummaryFields_1.getSummaryFieldValue; } });
+Object.defineProperty(exports, "isFieldPathCovered", { enumerable: true, get: function () { return extractSummaryFields_1.isFieldPathCovered; } });
+Object.defineProperty(exports, "resolveFieldPath", { enumerable: true, get: function () { return extractSummaryFields_1.resolveFieldPath; } });
+Object.defineProperty(exports, "estimateValueSize", { enumerable: true, get: function () { return extractSummaryFields_1.estimateValueSize; } });
+Object.defineProperty(exports, "buildSummaryEvaluationDoc", { enumerable: true, get: function () { return extractSummaryFields_1.buildSummaryEvaluationDoc; } });
+Object.defineProperty(exports, "ATTACHMENTS_FIELD", { enumerable: true, get: function () { return extractSummaryFields_1.ATTACHMENTS_FIELD; } });
+//# sourceMappingURL=index.js.map

package/dist/core/indexing/summary/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/indexing/summary/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAC7B,mFAG0C;AAFxC,gJAAA,8BAA8B,OAAA;AAGhC,iCAWiB;AAVf,6GAAA,oBAAoB,OAAA;AACpB,wHAAA,+BAA+B,OAAA;AAC/B,8GAAA,qBAAqB,OAAA;AACrB,wHAAA,+BAA+B,OAAA;AAC/B,wGAAA,eAAe,OAAA;AACf,4GAAA,mBAAmB,OAAA;AAMrB,+DASgC;AAR9B,4HAAA,oBAAoB,OAAA;AACpB,4HAAA,oBAAoB,OAAA;AACpB,0HAAA,kBAAkB,OAAA;AAClB,wHAAA,gBAAgB,OAAA;AAChB,yHAAA,iBAAiB,OAAA;AACjB,iIAAA,yBAAyB,OAAA;AACzB,yHAAA,iBAAiB,OAAA"}

package/dist/core/indexing/summary/types.d.ts

@@ -0,0 +1,119 @@
+import type { ProcessChangesCursor } from "../../types";
+/**
+ * Fixed ID of the per-database setup document. It syncs like any other
+ * document, giving users/apps (e.g. the Haven UI) one shared place to
+ * configure database-level settings across all replicas. Custom-ID
+ * documents share seeded Automerge ancestry, so independently created
+ * `dbsetup` documents merge cleanly.
+ */
+export declare const DB_SETUP_DOC_ID = "dbsetup";
+/**
+ * Field of the {@link DB_SETUP_DOC_ID} document holding the
+ * {@link SummaryConfig} used by summary stores that were not given an
+ * explicit configuration in code.
+ */
+export declare const SUMMARY_SETUP_FIELD = "summarySetup";
+/**
+ * Configuration describing which document fields are copied into the
+ * summary buffer (see docs/adhoc-queries.md).
+ *
+ * The summary is a derived, local index — unlike Notes summary items the
+ * configuration is NOT part of the documents. Changing it never rewrites
+ * documents; it only triggers a resumable backfill run over the changefeed.
+ */
+export interface SummaryConfig {
+    /**
+     * When `true` (default), every non-underscore top-level field whose value
+     * is a scalar (string/number/boolean/null) or an array of scalars is
+     * included automatically, as long as its serialized size does not exceed
+     * {@link maxValueBytes}.
+     */
+    autoInclude?: boolean;
+    /**
+     * Size cap (approximate, JSON-serialized length) for auto-included
+     * values. Values above the cap are skipped — queries on such fields see
+     * them as absent. Explicitly `include`d paths are NOT subject to the cap.
+     * Default: 1024.
+     */
+    maxValueBytes?: number;
+    /**
+     * Dot-separated paths to include explicitly. Unlike auto-include these
+     * may be nested (`"meta.author"`), may resolve to non-scalar values, and
+     * bypass the size cap. The value is stored under the full path as key.
+     */
+    include?: string[];
+    /**
+     * Dot-separated paths to exclude. Wins over auto-include and `include`;
+     * an exclude also covers all nested paths below it.
+     */
+    exclude?: string[];
+    /**
+     * When `true` (default), a slim projection of the document's
+     * `_attachments` array (`fileName`, `size`, `mimeType`, `createdAt` per
+     * attachment) is stored in the summary, so attachment expressions
+     * (`attachmentNames()`, `attachmentLengths()`, `attachmentCount()`) work
+     * on the summary path. Internal plumbing (`lastChunkId`,
+     * `decryptionKeyId`) and the creator's full signing key (`createdBy`)
+     * are deliberately not copied.
+     */
+    includeAttachments?: boolean;
+}
+/** {@link SummaryConfig} with all defaults applied. */
+export interface ResolvedSummaryConfig {
+    autoInclude: boolean;
+    maxValueBytes: number;
+    include: string[];
+    exclude: string[];
+    includeAttachments: boolean;
+}
+export declare const DEFAULT_SUMMARY_MAX_VALUE_BYTES = 1024;
+export declare function resolveSummaryConfig(config?: SummaryConfig): ResolvedSummaryConfig;
+/**
+ * Extract a {@link SummaryConfig} from an untyped value (the
+ * `summarySetup` field of the synced setup document). Unknown properties
+ * are dropped and wrongly-typed ones ignored, so a malformed document can
+ * never break summary maintenance. Returns `undefined` when the value is
+ * not an object (missing field, deleted document) — callers fall back to
+ * the default configuration.
+ */
+export declare function sanitizeSummaryConfig(value: unknown): SummaryConfig | undefined;
+/**
+ * Deterministic fingerprint of a summary configuration. Persisted alongside
+ * the summary cache; a mismatch on restore (or a config change at runtime)
+ * marks the summary as `"rebuilding"` and triggers a backfill.
+ */
+export declare function computeSummaryConfigFingerprint(config: ResolvedSummaryConfig): string;
+/** One document's entry in the summary buffer. */
+export interface DocumentSummaryEntry {
+    docId: string;
+    /**
+     * Flat map of extracted values. Auto-included top-level fields are keyed
+     * by field name; explicitly included paths are keyed by their full
+     * dot-path. Use `getSummaryFieldValue()` for path-aware lookups.
+     */
+    fields: Record<string, unknown>;
+    lastModified: number;
+    /** Changefeed sequence of the change this entry was extracted from. */
+    changeSeq: number;
+    decryptionKeyId: string | null;
+}
+/**
+ * Coverage state reported by query results: `"full"` when the summary
+ * reflects the current configuration for all documents, `"rebuilding"`
+ * while a config-change backfill is still in progress (entries extracted
+ * with the previous configuration may still be served).
+ */
+export type SummaryCoverage = "full" | "rebuilding";
+/** Serialized shape of one persisted summary bucket. */
+export interface SummaryBucketPayload {
+    entries: DocumentSummaryEntry[];
+}
+/** Serialized shape of the persisted summary metadata record. */
+export interface SummaryMetaPayload {
+    cursor: ProcessChangesCursor | null;
+    configFingerprint: string;
+    bucketCount: number;
+    needsBackfill: boolean;
+    backfillCursor: ProcessChangesCursor | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/indexing/summary/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/indexing/summary/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,qBAAqB,CAQlF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CA4B/E;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAQrF;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,CAAC;AAEpD,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC7C"}

package/dist/core/indexing/summary/types.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SUMMARY_MAX_VALUE_BYTES = exports.SUMMARY_SETUP_FIELD = exports.DB_SETUP_DOC_ID = void 0;
+exports.resolveSummaryConfig = resolveSummaryConfig;
+exports.sanitizeSummaryConfig = sanitizeSummaryConfig;
+exports.computeSummaryConfigFingerprint = computeSummaryConfigFingerprint;
+/**
+ * Fixed ID of the per-database setup document. It syncs like any other
+ * document, giving users/apps (e.g. the Haven UI) one shared place to
+ * configure database-level settings across all replicas. Custom-ID
+ * documents share seeded Automerge ancestry, so independently created
+ * `dbsetup` documents merge cleanly.
+ */
+exports.DB_SETUP_DOC_ID = "dbsetup";
+/**
+ * Field of the {@link DB_SETUP_DOC_ID} document holding the
+ * {@link SummaryConfig} used by summary stores that were not given an
+ * explicit configuration in code.
+ */
+exports.SUMMARY_SETUP_FIELD = "summarySetup";
+exports.DEFAULT_SUMMARY_MAX_VALUE_BYTES = 1024;
+function resolveSummaryConfig(config) {
+    return {
+        autoInclude: config?.autoInclude ?? true,
+        maxValueBytes: Math.max(0, config?.maxValueBytes ?? exports.DEFAULT_SUMMARY_MAX_VALUE_BYTES),
+        include: [...(config?.include ?? [])],
+        exclude: [...(config?.exclude ?? [])],
+        includeAttachments: config?.includeAttachments ?? true,
+    };
+}
+/**
+ * Extract a {@link SummaryConfig} from an untyped value (the
+ * `summarySetup` field of the synced setup document). Unknown properties
+ * are dropped and wrongly-typed ones ignored, so a malformed document can
+ * never break summary maintenance. Returns `undefined` when the value is
+ * not an object (missing field, deleted document) — callers fall back to
+ * the default configuration.
+ */
+function sanitizeSummaryConfig(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const raw = value;
+    const config = {};
+    if (typeof raw.autoInclude === "boolean") {
+        config.autoInclude = raw.autoInclude;
+    }
+    if (typeof raw.maxValueBytes === "number" && Number.isFinite(raw.maxValueBytes)) {
+        config.maxValueBytes = raw.maxValueBytes;
+    }
+    const stringList = (input) => Array.isArray(input)
+        ? input.filter((item) => typeof item === "string")
+        : undefined;
+    const include = stringList(raw.include);
+    if (include) {
+        config.include = include;
+    }
+    const exclude = stringList(raw.exclude);
+    if (exclude) {
+        config.exclude = exclude;
+    }
+    if (typeof raw.includeAttachments === "boolean") {
+        config.includeAttachments = raw.includeAttachments;
+    }
+    return config;
+}
+/**
+ * Deterministic fingerprint of a summary configuration. Persisted alongside
+ * the summary cache; a mismatch on restore (or a config change at runtime)
+ * marks the summary as `"rebuilding"` and triggers a backfill.
+ */
+function computeSummaryConfigFingerprint(config) {
+    return JSON.stringify({
+        autoInclude: config.autoInclude,
+        maxValueBytes: config.maxValueBytes,
+        include: [...config.include].sort(),
+        exclude: [...config.exclude].sort(),
+        includeAttachments: config.includeAttachments,
+    });
+}
+//# sourceMappingURL=types.js.map

package/dist/core/indexing/summary/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/indexing/summary/types.ts"],"names":[],"mappings":";;;AA+EA,oDAQC;AAUD,sDA4BC;AAOD,0EAQC;AA1ID;;;;;;GAMG;AACU,QAAA,eAAe,GAAG,SAAS,CAAC;AAEzC;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,cAAc,CAAC;AA6DrC,QAAA,+BAA+B,GAAG,IAAI,CAAC;AAEpD,SAAgB,oBAAoB,CAAC,MAAsB;IACzD,OAAO;QACL,WAAW,EAAE,MAAM,EAAE,WAAW,IAAI,IAAI;QACxC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,IAAI,uCAA+B,CAAC;QACpF,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACrC,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACrC,kBAAkB,EAAE,MAAM,EAAE,kBAAkB,IAAI,IAAI;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CAAC,KAAc;IAClD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IACvC,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;QAChF,MAAM,CAAC,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IAC3C,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,KAAc,EAAwB,EAAE,CAC1D,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAClB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC;QAClE,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IACD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAChD,MAAM,CAAC,kBAAkB,GAAG,GAAG,CAAC,kBAAkB,CAAC;IACrD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAgB,+BAA+B,CAAC,MAA6B;IAC3E,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QACnC,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QACnC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;KAC9C,CAAC,CAAC;AACL,CAAC"}

package/dist/core/indexing/virtualviews/IVirtualViewDataProvider.d.ts

@@ -1,4 +1,48 @@
 import type { VirtualView } from "./VirtualView";
+/**
+ * Progress snapshot passed to {@link VirtualViewUpdateOptions.onProgress}.
+ */
+export interface VirtualViewUpdateProgress {
+    /** Documents processed so far in this update run. */
+    processed: number;
+    /**
+     * Total number of changefeed entries pending at the start of the run
+     * (best effort; new changes arriving mid-run are not counted).
+     */
+    total: number;
+    /** Origin of the data provider reporting progress. */
+    origin: string;
+}
+/**
+ * Options controlling an incremental view update run.
+ *
+ * Batching makes long update runs observable and interruptible: after every
+ * `applyBatchSize` processed documents the accumulated changes are applied to
+ * the view (so the view and the provider cursor stay consistent), progress is
+ * reported, and the run can be cancelled. An interrupted run resumes from the
+ * saved cursor on the next `update()` call — no work is repeated.
+ */
+export interface VirtualViewUpdateOptions {
+    /**
+     * Apply accumulated changes to the view (and report progress) after this
+     * many processed documents. Default: 100. Use `Infinity` to apply all
+     * changes atomically at the end of the run (progress is then only
+     * reported once, and the run cannot be interrupted mid-way).
+     */
+    applyBatchSize?: number;
+    /**
+     * Called at every batch boundary (and once at the end of the run).
+     * Return `false` to stop the update after the current batch; the cursor
+     * points at the last applied document, so the next update resumes there.
+     */
+    onProgress?: (progress: VirtualViewUpdateProgress) => boolean | void;
+    /**
+     * Optional abort signal, checked at every batch boundary. Aborting behaves
+     * like `onProgress` returning `false`: the current batch is applied, then
+     * the run stops cleanly.
+     */
+    signal?: AbortSignal;
+}
 /**
  * Interface for classes that provide data to a VirtualView.
  * Data providers fetch documents from a source (like MindooDB) and
@@ -24,8 +68,10 @@ export interface IVirtualViewDataProvider {
      * Fetches the latest data and sends updates to the VirtualView.
      * This should be idempotent and handle incremental updates efficiently.
      *
+     * @param options Optional batching/progress/cancellation options.
+     *   Providers that do not support batching may ignore them.
      * @returns A promise that resolves when the update is complete
      */
-    update(): Promise<void>;
+    update(options?: VirtualViewUpdateOptions): Promise<void>;
 }
 //# sourceMappingURL=IVirtualViewDataProvider.d.ts.map

package/dist/core/indexing/virtualviews/IVirtualViewDataProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IVirtualViewDataProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/indexing/virtualviews/IVirtualViewDataProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,SAAS,IAAI,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9B;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}
+{"version":3,"file":"IVirtualViewDataProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/indexing/virtualviews/IVirtualViewDataProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,yBAAyB,KAAK,OAAO,GAAG,IAAI,CAAC;IACrE;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,SAAS,IAAI,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D"}

package/dist/core/indexing/virtualviews/MindooDBVirtualViewDataProvider.d.ts

@@ -1,5 +1,5 @@
 import type { MindooDB, ProcessChangesCursor } from "../../types";
-import type { IVirtualViewDataProvider } from "./IVirtualViewDataProvider";
+import type { IVirtualViewDataProvider, VirtualViewUpdateOptions } from "./IVirtualViewDataProvider";
 import type { VirtualView } from "./VirtualView";
 import type { DocumentFilterFunction } from "./types";
 /**
@@ -12,19 +12,29 @@ export interface MindooDBVirtualViewDataProviderOptions {
     db: MindooDB;
     /** Optional filter function to select which documents to include */
     filterFunction?: DocumentFilterFunction;
-    /** Page size for incremental processing (default: 100) */
-    pageSize?: number;
+    /**
+     * When `true`, every (non-underscore) document field is copied into the
+     * view entry's column values, mirroring the legacy behavior. Defaults to
+     * `false`: only the fields the view's columns reference are kept, which
+     * significantly reduces memory usage and view-cache size for documents
+     * with large payloads. Enable this for consumers that need free-form
+     * field access on view entries (e.g. formula languages evaluating
+     * arbitrary fields at read time).
+     */
+    includeAllDocumentFields?: boolean;
 }
 /**
  * Data provider that reads documents from a MindooDB and provides them
- * to a VirtualView. It uses metadata-first incremental updates so delete-only
- * changes can be handled without materializing document bodies.
+ * to a VirtualView. Incremental updates are driven by
+ * `iterateChangesSince`, which prefetches upcoming documents in parallel
+ * and emits lightweight tombstones for deleted and inaccessible documents,
+ * so removals never pay document materialization.
  */
 export declare class MindooDBVirtualViewDataProvider implements IVirtualViewDataProvider {
     private readonly origin;
     private readonly db;
     private readonly filterFunction;
-    private readonly pageSize;
+    private readonly includeAllDocumentFields;
     private view;
     private cursor;
     /** Track documents currently in the view from this provider */
@@ -32,9 +42,15 @@ export declare class MindooDBVirtualViewDataProvider implements IVirtualViewData
     constructor(options: MindooDBVirtualViewDataProviderOptions);
     getOrigin(): string;
     init(view: VirtualView): void;
-    update(): Promise<void>;
+    update(options?: VirtualViewUpdateOptions): Promise<void>;
     /**
-     * Compute column values for a document using column value functions
+     * Compute column values for a document using column value functions.
+     *
+     * By default only the fields the view's columns reference are copied into
+     * the result, keeping view entries (and the serialized view cache) small.
+     * With `includeAllDocumentFields: true` every non-underscore document
+     * field is copied first, mirroring the legacy behavior for consumers that
+     * need free-form field access on view entries.
      */
     private computeColumnValues;
     /**