@tellaro/tql 4.0.2 → 5.0.0

package/dist/index.js

@@ -1,90 +1,98 @@
-import { AGGREGATION_FUNCTIONS as t, BOOLEAN_PREDICATE_MUTATORS as o, BOOLEAN_PREDICATE_MUTATOR_SET as i, COLLECTION_OPERATORS as T, COMPARISON_OPERATORS as a, DATE_HISTOGRAM_CALENDAR_INTERVALS as E, DATE_HISTOGRAM_FIXED_UNITS as S, GEO_GRID_PRECISION as _, GROUP_BY_BUCKET_FUNCTIONS as l, KEYWORDS as A, LOGICAL_OPERATORS as O, MUTATORS as n, NEGATION_SYMBOL_OPERATORS as R, SYMBOL_OPERATORS as s, TYPE_HINTS as g, TqlTokenizer as m, VISUALIZATION_TYPES as P, findPreviousToken as I, findTokenAtPosition as N, findTokenBefore as C, findTokensInRange as c, tokenizeTql as p, tokenizeTqlNoWhitespace as L } from "./src/tokenizer.js";
-import { TqlParser as f, dateHistogramIntervalProblem as h, formatParseError as x, geoPrecisionProblem as U, getTqlErrors as M, isValidTql as u, parseTql as y, rangeBoundariesProblem as q } from "./src/parser.js";
-import { CASE_SENSITIVE_MEMBERSHIP_OPERATORS as V, CASE_SENSITIVE_OPERATORS as z, CASE_SENSITIVE_WHOLE_VALUE_OPERATORS as D, MAX_REGEX_PATTERN_LENGTH as F, TqlValidator as Y, casePreservingForm as B, caseSensitiveSupport as H, formatValidationResult as v, getTqlIssues as k, isValidTqlSyntax as Q, validateTql as W } from "./src/validator.js";
-import { getCompletionTriggerCharacters as b, getCompletions as K, getWordAtPosition as w, shouldTriggerCompletion as Z } from "./src/completionProvider.js";
-import { findClosestMatch as J, fuzzyFilter as $, fuzzyMatch as ee, highlightMatch as re, levenshteinDistance as te } from "./src/fuzzyMatcher.js";
-import { SchemaCache as ie, createSchemaCache as Te, getCachedField as ae, getCachedFieldNames as Ee, getCachedFieldType as Se, getSchemaCache as _e } from "./src/schemaCache.js";
-import { ComplexityAnalyzer as Ae, analyzeComplexity as Oe, getComplexityMetrics as ne, getComplexityWarnings as Re, isHighComplexity as se } from "./src/complexityAnalyzer.js";
-import { SemanticPreview as me, flattenLogicTree as Pe, formatLogicTreeAscii as Ie, formatLogicTreeNode as Ne, generatePreview as Ce, getFieldUsage as ce, getLogicTree as pe, getLogicTreeDepth as Le, getOperatorSummary as de, getUniqueFields as fe } from "./src/semanticPreview.js";
-import { buildStatsQuery as xe, parseVizHintString as Ue } from "./src/builder.js";
-import { QUERY_PLAN_EXPLAIN_KEYS as ue, QUERY_PLAN_EXPLAIN_VERSION as ye, QUERY_PLAN_RULES as qe, summarizeQueryPlan as Ge } from "./src/queryPlan.js";
+import { AGGREGATION_FUNCTIONS as t, BOOLEAN_PREDICATE_MUTATORS as o, BOOLEAN_PREDICATE_MUTATOR_SET as i, COLLECTION_OPERATORS as T, COMPARISON_OPERATORS as a, DATE_HISTOGRAM_CALENDAR_INTERVALS as E, DATE_HISTOGRAM_FIXED_UNITS as O, GEO_GRID_PRECISION as S, GROUP_BY_BUCKET_FUNCTIONS as l, KEYWORDS as R, LOGICAL_OPERATORS as _, MUTATORS as n, NEGATION_SYMBOL_OPERATORS as A, SYMBOL_OPERATORS as s, TYPE_HINTS as g, TqlTokenizer as m, VISUALIZATION_TYPES as I, findPreviousToken as P, findTokenAtPosition as N, findTokenBefore as C, findTokensInRange as c, tokenizeTql as d, tokenizeTqlNoWhitespace as p } from "./src/tokenizer.js";
+import { TqlParser as f, dateHistogramIntervalProblem as h, formatParseError as x, geoPrecisionProblem as M, getTqlErrors as U, isValidTql as u, parseTql as y, rangeBoundariesProblem as D } from "./src/parser.js";
+import { CASE_SENSITIVE_MEMBERSHIP_OPERATORS as V, CASE_SENSITIVE_OPERATORS as q, CASE_SENSITIVE_WHOLE_VALUE_OPERATORS as z, MAX_REGEX_PATTERN_LENGTH as F, TqlValidator as Y, casePreservingForm as B, caseSensitiveSupport as H, formatValidationResult as k, getTqlIssues as v, isValidTqlSyntax as b, validateTql as Q } from "./src/validator.js";
+import { ORDERABLE_FIELD_TYPES as X, ORDERING_OPERATORS as K, checkOrderingComparison as w, isOrderingOperator as Z, literalIsOrderable as j, orderingRefusalMessage as J, orderingVerdict as $ } from "./src/ordering.js";
+import { getCompletionTriggerCharacters as re, getCompletions as te, getWordAtPosition as oe, shouldTriggerCompletion as ie } from "./src/completionProvider.js";
+import { findClosestMatch as ae, fuzzyFilter as Ee, fuzzyMatch as Oe, highlightMatch as Se, levenshteinDistance as le } from "./src/fuzzyMatcher.js";
+import { SchemaCache as _e, createSchemaCache as ne, getCachedField as Ae, getCachedFieldNames as se, getCachedFieldType as ge, getSchemaCache as me } from "./src/schemaCache.js";
+import { ComplexityAnalyzer as Pe, analyzeComplexity as Ne, getComplexityMetrics as Ce, getComplexityWarnings as ce, isHighComplexity as de } from "./src/complexityAnalyzer.js";
+import { SemanticPreview as Le, flattenLogicTree as fe, formatLogicTreeAscii as he, formatLogicTreeNode as xe, generatePreview as Me, getFieldUsage as Ue, getLogicTree as ue, getLogicTreeDepth as ye, getOperatorSummary as De, getUniqueFields as Ge } from "./src/semanticPreview.js";
+import { buildStatsQuery as qe, parseVizHintString as ze } from "./src/builder.js";
+import { QUERY_PLAN_EXPLAIN_KEYS as Ye, QUERY_PLAN_EXPLAIN_VERSION as Be, QUERY_PLAN_RULES as He, summarizeQueryPlan as ke } from "./src/queryPlan.js";
 export {
   t as AGGREGATION_FUNCTIONS,
   o as BOOLEAN_PREDICATE_MUTATORS,
   i as BOOLEAN_PREDICATE_MUTATOR_SET,
   V as CASE_SENSITIVE_MEMBERSHIP_OPERATORS,
-  z as CASE_SENSITIVE_OPERATORS,
-  D as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
+  q as CASE_SENSITIVE_OPERATORS,
+  z as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
   T as COLLECTION_OPERATORS,
   a as COMPARISON_OPERATORS,
-  Ae as ComplexityAnalyzer,
+  Pe as ComplexityAnalyzer,
   E as DATE_HISTOGRAM_CALENDAR_INTERVALS,
-  S as DATE_HISTOGRAM_FIXED_UNITS,
-  _ as GEO_GRID_PRECISION,
+  O as DATE_HISTOGRAM_FIXED_UNITS,
+  S as GEO_GRID_PRECISION,
   l as GROUP_BY_BUCKET_FUNCTIONS,
-  A as KEYWORDS,
-  O as LOGICAL_OPERATORS,
+  R as KEYWORDS,
+  _ as LOGICAL_OPERATORS,
   F as MAX_REGEX_PATTERN_LENGTH,
   n as MUTATORS,
-  R as NEGATION_SYMBOL_OPERATORS,
-  ue as QUERY_PLAN_EXPLAIN_KEYS,
-  ye as QUERY_PLAN_EXPLAIN_VERSION,
-  qe as QUERY_PLAN_RULES,
+  A as NEGATION_SYMBOL_OPERATORS,
+  X as ORDERABLE_FIELD_TYPES,
+  K as ORDERING_OPERATORS,
+  Ye as QUERY_PLAN_EXPLAIN_KEYS,
+  Be as QUERY_PLAN_EXPLAIN_VERSION,
+  He as QUERY_PLAN_RULES,
   s as SYMBOL_OPERATORS,
-  ie as SchemaCache,
-  me as SemanticPreview,
+  _e as SchemaCache,
+  Le as SemanticPreview,
   g as TYPE_HINTS,
   f as TqlParser,
   m as TqlTokenizer,
   Y as TqlValidator,
-  P as VISUALIZATION_TYPES,
-  Oe as analyzeComplexity,
-  xe as buildStatsQuery,
+  I as VISUALIZATION_TYPES,
+  Ne as analyzeComplexity,
+  qe as buildStatsQuery,
   B as casePreservingForm,
   H as caseSensitiveSupport,
-  Te as createSchemaCache,
+  w as checkOrderingComparison,
+  ne as createSchemaCache,
   h as dateHistogramIntervalProblem,
-  J as findClosestMatch,
-  I as findPreviousToken,
+  ae as findClosestMatch,
+  P as findPreviousToken,
   N as findTokenAtPosition,
   C as findTokenBefore,
   c as findTokensInRange,
-  Pe as flattenLogicTree,
-  Ie as formatLogicTreeAscii,
-  Ne as formatLogicTreeNode,
+  fe as flattenLogicTree,
+  he as formatLogicTreeAscii,
+  xe as formatLogicTreeNode,
   x as formatParseError,
-  v as formatValidationResult,
-  $ as fuzzyFilter,
-  ee as fuzzyMatch,
-  Ce as generatePreview,
-  U as geoPrecisionProblem,
-  ae as getCachedField,
-  Ee as getCachedFieldNames,
-  Se as getCachedFieldType,
-  b as getCompletionTriggerCharacters,
-  K as getCompletions,
-  ne as getComplexityMetrics,
-  Re as getComplexityWarnings,
-  ce as getFieldUsage,
-  pe as getLogicTree,
-  Le as getLogicTreeDepth,
-  de as getOperatorSummary,
-  _e as getSchemaCache,
-  M as getTqlErrors,
-  k as getTqlIssues,
-  fe as getUniqueFields,
-  w as getWordAtPosition,
-  re as highlightMatch,
-  se as isHighComplexity,
+  k as formatValidationResult,
+  Ee as fuzzyFilter,
+  Oe as fuzzyMatch,
+  Me as generatePreview,
+  M as geoPrecisionProblem,
+  Ae as getCachedField,
+  se as getCachedFieldNames,
+  ge as getCachedFieldType,
+  re as getCompletionTriggerCharacters,
+  te as getCompletions,
+  Ce as getComplexityMetrics,
+  ce as getComplexityWarnings,
+  Ue as getFieldUsage,
+  ue as getLogicTree,
+  ye as getLogicTreeDepth,
+  De as getOperatorSummary,
+  me as getSchemaCache,
+  U as getTqlErrors,
+  v as getTqlIssues,
+  Ge as getUniqueFields,
+  oe as getWordAtPosition,
+  Se as highlightMatch,
+  de as isHighComplexity,
+  Z as isOrderingOperator,
   u as isValidTql,
-  Q as isValidTqlSyntax,
-  te as levenshteinDistance,
+  b as isValidTqlSyntax,
+  le as levenshteinDistance,
+  j as literalIsOrderable,
+  J as orderingRefusalMessage,
+  $ as orderingVerdict,
   y as parseTql,
-  Ue as parseVizHintString,
-  q as rangeBoundariesProblem,
-  Z as shouldTriggerCompletion,
-  Ge as summarizeQueryPlan,
-  p as tokenizeTql,
-  L as tokenizeTqlNoWhitespace,
-  W as validateTql
+  ze as parseVizHintString,
+  D as rangeBoundariesProblem,
+  ie as shouldTriggerCompletion,
+  ke as summarizeQueryPlan,
+  d as tokenizeTql,
+  p as tokenizeTqlNoWhitespace,
+  Q as validateTql
 };

package/dist/src/completionProvider.js

@@ -1,7 +1,7 @@
-import { BOOLEAN_PREDICATE_MUTATORS as E, tokenizeTql as T, COMPARISON_OPERATORS as R, LOGICAL_OPERATORS as $, GROUP_BY_BUCKET_FUNCTIONS as P, AGGREGATION_FUNCTIONS as D, VISUALIZATION_TYPES as M, TYPE_HINTS as z, MUTATORS as U } from "./tokenizer.js";
+import { BOOLEAN_PREDICATE_MUTATORS as E, tokenizeTql as T, COMPARISON_OPERATORS as $, LOGICAL_OPERATORS as R, GROUP_BY_BUCKET_FUNCTIONS as P, AGGREGATION_FUNCTIONS as D, VISUALIZATION_TYPES as M, TYPE_HINTS as z, MUTATORS as U } from "./tokenizer.js";
 import { fuzzyMatch as v } from "./fuzzyMatcher.js";
 import { getSchemaCache as I } from "./schemaCache.js";
-import { ALL_FIELD_TYPES as u, BETWEEN_FIELD_TYPES as w, ORDERED_FIELD_TYPES as f } from "./validator.js";
+import { ALL_FIELD_TYPES as c, BETWEEN_FIELD_TYPES as w, ORDERED_FIELD_TYPES as f } from "./validator.js";
 const F = [
   {
     label: "Simple equality",
@@ -105,24 +105,24 @@ const F = [
     description: "Top 10 results by count",
     category: "Stats"
   }
-], G = {
+], q = {
   eq: { detail: "Equals", documentation: "Exact match comparison" },
   ne: { detail: "Not equals", documentation: "Match any value except this one" },
   gt: {
     detail: "Greater than",
-    documentation: "Ordered comparison. Numbers and dates compare numerically; two STRINGS compare lexicographically. An array-valued field matches if ANY element does."
+    documentation: "Ordered comparison, on numeric, date and ip fields only: a keyword or text field is refused (tql#302). With no schema the value must be a number, a date or an ip. An array-valued field matches if ANY element does."
   },
   gte: {
     detail: "Greater than or equal",
-    documentation: "Ordered comparison. Numbers and dates compare numerically; two STRINGS compare lexicographically. An array-valued field matches if ANY element does."
+    documentation: "Ordered comparison, on numeric, date and ip fields only: a keyword or text field is refused (tql#302). With no schema the value must be a number, a date or an ip. An array-valued field matches if ANY element does."
   },
   lt: {
     detail: "Less than",
-    documentation: "Ordered comparison. Numbers and dates compare numerically; two STRINGS compare lexicographically. An array-valued field matches if ANY element does."
+    documentation: "Ordered comparison, on numeric, date and ip fields only: a keyword or text field is refused (tql#302). With no schema the value must be a number, a date or an ip. An array-valued field matches if ANY element does."
   },
   lte: {
     detail: "Less than or equal",
-    documentation: "Ordered comparison. Numbers and dates compare numerically; two STRINGS compare lexicographically. An array-valued field matches if ANY element does."
+    documentation: "Ordered comparison, on numeric, date and ip fields only: a keyword or text field is refused (tql#302). With no schema the value must be a number, a date or an ip. An array-valued field matches if ANY element does."
   },
   contains: { detail: "Contains substring", documentation: "Case-insensitive substring match" },
   not_contains: { detail: "Does not contain", documentation: "Negative substring match" },
@@ -138,7 +138,7 @@ const F = [
   not_matches: { detail: "Not matching pattern", documentation: "Negative pattern match" },
   between: {
     detail: "Between range",
-    documentation: "Inclusive range. Usage: field between A AND B, or field between [A, B]. Numeric bounds compare numerically; STRING bounds compare lexicographically, matching the range query this becomes on a keyword field."
+    documentation: "Inclusive range. Usage: field between A AND B, or field between [A, B]. Numeric, date and ip fields only: a keyword or text field is refused (tql#302), and with no schema both bounds must be numbers, dates or ips."
   },
   not_between: { detail: "Not between range", documentation: "Exclude values in range" },
   in: { detail: "In list", documentation: 'Usage: field in ["a", "b", "c"]' },
@@ -257,30 +257,27 @@ const F = [
   geo: "object",
   // Array output (returns array of strings)
   split: "keyword"
-}, q = {
+}, G = {
   // Equality and membership — every field type, by NAME rather than by a transcribed list.
-  eq: u,
-  ne: u,
-  in: u,
-  not_in: u,
+  eq: c,
+  ne: c,
+  in: c,
+  not_in: c,
   // Existence. `is null` is the SAME PREDICATE as `not exists`, so these four lists must be
   // equal. They were not: `nested` and `object` were offered for `exists` and withheld from
   // `is`, so the completion menu published one of two spellings of one operation depending
   // on the field type. Pinned by `tests/collectionAndNullSemantics.spec.ts`.
-  exists: u,
-  not_exists: u,
-  is: u,
-  is_not: u,
-  // Ordered comparison — numeric, date and keyword. See ORDERED_FIELD_TYPES in
-  // `validator.ts`: both evaluators fall back to a lexicographic string comparison, and
-  // Python's own validator lists all four in `keyword_ops`. Withholding them from a keyword
-  // field's menu hid an operator every layer of the product supports.
+  exists: c,
+  not_exists: c,
+  is: c,
+  is_not: c,
+  // Ordered comparison — numeric, date and ip only (tql#302). See ORDERED_FIELD_TYPES in
+  // `validator.ts`: every engine refuses them on any other type, so offering one on a
+  // keyword field's menu would offer a query that cannot run.
   gt: f,
   gte: f,
   lt: f,
   lte: f,
-  // Numeric and date. `keyword` and `text` stay out because Python's `keyword_ops` excludes
-  // `between` while including `gte` — see BETWEEN_FIELD_TYPES in `validator.ts`.
   between: w,
   not_between: w,
   // String operators (text/keyword only)
@@ -312,12 +309,12 @@ const F = [
   // filter reads as "no restriction" — so the negated halves were offered on every type
   // while their positive twins were withheld. Permissive by omission is not the same as
   // permissive by decision, and only one of them survives someone reading the table.
-  any: u,
-  all: u,
-  none: u,
-  not_any: u,
-  not_all: u,
-  not_none: u
+  any: c,
+  all: c,
+  none: c,
+  not_any: c,
+  not_all: c,
+  not_none: c
 };
 class Y {
   cache = /* @__PURE__ */ new Map();
@@ -354,7 +351,7 @@ function H(e, t, i) {
   const n = T(e.substring(0, t)).filter((l) => l.type !== "whitespace");
   if (n.length === 0)
     return { type: "start" };
-  const a = n[n.length - 1], s = n.length > 1 ? n[n.length - 2] : null, c = a.end === t && !e[t - 1]?.match(/\s/), d = c ? a.value : void 0;
+  const a = n[n.length - 1], s = n.length > 1 ? n[n.length - 2] : null, u = a.end === t && !e[t - 1]?.match(/\s/), d = u ? a.value : void 0;
   if (a.type === "logicalOp")
     return { type: "start" };
   if (a.type === "paren" && a.value === "(") {
@@ -362,7 +359,7 @@ function H(e, t, i) {
     if (r && r.type === "visualization")
       return { type: "in_viz_params" };
   }
-  if (a.type === "comma" || a.type === "field" && c) {
+  if (a.type === "comma" || a.type === "field" && u) {
     const l = n.indexOf(a);
     for (let r = l - 1; r >= 0; r--) {
       if (n[r].type === "paren" && n[r].value === "(") {
@@ -377,13 +374,13 @@ function H(e, t, i) {
     return { type: "after_paren" };
   if (a.type === "arrow")
     return { type: "after_arrow", partialText: d };
-  if (s?.type === "doubleColon" && c)
+  if (s?.type === "doubleColon" && u)
     return { type: "after_double_colon", partialText: d };
   if (a.type === "doubleColon")
     return { type: "after_double_colon" };
-  if (a.type === "visualization" && c)
+  if (a.type === "visualization" && u)
     return { type: "after_arrow", partialText: d };
-  if (a.type === "typeHint" && c)
+  if (a.type === "typeHint" && u)
     return { type: "after_double_colon", partialText: d };
   if (a.type === "keyword" && a.value.toLowerCase() === "stats")
     return { type: "after_stats", partialText: d };
@@ -397,7 +394,7 @@ function H(e, t, i) {
       if (n[r].type === "keyword" && n[r].value.toLowerCase() === "by" || n[r].type === "pipe") break;
     }
   }
-  if (a.type === "field" && !c) {
+  if (a.type === "field" && !u) {
     const l = n.indexOf(a);
     for (let r = l - 1; r >= 0; r--) {
       if (n[r].type === "keyword" && n[r].value.toLowerCase() === "by") {
@@ -414,7 +411,7 @@ function H(e, t, i) {
   if (a.type === "pipe")
     return { type: "after_pipe", partialText: d };
   if (a.type === "mutator") {
-    if (c)
+    if (u)
       return { type: "after_pipe", partialText: d };
     const l = a.value.toLowerCase(), r = g[l];
     return {
@@ -424,9 +421,9 @@ function H(e, t, i) {
     };
   }
   if (a.type === "aggregation")
-    return c ? { type: "after_stats", partialText: d } : { type: "after_value" };
+    return u ? { type: "after_stats", partialText: d } : { type: "after_value" };
   if (a.type === "field") {
-    if (c)
+    if (u)
       return s?.type === "pipe" ? { type: "after_pipe", partialText: d } : { type: "start", partialText: d };
     if (s?.type === "pipe")
       return { type: "after_pipe", partialText: a.value };
@@ -434,7 +431,7 @@ function H(e, t, i) {
     return { type: "after_field", fieldName: a.value, fieldType: l };
   }
   if (a.type === "operator") {
-    if (c) {
+    if (u) {
       if (s?.type === "field") {
         const l = h(s.value, i);
         return { type: "after_field", fieldName: s.value, fieldType: l, partialText: d };
@@ -447,14 +444,14 @@ function H(e, t, i) {
     return { type: "after_operator", operatorName: a.value };
   }
   if (a.type === "string" || a.type === "number" || a.type === "boolean" || a.type === "null")
-    return c ? { type: "at_value_end" } : { type: "after_value" };
+    return u ? { type: "at_value_end" } : { type: "after_value" };
   if (a.type === "paren" && a.value === ")")
     return { type: "after_value" };
-  if (s?.type === "field" && c) {
+  if (s?.type === "field" && u) {
     const l = h(s.value, i);
     return { type: "after_field", fieldName: s.value, fieldType: l, partialText: d };
   }
-  if (s?.type === "mutator" && c) {
+  if (s?.type === "mutator" && u) {
     const l = s.value.toLowerCase(), r = g[l];
     return { type: "after_mutator", mutatorName: l, mutatorOutputType: r, partialText: d };
   }
@@ -477,10 +474,10 @@ function le(e, t = {}) {
       a.push(...b(n.partialText, n.mutatorOutputType));
       break;
     case "after_operator":
-      a.push(...W(n.fieldName, t));
+      a.push(...K(n.fieldName, t));
       break;
     case "after_value":
-      a.push(...C());
+      a.push(...A());
       break;
     case "at_value_end":
       break;
@@ -540,20 +537,20 @@ function le(e, t = {}) {
       a.push(...ae(n.partialText));
       break;
     case "after_stats":
-      a.push(...A(n.partialText));
+      a.push(...N(n.partialText));
       break;
     case "after_by":
       a.push(...x(t.fields, n.partialText)), a.push(...J(n.partialText));
       break;
     default:
-      a.push(...x(t.fields, n.partialText)), a.push(...b(n.partialText)), a.push(...C());
+      a.push(...x(t.fields, n.partialText)), a.push(...b(n.partialText)), a.push(...A());
   }
-  t.includeAggregations && n.type === "start" && a.push(...A(n.partialText));
+  t.includeAggregations && n.type === "start" && a.push(...N(n.partialText));
   let s = a;
-  const c = t.fuzzyMatching !== !1, d = t.minFuzzyScore ?? 0;
+  const u = t.fuzzyMatching !== !1, d = t.minFuzzyScore ?? 0;
   if (n.partialText) {
     const l = n.partialText.toLowerCase();
-    if (c) {
+    if (u) {
       const r = [];
       for (const m of a) {
         const p = v(l, m.label), _ = m.filterText ? v(l, m.filterText) : { matched: !1, score: 0 }, y = p.score >= _.score ? p : _;
@@ -576,10 +573,10 @@ function x(e, t) {
     return j(t);
   const i = [];
   for (const o of e) {
-    const n = N(o);
+    const n = C(o);
     if (i.push(n), o.nested)
       for (const a of o.nested) {
-        const s = N(a, o.name);
+        const s = C(a, o.name);
         i.push(s);
       }
   }
@@ -597,9 +594,6 @@ function j(e) {
     { name: "@timestamp", description: "Event timestamp" },
     { name: "message", description: "Message content" },
     { name: "user.name", description: "User name" },
-    { name: "os.family", description: "Operating system family" },
-    { name: "os.type", description: "Operating system type" },
-    { name: "os.version", description: "Operating system version" },
     { name: "customer", description: "Customer identifier" },
     { name: "stack", description: "Stack identifier" }
   ].filter((i) => !e || i.name.toLowerCase().includes(e.toLowerCase())).map((i) => ({
@@ -611,7 +605,7 @@ function j(e) {
     sortOrder: 10
   }));
 }
-function N(e, t) {
+function C(e, t) {
   const i = t ? `${t}.${e.name}` : e.name;
   return {
     label: i,
@@ -624,12 +618,12 @@ function N(e, t) {
   };
 }
 function b(e, t) {
-  let i = [...R];
+  let i = [...$];
   return t && (i = i.filter((o) => {
-    const n = q[o];
+    const n = G[o];
     return !n || n.includes(t);
   })), e && (i = i.filter((o) => o.toLowerCase().includes(e.toLowerCase()))), i.map((o, n) => {
-    const a = G[o] || { detail: o, documentation: "" }, s = K(o, t);
+    const a = q[o] || { detail: o, documentation: "" }, s = W(o, t);
     return {
       label: o,
       insertText: s,
@@ -640,7 +634,7 @@ function b(e, t) {
     };
   });
 }
-function K(e, t) {
+function W(e, t) {
   const i = [
     "contains",
     "not_contains",
@@ -683,6 +677,7 @@ function K(e, t) {
       return `${e} $1`;
     // Numbers, no quotes
     case "date":
+    case "date_nanos":
       return `${e} "$1"`;
     // Dates typically quoted
     case "ip":
@@ -695,8 +690,8 @@ function K(e, t) {
 function O(e) {
   return e === "long" || e === "integer" || e === "double" || e === "float" || e === "short" || e === "byte" || e === "half_float" || e === "scaled_float" || e === "unsigned_long";
 }
-function C() {
-  return $.filter((e) => e !== "NOT").map(
+function A() {
+  return R.filter((e) => e !== "NOT").map(
     (e, t) => L(e, t)
   );
 }
@@ -709,7 +704,7 @@ function L(e, t = 0) {
     sortOrder: 30 + t
   };
 }
-function W(e, t) {
+function K(e, t) {
   const i = [];
   return e && t?.fieldValues?.[e] && t.fieldValues[e].forEach((n, a) => {
     i.push({
@@ -775,7 +770,7 @@ function X(e) {
     }
   );
 }
-function A(e) {
+function N(e) {
   return D.filter(
     (t) => !e || t.toLowerCase().includes(e.toLowerCase())
   ).map((t, i) => ({
@@ -901,7 +896,7 @@ function se(e, t) {
 function de() {
   return [" ", "(", ".", '"', "'", "|", ":", "="];
 }
-function ce(e, t, i) {
+function ue(e, t, i) {
   if (!e) return !1;
   if (i === " " || i === "(" || i === "." || i === "|" || i === ":" || i === "=") return !0;
   const o = T(e.substring(0, t)), n = o[o.length - 1];
@@ -912,5 +907,5 @@ export {
   de as getCompletionTriggerCharacters,
   le as getCompletions,
   se as getWordAtPosition,
-  ce as shouldTriggerCompletion
+  ue as shouldTriggerCompletion
 };

package/dist/src/index.d.ts

@@ -6,10 +6,11 @@
  *
  * @packageDocumentation
  */
-export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, TqlGroupByBucket, TqlLatLon, TqlGroupByLevel, TqlGroupByMetadata, TqlRowBucketMeta, TqlStatsRow, TqlGroupExpression, TqlLiteral, TqlFieldReference, TqlComparisonOperator, TqlLogicalOperator, TqlCollectionOperator, TqlMutator, TqlAggregationFunction, TqlTypeHint, TqlVisualizationType, TqlVizParams, TqlVizHint, TqlParseResult, TqlParseError, TqlParseWarning, TqlErrorCode, TqlWarningCode, TqlValidationResult, TqlValidationOptions, TqlFieldType, CaseSensitiveSupport, TqlCompletionItem, TqlCompletionKind, TqlCompletionContext, TqlCompletionOptions, TqlFieldSchema, TqlSnippet, TqlInputProps, TqlInputEmits, TqlInputExpose } from './types';
+export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, TqlGroupByBucket, TqlLatLon, TqlGroupByLevel, TqlGroupByMetadata, TqlRowBucketMeta, TqlStatsRow, TqlGroupExpression, TqlLiteral, TqlFieldReference, TqlComparisonOperator, TqlLogicalOperator, TqlCollectionOperator, TqlMutator, TqlAggregationFunction, TqlTypeHint, TqlVisualizationType, TqlVizParams, TqlVizHint, TqlParseResult, TqlParseError, TqlOrderingRefusal, TqlParseWarning, TqlErrorCode, TqlWarningCode, TqlValidationResult, TqlValidationOptions, TqlFieldType, CaseSensitiveSupport, TqlCompletionItem, TqlCompletionKind, TqlCompletionContext, TqlCompletionOptions, TqlFieldSchema, TqlSnippet, TqlInputProps, TqlInputEmits, TqlInputExpose } from './types';
 export { TqlTokenizer, tokenizeTql, tokenizeTqlNoWhitespace, findTokenAtPosition, findTokensInRange, findTokenBefore, findPreviousToken, COMPARISON_OPERATORS, SYMBOL_OPERATORS, NEGATION_SYMBOL_OPERATORS, LOGICAL_OPERATORS, COLLECTION_OPERATORS, MUTATORS, BOOLEAN_PREDICATE_MUTATORS, BOOLEAN_PREDICATE_MUTATOR_SET, AGGREGATION_FUNCTIONS, GROUP_BY_BUCKET_FUNCTIONS, DATE_HISTOGRAM_CALENDAR_INTERVALS, DATE_HISTOGRAM_FIXED_UNITS, GEO_GRID_PRECISION, TYPE_HINTS, VISUALIZATION_TYPES, KEYWORDS } from './tokenizer';
 export { TqlParser, parseTql, isValidTql, getTqlErrors, formatParseError, dateHistogramIntervalProblem, geoPrecisionProblem, rangeBoundariesProblem } from './parser';
 export { TqlValidator, validateTql, isValidTqlSyntax, getTqlIssues, formatValidationResult, caseSensitiveSupport, casePreservingForm, CASE_SENSITIVE_OPERATORS, CASE_SENSITIVE_WHOLE_VALUE_OPERATORS, CASE_SENSITIVE_MEMBERSHIP_OPERATORS, MAX_REGEX_PATTERN_LENGTH } from './validator';
+export { ORDERING_OPERATORS, ORDERABLE_FIELD_TYPES, isOrderingOperator, literalIsOrderable, orderingVerdict, orderingRefusalMessage, checkOrderingComparison } from './ordering';
 export { getCompletions, getWordAtPosition, getCompletionTriggerCharacters, shouldTriggerCompletion } from './completionProvider';
 export { fuzzyMatch, levenshteinDistance, findClosestMatch, fuzzyFilter, highlightMatch, type FuzzyMatchResult, type FuzzyMatchOptions } from './fuzzyMatcher';
 export { SchemaCache, getSchemaCache, createSchemaCache, getCachedFieldNames, getCachedFieldType, getCachedField, type CachedSchema } from './schemaCache';

package/dist/src/ordering.d.ts

@@ -0,0 +1,32 @@
+import { TqlFieldType, TqlLiteral, TqlOrderingRefusal } from './types';
+/** Every spelling of an ordering comparator the parser produces. */
+export declare const ORDERING_OPERATORS: readonly string[];
+/** The field types an ordering comparator is valid on, in the order the error lists them. */
+export declare const ORDERABLE_FIELD_TYPES: readonly string[];
+/** Type names a refusal reports as themselves; see `orderingVerdict`. */
+export declare const REPORTED_TYPE_NAMES: ReadonlySet<string>;
+export declare function isOrderingOperator(operator: string): boolean;
+export type { TqlOrderingRefusal };
+/** The refusal text. Byte-identical to Python's `TQLOrderingTypeError` and Rust's `OrderingTypeError`. */
+export declare function orderingRefusalMessage(refusal: Omit<TqlOrderingRefusal, "allowedTypes">): string;
+/** Is this literal a number, a date or an ip address? Judged on its text: quoting is not the rule. */
+export declare function literalIsOrderable(literal: TqlLiteral): boolean;
+/** `null` when nothing is known about the field's type; else its type and whether it is orderable. */
+export type TqlFieldTypeVerdict = {
+    reported: string;
+    orderable: boolean;
+} | null;
+/**
+ * The verdict for `field` from a flat schema. A field is orderable when it, or a DIRECT subfield
+ * the schema lists (`f.num`), has an orderable type — the engines aim the clause at that subfield.
+ */
+export declare function orderingVerdict(field: string, fieldTypes?: Record<string, TqlFieldType | TqlFieldType[]>): TqlFieldTypeVerdict;
+/** Refuse one ordering comparison with no meaningful order, or return `null`. See the module doc. */
+export declare function checkOrderingComparison(args: {
+    field: string;
+    operator: string;
+    value: TqlLiteral | TqlLiteral[];
+    verdict: TqlFieldTypeVerdict;
+    typeHint?: string;
+    hasFieldMutators: boolean;
+}): TqlOrderingRefusal | null;

package/dist/src/ordering.js

@@ -0,0 +1,141 @@
+const h = [
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  ">",
+  ">=",
+  "<",
+  "<=",
+  "between",
+  "not_between",
+  "!between"
+], c = [
+  "long",
+  "integer",
+  "short",
+  "byte",
+  "double",
+  "float",
+  "half_float",
+  "scaled_float",
+  "unsigned_long",
+  "date",
+  "date_nanos",
+  "ip"
+], w = /* @__PURE__ */ new Set([
+  "keyword",
+  "text",
+  "long",
+  "double",
+  "boolean",
+  "date",
+  "ip",
+  "wildcard",
+  "object",
+  "nested",
+  "geo_point",
+  "unsigned_long",
+  "match_only_text",
+  "annotated_text",
+  "unknown"
+]), y = /* @__PURE__ */ new Set(["integer", "int", "number", "decimal", "float", "double", "date", "ip"]), _ = /* @__PURE__ */ new Set(["string", "str", "boolean", "bool", "geo", "object"]);
+function E(e) {
+  return h.includes(e);
+}
+function $(e) {
+  const t = e.operator === "!between" ? "not_between" : e.operator, s = e.literal === void 0 ? `field '${e.field}' of type '${e.fieldType}'` : `field '${e.field}' of unknown type with the literal '${e.literal}'`;
+  let r = `Cannot apply ordering operator '${t}' to ${s}. Ordering operators (gt, gte, lt, lte, between) are valid only on numeric, date and ip fields (allowed types: ${c.join(", ")}).`;
+  return e.literal !== void 0 && (r += " With no field type known, the literal must be a number, a date or an ip address."), r;
+}
+const O = /^[+-]?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?$/, f = /^[0-9]{4}-[0-9]{2}-[0-9]{2}([T ][0-9]{2}:[0-9]{2}(:[0-9]{2}([.,][0-9]+)?)?(Z|[+-][0-9]{2}(:?[0-9]{2})?)?)?$/, p = /^([+-][0-9]+[yMwdhHms]|\/[yMwdhHms])*$/, g = /^(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])(\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])){3}$/, v = /^[0-9A-Fa-f]{1,4}$/;
+function A(e) {
+  if (!e.includes(":") || !/^[0-9A-Fa-f:.]+$/.test(e))
+    return !1;
+  const t = e.split("::");
+  if (t.length > 2)
+    return !1;
+  const s = (n) => n === "" ? [] : n.split(":"), r = s(t[0]), i = t.length === 2 ? s(t[1]) : [];
+  if (r === null || i === null)
+    return !1;
+  const a = [...r, ...i];
+  let u = 0;
+  for (let n = 0; n < a.length; n++) {
+    const l = a[n];
+    if (n === a.length - 1 && !e.endsWith("::") && l.includes(".")) {
+      if (!g.test(l)) return !1;
+      u += 2;
+    } else if (v.test(l))
+      u += 1;
+    else
+      return !1;
+  }
+  return t.length === 2 ? u <= 7 : u === 8;
+}
+function m(e) {
+  if (e.startsWith("now"))
+    return p.test(e.slice(3));
+  const t = e.indexOf("||");
+  return t === -1 ? f.test(e) : f.test(e.slice(0, t)) && p.test(e.slice(t + 2));
+}
+function R(e) {
+  if (e.valueType === "number") return !0;
+  if (e.valueType !== "string" || typeof e.value != "string") return !1;
+  const t = e.value;
+  return O.test(t) || m(t) || g.test(t) || A(t);
+}
+function T(e) {
+  return e.value === null ? "null" : String(e.value);
+}
+function S(e, t) {
+  const s = t?.[e];
+  if (s === void 0) return null;
+  const r = Array.isArray(s) ? s : [s];
+  if (r.length === 0) return null;
+  let i = r.some((n) => c.includes(n));
+  const a = r.every((n) => n === "object" || n === "nested");
+  if (!i && !a && t) {
+    const n = `${e}.`;
+    for (const [l, o] of Object.entries(t)) {
+      if (!l.startsWith(n) || l.slice(n.length).includes(".")) continue;
+      if ((Array.isArray(o) ? o : [o]).some((b) => c.includes(b))) {
+        i = !0;
+        break;
+      }
+    }
+  }
+  return { reported: r.map((n) => i || w.has(n) ? n : "unknown").join(" or "), orderable: i };
+}
+function D(e) {
+  const { field: t, operator: s, value: r, verdict: i, typeHint: a, hasFieldMutators: u } = e;
+  if (!E(s)) return null;
+  const n = (o, d) => ({
+    field: t,
+    fieldType: o,
+    operator: s === "!between" ? "not_between" : s,
+    ...d === void 0 ? {} : { literal: d },
+    allowedTypes: [...c]
+  });
+  if (!u) {
+    if (i !== null)
+      return i.orderable ? null : n(i.reported);
+    const o = (a ?? "").toLowerCase();
+    if (y.has(o)) return null;
+    if (_.has(o)) return n(o);
+  }
+  const l = Array.isArray(r) ? r : [r];
+  for (const o of l)
+    if (o.type === "literal" && !R(o))
+      return n("unknown", T(o));
+  return null;
+}
+export {
+  c as ORDERABLE_FIELD_TYPES,
+  h as ORDERING_OPERATORS,
+  w as REPORTED_TYPE_NAMES,
+  D as checkOrderingComparison,
+  E as isOrderingOperator,
+  R as literalIsOrderable,
+  $ as orderingRefusalMessage,
+  S as orderingVerdict
+};

package/dist/src/types.d.ts

@@ -293,6 +293,18 @@ export interface TqlParseError {
     severity: "error";
     code: TqlErrorCode;
     suggestion?: string;
+    /** Set on `UNORDERABLE_FIELD`: the field, its type, the operator and the allowed types. */
+    ordering?: TqlOrderingRefusal;
+}
+/** An ordering comparator refused on a field with no meaningful order (tql#302). */
+export interface TqlOrderingRefusal {
+    field: string;
+    /** Mapped type, the type hint, or `"unknown"` when the literal was refused. */
+    fieldType: string;
+    operator: string;
+    /** Set when no field type was known and the LITERAL was refused. */
+    literal?: string;
+    allowedTypes: string[];
 }
 export interface TqlParseWarning {
     message: string;
@@ -335,7 +347,15 @@ export type TqlErrorCode = "UNEXPECTED_TOKEN" | "UNEXPECTED_END" | "UNBALANCED_P
  * malformed `range` boundaries, a duplicate `filters` label. Mirrors
  * `cross_language_tests/fixtures/test_cases/validation/stats_bucket_errors.json`.
  */
- | "INVALID_STATS_BUCKET";
+ | "INVALID_STATS_BUCKET"
+/**
+ * An ordering comparator (`gt`/`gte`/`lt`/`lte`, `between`) on a field with no meaningful
+ * order (tql#302): a mapped type that is not numeric, date or ip, or — with no type known —
+ * a literal that is not a number, a date or an ip address. Both engines refuse the same
+ * query with the same message (`TQLOrderingTypeError` / `OrderingTypeError`). The error's
+ * `ordering` field carries the details.
+ */
+ | "UNORDERABLE_FIELD";
 export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPERATOR" | "REDUNDANT_PARENS"
 /**
  * The query parses, but only ONE of the two engines accepts it.
@@ -412,7 +432,7 @@ export interface TqlValidationOptions {
  * documents the predicate and its two blind spots.
  */
 export type CaseSensitiveSupport = "supported" | "unsupported" | "unknown";
-export type TqlFieldType = "text" | "keyword" | "long" | "integer" | "short" | "byte" | "double" | "float" | "half_float" | "scaled_float" | "unsigned_long" | "date" | "boolean" | "ip" | "nested" | "object" | "geo_point";
+export type TqlFieldType = "text" | "keyword" | "long" | "integer" | "short" | "byte" | "double" | "float" | "half_float" | "scaled_float" | "unsigned_long" | "date" | "date_nanos" | "boolean" | "ip" | "nested" | "object" | "geo_point";
 export interface TqlCompletionItem {
     label: string;
     insertText: string;

package/dist/src/validator.d.ts

@@ -29,22 +29,18 @@ export declare const ALL_FIELD_TYPES: TqlFieldType[];
  */
 export declare const NUMERIC_FIELD_TYPES: TqlFieldType[];
 /**
- * The types an ORDERED comparison (`gt`/`gte`/`lt`/`lte`) is defined over.
+ * The types an ORDERED comparison (`gt`/`gte`/`lt`/`lte`) is defined over: numeric, date and
+ * ip — exactly `ORDERABLE_FIELD_TYPES` in `./ordering` (`date_nanos` joined this union in
+ * tql#302, so a `date_nanos` field's completion menu offers them).
  *
- * Numeric and date, plus `keyword`: both evaluators fall back to a lexicographic string
- * comparison when neither side reads as a number, and Python's own validator lists all four
- * operators in its `keyword_ops`. `text` is excluded on that same source's reasoning — a
- * range over an analyzed field compares tokens, not the value the user typed.
+ * `keyword` used to be here, because both evaluators fell back to a lexicographic string
+ * comparison. That fallback is what made `os.version gte "10"` match Windows 7, and every
+ * engine now refuses it (tql#302); `validate()` reports it as `UNORDERABLE_FIELD`.
  */
 export declare const ORDERED_FIELD_TYPES: TqlFieldType[];
 /**
- * The types `between` / `not_between` are defined over.
- *
- * `ORDERED_FIELD_TYPES` minus `keyword`. The four ordered operators and `between` are NOT
- * the same set, and the difference is Python's, not this package's: `keyword_ops` in
- * `_validate_simple_type_compatibility` lists `gt`/`gte`/`lt`/`lte` and excludes `between`.
- * `tests/collectionAndNullSemantics.spec.ts` pins that exclusion against the Python source,
- * so this constant self-retires if Python ever adds it.
+ * The types `between` / `not_between` are defined over: the same set as the four ordered
+ * operators since tql#302 (they differed only by `keyword`, which neither allows now).
  */
 export declare const BETWEEN_FIELD_TYPES: TqlFieldType[];
 /**
@@ -220,6 +216,12 @@ export declare class TqlValidator {
     /**
      * Suggest a similar field name using Levenshtein distance
      */
+    /**
+     * Report an ordering comparator with no meaningful order as `UNORDERABLE_FIELD`. Returns
+     * whether it did. A field with mutators (`f | length gt 5`) is judged by its literal, as the
+     * engines judge it.
+     */
+    private validateOrdering;
     private suggestField;
     /**
      * Calculate Levenshtein distance between two strings

package/dist/src/validator.js

@@ -1,5 +1,6 @@
-import { parseTql as p } from "./parser.js";
-const g = 1e3, r = [
+import { isOrderingOperator as h, checkOrderingComparison as b, orderingVerdict as m, orderingRefusalMessage as v } from "./ordering.js";
+import { parseTql as E } from "./parser.js";
+const _ = 1e3, r = [
   "text",
   "keyword",
   "long",
@@ -12,12 +13,13 @@ const g = 1e3, r = [
   "scaled_float",
   "unsigned_long",
   "date",
+  "date_nanos",
   "boolean",
   "ip",
   "nested",
   "object",
   "geo_point"
-], _ = [
+], k = [
   "long",
   "integer",
   "short",
@@ -27,7 +29,7 @@ const g = 1e3, r = [
   "half_float",
   "scaled_float",
   "unsigned_long"
-], l = [..._, "date", "keyword"], u = [..._, "date"], b = {
+], d = [...k, "date", "date_nanos", "ip"], g = d, T = {
   // Equality (all types) — and now that is what it says.
   //
   // The transcribed twelve-element list this replaces claimed "all types" while omitting
@@ -39,29 +41,21 @@ const g = 1e3, r = [
   "=": r,
   "!=": r,
   eq_ci: ["text", "keyword"],
-  // Ordered comparison — numeric, date, AND keyword.
+  // Ordered comparison — numeric, date and ip (tql#302). These rows no longer produce the
+  // soft warning: `validateOrdering` reports every ordering comparator on another type as the
+  // `UNORDERABLE_FIELD` ERROR the engines' refusal deserves. They stay here because the
+  // completion menu is checked against this table (completionOperatorTableParity.spec.ts).
   //
-  // `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
+  // Every numeric width is listed via 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,
+  gt: d,
+  gte: d,
+  lt: d,
+  lte: d,
+  ">": d,
+  ">=": d,
+  "<": d,
+  "<=": d,
   // String operations
   //
   // ## The `_cs` operators list `text`, and that is deliberate — the rule lives in the caller
@@ -147,19 +141,12 @@ const g = 1e3, r = [
   matches: ["text", "keyword"],
   not_matches: ["text", "keyword"],
   "!matches": ["text", "keyword"],
-  // 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: u,
-  not_between: u,
-  "!between": u,
+  // Range. Numeric, date and ip, via the named constant — the same set as the four ordered
+  // operators since tql#302; on any other type `validateOrdering` reports the engines'
+  // refusal as an ERROR, and these rows never warn.
+  between: g,
+  not_between: g,
+  "!between": g,
   // 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`.
@@ -226,11 +213,11 @@ const g = 1e3, r = [
   "!any": r,
   "!all": r,
   "!none": r
-}, h = {
+}, f = {
   cidr: ["ip"],
   not_cidr: ["ip"],
   "!cidr": ["ip"]
-}, m = [
+}, A = [
   "contains_cs",
   "not_contains_cs",
   "!contains_cs",
@@ -240,25 +227,25 @@ const g = 1e3, r = [
   "endswith_cs",
   "not_endswith_cs",
   "!endswith_cs"
-], f = [
+], w = [
   "in_cs",
   "not_in_cs",
   "!in_cs"
-], v = [
-  ...m,
-  ...f
+], $ = [
+  ...A,
+  ...w
 ];
-function c(o, t) {
+function u(o, t) {
   const e = t?.[o];
   return e === void 0 ? [] : Array.isArray(e) ? e : [e];
 }
-function E(o, t) {
+function R(o, t) {
   if (!t)
     return "unknown";
-  const e = c(o, t);
+  const e = u(o, t);
   if (e.length === 0)
     return "unknown";
-  if (e.includes("keyword") || c(`${o}.keyword`, t).includes("keyword"))
+  if (e.includes("keyword") || u(`${o}.keyword`, t).includes("keyword"))
     return "present";
   const i = `${o}.`;
   for (const [n, s] of Object.entries(t))
@@ -266,18 +253,18 @@ function E(o, t) {
       return "present";
   return "absent";
 }
-function k(o, t, e) {
-  if (!v.includes(t))
+function I(o, t, e) {
+  if (!$.includes(t))
     return "supported";
-  const i = E(o, e);
+  const i = R(o, e);
   if (i !== "absent")
     return i === "present" ? "supported" : "unknown";
-  if (!f.includes(t))
+  if (!w.includes(t))
     return "unsupported";
-  const n = c(o, e);
+  const n = u(o, e);
   return n.length > 0 && n.every((s) => s === "text") ? "unsupported" : "supported";
 }
-const T = {
+const S = {
   eq: ["string", "number", "boolean"],
   ne: ["string", "number", "boolean"],
   "=": ["string", "number", "boolean"],
@@ -346,7 +333,7 @@ const T = {
   "!all": ["string", "number", "boolean"],
   "!none": ["string", "number", "boolean"]
 };
-class A {
+class O {
   options;
   errors;
   warnings;
@@ -359,7 +346,7 @@ class A {
   validate(t) {
     if (this.errors = [], this.warnings = [], !t)
       return { valid: !0, errors: [], warnings: [] };
-    const e = p(t);
+    const e = E(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,
@@ -477,7 +464,7 @@ class A {
    */
   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(
+    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,
@@ -485,25 +472,27 @@ class A {
       1,
       "UNKNOWN_FIELD",
       `Did you mean: ${this.suggestField(e)}`
-    ), this.options.fieldTypes && t.field.type === "field") {
-      const n = c(e, this.options.fieldTypes), s = n.join(" or ");
-      if (n.length > 0) {
-        const a = h[t.operator];
-        a && !n.some((d) => a.includes(d)) && this.addError(
-          `Operator '${t.operator}' requires field type ${a.join(" or ")}, but '${e}' is type '${s}'`,
+    );
+    const i = this.validateOrdering(t);
+    if (this.options.fieldTypes && t.field.type === "field") {
+      const s = u(e, this.options.fieldTypes), a = s.join(" or ");
+      if (s.length > 0) {
+        const l = f[t.operator];
+        l && !s.some((c) => l.includes(c)) && this.addError(
+          `Operator '${t.operator}' requires field type ${l.join(" or ")}, but '${e}' is type '${a}'`,
           t.start,
           t.end,
           1,
           1,
           "TYPE_MISMATCH",
-          `Use '${t.operator}' only with ${a.join(" or ")} fields`
+          `Use '${t.operator}' only with ${l.join(" or ")} fields`
         );
       }
     }
-    let i = !1;
-    if (t.field.type === "field" && k(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`;
+    let n = !1;
+    if (t.field.type === "field" && I(e, t.operator, this.options.fieldTypes) === "unsupported") {
+      n = !0;
+      const s = t.operator.replace(/_cs$/, ""), a = this.options.fieldTypes?.[e], l = a === "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 '${a}' 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 —
@@ -512,34 +501,34 @@ class A {
         // 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.`,
+        `${l}. 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}'.`
+        a === "text" ? `Use the case-insensitive '${s}', or query a keyword subfield (\`${e}.keyword\`) if the index has one this schema does not list.` : `Use the case-insensitive '${s}', or compare '${e}' with an operator suited to '${a}'.`
       );
     }
     if (this.options.fieldTypes && t.field.type === "field") {
-      const n = c(e, this.options.fieldTypes), s = n.join(" or ");
-      if (n.length > 0) {
-        const a = b[t.operator], d = h[t.operator];
-        !i && !d && a && !n.some((y) => a.includes(y)) && this.addWarning(
-          `Operator '${t.operator}' may not work well with field type '${s}'`,
+      const s = u(e, this.options.fieldTypes), a = s.join(" or ");
+      if (s.length > 0) {
+        const l = T[t.operator], c = f[t.operator];
+        !n && !i && !h(t.operator) && !c && l && !s.some((p) => l.includes(p)) && this.addWarning(
+          `Operator '${t.operator}' may not work well with field type '${a}'`,
           t.start,
           t.end,
           1,
           1,
           "TYPE_MISMATCH",
-          `Consider using a different operator for ${s} fields`
+          `Consider using a different operator for ${a} fields`
         );
       }
     }
     if (!Array.isArray(t.value) && t.value.type === "literal") {
-      const n = T[t.operator];
-      n && !n.includes(t.value.valueType) && this.addWarning(
-        `Operator '${t.operator}' expects ${n.join(" or ")} value`,
+      const s = S[t.operator];
+      s && !s.includes(t.value.valueType) && this.addWarning(
+        `Operator '${t.operator}' expects ${s.join(" or ")} value`,
         t.value.start,
         t.value.end,
         1,
@@ -548,10 +537,10 @@ class A {
       );
     }
     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 > g)
+      const s = Array.from(t.value.value).length;
+      if (s > _)
         this.addError(
-          `Regex pattern is ${n} characters, which exceeds the maximum supported length of ${g}. The query cannot run as written.`,
+          `Regex pattern is ${s} characters, which exceeds the maximum supported length of ${_}. The query cannot run as written.`,
           t.value.start,
           t.value.end,
           1,
@@ -578,6 +567,36 @@ class A {
   /**
    * Suggest a similar field name using Levenshtein distance
    */
+  /**
+   * Report an ordering comparator with no meaningful order as `UNORDERABLE_FIELD`. Returns
+   * whether it did. A field with mutators (`f | length gt 5`) is judged by its literal, as the
+   * engines judge it.
+   */
+  validateOrdering(t) {
+    if (!h(t.operator)) return !1;
+    let e = t.field, i = !1;
+    for (; e.type === "mutator"; )
+      i = !0, e = e.field;
+    ((e.mutators?.length ?? 0) > 0 || (e.mutatorCalls?.length ?? 0) > 0) && (i = !0);
+    const n = b({
+      field: e.name,
+      operator: t.operator,
+      value: t.value,
+      verdict: m(e.name, this.options.fieldTypes),
+      typeHint: e.typeHint,
+      hasFieldMutators: i
+    });
+    return n === null ? !1 : (this.addError(
+      v(n),
+      t.start,
+      t.end,
+      1,
+      1,
+      "UNORDERABLE_FIELD",
+      n.literal === void 0 ? `Compare '${n.field}' with eq/ne/in, or order on a numeric, date or ip field (a version has numeric parts such as os.version_build).` : "Use a number, a date or an ip address, or compare with eq/ne/in.",
+      n
+    ), !0);
+  }
   suggestField(t) {
     if (!this.options.availableFields || this.options.availableFields.length === 0)
       return "check available fields";
@@ -606,7 +625,7 @@ class A {
         );
     return i[e.length][t.length];
   }
-  addError(t, e, i, n, s, a, d) {
+  addError(t, e, i, n, s, a, l, c) {
     this.errors.push({
       message: t,
       start: e,
@@ -615,10 +634,11 @@ class A {
       column: s,
       severity: "error",
       code: a,
-      suggestion: d
+      suggestion: l,
+      ...c ? { ordering: c } : {}
     });
   }
-  addWarning(t, e, i, n, s, a, d) {
+  addWarning(t, e, i, n, s, a, l) {
     this.warnings.push({
       message: t,
       start: e,
@@ -627,21 +647,21 @@ class A {
       column: s,
       severity: "warning",
       code: a,
-      suggestion: d
+      suggestion: l
     });
   }
 }
-function w(o, t) {
-  return new A(t).validate(o);
+function y(o, t) {
+  return new O(t).validate(o);
 }
-function I(o) {
-  return w(o).valid;
+function x(o) {
+  return y(o).valid;
 }
-function S(o, t) {
-  const e = w(o, t);
+function C(o, t) {
+  const e = y(o, t);
   return [...e.errors, ...e.warnings];
 }
-function R(o) {
+function M(o) {
   const t = [];
   o.valid ? t.push("Query is valid") : t.push("Query has errors:");
   for (const e of o.errors)
@@ -653,18 +673,18 @@ function R(o) {
 }
 export {
   r as ALL_FIELD_TYPES,
-  u as BETWEEN_FIELD_TYPES,
-  f as CASE_SENSITIVE_MEMBERSHIP_OPERATORS,
-  v as CASE_SENSITIVE_OPERATORS,
-  m as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
-  g as MAX_REGEX_PATTERN_LENGTH,
-  _ as NUMERIC_FIELD_TYPES,
-  l as ORDERED_FIELD_TYPES,
-  A as TqlValidator,
-  E as casePreservingForm,
-  k as caseSensitiveSupport,
-  R as formatValidationResult,
-  S as getTqlIssues,
-  I as isValidTqlSyntax,
-  w as validateTql
+  g as BETWEEN_FIELD_TYPES,
+  w as CASE_SENSITIVE_MEMBERSHIP_OPERATORS,
+  $ as CASE_SENSITIVE_OPERATORS,
+  A as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
+  _ as MAX_REGEX_PATTERN_LENGTH,
+  k as NUMERIC_FIELD_TYPES,
+  d as ORDERED_FIELD_TYPES,
+  O as TqlValidator,
+  R as casePreservingForm,
+  I as caseSensitiveSupport,
+  M as formatValidationResult,
+  C as getTqlIssues,
+  x as isValidTqlSyntax,
+  y as validateTql
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellaro/tql",
-  "version": "4.0.2",
+  "version": "5.0.0",
   "description": "Tellaro Query Language (TQL) parser, validator, and autocomplete for JavaScript/TypeScript",
   "type": "module",
   "main": "./dist/index.js",