@venizia/ignis-connectors 0.2.0-0

package/dist/cjs/search/typesense/repositories/dialect/query-dialect.d.ts

@@ -0,0 +1,62 @@
+import { type TFilter, type TWhere } from '@venizia/ignis-filter';
+import type { ISearchCompileCapabilities, ISearchQuery, ISearchQueryDialect, TCompiledWhere, TSearchInput } from '../../../../search/core/repositories/common';
+import { SearchModes } from '../../../../search/core/repositories/common';
+import type { ITypesenseSearchQuery } from '../../../../search/typesense/repositories/common';
+/** The non-raw search inputs the dialect translates; `raw` bypasses the dialect entirely. */
+type TTranslatableSearchInput = Exclude<TSearchInput, {
+    mode: typeof SearchModes.RAW;
+}>;
+/** Translates repository-level TFilter/TWhere into Typesense search params - pure string building, no dependency on the `typesense` package. Untranslatable shapes (relations, pattern/regex) throw, as does any field name the collection does not declare. */
+export declare class TypesenseQueryDialect implements ISearchQueryDialect {
+    build(opts: {
+        filter?: TFilter;
+        hiddenFields?: string[];
+        capabilities?: ISearchCompileCapabilities;
+    }): ITypesenseSearchQuery;
+    /** Maps a camelCase `ISearchQuery` onto Typesense's snake_case wire params via `SearchWireKeys.wireKey`; unmapped keys (`page`, `offset`) pass through unchanged and `engineParams` merges last, verbatim. */
+    toWireParams(opts: {
+        query: Partial<ISearchQuery>;
+    }): Record<string, unknown>;
+    /** Writes the mode dispatch, the vector clause and the `prefix` default onto `query`; everything engine-specific about a non-raw search lives here, so the repository tier stays neutral. */
+    applySearchInput(opts: {
+        query: ISearchQuery;
+        input: TTranslatableSearchInput;
+    }): void;
+    /** Builds Typesense's `<field>:([v1, v2, ...], k: N, alpha: A)` vector-search clause; an omitted `nearVector` emits an empty `[]`, Typesense's server-side auto-embed path, rather than requiring the caller to already hold a vector. */
+    private buildVectorClause;
+    /** Copies faceting/highlighting/grouping/tuning params (shared by keyword/semantic/hybrid, absent from `raw`) onto the query; arrays are comma-joined as `build` joins queryBy/fields. */
+    private applyCommonParams;
+    /**
+     * @deprecated Use `compileWhere`. A `filter_by` STRING cannot represent "matches nothing", so
+     * this returned `''` for it - indistinguishable from "no constraint", which is precisely how an
+     * empty `or` came to widen the query it was written to narrow. It now throws on that input.
+     */
+    toWhere(opts: {
+        where: TWhere;
+    }): string;
+    /** Compiles a `TWhere` into a Typesense `filter_by` expression or one of the two absorbing outcomes. Top-level keys conjoin. */
+    compileWhere(opts: {
+        where: TWhere;
+        capabilities?: ISearchCompileCapabilities;
+    }): TCompiledWhere;
+    /** @see ISearchQueryDialect.canExpress */
+    canExpress(opts: {
+        operator: string;
+    }): boolean;
+    /** @see ISearchQueryDialect.conjoin */
+    conjoin(opts: {
+        clauses: TCompiledWhere[];
+    }): TCompiledWhere;
+    private toOrderBy;
+    /** A logical group always parenthesises, so precedence never depends on where the group sat in the tree. */
+    private compileLogicalGroup;
+    private compileFieldClause;
+    private compileOperatorClause;
+    private escapeValue;
+    private escapeArray;
+    /** Shared by `between` and `notBetween` so the two cannot disagree on what a valid range is. */
+    private assertBetweenTuple;
+    private escapeBetween;
+}
+export {};
+//# sourceMappingURL=query-dialect.d.ts.map

package/dist/cjs/search/typesense/repositories/dialect/query-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-dialect.d.ts","sourceRoot":"","sources":["../../../../../../src/search/typesense/repositories/dialect/query-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,KAAK,EACV,0BAA0B,EAC1B,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,YAAY,EACb,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAwB,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAUtF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAIpF,6FAA6F;AAC7F,KAAK,wBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,OAAO,WAAW,CAAC,GAAG,CAAA;CAAE,CAAC,CAAC;AAqIxF,gQAAgQ;AAChQ,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,KAAK,CAAC,IAAI,EAAE;QACV,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,YAAY,CAAC,EAAE,0BAA0B,CAAC;KAC3C,GAAG,qBAAqB;IA8DzB,8MAA8M;IAC9M,YAAY,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAqB7E,6LAA6L;IAC7L,gBAAgB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,wBAAwB,CAAA;KAAE,GAAG,IAAI;IAyDtF,0OAA0O;IAC1O,OAAO,CAAC,iBAAiB;IAqCzB,0LAA0L;IAC1L,OAAO,CAAC,iBAAiB;IA4DzB;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAmBxC,gIAAgI;IAChI,YAAY,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,0BAA0B,CAAA;KAAE,GAAG,cAAc;IA8BhG,0CAA0C;IAC1C,UAAU,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAI/C,uCAAuC;IACvC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,GAAG,cAAc;IAW5D,OAAO,CAAC,SAAS;IA2BjB,4GAA4G;IAC5G,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,qBAAqB;IA4F7B,OAAO,CAAC,WAAW;IAiCnB,OAAO,CAAC,WAAW;IAYnB,gGAAgG;IAChG,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,aAAa;CAMtB"}

package/dist/cjs/search/typesense/repositories/dialect/query-dialect.js

@@ -0,0 +1,554 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypesenseQueryDialect = void 0;
+const ignis_filter_1 = require("@venizia/ignis-filter");
+const common_1 = require("../../../../search/core/repositories/common");
+const dialect_helpers_1 = require("../../../../search/core/repositories/common/dialect-helpers");
+const common_2 = require("../../../../search/core/common");
+const core_1 = require("@venizia/ignis-helpers/core");
+/** Maximum number of `order` entries Typesense `sort_by` can express. */
+const MAX_SORT_FIELDS = 3;
+/** Names the engine in every rejection, so a caller reading the error knows it is the ENGINE CHOICE that decided it, not the operator. */
+const ENGINE = 'Typesense';
+/**
+ * Typesense has no null: an optional field is either present with a value or absent, and
+ * `filter_by` cannot test which. That single fact is why `is: null`, `isn: null`, `exists` and
+ * `notExists` are all unexpressible - they are one limitation, not four. The only documented
+ * workaround is an INDEXING-time placeholder (write a sentinel, add it to `symbols_to_index`),
+ * which is a schema decision the caller owns; a dialect cannot synthesise it.
+ */
+const NO_NULL_REASON = 'Typesense has no null representation - an optional field is either present or absent, and filter_by cannot test presence; model it with an explicit sentinel value instead';
+/**
+ * Which neutral operators this engine can express. EVERY member of `QueryOperators.SCHEME_SET`
+ * has a cell - `canExpress` asserts that at construction, so an operator added to the vocabulary
+ * cannot reach an engine unclassified and start silently falling through to a default branch.
+ */
+const CAN_EXPRESS = {
+    [ignis_filter_1.QueryOperators.EQ]: true,
+    [ignis_filter_1.QueryOperators.NE]: true,
+    [ignis_filter_1.QueryOperators.NEQ]: true,
+    [ignis_filter_1.QueryOperators.GT]: true,
+    [ignis_filter_1.QueryOperators.GTE]: true,
+    [ignis_filter_1.QueryOperators.LT]: true,
+    [ignis_filter_1.QueryOperators.LTE]: true,
+    // Pattern matching is a RELEVANCE concern in Typesense - it lives in `q`/`query_by`, not filter_by.
+    [ignis_filter_1.QueryOperators.LIKE]: false,
+    [ignis_filter_1.QueryOperators.NOT_LIKE]: false,
+    [ignis_filter_1.QueryOperators.ILIKE]: false,
+    [ignis_filter_1.QueryOperators.NOT_ILIKE]: false,
+    [ignis_filter_1.QueryOperators.REGEXP]: false,
+    [ignis_filter_1.QueryOperators.IREGEXP]: false,
+    // Expressible against a VALUE; the `: null` form is refused at the value level (see NO_NULL_REASON).
+    [ignis_filter_1.QueryOperators.IS]: true,
+    [ignis_filter_1.QueryOperators.IS_NOT]: true,
+    [ignis_filter_1.QueryOperators.IN]: true,
+    [ignis_filter_1.QueryOperators.INQ]: true,
+    [ignis_filter_1.QueryOperators.NIN]: true,
+    // See NO_NULL_REASON - the same limitation as `is: null`, deliberately not solved twice.
+    [ignis_filter_1.QueryOperators.EXISTS]: false,
+    [ignis_filter_1.QueryOperators.NOT_EXISTS]: false,
+    [ignis_filter_1.QueryOperators.BETWEEN]: true,
+    // Rewritten by De Morgan into `< min OR > max` - see compileOperatorClause.
+    [ignis_filter_1.QueryOperators.NOT_BETWEEN]: true,
+    // Postgres array-containment semantics; Typesense array fields match by value, which is not the same question.
+    [ignis_filter_1.QueryOperators.CONTAINS]: false,
+    [ignis_filter_1.QueryOperators.CONTAINED_BY]: false,
+    [ignis_filter_1.QueryOperators.OVERLAPS]: false,
+    // Negating an ARBITRARY subtree needs De Morgan through the whole tree. Partial support would be
+    // worse than none: `not: 'x'` would work and `not: { and: [...] }` would not, with no way for a
+    // caller to tell which shape they had until it failed.
+    [ignis_filter_1.QueryOperators.NOT]: false,
+    [ignis_filter_1.QueryOperators.AND]: true,
+    [ignis_filter_1.QueryOperators.OR]: true,
+};
+/** camelCase `ISearchQuery` field -> Typesense wire (snake_case) field; the snake_case strings are values only, never identifiers. */
+class SearchWireKeys {
+    static { this.QUERY = { from: 'query', to: 'q' }; }
+    static { this.FILTER_BY = { from: 'filterBy', to: 'filter_by' }; }
+    static { this.SORT_BY = { from: 'sortBy', to: 'sort_by' }; }
+    static { this.PER_PAGE = { from: 'perPage', to: 'per_page' }; }
+    static { this.INCLUDE_FIELDS = { from: 'includeFields', to: 'include_fields' }; }
+    static { this.EXCLUDE_FIELDS = { from: 'excludeFields', to: 'exclude_fields' }; }
+    static { this.QUERY_BY = { from: 'queryBy', to: 'query_by' }; }
+    static { this.VECTOR_QUERY = { from: 'vectorQuery', to: 'vector_query' }; }
+    static { this.FACET_BY = { from: 'facetBy', to: 'facet_by' }; }
+    static { this.FACET_QUERY = { from: 'facetQuery', to: 'facet_query' }; }
+    static { this.MAX_FACET_VALUES = { from: 'maxFacetValues', to: 'max_facet_values' }; }
+    static { this.HIGHLIGHT_FIELDS = { from: 'highlightFields', to: 'highlight_fields' }; }
+    static { this.HIGHLIGHT_FULL_FIELDS = {
+        from: 'highlightFullFields',
+        to: 'highlight_full_fields',
+    }; }
+    static { this.HIGHLIGHT_START_TAG = { from: 'highlightStartTag', to: 'highlight_start_tag' }; }
+    static { this.HIGHLIGHT_END_TAG = { from: 'highlightEndTag', to: 'highlight_end_tag' }; }
+    static { this.SNIPPET_THRESHOLD = { from: 'snippetThreshold', to: 'snippet_threshold' }; }
+    static { this.GROUP_BY = { from: 'groupBy', to: 'group_by' }; }
+    static { this.GROUP_LIMIT = { from: 'groupLimit', to: 'group_limit' }; }
+    static { this.GROUP_MISSING_VALUES = {
+        from: 'groupMissingValues',
+        to: 'group_missing_values',
+    }; }
+    static { this.QUERY_BY_WEIGHTS = { from: 'queryByWeights', to: 'query_by_weights' }; }
+    static { this.ENTRIES = [
+        SearchWireKeys.QUERY,
+        SearchWireKeys.FILTER_BY,
+        SearchWireKeys.SORT_BY,
+        SearchWireKeys.PER_PAGE,
+        SearchWireKeys.INCLUDE_FIELDS,
+        SearchWireKeys.EXCLUDE_FIELDS,
+        SearchWireKeys.QUERY_BY,
+        SearchWireKeys.VECTOR_QUERY,
+        SearchWireKeys.FACET_BY,
+        SearchWireKeys.FACET_QUERY,
+        SearchWireKeys.MAX_FACET_VALUES,
+        SearchWireKeys.HIGHLIGHT_FIELDS,
+        SearchWireKeys.HIGHLIGHT_FULL_FIELDS,
+        SearchWireKeys.HIGHLIGHT_START_TAG,
+        SearchWireKeys.HIGHLIGHT_END_TAG,
+        SearchWireKeys.SNIPPET_THRESHOLD,
+        SearchWireKeys.GROUP_BY,
+        SearchWireKeys.GROUP_LIMIT,
+        SearchWireKeys.GROUP_MISSING_VALUES,
+        SearchWireKeys.QUERY_BY_WEIGHTS,
+    ]; }
+    /** camelCase field -> wire key, built once from ENTRIES so `wireKey` is O(1) per lookup, not O(n) per field per query. */
+    static { this.WIRE_BY_FIELD = Object.fromEntries(SearchWireKeys.ENTRIES.map(entry => [entry.from, entry.to])); }
+    /** Resolves a camelCase field to its wire key; unmapped keys (`page`, `offset`) pass through. */
+    static wireKey(field) {
+        return SearchWireKeys.WIRE_BY_FIELD[field] ?? field;
+    }
+}
+/** Translates repository-level TFilter/TWhere into Typesense search params - pure string building, no dependency on the `typesense` package. Untranslatable shapes (relations, pattern/regex) throw, as does any field name the collection does not declare. */
+class TypesenseQueryDialect {
+    build(opts) {
+        const { filter, hiddenFields, capabilities } = opts;
+        // No early return on a missing filter: `search({ mode: 'keyword', query: 'john' })` carries none, and short-circuiting here skips the exclude-fields block below, leaking the model's `hiddenProperties`.
+        const { where, fields, order, limit, skip, offset, include } = filter ?? {};
+        if (include) {
+            throw (0, core_1.getError)({
+                message: '[TypesenseQueryDialect][build] search() does not support "include" - relations cannot be translated to a Typesense filter',
+            });
+        }
+        const query = { query: '*' };
+        if (where) {
+            const compiled = this.compileWhere({ where, capabilities });
+            if (compiled.outcome === common_1.SearchFilterOutcomes.FILTER) {
+                query.filterBy = compiled.filterBy;
+            }
+            else if (compiled.outcome === common_1.SearchFilterOutcomes.MATCH_NONE) {
+                // Marked, never expressed as a filter: Typesense has no match-nothing primitive, and the
+                // repository answers empty without a round-trip rather than sending something approximate.
+                query.matchNone = true;
+            }
+        }
+        if (order) {
+            query.sortBy = this.toOrderBy({ order, capabilities });
+        }
+        // Native offset, not a page number. `toSearchPage` refuses a skip that is not a multiple of
+        // limit, so `skip: 15, limit: 10` was rejected - a rule Typesense never imposed and one the
+        // relational reference never had either (relational/.../filter.ts:283-287 passes skip straight
+        // through to Drizzle). Exactly one pagination pair reaches the engine, because Typesense
+        // documents offset/limit and page/per_page as alternatives without saying which wins if both
+        // are present.
+        const effectiveSkip = skip ?? offset;
+        if (effectiveSkip === undefined) {
+            if (limit !== undefined) {
+                query.perPage = limit;
+            }
+        }
+        else {
+            query.offset = effectiveSkip;
+            if (limit !== undefined) {
+                query.limit = limit;
+            }
+        }
+        if (fields) {
+            query.includeFields = (0, dialect_helpers_1.toFieldsCsv)({ fields });
+        }
+        if (hiddenFields && hiddenFields.length > 0) {
+            query.excludeFields = hiddenFields.join(',');
+        }
+        return query;
+    }
+    /** Maps a camelCase `ISearchQuery` onto Typesense's snake_case wire params via `SearchWireKeys.wireKey`; unmapped keys (`page`, `offset`) pass through unchanged and `engineParams` merges last, verbatim. */
+    toWireParams(opts) {
+        const { query } = opts;
+        const { engineParams, ...rest } = query;
+        // `matchNone` is a repository-tier instruction, not a search param - dropped here so it can
+        // never reach Typesense as an unknown key. `rest` is already a fresh object.
+        delete rest.matchNone;
+        const wire = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (value === undefined) {
+                continue;
+            }
+            wire[SearchWireKeys.wireKey(key)] = value;
+        }
+        return engineParams ? { ...wire, ...engineParams } : wire;
+    }
+    /** Writes the mode dispatch, the vector clause and the `prefix` default onto `query`; everything engine-specific about a non-raw search lives here, so the repository tier stays neutral. */
+    applySearchInput(opts) {
+        const { input } = opts;
+        const searchQuery = opts.query;
+        switch (input.mode) {
+            case common_1.SearchModes.KEYWORD: {
+                if (input.query) {
+                    searchQuery.query = input.query;
+                }
+                if (input.queryBy) {
+                    searchQuery.queryBy = input.queryBy.join(',');
+                }
+                break;
+            }
+            case common_1.SearchModes.SEMANTIC: {
+                // Vector search: prefix matching is meaningless and remote embedders reject it outright, so it defaults off - applyCommonParams still lets an explicit caller override it.
+                searchQuery.prefix = false;
+                if (input.nearVector) {
+                    searchQuery.vectorQuery = this.buildVectorClause({ ...input, field: input.vectorField });
+                    break;
+                }
+                if (!input.queryText) {
+                    throw (0, core_1.getError)({
+                        message: `[TypesenseQueryDialect][applySearchInput] semantic mode requires 'nearVector' or 'queryText'`,
+                    });
+                }
+                // Auto-embed: the engine vectorizes queryText against vectorField; vector_query carries k.
+                searchQuery.query = input.queryText;
+                searchQuery.queryBy = input.vectorField;
+                searchQuery.vectorQuery = this.buildVectorClause({ ...input, field: input.vectorField });
+                break;
+            }
+            case common_1.SearchModes.HYBRID: {
+                // Same as semantic: the embedded query hits the remote embedder, which rejects prefix search.
+                searchQuery.prefix = false;
+                searchQuery.query = input.query;
+                // Auto-embed (no nearVector) needs the embedding field in query_by; a supplied vector keeps text fields only.
+                searchQuery.queryBy = input.nearVector
+                    ? input.queryBy.join(',')
+                    : [...input.queryBy, input.vectorField].join(',');
+                searchQuery.vectorQuery = this.buildVectorClause({ ...input, field: input.vectorField });
+                break;
+            }
+            default: {
+                break;
+            }
+        }
+        this.applyCommonParams({ query: searchQuery, input });
+    }
+    /** Builds Typesense's `<field>:([v1, v2, ...], k: N, alpha: A)` vector-search clause; an omitted `nearVector` emits an empty `[]`, Typesense's server-side auto-embed path, rather than requiring the caller to already hold a vector. */
+    buildVectorClause(opts) {
+        const { field, nearVector, k, alpha, distanceThreshold, ef } = opts;
+        const vectorCsv = (nearVector ?? [])
+            .map(value => this.escapeValue({ field, value }))
+            .join(', ');
+        let clause = `${field}:([${vectorCsv}]`;
+        if (k !== undefined) {
+            clause += `, k: ${k}`;
+        }
+        if (alpha !== undefined) {
+            clause += `, alpha: ${alpha}`;
+        }
+        if (distanceThreshold !== undefined) {
+            clause += `, distance_threshold: ${distanceThreshold}`;
+        }
+        if (ef !== undefined) {
+            clause += `, ef: ${ef}`;
+        }
+        clause += ')';
+        return clause;
+    }
+    /** Copies faceting/highlighting/grouping/tuning params (shared by keyword/semantic/hybrid, absent from `raw`) onto the query; arrays are comma-joined as `build` joins queryBy/fields. */
+    applyCommonParams(opts) {
+        const { query, input } = opts;
+        if (input.facetBy) {
+            query.facetBy = input.facetBy.join(',');
+        }
+        if (input.facetQuery !== undefined) {
+            query.facetQuery = input.facetQuery;
+        }
+        if (input.maxFacetValues !== undefined) {
+            query.maxFacetValues = input.maxFacetValues;
+        }
+        if (input.highlightFields) {
+            query.highlightFields = input.highlightFields.join(',');
+        }
+        if (input.highlightFullFields) {
+            query.highlightFullFields = input.highlightFullFields.join(',');
+        }
+        if (input.highlightStartTag !== undefined) {
+            query.highlightStartTag = input.highlightStartTag;
+        }
+        if (input.highlightEndTag !== undefined) {
+            query.highlightEndTag = input.highlightEndTag;
+        }
+        if (input.snippetThreshold !== undefined) {
+            query.snippetThreshold = input.snippetThreshold;
+        }
+        if (input.groupBy) {
+            query.groupBy = input.groupBy.join(',');
+        }
+        if (input.groupLimit !== undefined) {
+            query.groupLimit = input.groupLimit;
+        }
+        if (input.groupMissingValues !== undefined) {
+            query.groupMissingValues = input.groupMissingValues;
+        }
+        if (input.queryByWeights) {
+            query.queryByWeights = input.queryByWeights.join(',');
+        }
+        // engineParams carries Typesense's own wire-keyed tuning params, merged verbatim by toWireParams; copied onto the query here so the single-search path reaches that merge.
+        if (input.engineParams) {
+            query.engineParams = input.engineParams;
+        }
+    }
+    /**
+     * @deprecated Use `compileWhere`. A `filter_by` STRING cannot represent "matches nothing", so
+     * this returned `''` for it - indistinguishable from "no constraint", which is precisely how an
+     * empty `or` came to widen the query it was written to narrow. It now throws on that input.
+     */
+    toWhere(opts) {
+        const compiled = this.compileWhere({ where: opts.where });
+        switch (compiled.outcome) {
+            case common_1.SearchFilterOutcomes.FILTER: {
+                return compiled.filterBy;
+            }
+            case common_1.SearchFilterOutcomes.MATCH_ALL: {
+                return '';
+            }
+            default: {
+                throw (0, core_1.getError)({
+                    error: common_2.SearchErrors.UNSUPPORTED_OPERATOR,
+                    message: `[TypesenseQueryDialect][toWhere] This where compiles to MATCH-NOTHING, which a filter_by string cannot express | engine: '${ENGINE}' | returning '' here would match EVERYTHING - call compileWhere() and honour its 'matchNone' outcome instead`,
+                });
+            }
+        }
+    }
+    /** Compiles a `TWhere` into a Typesense `filter_by` expression or one of the two absorbing outcomes. Top-level keys conjoin. */
+    compileWhere(opts) {
+        const { where, capabilities } = opts;
+        const clauses = [];
+        for (const key in where) {
+            // TWhere<T = any> is a mapped-over-`any` type with no narrower runtime shape to recover here; `unknown` is the honest type for a `for...in` value.
+            const value = where[key];
+            if (value === undefined) {
+                continue;
+            }
+            switch (key) {
+                case ignis_filter_1.QueryOperators.AND: {
+                    clauses.push(this.compileLogicalGroup({ value, capabilities, isDisjunction: false }));
+                    break;
+                }
+                case ignis_filter_1.QueryOperators.OR: {
+                    clauses.push(this.compileLogicalGroup({ value, capabilities, isDisjunction: true }));
+                    break;
+                }
+                default: {
+                    clauses.push(this.compileFieldClause({ field: key, value, capabilities }));
+                }
+            }
+        }
+        return (0, dialect_helpers_1.reduceCompiled)({ clauses, isDisjunction: false, joiner: ' && ' });
+    }
+    /** @see ISearchQueryDialect.canExpress */
+    canExpress(opts) {
+        return CAN_EXPRESS[opts.operator] ?? false;
+    }
+    /** @see ISearchQueryDialect.conjoin */
+    conjoin(opts) {
+        const { clauses } = opts;
+        const combined = (0, dialect_helpers_1.reduceCompiled)({ clauses, isDisjunction: false, joiner: ' && ' });
+        // Parenthesised once two clauses actually join, reproducing byte-for-byte what the previous
+        // `{ and: [defaultWhere, where] }` merge emitted through the logical-group path.
+        return clauses.filter(clause => clause.outcome === common_1.SearchFilterOutcomes.FILTER).length > 1
+            ? (0, dialect_helpers_1.parenthesize)(combined)
+            : combined;
+    }
+    toOrderBy(opts) {
+        const { order, capabilities } = opts;
+        if (order.length > MAX_SORT_FIELDS) {
+            throw (0, core_1.getError)({
+                message: `[TypesenseQueryDialect][build] search() sort_by supports at most ${MAX_SORT_FIELDS} fields | got: ${order.length}`,
+            });
+        }
+        return order
+            .map(entry => {
+            const [field, direction = ignis_filter_1.Sorts.ASC] = entry.trim().split(/\s+/);
+            const normalizedDirection = direction.toLowerCase();
+            if (!ignis_filter_1.Sorts.isValid(normalizedDirection)) {
+                throw (0, core_1.getError)({
+                    message: `[TypesenseQueryDialect][build] Invalid sort direction '${direction}' for field '${field}'`,
+                });
+            }
+            (0, dialect_helpers_1.assertKnownField)({ field, engine: ENGINE, capabilities, method: 'toOrderBy' });
+            return `${field}:${normalizedDirection}`;
+        })
+            .join(',');
+    }
+    /** A logical group always parenthesises, so precedence never depends on where the group sat in the tree. */
+    compileLogicalGroup(opts) {
+        const { value, capabilities, isDisjunction } = opts;
+        const items = Array.isArray(value) ? value : [value];
+        const clauses = items.map(item => this.compileWhere({ where: item, capabilities }));
+        // An empty member (`{}`) compiles to matchAll and the algebra absorbs it correctly: identity
+        // under `and`, absorbing under `or`. Dropping it by string-length, as this once did, is what
+        // turned `or: []` into "no constraint".
+        return (0, dialect_helpers_1.parenthesize)((0, dialect_helpers_1.reduceCompiled)({ clauses, isDisjunction, joiner: isDisjunction ? ' || ' : ' && ' }));
+    }
+    compileFieldClause(opts) {
+        const { field, value, capabilities } = opts;
+        (0, dialect_helpers_1.assertKnownField)({ field, engine: ENGINE, capabilities });
+        if (Array.isArray(value)) {
+            // Mirrors relational `buildValueCondition`: an empty IN-list can match nothing, so it is
+            // absorbing false - NOT the malformed `field:=[]` this used to emit.
+            return value.length === 0
+                ? { outcome: common_1.SearchFilterOutcomes.MATCH_NONE }
+                : (0, dialect_helpers_1.toFilterClause)(`${field}:=[${this.escapeArray({ field, value })}]`);
+        }
+        if (!(0, dialect_helpers_1.isOperatorObject)(value)) {
+            return (0, dialect_helpers_1.toFilterClause)(`${field}:=${this.escapeValue({ field, value })}`);
+        }
+        const clauses = Object.entries(value).map(([op, opValue]) => this.compileOperatorClause({ field, op, value: opValue }));
+        const combined = (0, dialect_helpers_1.reduceCompiled)({ clauses, isDisjunction: false, joiner: ' && ' });
+        // Parenthesised only when more than one operator actually contributed a filter, preserving the
+        // exact shape callers already assert on for the single-operator case.
+        return clauses.filter(clause => clause.outcome === common_1.SearchFilterOutcomes.FILTER).length > 1
+            ? (0, dialect_helpers_1.parenthesize)(combined)
+            : combined;
+    }
+    compileOperatorClause(opts) {
+        const { field, op, value } = opts;
+        switch (op) {
+            case ignis_filter_1.QueryOperators.EQ: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.NEQ:
+            case ignis_filter_1.QueryOperators.NE: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:!=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.IS: {
+                // Mirrors PostgresQueryOperators.FNS[IS] (maps null to isNull(column)) for a real value; the null form is the NO_NULL_REASON limitation.
+                if (value === null) {
+                    return (0, dialect_helpers_1.throwUnsupportedOperator)({
+                        operator: op,
+                        field,
+                        engine: ENGINE,
+                        reason: NO_NULL_REASON,
+                    });
+                }
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.IS_NOT: {
+                if (value === null) {
+                    return (0, dialect_helpers_1.throwUnsupportedOperator)({
+                        operator: op,
+                        field,
+                        engine: ENGINE,
+                        reason: NO_NULL_REASON,
+                    });
+                }
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:!=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.GT: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:>${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.GTE: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:>=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.LT: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:<${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.LTE: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:<=${this.escapeValue({ field, value })}`);
+            }
+            case ignis_filter_1.QueryOperators.IN:
+            case ignis_filter_1.QueryOperators.INQ: {
+                // Relational: `inq: []` -> sql`false`. Nothing is a member of the empty set.
+                if (Array.isArray(value) && value.length === 0) {
+                    return { outcome: common_1.SearchFilterOutcomes.MATCH_NONE };
+                }
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:=[${this.escapeArray({ field, value })}]`);
+            }
+            case ignis_filter_1.QueryOperators.NIN: {
+                // Relational: `nin: []` -> sql`true`. Excluding nothing excludes nothing.
+                if (Array.isArray(value) && value.length === 0) {
+                    return { outcome: common_1.SearchFilterOutcomes.MATCH_ALL };
+                }
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:!=[${this.escapeArray({ field, value })}]`);
+            }
+            case ignis_filter_1.QueryOperators.BETWEEN: {
+                return (0, dialect_helpers_1.toFilterClause)(`${field}:[${this.escapeBetween({ field, value })}]`);
+            }
+            case ignis_filter_1.QueryOperators.NOT_BETWEEN: {
+                // De Morgan: NOT (min <= x <= max) is (x < min) OR (x > max). Typesense has no negated
+                // range, but the rewrite is exact for any field that HAS a value.
+                const [min, max] = this.assertBetweenTuple({ field, value });
+                return (0, dialect_helpers_1.toFilterClause)(`(${field}:<${this.escapeValue({ field, value: min })} || ${field}:>${this.escapeValue({ field, value: max })})`);
+            }
+            case ignis_filter_1.QueryOperators.EXISTS:
+            case ignis_filter_1.QueryOperators.NOT_EXISTS: {
+                // The same limitation as `is: null` - stated once, in NO_NULL_REASON.
+                return (0, dialect_helpers_1.throwUnsupportedOperator)({
+                    operator: op,
+                    field,
+                    engine: ENGINE,
+                    reason: NO_NULL_REASON,
+                });
+            }
+            default: {
+                return (0, dialect_helpers_1.throwUnsupportedOperator)({ operator: op, field, engine: ENGINE });
+            }
+        }
+    }
+    escapeValue(opts) {
+        const { field, value } = opts;
+        if (typeof value === 'string') {
+            if (value.includes('`')) {
+                throw (0, core_1.getError)({
+                    message: `[TypesenseQueryDialect][toWhere] search() cannot safely represent a value containing a backtick | field: '${field}' | value: '${value}'`,
+                });
+            }
+            return `\`${value}\``;
+        }
+        if (typeof value === 'number') {
+            // NaN/Infinity would silently produce an unparseable filter_by token (e.g. 'price:>NaN') instead of a clear rejection.
+            if (!Number.isFinite(value)) {
+                throw (0, core_1.getError)({
+                    message: `[TypesenseQueryDialect][toWhere] search() does not support non-finite numbers (NaN/Infinity) | field: '${field}' | value: ${value}`,
+                });
+            }
+            return String(value);
+        }
+        if (typeof value === 'boolean') {
+            return String(value);
+        }
+        throw (0, core_1.getError)({
+            message: `[TypesenseQueryDialect][toWhere] search() does not support this value type | field: '${field}' | value: ${JSON.stringify(value)}`,
+        });
+    }
+    escapeArray(opts) {
+        const { field, value } = opts;
+        if (!Array.isArray(value)) {
+            throw (0, core_1.getError)({
+                message: `[TypesenseQueryDialect][toWhere] search() expected an array value | field: '${field}' | value: ${JSON.stringify(value)}`,
+            });
+        }
+        return value.map(item => this.escapeValue({ field, value: item })).join(',');
+    }
+    /** Shared by `between` and `notBetween` so the two cannot disagree on what a valid range is. */
+    assertBetweenTuple(opts) {
+        const { field, value } = opts;
+        if (!Array.isArray(value) || value.length !== 2) {
+            throw (0, core_1.getError)({
+                message: `[TypesenseQueryDialect][toWhere] search() 'between' requires a [min, max] tuple | field: '${field}' | value: ${JSON.stringify(value)}`,
+            });
+        }
+        return [value[0], value[1]];
+    }
+    escapeBetween(opts) {
+        const { field, value } = opts;
+        const [min, max] = this.assertBetweenTuple({ field, value });
+        return `${this.escapeValue({ field, value: min })}..${this.escapeValue({ field, value: max })}`;
+    }
+}
+exports.TypesenseQueryDialect = TypesenseQueryDialect;
+//# sourceMappingURL=query-dialect.js.map