@venizia/ignis-connectors 0.2.0-0

package/dist/esm/search/core/repositories/common/constants.js

@@ -0,0 +1,143 @@
+import { FieldsSchema, LimitSchema, OffsetSchema, OrderBySchema, SkipSchema, WhereSchema, } from '@venizia/ignis-kernel';
+import { z } from '@hono/zod-openapi';
+/** Discriminant values for `TSearchInput.mode` - which search strategy `ReadableSearchRepository.search()` runs. */
+export class SearchModes {
+    static { this.KEYWORD = 'keyword'; }
+    static { this.SEMANTIC = 'semantic'; }
+    static { this.HYBRID = 'hybrid'; }
+    static { this.RAW = 'raw'; }
+    static { this.SCHEME_SET = new Set([this.KEYWORD, this.SEMANTIC, this.HYBRID, this.RAW]); }
+    static isValid(input) {
+        return this.SCHEME_SET.has(input);
+    }
+}
+/** Reassembled from FilterSchema's atomic pieces minus `include` (search has no relations) so `z.infer` stays finite - embedding the recursive FilterSchema collapses optional-key inference for every sibling field, silently turning `filter` into a required `any`. */
+const SearchFilterSchema = z
+    .object({
+    where: WhereSchema.optional(),
+    fields: FieldsSchema,
+    order: OrderBySchema,
+    limit: LimitSchema,
+    offset: OffsetSchema,
+    skip: SkipSchema,
+})
+    .optional()
+    .openapi({
+    description: 'Search-scoped filter - same shape as the repository TFilter minus include (search has no relations)',
+});
+/** Shape object (NOT a z.object) so it spreads into each mode's z.object; `raw` mode skips it. Only cross-engine params live here - engine-specific tuning goes through `engineParams`. */
+const commonSearchParamsShape = {
+    facetBy: z.array(z.string()).optional(),
+    facetQuery: z.string().optional(),
+    maxFacetValues: z.number().optional(),
+    highlightFields: z.array(z.string()).optional(),
+    highlightFullFields: z.array(z.string()).optional(),
+    highlightStartTag: z.string().optional(),
+    highlightEndTag: z.string().optional(),
+    snippetThreshold: z.number().optional(),
+    groupBy: z.array(z.string()).optional(),
+    groupLimit: z.number().optional(),
+    groupMissingValues: z.boolean().optional(),
+    queryByWeights: z.array(z.number()).optional(),
+    /** Escape hatch for engine-specific tuning: keys are the engine's OWN wire names (`num_typos`, not `numTypos`), merged verbatim and unvalidated after every neutral param. */
+    engineParams: z.record(z.string(), z.unknown()).optional(),
+};
+const KeywordSearchSchema = z
+    .object({
+    mode: z.literal(SearchModes.KEYWORD),
+    query: z.string().optional(),
+    queryBy: z.array(z.string()).optional(),
+    filter: SearchFilterSchema,
+    ...commonSearchParamsShape,
+})
+    .openapi({ description: 'Keyword full-text search' });
+const SemanticSearchSchema = z
+    .object({
+    mode: z.literal(SearchModes.SEMANTIC),
+    vectorField: z.string(),
+    nearVector: z.array(z.number()).optional(),
+    queryText: z.string().optional(),
+    k: z.number().optional(),
+    filter: SearchFilterSchema,
+    ...commonSearchParamsShape,
+    distanceThreshold: z.number().optional(),
+    ef: z.number().optional(),
+})
+    .openapi({ description: 'Vector / semantic search' });
+const HybridSearchSchema = z
+    .object({
+    mode: z.literal(SearchModes.HYBRID),
+    query: z.string(),
+    queryBy: z.array(z.string()),
+    vectorField: z.string(),
+    nearVector: z.array(z.number()).optional(),
+    alpha: z.number().optional(),
+    k: z.number().optional(),
+    filter: SearchFilterSchema,
+    ...commonSearchParamsShape,
+    distanceThreshold: z.number().optional(),
+    ef: z.number().optional(),
+})
+    .openapi({ description: 'Hybrid keyword + vector search' });
+const RawSearchSchema = z
+    .object({
+    mode: z.literal(SearchModes.RAW),
+    params: z.record(z.string(), z.any()),
+})
+    .openapi({ description: 'Raw engine passthrough' });
+export const SearchInputSchema = z.discriminatedUnion('mode', [
+    KeywordSearchSchema,
+    SemanticSearchSchema,
+    HybridSearchSchema,
+    RawSearchSchema,
+]);
+/** One collection's query within a multi-search - same friendly field names as `search()`. `filterBy` is a raw engine filter string because cross-collection search has no per-collection model to translate a `TFilter` against; the datasource maps entries to wire form via the dialect. */
+export const MultiSearchEntrySchema = z
+    .object({
+    collection: z.string(),
+    query: z.string().optional(),
+    queryBy: z.array(z.string()).optional(),
+    filterBy: z.string().optional(),
+    sortBy: z.string().optional(),
+    page: z.number().optional(),
+    perPage: z.number().optional(),
+    offset: z.number().optional(),
+    includeFields: z.array(z.string()).optional(),
+    excludeFields: z.array(z.string()).optional(),
+    vectorQuery: z.string().optional(),
+    ...commonSearchParamsShape,
+})
+    .openapi({ description: 'A single collection query within a multi-search' });
+/** List-shaped friendly fields that are comma-joined into their single `ISearchQuery` wire form. */
+const MULTI_SEARCH_LIST_FIELDS = new Set([
+    'queryBy',
+    'includeFields',
+    'excludeFields',
+    'facetBy',
+    'highlightFields',
+    'highlightFullFields',
+    'groupBy',
+    'queryByWeights',
+]);
+/** Friendly multi-search params -> `ISearchQuery`: list fields comma-joined, the rest pass through; keeps `search()`, `multiSearch()` and `commonParams` on one friendly-to-wire path. */
+export const toSearchQueryParams = (input) => {
+    const params = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || key === 'collection') {
+            continue;
+        }
+        params[key] =
+            MULTI_SEARCH_LIST_FIELDS.has(key) && Array.isArray(value) ? value.join(',') : value;
+    }
+    return params;
+};
+/** Cross-collection multi-search input: friendly `searches` entries plus the union flag. */
+export const MultiSearchInputSchema = z
+    .object({
+    searches: z.array(MultiSearchEntrySchema).min(1),
+    union: z.boolean().optional(),
+})
+    .openapi({
+    description: 'Cross-collection multi-search (federated by default; union merges results)',
+});
+//# sourceMappingURL=constants.js.map

package/dist/esm/search/core/repositories/common/constants.js.map

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

package/dist/esm/search/core/repositories/common/dialect-helpers.d.ts

@@ -0,0 +1,75 @@
+import { type TFields } from '@venizia/ignis-filter';
+import type { ISearchCompileCapabilities, TCompiledWhere } from './types.js';
+/** Dialect-shared pure helpers, shared once rather than byte-copied per dialect; not barrel-exported, not part of the connector's public surface. */
+/** skip/offset -> 1-based page number. Requires a page size, and the skip must land on a page boundary. */
+export declare const toSearchPage: (opts: {
+    skip: number;
+    limit?: number;
+}) => number;
+/** `fields` (array form, or object form keeping only `true` keys) -> comma-joined include list. */
+export declare const toFieldsCsv: (opts: {
+    fields: TFields;
+}) => string;
+/**
+ * A `{ gte: 1 }`-style operator map: non-null, non-array, non-Date, at least one key, and EVERY
+ * key a known operator. The every-key test mirrors the relational reference
+ * (relational/repositories/dialect/filter.ts:546-559) rather than accepting any non-empty object.
+ *
+ * Without it `{ meta: { foo: 1 } }` read as an operator map and reported "does not support
+ * operator 'foo'", naming a key the caller never meant as an operator; it now falls through to
+ * the value path and is rejected for what it actually is - an object where a scalar belongs.
+ */
+export declare const isOperatorObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * AND of two compiled clauses: `matchNone` absorbs, `matchAll` is the identity. This is the
+ * algebra string-joining could not express, and the reason an empty permission disjunction now
+ * survives into the query instead of evaporating out of it.
+ */
+export declare const andCompiled: (left: TCompiledWhere, right: TCompiledWhere, joiner: string) => TCompiledWhere;
+/** OR of two compiled clauses - the dual of `andCompiled`: `matchAll` absorbs, `matchNone` is the identity. */
+export declare const orCompiled: (left: TCompiledWhere, right: TCompiledWhere, joiner: string) => TCompiledWhere;
+/** Folds a clause list, seeded with that operator's IDENTITY so an empty list lands on it: `and: []` -> matchAll (vacuously true), `or: []` -> matchNone (absorbing false). */
+export declare const reduceCompiled: (opts: {
+    clauses: TCompiledWhere[];
+    isDisjunction: boolean;
+    joiner: string;
+}) => TCompiledWhere;
+/** Parenthesises a compiled group; the absorbing outcomes carry no string to wrap. */
+export declare const parenthesize: (compiled: TCompiledWhere) => TCompiledWhere;
+/** Wraps a filter string as a compiled clause. */
+export declare const toFilterClause: (filterBy: string) => TCompiledWhere;
+/**
+ * Rejects a field name the collection does not declare, mirroring the relational reference which
+ * resolves every name against the table's columns and throws `Column NOT FOUND`
+ * (relational/repositories/dialect/filter.ts:377-382 for `where`, :423-428 for `order`). Without it
+ * the name compiles verbatim and the ENGINE's rejection surfaces as an infrastructure failure
+ * rather than a 400 naming the field.
+ *
+ * ONE judgment, shared by both paths a caller can name a field from - `where` and `order` - so the
+ * two cannot drift into disagreeing about what exists. `method` only labels the message with the
+ * path that asked; it never changes the answer.
+ *
+ * Absent `fields` means unvalidated, not "no fields": an entity carrying no collection definition
+ * must compile exactly as it did before this check existed.
+ *
+ * Membership is the WHOLE judgment - a dotted name is not special. Under Typesense's
+ * `enable_nested_fields` a dotted name is an ordinary field name, so `merchantName.en` passes when
+ * declared and `metadata.foo` fails when not, for the only reason that is true of it.
+ *
+ * Hidden fields stay filterable on purpose - `FilterBuilder` does not consult `hiddenProperties`
+ * either, and diverging from the reference is not this change's business.
+ */
+export declare const assertKnownField: (opts: {
+    field: string;
+    engine: string;
+    capabilities?: ISearchCompileCapabilities;
+    method?: string;
+}) => void;
+/** Rejects an operator this engine cannot express, naming BOTH so the caller knows it is the engine choice - not the operator - that decides it. */
+export declare const throwUnsupportedOperator: (opts: {
+    operator: string;
+    field: string;
+    engine: string;
+    reason?: string;
+}) => never;
+//# sourceMappingURL=dialect-helpers.d.ts.map

package/dist/esm/search/core/repositories/common/dialect-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect-helpers.d.ts","sourceRoot":"","sources":["../../../../../../src/search/core/repositories/common/dialect-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,KAAK,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG1E,qJAAqJ;AAErJ,2GAA2G;AAC3G,eAAO,MAAM,YAAY,GAAI,MAAM;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,MAkBrE,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,WAAW,GAAI,MAAM;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,KAAG,MAevD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAWhF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,cAAc,EACpB,OAAO,cAAc,EACrB,QAAQ,MAAM,KACb,cAoBF,CAAC;AAEF,+GAA+G;AAC/G,eAAO,MAAM,UAAU,GACrB,MAAM,cAAc,EACpB,OAAO,cAAc,EACrB,QAAQ,MAAM,KACb,cAoBF,CAAC;AAEF,+KAA+K;AAC/K,eAAO,MAAM,cAAc,GAAI,MAAM;IACnC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,cAQH,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,YAAY,GAAI,UAAU,cAAc,KAAG,cAG1C,CAAC;AAEf,kDAAkD;AAClD,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,KAAG,cAGhD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,IAWH,CAAC;AAEF,oJAAoJ;AACpJ,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,KAOH,CAAC"}

package/dist/esm/search/core/repositories/common/dialect-helpers.js

@@ -0,0 +1,149 @@
+import { QueryOperators } from '@venizia/ignis-filter';
+import { getError } from '@venizia/ignis-helpers/core';
+import { SearchErrors } from '../../../../search/core/common/errors.js';
+import { SearchFilterOutcomes } from './types.js';
+/** Dialect-shared pure helpers, shared once rather than byte-copied per dialect; not barrel-exported, not part of the connector's public surface. */
+/** skip/offset -> 1-based page number. Requires a page size, and the skip must land on a page boundary. */
+export const toSearchPage = (opts) => {
+    const { skip, limit } = opts;
+    if (limit === undefined) {
+        throw getError({
+            message: '[SearchQueryDialect][toPage] skip/offset requires limit for search() pagination - a page cannot be expressed without a page size',
+        });
+    }
+    if (skip % limit !== 0) {
+        throw getError({
+            message: '[SearchQueryDialect][toPage] skip must be a multiple of limit for search pagination',
+        });
+    }
+    return Math.floor(skip / limit) + 1;
+};
+/** `fields` (array form, or object form keeping only `true` keys) -> comma-joined include list. */
+export const toFieldsCsv = (opts) => {
+    const { fields } = opts;
+    if (Array.isArray(fields)) {
+        return fields.join(',');
+    }
+    const included = [];
+    for (const key in fields) {
+        if (fields[key] === true) {
+            included.push(key);
+        }
+    }
+    return included.join(',');
+};
+/**
+ * A `{ gte: 1 }`-style operator map: non-null, non-array, non-Date, at least one key, and EVERY
+ * key a known operator. The every-key test mirrors the relational reference
+ * (relational/repositories/dialect/filter.ts:546-559) rather than accepting any non-empty object.
+ *
+ * Without it `{ meta: { foo: 1 } }` read as an operator map and reported "does not support
+ * operator 'foo'", naming a key the caller never meant as an operator; it now falls through to
+ * the value path and is rejected for what it actually is - an object where a scalar belongs.
+ */
+export const isOperatorObject = (value) => {
+    if (value === null || Array.isArray(value) || typeof value !== 'object') {
+        return false;
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+        return false;
+    }
+    return keys.every(key => QueryOperators.isValid(key));
+};
+/**
+ * AND of two compiled clauses: `matchNone` absorbs, `matchAll` is the identity. This is the
+ * algebra string-joining could not express, and the reason an empty permission disjunction now
+ * survives into the query instead of evaporating out of it.
+ */
+export const andCompiled = (left, right, joiner) => {
+    if (left.outcome === SearchFilterOutcomes.MATCH_NONE ||
+        right.outcome === SearchFilterOutcomes.MATCH_NONE) {
+        return { outcome: SearchFilterOutcomes.MATCH_NONE };
+    }
+    if (left.outcome === SearchFilterOutcomes.MATCH_ALL) {
+        return right;
+    }
+    if (right.outcome === SearchFilterOutcomes.MATCH_ALL) {
+        return left;
+    }
+    return {
+        outcome: SearchFilterOutcomes.FILTER,
+        filterBy: `${left.filterBy}${joiner}${right.filterBy}`,
+    };
+};
+/** OR of two compiled clauses - the dual of `andCompiled`: `matchAll` absorbs, `matchNone` is the identity. */
+export const orCompiled = (left, right, joiner) => {
+    if (left.outcome === SearchFilterOutcomes.MATCH_ALL ||
+        right.outcome === SearchFilterOutcomes.MATCH_ALL) {
+        return { outcome: SearchFilterOutcomes.MATCH_ALL };
+    }
+    if (left.outcome === SearchFilterOutcomes.MATCH_NONE) {
+        return right;
+    }
+    if (right.outcome === SearchFilterOutcomes.MATCH_NONE) {
+        return left;
+    }
+    return {
+        outcome: SearchFilterOutcomes.FILTER,
+        filterBy: `${left.filterBy}${joiner}${right.filterBy}`,
+    };
+};
+/** Folds a clause list, seeded with that operator's IDENTITY so an empty list lands on it: `and: []` -> matchAll (vacuously true), `or: []` -> matchNone (absorbing false). */
+export const reduceCompiled = (opts) => {
+    const { clauses, isDisjunction, joiner } = opts;
+    const combine = isDisjunction ? orCompiled : andCompiled;
+    const identity = isDisjunction
+        ? { outcome: SearchFilterOutcomes.MATCH_NONE }
+        : { outcome: SearchFilterOutcomes.MATCH_ALL };
+    return clauses.reduce((accumulated, clause) => combine(accumulated, clause, joiner), identity);
+};
+/** Parenthesises a compiled group; the absorbing outcomes carry no string to wrap. */
+export const parenthesize = (compiled) => compiled.outcome === SearchFilterOutcomes.FILTER
+    ? { outcome: SearchFilterOutcomes.FILTER, filterBy: `(${compiled.filterBy})` }
+    : compiled;
+/** Wraps a filter string as a compiled clause. */
+export const toFilterClause = (filterBy) => ({
+    outcome: SearchFilterOutcomes.FILTER,
+    filterBy,
+});
+/**
+ * Rejects a field name the collection does not declare, mirroring the relational reference which
+ * resolves every name against the table's columns and throws `Column NOT FOUND`
+ * (relational/repositories/dialect/filter.ts:377-382 for `where`, :423-428 for `order`). Without it
+ * the name compiles verbatim and the ENGINE's rejection surfaces as an infrastructure failure
+ * rather than a 400 naming the field.
+ *
+ * ONE judgment, shared by both paths a caller can name a field from - `where` and `order` - so the
+ * two cannot drift into disagreeing about what exists. `method` only labels the message with the
+ * path that asked; it never changes the answer.
+ *
+ * Absent `fields` means unvalidated, not "no fields": an entity carrying no collection definition
+ * must compile exactly as it did before this check existed.
+ *
+ * Membership is the WHOLE judgment - a dotted name is not special. Under Typesense's
+ * `enable_nested_fields` a dotted name is an ordinary field name, so `merchantName.en` passes when
+ * declared and `metadata.foo` fails when not, for the only reason that is true of it.
+ *
+ * Hidden fields stay filterable on purpose - `FilterBuilder` does not consult `hiddenProperties`
+ * either, and diverging from the reference is not this change's business.
+ */
+export const assertKnownField = (opts) => {
+    const { field, engine, capabilities, method = 'compileWhere' } = opts;
+    if (!capabilities?.fields || capabilities.fields.has(field)) {
+        return;
+    }
+    throw getError({
+        error: SearchErrors.UNKNOWN_FIELD,
+        message: `[${engine}QueryDialect][${method}] search() Field NOT FOUND | field: '${field}' | engine: '${engine}' | the collection definition declares no such field`,
+    });
+};
+/** Rejects an operator this engine cannot express, naming BOTH so the caller knows it is the engine choice - not the operator - that decides it. */
+export const throwUnsupportedOperator = (opts) => {
+    const { operator, field, engine, reason } = opts;
+    throw getError({
+        error: SearchErrors.UNSUPPORTED_OPERATOR,
+        message: `[${engine}QueryDialect][compileWhere] search() does not support operator '${operator}' | operator: '${operator}' | engine: '${engine}' | field: '${field}'${reason ? ` | ${reason}` : ''}`,
+    });
+};
+//# sourceMappingURL=dialect-helpers.js.map

package/dist/esm/search/core/repositories/common/dialect-helpers.js.map

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

package/dist/esm/search/core/repositories/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/search/core/repositories/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/search/core/repositories/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/search/core/repositories/common/index.js

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/search/core/repositories/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/search/core/repositories/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/search/core/repositories/common/types.d.ts

@@ -0,0 +1,126 @@
+import type { TFilter, TWhere } from '@venizia/ignis-kernel';
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import type { SearchModes, TSearchInput } from './constants.js';
+/**
+ * What a `where` tree compiled down to. A filter STRING cannot express the two absorbing
+ * outcomes: `''` is indistinguishable from "no constraint", which is why an empty `or` used to
+ * compile to a filter byte-identical to the unscoped query - widening the very clause meant to
+ * narrow it. The relational branch has always had this vocabulary (`sql\`false\`` vs `undefined`,
+ * relational/repositories/dialect/filter.ts:637-641); this is that vocabulary for the search branch.
+ */
+export declare class SearchFilterOutcomes {
+    /** A real filter expression the engine should run. */
+    static readonly FILTER = "filter";
+    /** Vacuously true - impose no constraint. */
+    static readonly MATCH_ALL = "matchAll";
+    /** Absorbing false - can never match, so the engine must not be asked. */
+    static readonly MATCH_NONE = "matchNone";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(input: string): input is TSearchFilterOutcome;
+}
+export type TSearchFilterOutcome = TConstValue<typeof SearchFilterOutcomes>;
+export type TCompiledWhere = {
+    outcome: typeof SearchFilterOutcomes.FILTER;
+    filterBy: string;
+} | {
+    outcome: typeof SearchFilterOutcomes.MATCH_ALL;
+} | {
+    outcome: typeof SearchFilterOutcomes.MATCH_NONE;
+};
+/**
+ * Query-time capabilities a dialect compiles against. Passed per call, never stored: every
+ * datasource shares ONE dialect instance (`typesense/datasources/datasource.ts:29` holds it in a
+ * static), so a dialect that remembered a collection would answer the next collection's query
+ * with the previous one's fields.
+ */
+export interface ISearchCompileCapabilities {
+    /**
+     * Field names the collection declares. ABSENT means "unvalidated" - an entity carrying no
+     * collection definition must still compile, exactly as it did before field checking existed.
+     */
+    fields?: ReadonlySet<string>;
+}
+/** Search-engine query parameters translated from a repository-level TFilter. Only the cross-engine intersection lives here - an engine's own tuning knobs go on its own extension. Field names stay camelCase; wire format is produced only at the dialect's `toWireParams` boundary. */
+export interface ISearchQuery {
+    /** Full-text search term. Use '*' for pure filter listings. */
+    query: string;
+    filterBy?: string;
+    sortBy?: string;
+    page?: number;
+    perPage?: number;
+    includeFields?: string;
+    excludeFields?: string;
+    offset?: number;
+    queryBy?: string;
+    queryByWeights?: string;
+    facetBy?: string;
+    facetQuery?: string;
+    maxFacetValues?: number;
+    highlightFields?: string;
+    highlightFullFields?: string;
+    highlightStartTag?: string;
+    highlightEndTag?: string;
+    snippetThreshold?: number;
+    groupBy?: string;
+    groupLimit?: number;
+    groupMissingValues?: boolean;
+    /** Engine-native wire parameters, merged last into `toWireParams` output verbatim and unvalidated; keys use the engine's own vocabulary (`num_typos`, not `numTypos`). */
+    engineParams?: Record<string, unknown>;
+    /** The `where` compiled to an absorbing false: no query can match, so the repository answers empty WITHOUT calling the engine. Internal - `toWireParams` strips it, so it never reaches the wire. */
+    matchNone?: boolean;
+}
+/** Translates repository-level `TFilter`/`TWhere` into a search-engine-specific query. */
+export interface ISearchQueryDialect {
+    build(opts: {
+        filter?: TFilter;
+        hiddenFields?: string[];
+        capabilities?: ISearchCompileCapabilities;
+    }): ISearchQuery;
+    /**
+     * @deprecated Use `compileWhere`, which can express the absorbing outcomes a filter STRING
+     * cannot. This signature has no representation for "matches nothing" - it returned `''`, which
+     * the caller could not tell from "no constraint", so an empty `or` widened the query it was
+     * meant to narrow. It now THROWS on that input rather than answering wrongly.
+     */
+    toWhere(opts: {
+        where: TWhere;
+    }): string;
+    /**
+     * Compiles a `where` tree, resolving what a filter string cannot express. `capabilities` is
+     * per-call, never retained - one dialect instance serves every datasource.
+     */
+    compileWhere(opts: {
+        where: TWhere;
+        capabilities?: ISearchCompileCapabilities;
+    }): TCompiledWhere;
+    /**
+     * Whether this engine can express `operator` at all. Published by the dialect rather than
+     * hand-copied by callers, so it cannot drift from the engine's own `switch`; every member of
+     * `QueryOperators.SCHEME_SET` has an answer, which is what stops a new engine from silently
+     * leaving one unclassified.
+     */
+    canExpress(opts: {
+        operator: string;
+    }): boolean;
+    /**
+     * ANDs already-compiled clauses using this engine's own conjunction, honouring the absorbing
+     * outcomes. The repository needs this to combine a caller clause with a repository-owned one it
+     * compiled SEPARATELY - the joiner belongs to the engine, so the dialect supplies it rather
+     * than the caller guessing `&&` versus `AND`.
+     */
+    conjoin(opts: {
+        clauses: TCompiledWhere[];
+    }): TCompiledWhere;
+    /** Writes every engine-specific consequence of a non-raw search input onto `query` (mode dispatch, vector clause, tuning knobs) - keeping `ReadableSearchRepository` engine-free. */
+    applySearchInput(opts: {
+        query: ISearchQuery;
+        input: Exclude<TSearchInput, {
+            mode: typeof SearchModes.RAW;
+        }>;
+    }): void;
+    /** Maps a camelCase query record onto the engine's wire-format field names via a key lookup, never a wire-cased identifier; `engineParams` merges last. */
+    toWireParams(opts: {
+        query: Partial<ISearchQuery>;
+    }): Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/search/core/repositories/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/search/core/repositories/common/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/search/core/repositories/common/types.js

@@ -0,0 +1,20 @@
+/**
+ * What a `where` tree compiled down to. A filter STRING cannot express the two absorbing
+ * outcomes: `''` is indistinguishable from "no constraint", which is why an empty `or` used to
+ * compile to a filter byte-identical to the unscoped query - widening the very clause meant to
+ * narrow it. The relational branch has always had this vocabulary (`sql\`false\`` vs `undefined`,
+ * relational/repositories/dialect/filter.ts:637-641); this is that vocabulary for the search branch.
+ */
+export class SearchFilterOutcomes {
+    /** A real filter expression the engine should run. */
+    static { this.FILTER = 'filter'; }
+    /** Vacuously true - impose no constraint. */
+    static { this.MATCH_ALL = 'matchAll'; }
+    /** Absorbing false - can never match, so the engine must not be asked. */
+    static { this.MATCH_NONE = 'matchNone'; }
+    static { this.SCHEME_SET = new Set([this.FILTER, this.MATCH_ALL, this.MATCH_NONE]); }
+    static isValid(input) {
+        return this.SCHEME_SET.has(input);
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/search/core/repositories/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/search/core/repositories/common/types.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IAC/B,sDAAsD;aACtC,WAAM,GAAG,QAAQ,CAAC;IAClC,6CAA6C;aAC7B,cAAS,GAAG,UAAU,CAAC;IACvC,0EAA0E;aAC1D,eAAU,GAAG,WAAW,CAAC;aAEzB,eAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAErF,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC"}