@camunda/ccma-shared-types 5.0.0 → 7.0.0

package/dist/charts/chart-metrics.js

@@ -0,0 +1,188 @@
+const CLUSTER_DIMENSION = {
+  id: "cluster",
+  label: "Cluster",
+  description: "The cluster id."
+};
+const ORG_DIMENSION = {
+  id: "org",
+  label: "Organization",
+  description: "The organization id."
+};
+const ORG_NAME_DIMENSION = {
+  id: "orgName",
+  label: "Organization name",
+  description: "The name of the organization of the cluster. Prod clusters only: on other stages it is (unknown)."
+};
+const ORG_ID_FILTER = {
+  field: "orgId",
+  label: "Organization id",
+  description: "Exact organization id.",
+  type: "string",
+  capabilities: ["match"],
+  example: "orgId:3f2c\u2026"
+};
+const CLUSTER_ID_FILTER = {
+  field: "clusterId",
+  label: "Cluster id",
+  description: "Exact cluster id.",
+  type: "string",
+  capabilities: ["match"],
+  example: "clusterId:9a1b\u2026"
+};
+const VALUE_METRIC_DIMENSIONS = [
+  CLUSTER_DIMENSION,
+  ORG_DIMENSION,
+  ORG_NAME_DIMENSION,
+  {
+    id: "salesPlan",
+    label: "Sales plan",
+    description: "The sales plan of the organization on that day."
+  },
+  {
+    id: "env",
+    label: "Environment",
+    description: "Production or development cluster."
+  }
+];
+const VALUE_METRIC_FILTERS = [
+  ORG_ID_FILTER,
+  CLUSTER_ID_FILTER,
+  {
+    field: "salesPlan",
+    label: "Sales plan",
+    description: "Sales plan name, case-insensitive. Use * as a wildcard.",
+    type: "string",
+    capabilities: ["match"],
+    example: "salesPlan:enterprise*"
+  },
+  {
+    field: "env",
+    label: "Environment",
+    description: "Production or development cluster.",
+    type: "enum",
+    capabilities: ["match"],
+    enumValues: ["production", "development"],
+    example: "env:production"
+  }
+];
+const ALL_GRAINS = ["day", "week", "month"];
+const VALUE_METRIC_GRAINS = ALL_GRAINS;
+const LARGE_TABLE_MAX_WINDOW_DAYS = 400;
+const gaugeMetric = (id, label, unit, stat, description) => ({
+  id,
+  label,
+  description,
+  unit,
+  dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],
+  filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],
+  grains: ALL_GRAINS,
+  maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,
+  stat
+});
+const VALUE_METRIC_MAX_WINDOW_DAYS = 762;
+const valueMetric = (id, label, description) => ({
+  id,
+  label,
+  description,
+  unit: "count",
+  dimensions: VALUE_METRIC_DIMENSIONS,
+  filters: VALUE_METRIC_FILTERS,
+  grains: VALUE_METRIC_GRAINS,
+  maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,
+  stat: { series: "sum", window: "sum" }
+});
+const CHART_METRICS = [
+  valueMetric(
+    "processInstances",
+    "Process instances",
+    "Process instances that started, from the HDP value metrics. The sum over each bucket."
+  ),
+  valueMetric(
+    "decisionInstances",
+    "Decision instances",
+    "Decision instances that ran, from the HDP value metrics. The sum over each bucket."
+  ),
+  valueMetric(
+    "taskUsers",
+    "Task users",
+    "Task users, from the HDP value metrics. The sum of the daily values over each bucket, as on the Value metrics tab."
+  ),
+  gaugeMetric(
+    "activeTenants",
+    "Active tenants",
+    "count",
+    { series: "sum", window: "max" },
+    "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."
+  ),
+  gaugeMetric(
+    "clusterLoad",
+    "Cluster load",
+    "percent",
+    { series: "mean", window: "mean" },
+    "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."
+  ),
+  gaugeMetric(
+    "diskUsedBytes",
+    "Elasticsearch disk used",
+    "bytes",
+    { series: "sum", window: "max" },
+    "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."
+  ),
+  {
+    id: "hostingCost",
+    label: "Hosting cost",
+    description: "The loaded hosting cost of the clusters, in US dollars, from the cloud bill. The sum over each bucket. The bill holds every stage.",
+    unit: "usd",
+    dimensions: [CLUSTER_DIMENSION, ORG_DIMENSION, ORG_NAME_DIMENSION],
+    filters: [ORG_ID_FILTER, CLUSTER_ID_FILTER],
+    grains: ALL_GRAINS,
+    maxWindowDays: VALUE_METRIC_MAX_WINDOW_DAYS,
+    stat: { series: "sum", window: "sum" }
+  },
+  {
+    id: "changeEvents",
+    label: "Change events",
+    description: "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.",
+    unit: "count",
+    dimensions: [
+      { id: "entity", label: "Entity", description: "For example cluster." },
+      {
+        id: "operation",
+        label: "Operation",
+        description: "insert, update or delete."
+      }
+    ],
+    filters: [
+      {
+        field: "entity",
+        label: "Entity",
+        description: "The entity, case-insensitive. Use * as a wildcard.",
+        type: "string",
+        capabilities: ["match"],
+        example: "entity:cluster"
+      },
+      {
+        field: "operation",
+        label: "Operation",
+        description: "The operation.",
+        type: "enum",
+        capabilities: ["match"],
+        enumValues: ["insert", "update", "delete"],
+        example: "operation:delete"
+      }
+    ],
+    grains: ALL_GRAINS,
+    maxWindowDays: LARGE_TABLE_MAX_WINDOW_DAYS,
+    stat: { series: "sum", window: "sum" }
+  }
+];
+const findChartMetric = (id, metrics = CHART_METRICS) => metrics.find((metric) => metric.id.toLowerCase() === id.toLowerCase());
+const findChartDimension = (metric, id) => metric.dimensions.find(
+  (dimension) => dimension.id.toLowerCase() === id.toLowerCase()
+);
+export {
+  CHART_METRICS,
+  findChartDimension,
+  findChartMetric
+};
+//# sourceMappingURL=chart-metrics.js.map

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": "AA4CA,MAAM,oBAAwC;AAAA,EAC5C,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AACf;AAEA,MAAM,gBAAoC;AAAA,EACxC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AACf;AAOA,MAAM,qBAAyC;AAAA,EAC7C,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aACE;AACJ;AAEA,MAAM,gBAAiC;AAAA,EACrC,OAAO;AAAA,EACP,OAAO;AAAA,EACP,aAAa;AAAA,EACb,MAAM;AAAA,EACN,cAAc,CAAC,OAAO;AAAA,EACtB,SAAS;AACX;AAEA,MAAM,oBAAqC;AAAA,EACzC,OAAO;AAAA,EACP,OAAO;AAAA,EACP,aAAa;AAAA,EACb,MAAM;AAAA,EACN,cAAc,CAAC,OAAO;AAAA,EACtB,SAAS;AACX;AAEA,MAAM,0BAAyD;AAAA,EAC7D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,aAAa;AAAA,EACf;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,aAAa;AAAA,EACf;AACF;AAEA,MAAM,uBAAmD;AAAA,EACvD;AAAA,EACA;AAAA,EACA;AAAA,IACE,OAAO;AAAA,IACP,OAAO;AAAA,IACP,aAAa;AAAA,IACb,MAAM;AAAA,IACN,cAAc,CAAC,OAAO;AAAA,IACtB,SAAS;AAAA,EACX;AAAA,EACA;AAAA,IACE,OAAO;AAAA,IACP,OAAO;AAAA,IACP,aAAa;AAAA,IACb,MAAM;AAAA,IACN,cAAc,CAAC,OAAO;AAAA,IACtB,YAAY,CAAC,cAAc,aAAa;AAAA,IACxC,SAAS;AAAA,EACX;AACF;AAEA,MAAM,aAAoC,CAAC,OAAO,QAAQ,OAAO;AACjE,MAAM,sBAAsB;AAQ5B,MAAM,8BAA8B;AAGpC,MAAM,cAAc,CAClB,IACA,OACA,MACA,MACA,iBACqB;AAAA,EACrB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY,CAAC,mBAAmB,eAAe,kBAAkB;AAAA,EACjE,SAAS,CAAC,eAAe,iBAAiB;AAAA,EAC1C,QAAQ;AAAA,EACR,eAAe;AAAA,EACf;AACF;AAOA,MAAM,+BAA+B;AAErC,MAAM,cAAc,CAClB,IACA,OACA,iBACqB;AAAA,EACrB;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,eAAe;AAAA,EACf,MAAM,EAAE,QAAQ,OAAO,QAAQ,MAAM;AACvC;AAEO,MAAM,gBAA4C;AAAA,EACvD;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA,EAAE,QAAQ,OAAO,QAAQ,MAAM;AAAA,IAC/B;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA,EAAE,QAAQ,QAAQ,QAAQ,OAAO;AAAA,IACjC;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA,EAAE,QAAQ,OAAO,QAAQ,MAAM;AAAA,IAC/B;AAAA,EACF;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,aACE;AAAA,IACF,MAAM;AAAA,IACN,YAAY,CAAC,mBAAmB,eAAe,kBAAkB;AAAA,IACjE,SAAS,CAAC,eAAe,iBAAiB;AAAA,IAC1C,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,MAAM,EAAE,QAAQ,OAAO,QAAQ,MAAM;AAAA,EACvC;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,aACE;AAAA,IACF,MAAM;AAAA,IACN,YAAY;AAAA,MACV,EAAE,IAAI,UAAU,OAAO,UAAU,aAAa,uBAAuB;AAAA,MACrE;AAAA,QACE,IAAI;AAAA,QACJ,OAAO;AAAA,QACP,aAAa;AAAA,MACf;AAAA,IACF;AAAA,IACA,SAAS;AAAA,MACP;AAAA,QACE,OAAO;AAAA,QACP,OAAO;AAAA,QACP,aAAa;AAAA,QACb,MAAM;AAAA,QACN,cAAc,CAAC,OAAO;AAAA,QACtB,SAAS;AAAA,MACX;AAAA,MACA;AAAA,QACE,OAAO;AAAA,QACP,OAAO;AAAA,QACP,aAAa;AAAA,QACb,MAAM;AAAA,QACN,cAAc,CAAC,OAAO;AAAA,QACtB,YAAY,CAAC,UAAU,UAAU,QAAQ;AAAA,QACzC,SAAS;AAAA,MACX;AAAA,IACF;AAAA,IACA,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,MAAM,EAAE,QAAQ,OAAO,QAAQ,MAAM;AAAA,EACvC;AACF;AAGO,MAAM,kBAAkB,CAC7B,IACA,UAAsC,kBAEtC,QAAQ,KAAK,CAAC,WAAW,OAAO,GAAG,YAAY,MAAM,GAAG,YAAY,CAAC;AAGhE,MAAM,qBAAqB,CAChC,QACA,OAEA,OAAO,WAAW;AAAA,EAChB,CAAC,cAAc,UAAU,GAAG,YAAY,MAAM,GAAG,YAAY;AAC/D;",
+  "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