@tellaro/tql 1.3.8 → 1.4.0

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

@@ -0,0 +1,849 @@
+/**
+ * TQL Chart Data Mappers
+ *
+ * Pure functions that transform TQL stats results into Chart.js data/options.
+ * Supports 20+ viz_params for professional-grade chart customization.
+ *
+ * No Chart.js import needed — outputs plain objects matching Chart.js interfaces.
+ */
+/** TQL stats result shape from the evaluator */
+export interface TqlStatsResult {
+    stats: Record<string, unknown>;
+    total?: number;
+    took?: number;
+    viz_hint?: string;
+    viz_params?: Record<string, unknown>;
+}
+/** Extracted data from a grouped aggregation */
+export interface GroupedData {
+    labels: string[];
+    values: number[];
+    colors?: string[];
+    multiValues?: Record<string, number[]>;
+}
+/** Drilldown event payload emitted on chart click */
+export interface DrilldownEvent {
+    label: string;
+    value: number;
+    index: number;
+    field?: string;
+    chartType: string;
+}
+/** Check if the group-by field looks like a timestamp */
+export declare function isTimeSeriesData(stats: Record<string, unknown>): boolean;
+/**
+ * Normalize OpenSearch aggregation response into the results array format.
+ * Handles both flat and nested (multi-group-by) aggregations.
+ * OpenSearch returns: { group_by_field: { buckets: [{key, doc_count}, ...] } }
+ * We normalize to: { results: [{key, doc_count}, ...] }
+ */
+export declare function normalizeOpenSearchAggs(stats: Record<string, unknown>): Record<string, unknown>;
+/** Extract labels and values from a TQL grouped stats result */
+export declare function extractGroupedData(stats: Record<string, unknown>): GroupedData;
+/** Extract a single scalar value from a stats result.
+ *  For scalar results (no group by): returns the value directly.
+ *  For grouped results (buckets): sums all bucket values as a total.
+ */
+export declare function extractScalarValue(stats: Record<string, unknown>): number;
+/** Parse "key:#hex,key2:#hex" or preset name into a color map */
+export declare function parseColorMap(colorStr: string | undefined): Record<string, string> | null;
+/**
+ * Apply all viz_param filters to grouped data:
+ * - include/exclude value filtering
+ * - top N with Other bucket
+ * - sort order
+ * - normalize to 100%
+ * - color mapping
+ */
+export declare function applyVizFilters(data: GroupedData, vizParams?: Record<string, unknown>): GroupedData;
+/** Expand a template URL: "https://example.com/{{value}}" with context */
+export declare function expandLinkTemplate(template: string, ctx: {
+    value: string;
+    label: string;
+    field?: string;
+    count?: number;
+}): string;
+/** Validate a URL template is safe (no javascript:, data:, etc.) */
+export declare function isLinkTemplateSafe(template: string): boolean;
+/** Build Chart.js data for bar charts */
+export declare function barChartData(result: TqlStatsResult): {
+    labels: string[];
+    datasets: unknown[];
+};
+/** Build Chart.js data for line/area charts */
+export declare function lineChartData(result: TqlStatsResult, fill?: boolean, smooth?: boolean): {
+    labels: string[];
+    datasets: {
+        label: string;
+        data: number[];
+        borderColor: string;
+        backgroundColor: string;
+        fill: boolean;
+        tension: number;
+        pointRadius: number;
+        pointHoverRadius: number;
+        pointBackgroundColor: string;
+        pointBorderColor: string;
+        pointBorderWidth: number;
+        borderWidth: number;
+        spanGaps: boolean;
+    }[];
+} | {
+    labels: string[];
+    datasets: {
+        data: number[];
+        borderColor: string;
+        backgroundColor: string;
+        fill: boolean;
+        tension: number;
+        pointRadius: number;
+        pointHoverRadius: number;
+        pointBackgroundColor: string;
+        pointBorderColor: string;
+        pointBorderWidth: number;
+        borderWidth: number;
+        spanGaps: boolean;
+    }[];
+};
+/** Build Chart.js data for pie/donut charts */
+export declare function pieChartData(result: TqlStatsResult): {
+    labels: string[];
+    datasets: {
+        label: string;
+        data: number[];
+        backgroundColor: string[];
+        borderColor: string;
+        borderWidth: number;
+        hoverBorderColor: string;
+        hoverBorderWidth: number;
+        hoverOffset: number;
+    }[];
+} | {
+    labels: string[];
+    datasets: {
+        data: number[];
+        backgroundColor: string[];
+        borderColor: string;
+        borderWidth: number;
+        hoverBorderColor: string;
+        hoverBorderWidth: number;
+        hoverOffset: number;
+    }[];
+};
+/** Build Chart.js options for bar charts */
+export declare function barChartOptions(vizParams?: Record<string, unknown>, multiSeries?: boolean): {
+    responsive: boolean;
+    maintainAspectRatio: boolean;
+    indexAxis: "y" | "x";
+    animation: {
+        duration: number;
+        easing: "easeOutQuart";
+    };
+    layout: {
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    interaction: {
+        mode: "index" | "nearest";
+        intersect: boolean;
+    };
+    plugins: {
+        legend: {
+            display: boolean;
+            labels: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                usePointStyle: boolean;
+                pointStyleWidth: number;
+                filter: ((item: {
+                    text?: string;
+                }) => boolean) | undefined;
+            };
+        };
+        title: {
+            display: boolean;
+            text: string;
+            color: string;
+            font: {
+                size: number;
+                weight: "600";
+            };
+            padding: {
+                top: number;
+                bottom: number;
+            };
+        };
+        tooltip: {
+            enabled: boolean;
+            mode: "index" | "nearest";
+            intersect: boolean;
+            backgroundColor: string;
+            titleColor: string;
+            bodyColor: string;
+            borderColor: string;
+            borderWidth: number;
+            cornerRadius: number;
+            padding: number;
+            titleFont: {
+                size: number;
+                weight: "600";
+            };
+            bodyFont: {
+                size: number;
+            };
+            displayColors: boolean;
+            boxPadding: number;
+            callbacks: {
+                title: (items: Array<{
+                    label: string;
+                }>) => string;
+                label: (ctx: {
+                    dataset: {
+                        label?: string;
+                    };
+                    parsed: {
+                        y: number;
+                        x: number;
+                    };
+                    formattedValue: string;
+                }) => string;
+            };
+        };
+        datalabels: {
+            display: boolean;
+            color?: undefined;
+            font?: undefined;
+            anchor?: undefined;
+            align?: undefined;
+            offset?: undefined;
+            formatter?: undefined;
+        } | {
+            display: string | boolean;
+            color: string;
+            font: {
+                size: number;
+                weight: "500";
+            };
+            anchor: "end";
+            align: "top";
+            offset: number;
+            formatter: ((value: number) => string) | undefined;
+        };
+    };
+    scales: {
+        x: {
+            stacked: boolean;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    top: number;
+                };
+            };
+            ticks: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                maxRotation: number;
+                autoSkip: boolean;
+                maxTicksLimit: number;
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+                drawTicks: boolean;
+            };
+            border: {
+                color: string;
+            };
+        };
+        y: {
+            stacked: boolean;
+            beginAtZero: boolean;
+            min: number | undefined;
+            max: number | undefined;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    bottom: number;
+                };
+            };
+            ticks: {
+                stepSize?: number | undefined;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+            };
+            border: {
+                display: boolean;
+            };
+        };
+    };
+};
+/** Build Chart.js options for line/area charts */
+export declare function lineChartOptions(vizParams?: Record<string, unknown>, multiSeries?: boolean): {
+    responsive: boolean;
+    maintainAspectRatio: boolean;
+    indexAxis: "y" | "x";
+    animation: {
+        duration: number;
+        easing: "easeOutQuart";
+    };
+    layout: {
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    interaction: {
+        mode: "index" | "nearest";
+        intersect: boolean;
+    };
+    plugins: {
+        legend: {
+            display: boolean;
+            labels: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                usePointStyle: boolean;
+                pointStyleWidth: number;
+                filter: ((item: {
+                    text?: string;
+                }) => boolean) | undefined;
+            };
+        };
+        title: {
+            display: boolean;
+            text: string;
+            color: string;
+            font: {
+                size: number;
+                weight: "600";
+            };
+            padding: {
+                top: number;
+                bottom: number;
+            };
+        };
+        tooltip: {
+            enabled: boolean;
+            mode: "index" | "nearest";
+            intersect: boolean;
+            backgroundColor: string;
+            titleColor: string;
+            bodyColor: string;
+            borderColor: string;
+            borderWidth: number;
+            cornerRadius: number;
+            padding: number;
+            titleFont: {
+                size: number;
+                weight: "600";
+            };
+            bodyFont: {
+                size: number;
+            };
+            displayColors: boolean;
+            boxPadding: number;
+            callbacks: {
+                title: (items: Array<{
+                    label: string;
+                }>) => string;
+                label: (ctx: {
+                    dataset: {
+                        label?: string;
+                    };
+                    parsed: {
+                        y: number;
+                        x: number;
+                    };
+                    formattedValue: string;
+                }) => string;
+            };
+        };
+        datalabels: {
+            display: boolean;
+            color?: undefined;
+            font?: undefined;
+            anchor?: undefined;
+            align?: undefined;
+            offset?: undefined;
+            formatter?: undefined;
+        } | {
+            display: string | boolean;
+            color: string;
+            font: {
+                size: number;
+                weight: "500";
+            };
+            anchor: "end";
+            align: "top";
+            offset: number;
+            formatter: ((value: number) => string) | undefined;
+        };
+    };
+    scales: {
+        x: {
+            stacked: boolean;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    top: number;
+                };
+            };
+            ticks: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                maxRotation: number;
+                autoSkip: boolean;
+                maxTicksLimit: number;
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+                drawTicks: boolean;
+            };
+            border: {
+                color: string;
+            };
+        };
+        y: {
+            stacked: boolean;
+            beginAtZero: boolean;
+            min: number | undefined;
+            max: number | undefined;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    bottom: number;
+                };
+            };
+            ticks: {
+                stepSize?: number | undefined;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+            };
+            border: {
+                display: boolean;
+            };
+        };
+    };
+};
+/** Build Chart.js options for pie/donut charts */
+export declare function pieChartOptions(vizParams?: Record<string, unknown>, donut?: boolean, multiLevel?: boolean): {
+    responsive: boolean;
+    maintainAspectRatio: boolean;
+    animation: {
+        duration: number;
+        easing: "easeOutQuart";
+    };
+    cutout: string | number;
+    layout: {
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    plugins: {
+        legend: {
+            display: boolean;
+            position: "top" | "bottom" | "left" | "right";
+            labels: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                usePointStyle: boolean;
+                pointStyleWidth: number;
+                boxHeight: number;
+            };
+        };
+        title: {
+            display: boolean;
+            text: string;
+            color: string;
+            font: {
+                size: number;
+                weight: "600";
+            };
+            padding: {
+                top: number;
+                bottom: number;
+            };
+        };
+        tooltip: {
+            callbacks: {
+                title: () => string;
+                label: (ctx: {
+                    label: string;
+                    parsed: number;
+                }) => string;
+            };
+            enabled: boolean;
+            mode: "index" | "nearest";
+            intersect: boolean;
+            backgroundColor: string;
+            titleColor: string;
+            bodyColor: string;
+            borderColor: string;
+            borderWidth: number;
+            cornerRadius: number;
+            padding: number;
+            titleFont: {
+                size: number;
+                weight: "600";
+            };
+            bodyFont: {
+                size: number;
+            };
+            displayColors: boolean;
+            boxPadding: number;
+        };
+        datalabels: {
+            display: boolean;
+            color?: undefined;
+            font?: undefined;
+            anchor?: undefined;
+            align?: undefined;
+            offset?: undefined;
+            formatter?: undefined;
+        } | {
+            display: string | boolean;
+            color: string;
+            font: {
+                size: number;
+                weight: "500";
+            };
+            anchor: "end";
+            align: "top";
+            offset: number;
+            formatter: ((value: number) => string) | undefined;
+        };
+    };
+};
+/** Map TQL viz type to Chart.js type string */
+export declare function chartJsType(tqlType: string): string;
+/** Build Chart.js data for any chart type */
+export declare function buildChartData(result: TqlStatsResult, chartType: string): {
+    labels: string[];
+    datasets: unknown[];
+};
+/** Build Chart.js options for any chart type */
+export declare function buildChartOptions(result: TqlStatsResult, chartType: string): {
+    responsive: boolean;
+    maintainAspectRatio: boolean;
+    indexAxis: "y" | "x";
+    animation: {
+        duration: number;
+        easing: "easeOutQuart";
+    };
+    layout: {
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    interaction: {
+        mode: "index" | "nearest";
+        intersect: boolean;
+    };
+    plugins: {
+        legend: {
+            display: boolean;
+            labels: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                usePointStyle: boolean;
+                pointStyleWidth: number;
+                filter: ((item: {
+                    text?: string;
+                }) => boolean) | undefined;
+            };
+        };
+        title: {
+            display: boolean;
+            text: string;
+            color: string;
+            font: {
+                size: number;
+                weight: "600";
+            };
+            padding: {
+                top: number;
+                bottom: number;
+            };
+        };
+        tooltip: {
+            enabled: boolean;
+            mode: "index" | "nearest";
+            intersect: boolean;
+            backgroundColor: string;
+            titleColor: string;
+            bodyColor: string;
+            borderColor: string;
+            borderWidth: number;
+            cornerRadius: number;
+            padding: number;
+            titleFont: {
+                size: number;
+                weight: "600";
+            };
+            bodyFont: {
+                size: number;
+            };
+            displayColors: boolean;
+            boxPadding: number;
+            callbacks: {
+                title: (items: Array<{
+                    label: string;
+                }>) => string;
+                label: (ctx: {
+                    dataset: {
+                        label?: string;
+                    };
+                    parsed: {
+                        y: number;
+                        x: number;
+                    };
+                    formattedValue: string;
+                }) => string;
+            };
+        };
+        datalabels: {
+            display: boolean;
+            color?: undefined;
+            font?: undefined;
+            anchor?: undefined;
+            align?: undefined;
+            offset?: undefined;
+            formatter?: undefined;
+        } | {
+            display: string | boolean;
+            color: string;
+            font: {
+                size: number;
+                weight: "500";
+            };
+            anchor: "end";
+            align: "top";
+            offset: number;
+            formatter: ((value: number) => string) | undefined;
+        };
+    };
+    scales: {
+        x: {
+            stacked: boolean;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    top: number;
+                };
+            };
+            ticks: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                maxRotation: number;
+                autoSkip: boolean;
+                maxTicksLimit: number;
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+                drawTicks: boolean;
+            };
+            border: {
+                color: string;
+            };
+        };
+        y: {
+            stacked: boolean;
+            beginAtZero: boolean;
+            min: number | undefined;
+            max: number | undefined;
+            title: {
+                display: boolean;
+                text: string;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: {
+                    bottom: number;
+                };
+            };
+            ticks: {
+                stepSize?: number | undefined;
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                callback: ((value: number | string) => string) | undefined;
+            };
+            grid: {
+                color: string;
+            };
+            border: {
+                display: boolean;
+            };
+        };
+    };
+} | {
+    responsive: boolean;
+    maintainAspectRatio: boolean;
+    animation: {
+        duration: number;
+        easing: "easeOutQuart";
+    };
+    cutout: string | number;
+    layout: {
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    plugins: {
+        legend: {
+            display: boolean;
+            position: "top" | "bottom" | "left" | "right";
+            labels: {
+                color: string;
+                font: {
+                    size: number;
+                };
+                padding: number;
+                usePointStyle: boolean;
+                pointStyleWidth: number;
+                boxHeight: number;
+            };
+        };
+        title: {
+            display: boolean;
+            text: string;
+            color: string;
+            font: {
+                size: number;
+                weight: "600";
+            };
+            padding: {
+                top: number;
+                bottom: number;
+            };
+        };
+        tooltip: {
+            callbacks: {
+                title: () => string;
+                label: (ctx: {
+                    label: string;
+                    parsed: number;
+                }) => string;
+            };
+            enabled: boolean;
+            mode: "index" | "nearest";
+            intersect: boolean;
+            backgroundColor: string;
+            titleColor: string;
+            bodyColor: string;
+            borderColor: string;
+            borderWidth: number;
+            cornerRadius: number;
+            padding: number;
+            titleFont: {
+                size: number;
+                weight: "600";
+            };
+            bodyFont: {
+                size: number;
+            };
+            displayColors: boolean;
+            boxPadding: number;
+        };
+        datalabels: {
+            display: boolean;
+            color?: undefined;
+            font?: undefined;
+            anchor?: undefined;
+            align?: undefined;
+            offset?: undefined;
+            formatter?: undefined;
+        } | {
+            display: string | boolean;
+            color: string;
+            font: {
+                size: number;
+                weight: "500";
+            };
+            anchor: "end";
+            align: "top";
+            offset: number;
+            formatter: ((value: number) => string) | undefined;
+        };
+    };
+};