@camunda/ccma-shared-types 5.0.0 → 6.0.0

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;

package/dist/charts/chart-spec.js

@@ -0,0 +1,79 @@
+import { LUCENE_QUERY_MAX_LENGTH } from "../search/parser.js";
+const CHART_GRAINS = ["day", "week", "month"];
+const CHART_WINDOW_UNITS = ["d", "w", "m"];
+const CHART_GRAIN_DEFAULT = "day";
+const CHART_WINDOW_DEFAULT = { amount: 30, unit: "d" };
+const CHART_TOP_DEFAULT = 10;
+const CHART_TOP_MAX = 20;
+const CHART_DAY_GRAIN_MAX_DAYS = 366;
+const CHART_QUERY_MAX_LENGTH = 700;
+const CHART_FILTER_MAX_LENGTH = LUCENE_QUERY_MAX_LENGTH;
+const CHART_ID_MAX_LENGTH = 64;
+const CHART_WINDOW_AMOUNT_MAX = 9999;
+const CHART_OTHER_SERIES_KEY = "(other)";
+const CHART_UNKNOWN_SERIES_KEY = "(unknown)";
+const DAY_MS = 24 * 60 * 60 * 1e3;
+const toDay = (date) => date.toISOString().slice(0, 10);
+const parseDay = (day) => /* @__PURE__ */ new Date(`${day}T00:00:00Z`);
+const addDays = (day, delta) => toDay(new Date(parseDay(day).getTime() + delta * DAY_MS));
+const chartBucketStart = (day, grain) => {
+  const date = parseDay(day);
+  switch (grain) {
+    case "day":
+      return day;
+    case "week": {
+      const sinceMonday = (date.getUTCDay() + 6) % 7;
+      return addDays(day, -sinceMonday);
+    }
+    case "month":
+      return `${day.slice(0, 7)}-01`;
+  }
+};
+const chartWindowRange = (window, grain, today) => {
+  let start;
+  switch (window.unit) {
+    case "d":
+      start = addDays(today, -(window.amount - 1));
+      break;
+    case "w":
+      start = addDays(today, -(7 * window.amount - 1));
+      break;
+    case "m": {
+      const date = parseDay(today);
+      const shifted = new Date(
+        Date.UTC(date.getUTCFullYear(), date.getUTCMonth() - window.amount, 1)
+      );
+      const lastDay = new Date(
+        Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, 0)
+      ).getUTCDate();
+      shifted.setUTCDate(Math.min(date.getUTCDate(), lastDay));
+      start = addDays(toDay(shifted), 1);
+      break;
+    }
+  }
+  const from = chartBucketStart(start, grain);
+  const days = Math.round(
+    (parseDay(today).getTime() - parseDay(from).getTime()) / DAY_MS
+  ) + 1;
+  return { from, to: today, days };
+};
+const chartToday = (now = /* @__PURE__ */ new Date()) => toDay(now);
+export {
+  CHART_DAY_GRAIN_MAX_DAYS,
+  CHART_FILTER_MAX_LENGTH,
+  CHART_GRAINS,
+  CHART_GRAIN_DEFAULT,
+  CHART_ID_MAX_LENGTH,
+  CHART_OTHER_SERIES_KEY,
+  CHART_QUERY_MAX_LENGTH,
+  CHART_TOP_DEFAULT,
+  CHART_TOP_MAX,
+  CHART_UNKNOWN_SERIES_KEY,
+  CHART_WINDOW_AMOUNT_MAX,
+  CHART_WINDOW_DEFAULT,
+  CHART_WINDOW_UNITS,
+  chartBucketStart,
+  chartToday,
+  chartWindowRange
+};
+//# sourceMappingURL=chart-spec.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/charts/chart-spec.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 { LUCENE_QUERY_MAX_LENGTH } from '../search/parser.js'\n\n// ============================================================================\n// The chart query of a dashboard tile, and the result that the chart route of\n// accounts-backend gives for it. See\n// docs/superpowers/specs/2026-10-02-dashboard-chart-tiles-design.md.\n// ============================================================================\n\n/** The time buckets of a chart. A week starts on Monday (ISO). */\nexport const CHART_GRAINS = ['day', 'week', 'month'] as const\nexport type ChartGrain = (typeof CHART_GRAINS)[number]\n\n/** `d` is days, `w` is weeks and `m` is calendar months. */\nexport const CHART_WINDOW_UNITS = ['d', 'w', 'm'] as const\nexport type ChartWindowUnit = (typeof CHART_WINDOW_UNITS)[number]\n\n/** A window that ends today (UTC). \"The last 90 days\" is `{ amount: 90, unit: 'd' }`. */\nexport interface ChartWindow {\n  amount: number\n  unit: ChartWindowUnit\n}\n\n/**\n * One chart query. A tile stores this and never the data, so the chart\n * follows the window as the days go by.\n */\nexport interface ChartSpec {\n  /** A metric id of `CHART_METRICS`. */\n  metric: string\n  /** A dimension id of the metric. Each value of it is one series. */\n  by?: string\n  grain: ChartGrain\n  window: ChartWindow\n  /** Lucene source text over the filter fields of the metric. */\n  filter?: string\n  /** The number of series to show. Only with `by`. */\n  top?: number\n}\n\nexport const CHART_GRAIN_DEFAULT: ChartGrain = 'day'\nexport const CHART_WINDOW_DEFAULT: ChartWindow = { amount: 30, unit: 'd' }\nexport const CHART_TOP_DEFAULT = 10\nexport const CHART_TOP_MAX = 20\n\n/** The longest window, in days, for `every day`. */\nexport const CHART_DAY_GRAIN_MAX_DAYS = 366\n\n/**\n * The longest text of a whole chart query. The filter has its own limit,\n * `CHART_FILTER_MAX_LENGTH`.\n */\nexport const CHART_QUERY_MAX_LENGTH = 700\n\n/**\n * The longest filter of a chart query. It is the limit of the Lucene parser,\n * which checks every filter on every run.\n */\nexport const CHART_FILTER_MAX_LENGTH = LUCENE_QUERY_MAX_LENGTH\n\n/** The longest metric id or dimension id that a stored chart query holds. */\nexport const CHART_ID_MAX_LENGTH = 64\n\n/** The largest amount of a window, in its unit. */\nexport const CHART_WINDOW_AMOUNT_MAX = 9999\n\n/**\n * The series key of the sum of every series that is not in the top N. When a\n * real value of the dimension has this key, the key gets a `*`, so the keys\n * of a result stay unique.\n */\nexport const CHART_OTHER_SERIES_KEY = '(other)'\n\n/**\n * The series key of the rows with no value for the `by` dimension. It gets a\n * `*` the same way as `CHART_OTHER_SERIES_KEY`.\n */\nexport const CHART_UNKNOWN_SERIES_KEY = '(unknown)'\n\nexport interface ChartPoint {\n  /** The first day of the bucket, `YYYY-MM-DD`. */\n  ts: string\n  value: number\n}\n\nexport interface ChartSeries {\n  key: string\n  points: ChartPoint[]\n}\n\n/** `percent` is 0 to 100. */\nexport type ChartUnit = 'count' | 'bytes' | 'usd' | 'percent'\n\n/** The answer of `POST /api/hdp/charts/query`. */\nexport interface ChartResult {\n  metric: string\n  unit: ChartUnit\n  grain: ChartGrain\n  /** The first day that the query reads, `YYYY-MM-DD`, inclusive. */\n  from: string\n  /** The last day that the query reads, `YYYY-MM-DD`, inclusive. */\n  to: string\n  /**\n   * Sorted by the total of the series, the largest first. `(other)` is last.\n   * The keys are unique.\n   */\n  series: ChartSeries[]\n  /** True when the top N left out series. Their sum is the `(other)` series. */\n  truncated: boolean\n  bytesProcessed: number\n  /** When the result came from the cache: the time of the query, ISO. */\n  cachedAt?: string\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000\n\nconst toDay = (date: Date): string => date.toISOString().slice(0, 10)\n\nconst parseDay = (day: string): Date => new Date(`${day}T00:00:00Z`)\n\nconst addDays = (day: string, delta: number): string =>\n  toDay(new Date(parseDay(day).getTime() + delta * DAY_MS))\n\n/** The first day of the bucket of `day`, as BigQuery's `DATE_TRUNC` gives it. */\nexport const chartBucketStart = (day: string, grain: ChartGrain): string => {\n  const date = parseDay(day)\n  switch (grain) {\n    case 'day':\n      return day\n    case 'week': {\n      // getUTCDay: Sunday is 0. Monday starts the week.\n      const sinceMonday = (date.getUTCDay() + 6) % 7\n      return addDays(day, -sinceMonday)\n    }\n    case 'month':\n      return `${day.slice(0, 7)}-01`\n  }\n}\n\n/**\n * The days that a chart reads. The window ends on `today` and goes back by its\n * amount. The start moves back to the start of its bucket, so the first\n * bucket of the chart is complete.\n */\nexport const chartWindowRange = (\n  window: ChartWindow,\n  grain: ChartGrain,\n  today: string,\n): { from: string; to: string; days: number } => {\n  let start: string\n  switch (window.unit) {\n    case 'd':\n      start = addDays(today, -(window.amount - 1))\n      break\n    case 'w':\n      start = addDays(today, -(7 * window.amount - 1))\n      break\n    case 'm': {\n      const date = parseDay(today)\n      // Day 0 of a month is the last day of the month before. Thus a short\n      // month clamps the day, and 03-31 minus one month gives 02-28.\n      const shifted = new Date(\n        Date.UTC(date.getUTCFullYear(), date.getUTCMonth() - window.amount, 1),\n      )\n      const lastDay = new Date(\n        Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, 0),\n      ).getUTCDate()\n      shifted.setUTCDate(Math.min(date.getUTCDate(), lastDay))\n      start = addDays(toDay(shifted), 1)\n      break\n    }\n  }\n  const from = chartBucketStart(start, grain)\n  const days =\n    Math.round(\n      (parseDay(today).getTime() - parseDay(from).getTime()) / DAY_MS,\n    ) + 1\n  return { from, to: today, days }\n}\n\n/** Today in UTC, `YYYY-MM-DD`. */\nexport const chartToday = (now: Date = new Date()): string => toDay(now)\n"],
+  "mappings": "AAMA,SAAS,+BAA+B;AASjC,MAAM,eAAe,CAAC,OAAO,QAAQ,OAAO;AAI5C,MAAM,qBAAqB,CAAC,KAAK,KAAK,GAAG;AA0BzC,MAAM,sBAAkC;AACxC,MAAM,uBAAoC,EAAE,QAAQ,IAAI,MAAM,IAAI;AAClE,MAAM,oBAAoB;AAC1B,MAAM,gBAAgB;AAGtB,MAAM,2BAA2B;AAMjC,MAAM,yBAAyB;AAM/B,MAAM,0BAA0B;AAGhC,MAAM,sBAAsB;AAG5B,MAAM,0BAA0B;AAOhC,MAAM,yBAAyB;AAM/B,MAAM,2BAA2B;AAqCxC,MAAM,SAAS,KAAK,KAAK,KAAK;AAE9B,MAAM,QAAQ,CAAC,SAAuB,KAAK,YAAY,EAAE,MAAM,GAAG,EAAE;AAEpE,MAAM,WAAW,CAAC,QAAsB,oBAAI,KAAK,GAAG,GAAG,YAAY;AAEnE,MAAM,UAAU,CAAC,KAAa,UAC5B,MAAM,IAAI,KAAK,SAAS,GAAG,EAAE,QAAQ,IAAI,QAAQ,MAAM,CAAC;AAGnD,MAAM,mBAAmB,CAAC,KAAa,UAA8B;AAC1E,QAAM,OAAO,SAAS,GAAG;AACzB,UAAQ,OAAO;AAAA,IACb,KAAK;AACH,aAAO;AAAA,IACT,KAAK,QAAQ;AAEX,YAAM,eAAe,KAAK,UAAU,IAAI,KAAK;AAC7C,aAAO,QAAQ,KAAK,CAAC,WAAW;AAAA,IAClC;AAAA,IACA,KAAK;AACH,aAAO,GAAG,IAAI,MAAM,GAAG,CAAC,CAAC;AAAA,EAC7B;AACF;AAOO,MAAM,mBAAmB,CAC9B,QACA,OACA,UAC+C;AAC/C,MAAI;AACJ,UAAQ,OAAO,MAAM;AAAA,IACnB,KAAK;AACH,cAAQ,QAAQ,OAAO,EAAE,OAAO,SAAS,EAAE;AAC3C;AAAA,IACF,KAAK;AACH,cAAQ,QAAQ,OAAO,EAAE,IAAI,OAAO,SAAS,EAAE;AAC/C;AAAA,IACF,KAAK,KAAK;AACR,YAAM,OAAO,SAAS,KAAK;AAG3B,YAAM,UAAU,IAAI;AAAA,QAClB,KAAK,IAAI,KAAK,eAAe,GAAG,KAAK,YAAY,IAAI,OAAO,QAAQ,CAAC;AAAA,MACvE;AACA,YAAM,UAAU,IAAI;AAAA,QAClB,KAAK,IAAI,QAAQ,eAAe,GAAG,QAAQ,YAAY,IAAI,GAAG,CAAC;AAAA,MACjE,EAAE,WAAW;AACb,cAAQ,WAAW,KAAK,IAAI,KAAK,WAAW,GAAG,OAAO,CAAC;AACvD,cAAQ,QAAQ,MAAM,OAAO,GAAG,CAAC;AACjC;AAAA,IACF;AAAA,EACF;AACA,QAAM,OAAO,iBAAiB,OAAO,KAAK;AAC1C,QAAM,OACJ,KAAK;AAAA,KACF,SAAS,KAAK,EAAE,QAAQ,IAAI,SAAS,IAAI,EAAE,QAAQ,KAAK;AAAA,EAC3D,IAAI;AACN,SAAO,EAAE,MAAM,IAAI,OAAO,KAAK;AACjC;AAGO,MAAM,aAAa,CAAC,MAAY,oBAAI,KAAK,MAAc,MAAM,GAAG;",
+  "names": []
+}

package/dist/charts/index.d.ts

@@ -0,0 +1,3 @@
+export { CHART_METRICS, type ChartDimensionSpec, type ChartMetricSpec, findChartDimension, findChartMetric, } from './chart-metrics.js';
+export { type ChartQueryCheck, ChartQueryError, type ChartQueryErrorKind, type ChartQueryOptions, formatChartSpec, isChartQueryError, parseChartQuery, readChartSpec, validateChartSpec, } from './chart-query.js';
+export { CHART_DAY_GRAIN_MAX_DAYS, CHART_FILTER_MAX_LENGTH, CHART_GRAIN_DEFAULT, CHART_GRAINS, CHART_ID_MAX_LENGTH, CHART_OTHER_SERIES_KEY, CHART_QUERY_MAX_LENGTH, CHART_TOP_DEFAULT, CHART_TOP_MAX, CHART_UNKNOWN_SERIES_KEY, CHART_WINDOW_AMOUNT_MAX, CHART_WINDOW_DEFAULT, CHART_WINDOW_UNITS, type ChartGrain, type ChartPoint, type ChartResult, type ChartSeries, type ChartSpec, type ChartUnit, type ChartWindow, type ChartWindowUnit, chartBucketStart, chartToday, chartWindowRange, } from './chart-spec.js';