@tellaro/tql 1.3.8 → 1.4.1

package/dist/src/builder.d.ts

@@ -0,0 +1,62 @@
+import { TqlAggregationFunction, TqlVisualizationType, TqlVizParams } from './types';
+/**
+ * Configuration for building a stats query.
+ */
+export interface StatsQueryConfig {
+    /** Optional TQL filter expression (prepended before | stats) */
+    filter?: string;
+    /** Aggregation functions to apply */
+    aggregations: AggregationConfig[];
+    /** Fields to group results by */
+    groupBy?: GroupByConfig[];
+    /** Visualization hint */
+    vizHint?: VizHintConfig;
+}
+/**
+ * Single aggregation function configuration.
+ */
+export interface AggregationConfig {
+    /** Aggregation function name */
+    function: TqlAggregationFunction;
+    /** Field to aggregate (omit or use "*" for count(*)) */
+    field?: string;
+    /** Alias for the result (e.g., "total_events") */
+    alias?: string;
+}
+/**
+ * Group-by field configuration.
+ */
+export interface GroupByConfig {
+    /** Field name to group by */
+    field: string;
+    /** Optional top N limit */
+    topN?: number;
+}
+/**
+ * Visualization hint configuration.
+ */
+export interface VizHintConfig {
+    /** Chart type */
+    type: TqlVisualizationType;
+    /** Optional visualization parameters */
+    params?: TqlVizParams;
+}
+/**
+ * Build a TQL stats query string from structured configuration.
+ *
+ * @example
+ * ```ts
+ * buildStatsQuery({
+ *   aggregations: [{ function: "count" }],
+ *   groupBy: [{ field: "status" }],
+ *   vizHint: { type: "bar", params: { title: "Events by Status" } }
+ * })
+ * // => '| stats count(*) by status => bar(title="Events by Status")'
+ * ```
+ */
+export declare function buildStatsQuery(config: StatsQueryConfig): string;
+/**
+ * Parse a TQL viz hint string (e.g., "bar" or 'bar(title="Events")') into a VizHintConfig.
+ * This is a lightweight parser for the viz_hint portion only.
+ */
+export declare function parseVizHintString(vizStr: string): VizHintConfig | null;

package/dist/src/builder.js

@@ -0,0 +1,56 @@
+function p(e) {
+  const i = [];
+  if (e.filter?.trim() && i.push(e.filter.trim()), i.push("| stats"), !e.aggregations || e.aggregations.length === 0)
+    throw new Error("At least one aggregation is required");
+  const a = e.aggregations.map((r) => {
+    const t = r.field && r.field !== "*" ? r.field : "*";
+    let s = `${r.function}(${t})`;
+    return r.alias && (s += ` as ${r.alias}`), s;
+  });
+  if (i.push(a.join(", ")), e.groupBy && e.groupBy.length > 0) {
+    const r = e.groupBy.map((t) => {
+      let s = t.field;
+      return t.topN !== void 0 && t.topN > 0 && (s += ` top ${t.topN}`), s;
+    });
+    i.push("by " + r.join(", "));
+  }
+  if (e.vizHint) {
+    let r = `=> ${e.vizHint.type}`;
+    if (e.vizHint.params) {
+      const t = Object.entries(e.vizHint.params).filter(
+        ([, s]) => s !== void 0
+      );
+      if (t.length > 0) {
+        const s = t.map(([n, u]) => typeof u == "string" ? `${n}="${u}"` : `${n}=${u}`);
+        r += `(${s.join(", ")})`;
+      }
+    }
+    i.push(r);
+  }
+  return i.join(" ");
+}
+function m(e) {
+  if (!e || !e.trim()) return null;
+  const i = e.trim(), a = i.indexOf("(");
+  if (a === -1)
+    return { type: i };
+  const r = i.substring(0, a).trim(), t = i.substring(a + 1, i.lastIndexOf(")"));
+  if (!t.trim())
+    return { type: r };
+  const s = {};
+  let n = "", u = !1, l = "";
+  for (const o of t)
+    (o === '"' || o === "'") && !u ? (u = !0, l = o, n += o) : o === l && u ? (u = !1, n += o) : o === "," && !u ? (f(n.trim(), s), n = "") : n += o;
+  return n.trim() && f(n.trim(), s), { type: r, params: Object.keys(s).length > 0 ? s : void 0 };
+}
+function f(e, i) {
+  const a = e.indexOf("=");
+  if (a === -1) return;
+  const r = e.substring(0, a).trim();
+  let t = e.substring(a + 1).trim();
+  t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'") ? t = t.slice(1, -1) : t.toLowerCase() === "true" ? t = !0 : t.toLowerCase() === "false" ? t = !1 : !isNaN(Number(t)) && t !== "" && (t = Number(t)), i[r] = t;
+}
+export {
+  p as buildStatsQuery,
+  m as parseVizHintString
+};

package/dist/src/chart/colors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TQL Chart Color System
+ *
+ * Named palettes, severity presets, and color utilities.
+ */
+/** Default palette — high-contrast colors for dark backgrounds */
+export declare const PALETTE: readonly ["#818cf8", "#34d399", "#f472b6", "#fbbf24", "#60a5fa", "#a78bfa", "#fb923c", "#2dd4bf", "#f87171", "#a3e635", "#e879f9", "#38bdf8", "#c084fc", "#4ade80", "#facc15", "#fb7185"];
+/** All named palettes */
+export declare const PALETTES: Record<string, readonly string[]>;
+export type PaletteName = keyof typeof PALETTES;
+/**
+ * Severity-specific colors — colorblind-safe palette.
+ * Keyed by label string (case-insensitive matching in resolveColors).
+ * These are hardcoded to specific severity values, not positional.
+ * Red-orange-yellowgreen-blue avoids the red-green confusion in deuteranopia.
+ */
+export declare const SEVERITY: Record<string, string>;
+/** Get color at index from a named palette */
+export declare function colorAt(index: number, palette?: PaletteName): string;
+/** Generate N colors from a named palette */
+export declare function colorArray(count: number, palette?: PaletteName): string[];
+/** Generate N colors with 20% opacity for fills */
+export declare function fillColorArray(count: number, palette?: PaletteName): string[];

package/dist/src/chart/colors.js

@@ -0,0 +1,101 @@
+const c = [
+  "#818cf8",
+  "#34d399",
+  "#f472b6",
+  "#fbbf24",
+  "#60a5fa",
+  "#a78bfa",
+  "#fb923c",
+  "#2dd4bf",
+  "#f87171",
+  "#a3e635",
+  "#e879f9",
+  "#38bdf8",
+  "#c084fc",
+  "#4ade80",
+  "#facc15",
+  "#fb7185"
+], d = [
+  "#ef4444",
+  "#f97316",
+  "#f59e0b",
+  "#eab308",
+  "#fb923c",
+  "#fbbf24",
+  "#f87171",
+  "#fb7185",
+  "#e11d48",
+  "#dc2626",
+  "#ea580c",
+  "#d97706"
+], t = [
+  "#3b82f6",
+  "#6366f1",
+  "#8b5cf6",
+  "#06b6d4",
+  "#14b8a6",
+  "#22c55e",
+  "#60a5fa",
+  "#818cf8",
+  "#a78bfa",
+  "#2dd4bf",
+  "#34d399",
+  "#4ade80"
+], o = [
+  "#ef4444",
+  "#f97316",
+  "#fbbf24",
+  "#a3e635",
+  "#22c55e",
+  "#14b8a6",
+  "#06b6d4",
+  "#3b82f6",
+  "#6366f1",
+  "#8b5cf6"
+], n = [
+  "#dbeafe",
+  "#bfdbfe",
+  "#93c5fd",
+  "#60a5fa",
+  "#3b82f6",
+  "#2563eb",
+  "#1d4ed8",
+  "#1e40af",
+  "#1e3a8a",
+  "#172554"
+], r = {
+  default: c,
+  warm: d,
+  cool: t,
+  diverging: o,
+  sequential: n
+}, u = {
+  critical: "#dc2626",
+  // red-600 — clearly red even in protanopia
+  high: "#ea580c",
+  // orange-600 — distinct from red in all forms
+  medium: "#ca8a04",
+  // yellow-700 — darker yellow, visible on dark/light backgrounds
+  low: "#2563eb",
+  // blue-600 — completely safe, never confused with red/orange
+  informational: "#6b7280"
+  // grey-500 — neutral, non-alert
+};
+function l(f, a = "default") {
+  const e = r[a] || c;
+  return e[f % e.length];
+}
+function i(f, a = "default") {
+  return Array.from({ length: f }, (e, b) => l(b, a));
+}
+function s(f, a = "default") {
+  return i(f, a).map((e) => e + "33");
+}
+export {
+  c as PALETTE,
+  r as PALETTES,
+  u as SEVERITY,
+  i as colorArray,
+  l as colorAt,
+  s as fillColorArray
+};

package/dist/src/chart/formatters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TQL Chart Number Formatters
+ *
+ * Format numbers for axis ticks, tooltips, and data labels.
+ * Supports: number, percent, bytes, duration, short (1.2K, 3.4M).
+ */
+/** Format a number based on the format type */
+export declare function formatValue(value: number, format?: string): string;
+/** Create a Chart.js tick callback for the given format */
+export declare function tickFormatter(format?: string): ((value: number | string) => string) | undefined;
+/** Create a Chart.js tooltip label callback for the given format */
+export declare function tooltipFormatter(format?: string): ((ctx: {
+    parsed: {
+        y: number;
+    };
+    label: string;
+}) => string) | undefined;

package/dist/src/chart/formatters.js

@@ -0,0 +1,49 @@
+function s(r, t) {
+  if (!t || t === "number") return r.toLocaleString();
+  switch (t) {
+    case "short":
+      return u(r);
+    case "percent":
+      return (Number.isInteger(r * 100) ? String(Math.round(r * 100)) : (r * 100).toFixed(1)) + "%";
+    case "percent_raw":
+      return (Number.isInteger(r) ? String(Math.round(r)) : r.toFixed(1)) + "%";
+    case "bytes":
+      return c(r);
+    case "duration":
+      return f(r);
+    default:
+      return r.toLocaleString();
+  }
+}
+function u(r) {
+  const t = Math.abs(r), e = r < 0 ? "-" : "";
+  return t >= 1e9 ? e + (t / 1e9).toFixed(1) + "B" : t >= 1e6 ? e + (t / 1e6).toFixed(1) + "M" : t >= 1e3 ? e + (t / 1e3).toFixed(1) + "K" : Number.isInteger(r) ? r.toLocaleString() : r.toFixed(2);
+}
+function c(r) {
+  const t = Math.abs(r), e = r < 0 ? "-" : "";
+  return t >= 1073741824 ? e + (t / 1073741824).toFixed(1) + " GB" : t >= 1048576 ? e + (t / 1048576).toFixed(1) + " MB" : t >= 1024 ? e + (t / 1024).toFixed(1) + " KB" : e + t + " B";
+}
+function f(r) {
+  const t = Math.abs(r);
+  if (t < 1e3) return t.toFixed(0) + "ms";
+  if (t < 6e4) return (t / 1e3).toFixed(1) + "s";
+  if (t < 36e5) {
+    const o = Math.floor(t / 6e4), i = Math.round(t % 6e4 / 1e3);
+    return i > 0 ? `${o}m ${i}s` : `${o}m`;
+  }
+  const e = Math.floor(t / 36e5), n = Math.round(t % 36e5 / 6e4);
+  return n > 0 ? `${e}h ${n}m` : `${e}h`;
+}
+function d(r) {
+  if (r)
+    return (t) => s(Number(t), r);
+}
+function a(r) {
+  if (r)
+    return (t) => `${t.label}: ${s(t.parsed.y, r)}`;
+}
+export {
+  s as formatValue,
+  d as tickFormatter,
+  a as tooltipFormatter
+};

package/dist/src/chart/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @tellaro/tql/chart
+ *
+ * Chart data mappers, formatters, and configuration builders for TQL stats visualizations.
+ * Pure functions — no Chart.js dependency at the module level.
+ */
+export { PALETTE, PALETTES, SEVERITY, type PaletteName, colorAt, colorArray, fillColorArray, } from './colors';
+export { formatValue, tickFormatter, tooltipFormatter, } from './formatters';
+export { type TqlStatsResult, type GroupedData, type DrilldownEvent, normalizeOpenSearchAggs, extractGroupedData, extractScalarValue, isTimeSeriesData, parseColorMap, applyVizFilters, expandLinkTemplate, isLinkTemplateSafe, barChartData, lineChartData, pieChartData, barChartOptions, lineChartOptions, pieChartOptions, chartJsType, buildChartData, buildChartOptions, } from './mappers';

package/dist/src/chart/index.js

@@ -0,0 +1,31 @@
+import { PALETTE as t, PALETTES as e, SEVERITY as o, colorArray as i, colorAt as p, fillColorArray as l } from "./colors.js";
+import { formatValue as s, tickFormatter as h, tooltipFormatter as m } from "./formatters.js";
+import { applyVizFilters as T, barChartData as c, barChartOptions as f, buildChartData as x, buildChartOptions as A, chartJsType as D, expandLinkTemplate as E, extractGroupedData as S, extractScalarValue as u, isLinkTemplateSafe as O, isTimeSeriesData as b, lineChartData as d, lineChartOptions as y, normalizeOpenSearchAggs as L, parseColorMap as V, pieChartData as k, pieChartOptions as F } from "./mappers.js";
+export {
+  t as PALETTE,
+  e as PALETTES,
+  o as SEVERITY,
+  T as applyVizFilters,
+  c as barChartData,
+  f as barChartOptions,
+  x as buildChartData,
+  A as buildChartOptions,
+  D as chartJsType,
+  i as colorArray,
+  p as colorAt,
+  E as expandLinkTemplate,
+  S as extractGroupedData,
+  u as extractScalarValue,
+  l as fillColorArray,
+  s as formatValue,
+  O as isLinkTemplateSafe,
+  b as isTimeSeriesData,
+  d as lineChartData,
+  y as lineChartOptions,
+  L as normalizeOpenSearchAggs,
+  V as parseColorMap,
+  k as pieChartData,
+  F as pieChartOptions,
+  h as tickFormatter,
+  m as tooltipFormatter
+};