@tellaro/tql 3.0.2 → 3.1.0

package/dist/index.js

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

package/dist/src/index.d.ts

@@ -17,3 +17,4 @@ export { ComplexityAnalyzer, analyzeComplexity, isHighComplexity, getComplexityW
 export { SemanticPreview, generatePreview, getFieldUsage, getLogicTree, getUniqueFields, getOperatorSummary, formatLogicTreeNode, formatLogicTreeAscii, flattenLogicTree, getLogicTreeDepth } from './semanticPreview';
 export { buildStatsQuery, parseVizHintString, type StatsQueryConfig, type AggregationConfig, type GroupByConfig, type VizHintConfig } from './builder';
 export type { ComplexityScore, ComplexityWarning, ComplexityWarningType, ComplexityMetrics, ComplexityResult, ComplexityThresholds, MatchType, FieldUsage, LogicTreeNodeType, LogicTreeNode, PreviewResult, QueryHistoryEntry, UseQueryHistoryOptions } from './types';
+export { QUERY_PLAN_EXPLAIN_VERSION, QUERY_PLAN_RULES, QUERY_PLAN_EXPLAIN_KEYS, summarizeQueryPlan, type QueryPlanExplain, type QueryPlanRewrite, type QueryPlanNotApplied, type QueryPlanRule, type QueryPlanMode, type QueryPlanLimit } from './queryPlan';

package/dist/src/queryPlan.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The OpenSearch query planner's explain document, as produced by the Rust
+ * crate (`QueryBuilder::explain`, `tql --explain-opensearch`) and the Python
+ * package (`TQL.explain_plan`, `OpenSearchBackend.explain`).
+ *
+ * This package builds no OpenSearch DSL itself; it ships the shape so UIs that
+ * render a plan (the backend returns it verbatim) are typed against the same
+ * contract the engines are tested against. The shape is versioned by
+ * `explain_version`; `tests/queryPlanParity.spec.ts` reads the engines' version
+ * constants, rule registries and the shared fixture, so this file goes red when
+ * they move. Design: `docs/developer/query-planner.md`.
+ */
+/** The `explain_version` this package's types describe. */
+export declare const QUERY_PLAN_EXPLAIN_VERSION = 1;
+/** Every rule a `rewrites` record can name, in pipeline order. */
+export declare const QUERY_PLAN_RULES: readonly ["flatten", "double_negation", "constant_fold", "dedupe", "absorption", "factor_common", "or_wildcard_to_regexp", "or_term_to_terms"];
+export type QueryPlanRule = (typeof QUERY_PLAN_RULES)[number];
+export type QueryPlanMode = "off" | "logical" | "full";
+/** The keys of an explain document, in the order the engines emit them. */
+export declare const QUERY_PLAN_EXPLAIN_KEYS: readonly ["explain_version", "planner_version", "mode", "query", "options", "normalized", "optimized", "rewrites", "not_applied", "changed", "original_dsl", "optimized_dsl"];
+export interface QueryPlanLimit {
+    setting: "index.max_regex_length" | "index.max_terms_count";
+    value: number;
+}
+/** One applied rewrite. `before`/`after` are rendered logical forms. */
+export interface QueryPlanRewrite {
+    phase: "normalize" | "logical" | "physical";
+    rule: QueryPlanRule;
+    /** Child indices from the root, joined by `.`; the root is `""`. */
+    path: string;
+    before: string;
+    after: string;
+    /** Rule-specific facts: merged clauses, chunk count and the limit behind it, skipped members. */
+    detail?: {
+        context?: "should" | "must_not";
+        field?: string;
+        shape?: "contains" | "endswith" | "equals" | "startswith";
+        case_insensitive?: boolean;
+        members?: number;
+        literals?: number;
+        values?: number;
+        chunks?: number;
+        limit?: QueryPlanLimit;
+        chunk_lengths?: Array<number | null>;
+        skipped?: Array<{
+            member: string;
+            reason: string;
+        }>;
+        clauses?: Array<Record<string, unknown>>;
+        removed?: string[];
+        [key: string]: unknown;
+    };
+}
+/** A merge the planner considered and left alone, and why. */
+export interface QueryPlanNotApplied {
+    rule: QueryPlanRule;
+    path: string;
+    context: "should" | "must_not";
+    field: string;
+    members: number;
+    reason: string;
+    shape?: string;
+    case_insensitive?: boolean;
+    skipped?: Array<{
+        member: string;
+        reason: string;
+    }>;
+}
+export interface QueryPlanExplain {
+    explain_version: number;
+    planner_version: number;
+    mode: QueryPlanMode;
+    query: string | null;
+    options: {
+        max_regex_length: number;
+        max_terms_count: number;
+    };
+    normalized: string;
+    optimized: string;
+    rewrites: QueryPlanRewrite[];
+    not_applied: QueryPlanNotApplied[];
+    /** False exactly when `rewrites` is empty and `optimized_dsl` is the original. */
+    changed: boolean;
+    original_dsl: Record<string, unknown>;
+    optimized_dsl: Record<string, unknown>;
+}
+/** One line per rewrite, for a compact summary: `rule @ path: before -> after`. */
+export declare function summarizeQueryPlan(plan: QueryPlanExplain): string[];

package/dist/src/queryPlan.js

@@ -0,0 +1,34 @@
+const o = 1, n = [
+  "flatten",
+  "double_negation",
+  "constant_fold",
+  "dedupe",
+  "absorption",
+  "factor_common",
+  "or_wildcard_to_regexp",
+  "or_term_to_terms"
+], r = [
+  "explain_version",
+  "planner_version",
+  "mode",
+  "query",
+  "options",
+  "normalized",
+  "optimized",
+  "rewrites",
+  "not_applied",
+  "changed",
+  "original_dsl",
+  "optimized_dsl"
+];
+function i(t) {
+  return t.changed ? t.rewrites.map(
+    (e) => `${e.rule}${e.path ? ` @ ${e.path}` : ""}: ${e.before} -> ${e.after}`
+  ) : ["no rewrites: the query is sent as translated"];
+}
+export {
+  r as QUERY_PLAN_EXPLAIN_KEYS,
+  o as QUERY_PLAN_EXPLAIN_VERSION,
+  n as QUERY_PLAN_RULES,
+  i as summarizeQueryPlan
+};

package/package.json

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