drizzle-cube 0.7.0 → 0.8.0

package/dist/adapters/{utils-tjiwXFnP.js → utils-DkmShl5f.js}

@@ -542,7 +542,7 @@ var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescr
 	"chart.configText.add_2_or_more_measures_they_become_the_x_axis_categories_in_the_order_li": "Add 2 or more measures — they become the X-axis categories in the order listed",
 	"chart.configText.add_an_accent_colored_border_on_one_side_of_the_content": "Add an accent-colored border on one side of the content",
 	"chart.configText.all_fields_to_display_as_columns": "All fields to display as columns",
-	"chart.configText.array_of_value_0_1_fraction_color_bands_shown_as_outer_arc_markers": "Array of {value (0–1 fraction), color} bands shown as outer arc markers",
+	"chart.gauge.thresholds.description": "Each band runs from its value up to the next one. Values are on the gauge’s own scale.",
 	"chart.configText.axes_categories": "Axes (Categories)",
 	"chart.configText.bubble_colour": "Bubble Colour",
 	"chart.configText.bubble_labels": "Bubble Labels",
@@ -714,6 +714,9 @@ var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescr
 	"server.errors.retentionValidationFailed": "Retention validation failed: {errors}",
 	"server.errors.cubeRefUnresolved": "{cubeName}.joins.{joinName}: target cube '{targetCube}' is not registered",
 	"server.errors.unresolvedCubeRefs": "Unresolved cube references:\n{details}",
+	"server.errors.cubeSetIdEmpty": "Cube set id must not be empty — the empty id is reserved for the base cube set",
+	"server.errors.cubeSetNotFound": "No cube set registered for '{setId}'",
+	"server.errors.attributeIdRequired": "Attribute definitions must have a non-empty id",
 	"server.errors.calculatedMeasureValidation": "Calculated measure validation failed for cube '{cubeName}':\n{details}",
 	"server.errors.queryValidationFailed": "Query validation failed: {errors}",
 	"server.errors.queryContainsMultipleModes": "Query contains multiple query modes: {modes}",
@@ -1585,7 +1588,11 @@ var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescr
 	"chart.option.proportionBarLabels.label": "Show labels",
 	"chart.runtime.summarySince": "since {period}",
 	"chart.option.showPoints.label": "Show data points",
-	"chart.option.showPoints.description": "Draw a marker at every data point. Turn off for dense series, where the markers obscure the line"
+	"chart.option.showPoints.description": "Draw a marker at every data point. Turn off for dense series, where the markers obscure the line",
+	"chart.gauge.thresholds.from": "Band starts at",
+	"chart.gauge.thresholds.colour": "Band colour",
+	"chart.gauge.thresholds.add": "Add band",
+	"chart.gauge.thresholds.remove": "Remove band"
 };
 function f(e, t) {
 	let n = d[e];
@@ -6421,13 +6428,13 @@ function Mo(e, t, n) {
 //#endregion
 //#region src/server/query-handlers.ts
 var No = fo.messages[0]?.content.text ?? "";
-async function Po(e, t) {
+async function Po(e, t, n) {
 	return {
-		cubes: jo(e.getMetadata(), {
-			topic: t.topic,
-			intent: t.intent,
-			limit: t.limit,
-			minScore: t.minScore
+		cubes: jo(e.getMetadata(t), {
+			topic: n.topic,
+			intent: n.intent,
+			limit: n.limit,
+			minScore: n.minScore
 		}),
 		queryLanguageReference: co,
 		dateFilteringGuide: No
@@ -6480,7 +6487,7 @@ function zo(e, t) {
 	return r;
 }
 async function Bo(e, t, n) {
-	let r = Fo(n.query), i = e.validateQuery(r);
+	let r = Fo(n.query), i = e.validateQuery(r, t);
 	if (!i.isValid) throw Error(`Query validation failed: ${i.errors.join(", ")}`);
 	let a = await e.executeMultiCubeQuery(r, t);
 	return {
@@ -7214,9 +7221,9 @@ function ys(e, t, n) {
 		return;
 	}
 }
-function Y(e, t, n) {
-	let r = t.validateQuery(e);
-	if (!r.isValid) throw Error(`${n} validation failed: ${r.errors.join(", ")}`);
+function Y(e, t, n, r) {
+	let i = n.validateQuery(e, t);
+	if (!i.isValid) throw Error(`${r} validation failed: ${i.errors.join(", ")}`);
 }
 async function X(e, t, n) {
 	return {
@@ -7289,7 +7296,7 @@ async function ws(e, t, n) {
 	}[vs(e)]();
 }
 async function Ts(e, t, n) {
-	Y(e, n, "Query");
+	Y(e, t, n, "Query");
 	let r = bs(e), i = r.length > 1, { sqlResult: a, analysis: o } = await X(e, t, n), s = r.map((t) => ({
 		cube: t,
 		query: {
@@ -7315,7 +7322,7 @@ async function Ts(e, t, n) {
 	});
 }
 async function Es(e, t, n) {
-	Y(e, n, "Comparison query");
+	Y(e, t, n, "Comparison query");
 	let r = bs(e), i = r.length > 1, { sqlResult: a, analysis: o } = await X(e, t, n), s = e.timeDimensions?.find((e) => e.compareDateRange && e.compareDateRange.length >= 2), c = s ? {
 		timeDimension: s.dimension,
 		granularity: s.granularity || "day",
@@ -7464,7 +7471,7 @@ async function js(e, t, n, r) {
 	}) };
 }
 async function Ms(e, t, n) {
-	Y(e, n, "Funnel query");
+	Y(e, t, n, "Funnel query");
 	let r = xs(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.funnel;
 	return $({
 		mode: "funnel",
@@ -7491,7 +7498,7 @@ async function Ms(e, t, n) {
 	});
 }
 async function Ns(e, t, n) {
-	Y(e, n, "Flow query");
+	Y(e, t, n, "Flow query");
 	let r = Ss(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.flow;
 	return $({
 		mode: "flow",
@@ -7513,7 +7520,7 @@ async function Ns(e, t, n) {
 	});
 }
 async function Ps(e, t, n) {
-	Y(e, n, "Retention query");
+	Y(e, t, n, "Retention query");
 	let r = Cs(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.retention;
 	return $({
 		mode: "retention",
@@ -7535,13 +7542,13 @@ async function Ps(e, t, n) {
 		}
 	});
 }
-async function Fs(e, t) {
-	return es(e.getMetadata(), t.naturalLanguage, t.cube);
+async function Fs(e, t, n) {
+	return es(e.getMetadata(t), n.naturalLanguage, n.cube);
 }
 async function Is(e, t, n) {
-	let r = e.getMetadata(), i = await fs(t.query, r);
-	if (i.isValid && n) try {
-		let r = Fo(i.correctedQuery ?? t.query), a = await e.dryRun(r, n);
+	let r = e.getMetadata(t), i = await fs(n.query, r);
+	if (i.isValid) try {
+		let r = Fo(i.correctedQuery ?? n.query), a = await e.dryRun(r, t);
 		return {
 			...i,
 			sql: a

package/dist/adapters/utils.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./utils-C5FLHK04.cjs");exports.buildTransformedQuery=e.t,exports.calculateQueryComplexity=e.n,exports.formatCubeResponse=e.r,exports.formatErrorResponse=e.i,exports.formatMetaResponse=e.a,exports.formatSqlResponse=e.o,exports.formatSqlString=e.S,exports.generateRequestId=e.s,exports.getDatabaseType=e.c,exports.handleBatchRequest=e.l,exports.handleDiscover=e.p,exports.handleDryRun=e.u,exports.handleLoad=e.m,exports.handleSuggest=e.d,exports.handleValidate=e.f,exports.normalizeQueryFields=e.h;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./utils-BY0-KFyI.cjs");exports.buildTransformedQuery=e.t,exports.calculateQueryComplexity=e.n,exports.formatCubeResponse=e.r,exports.formatErrorResponse=e.i,exports.formatMetaResponse=e.a,exports.formatSqlResponse=e.o,exports.formatSqlString=e.S,exports.generateRequestId=e.s,exports.getDatabaseType=e.c,exports.handleBatchRequest=e.l,exports.handleDiscover=e.p,exports.handleDryRun=e.u,exports.handleLoad=e.m,exports.handleSuggest=e.d,exports.handleValidate=e.f,exports.normalizeQueryFields=e.h;

package/dist/adapters/utils.d.ts

@@ -354,11 +354,11 @@ export interface ValidateRequest {
 /**
  * Handle /suggest endpoint - generate query from natural language
  */
-export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, body: SuggestRequest): Promise<QuerySuggestion>;
+export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: SuggestRequest): Promise<QuerySuggestion>;
 /**
  * Handle /validate endpoint - validate query with corrections
  */
-export declare function handleValidate(semanticLayer: SemanticLayerCompiler, body: ValidateRequest, securityContext?: SecurityContext): Promise<AIValidationResult & {
+export declare function handleValidate(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: ValidateRequest): Promise<AIValidationResult & {
     sql?: {
         sql: string;
         params?: any[];

package/dist/adapters/utils.js

@@ -1,2 +1,2 @@
-import { S as e, a as t, c as n, d as r, f as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./utils-tjiwXFnP.js";
+import { S as e, a as t, c as n, d as r, f as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./utils-DkmShl5f.js";
 export { m as buildTransformedQuery, l as calculateQueryComplexity, f as formatCubeResponse, o as formatErrorResponse, t as formatMetaResponse, u as formatSqlResponse, e as formatSqlString, p as generateRequestId, n as getDatabaseType, s as handleBatchRequest, d as handleDiscover, h as handleDryRun, c as handleLoad, r as handleSuggest, i as handleValidate, a as normalizeQueryFields };

package/dist/cjs/adapters/core/http-port.d.ts

@@ -7,8 +7,16 @@
  * (Hono/Next.js). Implementations are constructed per request by each adapter.
  *
  * This interface is public — third parties implement it to build adapters for
- * other frameworks. Add new capabilities as optional members or via a separate
- * extension interface; a new required member is a breaking change.
+ * other frameworks. Prefer optional members or a separate extension interface
+ * for new capabilities, because a new required member is a breaking change for
+ * those adapters.
+ *
+ * `setHeader` was promoted from {@link McpHttpPort} to this interface in the
+ * per-tenant cube sets release, so that the core can stamp `Cache-Control` on
+ * every REST response (see {@link withRestCacheHeaders}). Every REST body is now
+ * tenant-scoped, and that guarantee cannot be left to each adapter. The break is
+ * accepted for this release: third-party REST-only adapters must add
+ * `setHeader`, which all four first-party adapters already implemented.
  */
 export interface HttpPort<TRes> {
     /** Read a request header by (case-insensitive) name. Synchronous. */
@@ -17,23 +25,42 @@ export interface HttpPort<TRes> {
     getBody(): Promise<unknown>;
     /** Read a raw query-string value by name (used by GET). */
     getQueryParam(name: string): string | undefined;
+    /** Set a response header. Must be called before `send`/`sendSse`/`sendEmpty`. */
+    setHeader(name: string, value: string): void;
     /** Send a response with the given status and JSON body; returns the framework's response value. */
     send(status: number, body: unknown): TRes;
 }
 /**
- * Extension of {@link HttpPort} for the MCP POST handler, which needs to set
- * response headers (WWW-Authenticate, MCP-Session-Id), emit a single-event SSE
- * response, and send an empty-body acknowledgement (202 for notifications).
+ * Extension of {@link HttpPort} for the MCP POST handler, which needs to emit a
+ * single-event SSE response and send an empty-body acknowledgement (202 for
+ * notifications).
  *
  * Kept separate from the minimal REST port so third-party adapters only
  * implement these when they wire up MCP. New required members on this interface
  * are still a breaking change for MCP-capable adapters.
  */
 export interface McpHttpPort<TRes> extends HttpPort<TRes> {
-    /** Set a response header. Must be called before `send`/`sendSse`/`sendEmpty`. */
-    setHeader(name: string, value: string): void;
     /** Send a single-event SSE response (status 200): write the pre-serialized body, then end. */
     sendSse(status: number, body: string): TRes;
     /** Send an empty-body response (no JSON), e.g. a 202 notification acknowledgement. */
     sendEmpty(status: number): TRes;
 }
+/**
+ * `Cache-Control` stamped on every REST response.
+ *
+ * Every REST body varies by tenant: `/meta` returns the caller's cube set, and
+ * `/load`, `/sql`, `/dry-run`, `/batch` and `/explain` return that tenant's data
+ * or SQL. With no `Cache-Control` a shared cache may store and reuse these
+ * responses heuristically, which would cross-serve one tenant's cubes to
+ * another. `private` bars shared caches; `no-store` bars storage entirely.
+ */
+export declare const REST_CACHE_CONTROL = "private, no-store";
+/**
+ * Wrap a port so every response it sends carries {@link REST_CACHE_CONTROL}.
+ *
+ * Applied once over the whole REST surface in `createCubeHttpHandler`, not per
+ * route, so no endpoint can forget it — including the 400/500 error paths.
+ * Deliberately NOT applied to MCP: its SSE responses set their own
+ * `Cache-Control`, and JSON-RPC POSTs are not heuristically cacheable.
+ */
+export declare function withRestCacheHeaders<TRes>(port: HttpPort<TRes>): HttpPort<TRes>;

package/dist/cjs/adapters/core/index.d.ts

@@ -6,6 +6,7 @@
  * {@link createCubeHttpHandler}.
  */
 export type { HttpPort, McpHttpPort } from './http-port.js';
+export { withRestCacheHeaders, REST_CACHE_CONTROL } from './http-port.js';
 export { withLocaleFromHeaders, resolveSecurityContext, type HeaderReader, type BaseSecurityContextThunk } from './security-context.js';
 export { createCubeHttpHandler, type CubeHttpHandler, type CubeHttpHandlerOptions } from './cube-http-handler.js';
 export type { RestHandlers } from './rest-handlers.js';

package/dist/cjs/adapters/core/rest-handlers.d.ts

@@ -3,7 +3,7 @@ import { HttpPort } from './http-port.js';
 import { BaseSecurityContextThunk } from './security-context.js';
 /** REST handlers keyed by endpoint; each closes over the shared semantic layer. */
 export interface RestHandlers {
-    handleMetaGet<TRes>(port: HttpPort<TRes>): TRes;
+    handleMetaGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleSqlGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleSqlPost<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleDryRunGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;

package/dist/cjs/adapters/express/index.d.ts

@@ -2,15 +2,24 @@ import { Router, Request, Response, Express } from 'express';
 import { CorsOptions } from 'cors';
 import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
 import { AgentConfig } from '../../server/agent/types.js';
+import { SemanticLayerCompiler } from '../../server/compiler.js';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { MySql2Database } from 'drizzle-orm/mysql2';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 import { MCPOptions } from '../utils.js';
 export interface ExpressAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Pre-configured SemanticLayerCompiler instance.
+     * When provided, skips creating a new compiler and cube registration (caller
+     * manages it). Required to use per-tenant cube sets, since the caller must own
+     * the compiler to call `registerCubeSet` — see docs/per-tenant-cube-sets.md.
      */
-    cubes: Cube[];
+    semanticLayer?: SemanticLayerCompiler;
+    /**
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided.
+     */
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/fastify/index.d.ts

@@ -2,15 +2,24 @@ import { FastifyPluginCallback, FastifyRequest, FastifyInstance } from 'fastify'
 import { FastifyCorsOptions } from '@fastify/cors';
 import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
 import { AgentConfig } from '../../server/agent/types.js';
+import { SemanticLayerCompiler } from '../../server/compiler.js';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { MySql2Database } from 'drizzle-orm/mysql2';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 import { MCPOptions } from '../utils.js';
 export interface FastifyAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Pre-configured SemanticLayerCompiler instance.
+     * When provided, skips creating a new compiler and cube registration (caller
+     * manages it). Required to use per-tenant cube sets, since the caller must own
+     * the compiler to call `registerCubeSet` — see docs/per-tenant-cube-sets.md.
      */
-    cubes: Cube[];
+    semanticLayer?: SemanticLayerCompiler;
+    /**
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided.
+     */
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/mcp-tools-handlers.d.ts

@@ -6,9 +6,16 @@ export interface CubeToolHandlerDeps {
     wrapContent: (result: unknown) => MCPToolResult;
     wrapError: (error: unknown) => MCPToolResult;
 }
-/** Execute the `discover` tool. */
-export declare function runDiscoverTool(deps: CubeToolHandlerDeps, args: unknown): Promise<MCPToolResult>;
-/** Execute the `validate` tool — security context is optional (SQL omitted without auth). */
+/**
+ * Execute the `discover` tool. Reads the caller's cube set, so it resolves a
+ * security context first — discovery has no unauthenticated mode.
+ */
+export declare function runDiscoverTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;
+/**
+ * Execute the `validate` tool. The security context is required: validation is
+ * against the caller's cube set, so a caller whose context cannot be resolved
+ * gets an error rather than a base-set answer with the SQL omitted.
+ */
 export declare function runValidateTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;
 /**
  * Execute the `load` / `chart` tools. Both run the same query path; `chart`

package/dist/cjs/adapters/mcp-transport.d.ts

@@ -172,5 +172,16 @@ export declare function resolveMcpResources(resources?: MCPResourceResolver): MC
  *   project-specific guidance like custom cube semantics).
  */
 export declare function resolveMcpInstructions(instructions?: MCPInstructionsResolver): string;
-export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler): MCPResource;
-export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, resources?: MCPResourceResolver): MCPResource[];
+/**
+ * The `drizzle-cube://schema` resource: this caller's cube metadata as JSON.
+ *
+ * Its body is tenant-specific, so it must be built per request under the
+ * caller's security context. Building it once at handler construction — as this
+ * used to be — would freeze every tenant's view to the base set.
+ */
+export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext): MCPResource;
+/**
+ * Static resources plus this caller's schema resource. Call per request, never
+ * at setup time — see {@link buildMcpSchemaResource}.
+ */
+export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, resources?: MCPResourceResolver): MCPResource[];

package/dist/cjs/adapters/nextjs/index.d.ts

@@ -26,9 +26,12 @@ export interface NextCorsOptions {
 }
 export interface NextAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided — `createSemanticLayer` returns
+     * an injected compiler untouched, so a caller managing their own (which
+     * per-tenant cube sets require) supplies no cubes here.
      */
-    cubes: Cube[];
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/utils.d.ts

@@ -354,11 +354,11 @@ export interface ValidateRequest {
 /**
  * Handle /suggest endpoint - generate query from natural language
  */
-export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, body: SuggestRequest): Promise<QuerySuggestion>;
+export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: SuggestRequest): Promise<QuerySuggestion>;
 /**
  * Handle /validate endpoint - validate query with corrections
  */
-export declare function handleValidate(semanticLayer: SemanticLayerCompiler, body: ValidateRequest, securityContext?: SecurityContext): Promise<AIValidationResult & {
+export declare function handleValidate(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: ValidateRequest): Promise<AIValidationResult & {
     sql?: {
         sql: string;
         params?: any[];

package/dist/cjs/client/charts/chartConfigs.d.ts

@@ -28,7 +28,7 @@ export interface DisplayOptionConfig {
     /** Display label for the option */
     label: string;
     /** Type of input control to render */
-    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup';
+    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup' | 'thresholdBands';
     /** Default value for the option */
     defaultValue?: any;
     /** Placeholder text for string/number inputs */

package/dist/cjs/client/components/charts/GaugeChart.d.ts

@@ -1,4 +1,12 @@
 import { default as React } from 'react';
 import { ChartProps } from '../../types.js';
+/**
+ * Gauge chart: a 270° dial whose arc *is* the threshold banding — one thick,
+ * rounded segment per threshold with a small gap between them — read by a
+ * tapered needle, with numeric scale labels at the band boundaries and the
+ * measure label + value stacked below the centre.
+ *
+ * All geometry lives in `gaugeChartHelpers.ts`; this component only renders it.
+ */
 declare const GaugeChart: React.MemoExoticComponent<({ data, chartConfig, displayConfig, height, }: ChartProps) => React.JSX.Element>;
 export default GaugeChart;

package/dist/cjs/client/components/charts/gaugeChartHelpers.d.ts

@@ -1,36 +1,141 @@
 import { AxisFormatConfig, ThresholdBand } from '../../types.js';
 /**
- * Co-located helpers for GaugeChart: pure geometry/value math and threshold
- * parsing extracted from the component so the render body stays flat. Pure
- * extraction — no behaviour change.
+ * Co-located geometry/value maths for {@link GaugeChart}.
+ *
+ * Everything here is pure so the component stays declarative: it reads a
+ * layout, a list of band segments, a list of scale ticks and a needle path,
+ * then renders them.
+ *
+ * ## Angle convention
+ * d3-shape's: `0` points at 12 o'clock and positive angles run clockwise. The
+ * dial sweeps 270°, from `START_ANGLE` (-135°, lower-left) to `END_ANGLE`
+ * (+135°, lower-right).
+ *
+ * ## Threshold semantics
+ * A {@link ThresholdBand}'s `value` is the **lower bound** of its band, as a
+ * 0–1 fraction of the min→max range. So `[{0, red}, {0.5, amber}, {0.7, green}]`
+ * paints 0–50% red, 50–70% amber and 70–100% green. This matches
+ * {@link resolveColor}, and the invariant
+ * `bandContaining(f).color === resolveColor(f)` holds for every `f` in [0, 1).
  */
+/** Dial start: -135°, lower-left. */
 export declare const START_ANGLE: number;
+/** Dial end: +135°, lower-right. */
 export declare const END_ANGLE: number;
-export declare const TRACK_COLOR = "#e2e8f0";
-export declare const DEFAULT_FILL = "#6366f1";
+/** Total dial sweep in radians (270°). */
+export declare const ANGLE_SPAN: number;
+/** Neutral band colour for the region below every configured threshold. */
+export declare const DEFAULT_FILL = "var(--dc-accent)";
+/** Angular gap rendered between adjacent band segments (radians, ~2.3°). */
+export declare const BAND_GAP_RADIANS = 0.04;
+/**
+ * Height of the 270° arc's bounding box as a multiple of its radius.
+ * The arc spans y from `-r` (top) to `+r·cos45°` (the two lower tips).
+ */
+export declare const ARC_BBOX_HEIGHT_RATIO: number;
+/** Width of the 270° arc's bounding box as a multiple of its radius. */
+export declare const ARC_BBOX_WIDTH_RATIO = 2;
 export declare function parseNum(v: unknown): number | null;
 export declare function clamp(v: number, lo: number, hi: number): number;
+/** A finite `value`, or `fallback` when it is undefined / NaN / infinite. */
+export declare function finiteOr(value: number | undefined | null, fallback: number): number;
+/** Map a 0–1 fraction of the range onto its dial angle. */
+export declare function fractionToAngle(fraction: number): number;
 export declare function valueToAngle(value: number, min: number, max: number): number;
+/** Cartesian point at `angle`/`radius` in the d3 angle convention. */
+export declare function polarPoint(angle: number, radius: number): {
+    x: number;
+    y: number;
+};
 export declare function resolveColor(fraction: number, thresholds: ThresholdBand[]): string;
-export declare function buildArcPath(innerRadius: number, outerRadius: number, startAngle: number, endAngle: number): string;
+export declare function buildArcPath(innerRadius: number, outerRadius: number, startAngle: number, endAngle: number, cornerRadius?: number): string;
 /** Parse the displayConfig.thresholds value (array or JSON string) into bands. */
 export declare function parseThresholds(raw: unknown): ThresholdBand[];
+/** Clamp threshold fractions into [0, 1] and sort them ascending. */
+export declare function normalizeThresholds(thresholds: ThresholdBand[]): ThresholdBand[];
 export interface ThresholdArcBand {
     color: string;
-    start: number;
-    end: number;
+    /** Lower bound of the band, as a 0–1 fraction of the min→max range. */
+    startFraction: number;
+    /** Upper bound of the band, as a 0–1 fraction of the min→max range. */
+    endFraction: number;
+    /** Dial angle of {@link startFraction}. */
+    startAngle: number;
+    /** Dial angle of {@link endFraction}. */
+    endAngle: number;
 }
-/** Build the outer-ring threshold arc bands (in fraction space 0..1). */
+/**
+ * Split the dial into coloured bands. The bands tile the whole 0–1 range with
+ * no holes: a leading neutral band covers anything below the first threshold,
+ * and the last threshold's band runs to 1. Zero-width bands (duplicate
+ * thresholds, or one pinned at 1) are dropped.
+ *
+ * With no thresholds configured the dial is a single neutral band, so the
+ * gauge still renders a full arc.
+ */
 export declare function buildThresholdBands(thresholds: ThresholdBand[]): ThresholdArcBand[];
+export interface GaugeBandSegment {
+    color: string;
+    startAngle: number;
+    endAngle: number;
+}
+/**
+ * Turn logical bands into drawable segments by inserting a gap at every
+ * *internal* boundary (the dial's outer ends keep the full 270° sweep).
+ * Segments too narrow to render cleanly with rounded caps are dropped.
+ */
+export declare function buildBandSegments(bands: ThresholdArcBand[], gap?: number): GaugeBandSegment[];
+export interface GaugeScaleTick {
+    fraction: number;
+    value: number;
+    angle: number;
+}
+/**
+ * Numeric scale ticks at the band boundaries (plus the dial's start and end).
+ * Ticks are thinned back-to-front so the max is always kept and no two labels
+ * collide.
+ */
+export declare function buildScaleTicks(bands: ThresholdArcBand[], minValue: number, maxValue: number): GaugeScaleTick[];
+/** Triangular needle: wide at the hub, tapering to a point at `length`. */
+export declare function buildNeedlePath(angle: number, length: number, halfWidth: number): string;
+export interface GaugeLayout {
+    /** Dial centre in SVG coordinates. */
+    cx: number;
+    cy: number;
+    radius: number;
+    outerRadius: number;
+    innerRadius: number;
+    /** Corner radius that fully rounds a band segment's ends. */
+    bandCornerRadius: number;
+    /** Radius at which scale tick labels are centred (just inside the band). */
+    tickRadius: number;
+    needleLength: number;
+    needleHalfWidth: number;
+    hubRadius: number;
+    tickFontSize: number;
+    labelFontSize: number;
+    labelY: number;
+    valueFontSize: number;
+    valueY: number;
+}
+/**
+ * Size and position the dial so its 270° bounding box is centred in, and fits
+ * inside, a `width` x `height` box. Everything else is expressed as a ratio of
+ * the resulting radius so the gauge scales smoothly.
+ */
+export declare function computeGaugeLayout(width: number, height: number): GaugeLayout;
 export interface GaugeGeometry {
     effectiveMax: number;
     clampedValue: number;
     fraction: number;
     fillColor: string;
-    fillAngle: number;
     needleAngle: number;
 }
-/** Compute the gauge's clamped value, fraction, fill colour, and angles. */
+/** Compute the gauge's clamped value, fraction, indicated colour and angle. */
 export declare function computeGaugeGeometry(rawValue: number, minValue: number, maxValue: number, thresholds: ThresholdBand[]): GaugeGeometry;
-/** Format a gauge value with the optional axis format, else locale string. */
+/**
+ * Format a gauge value. With a configured axis format this honours its unit,
+ * decimals and abbreviation (so a percent format renders `66.9%`); without one
+ * it falls back to the shared default numeric formatting (`66.94`).
+ */
 export declare function formatGaugeValue(value: number, yAxisFormat?: AxisFormatConfig): string;

package/dist/cjs/server/adapters/base-adapter.d.ts

@@ -111,6 +111,17 @@ export interface DatabaseAdapter {
      * @returns SQL expression with type casting
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Cast expression to specific database type, tolerantly: unparseable input yields NULL
+     * instead of raising an error (PostgreSQL's `::`/`CAST` on bad input) or silently producing
+     * 0 (MySQL/SQLite `CAST` on non-numeric text). Intended for EAV-style schemas where a text
+     * column holds numbers/timestamps for some attributes and free text for others, so one dirty
+     * value doesn't fail the whole query or masquerade as a real 0.
+     * @param fieldExpr - The field expression to cast
+     * @param targetType - Target database type
+     * @returns SQL expression with tolerant type casting; unparseable/NULL input yields NULL
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Build AVG aggregation expression with database-specific null handling
      * @param fieldExpr - The field expression to average
@@ -216,6 +227,7 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
     abstract buildPeriodSeriesSubquery(maxPeriod: number): SQL;
     abstract buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
     abstract castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    abstract tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     abstract getCapabilities(): DatabaseCapabilities;
     abstract buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL | null;
     /**
@@ -303,6 +315,40 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
         field: AnyColumn | SQL;
         direction: 'asc' | 'desc';
     }>, config?: WindowFunctionConfig): SQL | null;
+    /**
+     * Regex pattern for tryCastToType's decimal guard: optional leading sign, digits with an
+     * optional fractional part (or a bare fractional part like `.5`), surrounded by optional
+     * spaces; rejects everything else. Shared by PostgreSQL (`~`) and MySQL/SingleStore
+     * (`REGEXP`).
+     *
+     * Deliberately written using only POSIX ERE syntax (`[0-9]` instead of `\d`, a literal
+     * space instead of `\s`) rather than Perl/ICU shorthands. PostgreSQL's `~` always
+     * understands `\d`/`\s`, and MySQL 8.0.4+'s default ICU regex engine does too — but
+     * SingleStore's `REGEXP` is dialect-switchable via the `regexp_format` session variable
+     * ('extended' = POSIX ERE, 'advanced' = ICU/PCRE-style), and SingleStore's own docs
+     * recommend explicitly opting into 'advanced' for new regex logic, implying 'extended'
+     * (POSIX, no `\d`/`\s`) is the default. Since SingleStoreAdapter inherits this pattern
+     * unchanged from MySQLAdapter and this repo doesn't control session variables for
+     * consumers, the pattern is written as the POSIX-ERE/ICU/ARE intersection so it matches
+     * correctly regardless of which dialect is active.
+     */
+    protected decimalTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's integer guard: optional leading sign, digits only,
+     * surrounded by optional spaces. Same POSIX-ERE/ICU/ARE-portable rationale as
+     * decimalTryCastPattern().
+     */
+    protected integerTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's timestamp guard: an ISO 8601-shaped date, optionally
+     * followed by a time component (with optional seconds, fractional seconds and a UTC/offset
+     * suffix), surrounded by optional spaces. This only validates the *shape* of the input —
+     * it does not catch calendar-invalid dates (e.g. 2024-02-30) or reject strings that "look"
+     * like a timestamp but aren't (that would need engine-side parsing, which is exactly what
+     * tryCastToType is avoiding relying on for error-safety). Same POSIX-ERE/ICU/ARE-portable
+     * rationale as decimalTryCastPattern().
+     */
+    protected timestampTryCastPattern(): string;
     /**
      * Helper method to build pattern for string matching
      * Can be overridden by specific adapters if needed

package/dist/cjs/server/adapters/databend-adapter.d.ts

@@ -45,6 +45,11 @@ export declare class DatabendAdapter extends BaseDatabaseAdapter {
      * Databend supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Databend tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Databend capabilities - start conservative
      */