@columnus/shared 0.1.47

package/dist/queryTypes.d.ts

@@ -0,0 +1,402 @@
+import { z } from "zod";
+import type { BetweenValue } from "./queryBetween.ts";
+import { PREDICATE_OPS, PREDICATE_VARIANTS, type PredicateOp } from "./queryFieldOps.ts";
+export { PREDICATE_OPS, type PredicateOp };
+/** Platform default scan ceiling when profile/share omits `maxScanLimit`. */
+export declare const DEFAULT_MAX_SCAN_LIMIT = 1000;
+/** How rows are accessed before residual filters / page mode. */
+export declare const listAccessKindSchema: z.ZodEnum<["table", "index", "search", "idList"]>;
+export type ListAccessKind = z.infer<typeof listAccessKindSchema>;
+/** How the page is materialized from the access stream. */
+export declare const listPageKindSchema: z.ZodEnum<["paginate", "boundedSort"]>;
+export type ListPageKind = z.infer<typeof listPageKindSchema>;
+export declare const queryErrorCodeSchema: z.ZodEnum<["query_invalid", "query_unsupported", "query_unsatisfiable"]>;
+export type QueryErrorCode = z.infer<typeof queryErrorCodeSchema>;
+type PredicateVariant = (typeof PREDICATE_VARIANTS)[number];
+type PredicateValue<Kind extends PredicateVariant["value"]> = Kind extends "unknownArray" ? unknown[] : Kind extends "between" ? BetweenValue : unknown;
+export type Predicate = PredicateVariant extends infer Variant ? Variant extends PredicateVariant ? {
+    field: string;
+    op: Variant["ops"][number]["op"];
+    value: PredicateValue<Variant["value"]>;
+} : never : never;
+export declare const predicateOpSchema: z.ZodEnum<["gte" | "lte" | "between" | "eq" | "neq" | "in" | "gt" | "lt" | "containsAll", ...("gte" | "lte" | "between" | "eq" | "neq" | "in" | "gt" | "lt" | "containsAll")[]]>;
+export declare const predicateSchema: z.ZodType<Predicate>;
+export declare const queryOrderSchema: z.ZodObject<{
+    field: z.ZodString;
+    direction: z.ZodEnum<["asc", "desc"]>;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    direction: "asc" | "desc";
+}, {
+    field: string;
+    direction: "asc" | "desc";
+}>;
+export type QueryOrder = z.infer<typeof queryOrderSchema>;
+export declare const querySearchSchema: z.ZodObject<{
+    index: z.ZodString;
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    index: string;
+    query: string;
+}, {
+    index: string;
+    query: string;
+}>;
+export type QuerySearch = z.infer<typeof querySearchSchema>;
+export declare const querySchema: z.ZodObject<{
+    predicates: z.ZodOptional<z.ZodArray<z.ZodType<{
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    }, z.ZodTypeDef, {
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    }>, "many">>;
+    order: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        direction: "asc" | "desc";
+    }, {
+        field: string;
+        direction: "asc" | "desc";
+    }>>;
+    search: z.ZodOptional<z.ZodObject<{
+        index: z.ZodString;
+        query: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        index: string;
+        query: string;
+    }, {
+        index: string;
+        query: string;
+    }>>;
+    /** Reserved — rejected by the planner until vector indexes exist in the manifest. */
+    vector: z.ZodOptional<z.ZodUnknown>;
+    maxScan: z.ZodOptional<z.ZodNumber>;
+    indexHint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    predicates?: ({
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    })[] | undefined;
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    search?: {
+        index: string;
+        query: string;
+    } | undefined;
+    vector?: unknown;
+    maxScan?: number | undefined;
+    indexHint?: string | undefined;
+}, {
+    predicates?: ({
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    })[] | undefined;
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    search?: {
+        index: string;
+        query: string;
+    } | undefined;
+    vector?: unknown;
+    maxScan?: number | undefined;
+    indexHint?: string | undefined;
+}>;
+export type Query = z.infer<typeof querySchema>;
+export declare function makePredicate(field: string, op: PredicateOp, value: unknown): Predicate;
+/** Profile/share clamp: predicates + optional default order/search only. */
+export declare const clampQuerySchema: z.ZodObject<{
+    predicates: z.ZodOptional<z.ZodArray<z.ZodType<{
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    }, z.ZodTypeDef, {
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    }>, "many">>;
+    order: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        direction: "asc" | "desc";
+    }, {
+        field: string;
+        direction: "asc" | "desc";
+    }>>;
+    search: z.ZodOptional<z.ZodObject<{
+        index: z.ZodString;
+        query: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        index: string;
+        query: string;
+    }, {
+        index: string;
+        query: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    predicates?: ({
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    })[] | undefined;
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    search?: {
+        index: string;
+        query: string;
+    } | undefined;
+}, {
+    predicates?: ({
+        field: string;
+        op: "eq" | "neq";
+        value: unknown;
+    } | {
+        field: string;
+        op: "in";
+        value: unknown[];
+    } | {
+        field: string;
+        op: "gte" | "lte" | "gt" | "lt";
+        value: unknown;
+    } | {
+        field: string;
+        op: "between";
+        value: BetweenValue;
+    } | {
+        field: string;
+        op: "containsAll";
+        value: unknown[];
+    })[] | undefined;
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    search?: {
+        index: string;
+        query: string;
+    } | undefined;
+}>;
+export type ClampQuery = z.infer<typeof clampQuerySchema>;
+export declare const listMetaOrderSchema: z.ZodUnion<[z.ZodObject<{
+    field: z.ZodString;
+    direction: z.ZodEnum<["asc", "desc"]>;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    direction: "asc" | "desc";
+}, {
+    field: string;
+    direction: "asc" | "desc";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"relevance">;
+}, "strip", z.ZodTypeAny, {
+    kind: "relevance";
+}, {
+    kind: "relevance";
+}>]>;
+export type ListMetaOrder = z.infer<typeof listMetaOrderSchema>;
+export declare const listMetaSchema: z.ZodObject<{
+    access: z.ZodEnum<["table", "index", "search", "idList"]>;
+    page: z.ZodEnum<["paginate", "boundedSort"]>;
+    order: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        direction: "asc" | "desc";
+    }, {
+        field: string;
+        direction: "asc" | "desc";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"relevance">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "relevance";
+    }, {
+        kind: "relevance";
+    }>]>>;
+    indexName: z.ZodOptional<z.ZodString>;
+    searchIndexName: z.ZodOptional<z.ZodString>;
+    scanned: z.ZodOptional<z.ZodNumber>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    access: "index" | "search" | "table" | "idList";
+    page: "paginate" | "boundedSort";
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | {
+        kind: "relevance";
+    } | undefined;
+    indexName?: string | undefined;
+    searchIndexName?: string | undefined;
+    scanned?: number | undefined;
+    truncated?: boolean | undefined;
+}, {
+    access: "index" | "search" | "table" | "idList";
+    page: "paginate" | "boundedSort";
+    order?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | {
+        kind: "relevance";
+    } | undefined;
+    indexName?: string | undefined;
+    searchIndexName?: string | undefined;
+    scanned?: number | undefined;
+    truncated?: boolean | undefined;
+}>;
+export type ListMeta = z.infer<typeof listMetaSchema>;
+export type ListResult<T> = {
+    page: T[];
+    isDone: boolean;
+    continueCursor: string;
+    meta: ListMeta;
+};
+export type QueryError = {
+    code: QueryErrorCode;
+    message: string;
+};
+export declare function parseQuery(input: unknown): {
+    ok: true;
+    query: Query;
+} | {
+    ok: false;
+    error: QueryError;
+};
+export declare function parseClampQuery(input: unknown): {
+    ok: true;
+    query: ClampQuery;
+} | {
+    ok: false;
+    error: QueryError;
+};
+/** Parse a persisted Query JSON payload through the canonical schema. */
+export declare function parseQueryJson(raw: string): Query | null;
+/** Stable compact JSON used by URLs and rich-document record-table blocks. */
+export declare function stringifyQuery(query: Query): string;
+export declare function queriesEqual(a: Query | null | undefined, b: Query | null | undefined): boolean;