@dalgo/dalgo2typesense 0.0.0-bootstrap.0 → 0.2.1

package/dist/metadata.js

@@ -0,0 +1,159 @@
+import { TypesenseHttpError, TypesenseRequestError, TypesenseResponseSizeError } from "./errors.js";
+import { isObject } from "./transport.js";
+const FIELD_TYPE = /^[A-Za-z][A-Za-z0-9[\]_]*$/u;
+function failureFor(error) {
+    if (error instanceof TypesenseHttpError) {
+        return {
+            reason: error.status === 401 ? "unauthorized" : error.status === 403 ? "forbidden" : error.status === 404 ? "not-found" : "unavailable",
+            httpStatus: error.status,
+        };
+    }
+    if (error instanceof TypesenseRequestError || error instanceof TypesenseResponseSizeError)
+        return { reason: "unavailable" };
+    if (error instanceof TypeError)
+        return { reason: "malformed" };
+    return { reason: "unavailable" };
+}
+export function metadataFailure(error) {
+    return failureFor(error);
+}
+export function supportedDeclaredType(type) {
+    return type === "string" || type === "string[]"
+        || type === "int32" || type === "int32[]"
+        || type === "int64" || type === "int64[]"
+        || type === "float" || type === "float[]"
+        || type === "bool" || type === "bool[]"
+        || type === "object" || type === "object[]"
+        || type === "geopoint" || type === "geopoint[]"
+        || type === "geopolygon" || type === "auto";
+}
+function requiredString(value, label, maximum = 1_024) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || !value.isWellFormed()) {
+        throw new TypeError(`malformed Typesense ${label}`);
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            throw new TypeError(`malformed Typesense ${label}`);
+    }
+    return value;
+}
+function optionalBoolean(value, label, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new TypeError(`malformed Typesense ${label}`);
+    return value;
+}
+/**
+ * The official 30.2 `Collection.get_summary_json` always includes
+ * `default_sorting_field`, and a collection created without one carries the
+ * empty string. An empty sentinel is valid; a non-string, non-well-formed or
+ * control-bearing value is still malformed.
+ */
+function defaultSortingField(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length > 256 || !value.isWellFormed()) {
+        throw new TypeError("malformed Typesense default_sorting_field");
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            throw new TypeError("malformed Typesense default_sorting_field");
+    }
+    return value;
+}
+function optionalNumber(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`malformed Typesense ${label}`);
+    }
+    return value;
+}
+/** Parses the real collection schema. Arrays keep their declared native type. */
+export function parseCollectionSchema(value, expectedName, maxFields) {
+    if (!isObject(value))
+        throw new TypeError("malformed Typesense collection schema");
+    const name = requiredString(value.name, "collection name", 256);
+    if (name !== expectedName)
+        throw new TypeError("Typesense collection schema name does not match the configured collection");
+    if (!Array.isArray(value.fields))
+        throw new TypeError("malformed Typesense collection fields");
+    if (value.fields.length > maxFields)
+        throw new RangeError("Typesense collection fields exceed maxColumns");
+    const seen = new Set();
+    const fields = [];
+    for (const raw of value.fields) {
+        if (!isObject(raw))
+            throw new TypeError("malformed Typesense collection field");
+        const fieldName = requiredString(raw.name, "field name", 256);
+        if (fieldName.startsWith("$") || /[,\t\r\n]/u.test(fieldName))
+            throw new TypeError("unsupported Typesense field name");
+        if (seen.has(fieldName))
+            throw new TypeError("duplicate Typesense field name");
+        seen.add(fieldName);
+        const type = requiredString(raw.type, "field type", 64);
+        if (!FIELD_TYPE.test(type) || !supportedDeclaredType(type))
+            throw new TypeError("unsupported Typesense field type");
+        if (fieldName === "id" && type !== "string")
+            throw new TypeError("explicit Typesense id field type must be string");
+        fields.push(Object.freeze({
+            name: fieldName,
+            type,
+            facet: optionalBoolean(raw.facet, "field facet", false),
+            // Typesense always returns the id string and assigns one when omitted, so
+            // an explicitly optional id is normalised to non-null. It is not invented
+            // twice when declared.
+            optional: fieldName === "id" ? false : optionalBoolean(raw.optional, "field optional", false),
+            index: optionalBoolean(raw.index, "field index", true),
+            sort: optionalBoolean(raw.sort, "field sort", false),
+            infix: optionalBoolean(raw.infix, "field infix", false),
+        }));
+    }
+    if (!seen.has("id")) {
+        fields.push(Object.freeze({
+            name: "id",
+            type: "string",
+            facet: false,
+            optional: false,
+            index: true,
+            sort: false,
+            infix: false,
+        }));
+    }
+    const defaultSortingFieldValue = defaultSortingField(value.default_sorting_field);
+    const numDocuments = optionalNumber(value.num_documents, "num_documents");
+    return Object.freeze({
+        name,
+        fields: Object.freeze(fields),
+        ...(defaultSortingFieldValue === undefined ? {} : { defaultSortingField: defaultSortingFieldValue }),
+        ...(numDocuments === undefined ? {} : { numDocuments }),
+    });
+}
+/** Parses `GET /collections` and never turns a denial into an empty list. */
+export function parseCollectionList(value, maximum) {
+    if (!Array.isArray(value))
+        throw new TypeError("malformed Typesense collection list");
+    const truncated = value.length > maximum;
+    const names = [];
+    const seen = new Set();
+    for (const entry of value.slice(0, maximum)) {
+        if (!isObject(entry))
+            throw new TypeError("malformed Typesense collection entry");
+        const name = requiredString(entry.name, "collection name", 256);
+        if (seen.has(name))
+            throw new TypeError("duplicate Typesense collection name");
+        seen.add(name);
+        names.push(name);
+    }
+    return { collections: Object.freeze(names.sort()), truncated };
+}
+export function schemaFieldTypes(schema) {
+    const result = new Map();
+    for (const field of schema.fields)
+        result.set(field.name, field.type);
+    return result;
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

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

package/dist/search.d.ts

@@ -0,0 +1,82 @@
+export interface TypesenseSort {
+    readonly field: string;
+    readonly direction?: "asc" | "desc";
+}
+/** One bounded, typed native Typesense search. No arbitrary option bag. */
+export interface TypesenseNativeSearchRequest {
+    /** Native query text. `*` is the wildcard query. */
+    readonly q: string;
+    /** Full-text fields. Required unless `q` is `*`. */
+    readonly queryBy?: readonly string[];
+    /** Bounded native Typesense filter expression; negative filters are retained here. */
+    readonly filterBy?: string;
+    readonly sortBy?: readonly TypesenseSort[];
+    readonly facetBy?: readonly string[];
+    readonly maxFacetValues?: number;
+    readonly limit: number;
+    readonly offset?: number;
+}
+export interface TypesenseNativeSearchHit {
+    readonly id: string;
+    /** The complete native document, including its string id. */
+    readonly document: Readonly<Record<string, unknown>>;
+    /**
+     * The server's native full-text ranking score as its **exact decimal
+     * string**. Typesense serialises the uint64 `text_match` wrapper, which
+     * routinely exceeds Number.MAX_SAFE_INTEGER, so a JavaScript number would
+     * silently round the ranking. The string is never converted to a number and
+     * is cross-checked against `text_match_info.score` when the server sends it.
+     */
+    readonly textMatch?: string;
+    readonly curated: boolean;
+}
+export interface TypesenseFacetValue {
+    readonly value: string;
+    readonly count: number;
+    readonly highlighted?: string;
+}
+export interface TypesenseFacetStats {
+    readonly min?: number;
+    readonly max?: number;
+    readonly sum?: number;
+    readonly avg?: number;
+    readonly totalValues?: number;
+}
+export interface TypesenseFacet {
+    readonly field: string;
+    readonly counts: readonly TypesenseFacetValue[];
+    readonly stats?: TypesenseFacetStats;
+}
+export interface TypesenseNativeSearchResult {
+    readonly collection: string;
+    readonly hits: readonly TypesenseNativeSearchHit[];
+    readonly facets: readonly TypesenseFacet[];
+    readonly found: number;
+    readonly outOf: number;
+    readonly page: number;
+    readonly returned: number;
+    readonly searchTimeMs: number;
+    readonly partial: boolean;
+    readonly complete: boolean;
+    readonly truncated: boolean;
+    readonly provenance: "typesense-native-search";
+}
+export interface DecodedSearch {
+    readonly hits: readonly TypesenseNativeSearchHit[];
+    readonly facets: readonly TypesenseFacet[];
+    readonly found: number;
+    readonly outOf: number;
+    readonly page: number;
+    readonly searchTimeMs: number;
+    readonly cutoff: boolean;
+}
+export interface SearchDecodeOptions {
+    readonly limit: number;
+    readonly offset: number;
+    readonly facetFields: readonly string[];
+    readonly maxFacetValues: number;
+    readonly maxRowBytes: number;
+}
+/** Decodes one search response strictly. No array, id or count is inferred. */
+export declare function decodeSearchResponse(value: unknown, options: SearchDecodeOptions): DecodedSearch;
+export declare function buildNativeResult(collection: string, decoded: DecodedSearch, limit: number, offset: number): TypesenseNativeSearchResult;

package/dist/search.js

@@ -0,0 +1,238 @@
+import { isExactUint64, isLosslessNumber } from "./json.js";
+import { isObject, isPlainObject } from "./transport.js";
+function requiredInteger(value, label, allowZero = true) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (allowZero ? 0 : 1)) {
+        throw new TypeError(`malformed Typesense ${label}`);
+    }
+    return value;
+}
+function optionalInteger(value, label, allowZero = true) {
+    if (value === undefined)
+        return undefined;
+    return requiredInteger(value, label, allowZero);
+}
+function rowBytes(document, maximum) {
+    let text;
+    try {
+        text = JSON.stringify(document);
+    }
+    catch {
+        throw new TypeError("Typesense document is not JSON-encodable");
+    }
+    if (new TextEncoder().encode(text).byteLength > maximum) {
+        throw new RangeError("Typesense document exceeds maxRowBytes");
+    }
+}
+/**
+ * Reads the native score at its known protocol location. An unsafe uint64
+ * `text_match` token was already proven to be exactly this path by the raw
+ * scanner, so the parsed value is its exact decimal string. A safe integer is
+ * normalised to the same string representation. If the server also emits
+ * `text_match_info.score`, the two exact decimals must agree.
+ */
+function nativeTextMatch(raw) {
+    let exact;
+    const value = raw.text_match;
+    if (value !== undefined) {
+        if (typeof value === "number") {
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw new TypeError("malformed Typesense text_match");
+            exact = String(value);
+        }
+        else if (typeof value === "string") {
+            if (!isExactUint64(value))
+                throw new TypeError("malformed Typesense text_match");
+            exact = value;
+        }
+        else {
+            throw new TypeError("malformed Typesense text_match");
+        }
+    }
+    const info = raw.text_match_info;
+    if (info !== undefined) {
+        if (!isPlainObject(info))
+            throw new TypeError("malformed Typesense text_match_info");
+        const score = info.score;
+        if (score !== undefined) {
+            let counterpart;
+            if (typeof score === "number") {
+                if (!Number.isSafeInteger(score) || score < 0)
+                    throw new TypeError("malformed Typesense text_match_info.score");
+                counterpart = String(score);
+            }
+            else if (typeof score === "string") {
+                if (!isExactUint64(score))
+                    throw new TypeError("malformed Typesense text_match_info.score");
+                counterpart = score;
+            }
+            else {
+                throw new TypeError("malformed Typesense text_match_info.score");
+            }
+            if (exact === undefined)
+                exact = counterpart;
+            else if (exact !== counterpart)
+                throw new TypeError("Typesense text_match and text_match_info.score disagree");
+        }
+    }
+    return exact;
+}
+/** Decodes one search response strictly. No array, id or count is inferred. */
+export function decodeSearchResponse(value, options) {
+    if (!isObject(value))
+        throw new TypeError("malformed Typesense search response");
+    const found = requiredInteger(value.found, "found");
+    const outOf = requiredInteger(value.out_of, "out_of");
+    const page = optionalInteger(value.page, "page") ?? 0;
+    const searchTimeMs = optionalInteger(value.search_time_ms, "search_time_ms") ?? 0;
+    let cutoff = false;
+    if (value.search_cutoff !== undefined) {
+        if (typeof value.search_cutoff !== "boolean")
+            throw new TypeError("malformed Typesense search_cutoff");
+        cutoff = value.search_cutoff;
+    }
+    if (!Array.isArray(value.hits))
+        throw new TypeError("malformed Typesense hits");
+    if (value.hits.length > options.limit)
+        throw new TypeError("Typesense returned more hits than requested");
+    const hits = [];
+    const seen = new Set();
+    for (const raw of value.hits) {
+        if (!isObject(raw) || !isPlainObject(raw.document))
+            throw new TypeError("malformed Typesense search hit");
+        const id = raw.document.id;
+        if (typeof id !== "string" || id.length === 0 || id.length > 1_024 || !id.isWellFormed()) {
+            throw new TypeError("Typesense search hit document id must be a non-empty bounded string");
+        }
+        for (let index = 0; index < id.length; index += 1) {
+            const code = id.charCodeAt(index);
+            if (code < 0x20 || code === 0x7f)
+                throw new TypeError("Typesense search hit document id is not supported");
+        }
+        if (seen.has(id))
+            throw new TypeError("Typesense search response contains a duplicate document id");
+        seen.add(id);
+        rowBytes(raw.document, options.maxRowBytes);
+        const textMatch = nativeTextMatch(raw);
+        const curated = raw.curated === undefined ? false : raw.curated;
+        if (typeof curated !== "boolean")
+            throw new TypeError("malformed Typesense curated flag");
+        hits.push(Object.freeze({
+            id,
+            document: Object.freeze({ ...raw.document }),
+            curated,
+            ...(textMatch === undefined ? {} : { textMatch }),
+        }));
+    }
+    if ((hits.length > 0 && found < options.offset + hits.length) || outOf < found) {
+        throw new TypeError("Typesense search counts are inconsistent with the requested offset");
+    }
+    const facets = decodeFacets(value.facet_counts, options.facetFields, options.maxFacetValues);
+    return Object.freeze({
+        hits: Object.freeze(hits),
+        facets,
+        found,
+        outOf,
+        page,
+        searchTimeMs,
+        cutoff,
+    });
+}
+function decodeFacets(value, requested, maximum) {
+    if (value === undefined || value === null) {
+        if (requested.length > 0)
+            throw new TypeError("Typesense facet_counts is missing");
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(value))
+        throw new TypeError("malformed Typesense facet_counts");
+    if (requested.length === 0) {
+        if (value.length > 0)
+            throw new TypeError("Typesense returned facet_counts that were not requested");
+        return Object.freeze([]);
+    }
+    if (value.length !== requested.length)
+        throw new TypeError("Typesense facet_counts does not match the requested facets");
+    const wanted = new Set(requested);
+    const seen = new Set();
+    const facets = [];
+    for (const raw of value) {
+        if (!isObject(raw) || typeof raw.field_name !== "string" || raw.field_name.length === 0) {
+            throw new TypeError("malformed Typesense facet");
+        }
+        if (!wanted.has(raw.field_name) || seen.has(raw.field_name))
+            throw new TypeError("Typesense returned an unrequested or duplicate facet");
+        seen.add(raw.field_name);
+        if (!Array.isArray(raw.counts) || raw.counts.length > maximum)
+            throw new TypeError("malformed Typesense facet counts");
+        const counts = [];
+        const values = new Set();
+        for (const count of raw.counts) {
+            if (!isObject(count) || typeof count.value !== "string")
+                throw new TypeError("malformed Typesense facet value");
+            if (values.has(count.value))
+                throw new TypeError("Typesense facet contains a duplicate value");
+            values.add(count.value);
+            const amount = requiredInteger(count.count, "facet count");
+            const highlighted = count.highlighted === undefined ? undefined : count.highlighted;
+            if (highlighted !== undefined && typeof highlighted !== "string")
+                throw new TypeError("malformed Typesense facet highlight");
+            counts.push(Object.freeze({
+                value: count.value,
+                count: amount,
+                ...(highlighted === undefined ? {} : { highlighted }),
+            }));
+        }
+        const stats = raw.stats === undefined || raw.stats === null ? undefined : decodeStats(raw.stats);
+        facets.push(Object.freeze({
+            field: raw.field_name,
+            counts: Object.freeze(counts),
+            ...(stats === undefined ? {} : { stats }),
+        }));
+    }
+    return Object.freeze(facets);
+}
+function decodeStats(value) {
+    if (!isObject(value))
+        throw new TypeError("malformed Typesense facet stats");
+    const numeric = (name) => {
+        const raw = value[name];
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== "number" || !isLosslessNumber(raw))
+            throw new TypeError("malformed Typesense facet statistic");
+        return raw;
+    };
+    const min = numeric("min");
+    const max = numeric("max");
+    const sum = numeric("sum");
+    const avg = numeric("avg");
+    const totalValues = value.total_values === undefined ? undefined : requiredInteger(value.total_values, "facet total_values");
+    return Object.freeze({
+        ...(min === undefined ? {} : { min }),
+        ...(max === undefined ? {} : { max }),
+        ...(sum === undefined ? {} : { sum }),
+        ...(avg === undefined ? {} : { avg }),
+        ...(totalValues === undefined ? {} : { totalValues }),
+    });
+}
+export function buildNativeResult(collection, decoded, limit, offset) {
+    const returned = decoded.hits.length;
+    const truncated = decoded.found > offset + returned;
+    const partial = decoded.cutoff || (returned < limit && decoded.found > offset + returned);
+    const complete = !partial && !truncated && !decoded.cutoff;
+    return Object.freeze({
+        collection,
+        hits: decoded.hits,
+        facets: decoded.facets,
+        found: decoded.found,
+        outOf: decoded.outOf,
+        page: decoded.page,
+        returned,
+        searchTimeMs: decoded.searchTimeMs,
+        partial,
+        complete,
+        truncated,
+        provenance: "typesense-native-search",
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA0FzD,SAAS,eAAe,CAAC,KAAc,EAAE,KAAa,EAAE,SAAS,GAAG,IAAI;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7F,MAAM,IAAI,SAAS,CAAC,uBAAuB,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,KAAc,EAAE,KAAa,EAAE,SAAS,GAAG,IAAI;IACtE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,QAAQ,CAAC,QAA2C,EAAE,OAAe;IAC5E,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,OAAO,EAAE,CAAC;QACxD,MAAM,IAAI,UAAU,CAAC,wCAAwC,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,GAAsC;IAC7D,IAAI,KAAyB,CAAC;IAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;IAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;gBAAE,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;YACrG,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;YACjF,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,eAAe,CAAC;IACjC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,WAAmB,CAAC;YACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;oBAAE,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;gBAChH,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACrC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;oBAAE,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;gBAC5F,WAAW,GAAG,KAAK,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,KAAK,KAAK,SAAS;gBAAE,KAAK,GAAG,WAAW,CAAC;iBACxC,IAAI,KAAK,KAAK,WAAW;gBAAE,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;QACjH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,OAA4B;IAC/E,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAClF,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;QACvG,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAC/B,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC;IAChF,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK;QAAE,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IAC1G,MAAM,IAAI,GAA+B,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QAC1G,MAAM,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC;YACzF,MAAM,IAAI,SAAS,CAAC,qEAAqE,CAAC,CAAC;QAC7F,CAAC;QACD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;gBAAE,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;QAC7G,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;QACpG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5C,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;QAChE,IAAI,OAAO,OAAO,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;QAC1F,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACtB,EAAE;YACF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC5C,OAAO;YACP,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SAClD,CAAC,CAAC,CAAC;IACN,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;QAC/E,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7F,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACzB,MAAM;QACN,KAAK;QACL,KAAK;QACL,IAAI;QACJ,YAAY;QACZ,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,SAA4B,EAAE,OAAe;IACjF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;QACnF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IACnF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;QACrG,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;QAAE,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;IACzH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxF,MAAM,IAAI,SAAS,CAAC,2BAA2B,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;QACzI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;QACvH,MAAM,MAAM,GAA0B,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;YAC/B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;gBAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;YAChH,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;YAC/F,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACxB,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;YAC3D,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;YACpF,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,KAAK,QAAQ;gBAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;YAC7H,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,KAAK,EAAE,MAAM;gBACb,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;aACtD,CAAC,CAAC,CAAC;QACN,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACxB,KAAK,EAAE,GAAG,CAAC,UAAU;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;YAC7B,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;SAC1C,CAAC,CAAC,CAAC;IACN,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,CAAC,IAAY,EAAsB,EAAE;QACnD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;QAClH,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,WAAW,GAAG,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;IAC7H,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;KACtD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,OAAsB,EACtB,KAAa,EACb,MAAc;IAEd,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IACrC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,GAAG,KAAK,IAAI,OAAO,CAAC,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;IAC1F,MAAM,QAAQ,GAAG,CAAC,OAAO,IAAI,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ;QACR,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,OAAO;QACP,QAAQ;QACR,SAAS;QACT,UAAU,EAAE,yBAAyB;KACtC,CAAC,CAAC;AACL,CAAC"}

package/dist/structured.d.ts

@@ -0,0 +1,79 @@
+import { type StructuredQuery, type TugQLCondition } from "@dalgo/core";
+/** A core `StructuredQuery` plus the approved provider-local additions. */
+export interface TypesenseQuery<T> extends StructuredQuery<T> {
+    /** Provider-local exact predicate, ANDed with the flat `filters` array. */
+    readonly where?: TugQLCondition;
+    /** Exact top-level fields to return. The native id is fetched but not returned unless named. */
+    readonly projection?: readonly string[];
+}
+export type Truth = "true" | "false" | "unknown";
+export type LiteralClass = "string" | "number" | "boolean";
+export interface FilterLiteral {
+    readonly class: LiteralClass;
+    readonly value: string | number | boolean;
+    readonly wire: string;
+}
+export interface ComparisonNode {
+    readonly kind: "comparison";
+    readonly field: string;
+    readonly operator: "==" | "<" | "<=" | ">" | ">=" | "in";
+    readonly literal?: FilterLiteral;
+    readonly literals?: readonly FilterLiteral[];
+}
+export interface GroupNode {
+    readonly kind: "group";
+    readonly operator: "and" | "or";
+    readonly children: readonly ConditionNode[];
+}
+export type ConditionNode = ComparisonNode | GroupNode;
+export interface CompileOptions {
+    readonly maxFilterBytes: number;
+    readonly maxDepth?: number;
+    readonly maxConditions?: number;
+}
+export declare function structuredField(value: unknown): string;
+export declare function projectionFields(value: readonly string[] | undefined, maximum: number): readonly string[] | undefined;
+export declare function orderFields(orders: StructuredQuery<unknown>["orders"], maximum: number): readonly {
+    readonly field: string;
+    readonly direction: "asc" | "desc";
+}[];
+export declare function isNumericSchemaType(type: string | undefined): boolean;
+export declare function isNumericField(fields: ReadonlyMap<string, string>, field: string): boolean;
+export declare function filterLiteral(value: unknown): FilterLiteral;
+/** Renders the final filter after the database has supplied the real schema. */
+export declare function renderPredicate(node: ConditionNode, numeric: ReadonlyMap<string, string>, maxBytes: number): string;
+/**
+ * Builds and validates the complete admitted condition AST before any request.
+ * Numeric ranges are rendered later, once the real collection schema proves
+ * that the field is a scalar numeric type.
+ */
+export declare function predicateRoot<T>(query: TypesenseQuery<T>, options: CompileOptions): ConditionNode | undefined;
+export declare function collectPredicate(node: ConditionNode): {
+    readonly fields: readonly string[];
+    readonly ranges: readonly string[];
+};
+/**
+ * A deterministic, secret-free serialisation of the admitted predicate that
+ * retains the original operators and literal classes.
+ *
+ * The rendered native filter is deliberately not enough to identify a query:
+ * Typesense candidate normalisation widens `>`/`<` to `>=`/`<=` and two
+ * different exact predicates can therefore render one identical filter string.
+ * Cursor identity must bind the exact validated AST so a stricter handle can
+ * never be replayed as its widened neighbour.
+ */
+export declare function canonicalPredicate(node: ConditionNode | undefined): unknown;
+/** Mutable work budget shared by every row verified for one operation/window. */
+export interface VerificationState {
+    work: number;
+}
+export declare function createVerifierState(): VerificationState;
+/**
+ * Creates an exact verifier. The work budget is shared across all rows of one
+ * operation, so a query that verifies many small rows still reaches the
+ * macrotask cadence: a bounded per-row counter could never yield for trees
+ * smaller than the old 256-node threshold.
+ */
+export declare function createVerifier(node: ConditionNode, state?: VerificationState): (data: Readonly<Record<string, unknown>>, check: () => void) => Promise<boolean>;
+/** Yields an actual macrotask, not merely a promise microtask. */
+export declare function yieldToEventLoop(): Promise<void>;