@tellaro/tql 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @tellaro/tql
+ *
+ * Tellaro Query Language (TQL) parser, validator, and autocomplete for JavaScript/TypeScript.
+ * Synchronized with tellaro-query-language Python/Rust implementations.
+ *
+ * @packageDocumentation
+ */
+export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, TqlGroupExpression, TqlLiteral, TqlFieldReference, TqlComparisonOperator, TqlLogicalOperator, TqlCollectionOperator, TqlMutator, TqlAggregationFunction, TqlTypeHint, TqlVisualizationType, TqlParseResult, TqlParseError, TqlParseWarning, TqlErrorCode, TqlWarningCode, TqlValidationResult, TqlValidationOptions, TqlFieldType, 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, AGGREGATION_FUNCTIONS, TYPE_HINTS, VISUALIZATION_TYPES, KEYWORDS } from './tokenizer';
+export { TqlParser, parseTql, isValidTql, getTqlErrors, formatParseError } from './parser';
+export { TqlValidator, validateTql, isValidTqlSyntax, getTqlIssues, formatValidationResult } from './validator';
+export { getCompletions, getWordAtPosition, getCompletionTriggerCharacters, shouldTriggerCompletion } from './completionProvider';

package/dist/src/parser.d.ts

@@ -0,0 +1,81 @@
+import { TqlParseError, TqlParseResult } from './types';
+
+export declare class TqlParser {
+    private tokens;
+    private allTokens;
+    private current;
+    private errors;
+    private warnings;
+    private depth;
+    constructor(input: string);
+    /**
+     * Parse the input and return the result
+     */
+    parse(): TqlParseResult;
+    /**
+     * Parse a full expression (lowest precedence)
+     */
+    private parseExpression;
+    /**
+     * Parse OR expressions
+     */
+    private parseOr;
+    /**
+     * Parse AND expressions
+     */
+    private parseAnd;
+    /**
+     * Parse NOT expressions
+     */
+    private parseUnary;
+    /**
+     * Parse primary expressions (comparisons, groups, literals)
+     */
+    private parsePrimary;
+    /**
+     * Parse a grouped expression
+     */
+    private parseGroup;
+    /**
+     * Parse a comparison expression (field [::type] [| mutator]* operator value)
+     * Supports:
+     * - Optional type hint: field::string eq "value"
+     * - Optional mutator chain: field | lowercase | trim eq "value"
+     */
+    private parseComparison;
+    /**
+     * Parse a value (string, number, boolean, null)
+     */
+    private parseValue;
+    /**
+     * Parse a list of values for 'in' operator
+     */
+    private parseValueList;
+    private createFieldReference;
+    private normalizeOperator;
+    private isAtEnd;
+    private peek;
+    private previous;
+    private advance;
+    private check;
+    private match;
+    private matchLogical;
+    private addError;
+    private addWarning;
+}
+/**
+ * Parse a TQL query string
+ */
+export declare function parseTql(query: string): TqlParseResult;
+/**
+ * Check if a TQL query is syntactically valid
+ */
+export declare function isValidTql(query: string): boolean;
+/**
+ * Get parse errors for a TQL query
+ */
+export declare function getTqlErrors(query: string): TqlParseError[];
+/**
+ * Format a parse error for display
+ */
+export declare function formatParseError(error: TqlParseError): string;

package/dist/src/parser.js

@@ -0,0 +1,511 @@
+var c = Object.defineProperty;
+var p = (r, e, t) => e in r ? c(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
+var o = (r, e, t) => p(r, typeof e != "symbol" ? e + "" : e, t);
+import { tokenizeTql as d, COMPARISON_OPERATORS as v } from "./tokenizer.js";
+const k = 50;
+class f {
+  constructor(e) {
+    o(this, "tokens");
+    o(this, "allTokens");
+    // Including whitespace for highlighting
+    o(this, "current");
+    o(this, "errors");
+    o(this, "warnings");
+    o(this, "depth");
+    this.allTokens = d(e), this.tokens = this.allTokens.filter((t) => t.type !== "whitespace"), this.current = 0, this.errors = [], this.warnings = [], this.depth = 0;
+  }
+  /**
+   * Parse the input and return the result
+   */
+  parse() {
+    if (this.current = 0, this.errors = [], this.warnings = [], this.depth = 0, this.tokens.length === 0)
+      return {
+        ast: null,
+        tokens: this.allTokens,
+        errors: [],
+        warnings: [],
+        success: !0
+      };
+    try {
+      const e = this.parseExpression();
+      if (!this.isAtEnd()) {
+        const t = this.peek();
+        this.addError(
+          `Unexpected token '${t.value}'`,
+          t,
+          "UNEXPECTED_TOKEN",
+          "Check for missing operators or extra characters"
+        );
+      }
+      return {
+        ast: e,
+        tokens: this.allTokens,
+        errors: this.errors,
+        warnings: this.warnings,
+        success: this.errors.length === 0
+      };
+    } catch {
+      return {
+        ast: null,
+        tokens: this.allTokens,
+        errors: this.errors,
+        warnings: this.warnings,
+        success: !1
+      };
+    }
+  }
+  // ============================================================================
+  // Expression Parsing (Precedence: OR < AND < NOT < Comparison)
+  // ============================================================================
+  /**
+   * Parse a full expression (lowest precedence)
+   */
+  parseExpression() {
+    if (this.depth++, this.depth > k)
+      throw new Error("Maximum query depth exceeded");
+    try {
+      return this.parseOr();
+    } finally {
+      this.depth--;
+    }
+  }
+  /**
+   * Parse OR expressions
+   */
+  parseOr() {
+    let e = this.parseAnd();
+    for (; this.matchLogical("OR"); ) {
+      const t = this.parseAnd();
+      e = {
+        type: "binary",
+        operator: "OR",
+        left: e,
+        right: t,
+        start: e.start,
+        end: t.end
+      };
+    }
+    return e;
+  }
+  /**
+   * Parse AND expressions
+   */
+  parseAnd() {
+    let e = this.parseUnary();
+    for (; this.matchLogical("AND"); ) {
+      const t = this.parseUnary();
+      e = {
+        type: "binary",
+        operator: "AND",
+        left: e,
+        right: t,
+        start: e.start,
+        end: t.end
+      };
+    }
+    return e;
+  }
+  /**
+   * Parse NOT expressions
+   */
+  parseUnary() {
+    if (this.matchLogical("NOT")) {
+      const e = this.previous(), t = this.parseUnary();
+      return {
+        type: "unary",
+        operator: "NOT",
+        operand: t,
+        start: e.start,
+        end: t.end
+      };
+    }
+    return this.parsePrimary();
+  }
+  /**
+   * Parse primary expressions (comparisons, groups, literals)
+   */
+  parsePrimary() {
+    if (this.check("paren") && this.peek().value === "(")
+      return this.parseGroup();
+    if (this.check("field") || this.check("aggregation") || this.check("mutator") || this.check("typeHint"))
+      return this.parseComparison();
+    const e = this.peek();
+    if (this.addError(
+      `Expected field name or '(' but found '${e.value}'`,
+      e,
+      "UNEXPECTED_TOKEN",
+      "Start with a field name like 'hostname' or 'status'"
+    ), this.advance(), !this.isAtEnd())
+      return this.parsePrimary();
+    throw new Error("Parser recovery failed");
+  }
+  /**
+   * Parse a grouped expression
+   */
+  parseGroup() {
+    const e = this.advance(), t = this.parseExpression();
+    return !this.check("paren") || this.peek().value !== ")" ? this.addError(
+      "Missing closing parenthesis ')'",
+      this.isAtEnd() ? this.previous() : this.peek(),
+      "UNBALANCED_PARENS",
+      "Add a closing ')' to match the opening '('"
+    ) : this.advance(), {
+      type: "group",
+      expression: t,
+      start: e.start,
+      end: this.previous().end
+    };
+  }
+  /**
+   * Parse a comparison expression (field [::type] [| mutator]* operator value)
+   * Supports:
+   * - Optional type hint: field::string eq "value"
+   * - Optional mutator chain: field | lowercase | trim eq "value"
+   */
+  parseComparison() {
+    const e = this.advance();
+    let t = this.createFieldReference(e);
+    if (this.check("doubleColon"))
+      if (this.advance(), this.check("typeHint") || this.check("field")) {
+        const s = this.advance();
+        t = {
+          ...t,
+          typeHint: s.value.toLowerCase(),
+          end: s.end
+        };
+      } else {
+        const s = this.isAtEnd() ? this.previous() : this.peek();
+        this.addWarning(
+          "Expected type hint after '::'",
+          s,
+          "Valid types: string, int, float, date, bool, array"
+        );
+      }
+    const i = [];
+    for (; this.check("pipe"); )
+      if (this.advance(), this.check("mutator")) {
+        const s = this.advance();
+        i.push(s.value.toLowerCase());
+      } else if (this.check("field")) {
+        const s = this.advance();
+        i.push(s.value.toLowerCase()), this.addWarning(`Unknown mutator '${s.value}'`, s, "Check the mutator name spelling");
+      } else {
+        const s = this.isAtEnd() ? this.previous() : this.peek();
+        this.addError(
+          "Expected mutator name after '|'",
+          s,
+          "MISSING_MUTATOR",
+          "Add a mutator like 'lowercase', 'uppercase', 'trim', etc."
+        );
+        break;
+      }
+    if (i.length > 0 && (t = {
+      ...t,
+      mutators: i,
+      end: this.previous().end
+    }), !this.check("operator")) {
+      const s = this.isAtEnd() ? this.previous() : this.peek(), h = i.length > 0 ? `'${e.value}' with mutator` : `'${e.value}'`;
+      return this.addError(
+        `Expected operator after field ${h}`,
+        s,
+        "MISSING_OPERATOR",
+        "Add an operator like 'eq', 'contains', '==', etc."
+      ), {
+        type: "comparison",
+        field: t,
+        operator: "exists",
+        value: {
+          type: "literal",
+          valueType: "boolean",
+          value: !0,
+          start: t.end,
+          end: t.end
+        },
+        start: t.start,
+        end: t.end
+      };
+    }
+    const n = this.advance(), a = this.normalizeOperator(n.value);
+    if (a === "exists" || a === "not_exists")
+      return {
+        type: "comparison",
+        field: t,
+        operator: a,
+        value: {
+          type: "literal",
+          valueType: "boolean",
+          value: !0,
+          start: n.end,
+          end: n.end
+        },
+        start: t.start,
+        end: n.end
+      };
+    if ((a === "is" || a === "is_not") && this.check("null")) {
+      const s = this.advance();
+      return {
+        type: "comparison",
+        field: t,
+        operator: a,
+        value: {
+          type: "literal",
+          valueType: "null",
+          value: null,
+          start: s.start,
+          end: s.end
+        },
+        start: t.start,
+        end: s.end
+      };
+    }
+    if (a === "in" || a === "not_in") {
+      const s = this.parseValueList();
+      return {
+        type: "comparison",
+        field: t,
+        operator: a,
+        value: s,
+        start: t.start,
+        end: this.previous().end
+      };
+    }
+    if (a === "between" || a === "not_between") {
+      const s = this.parseValue();
+      this.matchLogical("AND") || this.addError(
+        "Expected 'AND' between values in 'between' operator",
+        this.isAtEnd() ? this.previous() : this.peek(),
+        "INVALID_SYNTAX",
+        "Use format: field between value1 AND value2"
+      );
+      const h = this.parseValue();
+      return {
+        type: "comparison",
+        field: t,
+        operator: a,
+        value: [s, h],
+        start: t.start,
+        end: h.end
+      };
+    }
+    if (this.isAtEnd())
+      return this.addError(
+        `Expected a value after operator '${a}'`,
+        n,
+        "MISSING_VALUE",
+        'Add a value like "text", 123, or true'
+      ), {
+        type: "comparison",
+        field: t,
+        operator: a,
+        value: {
+          type: "literal",
+          valueType: "string",
+          value: "",
+          start: n.end,
+          end: n.end
+        },
+        start: t.start,
+        end: n.end
+      };
+    const l = this.parseValue();
+    return {
+      type: "comparison",
+      field: t,
+      operator: a,
+      value: l,
+      start: t.start,
+      end: l.end
+    };
+  }
+  /**
+   * Parse a value (string, number, boolean, null)
+   */
+  parseValue() {
+    if (this.isAtEnd()) {
+      const t = this.previous();
+      return this.addError(
+        "Expected a value",
+        t,
+        "MISSING_VALUE",
+        'Add a value like "text", 123, or true'
+      ), {
+        type: "literal",
+        valueType: "string",
+        value: "",
+        start: t.end,
+        end: t.end
+      };
+    }
+    const e = this.peek();
+    return this.check("string") ? (this.advance(), {
+      type: "literal",
+      valueType: "string",
+      value: e.value,
+      start: e.start,
+      end: e.end
+    }) : this.check("number") ? (this.advance(), {
+      type: "literal",
+      valueType: "number",
+      value: e.value.includes(".") ? parseFloat(e.value) : parseInt(e.value, 10),
+      start: e.start,
+      end: e.end
+    }) : this.check("boolean") ? (this.advance(), {
+      type: "literal",
+      valueType: "boolean",
+      value: e.value.toLowerCase() === "true",
+      start: e.start,
+      end: e.end
+    }) : this.check("null") ? (this.advance(), {
+      type: "literal",
+      valueType: "null",
+      value: null,
+      start: e.start,
+      end: e.end
+    }) : this.check("field") ? (this.advance(), this.addWarning(`Unquoted value '${e.value}' - consider using quotes`, e, "Consider wrapping string values in quotes"), {
+      type: "literal",
+      valueType: "string",
+      value: e.value,
+      start: e.start,
+      end: e.end
+    }) : (this.addError(
+      "Expected a value (string, number, or boolean)",
+      e,
+      "MISSING_VALUE",
+      'Add a value like "text", 123, or true'
+    ), {
+      type: "literal",
+      valueType: "string",
+      value: "",
+      start: e.start,
+      end: e.start
+    });
+  }
+  /**
+   * Parse a list of values for 'in' operator
+   */
+  parseValueList() {
+    const e = [];
+    this.check("bracket") && this.peek().value === "[" ? this.advance() : this.check("paren") && this.peek().value === "(" && this.advance();
+    do {
+      if (this.check("bracket") && this.peek().value === "]" || this.check("paren") && this.peek().value === ")") break;
+      e.push(this.parseValue());
+    } while (this.match("comma"));
+    return this.check("bracket") && this.peek().value === "]" ? this.advance() : this.check("paren") && this.peek().value === ")" && this.advance(), e;
+  }
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+  createFieldReference(e) {
+    return {
+      type: "field",
+      name: e.value,
+      path: e.value.split("."),
+      start: e.start,
+      end: e.end
+    };
+  }
+  normalizeOperator(e) {
+    const t = e.toLowerCase(), i = {
+      "==": "eq",
+      "=": "eq",
+      "!=": "ne",
+      ">": "gt",
+      ">=": "gte",
+      "<": "lt",
+      "<=": "lte"
+    };
+    if (e in i)
+      return i[e];
+    const n = {
+      "!in": "not_in",
+      "!contains": "not_contains",
+      "!startswith": "not_startswith",
+      "!endswith": "not_endswith",
+      "!regexp": "not_regexp",
+      "!matches": "not_matches",
+      "!between": "not_between",
+      "!exists": "not_exists",
+      "!is": "is_not",
+      "!cidr": "not_cidr",
+      "!any": "not_any",
+      "!all": "not_all",
+      "!none": "not_none"
+    };
+    if (t in n)
+      return n[t];
+    const a = {
+      regex: "regexp",
+      starts_with: "startswith",
+      ends_with: "endswith"
+    };
+    return t in a ? a[t] : (v.includes(t), t);
+  }
+  isAtEnd() {
+    return this.current >= this.tokens.length;
+  }
+  peek() {
+    return this.tokens[this.current];
+  }
+  previous() {
+    return this.tokens[this.current - 1];
+  }
+  advance() {
+    return this.isAtEnd() || this.current++, this.previous();
+  }
+  check(e) {
+    return this.isAtEnd() ? !1 : this.peek().type === e;
+  }
+  match(...e) {
+    for (const t of e)
+      if (this.check(t))
+        return this.advance(), !0;
+    return !1;
+  }
+  matchLogical(e) {
+    return this.check("logicalOp") && this.peek().value.toUpperCase() === e ? (this.advance(), !0) : !1;
+  }
+  addError(e, t, i, n) {
+    this.errors.push({
+      message: e,
+      start: t.start,
+      end: t.end,
+      line: t.line,
+      column: t.column,
+      severity: "error",
+      code: i,
+      suggestion: n
+    });
+  }
+  addWarning(e, t, i) {
+    this.warnings.push({
+      message: e,
+      start: t.start,
+      end: t.end,
+      line: t.line,
+      column: t.column,
+      severity: "warning",
+      code: "TYPE_MISMATCH",
+      suggestion: i
+    });
+  }
+}
+function u(r) {
+  return new f(r).parse();
+}
+function g(r) {
+  return u(r).success;
+}
+function E(r) {
+  return u(r).errors;
+}
+function w(r) {
+  let e = `Error at line ${r.line}, column ${r.column}: ${r.message}`;
+  return r.suggestion && (e += ` (${r.suggestion})`), e;
+}
+export {
+  f as TqlParser,
+  w as formatParseError,
+  E as getTqlErrors,
+  g as isValidTql,
+  u as parseTql
+};