@tellaro/tql 1.5.0 → 3.0.0

package/dist/src/validator.js

@@ -1,22 +1,125 @@
-import { parseTql as g } from "./parser.js";
-const c = {
-  // Equality (all types)
-  eq: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  ne: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  "=": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  "==": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  "!=": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
+import { parseTql as w } from "./parser.js";
+const u = 1e3, r = [
+  "text",
+  "keyword",
+  "long",
+  "integer",
+  "short",
+  "byte",
+  "double",
+  "float",
+  "half_float",
+  "scaled_float",
+  "unsigned_long",
+  "date",
+  "boolean",
+  "ip",
+  "nested",
+  "object",
+  "geo_point"
+], h = [
+  "long",
+  "integer",
+  "short",
+  "byte",
+  "double",
+  "float",
+  "half_float",
+  "scaled_float",
+  "unsigned_long"
+], l = [...h, "date", "keyword"], c = [...h, "date"], y = {
+  // Equality (all types) — and now that is what it says.
+  //
+  // The transcribed twelve-element list this replaces claimed "all types" while omitting
+  // five: `short`, `byte`, `half_float`, `scaled_float` and `unsigned_long` are all in the
+  // `TqlFieldType` union and were all absent, so `port eq 443` on a `short` field warned
+  // that equality "may not work well" with it.
+  eq: r,
+  ne: r,
+  "=": r,
+  "!=": r,
   eq_ci: ["text", "keyword"],
-  // Comparison (numeric and dates)
-  gt: ["long", "integer", "double", "float", "date"],
-  gte: ["long", "integer", "double", "float", "date"],
-  lt: ["long", "integer", "double", "float", "date"],
-  lte: ["long", "integer", "double", "float", "date"],
-  ">": ["long", "integer", "double", "float", "date"],
-  ">=": ["long", "integer", "double", "float", "date"],
-  "<": ["long", "integer", "double", "float", "date"],
-  "<=": ["long", "integer", "double", "float", "date"],
+  // Ordered comparison — numeric, date, AND keyword.
+  //
+  // `keyword` is not a courtesy. `compare_ordered` in `tql/src/comparator.rs` tries numbers
+  // first and falls back to a LEXICOGRAPHIC string comparison when both sides are strings,
+  // Python does the same, and Python's own validator lists all four in `keyword_ops`
+  // (`_validate_simple_type_compatibility`). Warning here was a false positive against every
+  // layer at once — `host.name gte "m"` is a query the editor flagged, the validator
+  // accepts, the evaluator answers and the cluster serves.
+  //
+  // `text` stays out, and that is the same source's judgement rather than an omission:
+  // `text_ops` excludes the four, because a range over an ANALYZED field compares tokens
+  // rather than the value the user typed. `between` also stays out — see the note on it.
+  //
+  // Every numeric width is listed via ALL_NUMERIC_FIELD_TYPES so the five narrow ones cannot
+  // fall out again the way they did from `eq`.
+  gt: l,
+  gte: l,
+  lt: l,
+  lte: l,
+  ">": l,
+  ">=": l,
+  "<": l,
+  "<=": l,
   // String operations
+  //
+  // ## The `_cs` operators list `text`, and that is deliberate — the rule lives in the caller
+  //
+  // The engines REFUSE every `_cs` operator when the field cannot answer it — an ANALYZED
+  // field with no case-preserving subfield, and for the whole-value six ALSO any field with
+  // no un-analyzed string form at all. The analyzer lowercased every token it indexed, so
+  // the case the query asks about is not in the index; before the refusal both engines fell
+  // back to the analyzed field and returned zero hits with no error.
+  //
+  // "An analyzed field" alone is the MEMBERSHIP half, and stating it as the whole rule is
+  // how this shipped wrong for six operators once already. See `caseSensitiveSupport`.
+  //
+  // ALL EIGHT are covered, and the set arrived in two commits rather than one, which is why
+  // it is stated as a rule and not as a list of six:
+  //
+  //   * `a3971bd` — `contains_cs`, `not_contains_cs`, `startswith_cs`, `not_startswith_cs`,
+  //     `endswith_cs`, `not_endswith_cs`, as `CASE_SENSITIVE_WHOLE_VALUE_OPERATORS`. Named
+  //     one by one rather than as "and their negations": the shorthand is how the eighth
+  //     operator went missing from this paragraph in the first place.
+  //   * `c8e3e8a` — `in_cs`, `not_in_cs`, as `CASE_SENSITIVE_MEMBERSHIP_OPERATORS`. These
+  //     escaped the first round for a classification reason, not a semantic one: `in_cs` is
+  //     a keyword operator (an exact-match `terms` query), so it routed through a different
+  //     branch of `get_query_field` whose fallback still landed on the analyzed field.
+  //
+  // Both constants live in `tql/src/opensearch/field_mappings.rs` and
+  // `src/tql/opensearch_components/field_mapping.py`. A note here naming only the first six
+  // would leave a reader correct about `contains_cs` and wrong about `in_cs`, silently —
+  // which is the exact failure the engines' own interim pin existed to prevent.
+  //
+  // ### Why the rule is not in THIS table (tql#206)
+  //
+  // It keys on the MAPPING, not on the field type. The engines refuse only when there is no
+  // case-preserving form — a `text` field WITH a `keyword` subfield translates fine, and
+  // that is the commonest shape in ECS. So `type === "text"` does not decide the question,
+  // and dropping `text` from the eight `_cs` rows below would be that wrong check by another
+  // name. The rows stay exactly as they are.
+  //
+  // NOTE the table they are in. These rows are in THIS table, `OPERATOR_TYPE_COMPATIBILITY`,
+  // which emits a WARNING. `OPERATOR_REQUIRED_FIELD_TYPES` further down emits an ERROR and
+  // holds exactly three rows — `cidr`, `not_cidr`, `!cidr`. tql#206 named the wrong one, and
+  // the mistake was copied into this file, its spec, `docs/developer/field-routing.md` and
+  // the CHANGELOG before review caught it; `tests/completionOperatorTableParity.spec.ts`
+  // had the distinction right the whole time. Moving these rows into the ERROR table is the
+  // OTHER wrong fix, and is guarded in the spec alongside the first one.
+  //
+  // What CHANGED at tql#206 is that the question turned out to be answerable from the schema
+  // this package already receives. `TqlValidationOptions.fieldTypes` is a FLAT
+  // `Record<name, type>`, and a host that flattens an index mapping puts each multifield in
+  // as its own entry — `message` → `text` alongside `message.keyword` → `keyword`. That is a
+  // sibling LOOKUP, not a schema change, and it is what `caseSensitiveSupport` below does.
+  // The verdict is three-valued (`supported` / `unsupported` / `unknown`) and only the middle
+  // one produces a diagnostic, which is why this table can stay permissive and the caller can
+  // still be specific. See that function for the predicate and its blind spots.
+  //
+  // `tests/caseSensitiveOperatorMapping.spec.ts` derives the engines' refusal set from their
+  // own sources and asserts this note names all of it — so a third `_cs` round cannot leave
+  // this paragraph quietly under-claiming the way the six-name version did.
   contains: ["text", "keyword"],
   not_contains: ["text", "keyword"],
   "!contains": ["text", "keyword"],
@@ -44,47 +147,131 @@ const c = {
   matches: ["text", "keyword"],
   not_matches: ["text", "keyword"],
   "!matches": ["text", "keyword"],
-  // Range
-  between: ["long", "integer", "double", "float", "date"],
-  not_between: ["long", "integer", "double", "float", "date"],
-  "!between": ["long", "integer", "double", "float", "date"],
-  in: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip"],
-  not_in: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip"],
-  "!in": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip"],
+  // Range. Numeric and date, via the named constant — the transcribed list this replaces
+  // dropped the same five narrow widths `eq` did (`short`, `byte`, `half_float`,
+  // `scaled_float`, `unsigned_long`), so `port between [1, 1024]` on a `short` field warned.
+  // Python's `numeric_ops` carries `between` and covers `short` and `byte`; the other three
+  // widths have no arm at all in `_validate_simple_type_compatibility` and fall through its
+  // `else: return`, which allows every operator.
+  //
+  // `keyword` and `text` stay out, and that is a decision rather than an omission: Python's
+  // `keyword_ops` excludes `between` while including `gte`, which is the divergence pinned
+  // in `tests/collectionAndNullSemantics.spec.ts`.
+  between: c,
+  not_between: c,
+  "!between": c,
+  // Membership — the same set as `eq`, because `in` IS a disjunction of equalities and both
+  // evaluators implement it that way. The transcribed list this replaces omitted the five
+  // narrow numeric widths plus `nested`, `object` and `geo_point`.
+  //
+  // This is deliberately WIDER than Python's validator, which is already the standing stance
+  // here rather than a new one: `date_ops` and `boolean_ops` both omit `in`, so
+  // `_validate_simple_type_compatibility` refuses `f in ['2024-01-01','2024-01-02']` on a
+  // date field — while its own evaluator answers it and the cluster serves the DSL. That is
+  // the same validator-versus-evaluator disagreement already pinned for `keyword between`
+  // and `keyword is null`, and this table has always sided with the evaluator on it (`date`
+  // and `boolean` were in the transcribed list too). Widening to the remaining types applies
+  // the existing stance consistently; it does not take a new position.
+  in: r,
+  not_in: r,
+  "!in": r,
   in_cs: ["text", "keyword"],
   not_in_cs: ["text", "keyword"],
   "!in_cs": ["text", "keyword"],
-  // Existence (all types)
-  exists: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  not_exists: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  "!exists": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  // Null checks (all types)
-  is: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  is_not: ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
-  "!is": ["text", "keyword", "long", "integer", "double", "float", "date", "boolean", "ip", "nested", "object", "geo_point"],
+  // Existence and null checks — ONE predicate, so ONE list.
+  //
+  // `field is null` now means the field HAS NO VALUE (absent OR explicitly null), which is
+  // exactly `field not exists`; `is not null` is its complement and exactly `exists`. A
+  // product-owner decision landed in both engines as a breaking change. An empty array `[]`
+  // is a PRESENT value and satisfies neither `is null` nor `not exists` — complementarity is
+  // the reason, since `exists` answers true for `[]` and no record may satisfy both sides.
+  //
+  // Sharing the constant is what keeps the four honest. As four separate transcriptions they
+  // had already drifted from the union by five types apiece, and nothing would have caught
+  // two of them drifting from each other.
+  exists: r,
+  not_exists: r,
+  "!exists": r,
+  is: r,
+  is_not: r,
+  "!is": r,
   // IP-specific operators
   cidr: ["ip"],
   not_cidr: ["ip"],
   "!cidr": ["ip"],
-  // Collection operators
-  any: ["nested", "object", "keyword", "text"],
-  all: ["nested", "object", "keyword", "text"],
-  none: ["nested", "object", "keyword", "text"],
-  not_any: ["nested", "object", "keyword", "text"],
-  not_all: ["nested", "object", "keyword", "text"],
-  not_none: ["nested", "object", "keyword", "text"],
-  "!any": ["nested", "object", "keyword", "text"],
-  "!all": ["nested", "object", "keyword", "text"],
-  "!none": ["nested", "object", "keyword", "text"]
-}, l = {
+  // Collection operators — every type, and that is the engines' rule rather than a shrug.
+  //
+  // NOTE these rows are not reachable from this file: the parser builds a `collection` node
+  // whose `condition` carries the default inner operator `eq`, so `any`/`all`/`none` never
+  // arrive at `validateComparison`. They are corrected rather than left wrong because a
+  // stale rule gets copied -- the identical restriction WAS live in
+  // `completionProvider.ts`, where it withheld `any` from every `ip` and `long` field, and
+  // that is where `tests/collectionAndNullSemantics.spec.ts` measures it.
+  //
+  // Two things changed under this table. Both evaluators now treat a SCALAR field as a
+  // one-element collection (Rust returned false for every scalar before `1fe0a9f`), and both
+  // iterate array-valued fields across the comparison surface. Neither is conditional on the
+  // mapping type: OpenSearch has no array type, so `related.ip`, `host.ip`, `tags` and
+  // `dns.answers` are `ip` / `keyword` / `object` fields that ECS guarantees hold arrays.
+  //
+  // Restricting these six to `nested | object | keyword | text` therefore described neither
+  // engine. `related.ip any ["10.0.0.1"]` is the ordinary case for an IP field, not an
+  // abuse of one.
+  any: r,
+  all: r,
+  none: r,
+  not_any: r,
+  not_all: r,
+  not_none: r,
+  "!any": r,
+  "!all": r,
+  "!none": r
+}, g = {
   cidr: ["ip"],
   not_cidr: ["ip"],
   "!cidr": ["ip"]
-}, u = {
+}, p = [
+  "contains_cs",
+  "not_contains_cs",
+  "!contains_cs",
+  "startswith_cs",
+  "not_startswith_cs",
+  "!startswith_cs",
+  "endswith_cs",
+  "not_endswith_cs",
+  "!endswith_cs"
+], _ = [
+  "in_cs",
+  "not_in_cs",
+  "!in_cs"
+], b = [
+  ...p,
+  ..._
+];
+function m(o, t) {
+  if (!t)
+    return "unknown";
+  const e = t[o];
+  if (!e)
+    return "unknown";
+  if (e === "keyword" || t[`${o}.keyword`] === "keyword")
+    return "present";
+  const i = `${o}.`;
+  for (const [n, s] of Object.entries(t))
+    if (!(s !== "keyword" || !n.startsWith(i)) && !n.slice(i.length).includes("."))
+      return "present";
+  return "absent";
+}
+function v(o, t, e) {
+  if (!b.includes(t))
+    return "supported";
+  const i = m(o, e);
+  return i !== "absent" ? i === "present" ? "supported" : "unknown" : _.includes(t) ? e?.[o] === "text" ? "unsupported" : "supported" : "unsupported";
+}
+const E = {
   eq: ["string", "number", "boolean"],
   ne: ["string", "number", "boolean"],
   "=": ["string", "number", "boolean"],
-  "==": ["string", "number", "boolean"],
   "!=": ["string", "number", "boolean"],
   eq_ci: ["string"],
   gt: ["number", "string"],
@@ -150,21 +337,21 @@ const c = {
   "!all": ["string", "number", "boolean"],
   "!none": ["string", "number", "boolean"]
 };
-class b {
+class k {
   options;
   errors;
   warnings;
-  constructor(e = {}) {
-    this.options = e, this.errors = [], this.warnings = [];
+  constructor(t = {}) {
+    this.options = t, this.errors = [], this.warnings = [];
   }
   /**
    * Validate a TQL query
    */
-  validate(e) {
-    if (this.errors = [], this.warnings = [], !e)
+  validate(t) {
+    if (this.errors = [], this.warnings = [], !t)
       return { valid: !0, errors: [], warnings: [] };
-    const t = g(e);
-    return this.errors.push(...t.errors), this.warnings.push(...t.warnings), t.ast && this.validateExpression(t.ast), {
+    const e = w(t);
+    return this.errors.push(...e.errors), this.warnings.push(...e.warnings), e.ast && this.validateExpression(e.ast), {
       valid: this.errors.length === 0,
       errors: this.errors,
       warnings: this.warnings
@@ -173,171 +360,302 @@ class b {
   /**
    * Validate an expression recursively
    */
-  validateExpression(e) {
-    switch (e.type) {
+  validateExpression(t) {
+    switch (t.type) {
       case "binary":
-        this.validateExpression(e.left), this.validateExpression(e.right);
+        this.validateExpression(t.left), this.validateExpression(t.right);
         break;
       case "unary":
-        this.validateExpression(e.operand);
+        this.validateExpression(t.operand);
         break;
       case "group":
-        this.validateExpression(e.expression);
+        this.validateExpression(t.expression);
         break;
       case "comparison":
-        this.validateComparison(e);
+        this.validateComparison(t);
+        break;
+      // `field ANY value`. The collection wrapper carries no validatable content of its
+      // own -- field, inner operator and value all live in `condition` -- but it must be
+      // walked explicitly. Falling through the switch would have made every collection
+      // query validate vacuously clean, which is the failure mode this node type was added
+      // out of, not into.
+      //
+      // The COLLECTION OPERATOR itself is deliberately not checked here. Every field type
+      // is compatible with it (see the note on `any` in OPERATOR_TYPE_COMPATIBILITY), so a
+      // check would be a code path that can never produce an answer -- and a mechanism with
+      // no reachable outcome reads as enforcement while enforcing nothing. The completion
+      // provider's copy of the table IS live, and is where the widened rule is observable.
+      //
+      // The OPERAND SHAPE is checked, though — see validateCollectionOperand.
+      case "collection":
+        this.validateCollectionOperand(t), this.validateExpression(t.condition);
         break;
     }
   }
+  /**
+   * `f any ['a','b']` is ill-typed. Say so, and name `in`.
+   *
+   * ## The rule, as both engines implement it
+   *
+   * `any` / `none` apply a comparison to each ELEMENT of an array-valued field. The operand
+   * is therefore a SCALAR: `f any 'admin'` asks whether some element equals `'admin'`. A
+   * LIST operand asks whether some single element equals the whole two-element list, which
+   * no scalar element can. `in` is already the membership operator, and is what the author
+   * meant.
+   *
+   * Both engines now refuse it -- `ab55587` in `tql/src/opensearch/query_builder.rs`
+   * (`build_collection_op`) and `_refuse_list_operand` in
+   * `src/tql/opensearch_components/query_converter.py` -- raising a type error whose
+   * `valid_operators` are `in` / `not in`. Before that it emitted `{"term": {"f": [..]}}`,
+   * which OpenSearch answers with HTTP 400 `[term] query does not support array of values`,
+   * failing the WHOLE search including every unrelated clause; the intermediate fix emitted
+   * `match_none`, which executed cleanly and excluded nothing, silently.
+   *
+   * ## Three arities, and only the middle one is new
+   *
+   * The engines do NOT test `is_array`. They unwrap a single-element list FIRST
+   * (`unwrap_single` in Rust, `len(value) == 1` in Python) and refuse only what is still a
+   * list. Measured against the live Python translator at `ab55587`:
+   *
+   * | Query              | Python translator                                    |
+   * |--------------------|------------------------------------------------------|
+   * | `f any 'admin'`    | `{"term": {"f": "admin"}}`                            |
+   * | `f any ['a']`      | `{"term": {"f": "a"}}` -- unwrapped, NOT refused      |
+   * | `f any ['a','b']`  | `TQLTypeError`, valid operators `in`, `not in`        |
+   *
+   * A naive `Array.isArray(value)` check would flag `f any ['a']`, which both engines
+   * translate perfectly well -- a red squiggle over a working query, which is the defect
+   * this parser keeps being fixed for. Hence `length >= 2`, and hence the two arities are
+   * tested separately in `tests/collectionListOperand.spec.ts`.
+   *
+   * The empty list is not handled here: `f any []` is already an `INVALID_VALUE` error from
+   * the parser (`tests/emptyValueList.spec.ts`), and Python does not even parse it
+   * (`TQLSyntaxError`). Reporting it twice would be noise.
+   *
+   * ## Why `ALL` is excluded, and why that is not an oversight
+   *
+   * `all` / `not_all` are answered by a Painless script that compares each element to
+   * `params.value`. A list operand there emits valid DSL that matches nothing -- which is
+   * what both in-memory evaluators also answer -- so both engines dispatch `all` BEFORE the
+   * refusal and leave it untouched. `f all ['a','b']` translating cleanly is a pinned
+   * negative case here, not a gap.
+   *
+   * Negation is irrelevant: in both engines the array check precedes the quantifier wrapper,
+   * so `not any` / `not none` refuse on the same footing as the positive spellings.
+   */
+  validateCollectionOperand(t) {
+    if (t.operator === "ALL")
+      return;
+    const e = t.condition;
+    if (e.type !== "comparison")
+      return;
+    const i = e.value;
+    if (!Array.isArray(i) || i.length < 2)
+      return;
+    const n = t.operator.toLowerCase(), s = t.negated ? `not ${n}` : n, a = t.field.name;
+    this.addError(
+      `'${s}' takes a single value and tests it against each element of '${a}'; it does not take a list.`,
+      i[0].start,
+      i[i.length - 1].end,
+      1,
+      1,
+      "TYPE_MISMATCH",
+      `Use \`in\` for membership: \`${a} in [...]\` (or \`${a} not in [...]\` to exclude).`
+    );
+  }
   /**
    * Validate a comparison expression
    */
-  validateComparison(e) {
-    const t = e.field.type === "field" ? e.field.name : "computed";
-    if (this.options.availableFields && this.options.strictMode && !this.options.availableFields.includes(t) && e.field.type === "field" && this.addWarning(
-      `Unknown field '${t}'`,
-      e.field.start,
-      e.field.end,
-      (e.field.type === "field", 1),
+  validateComparison(t) {
+    const e = t.field.type === "field" ? t.field.name : "computed";
+    if (this.options.availableFields && this.options.strictMode && !this.options.availableFields.includes(e) && t.field.type === "field" && this.addWarning(
+      `Unknown field '${e}'`,
+      t.field.start,
+      t.field.end,
+      (t.field.type === "field", 1),
       1,
       "UNKNOWN_FIELD",
-      `Did you mean: ${this.suggestField(t)}`
-    ), this.options.fieldTypes && e.field.type === "field") {
-      const o = this.options.fieldTypes[t];
-      if (o) {
-        const n = l[e.operator];
-        n && !n.includes(o) && this.addError(
-          `Operator '${e.operator}' requires field type ${n.join(" or ")}, but '${t}' is type '${o}'`,
-          e.start,
-          e.end,
+      `Did you mean: ${this.suggestField(e)}`
+    ), this.options.fieldTypes && t.field.type === "field") {
+      const n = this.options.fieldTypes[e];
+      if (n) {
+        const s = g[t.operator];
+        s && !s.includes(n) && this.addError(
+          `Operator '${t.operator}' requires field type ${s.join(" or ")}, but '${e}' is type '${n}'`,
+          t.start,
+          t.end,
           1,
           1,
           "TYPE_MISMATCH",
-          `Use '${e.operator}' only with ${n.join(" or ")} fields`
+          `Use '${t.operator}' only with ${s.join(" or ")} fields`
         );
       }
     }
-    if (this.options.fieldTypes && e.field.type === "field") {
-      const o = this.options.fieldTypes[t];
-      if (o) {
-        const n = c[e.operator];
-        !l[e.operator] && n && !n.includes(o) && this.addWarning(
-          `Operator '${e.operator}' may not work well with field type '${o}'`,
-          e.start,
-          e.end,
+    let i = !1;
+    if (t.field.type === "field" && v(e, t.operator, this.options.fieldTypes) === "unsupported") {
+      i = !0;
+      const n = t.operator.replace(/_cs$/, ""), s = this.options.fieldTypes?.[e], a = s === "text" ? `'${e}' is an analyzed text field with no case-preserving subfield in the supplied schema, so the analyzer lowercased every token it indexed and the case '${t.operator}' asks about is not in the index` : `'${e}' is type '${s}' and has no un-analyzed string form, which is what '${t.operator}' matches against`;
+      this.addWarning(
+        // "The query engine", singular and unqualified, and kept that way deliberately.
+        // It was written this way because "both engines" was FALSE in twelve cells —
+        // Rust permitted `_cs` on `geo_point` and `unsigned_long`. tql#210 fixed that in
+        // this same PR, so "both" would now be accurate. It stays singular anyway: the
+        // user does not choose the engine, the sentence is about what will go wrong
+        // rather than about who refuses, and a message that counts engines is a message
+        // that goes stale the next time one of them changes.
+        `${a}. The query engine refuses this at execution.`,
+        t.start,
+        t.end,
+        1,
+        1,
+        "UNANSWERABLE_MAPPING",
+        s === "text" ? `Use the case-insensitive '${n}', or query a keyword subfield (\`${e}.keyword\`) if the index has one this schema does not list.` : `Use the case-insensitive '${n}', or compare '${e}' with an operator suited to '${s}'.`
+      );
+    }
+    if (this.options.fieldTypes && t.field.type === "field") {
+      const n = this.options.fieldTypes[e];
+      if (n) {
+        const s = y[t.operator], a = g[t.operator];
+        !i && !a && s && !s.includes(n) && this.addWarning(
+          `Operator '${t.operator}' may not work well with field type '${n}'`,
+          t.start,
+          t.end,
           1,
           1,
           "TYPE_MISMATCH",
-          `Consider using a different operator for ${o} fields`
+          `Consider using a different operator for ${n} fields`
         );
       }
     }
-    if (!Array.isArray(e.value) && e.value.type === "literal") {
-      const o = u[e.operator];
-      o && !o.includes(e.value.valueType) && this.addWarning(
-        `Operator '${e.operator}' expects ${o.join(" or ")} value`,
-        e.value.start,
-        e.value.end,
+    if (!Array.isArray(t.value) && t.value.type === "literal") {
+      const n = E[t.operator];
+      n && !n.includes(t.value.valueType) && this.addWarning(
+        `Operator '${t.operator}' expects ${n.join(" or ")} value`,
+        t.value.start,
+        t.value.end,
         1,
         1,
         "TYPE_MISMATCH"
       );
     }
-    if ((e.operator === "regexp" || e.operator === "regex" || e.operator === "not_regexp" || e.operator === "not_regex" || e.operator === "matches" || e.operator === "not_matches") && !Array.isArray(e.value) && e.value.valueType === "string" && typeof e.value.value == "string")
-      try {
-        new RegExp(e.value.value);
-      } catch {
+    if ((t.operator === "regexp" || t.operator === "regex" || t.operator === "not_regexp" || t.operator === "not_regex" || t.operator === "matches" || t.operator === "not_matches") && !Array.isArray(t.value) && t.value.valueType === "string" && typeof t.value.value == "string") {
+      const n = Array.from(t.value.value).length;
+      if (n > u)
         this.addError(
-          `Invalid regular expression: ${e.value.value}`,
-          e.value.start,
-          e.value.end,
+          `Regex pattern is ${n} characters, which exceeds the maximum supported length of ${u}. The query cannot run as written.`,
+          t.value.start,
+          t.value.end,
           1,
           1,
           "INVALID_VALUE",
-          "Check the regex syntax"
+          "Split the pattern into several shorter alternations combined with OR, or use an `in [...]` list"
         );
-      }
+      else
+        try {
+          new RegExp(t.value.value);
+        } catch {
+          this.addError(
+            `Invalid regular expression: ${t.value.value}`,
+            t.value.start,
+            t.value.end,
+            1,
+            1,
+            "INVALID_VALUE",
+            "Check the regex syntax"
+          );
+        }
+    }
   }
   /**
    * Suggest a similar field name using Levenshtein distance
    */
-  suggestField(e) {
+  suggestField(t) {
     if (!this.options.availableFields || this.options.availableFields.length === 0)
       return "check available fields";
-    let t = this.options.availableFields[0], o = this.levenshteinDistance(e, t);
+    let e = this.options.availableFields[0], i = this.levenshteinDistance(t, e);
     for (const n of this.options.availableFields) {
-      const i = this.levenshteinDistance(e, n);
-      i < o && (o = i, t = n);
+      const s = this.levenshteinDistance(t, n);
+      s < i && (i = s, e = n);
     }
-    return t;
+    return e;
   }
   /**
    * Calculate Levenshtein distance between two strings
    */
-  levenshteinDistance(e, t) {
-    const o = [];
-    for (let n = 0; n <= t.length; n++)
-      o[n] = [n];
+  levenshteinDistance(t, e) {
+    const i = [];
     for (let n = 0; n <= e.length; n++)
-      o[0][n] = n;
-    for (let n = 1; n <= t.length; n++)
-      for (let i = 1; i <= e.length; i++)
-        t.charAt(n - 1) === e.charAt(i - 1) ? o[n][i] = o[n - 1][i - 1] : o[n][i] = Math.min(
-          o[n - 1][i - 1] + 1,
-          o[n][i - 1] + 1,
-          o[n - 1][i] + 1
+      i[n] = [n];
+    for (let n = 0; n <= t.length; n++)
+      i[0][n] = n;
+    for (let n = 1; n <= e.length; n++)
+      for (let s = 1; s <= t.length; s++)
+        e.charAt(n - 1) === t.charAt(s - 1) ? i[n][s] = i[n - 1][s - 1] : i[n][s] = Math.min(
+          i[n - 1][s - 1] + 1,
+          i[n][s - 1] + 1,
+          i[n - 1][s] + 1
         );
-    return o[t.length][e.length];
+    return i[e.length][t.length];
   }
-  addError(e, t, o, n, i, r, a) {
+  addError(t, e, i, n, s, a, d) {
     this.errors.push({
-      message: e,
-      start: t,
-      end: o,
+      message: t,
+      start: e,
+      end: i,
       line: n,
-      column: i,
+      column: s,
       severity: "error",
-      code: r,
-      suggestion: a
+      code: a,
+      suggestion: d
     });
   }
-  addWarning(e, t, o, n, i, r, a) {
+  addWarning(t, e, i, n, s, a, d) {
     this.warnings.push({
-      message: e,
-      start: t,
-      end: o,
+      message: t,
+      start: e,
+      end: i,
       line: n,
-      column: i,
+      column: s,
       severity: "warning",
-      code: r,
-      suggestion: a
+      code: a,
+      suggestion: d
     });
   }
 }
-function d(s, e) {
-  return new b(e).validate(s);
+function f(o, t) {
+  return new k(t).validate(o);
 }
-function h(s) {
-  return d(s).valid;
+function $(o) {
+  return f(o).valid;
 }
-function y(s, e) {
-  const t = d(s, e);
-  return [...t.errors, ...t.warnings];
+function A(o, t) {
+  const e = f(o, t);
+  return [...e.errors, ...e.warnings];
 }
-function f(s) {
-  const e = [];
-  s.valid ? e.push("Query is valid") : e.push("Query has errors:");
-  for (const t of s.errors)
-    e.push(`  Error: ${t.message}`), t.suggestion && e.push(`    Suggestion: ${t.suggestion}`);
-  for (const t of s.warnings)
-    e.push(`  Warning: ${t.message}`), t.suggestion && e.push(`    Suggestion: ${t.suggestion}`);
-  return e.join(`
+function I(o) {
+  const t = [];
+  o.valid ? t.push("Query is valid") : t.push("Query has errors:");
+  for (const e of o.errors)
+    t.push(`  Error: ${e.message}`), e.suggestion && t.push(`    Suggestion: ${e.suggestion}`);
+  for (const e of o.warnings)
+    t.push(`  Warning: ${e.message}`), e.suggestion && t.push(`    Suggestion: ${e.suggestion}`);
+  return t.join(`
 `);
 }
 export {
-  b as TqlValidator,
-  f as formatValidationResult,
-  y as getTqlIssues,
-  h as isValidTqlSyntax,
-  d as validateTql
+  r as ALL_FIELD_TYPES,
+  c as BETWEEN_FIELD_TYPES,
+  _ as CASE_SENSITIVE_MEMBERSHIP_OPERATORS,
+  b as CASE_SENSITIVE_OPERATORS,
+  p as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
+  u as MAX_REGEX_PATTERN_LENGTH,
+  h as NUMERIC_FIELD_TYPES,
+  l as ORDERED_FIELD_TYPES,
+  k as TqlValidator,
+  m as casePreservingForm,
+  v as caseSensitiveSupport,
+  I as formatValidationResult,
+  A as getTqlIssues,
+  $ as isValidTqlSyntax,
+  f as validateTql
 };