@camunda/ccma-shared-types 4.0.0 → 6.0.0

package/dist/charts/chart-metrics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/charts/chart-metrics.ts"],
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport type { SearchFieldSpec } from '../search/fields.js'\nimport type { ChartGrain, ChartUnit } from './chart-spec.js'\n\n// ============================================================================\n// The metric catalogue of the chart tiles, without SQL.\n//\n// The frontend reads it for autocomplete, help and validation as you type.\n// accounts-backend pairs each entry with its SQL (`hdp-data.charts.controller`),\n// and a test there makes sure that the two have the same ids.\n// ============================================================================\n\nexport interface ChartDimensionSpec {\n  /** As typed after `by`. */\n  id: string\n  label: string\n  description: string\n}\n\nexport interface ChartMetricSpec {\n  /** As typed at the start of a query. */\n  id: string\n  label: string\n  description: string\n  unit: ChartUnit\n  dimensions: readonly ChartDimensionSpec[]\n  /** The fields that `where` can use. */\n  filters: readonly SearchFieldSpec[]\n  grains: readonly ChartGrain[]\n  /** The longest window, in days. */\n  maxWindowDays: number\n  /**\n   * How one number comes from a chart, for the `stat` render: first over the\n   * series of a bucket, then over the buckets of the window. A counter sums\n   * both. A gauge must not: a sum of daily load percentages means nothing.\n   */\n  stat: { series: 'sum' | 'mean'; window: 'sum' | 'max' | 'mean' }\n}\n\nconst CLUSTER_DIMENSION: ChartDimensionSpec = {\n  id: 'cluster',\n  label: 'Cluster',\n  description: 'The cluster id.',\n}\n\nconst ORG_DIMENSION: ChartDimensionSpec = {\n  id: 'org',\n  label: 'Organization',\n  description: 'The organization id.',\n}\n\n/**\n * The name of the organization of the cluster. It comes from the clusters\n * table of HDP, which holds the prod clusters only, so on another stage every\n * series is `(unknown)`.\n */\nconst ORG_NAME_DIMENSION: ChartDimensionSpec = {\n  id: 'orgName',\n  label: 'Organization name',\n  description:\n    'The name of the organization of the cluster. Prod clusters only: on other stages it is (unknown).',\n}\n\nconst ORG_ID_FILTER: SearchFieldSpec = {\n  field: 'orgId',\n  label: 'Organization id',\n  description: 'Exact organization id.',\n  type: 'string',\n  capabilities: ['match'],\n  example: 'orgId:3f2c\u2026',\n}\n\nconst CLUSTER_ID_FILTER: SearchFieldSpec = {\n  field: 'clusterId',\n  label: 'Cluster id',\n  description: 'Exact cluster id.',\n  type: 'string',\n  capabilities: ['match'],\n  example: 'clusterId:9a1b\u2026',\n}\n\nconst VALUE_METRIC_DIMENSIONS: readonly ChartDimensionSpec[] = [\n  CLUSTER_DIMENSION,\n  ORG_DIMENSION,\n  ORG_NAME_DIMENSION,\n  {\n    id: 'salesPlan',\n    label: 'Sales plan',\n    description: 'The sales plan of the organization on that day.',\n  },\n  {\n    id: 'env',\n    label: 'Environment',\n    description: 'Production or development cluster.',\n  },\n]\n\nconst VALUE_METRIC_FILTERS: readonly SearchFieldSpec[] = [\n  ORG_ID_FILTER,\n  CLUSTER_ID_FILTER,\n  {\n    field: 'salesPlan',\n    label: 'Sales plan',\n    description: 'Sales plan name, case-insensitive. Use * as a wildcard.',\n    type: 'string',\n    capabilities: ['match'],\n    example: 'salesPlan:enterprise*',\n  },\n  {\n    field: 'env',\n    label: 'Environment',\n    description: 'Production or development cluster.',\n    type: 'enum',\n    capabilities: ['match'],\n    enumValues: ['production', 'development'],\n    example: 'env:production',\n  },\n]\n\nconst ALL_GRAINS: readonly ChartGrain[] = ['day', 'week', 'month']\nconst VALUE_METRIC_GRAINS = ALL_GRAINS\n\n/**\n * About one year, for a metric on a large table: the cluster gauges, which\n * are scraped about once a minute, and the change events of every backend\n * and stage. `over 12m every month` starts on the 1st of a month and reads up\n * to 396 days, so the limit holds that query.\n */\nconst LARGE_TABLE_MAX_WINDOW_DAYS = 400\n\n/** A gauge of the clusters, from the Prometheus metrics in HDP. */\nconst gaugeMetric = (\n  id: string,\n  label: string,\n  unit: ChartMetricSpec['unit'],\n  stat: ChartMetricSpec['stat'],\n  description: string,\n): ChartMetricSpec => ({\n  id,\n  label,\n  description,\n  unit,\n  dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],\n  filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],\n  grains: ALL_GRAINS,\n  maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,\n  stat,\n})\n\n/**\n * About two years. The table holds one row for each cluster, day and metric.\n * `over 24m every month` starts on the 1st of a month and reads up to 761\n * days, so the limit holds that query.\n */\nconst VALUE_METRIC_MAX_WINDOW_DAYS = 762\n\nconst valueMetric = (\n  id: string,\n  label: string,\n  description: string,\n): ChartMetricSpec => ({\n  id,\n  label,\n  description,\n  unit: 'count',\n  dimensions: VALUE_METRIC_DIMENSIONS,\n  filters: VALUE_METRIC_FILTERS,\n  grains: VALUE_METRIC_GRAINS,\n  maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,\n  stat: { series: 'sum', window: 'sum' },\n})\n\nexport const CHART_METRICS: readonly ChartMetricSpec[] = [\n  valueMetric(\n    'processInstances',\n    'Process instances',\n    'Process instances that started, from the HDP value metrics. The sum over each bucket.',\n  ),\n  valueMetric(\n    'decisionInstances',\n    'Decision instances',\n    'Decision instances that ran, from the HDP value metrics. The sum over each bucket.',\n  ),\n  valueMetric(\n    'taskUsers',\n    'Task users',\n    'Task users, from the HDP value metrics. The sum of the daily values over each bucket, as on the Value metrics tab.',\n  ),\n  gaugeMetric(\n    'activeTenants',\n    'Active tenants',\n    'count',\n    { series: 'sum', window: 'max' },\n    'Active tenants: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage.',\n  ),\n  gaugeMetric(\n    'clusterLoad',\n    'Cluster load',\n    'percent',\n    { series: 'mean', window: 'mean' },\n    'The load of a cluster, in percent: the mean of a day, then the mean over the clusters and the days of a bucket. The table holds every stage.',\n  ),\n  gaugeMetric(\n    'diskUsedBytes',\n    'Elasticsearch disk used',\n    'bytes',\n    { series: 'sum', window: 'max' },\n    'The used Elasticsearch disk: the peak of each cluster on a day, summed over the clusters. A week or a month shows its highest day. The table holds every stage.',\n  ),\n  {\n    id: 'hostingCost',\n    label: 'Hosting cost',\n    description:\n      'The loaded hosting cost of the clusters, in US dollars, from the cloud bill. The sum over each bucket. The bill holds every stage.',\n    unit: 'usd',\n    dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],\n    filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],\n    grains: ALL_GRAINS,\n    maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,\n    stat: { series: 'sum', window: 'sum' },\n  },\n  {\n    id: 'changeEvents',\n    label: 'Change events',\n    description:\n      'The change events that the backends of this stage sent to HDP: one for each insert, update or delete of an entity. The count over each bucket.',\n    unit: 'count',\n    dimensions: [\n      { id: 'entity', label: 'Entity', description: 'For example cluster.' },\n      {\n        id: 'operation',\n        label: 'Operation',\n        description: 'insert, update or delete.',\n      },\n    ],\n    filters: [\n      {\n        field: 'entity',\n        label: 'Entity',\n        description: 'The entity, case-insensitive. Use * as a wildcard.',\n        type: 'string',\n        capabilities: ['match'],\n        example: 'entity:cluster',\n      },\n      {\n        field: 'operation',\n        label: 'Operation',\n        description: 'The operation.',\n        type: 'enum',\n        capabilities: ['match'],\n        enumValues: ['insert', 'update', 'delete'],\n        example: 'operation:delete',\n      },\n    ],\n    grains: ALL_GRAINS,\n    maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,\n    stat: { series: 'sum', window: 'sum' },\n  },\n]\n\n/** Case-insensitive. */\nexport const findChartMetric = (\n  id: string,\n  metrics: readonly ChartMetricSpec[] = CHART_METRICS,\n): ChartMetricSpec | undefined =>\n  metrics.find((metric) => metric.id.toLowerCase() === id.toLowerCase())\n\n/** Case-insensitive. */\nexport const findChartDimension = (\n  metric: ChartMetricSpec,\n  id: string,\n): ChartDimensionSpec | undefined =>\n  metric.dimensions.find(\n    (dimension) => dimension.id.toLowerCase() === id.toLowerCase(),\n  )\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/charts/chart-query.d.ts

@@ -0,0 +1,55 @@
+import { type ChartMetricSpec } from './chart-metrics.js';
+import { type ChartSpec } from './chart-spec.js';
+export type ChartQueryErrorKind = 'syntax' | 'unknown-metric' | 'unknown-dimension' | 'unknown-field' | 'bad-value';
+export declare class ChartQueryError extends Error {
+    readonly kind: ChartQueryErrorKind;
+    /** A name to use instead, for "did you mean". */
+    readonly suggestion?: string;
+    constructor(message: string, kind: ChartQueryErrorKind, suggestion?: string);
+}
+/** Type guard that works across package boundaries. */
+export declare const isChartQueryError: (error: unknown) => error is ChartQueryError;
+/**
+ * The answer of `POST /api/dashboards/chart-queries/check`: the canonical spec
+ * of a valid query, or what is wrong with a query and how to fix it. A wrong
+ * query is an answer and not a failure, so a client reads `valid`.
+ */
+export type ChartQueryCheck = {
+    valid: true;
+    spec: ChartSpec;
+    query: string;
+} | {
+    valid: false;
+    error: {
+        kind: ChartQueryErrorKind;
+        message: string;
+        suggestion?: string;
+    };
+};
+export interface ChartQueryOptions {
+    metrics?: readonly ChartMetricSpec[];
+    /** `YYYY-MM-DD`. The default is today in UTC. */
+    today?: string;
+}
+/**
+ * Parse and validate a chart query. Gives the canonical {@link ChartSpec}:
+ * the ids in the spelling of the catalogue, and the defaults filled in.
+ * Throws {@link ChartQueryError}.
+ */
+export declare const parseChartQuery: (text: string, options?: ChartQueryOptions) => ChartSpec;
+/**
+ * Check a spec against the catalogue and give it in canonical form. The chart
+ * route runs this on every request body, so a spec that a tile stored long ago
+ * gets the rules of today. Throws {@link ChartQueryError}.
+ */
+export declare const validateChartSpec: (spec: ChartSpec, options?: ChartQueryOptions) => ChartSpec;
+/**
+ * The text of a spec, in one canonical form. Parsing it again gives the same
+ * spec, so the text field and the builder can never disagree.
+ */
+export declare const formatChartSpec: (spec: ChartSpec) => string;
+/**
+ * Read a spec from JSON, for example a request body or a stored tile. Checks
+ * the shape only. Run {@link validateChartSpec} after it.
+ */
+export declare const readChartSpec: (value: unknown) => ChartSpec;

package/dist/charts/chart-query.js

@@ -0,0 +1,376 @@
+import { isLuceneQueryError } from "../search/ast.js";
+import { closestField } from "../search/compiler.js";
+import { findSearchField } from "../search/fields.js";
+import { parseLuceneQuery } from "../search/parser.js";
+import {
+  CHART_METRICS,
+  findChartDimension,
+  findChartMetric
+} from "./chart-metrics.js";
+import {
+  CHART_DAY_GRAIN_MAX_DAYS,
+  CHART_GRAIN_DEFAULT,
+  CHART_GRAINS,
+  CHART_ID_MAX_LENGTH,
+  CHART_QUERY_MAX_LENGTH,
+  CHART_TOP_DEFAULT,
+  CHART_TOP_MAX,
+  CHART_WINDOW_AMOUNT_MAX,
+  CHART_WINDOW_DEFAULT,
+  CHART_WINDOW_UNITS,
+  chartToday,
+  chartWindowRange
+} from "./chart-spec.js";
+class ChartQueryError extends Error {
+  kind;
+  /** A name to use instead, for "did you mean". */
+  suggestion;
+  constructor(message, kind, suggestion) {
+    super(message);
+    this.name = "ChartQueryError";
+    this.kind = kind;
+    this.suggestion = suggestion;
+  }
+}
+const isChartQueryError = (error) => error instanceof ChartQueryError || typeof error === "object" && error !== null && error.name === "ChartQueryError";
+const KEYWORDS = ["by", "every", "over", "top", "where"];
+const DURATION = /^(\d{1,4})([dwm])$/i;
+const INTEGER = /^\d{1,4}$/;
+const parseChartQuery = (text, options = {}) => validateChartSpec(readChartQueryText(text), options);
+const readChartQueryText = (text) => {
+  if (text.length > CHART_QUERY_MAX_LENGTH) {
+    throw new ChartQueryError(
+      `The query is too long. The maximum is ${CHART_QUERY_MAX_LENGTH} characters.`,
+      "syntax"
+    );
+  }
+  const tokens = [...text.matchAll(/\S+/g)];
+  if (tokens.length === 0) {
+    throw new ChartQueryError(
+      "The query is empty. Start with a metric.",
+      "syntax"
+    );
+  }
+  const metric = tokens[0][0];
+  if (isKeyword(metric)) {
+    throw new ChartQueryError(
+      `The query starts with "${metric}". Start with a metric.`,
+      "syntax"
+    );
+  }
+  const spec = { metric };
+  const seen = /* @__PURE__ */ new Set();
+  let index = 1;
+  while (index < tokens.length) {
+    const word = tokens[index][0];
+    const keyword = word.toLowerCase();
+    if (!isKeyword(keyword)) {
+      const suggestion = closestField(keyword, KEYWORDS);
+      throw new ChartQueryError(
+        `"${word}" is not a clause.${suggestion ? ` Did you mean "${suggestion}"?` : ""} Use by, every, over, top or where.`,
+        "syntax",
+        suggestion
+      );
+    }
+    if (seen.has(keyword)) {
+      throw new ChartQueryError(
+        `"${keyword}" occurs more than one time.`,
+        "syntax"
+      );
+    }
+    seen.add(keyword);
+    if (keyword === "where") {
+      const start = (tokens[index].index ?? 0) + word.length;
+      const filter = text.slice(start).trim();
+      if (filter.length === 0) {
+        throw new ChartQueryError('"where" has no filter after it.', "syntax");
+      }
+      spec.filter = filter;
+      break;
+    }
+    const value = tokens[index + 1]?.[0];
+    if (value === void 0 || isKeyword(value.toLowerCase())) {
+      throw new ChartQueryError(`"${keyword}" has no value after it.`, "syntax");
+    }
+    switch (keyword) {
+      case "by":
+        spec.by = value;
+        break;
+      case "every":
+        spec.grain = readGrain(value);
+        break;
+      case "over":
+        spec.window = readDuration(value);
+        break;
+      case "top":
+        spec.top = readTop(value);
+        break;
+    }
+    index += 2;
+  }
+  return {
+    ...spec,
+    grain: spec.grain ?? CHART_GRAIN_DEFAULT,
+    window: spec.window ?? CHART_WINDOW_DEFAULT
+  };
+};
+const isKeyword = (word) => KEYWORDS.includes(word);
+const readGrain = (value) => {
+  const grain = value.toLowerCase();
+  if (!CHART_GRAINS.includes(grain)) {
+    throw new ChartQueryError(
+      `"every ${value}" is not a bucket. Use day, week or month.`,
+      "bad-value"
+    );
+  }
+  return grain;
+};
+const readDuration = (value) => {
+  const match = DURATION.exec(value);
+  if (!match || Number(match[1]) === 0) {
+    throw new ChartQueryError(
+      `"over ${value}" is not a duration. Use a number and d, w or m, for example 90d.`,
+      "bad-value"
+    );
+  }
+  return {
+    amount: Number(match[1]),
+    unit: match[2].toLowerCase()
+  };
+};
+const readTop = (value) => {
+  if (!INTEGER.test(value)) {
+    throw new ChartQueryError(`"top ${value}" is not a number.`, "bad-value");
+  }
+  return Number(value);
+};
+const validateChartSpec = (spec, options = {}) => {
+  const metrics = options.metrics ?? CHART_METRICS;
+  const metric = findChartMetric(spec.metric, metrics);
+  if (!metric) {
+    const suggestion = closestField(
+      spec.metric,
+      metrics.map((entry) => entry.id)
+    );
+    throw new ChartQueryError(
+      `There is no metric "${spec.metric}".${suggestion ? ` Did you mean "${suggestion}"?` : ""}`,
+      "unknown-metric",
+      suggestion
+    );
+  }
+  let by;
+  if (spec.by !== void 0) {
+    const dimension = findChartDimension(metric, spec.by);
+    if (!dimension) {
+      const ids = metric.dimensions.map((entry) => entry.id);
+      const suggestion = closestField(spec.by, ids);
+      throw new ChartQueryError(
+        `${metric.id} has no dimension "${spec.by}". Use one of: ${ids.join(", ")}.`,
+        "unknown-dimension",
+        suggestion
+      );
+    }
+    by = dimension.id;
+  }
+  if (!metric.grains.includes(spec.grain)) {
+    throw new ChartQueryError(
+      `${metric.id} has no bucket "${spec.grain}". Use one of: ${metric.grains.join(", ")}.`,
+      "bad-value"
+    );
+  }
+  const today = options.today ?? chartToday();
+  const { days } = chartWindowRange(spec.window, spec.grain, today);
+  if (days > metric.maxWindowDays) {
+    throw new ChartQueryError(
+      `"over ${formatDuration(spec.window)}" reads ${days} days. ${metric.id} reads at most ${metric.maxWindowDays} days.`,
+      "bad-value"
+    );
+  }
+  if (spec.grain === "day" && days > CHART_DAY_GRAIN_MAX_DAYS) {
+    throw new ChartQueryError(
+      `"over ${formatDuration(spec.window)}" reads ${days} days. With "every day", the maximum is ${CHART_DAY_GRAIN_MAX_DAYS} days. Use "every week" or "every month".`,
+      "bad-value"
+    );
+  }
+  let top;
+  if (spec.top !== void 0 && by === void 0) {
+    throw new ChartQueryError(
+      '"top" needs "by". Without "by", the chart has one series.',
+      "syntax"
+    );
+  }
+  if (by !== void 0) {
+    top = spec.top ?? CHART_TOP_DEFAULT;
+    if (top < 1 || top > CHART_TOP_MAX) {
+      throw new ChartQueryError(
+        `"top ${top}" is out of range. Use 1 to ${CHART_TOP_MAX}.`,
+        "bad-value"
+      );
+    }
+  }
+  const filter = spec.filter?.trim() || void 0;
+  if (filter !== void 0) {
+    checkFilter(filter, metric.filters);
+  }
+  return {
+    metric: metric.id,
+    ...by !== void 0 ? { by } : {},
+    grain: spec.grain,
+    window: { amount: spec.window.amount, unit: spec.window.unit },
+    ...filter !== void 0 ? { filter } : {},
+    ...top !== void 0 ? { top } : {}
+  };
+};
+const checkFilter = (filter, fields) => {
+  let ast;
+  try {
+    ast = parseLuceneQuery(filter);
+  } catch (error) {
+    if (isLuceneQueryError(error)) {
+      throw new ChartQueryError(`In "where": ${error.message}`, "syntax");
+    }
+    throw error;
+  }
+  if (ast) {
+    checkFilterNode(ast, fields);
+  }
+};
+const checkFilterNode = (node, fields) => {
+  switch (node.kind) {
+    case "and":
+    case "or":
+      checkFilterNode(node.left, fields);
+      checkFilterNode(node.right, fields);
+      return;
+    case "not":
+      checkFilterNode(node.child, fields);
+      return;
+    case "range": {
+      const spec = filterField(node.field, fields);
+      if (!spec.capabilities.includes("range")) {
+        throw new ChartQueryError(
+          `"${spec.field}" does not take a range.`,
+          "bad-value"
+        );
+      }
+      return;
+    }
+    case "term": {
+      if (node.field === void 0) {
+        throw new ChartQueryError(
+          `"${node.value}" has no field. Write field:value, for example ${fields[0]?.example ?? "orgId:\u2026"}.`,
+          "syntax"
+        );
+      }
+      const spec = filterField(node.field, fields);
+      if (node.operator !== ":" && !spec.capabilities.includes("range")) {
+        throw new ChartQueryError(
+          `"${spec.field}" takes only ${spec.field}:value.`,
+          "bad-value"
+        );
+      }
+      if (node.value.startsWith("$")) {
+        throw new ChartQueryError(
+          `"${node.value}" is a dashboard variable. Dashboard variables are not available yet.`,
+          "bad-value"
+        );
+      }
+      if (spec.type === "enum" && !spec.enumValues?.some(
+        (value) => value.toLowerCase() === node.value.toLowerCase()
+      )) {
+        throw new ChartQueryError(
+          `"${spec.field}" takes one of: ${spec.enumValues?.join(", ")}.`,
+          "bad-value"
+        );
+      }
+      return;
+    }
+  }
+};
+const filterField = (name, fields) => {
+  const spec = findSearchField(fields, name);
+  if (!spec) {
+    const suggestion = closestField(
+      name,
+      fields.map((field) => field.field)
+    );
+    throw new ChartQueryError(
+      `There is no filter field "${name}".${suggestion ? ` Did you mean "${suggestion}"?` : ""}`,
+      "unknown-field",
+      suggestion
+    );
+  }
+  return spec;
+};
+const formatDuration = (window) => `${window.amount}${window.unit}`;
+const formatChartSpec = (spec) => [
+  spec.metric,
+  ...spec.by !== void 0 ? ["by", spec.by] : [],
+  "every",
+  spec.grain,
+  "over",
+  formatDuration(spec.window),
+  ...spec.top !== void 0 ? ["top", String(spec.top)] : [],
+  ...spec.filter !== void 0 ? ["where", spec.filter] : []
+].join(" ");
+const readChartSpec = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ChartQueryError("The chart query must be an object.", "syntax");
+  }
+  const record = value;
+  const allowed = /* @__PURE__ */ new Set(["metric", "by", "grain", "window", "filter", "top"]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      throw new ChartQueryError(
+        `The chart query has an unknown key "${key}".`,
+        "syntax"
+      );
+    }
+  }
+  const { metric, by, grain, window, filter, top } = record;
+  if (typeof metric !== "string" || metric.length === 0 || metric.length > CHART_ID_MAX_LENGTH) {
+    throw new ChartQueryError('"metric" must be a string.', "syntax");
+  }
+  if (by !== void 0 && (typeof by !== "string" || by.length > CHART_ID_MAX_LENGTH)) {
+    throw new ChartQueryError('"by" must be a string.', "syntax");
+  }
+  if (typeof grain !== "string" || !CHART_GRAINS.includes(grain)) {
+    throw new ChartQueryError(
+      `"grain" must be one of: ${CHART_GRAINS.join(", ")}.`,
+      "syntax"
+    );
+  }
+  if (typeof window !== "object" || window === null) {
+    throw new ChartQueryError('"window" must be an object.', "syntax");
+  }
+  const { amount, unit } = window;
+  if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 1 || amount > CHART_WINDOW_AMOUNT_MAX || typeof unit !== "string" || !CHART_WINDOW_UNITS.includes(unit) || Object.keys(window).length !== 2) {
+    throw new ChartQueryError(
+      `"window" must be { amount, unit }, with a whole amount from 1 to ${CHART_WINDOW_AMOUNT_MAX} and a unit of d, w or m.`,
+      "syntax"
+    );
+  }
+  if (filter !== void 0 && typeof filter !== "string") {
+    throw new ChartQueryError('"filter" must be a string.', "syntax");
+  }
+  if (top !== void 0 && (typeof top !== "number" || !Number.isInteger(top))) {
+    throw new ChartQueryError('"top" must be a whole number.', "syntax");
+  }
+  return {
+    metric,
+    ...by !== void 0 ? { by } : {},
+    grain,
+    window: { amount, unit },
+    ...filter !== void 0 ? { filter } : {},
+    ...top !== void 0 ? { top } : {}
+  };
+};
+export {
+  ChartQueryError,
+  formatChartSpec,
+  isChartQueryError,
+  parseChartQuery,
+  readChartSpec,
+  validateChartSpec
+};
+//# sourceMappingURL=chart-query.js.map

package/dist/charts/chart-query.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/charts/chart-query.ts"],
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport { isLuceneQueryError, type QueryNode } from '../search/ast.js'\nimport { closestField } from '../search/compiler.js'\nimport { findSearchField, type SearchFieldSpec } from '../search/fields.js'\nimport { parseLuceneQuery } from '../search/parser.js'\nimport {\n  CHART_METRICS,\n  type ChartMetricSpec,\n  findChartDimension,\n  findChartMetric,\n} from './chart-metrics.js'\nimport {\n  CHART_DAY_GRAIN_MAX_DAYS,\n  CHART_GRAIN_DEFAULT,\n  CHART_GRAINS,\n  CHART_ID_MAX_LENGTH,\n  CHART_QUERY_MAX_LENGTH,\n  CHART_TOP_DEFAULT,\n  CHART_TOP_MAX,\n  CHART_WINDOW_AMOUNT_MAX,\n  CHART_WINDOW_DEFAULT,\n  CHART_WINDOW_UNITS,\n  type ChartGrain,\n  type ChartSpec,\n  type ChartWindow,\n  type ChartWindowUnit,\n  chartToday,\n  chartWindowRange,\n} from './chart-spec.js'\n\n// ============================================================================\n// The chart query language.\n//\n//   query    = metric clause*\n//   clause   = \"by\" dimension | \"every\" grain | \"over\" duration\n//            | \"top\" integer | \"where\" lucene\n//   duration = integer (\"d\" | \"w\" | \"m\")\n//\n// Keywords are case-insensitive, and each clause occurs at most one time.\n// `where` is the last clause: the rest of the text is the Lucene filter of\n// Fleet query, over the filter fields of the metric. The frontend and the\n// backend run the same checks, so a query that the field accepts also runs.\n// ============================================================================\n\nexport type ChartQueryErrorKind =\n  | 'syntax'\n  | 'unknown-metric'\n  | 'unknown-dimension'\n  | 'unknown-field'\n  | 'bad-value'\n\nexport class ChartQueryError extends Error {\n  readonly kind: ChartQueryErrorKind\n  /** A name to use instead, for \"did you mean\". */\n  readonly suggestion?: string\n\n  constructor(message: string, kind: ChartQueryErrorKind, suggestion?: string) {\n    super(message)\n    this.name = 'ChartQueryError'\n    this.kind = kind\n    this.suggestion = suggestion\n  }\n}\n\n/** Type guard that works across package boundaries. */\nexport const isChartQueryError = (error: unknown): error is ChartQueryError =>\n  error instanceof ChartQueryError ||\n  (typeof error === 'object' &&\n    error !== null &&\n    (error as { name?: unknown }).name === 'ChartQueryError')\n\n/**\n * The answer of `POST /api/dashboards/chart-queries/check`: the canonical spec\n * of a valid query, or what is wrong with a query and how to fix it. A wrong\n * query is an answer and not a failure, so a client reads `valid`.\n */\nexport type ChartQueryCheck =\n  | { valid: true; spec: ChartSpec; query: string }\n  | {\n      valid: false\n      error: {\n        kind: ChartQueryErrorKind\n        message: string\n        suggestion?: string\n      }\n    }\n\nconst KEYWORDS = ['by', 'every', 'over', 'top', 'where'] as const\ntype Keyword = (typeof KEYWORDS)[number]\n\nconst DURATION = /^(\\d{1,4})([dwm])$/i\nconst INTEGER = /^\\d{1,4}$/\n\nexport interface ChartQueryOptions {\n  metrics?: readonly ChartMetricSpec[]\n  /** `YYYY-MM-DD`. The default is today in UTC. */\n  today?: string\n}\n\n/**\n * Parse and validate a chart query. Gives the canonical {@link ChartSpec}:\n * the ids in the spelling of the catalogue, and the defaults filled in.\n * Throws {@link ChartQueryError}.\n */\nexport const parseChartQuery = (\n  text: string,\n  options: ChartQueryOptions = {},\n): ChartSpec => validateChartSpec(readChartQueryText(text), options)\n\n/** The clauses of the text, with no check against the catalogue. */\nconst readChartQueryText = (text: string): ChartSpec => {\n  if (text.length > CHART_QUERY_MAX_LENGTH) {\n    throw new ChartQueryError(\n      `The query is too long. The maximum is ${CHART_QUERY_MAX_LENGTH} characters.`,\n      'syntax',\n    )\n  }\n  const tokens = [...text.matchAll(/\\S+/g)]\n  if (tokens.length === 0) {\n    throw new ChartQueryError(\n      'The query is empty. Start with a metric.',\n      'syntax',\n    )\n  }\n  const metric = tokens[0][0]\n  if (isKeyword(metric)) {\n    throw new ChartQueryError(\n      `The query starts with \"${metric}\". Start with a metric.`,\n      'syntax',\n    )\n  }\n\n  const spec: Partial<ChartSpec> & { metric: string } = { metric }\n  const seen = new Set<Keyword>()\n  let index = 1\n  while (index < tokens.length) {\n    const word = tokens[index][0]\n    const keyword = word.toLowerCase()\n    if (!isKeyword(keyword)) {\n      const suggestion = closestField(keyword, KEYWORDS)\n      throw new ChartQueryError(\n        `\"${word}\" is not a clause.${suggestion ? ` Did you mean \"${suggestion}\"?` : ''} Use by, every, over, top or where.`,\n        'syntax',\n        suggestion,\n      )\n    }\n    if (seen.has(keyword)) {\n      throw new ChartQueryError(\n        `\"${keyword}\" occurs more than one time.`,\n        'syntax',\n      )\n    }\n    seen.add(keyword)\n\n    if (keyword === 'where') {\n      const start = (tokens[index].index ?? 0) + word.length\n      const filter = text.slice(start).trim()\n      if (filter.length === 0) {\n        throw new ChartQueryError('\"where\" has no filter after it.', 'syntax')\n      }\n      spec.filter = filter\n      break\n    }\n\n    const value = tokens[index + 1]?.[0]\n    if (value === undefined || isKeyword(value.toLowerCase())) {\n      throw new ChartQueryError(`\"${keyword}\" has no value after it.`, 'syntax')\n    }\n    switch (keyword) {\n      case 'by':\n        spec.by = value\n        break\n      case 'every':\n        spec.grain = readGrain(value)\n        break\n      case 'over':\n        spec.window = readDuration(value)\n        break\n      case 'top':\n        spec.top = readTop(value)\n        break\n    }\n    index += 2\n  }\n\n  return {\n    ...spec,\n    grain: spec.grain ?? CHART_GRAIN_DEFAULT,\n    window: spec.window ?? CHART_WINDOW_DEFAULT,\n  }\n}\n\nconst isKeyword = (word: string): word is Keyword =>\n  (KEYWORDS as readonly string[]).includes(word)\n\nconst readGrain = (value: string): ChartGrain => {\n  const grain = value.toLowerCase()\n  if (!(CHART_GRAINS as readonly string[]).includes(grain)) {\n    throw new ChartQueryError(\n      `\"every ${value}\" is not a bucket. Use day, week or month.`,\n      'bad-value',\n    )\n  }\n  return grain as ChartGrain\n}\n\nconst readDuration = (value: string): ChartWindow => {\n  const match = DURATION.exec(value)\n  if (!match || Number(match[1]) === 0) {\n    throw new ChartQueryError(\n      `\"over ${value}\" is not a duration. Use a number and d, w or m, for example 90d.`,\n      'bad-value',\n    )\n  }\n  return {\n    amount: Number(match[1]),\n    unit: match[2].toLowerCase() as ChartWindowUnit,\n  }\n}\n\nconst readTop = (value: string): number => {\n  if (!INTEGER.test(value)) {\n    throw new ChartQueryError(`\"top ${value}\" is not a number.`, 'bad-value')\n  }\n  return Number(value)\n}\n\n/**\n * Check a spec against the catalogue and give it in canonical form. The chart\n * route runs this on every request body, so a spec that a tile stored long ago\n * gets the rules of today. Throws {@link ChartQueryError}.\n */\nexport const validateChartSpec = (\n  spec: ChartSpec,\n  options: ChartQueryOptions = {},\n): ChartSpec => {\n  const metrics = options.metrics ?? CHART_METRICS\n  const metric = findChartMetric(spec.metric, metrics)\n  if (!metric) {\n    const suggestion = closestField(\n      spec.metric,\n      metrics.map((entry) => entry.id),\n    )\n    throw new ChartQueryError(\n      `There is no metric \"${spec.metric}\".${suggestion ? ` Did you mean \"${suggestion}\"?` : ''}`,\n      'unknown-metric',\n      suggestion,\n    )\n  }\n\n  let by: string | undefined\n  if (spec.by !== undefined) {\n    const dimension = findChartDimension(metric, spec.by)\n    if (!dimension) {\n      const ids = metric.dimensions.map((entry) => entry.id)\n      const suggestion = closestField(spec.by, ids)\n      throw new ChartQueryError(\n        `${metric.id} has no dimension \"${spec.by}\". Use one of: ${ids.join(', ')}.`,\n        'unknown-dimension',\n        suggestion,\n      )\n    }\n    by = dimension.id\n  }\n\n  if (!metric.grains.includes(spec.grain)) {\n    throw new ChartQueryError(\n      `${metric.id} has no bucket \"${spec.grain}\". Use one of: ${metric.grains.join(', ')}.`,\n      'bad-value',\n    )\n  }\n\n  const today = options.today ?? chartToday()\n  const { days } = chartWindowRange(spec.window, spec.grain, today)\n  if (days > metric.maxWindowDays) {\n    throw new ChartQueryError(\n      `\"over ${formatDuration(spec.window)}\" reads ${days} days. ${metric.id} reads at most ${metric.maxWindowDays} days.`,\n      'bad-value',\n    )\n  }\n  if (spec.grain === 'day' && days > CHART_DAY_GRAIN_MAX_DAYS) {\n    throw new ChartQueryError(\n      `\"over ${formatDuration(spec.window)}\" reads ${days} days. With \"every day\", the maximum is ${CHART_DAY_GRAIN_MAX_DAYS} days. Use \"every week\" or \"every month\".`,\n      'bad-value',\n    )\n  }\n\n  let top: number | undefined\n  if (spec.top !== undefined && by === undefined) {\n    throw new ChartQueryError(\n      '\"top\" needs \"by\". Without \"by\", the chart has one series.',\n      'syntax',\n    )\n  }\n  if (by !== undefined) {\n    top = spec.top ?? CHART_TOP_DEFAULT\n    if (top < 1 || top > CHART_TOP_MAX) {\n      throw new ChartQueryError(\n        `\"top ${top}\" is out of range. Use 1 to ${CHART_TOP_MAX}.`,\n        'bad-value',\n      )\n    }\n  }\n\n  const filter = spec.filter?.trim() || undefined\n  if (filter !== undefined) {\n    checkFilter(filter, metric.filters)\n  }\n\n  return {\n    metric: metric.id,\n    ...(by !== undefined ? { by } : {}),\n    grain: spec.grain,\n    window: { amount: spec.window.amount, unit: spec.window.unit },\n    ...(filter !== undefined ? { filter } : {}),\n    ...(top !== undefined ? { top } : {}),\n  }\n}\n\nconst checkFilter = (\n  filter: string,\n  fields: readonly SearchFieldSpec[],\n): void => {\n  let ast: QueryNode | undefined\n  try {\n    ast = parseLuceneQuery(filter)\n  } catch (error) {\n    if (isLuceneQueryError(error)) {\n      throw new ChartQueryError(`In \"where\": ${error.message}`, 'syntax')\n    }\n    throw error\n  }\n  if (ast) {\n    checkFilterNode(ast, fields)\n  }\n}\n\nconst checkFilterNode = (\n  node: QueryNode,\n  fields: readonly SearchFieldSpec[],\n): void => {\n  switch (node.kind) {\n    case 'and':\n    case 'or':\n      checkFilterNode(node.left, fields)\n      checkFilterNode(node.right, fields)\n      return\n    case 'not':\n      checkFilterNode(node.child, fields)\n      return\n    case 'range': {\n      const spec = filterField(node.field, fields)\n      if (!spec.capabilities.includes('range')) {\n        throw new ChartQueryError(\n          `\"${spec.field}\" does not take a range.`,\n          'bad-value',\n        )\n      }\n      return\n    }\n    case 'term': {\n      if (node.field === undefined) {\n        throw new ChartQueryError(\n          `\"${node.value}\" has no field. Write field:value, for example ${fields[0]?.example ?? 'orgId:\u2026'}.`,\n          'syntax',\n        )\n      }\n      const spec = filterField(node.field, fields)\n      if (node.operator !== ':' && !spec.capabilities.includes('range')) {\n        throw new ChartQueryError(\n          `\"${spec.field}\" takes only ${spec.field}:value.`,\n          'bad-value',\n        )\n      }\n      if (node.value.startsWith('$')) {\n        throw new ChartQueryError(\n          `\"${node.value}\" is a dashboard variable. Dashboard variables are not available yet.`,\n          'bad-value',\n        )\n      }\n      if (\n        spec.type === 'enum' &&\n        !spec.enumValues?.some(\n          (value) => value.toLowerCase() === node.value.toLowerCase(),\n        )\n      ) {\n        throw new ChartQueryError(\n          `\"${spec.field}\" takes one of: ${spec.enumValues?.join(', ')}.`,\n          'bad-value',\n        )\n      }\n      return\n    }\n  }\n}\n\nconst filterField = (\n  name: string,\n  fields: readonly SearchFieldSpec[],\n): SearchFieldSpec => {\n  const spec = findSearchField(fields, name)\n  if (!spec) {\n    const suggestion = closestField(\n      name,\n      fields.map((field) => field.field),\n    )\n    throw new ChartQueryError(\n      `There is no filter field \"${name}\".${suggestion ? ` Did you mean \"${suggestion}\"?` : ''}`,\n      'unknown-field',\n      suggestion,\n    )\n  }\n  return spec\n}\n\nconst formatDuration = (window: ChartWindow): string =>\n  `${window.amount}${window.unit}`\n\n/**\n * The text of a spec, in one canonical form. Parsing it again gives the same\n * spec, so the text field and the builder can never disagree.\n */\nexport const formatChartSpec = (spec: ChartSpec): string =>\n  [\n    spec.metric,\n    ...(spec.by !== undefined ? ['by', spec.by] : []),\n    'every',\n    spec.grain,\n    'over',\n    formatDuration(spec.window),\n    ...(spec.top !== undefined ? ['top', String(spec.top)] : []),\n    ...(spec.filter !== undefined ? ['where', spec.filter] : []),\n  ].join(' ')\n\n/**\n * Read a spec from JSON, for example a request body or a stored tile. Checks\n * the shape only. Run {@link validateChartSpec} after it.\n */\nexport const readChartSpec = (value: unknown): ChartSpec => {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new ChartQueryError('The chart query must be an object.', 'syntax')\n  }\n  const record = value as Record<string, unknown>\n  const allowed = new Set(['metric', 'by', 'grain', 'window', 'filter', 'top'])\n  for (const key of Object.keys(record)) {\n    if (!allowed.has(key)) {\n      throw new ChartQueryError(\n        `The chart query has an unknown key \"${key}\".`,\n        'syntax',\n      )\n    }\n  }\n  const { metric, by, grain, window, filter, top } = record\n  if (\n    typeof metric !== 'string' ||\n    metric.length === 0 ||\n    metric.length > CHART_ID_MAX_LENGTH\n  ) {\n    throw new ChartQueryError('\"metric\" must be a string.', 'syntax')\n  }\n  if (\n    by !== undefined &&\n    (typeof by !== 'string' || by.length > CHART_ID_MAX_LENGTH)\n  ) {\n    throw new ChartQueryError('\"by\" must be a string.', 'syntax')\n  }\n  if (\n    typeof grain !== 'string' ||\n    !(CHART_GRAINS as readonly string[]).includes(grain)\n  ) {\n    throw new ChartQueryError(\n      `\"grain\" must be one of: ${CHART_GRAINS.join(', ')}.`,\n      'syntax',\n    )\n  }\n  if (typeof window !== 'object' || window === null) {\n    throw new ChartQueryError('\"window\" must be an object.', 'syntax')\n  }\n  const { amount, unit } = window as Record<string, unknown>\n  if (\n    typeof amount !== 'number' ||\n    !Number.isInteger(amount) ||\n    amount < 1 ||\n    amount > CHART_WINDOW_AMOUNT_MAX ||\n    typeof unit !== 'string' ||\n    !(CHART_WINDOW_UNITS as readonly string[]).includes(unit) ||\n    Object.keys(window).length !== 2\n  ) {\n    throw new ChartQueryError(\n      `\"window\" must be { amount, unit }, with a whole amount from 1 to ${CHART_WINDOW_AMOUNT_MAX} and a unit of d, w or m.`,\n      'syntax',\n    )\n  }\n  if (filter !== undefined && typeof filter !== 'string') {\n    throw new ChartQueryError('\"filter\" must be a string.', 'syntax')\n  }\n  if (\n    top !== undefined &&\n    (typeof top !== 'number' || !Number.isInteger(top))\n  ) {\n    throw new ChartQueryError('\"top\" must be a whole number.', 'syntax')\n  }\n  // The checks above narrow nothing for the compiler, thus the casts.\n  return {\n    metric,\n    ...(by !== undefined ? { by: by as string } : {}),\n    grain: grain as ChartGrain,\n    window: { amount, unit: unit as ChartWindowUnit },\n    ...(filter !== undefined ? { filter: filter as string } : {}),\n    ...(top !== undefined ? { top: top as number } : {}),\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/charts/chart-spec.d.ts

@@ -0,0 +1,103 @@
+/** The time buckets of a chart. A week starts on Monday (ISO). */
+export declare const CHART_GRAINS: readonly ["day", "week", "month"];
+export type ChartGrain = (typeof CHART_GRAINS)[number];
+/** `d` is days, `w` is weeks and `m` is calendar months. */
+export declare const CHART_WINDOW_UNITS: readonly ["d", "w", "m"];
+export type ChartWindowUnit = (typeof CHART_WINDOW_UNITS)[number];
+/** A window that ends today (UTC). "The last 90 days" is `{ amount: 90, unit: 'd' }`. */
+export interface ChartWindow {
+    amount: number;
+    unit: ChartWindowUnit;
+}
+/**
+ * One chart query. A tile stores this and never the data, so the chart
+ * follows the window as the days go by.
+ */
+export interface ChartSpec {
+    /** A metric id of `CHART_METRICS`. */
+    metric: string;
+    /** A dimension id of the metric. Each value of it is one series. */
+    by?: string;
+    grain: ChartGrain;
+    window: ChartWindow;
+    /** Lucene source text over the filter fields of the metric. */
+    filter?: string;
+    /** The number of series to show. Only with `by`. */
+    top?: number;
+}
+export declare const CHART_GRAIN_DEFAULT: ChartGrain;
+export declare const CHART_WINDOW_DEFAULT: ChartWindow;
+export declare const CHART_TOP_DEFAULT = 10;
+export declare const CHART_TOP_MAX = 20;
+/** The longest window, in days, for `every day`. */
+export declare const CHART_DAY_GRAIN_MAX_DAYS = 366;
+/**
+ * The longest text of a whole chart query. The filter has its own limit,
+ * `CHART_FILTER_MAX_LENGTH`.
+ */
+export declare const CHART_QUERY_MAX_LENGTH = 700;
+/**
+ * The longest filter of a chart query. It is the limit of the Lucene parser,
+ * which checks every filter on every run.
+ */
+export declare const CHART_FILTER_MAX_LENGTH = 512;
+/** The longest metric id or dimension id that a stored chart query holds. */
+export declare const CHART_ID_MAX_LENGTH = 64;
+/** The largest amount of a window, in its unit. */
+export declare const CHART_WINDOW_AMOUNT_MAX = 9999;
+/**
+ * The series key of the sum of every series that is not in the top N. When a
+ * real value of the dimension has this key, the key gets a `*`, so the keys
+ * of a result stay unique.
+ */
+export declare const CHART_OTHER_SERIES_KEY = "(other)";
+/**
+ * The series key of the rows with no value for the `by` dimension. It gets a
+ * `*` the same way as `CHART_OTHER_SERIES_KEY`.
+ */
+export declare const CHART_UNKNOWN_SERIES_KEY = "(unknown)";
+export interface ChartPoint {
+    /** The first day of the bucket, `YYYY-MM-DD`. */
+    ts: string;
+    value: number;
+}
+export interface ChartSeries {
+    key: string;
+    points: ChartPoint[];
+}
+/** `percent` is 0 to 100. */
+export type ChartUnit = 'count' | 'bytes' | 'usd' | 'percent';
+/** The answer of `POST /api/hdp/charts/query`. */
+export interface ChartResult {
+    metric: string;
+    unit: ChartUnit;
+    grain: ChartGrain;
+    /** The first day that the query reads, `YYYY-MM-DD`, inclusive. */
+    from: string;
+    /** The last day that the query reads, `YYYY-MM-DD`, inclusive. */
+    to: string;
+    /**
+     * Sorted by the total of the series, the largest first. `(other)` is last.
+     * The keys are unique.
+     */
+    series: ChartSeries[];
+    /** True when the top N left out series. Their sum is the `(other)` series. */
+    truncated: boolean;
+    bytesProcessed: number;
+    /** When the result came from the cache: the time of the query, ISO. */
+    cachedAt?: string;
+}
+/** The first day of the bucket of `day`, as BigQuery's `DATE_TRUNC` gives it. */
+export declare const chartBucketStart: (day: string, grain: ChartGrain) => string;
+/**
+ * The days that a chart reads. The window ends on `today` and goes back by its
+ * amount. The start moves back to the start of its bucket, so the first
+ * bucket of the chart is complete.
+ */
+export declare const chartWindowRange: (window: ChartWindow, grain: ChartGrain, today: string) => {
+    from: string;
+    to: string;
+    days: number;
+};
+/** Today in UTC, `YYYY-MM-DD`. */
+export declare const chartToday: (now?: Date) => string;