@tellaro/tql 3.2.0 → 4.0.0

package/dist/src/completionProvider.d.ts

@@ -1,8 +1,19 @@
+import { GROUP_BY_BUCKET_FUNCTIONS } from './tokenizer';
 import { TqlCompletionContext, TqlCompletionItem, TqlCompletionOptions } from './types';
 /**
  * Get completions for a TQL query at the cursor position
  */
 export declare function getCompletions(context: TqlCompletionContext, options?: TqlCompletionOptions): TqlCompletionItem[];
+/**
+ * Group-by bucket function completions, offered after `by`.
+ *
+ * Insert text uses `$1`-style placeholders like the aggregation completions. Details name the
+ * argument forms both engines accept (see `GROUP_BY_BUCKET_FUNCTIONS` in `tokenizer.ts`).
+ */
+export declare const BUCKET_FUNCTION_DETAILS: Record<(typeof GROUP_BY_BUCKET_FUNCTIONS)[number], {
+    insertText: string;
+    detail: string;
+}>;
 /**
  * Get the word at the cursor position
  */

package/dist/src/completionProvider.js

@@ -1,8 +1,8 @@
-import { BOOLEAN_PREDICATE_MUTATORS as L, tokenizeTql as T, COMPARISON_OPERATORS as E, LOGICAL_OPERATORS as R, AGGREGATION_FUNCTIONS as P, VISUALIZATION_TYPES as $, TYPE_HINTS as D, MUTATORS as M } from "./tokenizer.js";
-import { fuzzyMatch as _ } from "./fuzzyMatcher.js";
-import { getSchemaCache as S } from "./schemaCache.js";
+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 { 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";
-const z = [
+const F = [
   {
     label: "Simple equality",
     insertText: 'field eq "value"',
@@ -105,7 +105,7 @@ const z = [
     description: "Top 10 results by count",
     category: "Stats"
   }
-], U = {
+], G = {
   eq: { detail: "Equals", documentation: "Exact match comparison" },
   ne: { detail: "Not equals", documentation: "Match any value except this one" },
   gt: {
@@ -176,7 +176,7 @@ const z = [
   not_any: { detail: "Not any matches", documentation: "Negation of any" },
   not_all: { detail: "Not all match", documentation: "Negation of all" },
   not_none: { detail: "Not none match", documentation: "Negation of none" }
-}, F = {
+}, B = {
   lowercase: { detail: "Convert to lowercase", documentation: "Transform string to lowercase" },
   uppercase: { detail: "Convert to uppercase", documentation: "Transform string to uppercase" },
   trim: { detail: "Trim whitespace", documentation: "Remove leading/trailing whitespace" },
@@ -237,7 +237,7 @@ const z = [
   // There is exactly one JS copy, in `tokenizer.ts`, pinned against both engines by
   // `tests/booleanPredicateSugar.spec.ts`.
   ...Object.fromEntries(
-    L.map((e) => [e, "boolean"])
+    E.map((e) => [e, "boolean"])
   ),
   // `any` and `all` are collection OPERATORS rather than predicates — absent from both
   // engines' predicate sets, and not eligible for the `field | <name>` filter sugar — so
@@ -257,7 +257,7 @@ const z = [
   geo: "object",
   // Array output (returns array of strings)
   split: "keyword"
-}, G = {
+}, q = {
   // Equality and membership — every field type, by NAME rather than by a transcribed list.
   eq: u,
   ne: u,
@@ -319,7 +319,7 @@ const z = [
   not_all: u,
   not_none: u
 };
-class B {
+class Y {
   cache = /* @__PURE__ */ new Map();
   maxSize = 50;
   maxAge = 5e3;
@@ -341,16 +341,16 @@ class B {
     this.cache.clear();
   }
 }
-const k = new B();
+const k = new Y();
 function V(e, t, i) {
   if (!e) return { type: "start", partialText: "" };
-  const o = S().get(i)?.hash ?? "-", n = `${e.substring(0, t)}|${t}|${o}`, a = k.get(n);
+  const o = I().get(i)?.hash ?? "-", n = `${e.substring(0, t)}|${t}|${o}`, a = k.get(n);
   if (a)
     return a.fieldName && !a.fieldType && i && (a.fieldType = h(a.fieldName, i)), a;
-  const s = Y(e, t, i);
+  const s = H(e, t, i);
   return k.set(n, s), s;
 }
-function Y(e, t, i) {
+function H(e, t, i) {
   const n = T(e.substring(0, t)).filter((l) => l.type !== "whitespace");
   if (n.length === 0)
     return { type: "start" };
@@ -461,14 +461,14 @@ function Y(e, t, i) {
   return { type: "unknown", partialText: d };
 }
 function h(e, t) {
-  return t ? S().getFieldType(t, e) : void 0;
+  return t ? I().getFieldType(t, e) : void 0;
 }
-function ie(e, t = {}) {
+function le(e, t = {}) {
   const { query: i, cursorPosition: o } = e, n = V(i, o, t.fields), a = [];
   switch (n.type) {
     case "start":
     case "after_paren":
-      a.push(...x(t.fields, n.partialText)), a.push(I("NOT")), t.includeSnippets !== !1 && a.push(...K(t, n.partialText));
+      a.push(...x(t.fields, n.partialText)), a.push(L("NOT")), t.includeSnippets !== !1 && a.push(...Z(t, n.partialText));
       break;
     case "after_field":
       a.push(...b(n.partialText, n.fieldType));
@@ -477,7 +477,7 @@ function ie(e, t = {}) {
       a.push(...b(n.partialText, n.mutatorOutputType));
       break;
     case "after_operator":
-      a.push(...j(n.fieldName, t));
+      a.push(...W(n.fieldName, t));
       break;
     case "after_value":
       a.push(...C());
@@ -485,7 +485,7 @@ function ie(e, t = {}) {
     case "at_value_end":
       break;
     case "after_pipe":
-      a.push(...W(n.partialText)), (!n.partialText || "stats".includes(n.partialText.toLowerCase())) && a.push({
+      a.push(...X(n.partialText)), (!n.partialText || "stats".includes(n.partialText.toLowerCase())) && a.push({
         label: "stats",
         insertText: "stats ",
         kind: "keyword",
@@ -522,27 +522,33 @@ function ie(e, t = {}) {
         kind: "keyword",
         detail: "Add another group-by field",
         sortOrder: 2
+      }), a.push({
+        label: "with other",
+        insertText: "with other ",
+        kind: "keyword",
+        detail: `Add an "Other" row for what the level's limit dropped (last group-by level only)`,
+        sortOrder: 3
       });
       break;
     case "after_double_colon":
-      a.push(...Z(n.partialText));
+      a.push(...Q(n.partialText));
       break;
     case "after_arrow":
-      a.push(...X(n.partialText));
+      a.push(...ee(n.partialText));
       break;
     case "in_viz_params":
-      a.push(...Q(n.partialText));
+      a.push(...ae(n.partialText));
       break;
     case "after_stats":
-      a.push(...O(n.partialText));
+      a.push(...A(n.partialText));
       break;
     case "after_by":
-      a.push(...x(t.fields, n.partialText));
+      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());
   }
-  t.includeAggregations && n.type === "start" && a.push(...O(n.partialText));
+  t.includeAggregations && n.type === "start" && a.push(...A(n.partialText));
   let s = a;
   const c = t.fuzzyMatching !== !1, d = t.minFuzzyScore ?? 0;
   if (n.partialText) {
@@ -550,7 +556,7 @@ function ie(e, t = {}) {
     if (c) {
       const r = [];
       for (const m of a) {
-        const p = _(l, m.label), v = m.filterText ? _(l, m.filterText) : { matched: !1, score: 0 }, y = p.score >= v.score ? p : v;
+        const p = v(l, m.label), _ = m.filterText ? v(l, m.filterText) : { matched: !1, score: 0 }, y = p.score >= _.score ? p : _;
         y.matched && y.score >= d && r.push({
           ...m,
           matchScore: y.score,
@@ -567,7 +573,7 @@ function ie(e, t = {}) {
 }
 function x(e, t) {
   if (!e || e.length === 0)
-    return q(t);
+    return j(t);
   const i = [];
   for (const o of e) {
     const n = N(o);
@@ -579,7 +585,7 @@ function x(e, t) {
   }
   return i;
 }
-function q(e) {
+function j(e) {
   return [
     { name: "hostname", description: "Host/machine name" },
     { name: "status", description: "Status value" },
@@ -618,12 +624,12 @@ function N(e, t) {
   };
 }
 function b(e, t) {
-  let i = [...E];
+  let i = [...R];
   return t && (i = i.filter((o) => {
-    const n = G[o];
+    const n = q[o];
     return !n || n.includes(t);
   })), e && (i = i.filter((o) => o.toLowerCase().includes(e.toLowerCase()))), i.map((o, n) => {
-    const a = U[o] || { detail: o, documentation: "" }, s = H(o, t);
+    const a = G[o] || { detail: o, documentation: "" }, s = K(o, t);
     return {
       label: o,
       insertText: s,
@@ -634,7 +640,7 @@ function b(e, t) {
     };
   });
 }
-function H(e, t) {
+function K(e, t) {
   const i = [
     "contains",
     "not_contains",
@@ -650,9 +656,9 @@ function H(e, t) {
     "not_matches"
   ], o = ["exists", "not_exists"], n = ["is", "is_not"];
   if (e === "in" || e === "not_in")
-    return A(t) ? `${e} [$1]` : `${e} ["$1"]`;
+    return O(t) ? `${e} [$1]` : `${e} ["$1"]`;
   if (e === "between" || e === "not_between")
-    return A(t) ? `${e} $1 AND $2` : `${e} "$1" AND "$2"`;
+    return O(t) ? `${e} $1 AND $2` : `${e} "$1" AND "$2"`;
   if (n.includes(e))
     return `${e} null`;
   if (o.includes(e))
@@ -686,15 +692,15 @@ function H(e, t) {
       return `${e} `;
   }
 }
-function A(e) {
+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 R.filter((e) => e !== "NOT").map(
-    (e, t) => I(e, t)
+  return $.filter((e) => e !== "NOT").map(
+    (e, t) => L(e, t)
   );
 }
-function I(e, t = 0) {
+function L(e, t = 0) {
   return {
     label: e,
     insertText: e + " ",
@@ -703,7 +709,7 @@ function I(e, t = 0) {
     sortOrder: 30 + t
   };
 }
-function j(e, t) {
+function W(e, t) {
   const i = [];
   return e && t?.fieldValues?.[e] && t.fieldValues[e].forEach((n, a) => {
     i.push({
@@ -744,8 +750,8 @@ function j(e, t) {
     }
   ), i;
 }
-function K(e, t) {
-  return z.filter((o) => !t || o.label.toLowerCase().includes(t.toLowerCase())).map((o, n) => ({
+function Z(e, t) {
+  return F.filter((o) => !t || o.label.toLowerCase().includes(t.toLowerCase())).map((o, n) => ({
     label: o.label,
     insertText: o.insertText,
     kind: "snippet",
@@ -754,10 +760,10 @@ function K(e, t) {
     sortOrder: 100 + n
   }));
 }
-function W(e) {
-  return M.filter((t) => !e || t.toLowerCase().includes(e.toLowerCase())).map(
+function X(e) {
+  return U.filter((t) => !e || t.toLowerCase().includes(e.toLowerCase())).map(
     (t, i) => {
-      const o = F[t] || { detail: "Field mutator", documentation: "" };
+      const o = B[t] || { detail: "Field mutator", documentation: "" };
       return {
         label: t,
         insertText: t,
@@ -769,8 +775,8 @@ function W(e) {
     }
   );
 }
-function O(e) {
-  return P.filter(
+function A(e) {
+  return D.filter(
     (t) => !e || t.toLowerCase().includes(e.toLowerCase())
   ).map((t, i) => ({
     label: t,
@@ -780,8 +786,41 @@ function O(e) {
     sortOrder: 70 + i
   }));
 }
-function Z(e) {
-  return D.filter(
+const S = {
+  date_histogram: {
+    insertText: "date_histogram(${1:@timestamp}, ${2:1h})",
+    detail: "Time buckets: fixed (30s, 5m, 1h, 1d), calendar (minute hour day week month quarter year) or auto / auto(N)"
+  },
+  geotile: {
+    insertText: "geotile(${1:source.geo.location}, ${2:6})",
+    detail: "Map tiles of a geo_point field; precision 0-29 (default 7)"
+  },
+  geohash: {
+    insertText: "geohash(${1:source.geo.location}, ${2:4})",
+    detail: "Geohash cells of a geo_point field; precision 1-12 (default 5)"
+  },
+  range: {
+    insertText: "range(${1:network.bytes}, ${2:0, 1024, 65536})",
+    detail: "Numeric ranges from increasing boundaries: *-b1, b1-b2, ..., bn-*"
+  },
+  filters: {
+    insertText: "filters(${1:log.level eq 'error'} as '${2:Errors}', ${3:log.level eq 'info'} as '${4:Info}')",
+    detail: "One bucket per filter expression, labelled with `as`"
+  }
+};
+function J(e) {
+  return P.filter(
+    (t) => !e || t.includes(e.toLowerCase())
+  ).map((t, i) => ({
+    label: t,
+    insertText: S[t].insertText,
+    kind: "aggregation",
+    detail: S[t].detail,
+    sortOrder: 60 + i
+  }));
+}
+function Q(e) {
+  return z.filter(
     (t) => !e || t.toLowerCase().includes(e.toLowerCase())
   ).map((t, i) => ({
     label: t,
@@ -791,8 +830,8 @@ function Z(e) {
     sortOrder: 80 + i
   }));
 }
-function X(e) {
-  return $.filter(
+function ee(e) {
+  return M.filter(
     (t) => !e || t.toLowerCase().includes(e.toLowerCase())
   ).map((t, i) => ({
     label: t,
@@ -802,7 +841,7 @@ function X(e) {
     sortOrder: 90 + i
   }));
 }
-const J = [
+const te = [
   // Titles & labels
   { name: "title", detail: "Chart title", insertText: 'title="' },
   { name: "x_label", detail: "X-axis label", insertText: 'x_label="' },
@@ -838,8 +877,8 @@ const J = [
   { name: "link", detail: 'Template URL for value links: "https://...{{value}}"', insertText: 'link="' },
   { name: "link_target", detail: "Link target: _self (default) or _blank", insertText: "link_target=" }
 ];
-function Q(e) {
-  return J.filter(
+function ae(e) {
+  return te.filter(
     (t) => !e || t.name.toLowerCase().includes(e.toLowerCase())
   ).map((t, i) => ({
     label: t.name,
@@ -849,7 +888,7 @@ function Q(e) {
     sortOrder: 95 + i
   }));
 }
-function re(e, t) {
+function se(e, t) {
   const o = T(e).find(
     (n) => n.start <= t && n.end >= t && n.type !== "whitespace"
   );
@@ -859,18 +898,19 @@ function re(e, t) {
     end: o.end
   } : null;
 }
-function oe() {
+function de() {
   return [" ", "(", ".", '"', "'", "|", ":", "="];
 }
-function le(e, t, i) {
+function ce(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];
   return !!(n && n.type === "field" && n.value.length >= 2);
 }
 export {
-  oe as getCompletionTriggerCharacters,
-  ie as getCompletions,
-  re as getWordAtPosition,
-  le as shouldTriggerCompletion
+  S as BUCKET_FUNCTION_DETAILS,
+  de as getCompletionTriggerCharacters,
+  le as getCompletions,
+  se as getWordAtPosition,
+  ce as shouldTriggerCompletion
 };

package/dist/src/index.d.ts

@@ -6,9 +6,9 @@
  *
  * @packageDocumentation
  */
-export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, 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 { 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, TYPE_HINTS, VISUALIZATION_TYPES, KEYWORDS } from './tokenizer';
-export { TqlParser, parseTql, isValidTql, getTqlErrors, formatParseError } from './parser';
+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 { 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 { getCompletions, getWordAtPosition, getCompletionTriggerCharacters, shouldTriggerCompletion } from './completionProvider';
 export { fuzzyMatch, levenshteinDistance, findClosestMatch, fuzzyFilter, highlightMatch, type FuzzyMatchResult, type FuzzyMatchOptions } from './fuzzyMatcher';

package/dist/src/parser.d.ts

@@ -14,6 +14,29 @@ import { TqlCollectionOperator, TqlParseError, TqlParseResult } from './types';
  * a query the user can paste back.
  */
 export declare function collectionOperatorSpelling(operator: TqlCollectionOperator, negated: boolean): string;
+/**
+ * The refusal a `date_histogram` interval argument earns, or null — the JS reading of
+ * `parse_date_histogram_interval` in `src/tql/stats_buckets.py` / `tql/src/stats_buckets.rs`.
+ * `raw` is the argument's source text (null when omitted, which is `auto`).
+ */
+export declare function dateHistogramIntervalProblem(raw: string | null): {
+    message: string;
+    suggestion: string;
+} | null;
+/** The refusal a geotile/geohash precision argument earns, or null (see `parse_geo_precision`). */
+export declare function geoPrecisionProblem(kind: "geotile" | "geohash", raw: string | null): {
+    message: string;
+    suggestion: string;
+} | null;
+/**
+ * The refusal `range(...)` boundaries earn, or null (see `parse_range_boundaries`): each must be
+ * a finite number and they must strictly increase. `index` is the offending boundary.
+ */
+export declare function rangeBoundariesProblem(raws: readonly string[]): {
+    message: string;
+    suggestion: string;
+    index: number;
+} | null;
 export declare class TqlParser {
     private tokens;
     private allTokens;
@@ -21,6 +44,7 @@ export declare class TqlParser {
     private errors;
     private warnings;
     private depth;
+    private input;
     constructor(input: string);
     /**
      * Parse the input and return the result
@@ -263,6 +287,18 @@ export declare class TqlParser {
      * from `by top` needs the grammar this method is declining to reimplement.
      */
     private checkStatsModifiers;
+    /**
+     * Flag group-by bucket functions whose ARGUMENTS both engines refuse at parse time.
+     *
+     * Like `checkStatsModifiers`, a targeted scan rather than a stats parser: it reads each
+     * `bucketFunction` call's comma-separated arguments and applies the same argument rules as
+     * `stats_buckets.parse_date_histogram_interval` (Python) / `parse_date_histogram_interval`
+     * (Rust), with the same message text, so the editor reports what the engine will. Shapes the
+     * grammars themselves refuse (a missing field, `top N` on a bucket level) are left to the
+     * engines' ordinary syntax errors. `tests/statsBucketKinds.spec.ts` replays
+     * `validation/stats_bucket_errors.json` against this.
+     */
+    private checkStatsBucketFunctions;
     /**
      * Check if the token stream represents a stats query.
      * Handles: "| stats ...", "stats ...", or starts with a filter before "| stats".