mindoodb 0.0.23 → 0.0.32

package/dist/core/query/queryLive.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeQueryLive = executeQueryLive;
+const executeQuery_1 = require("./executeQuery");
+/**
+ * Fingerprint of a query result: docIds + lastModified in result order.
+ * Any membership, ordering, or content change (content changes bump
+ * `lastModified`) alters the fingerprint; changes to non-matching
+ * documents cost only the scan, never an `onResult` call.
+ *
+ * Full-text relevance scores participate ROUNDED (two decimals): adding
+ * 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.
+ */
+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)}`);
+    }
+    return parts.join("|");
+}
+/**
+ * Live query: delivers the initial result, keeps the summary current via
+ * the database's change listener, and re-evaluates the query after every
+ * (coalesced) change event. `onResult` only fires when the result
+ * fingerprint actually changed.
+ *
+ * Re-evaluations are single-flight with a pending flag, so bursts of
+ * change events never queue up more than one follow-up run. Evaluation
+ * 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.");
+    }
+    let lastFingerprint = null;
+    let unsubscribed = false;
+    let running = false;
+    let pending = false;
+    const reportError = (error) => {
+        if (options?.onError) {
+            options.onError(error);
+        }
+        else {
+            console.warn("[MindooDB] queryLive evaluation failed:", error);
+        }
+    };
+    const evaluate = async (force) => {
+        const result = await (0, executeQuery_1.executeQuery)(db, summary, query, options);
+        if (unsubscribed) {
+            return;
+        }
+        const fingerprint = fingerprintResult(result);
+        if (force || fingerprint !== lastFingerprint) {
+            lastFingerprint = fingerprint;
+            onResult(result);
+        }
+    };
+    const run = async (force) => {
+        if (running) {
+            pending = true;
+            return;
+        }
+        running = true;
+        try {
+            do {
+                pending = false;
+                try {
+                    await evaluate(force);
+                }
+                catch (error) {
+                    reportError(error);
+                }
+                force = false;
+            } while (pending && !unsubscribed);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const removeListener = db.addChangeListener(() => {
+        if (!unsubscribed) {
+            void run(false);
+        }
+    });
+    // Deliver the initial result asynchronously.
+    void run(true);
+    return {
+        unsubscribe() {
+            unsubscribed = true;
+            removeListener();
+        },
+        async refresh() {
+            if (unsubscribed) {
+                return;
+            }
+            await run(true);
+        },
+    };
+}
+//# sourceMappingURL=queryLive.js.map

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

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

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

@@ -0,0 +1,156 @@
+import type { MindooDB } from "../types";
+import type { MindooDBAppBooleanExpression } from "../expressions/types";
+import type { DocumentSummaryStore } from "../indexing/summary/DocumentSummaryStore";
+import { VirtualView } from "../indexing/virtualviews/VirtualView";
+import { VirtualViewColumn, type VirtualViewColumnOptions } from "../indexing/virtualviews/VirtualViewColumn";
+import type { VirtualViewUpdateOptions } from "../indexing/virtualviews/IVirtualViewDataProvider";
+import type { CategorizationStyle } from "../indexing/virtualviews/types";
+import { type MindooQueryTextClause } from "./types";
+/**
+ * Declarative definition of an ephemeral, summary-backed view. Fully
+ * JSON-serializable when columns use `expression` instead of
+ * `valueFunction` — the basis for view designs stored/synchronized as
+ * data.
+ */
+export interface MindooQueryViewDefinition {
+    /**
+     * Expression filter selecting which documents appear in the view.
+     * Applies to every source unless a source provides its own filter.
+     */
+    filter?: MindooDBAppBooleanExpression;
+    /**
+     * Full-text pre-filter: only documents matching this search (in each
+     * source's full-text index) appear in the view, combined with `filter`
+     * as a logical AND. Applies to every source unless a source provides
+     * its own `text` clause. Requires full-text indexing to be enabled for
+     * each source database (`fulltext-not-enabled` otherwise) — see
+     * docs/fulltext-search.md.
+     *
+     * Matching documents expose the relevance as pseudo-fields to filter
+     * and column expressions: `_textScore` (0..1, normalized to the best
+     * hit of the current search, rounded to 2 decimals) and
+     * `_textScoreRaw` (engine-specific raw score).
+     */
+    text?: MindooQueryTextClause;
+    /** View columns (categories/sorting/totals work as in persistent views). */
+    columns: Array<VirtualViewColumn | VirtualViewColumnOptions>;
+    categorizationStyle?: CategorizationStyle;
+}
+/**
+ * One database feeding an ephemeral summary view. Like persistent
+ * VirtualViews, ephemeral views can combine multiple sources — different
+ * databases and even different tenants — each contributing entries under
+ * its own origin.
+ */
+export interface EphemeralViewSource {
+    /** The database whose summary buffer feeds this source. */
+    db: MindooDB;
+    /**
+     * Per-source filter. When set it replaces the definition-level filter
+     * for this source (e.g. different document types per database).
+     */
+    filter?: MindooDBAppBooleanExpression;
+    /**
+     * Per-source full-text pre-filter. When set it replaces the
+     * definition-level `text` clause for this source.
+     */
+    text?: MindooQueryTextClause;
+    /**
+     * Origin identifier for entries of this source. Must be unique within
+     * the view. Defaults to `<tenantId>/<storeId>#ephemeral`, which is
+     * already unique across databases and tenants.
+     */
+    origin?: string;
+}
+/** Internally resolved source: summary store and origin are settled. */
+interface ResolvedViewSource {
+    db: MindooDB;
+    summary: DocumentSummaryStore;
+    origin: string;
+    filter?: MindooDBAppBooleanExpression;
+    text?: MindooQueryTextClause;
+}
+/**
+ * An ephemeral VirtualView over one or more document summary buffers,
+ * created by `db.queryView()` (single database) or {@link queryViewAcross}
+ * (multiple databases/tenants).
+ *
+ * Unlike persistent views it is not registered with a CacheManager —
+ * building it is a pure in-memory sort over summary entries, so dynamic
+ * re-sorting is cheap: {@link resort} swaps in a new column set over the
+ * SAME summaries (no document reload, no changefeed re-consumption).
+ */
+export declare class EphemeralSummaryView {
+    private readonly sources;
+    private definition;
+    private view;
+    private providers;
+    private disposed;
+    /** Whether a live binding is active (survives resort rebuilds). */
+    private liveBound;
+    constructor(sources: ResolvedViewSource[], definition: MindooQueryViewDefinition);
+    private buildView;
+    /** The underlying VirtualView (navigators, entries, totals as usual). */
+    getView(): VirtualView;
+    /** Bring the view up to date (summary updates + entry propagation). */
+    update(options?: VirtualViewUpdateOptions): Promise<void>;
+    /**
+     * Replace the column set (and optionally the filter and/or full-text
+     * clause) and rebuild the view from the summaries — dynamic re-sorting
+     * without touching documents. A live binding created via {@link bindTo}
+     * carries over to the new view.
+     */
+    resort(definition: Partial<MindooQueryViewDefinition> & Pick<MindooQueryViewDefinition, "columns">, options?: VirtualViewUpdateOptions): Promise<void>;
+    /**
+     * Keep this view up to date automatically via the change feeds of ALL
+     * source databases (see {@link VirtualView.bindTo}). Combine with
+     * `getView().onDidUpdate()` for UI re-render hooks.
+     *
+     * @returns An unbind function.
+     */
+    bindTo(): () => void;
+    private bindSources;
+    /** Detach all change-feed bindings. */
+    unbind(): void;
+    /**
+     * Release the view: detaches change-feed bindings and drops internal
+     * state. Ephemeral views hold no CacheManager registration, so nothing
+     * else needs cleanup.
+     */
+    dispose(): void;
+    isDisposed(): boolean;
+    private assertNotDisposed;
+}
+/**
+ * Build an ephemeral, summary-backed VirtualView over a single database
+ * and run its initial update. See {@link EphemeralSummaryView}.
+ */
+export declare function createEphemeralSummaryView(db: MindooDB, summary: DocumentSummaryStore, definition: MindooQueryViewDefinition, options?: VirtualViewUpdateOptions): Promise<EphemeralSummaryView>;
+/**
+ * Build an ephemeral, summary-backed VirtualView spanning MULTIPLE
+ * databases — and, since every source brings its own tenant context, even
+ * multiple tenants. Each source contributes entries under its own origin
+ * from its own summary buffer; no documents are materialized anywhere.
+ *
+ * ```typescript
+ * const view = await queryViewAcross(
+ *   [
+ *     { db: salesDb },
+ *     { db: archiveDb, filter: v.eq(v.field("year"), 2025) },
+ *   ],
+ *   {
+ *     filter: v.eq(v.field("type"), "deal"),
+ *     columns: [
+ *       VirtualViewColumn.category("region"),
+ *       VirtualViewColumn.sorted("amount", ColumnSorting.DESCENDING),
+ *     ],
+ *   }
+ * );
+ * ```
+ *
+ * A per-source `filter` replaces the definition-level filter for that
+ * source. `bindTo()` subscribes to the change feeds of all sources.
+ */
+export declare function queryViewAcross(sources: EphemeralViewSource[], definition: MindooQueryViewDefinition, options?: VirtualViewUpdateOptions): Promise<EphemeralSummaryView>;
+export {};
+//# sourceMappingURL=queryView.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EphemeralSummaryView = void 0;
+exports.createEphemeralSummaryView = createEphemeralSummaryView;
+exports.queryViewAcross = queryViewAcross;
+const expressions_1 = require("../expressions");
+const SummaryVirtualViewDataProvider_1 = require("../indexing/summary/SummaryVirtualViewDataProvider");
+const VirtualView_1 = require("../indexing/virtualviews/VirtualView");
+const VirtualViewColumn_1 = require("../indexing/virtualviews/VirtualViewColumn");
+const types_1 = require("./types");
+function defaultEphemeralOrigin(db) {
+    return `${db.getTenant().getId()}/${db.getStore().getId()}#ephemeral`;
+}
+function resolveSources(sources) {
+    if (sources.length === 0) {
+        throw new types_1.MindooQueryError("An ephemeral view needs at least one source database.");
+    }
+    const resolved = [];
+    const seenOrigins = new Set();
+    for (const source of sources) {
+        if (!source.db.getSummaryStore) {
+            throw new types_1.MindooQueryError("A source database does not support summary stores.");
+        }
+        const origin = source.origin ?? defaultEphemeralOrigin(source.db);
+        if (seenOrigins.has(origin)) {
+            throw new types_1.MindooQueryError(`Duplicate view source origin "${origin}" — pass distinct 'origin' values when combining the same database twice.`);
+        }
+        seenOrigins.add(origin);
+        resolved.push({
+            db: source.db,
+            summary: source.db.getSummaryStore(),
+            origin,
+            filter: source.filter,
+            text: source.text,
+        });
+    }
+    return resolved;
+}
+/**
+ * An ephemeral VirtualView over one or more document summary buffers,
+ * created by `db.queryView()` (single database) or {@link queryViewAcross}
+ * (multiple databases/tenants).
+ *
+ * Unlike persistent views it is not registered with a CacheManager —
+ * building it is a pure in-memory sort over summary entries, so dynamic
+ * re-sorting is cheap: {@link resort} swaps in a new column set over the
+ * SAME summaries (no document reload, no changefeed re-consumption).
+ */
+class EphemeralSummaryView {
+    constructor(sources, definition) {
+        this.sources = sources;
+        this.definition = definition;
+        this.providers = [];
+        this.disposed = false;
+        /** Whether a live binding is active (survives resort rebuilds). */
+        this.liveBound = false;
+        this.view = this.buildView(definition);
+    }
+    buildView(definition) {
+        validateViewDefinition(this.sources, definition);
+        const columns = definition.columns.map((column) => column instanceof VirtualViewColumn_1.VirtualViewColumn ? column : new VirtualViewColumn_1.VirtualViewColumn(column));
+        const view = new VirtualView_1.VirtualView(columns);
+        if (definition.categorizationStyle !== undefined) {
+            view.setCategorizationStyle(definition.categorizationStyle);
+        }
+        this.providers = [];
+        for (const source of this.sources) {
+            const textClause = source.text ?? definition.text;
+            let text;
+            if (textClause) {
+                if (!source.db.getFullTextIndex) {
+                    throw new types_1.MindooQueryError(`View source "${source.origin}" does not support full-text search.`, "fulltext-not-enabled");
+                }
+                text = { index: source.db.getFullTextIndex(), clause: textClause };
+            }
+            const provider = new SummaryVirtualViewDataProvider_1.SummaryVirtualViewDataProvider({
+                origin: source.origin,
+                summary: source.summary,
+                filter: source.filter ?? definition.filter,
+                text,
+            });
+            provider.init(view);
+            view.addDataProvider(provider);
+            this.providers.push(provider);
+        }
+        return view;
+    }
+    /** The underlying VirtualView (navigators, entries, totals as usual). */
+    getView() {
+        this.assertNotDisposed();
+        return this.view;
+    }
+    /** Bring the view up to date (summary updates + entry propagation). */
+    async update(options) {
+        this.assertNotDisposed();
+        await this.view.update(options);
+    }
+    /**
+     * Replace the column set (and optionally the filter and/or full-text
+     * clause) and rebuild the view from the summaries — dynamic re-sorting
+     * without touching documents. A live binding created via {@link bindTo}
+     * carries over to the new view.
+     */
+    async resort(definition, options) {
+        this.assertNotDisposed();
+        this.definition = {
+            ...this.definition,
+            ...definition,
+        };
+        this.view.unbind();
+        this.view = this.buildView(this.definition);
+        if (this.liveBound) {
+            this.bindSources();
+        }
+        await this.view.update(options);
+    }
+    /**
+     * Keep this view up to date automatically via the change feeds of ALL
+     * source databases (see {@link VirtualView.bindTo}). Combine with
+     * `getView().onDidUpdate()` for UI re-render hooks.
+     *
+     * @returns An unbind function.
+     */
+    bindTo() {
+        this.assertNotDisposed();
+        this.liveBound = true;
+        this.bindSources();
+        return () => {
+            this.unbind();
+        };
+    }
+    bindSources() {
+        for (const source of this.sources) {
+            this.view.bindTo(source.db);
+        }
+    }
+    /** Detach all change-feed bindings. */
+    unbind() {
+        this.liveBound = false;
+        this.view.unbind();
+    }
+    /**
+     * Release the view: detaches change-feed bindings and drops internal
+     * state. Ephemeral views hold no CacheManager registration, so nothing
+     * else needs cleanup.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.unbind();
+        this.disposed = true;
+        for (const provider of this.providers) {
+            provider.reset();
+        }
+        this.providers = [];
+    }
+    isDisposed() {
+        return this.disposed;
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new Error("This ephemeral view has been disposed.");
+        }
+    }
+}
+exports.EphemeralSummaryView = EphemeralSummaryView;
+/**
+ * Managed pseudo-fields provided by the full-text pre-filter (not stored
+ * in the summary buffer): `_textScore` is the normalized 0..1 relevance of
+ * the match, `_textScoreRaw` the engine's raw score.
+ */
+const TEXT_SCORE_FIELDS = new Set(["_textScore", "_textScoreRaw"]);
+/**
+ * Guardrails mirroring `db.query()`: expressions must be answerable from
+ * the summary buffers (no decrypt, no view-tree operations in filters,
+ * referenced fields covered by EACH source's summary configuration).
+ * The text-score pseudo-fields are exempt from coverage but require an
+ * effective `text` clause on the source.
+ */
+function validateViewDefinition(sources, definition) {
+    const columnPaths = new Set();
+    for (const column of definition.columns) {
+        const expression = column instanceof VirtualViewColumn_1.VirtualViewColumn ? column.expression : column.expression;
+        if (!expression) {
+            continue;
+        }
+        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.");
+        }
+        for (const path of (0, expressions_1.getReferencedFields)(expression)) {
+            columnPaths.add(path);
+        }
+    }
+    for (const source of sources) {
+        const referencedPaths = new Set(columnPaths);
+        const filter = source.filter ?? definition.filter;
+        if (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(", ")}).`);
+            }
+            if (requirements.needsDecryption) {
+                throw new types_1.MindooQueryError("View filters cannot use decrypt expressions: encrypted fields are not stored in the summary buffer.");
+            }
+            for (const path of (0, expressions_1.getReferencedFields)(filter)) {
+                referencedPaths.add(path);
+            }
+        }
+        const hasTextClause = (source.text ?? definition.text) !== undefined;
+        for (const path of referencedPaths) {
+            if (TEXT_SCORE_FIELDS.has(path)) {
+                if (!hasTextClause) {
+                    throw new types_1.MindooQueryError(`Expression references "${path}", but source "${source.origin}" has no 'text' clause — ` +
+                        `text scores only exist for full-text pre-filtered views.`);
+                }
+                continue;
+            }
+            if (!source.summary.isFieldCovered(path)) {
+                throw new types_1.MindooQueryError(`Field "${path}" is not covered by the summary configuration of source "${source.origin}" ` +
+                    `(check include/exclude in SummaryConfig).`);
+            }
+        }
+    }
+}
+/**
+ * Build an ephemeral, summary-backed VirtualView over a single database
+ * and run its initial update. See {@link EphemeralSummaryView}.
+ */
+async function createEphemeralSummaryView(db, summary, definition, options) {
+    const view = new EphemeralSummaryView([{ db, summary, origin: defaultEphemeralOrigin(db) }], definition);
+    await view.update(options);
+    return view;
+}
+/**
+ * Build an ephemeral, summary-backed VirtualView spanning MULTIPLE
+ * databases — and, since every source brings its own tenant context, even
+ * multiple tenants. Each source contributes entries under its own origin
+ * from its own summary buffer; no documents are materialized anywhere.
+ *
+ * ```typescript
+ * const view = await queryViewAcross(
+ *   [
+ *     { db: salesDb },
+ *     { db: archiveDb, filter: v.eq(v.field("year"), 2025) },
+ *   ],
+ *   {
+ *     filter: v.eq(v.field("type"), "deal"),
+ *     columns: [
+ *       VirtualViewColumn.category("region"),
+ *       VirtualViewColumn.sorted("amount", ColumnSorting.DESCENDING),
+ *     ],
+ *   }
+ * );
+ * ```
+ *
+ * A per-source `filter` replaces the definition-level filter for that
+ * source. `bindTo()` subscribes to the change feeds of all sources.
+ */
+async function queryViewAcross(sources, definition, options) {
+    const view = new EphemeralSummaryView(resolveSources(sources), definition);
+    await view.update(options);
+    return view;
+}
+//# sourceMappingURL=queryView.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,121 @@
+import type { MindooDBAppBooleanExpression, MindooDBAppExpression } from "../expressions/types";
+import type { SummaryCoverage } from "../indexing/summary/types";
+import type { VirtualViewUpdateOptions } from "../indexing/virtualviews/IVirtualViewDataProvider";
+/**
+ * One sort key of a {@link MindooQuery}. Either a plain summary field
+ * path, a computed expression (evaluated per row before comparison), or a
+ * special pseudo-key (`{ special: "textScore" }` sorts by the full-text
+ * relevance score of the {@link MindooQuery.text} clause).
+ */
+export interface MindooQuerySortKey {
+    field?: string;
+    expression?: MindooDBAppExpression;
+    /**
+     * `"textScore"`: sort by the relevance score of the query's `text`
+     * clause (only meaningful together with one). Direction defaults to the
+     * regular `direction` field — note that for pure relevance ranking you
+     * usually want `descending` (best match first), which is also the
+     * implicit default ordering when a `text` clause is present and no
+     * `sortBy` was given.
+     */
+    special?: "textScore";
+    direction?: "ascending" | "descending";
+}
+/**
+ * Full-text clause of a {@link MindooQuery}: matches documents through
+ * the database's full-text index (see docs/fulltext-search.md) and makes
+ * a relevance score available for sorting (`{ special: "textScore" }`).
+ * Requires full-text indexing to be enabled for the database — otherwise
+ * the query fails with `fulltext-not-enabled` (no silent full scan).
+ */
+export interface MindooQueryTextClause {
+    /** The search string (tokenized like indexed content). */
+    query: string;
+    /**
+     * Restrict matching to these index fields (document field paths, plus
+     * the synthetic `_attachments` field). Default: all indexed fields.
+     */
+    fields?: string[];
+    /** Match term prefixes (`"drag"` matches `"dragon"`). Default: `true`. */
+    prefix?: boolean;
+    /** Fuzzy matching tolerance (see `FulltextSearchOptions.fuzzy`). Default: `false`. */
+    fuzzy?: boolean | number;
+    /** How multiple terms combine: `"AND"` (default) or `"OR"`. */
+    combineWith?: "AND" | "OR";
+}
+/**
+ * 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.
+ */
+export interface MindooQuery {
+    filter?: MindooDBAppBooleanExpression;
+    /**
+     * Full-text clause: additionally require documents to match this
+     * full-text search (combined with `filter` as a logical AND). Adds a
+     * relevance score per row (`MindooQueryRow.textScore`); without an
+     * explicit `sortBy`, results are ordered best score first.
+     */
+    text?: MindooQueryTextClause;
+    sortBy?: MindooQuerySortKey[];
+    limit?: number;
+    offset?: number;
+    /**
+     * Projection: restrict the fields returned per row. Defaults to all
+     * summary fields of the matching document.
+     */
+    fields?: string[];
+}
+export interface MindooQueryOptions extends VirtualViewUpdateOptions {
+    /**
+     * Escape hatch: materialize every document via the changefeed instead of
+     * querying the summary buffer. Removes the summary coverage requirement
+     * and allows `decrypt` expressions, but costs a full document scan —
+     * document as expensive, use only for one-off/administrative queries.
+     */
+    allowFullScan?: boolean;
+}
+export interface MindooQueryRow {
+    docId: string;
+    fields: Record<string, unknown>;
+    lastModified: number;
+    /**
+     * Relevance score of the query's `text` clause (higher = better
+     * match). Only present when the query had a `text` clause.
+     */
+    textScore?: number;
+}
+/**
+ * Which data answered the query: `"full"`/`"rebuilding"` from the summary
+ * buffer (see {@link SummaryCoverage}), `"full-scan"` when documents were
+ * materialized via `allowFullScan`.
+ */
+export type MindooQueryCoverage = SummaryCoverage | "full-scan";
+export interface MindooQueryResult {
+    rows: MindooQueryRow[];
+    /** Number of matching documents before `offset`/`limit` were applied. */
+    total: number;
+    coverage: MindooQueryCoverage;
+}
+/**
+ * Machine-readable reason codes for {@link MindooQueryError}. Currently
+ * only `"fulltext-not-enabled"` (a `text` clause on a database without an
+ * enabled full-text index) is distinguished; other failures carry no code.
+ */
+export type MindooQueryErrorCode = "fulltext-not-enabled";
+/**
+ * Thrown for queries that cannot be answered: referenced fields outside the
+ * summary coverage, `decrypt`/view-tree expressions without
+ * `allowFullScan`, a `text` clause without an enabled full-text index,
+ * or an aborted run.
+ */
+export declare class MindooQueryError extends Error {
+    /** Machine-readable reason, when one is defined for the failure. */
+    readonly code?: MindooQueryErrorCode;
+    constructor(message: string, code?: MindooQueryErrorCode);
+}
+//# sourceMappingURL=types.d.ts.map