drizzle-cube 0.7.1 → 0.8.1

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

@@ -0,0 +1,68 @@
+import { default as React } from 'react';
+import { ChartAxisConfig, ChartPagination, CubeQuery } from '../../types.js';
+export declare const DEFAULT_PAGE_SIZE = 25;
+/**
+ * Which columns to render, in which order.
+ *
+ * The author's arrangement comes from the Columns drop zone; a viewer can drag
+ * a header on top of it, and that order is remembered per column set. It is
+ * *reconciled* rather than substituted, so a column the author adds later still
+ * appears instead of being swallowed by a stale local order.
+ */
+export declare function useRecordsColumns(params: {
+    rows: Record<string, unknown>[];
+    chartConfig?: ChartAxisConfig;
+    queryObject?: CubeQuery;
+}): {
+    columns: string[];
+    storageKey: string;
+    draggedColumn: string | null;
+    didDragRef: React.MutableRefObject<boolean>;
+    startColumnDrag: (column: string) => void;
+    endColumnDrag: () => void;
+    dropColumn: (target: string) => void;
+};
+/**
+ * Drag-resizable column widths, remembered per column set.
+ *
+ * A chart has no portlet id and no write path back to `displayConfig`, so an
+ * authored `columnWidths` acts as the default a viewer's own drags layer over —
+ * the same arrangement the data browser uses.
+ */
+export declare function useColumnWidths(params: {
+    columns: string[];
+    storageKey: string;
+    authored?: Record<string, number>;
+}): {
+    columnWidths: Record<string, number>;
+    totalWidth: number | undefined;
+    tableRef: React.RefObject<HTMLTableElement>;
+    didResizeRef: React.MutableRefObject<boolean>;
+    startResize: (event: React.MouseEvent, column: string) => void;
+};
+/**
+ * Sorting and paging, server-side when the host offers it.
+ *
+ * With a `pagination` prop the host re-queries, so both must go through it:
+ * sorting only the loaded page would put the wrong rows on page 1. Without one
+ * — the AnalysisBuilder preview, the notebook, plugin hosts — the table sorts
+ * and pages over the rows it already has.
+ */
+export declare function useRecordsPaging(params: {
+    rows: Record<string, unknown>[];
+    pagination?: ChartPagination;
+    authoredPageSize?: number;
+}): {
+    sort: {
+        column: string;
+        direction: "asc" | "desc";
+    } | null;
+    toggleSort: (column: string) => void;
+    visibleRows: Record<string, unknown>[];
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    rowCount: number;
+    goToPage: (next: number) => void;
+    showPager: boolean;
+};

package/dist/cjs/client/icons/types.d.ts

@@ -80,6 +80,7 @@ export interface IconRegistry {
     chartRadialBar: IconDefinition;
     chartTreemap: IconDefinition;
     chartTable: IconDefinition;
+    chartRecordsTable: IconDefinition;
     chartActivityGrid: IconDefinition;
     chartKpiNumber: IconDefinition;
     chartKpiDelta: IconDefinition;

package/dist/cjs/client/index.d.ts

@@ -33,7 +33,7 @@ useCubeFeatures } from './providers/CubeProvider.js';
 export { ScrollContainerProvider, useScrollContainer } from './providers/ScrollContainerContext.js';
 export { useCubeFieldLabel } from './hooks/useCubeFieldLabel.js';
 export { createCubeClient } from './client/CubeClient.js';
-export { CubeClient } from './client/CubeClient.js';
+export { CubeClient, CubeQueryError } from './client/CubeClient.js';
 export { useCubeMetaQuery, useCubeLoadQuery, useCubeQuery, useMultiCubeLoadQuery, useDryRunQuery, useMultiDryRunQueries, useDryRunQueries, useExplainQuery, createExplainQueryKey, useExplainAI, useFunnelQuery, createFunnelQueryKey, useFlowQuery, createFlowQueryKey, } from './hooks/queries/index.js';
 export type { UseCubeMetaQueryOptions, UseCubeMetaQueryResult, UseCubeLoadQueryOptions, UseCubeLoadQueryResult, UseMultiCubeLoadQueryOptions, UseMultiCubeLoadQueryResult, DebugDataEntry, UseExplainQueryOptions, UseExplainQueryResult, UseExplainAIOptions, UseExplainAIResult, UseFlowQueryOptions, UseFlowQueryResult, } from './hooks/queries/index.js';
 export { useAnalysisBuilder } from './hooks/useAnalysisBuilderHook.js';
@@ -55,7 +55,7 @@ export { useTheme } from './hooks/useTheme.js';
 export { useScrollDetection } from './hooks/useScrollDetection.js';
 export { useElementVisibility } from './hooks/useElementVisibility.js';
 export { useDrillInteraction } from './hooks/useDrillInteraction.js';
-export type { PortletConfig, ChartType, BuiltInChartType, ChartAxisConfig, ChartDisplayConfig, ChartProps, ColorPalette, CubeQuery, CubeQueryOptions, CubeApiOptions, DashboardConfig, PortletGroup, PortletGroupCell, FeaturesConfig, XlsExportFeatureConfig, ThumbnailFeatureConfig, MultiQueryConfig, QueryMergeStrategy, FunnelBindingKey, FunnelBindingKeyMapping, FunnelStep, FunnelConfig, FunnelStepResult, FunnelExecutionResult, FunnelChartData, FunnelValidationError, FunnelValidationResult, UseFunnelQueryOptions, UseFunnelQueryResult, ServerFlowQuery, FlowQueryConfig, FlowChartData, FlowSliceState, SankeyNode, SankeyLink, FlowStartingStep, FlowResultRow, } from './types.js';
+export type { PortletConfig, ChartType, BuiltInChartType, ChartAxisConfig, ChartDisplayConfig, ChartProps, ColorPalette, CubeQuery, CubeQueryOptions, CubeApiOptions, CubeValidationIssue, ChartPagination, ColumnFormatConfig, ColumnFormatKind, RowLinkConfig, DashboardConfig, PortletGroup, PortletGroupCell, FeaturesConfig, XlsExportFeatureConfig, ThumbnailFeatureConfig, MultiQueryConfig, QueryMergeStrategy, FunnelBindingKey, FunnelBindingKeyMapping, FunnelStep, FunnelConfig, FunnelStepResult, FunnelExecutionResult, FunnelChartData, FunnelValidationError, FunnelValidationResult, UseFunnelQueryOptions, UseFunnelQueryResult, ServerFlowQuery, FlowQueryConfig, FlowChartData, FlowSliceState, SankeyNode, SankeyLink, FlowStartingStep, FlowResultRow, } from './types.js';
 export { isQueryConfig, isFunnelConfig, isFlowConfig, isRetentionConfig, isMultiQuery, isSingleQuery, isValidAnalysisConfig, createDefaultQueryConfig, createDefaultFunnelConfig, createDefaultFlowConfig, createDefaultRetentionConfig, createDefaultConfig, isValidAnalysisWorkspace, createDefaultWorkspace } from './types/analysisConfig.js';
 export type { AnalysisConfig, QueryAnalysisConfig, FunnelAnalysisConfig, FlowAnalysisConfig, RetentionAnalysisConfig, AnalysisWorkspace } from './types/analysisConfig.js';
 export { isMultiQueryConfig, isServerFunnelQuery, isServerFlowQuery, isSankeyData } from './types.js';

package/dist/cjs/client/types.d.ts

@@ -71,7 +71,7 @@ export interface CubeMeta {
 }
 export type FieldLabelMap = Record<string, string>;
 export type { ColorPalette } from './utils/colorPalettes.js';
-export type BuiltInChartType = 'line' | 'bar' | 'pie' | 'table' | 'area' | 'scatter' | 'radar' | 'radialBar' | 'treemap' | 'bubble' | 'activityGrid' | 'kpiNumber' | 'kpiDelta' | 'kpiText' | 'markdown' | 'funnel' | 'sankey' | 'sunburst' | 'heatmap' | 'retentionHeatmap' | 'retentionCombined' | 'boxPlot' | 'waterfall' | 'candlestick' | 'proportionBar' | 'measureProfile' | 'gauge';
+export type BuiltInChartType = 'line' | 'bar' | 'pie' | 'table' | 'area' | 'scatter' | 'radar' | 'radialBar' | 'treemap' | 'bubble' | 'activityGrid' | 'kpiNumber' | 'kpiDelta' | 'kpiText' | 'markdown' | 'funnel' | 'sankey' | 'sunburst' | 'heatmap' | 'retentionHeatmap' | 'retentionCombined' | 'boxPlot' | 'waterfall' | 'candlestick' | 'proportionBar' | 'measureProfile' | 'gauge' | 'recordsTable';
 export type ChartType = BuiltInChartType | (string & {});
 export interface AxisFormatConfig {
     label?: string;
@@ -80,6 +80,7 @@ export interface AxisFormatConfig {
     decimals?: number;
     customPrefix?: string;
     customSuffix?: string;
+    currencyCode?: string;
 }
 export interface ChartAxisConfig {
     xAxis?: string[];
@@ -89,10 +90,49 @@ export interface ChartAxisConfig {
     colorField?: string;
     dateField?: string[];
     valueField?: string[];
+    columns?: string[];
+    hiddenColumns?: string[];
     x?: string;
     y?: string[];
     yAxisAssignment?: Record<string, 'left' | 'right'>;
 }
+/**
+ * How a records-table column renders its value. Chosen per column in the chart
+ * editor — never inferred from the data, so the same field can be a badge in one
+ * dashboard and plain text in another.
+ */
+export type ColumnFormatKind = 'text' | 'number' | 'date' | 'badge' | 'progress';
+export interface ColumnFormatConfig {
+    kind: ColumnFormatKind;
+    /** Numeric formatting for `kind: 'number'` — reuses the shared axis formatter. */
+    numberFormat?: AxisFormatConfig;
+    /** Granularity for `kind: 'date'`. */
+    dateGranularity?: TimeGranularity;
+    /**
+     * Value → palette colour index for `kind: 'badge'`. Values with no mapping
+     * render neutral rather than being assigned a guessed colour.
+     */
+    badgeColors?: Array<{
+        value: string;
+        colorIndex: number;
+    }>;
+    /** Bounds for `kind: 'progress'` (default 0-100). Values are clamped. */
+    progressMin?: number;
+    progressMax?: number;
+    /** How a `kind: 'progress'` cell draws: a full-width bar, or a compact ring for narrow columns. */
+    progressStyle?: 'bar' | 'circle';
+    /** Header override; falls back to the field's metadata title. */
+    label?: string;
+    align?: 'left' | 'right';
+}
+/**
+ * Row-level click-through for the records table. Tokens of the form
+ * `{Cube.field}` are substituted from the row, including hidden columns.
+ */
+export interface RowLinkConfig {
+    urlTemplate: string;
+    target?: 'self' | 'blank';
+}
 export interface ThresholdBand {
     value: number;
     color: string;
@@ -119,6 +159,10 @@ export interface ChartDisplayConfig {
     sortSegments?: boolean;
     fitToWidth?: boolean;
     pivotTimeDimension?: boolean;
+    columnFormats?: Record<string, ColumnFormatConfig>;
+    columnWidths?: Record<string, number>;
+    rowLink?: RowLinkConfig;
+    pageSize?: number;
     target?: string;
     template?: string;
     prefix?: string;
@@ -353,6 +397,12 @@ export interface CubeQuery {
     segments?: string[];
     /** When true, returns raw row-level data without GROUP BY or aggregation */
     ungrouped?: boolean;
+    /**
+     * Ask the server for the number of rows the query would return with no
+     * limit/offset, read back via `CubeResultSet.totalCount()`. Costs a second
+     * round trip, so only paginated views set it.
+     */
+    total?: boolean;
 }
 /**
  * Merge strategy for combining multiple query results
@@ -389,6 +439,17 @@ export interface CubeApiOptions {
     headers?: Record<string, string>;
     credentials?: 'include' | 'omit' | 'same-origin';
 }
+/**
+ * An unknown member the server rejected, mirroring the server's
+ * `QueryValidationIssue`. `source` is what decides the response: a projected
+ * member can be dropped and the query re-run, whereas dropping a filter would
+ * widen the result set and must stay an error.
+ */
+export interface CubeValidationIssue {
+    source: 'measure' | 'dimension' | 'timeDimension' | 'filter';
+    member: string;
+    message: string;
+}
 export interface CubeResultSet {
     rawData(): any[];
     tablePivot(): any[];
@@ -401,6 +462,8 @@ export interface CubeResultSet {
         ttlMs: number;
         ttlRemainingMs: number;
     } | undefined;
+    /** Rows the query would return without limit/offset — only when `total: true` was asked for. */
+    totalCount?(): number | undefined;
 }
 export interface AnalyticsPortletProps {
     query: string;
@@ -464,6 +527,34 @@ export interface ChartProps {
     onDataPointClick?: (event: import('./types/drill.js').ChartDataPointClickEvent) => void;
     /** Whether drill-down is enabled (shows pointer cursor on clickable elements) */
     drillEnabled?: boolean;
+    /**
+     * Server-side pagination, supplied by hosts that can re-query (the dashboard
+     * portlet). Absent in the AnalysisBuilder preview, the notebook and plugin
+     * hosts, where a chart pages and sorts over the rows it already has.
+     */
+    pagination?: ChartPagination;
+}
+/**
+ * Paging and sorting state a host drives on the chart's behalf.
+ *
+ * Sort lives here rather than in the chart because with server-side paging a
+ * header click has to re-order the whole result set: sorting only the loaded
+ * page would put the wrong rows on page 1.
+ */
+export interface ChartPagination {
+    page: number;
+    pageSize: number;
+    pageSizeOptions: number[];
+    /** Total matching rows, once the server has reported one. */
+    total?: number;
+    sort?: {
+        column: string;
+        direction: 'asc' | 'desc';
+    };
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    /** Cycles the column asc → desc → unsorted, resetting to the first page. */
+    toggleSort: (column: string) => void;
 }
 export interface ThumbnailFeatureConfig {
     enabled: boolean;

package/dist/cjs/client/utils/recordsTableUtils.d.ts

@@ -0,0 +1,71 @@
+import { ColumnFormatConfig } from '../types.js';
+/** Fallback when an author has not sized a column. */
+export declare const DEFAULT_COLUMN_WIDTH = 160;
+/** Narrower than this and the resize handle overlaps the header text. */
+export declare const MIN_COLUMN_WIDTH = 60;
+/**
+ * Identity under which a viewer's column widths are remembered.
+ *
+ * A chart component has no portlet id, so widths key on the columns themselves:
+ * two records tables showing the same fields share widths, which is the
+ * behaviour an author would expect from two views of the same records.
+ */
+export declare function columnWidthStorageKey(columns: string[]): string;
+export declare function loadColumnWidths(key: string): Record<string, number>;
+export declare function saveColumnWidths(key: string, widths: Record<string, number>): void;
+/**
+ * A viewer's own column order, remembered under the same identity as widths.
+ *
+ * Stored as a list rather than a map so it survives the author adding or
+ * removing a column: {@link applyColumnOrder} reconciles it against the
+ * columns that actually exist.
+ */
+export declare function loadColumnOrder(key: string): string[];
+export declare function saveColumnOrder(key: string, order: string[]): void;
+/**
+ * Lay a remembered order over the columns the chart actually has.
+ *
+ * Columns the order does not mention keep their authored position relative to
+ * the end, so an author adding a column still sees it rather than having it
+ * silently swallowed by a stale local order.
+ */
+export declare function applyColumnOrder(columns: string[], order: string[]): string[];
+/** Move one column to another's position, returning a new order. */
+export declare function moveColumn(columns: string[], from: string, to: string): string[];
+/**
+ * A cell resolved to something renderable. `progress` carries its own shape
+ * because the component draws a bar or a ring rather than a string; every
+ * other kind reduces to text plus, for badges, a colour.
+ *
+ * The component only ever sees a `RenderedCell`, so the progress `style` is
+ * resolved here rather than being read back out of the column's config.
+ */
+export type RenderedCell = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'badge';
+    text: string;
+    colorIndex?: number;
+} | {
+    kind: 'progress';
+    text: string;
+    fraction: number;
+    style: 'bar' | 'circle';
+};
+/**
+ * Turn a raw cell value into its display form under the column's format.
+ *
+ * Every kind degrades to text rather than erroring: a non-numeric value under
+ * `number`/`progress` renders as-is (EAV columns legitimately contain 'n/a'),
+ * and a badge value with no colour mapping renders neutral rather than being
+ * given a guessed colour.
+ */
+export declare function renderCellValue(value: unknown, format: ColumnFormatConfig | undefined): RenderedCell;
+/**
+ * Sort rows by one column, client-side.
+ *
+ * Only used when the host provides no server-side pagination — with paging on,
+ * sorting the loaded page alone would put the wrong rows on page 1.
+ */
+export declare function sortRows(rows: Record<string, unknown>[], column: string, direction: 'asc' | 'desc'): Record<string, unknown>[];

package/dist/cjs/client/utils/rowLinkUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Row click-through URLs for the records table.
+ *
+ * A dashboard author writes a template such as `/employees/{Employees.id}`,
+ * and each row fills its own tokens. The template is author-controlled but the
+ * *values* are data, so they are percent-encoded before substitution — an
+ * encoded value cannot introduce a scheme, a path segment or a query separator.
+ *
+ * The resulting URL is then checked rather than trusted: only same-origin
+ * relative paths and absolute http(s) URLs are allowed through.
+ */
+/**
+ * Resolve a row link template against one row.
+ *
+ * Returns `null` — meaning "render no link" — when the template references a
+ * field the row does not carry, or when the result is not a URL we are willing
+ * to navigate to. Never throws: a malformed template must not take the table
+ * down with it.
+ *
+ * @param template - e.g. `/employees/{Employees.id}?tab=profile`
+ * @param row - the row's values, including hidden columns
+ * @param origin - the origin relative URLs are resolved against
+ */
+export declare function buildRowUrl(template: string | undefined, row: Record<string, unknown>, origin?: string): string | null;
+/**
+ * Whether a URL is one we will navigate to: an absolute `http(s)` URL, or a
+ * path that stays on this origin.
+ *
+ * Rejected, deliberately: `javascript:`, `data:`, `vbscript:` and every other
+ * scheme; protocol-relative `//evil.example`, which inherits the current scheme
+ * and silently leaves the origin; and backslash forms such as `\\evil.example`
+ * or `/\evil.example`, which several browsers normalise into that same
+ * protocol-relative shape.
+ */
+export declare function isSafeUrl(url: string, origin?: string): boolean;

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
      */

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

@@ -52,6 +52,11 @@ export declare class DuckDBAdapter extends BaseDatabaseAdapter {
      * DuckDB supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build DuckDB 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;
     /**
      * DuckDB has full support for statistical and window functions
      * Note: supportsPercentileSubqueries is false because DuckDB's QUANTILE_CONT

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

@@ -47,6 +47,20 @@ export declare class MySQLAdapter extends BaseDatabaseAdapter {
      * MySQL equivalent to PostgreSQL's :: casting syntax
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build MySQL tolerant type casting: NULL on unparseable input instead of MySQL's usual
+     * lenient-but-wrong behaviour. `CAST(x AS DECIMAL/SIGNED)` parses a leading numeric prefix
+     * (or returns 0 with a warning if there's no numeric prefix at all) rather than erroring —
+     * so a dirty value like 'n/a' silently becomes 0. `CAST(x AS DATETIME)` on a string that
+     * merely looks date-shaped but is calendar-invalid can, depending on sql_mode, raise an
+     * error (strict mode, the MySQL 8 default) rather than returning NULL. Guard all three with
+     * REGEXP so we only ever attempt the cast on input that already looks like the target type;
+     * anything else short-circuits to NULL first.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* — it will not catch calendar-invalid
+     * dates like 2024-02-30, which could still error under strict SQL mode.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * MySQL AVG/STDDEV/VARIANCE use IFNULL (no COALESCE-for-zero idiom mismatch,
      * but IFNULL is the MySQL-idiomatic null guard).

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

@@ -43,6 +43,21 @@ export declare class PostgresAdapter extends BaseDatabaseAdapter {
      * Extracted from various locations where ::timestamp was used
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build PostgreSQL tolerant type casting: NULL on unparseable input instead of an error.
+     * PostgreSQL has no TRY_CAST, and `CAST(x AS type DEFAULT NULL ON ERROR)` (added in a
+     * recent PostgreSQL release) requires a minimum server version. This repo pins no minimum
+     * PostgreSQL version anywhere (CI/dev docker-compose both run `postgres:18`, but nothing
+     * documents that as a floor for consumers), so we don't assume newer syntax is available.
+     * Instead, guard the cast with a POSIX regex (`~`) so we only ever attempt to cast values
+     * that already look like the target type; anything else short-circuits to NULL before the
+     * cast runs, so PostgreSQL never gets a chance to raise.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* (see timestampTryCastPattern) — it
+     * will not catch calendar-invalid dates like 2024-02-30, which would still error. A full
+     * guarantee would need a helper SQL function (out of scope here).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * PostgreSQL has full support for statistical and window functions
      */

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

@@ -41,6 +41,12 @@ export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
      * Snowflake supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Snowflake tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST). Snowflake's
+     * TRY_CAST supports VARCHAR, NUMBER-family types (including DECIMAL) and TIMESTAMP.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Snowflake capabilities - full SQL support
      */

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

@@ -51,6 +51,27 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * SQLite has dynamic typing but supports CAST for consistency
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build SQLite tolerant type casting: NULL on unparseable input instead of SQLite's usual
+     * dynamic-typing behaviour. SQLite's CAST-to-numeric applies "prefix" conversion — the
+     * longest numeric prefix of the string is used, or 0 if there is none — so `CAST('n/a' AS
+     * REAL)` silently yields 0.0 rather than erroring or returning NULL.
+     *
+     * SQLite has no REGEXP operator by default (it requires loading an extension, same
+     * limitation regexCondition() works around with GLOB). GLOB's `*`/`?`/`[...]` syntax can't
+     * express "one or more digits" directly, but the standard SQLite idiom for "string contains
+     * only characters from a set" is `NOT x GLOB '*[^set]*'` — true only if no character outside
+     * the set appears anywhere. That's what's used below to validate the trimmed value contains
+     * only the characters a valid decimal/integer/epoch-ms value could use, before attempting
+     * the cast; empty/whitespace-only strings are excluded separately.
+     *
+     * Known limitation: this is a character-set check, not a full grammar check, so a malformed
+     * value that still only uses allowed characters (e.g. '1.2.3' or '+-5') passes the guard and
+     * is then handled by SQLite's own prefix-based numeric parsing (never an error, but not
+     * necessarily NULL either). Clearly non-numeric input (letters, 'n/a', punctuation outside
+     * the allowed set) is reliably rejected to NULL, which is the case this method exists for.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * SQLite AVG uses IFNULL rather than COALESCE for null-to-zero handling.
      */

package/dist/cjs/server/agent/chart-validation.d.ts

@@ -12,7 +12,7 @@ interface ValidationResult {
 /**
  * Validate chartConfig against the chart type's drop zone requirements.
  */
-export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, _query: Record<string, unknown>): ValidationResult;
+export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): ValidationResult;
 export declare function inferChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build per-chart-type requirements text for the agent tool description.