@columnus/shared 0.1.47

package/dist/queryPlan.d.ts

@@ -0,0 +1,97 @@
+import type { SearchIndex, Table } from "./schemaTypes.ts";
+import { type MergedQuery } from "./queryMerge.ts";
+import { type ListMeta, type Predicate, type Query, type QueryError, type QueryOrder } from "./queryTypes.ts";
+export type IndexRangeBound = {
+    op: "gt" | "gte" | "lt" | "lte";
+    value: unknown;
+} | {
+    op: "between";
+    min: unknown;
+    max: unknown;
+} | {
+    op: "bounded";
+    lower: {
+        op: "gt" | "gte";
+        value: unknown;
+    };
+    upper: {
+        op: "lt" | "lte";
+        value: unknown;
+    };
+};
+export type PlannedIndexAccess = {
+    name: string;
+    eqs: {
+        field: string;
+        value: unknown;
+    }[];
+    /** Optional range on the next index field after eqs (Convex-native). */
+    range?: {
+        field: string;
+        bound: IndexRangeBound;
+    };
+    /** Convex `.order` when the index order satisfies `query.order`. */
+    direction?: "asc" | "desc";
+};
+export type PlannedSearchAccess = {
+    name: string;
+    searchField: string;
+    query: string;
+    filterEqs: {
+        field: string;
+        value: unknown;
+    }[];
+};
+export type PlannedAccess = {
+    mode: "search";
+    search: PlannedSearchAccess;
+} | {
+    mode: "index";
+    index: PlannedIndexAccess;
+} | {
+    mode: "table";
+    direction?: "asc" | "desc";
+};
+export type PlannedPage = {
+    mode: "paginate";
+} | {
+    mode: "boundedSort";
+    order: QueryOrder;
+    maxScan: number;
+};
+export type QueryPlan = {
+    access: PlannedAccess;
+    page: PlannedPage;
+    /** Predicates applied after index/search access (post-filter). */
+    postFilters: Predicate[];
+};
+export type PlanQueryResult = {
+    ok: true;
+    plan: QueryPlan;
+} | {
+    ok: false;
+    error: QueryError;
+};
+export type PlanQueryOptions = {
+    /** Effective execution ceiling after applying profile/share policy. */
+    effectiveMaxScan?: number;
+};
+export declare function takeRangeBound(preds: Predicate[] | undefined): {
+    bound: IndexRangeBound;
+    preds: Predicate[];
+} | null;
+/**
+ * Build public list explain metadata from an executable plan.
+ * Call once when constructing {@link ListMeta} on a list result — not stored on {@link QueryPlan}.
+ */
+export declare function deriveListMeta(access: PlannedAccess, page: PlannedPage, order?: QueryOrder): ListMeta;
+/** Share scopes that resolve rows from an explicit ID list (outside the Query planner). */
+export declare function idListMeta(scanned: number, truncated?: boolean): ListMeta;
+/**
+ * Build an executable plan for a (already merged) query against a table manifest.
+ */
+export declare function planQuery(table: Pick<Table, "name" | "fields" | "indexes" | "searchIndexes">, query: Query | null | undefined, options?: PlanQueryOptions): PlanQueryResult;
+/** Plan a caller query with optional clamp using {@link mergeQuery} semantics externally. */
+export declare function planMergedQuery(table: Pick<Table, "name" | "fields" | "indexes" | "searchIndexes">, merged: MergedQuery): PlanQueryResult;
+/** @internal exported for tests — search index lookup helper */
+export declare function findSearchIndex(table: Pick<Table, "searchIndexes">, name: string): SearchIndex | undefined;