@matthieumordrel/chart-studio 0.3.0 → 0.5.2

package/dist/core/dataset-builder.types.d.mts

@@ -0,0 +1,51 @@
+import { ChartType, ChartTypeConfig, DefinedChartSchema, FiltersConfig, GroupByConfig, InferableFieldKey, MetricConfig, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, TimeBucket, TimeBucketConfig, XAxisConfig } from "./types.mjs";
+import { ColumnHelper, ColumnsFromEntries, MetricBuilder, MetricBuilderConfig, SchemaColumnEntry, SchemaFromBuilder, SelectableControlBuilder, SelectableControlBuilderConfig, ValidateColumnEntries } from "./schema-builder.types.mjs";
+import { DATASET_CHART_METADATA, DatasetChartMetadata } from "./dataset-chart-metadata.mjs";
+
+//#region src/core/dataset-builder.types.d.ts
+type NonEmptyReadonlyArray<TValue> = readonly [TValue, ...TValue[]];
+type DatasetColumnsContext<TColumns extends Record<string, unknown> | undefined> = [TColumns] extends [undefined] ? undefined : {
+  columns?: TColumns;
+};
+type DefinedDatasetChartSchema<TRow, TColumns extends Record<string, unknown> | undefined, TXAxis extends XAxisConfig<any> | undefined, TGroupBy extends GroupByConfig<any> | undefined, TFilters extends FiltersConfig<any> | undefined, TMetric extends MetricConfig<any> | undefined, TChartType extends ChartTypeConfig | undefined, TTimeBucket extends TimeBucketConfig | undefined, TConnectNulls extends boolean | undefined, TChartId extends string | undefined = undefined, TOwner = unknown> = DefinedChartSchema<TRow, SchemaFromBuilder<TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls>> & {
+  readonly [DATASET_CHART_METADATA]: DatasetChartMetadata<TChartId, TOwner>;
+};
+type DatasetKey<TRow> = NonEmptyReadonlyArray<InferableFieldKey<TRow>>;
+type DefinedDataset<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> = {
+  readonly key?: TKey;
+  readonly columns?: TColumns;
+  chart<const TChartId extends string | undefined = undefined>(id?: TChartId): DatasetChartBuilder<TRow, TColumns, undefined, undefined, undefined, undefined, undefined, undefined, undefined, TChartId, DefinedDataset<TRow, TColumns, TKey>>;
+  validateData(data: readonly TRow[]): void;
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+  readonly __datasetBrand: 'dataset-definition';
+};
+type DatasetDefinition<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> = {
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+};
+type ResolvedDatasetFromDefinition<TDataset> = TDataset extends DatasetDefinition<any, any, any> ? ReturnType<TDataset['build']> : never;
+type DatasetRow<TDataset> = TDataset extends DefinedDataset<infer TRow, any, any> ? TRow : never;
+type DatasetColumns<TDataset> = TDataset extends DefinedDataset<any, infer TColumns, any> ? TColumns : never;
+type DatasetKeyIds<TDataset> = TDataset extends DefinedDataset<any, any, infer TKey> ? TKey : never;
+type SingleDatasetKeyId<TDataset> = DatasetKeyIds<TDataset> extends readonly [infer TKeyId extends string] ? TKeyId : never;
+type DatasetChartBuilder<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TXAxis extends XAxisConfig<any> | undefined = undefined, TGroupBy extends GroupByConfig<any> | undefined = undefined, TFilters extends FiltersConfig<any> | undefined = undefined, TMetric extends MetricConfig<any> | undefined = undefined, TChartType extends ChartTypeConfig | undefined = undefined, TTimeBucket extends TimeBucketConfig | undefined = undefined, TConnectNulls extends boolean | undefined = undefined, TChartId extends string | undefined = undefined, TOwner = unknown> = {
+  xAxis<const TBuilder extends SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>>(defineXAxis: (xAxis: SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, SelectableControlBuilderConfig<TBuilder>, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  groupBy<const TBuilder extends SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>>(defineGroupBy: (groupBy: SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, SelectableControlBuilderConfig<TBuilder>, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  filters<const TBuilder extends SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, false>>(defineFilters: (filters: SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, false>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, SelectableControlBuilderConfig<TBuilder>, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  metric<const TBuilder extends MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, any, any, any>>(defineMetric: (metric: MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, MetricBuilderConfig<TBuilder>, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  chartType<const TBuilder extends SelectableControlBuilder<ChartType, true>>(defineChartType: (chartType: SelectableControlBuilder<ChartType, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, SelectableControlBuilderConfig<TBuilder>, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  timeBucket<const TBuilder extends SelectableControlBuilder<TimeBucket, true>>(defineTimeBucket: (timeBucket: SelectableControlBuilder<TimeBucket, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, SelectableControlBuilderConfig<TBuilder>, TConnectNulls, TChartId, TOwner>;
+  connectNulls<const TValue extends boolean>(value: TValue): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TValue, TChartId, TOwner>;
+  build(): DefinedDatasetChartSchema<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  readonly [DATASET_CHART_METADATA]: DatasetChartMetadata<TChartId, TOwner>;
+};
+type DatasetChartDefinition<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TXAxis extends XAxisConfig<any> | undefined = undefined, TGroupBy extends GroupByConfig<any> | undefined = undefined, TFilters extends FiltersConfig<any> | undefined = undefined, TMetric extends MetricConfig<any> | undefined = undefined, TChartType extends ChartTypeConfig | undefined = undefined, TTimeBucket extends TimeBucketConfig | undefined = undefined, TConnectNulls extends boolean | undefined = undefined, TChartId extends string | undefined = undefined, TOwner = unknown> = DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner> | DefinedDatasetChartSchema<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+interface DatasetBuilder<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> extends DatasetDefinition<TRow, TColumns, TKey> {
+  key<const TFieldId extends InferableFieldKey<TRow>>(id: TFieldId): DatasetBuilder<TRow, TColumns, readonly [TFieldId]>;
+  key<const TKeyIds extends DatasetKey<TRow>>(ids: TKeyIds): DatasetBuilder<TRow, TColumns, TKeyIds>;
+  columns: TColumns extends undefined ? <const TEntries extends readonly SchemaColumnEntry<TRow>[]>(defineColumns: (columns: ColumnHelper<TRow>) => TEntries & ValidateColumnEntries<TEntries>) => DatasetBuilder<TRow, ColumnsFromEntries<TRow, TEntries>, TKey> : never;
+  chart<const TChartId extends string | undefined = undefined>(id?: TChartId): DatasetChartBuilder<TRow, TColumns, undefined, undefined, undefined, undefined, undefined, undefined, undefined, TChartId, DefinedDataset<TRow, TColumns, TKey>>;
+  validateData(data: readonly TRow[]): void;
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+}
+//#endregion
+export { DatasetBuilder, DatasetChartBuilder, DatasetChartDefinition, DatasetColumns, DatasetDefinition, DatasetKey, DatasetKeyIds, DatasetRow, DefinedDataset, DefinedDatasetChartSchema, ResolvedDatasetFromDefinition, SingleDatasetKeyId };

package/dist/core/dataset-chart-metadata.d.mts

@@ -0,0 +1,8 @@
+//#region src/core/dataset-chart-metadata.d.ts
+declare const DATASET_CHART_METADATA: unique symbol;
+type DatasetChartMetadata<TChartId extends string | undefined = string | undefined, TOwner = unknown> = {
+  readonly dataset: TOwner;
+  readonly chartId: TChartId;
+};
+//#endregion
+export { DATASET_CHART_METADATA, DatasetChartMetadata };

package/dist/core/dataset-chart-metadata.mjs

@@ -0,0 +1,4 @@
+//#region src/core/dataset-chart-metadata.ts
+const DATASET_CHART_METADATA = Symbol("dataset-chart-metadata");
+//#endregion
+export { DATASET_CHART_METADATA };

package/dist/core/date-range-presets.d.mts

@@ -1,3 +1,5 @@
+import { DateRangeFilter, TimeBucket } from "./types.mjs";
+
 //#region src/core/date-range-presets.d.ts
 /**
  * All recognised date range preset identifiers.
@@ -8,5 +10,45 @@
  * - Calendar presets   — aligned to calendar boundaries
  */
 type DateRangePresetId = 'auto' | 'all-time' | 'last-7-days' | 'last-30-days' | 'last-3-months' | 'last-12-months' | 'quarter-to-date' | 'year-to-date' | 'last-year';
+type DateRangePreset = {
+  id: DateRangePresetId;
+  label: string; /** Optional tooltip description shown on hover. */
+  description?: string; /** Build the filter for this preset. `null` = no date filtering (all time). */
+  buildFilter: () => DateRangeFilter | null;
+};
+/**
+ * Ordered list of all date range presets shown in the UI.
+ *
+ * Layout hint (2-column grid):
+ *   Auto          | All time
+ *   Last 7 days   | Last 30 days
+ *   Last 3 months | Last 12 months
+ *   Quarter to date | Year to date
+ *   Last year     |
+ */
+declare const DATE_RANGE_PRESETS: readonly DateRangePreset[];
+/**
+ * Map a time bucket to a sensible default date range.
+ *
+ * - `day`     → last 30 days (enough for a meaningful daily trend)
+ * - `week`    → last 3 months (~13 weeks)
+ * - `month`   → last 12 months
+ * - `quarter` → all time (null)
+ * - `year`    → all time (null)
+ */
+declare function autoFilterForBucket(bucket: TimeBucket): DateRangeFilter | null;
+/**
+ * Compute the effective `DateRangeFilter` for a given preset.
+ *
+ * For `'auto'`, this uses the provided `timeBucket` to derive the range.
+ * For all other presets, the filter is computed from the preset definition.
+ *
+ * @returns The resolved filter, or `null` for "all time".
+ */
+declare function resolvePresetFilter(presetId: DateRangePresetId, timeBucket: TimeBucket): DateRangeFilter | null;
+/**
+ * Get the human-readable label for a preset ID.
+ */
+declare function getPresetLabel(presetId: DateRangePresetId): string;
 //#endregion
-export { DateRangePresetId };
+export { DATE_RANGE_PRESETS, DateRangePreset, DateRangePresetId, autoFilterForBucket, getPresetLabel, resolvePresetFilter };

package/dist/core/date-range-presets.mjs

@@ -111,7 +111,7 @@ function autoFilterForBucket(bucket) {
 * @returns The resolved filter, or `null` for "all time".
 */
 function resolvePresetFilter(presetId, timeBucket) {
-	if (presetId === "auto") return autoFilterForBucket(timeBucket);
+	if (presetId === "auto") return autoFilterForBucket(timeBucket) ?? null;
 	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.buildFilter() ?? null;
 }
 /**
@@ -149,4 +149,4 @@ function lastYear() {
 	};
 }
 //#endregion
-export { DATE_RANGE_PRESETS, getPresetLabel, resolvePresetFilter };
+export { DATE_RANGE_PRESETS, autoFilterForBucket, getPresetLabel, resolvePresetFilter };

package/dist/core/date-utils.d.mts

@@ -0,0 +1,26 @@
+import { DateColumn, DateRangeFilter } from "./types.mjs";
+
+//#region src/core/date-utils.d.ts
+/**
+ * Filter data by a date range on a specific date column.
+ * Both bounds are inclusive (to is extended to end of day).
+ *
+ * @param data - Raw data items
+ * @param dateColumn - The date column to filter on
+ * @param filter - Date range filter with from/to bounds
+ * @returns Filtered data items within the date range
+ */
+declare function filterByDateRange<T>(data: readonly T[], dateColumn: DateColumn<T>, filter: DateRangeFilter): T[];
+/**
+ * Compute the min/max date range from data for a given date column.
+ *
+ * @param data - Data items to scan
+ * @param dateColumn - The date column to extract dates from
+ * @returns Object with min and max dates (both null if no valid dates)
+ */
+declare function computeDateRange<T>(data: readonly T[], dateColumn: DateColumn<T>): {
+  min: Date | null;
+  max: Date | null;
+};
+//#endregion
+export { computeDateRange, filterByDateRange };

package/dist/core/define-dashboard.d.mts

@@ -0,0 +1,8 @@
+import { DataModelDefinition } from "./data-model.types.mjs";
+import { DashboardBuilder, DashboardDefinition, DashboardInputModel, ResolvedDashboardFromDefinition } from "./dashboard.types.mjs";
+
+//#region src/core/define-dashboard.d.ts
+declare function resolveDashboardDefinition<TDashboard extends DashboardDefinition<any, any, any>>(dashboard: TDashboard): ResolvedDashboardFromDefinition<TDashboard>;
+declare function defineDashboard<TModel extends DataModelDefinition<any, any, any, any>>(model: TModel): DashboardBuilder<DashboardInputModel<TModel>>;
+//#endregion
+export { defineDashboard, resolveDashboardDefinition };

package/dist/core/define-dashboard.mjs

@@ -0,0 +1,156 @@
+import { DATASET_CHART_METADATA } from "./dataset-chart-metadata.mjs";
+//#region src/core/define-dashboard.ts
+function humanizeId(id) {
+	return id.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim().split(/\s+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function assertUniqueId(collection, kind, id) {
+	if (id in collection) throw new Error(`Duplicate ${kind} id: "${id}"`);
+}
+function getDatasetChartMetadata(chart) {
+	if (chart && typeof chart === "object" && DATASET_CHART_METADATA in chart) return chart[DATASET_CHART_METADATA];
+	if (chart && typeof chart === "object" && "build" in chart && typeof chart.build === "function") {
+		const built = chart.build();
+		if (built && typeof built === "object" && DATASET_CHART_METADATA in built) return built[DATASET_CHART_METADATA];
+	}
+}
+function findModelDatasetId(model, dataset) {
+	return Object.entries(model.datasets).find(([, candidate]) => candidate === dataset)?.[0];
+}
+function isMaterializedView(source) {
+	return !!source && typeof source === "object" && "__materializedViewBrand" in source && "materialization" in source && "build" in source && typeof source.build === "function";
+}
+function resolveChartDataSource(model, datasetOrView) {
+	const datasetId = findModelDatasetId(model, datasetOrView);
+	if (datasetId) return {
+		kind: "dataset",
+		datasetId
+	};
+	if (!isMaterializedView(datasetOrView)) return;
+	const view = datasetOrView;
+	const baseDatasetId = view.materialization.baseDataset;
+	if (!(baseDatasetId in model.datasets)) return;
+	return {
+		kind: "materialized-view",
+		datasetId: baseDatasetId,
+		view
+	};
+}
+function createDefinedDashboard(state) {
+	let cachedDashboard;
+	const build = () => {
+		if (cachedDashboard) return cachedDashboard;
+		const definedDashboard = {
+			model: state.model,
+			charts: state.charts,
+			sharedFilters: state.sharedFilters,
+			build() {
+				return definedDashboard;
+			},
+			__dashboardBrand: "dashboard-definition"
+		};
+		cachedDashboard = definedDashboard;
+		return definedDashboard;
+	};
+	return build();
+}
+function createDashboardBuilder(state) {
+	let cachedDashboard;
+	return {
+		chart(id, chart) {
+			assertUniqueId(state.charts, "dashboard chart", id);
+			const metadata = getDatasetChartMetadata(chart);
+			if (!metadata) throw new Error(`Dashboard chart "${id}" must come from defineDataset(...).chart(...).`);
+			if (metadata.chartId && metadata.chartId !== id) throw new Error(`Dashboard chart "${id}" does not match the chart authoring id "${metadata.chartId}".`);
+			const dataSource = resolveChartDataSource(state.model, metadata.dataset);
+			if (!dataSource) throw new Error(`Dashboard chart "${id}" references a dataset or materialized view that is not registered in this data model.`);
+			return createDashboardBuilder({
+				...state,
+				charts: {
+					...state.charts,
+					[id]: {
+						id,
+						datasetId: dataSource.datasetId,
+						schema: chart,
+						dataSource
+					}
+				}
+			});
+		},
+		sharedFilter(id, config) {
+			assertUniqueId(state.sharedFilters, "shared filter", id);
+			if (config === void 0) {
+				const attribute = state.model.attributes[id];
+				if (!attribute) throw new Error(`Unknown model attribute id: "${id}"`);
+				return createDashboardBuilder({
+					...state,
+					sharedFilters: {
+						...state.sharedFilters,
+						[id]: {
+							id,
+							kind: "select",
+							label: humanizeId(id),
+							source: {
+								kind: "attribute",
+								dataset: attribute.source.dataset,
+								key: attribute.source.key,
+								label: attribute.source.label
+							},
+							targets: attribute.targets,
+							attribute: id
+						}
+					}
+				});
+			}
+			if (config.kind === "select") return createDashboardBuilder({
+				...state,
+				sharedFilters: {
+					...state.sharedFilters,
+					[id]: {
+						id,
+						kind: "select",
+						label: config.label ?? humanizeId(id),
+						source: {
+							kind: "column",
+							dataset: config.source.dataset,
+							column: config.source.column
+						},
+						targets: config.targets ?? [{
+							dataset: config.source.dataset,
+							column: config.source.column
+						}]
+					}
+				}
+			});
+			if (!Array.isArray(config.targets) || config.targets.length === 0) throw new Error(`Dashboard shared date-range filter "${id}" requires at least one target.`);
+			return createDashboardBuilder({
+				...state,
+				sharedFilters: {
+					...state.sharedFilters,
+					[id]: {
+						id,
+						kind: "date-range",
+						label: config.label ?? humanizeId(id),
+						targets: config.targets
+					}
+				}
+			});
+		},
+		build() {
+			if (cachedDashboard) return cachedDashboard;
+			cachedDashboard = createDefinedDashboard(state);
+			return cachedDashboard;
+		}
+	};
+}
+function resolveDashboardDefinition(dashboard) {
+	return dashboard.build();
+}
+function defineDashboard(model) {
+	return createDashboardBuilder({
+		model: model.build(),
+		charts: {},
+		sharedFilters: {}
+	});
+}
+//#endregion
+export { defineDashboard, resolveDashboardDefinition };

package/dist/core/define-data-model.d.mts

@@ -0,0 +1,11 @@
+import { DataModelBuilder } from "./data-model.types.mjs";
+
+//#region src/core/define-data-model.d.ts
+/**
+ * Define one linked data model for dataset registration, relationships,
+ * associations, reusable model-level filter attributes, and explicit
+ * Phase 7 materialized views.
+ */
+declare function defineDataModel(): DataModelBuilder<{}, {}, {}, {}>;
+//#endregion
+export { defineDataModel };

package/dist/core/define-data-model.mjs

@@ -0,0 +1,327 @@
+import { resolveDatasetDefinition, validateDatasetData } from "./define-dataset.mjs";
+import { createMaterializationStartBuilder } from "./materialized-view.mjs";
+import { attachModelRuntimeMetadata, getModelRuntimeMetadata, inferModelAttributes, inferModelRelationships, rewriteInferredRelationshipError } from "./model-inference.mjs";
+import { compileModelChart } from "./model-chart.mjs";
+//#region src/core/define-data-model.ts
+function formatValue(value) {
+	if (value instanceof Date) return value.toISOString();
+	return String(value);
+}
+function buildFingerprint(value) {
+	if (value instanceof Date) return `date:${value.toISOString()}`;
+	return `${typeof value}:${String(value)}`;
+}
+function getSingleDatasetKey(dataset, datasetId) {
+	if (!dataset.key || dataset.key.length !== 1) throw new Error(`Dataset "${datasetId}" must declare exactly one key to participate in relationships or associations.`);
+	return dataset.key[0];
+}
+function assertUniqueId(collection, kind, id) {
+	if (id in collection) throw new Error(`Duplicate ${kind} id: "${id}"`);
+}
+function getDatasetOrThrow(datasets, datasetId) {
+	const dataset = datasets[datasetId];
+	if (!dataset) throw new Error(`Unknown dataset id: "${datasetId}"`);
+	return dataset;
+}
+function createKeyLookup(datasetId, keyId, rows) {
+	const values = /* @__PURE__ */ new Set();
+	rows.forEach((row, index) => {
+		const value = row[keyId];
+		if (value == null) throw new Error(`Dataset "${datasetId}" key "${keyId}" is missing a value at row ${index}.`);
+		values.add(buildFingerprint(value));
+	});
+	return {
+		keyId,
+		values
+	};
+}
+function validateRelationshipData(relationship, data, keyLookups) {
+	const toRows = data[relationship.to.dataset];
+	const sourceLookup = keyLookups[relationship.from.dataset]?.[relationship.from.key];
+	if (!sourceLookup) throw new Error(`Relationship "${relationship.id}" requires dataset "${relationship.from.dataset}" data.`);
+	if (!Array.isArray(toRows)) throw new Error(`Relationship "${relationship.id}" requires dataset "${relationship.to.dataset}" data.`);
+	toRows.forEach((row, index) => {
+		const value = row[relationship.to.column];
+		if (value == null) return;
+		if (!sourceLookup.values.has(buildFingerprint(value))) throw new Error(`Relationship "${relationship.id}" has an orphan foreign key "${formatValue(value)}" in dataset "${relationship.to.dataset}" column "${relationship.to.column}" at row ${index}.`);
+	});
+}
+function validateExplicitAssociationData(association, associationId, fromDatasetId, toDatasetId, fromLookup, toLookup) {
+	association.data.forEach((row, index) => {
+		const fromValue = row[association.columns.from];
+		const toValue = row[association.columns.to];
+		if (fromValue == null) throw new Error(`Association "${associationId}" is missing "${association.columns.from}" at edge row ${index}.`);
+		if (toValue == null) throw new Error(`Association "${associationId}" is missing "${association.columns.to}" at edge row ${index}.`);
+		if (!fromLookup.values.has(buildFingerprint(fromValue))) throw new Error(`Association "${associationId}" has an orphan "${association.columns.from}" value "${formatValue(fromValue)}" for dataset "${fromDatasetId}".`);
+		if (!toLookup.values.has(buildFingerprint(toValue))) throw new Error(`Association "${associationId}" has an orphan "${association.columns.to}" value "${formatValue(toValue)}" for dataset "${toDatasetId}".`);
+	});
+}
+function validateDerivedAssociationData(association, state, data, keyLookups) {
+	const derivedEdge = association.edge;
+	if (derivedEdge.kind !== "derived") return;
+	const deriveDatasetId = derivedEdge.deriveFrom.dataset;
+	const deriveRows = data[deriveDatasetId];
+	const deriveKeyId = getSingleDatasetKey(getDatasetOrThrow(state.datasets, deriveDatasetId), deriveDatasetId);
+	const oppositeDatasetId = deriveDatasetId === association.from.dataset ? association.to.dataset : association.from.dataset;
+	const oppositeKeyId = oppositeDatasetId === association.from.dataset ? association.from.key : association.to.key;
+	const oppositeLookup = keyLookups[oppositeDatasetId]?.[oppositeKeyId];
+	if (!oppositeLookup) throw new Error(`Association "${association.id}" requires dataset "${oppositeDatasetId}" data.`);
+	if (!Array.isArray(deriveRows)) throw new Error(`Association "${association.id}" requires dataset "${deriveDatasetId}" data.`);
+	deriveRows.forEach((row, index) => {
+		if (row[deriveKeyId] == null) throw new Error(`Association "${association.id}" source dataset "${deriveDatasetId}" is missing key "${deriveKeyId}" at row ${index}.`);
+		const rawValues = derivedEdge.deriveFrom.values(row) ?? [];
+		if (!Array.isArray(rawValues)) throw new Error(`Association "${association.id}" deriveFrom.values(...) must return an array.`);
+		rawValues.forEach((value) => {
+			if (value == null) throw new Error(`Association "${association.id}" deriveFrom.values(...) returned an empty key value.`);
+			if (!oppositeLookup.values.has(buildFingerprint(value))) throw new Error(`Association "${association.id}" has an orphan derived key "${formatValue(value)}" targeting dataset "${oppositeDatasetId}".`);
+		});
+	});
+}
+function validateAssociationData(association, state, data, keyLookups) {
+	const fromLookup = keyLookups[association.from.dataset]?.[association.from.key];
+	const toLookup = keyLookups[association.to.dataset]?.[association.to.key];
+	if (!fromLookup || !toLookup) throw new Error(`Association "${association.id}" requires both endpoint datasets to be present.`);
+	if (association.edge.kind === "explicit") {
+		validateExplicitAssociationData(association.edge, association.id, association.from.dataset, association.to.dataset, fromLookup, toLookup);
+		return;
+	}
+	validateDerivedAssociationData(association, state, data, keyLookups);
+}
+function validateModelRuntimeData(state, data) {
+	const keyLookups = {};
+	const requiredKeysByDataset = /* @__PURE__ */ new Map();
+	const addRequiredKey = (datasetId, keyId) => {
+		if (!keyId) return;
+		const existing = requiredKeysByDataset.get(datasetId);
+		if (existing) {
+			existing.add(keyId);
+			return;
+		}
+		requiredKeysByDataset.set(datasetId, new Set([keyId]));
+	};
+	Object.entries(state.datasets).forEach(([datasetId, dataset]) => {
+		const rows = data[datasetId];
+		if (!Array.isArray(rows)) throw new Error(`Missing dataset data for "${datasetId}".`);
+		validateDatasetData(dataset, rows, datasetId);
+	});
+	Object.values(state.relationships).forEach((relationship) => {
+		addRequiredKey(relationship.from.dataset, relationship.from.key);
+	});
+	Object.values(state.associations).forEach((association) => {
+		addRequiredKey(association.from.dataset, association.from.key);
+		addRequiredKey(association.to.dataset, association.to.key);
+	});
+	Object.values(state.attributes).forEach((attribute) => {
+		addRequiredKey(attribute.source.dataset, attribute.source.key);
+	});
+	Object.entries(state.datasets).forEach(([datasetId, dataset]) => {
+		if (dataset.key && dataset.key.length === 1) addRequiredKey(datasetId, dataset.key[0]);
+	});
+	requiredKeysByDataset.forEach((keyIds, datasetId) => {
+		const rows = data[datasetId];
+		if (!Array.isArray(rows)) throw new Error(`Missing dataset data for "${datasetId}".`);
+		keyLookups[datasetId] = {};
+		keyIds.forEach((keyId) => {
+			keyLookups[datasetId][keyId] = createKeyLookup(datasetId, keyId, rows);
+		});
+	});
+	Object.values(state.relationships).forEach((relationship) => {
+		validateRelationshipData(relationship, data, keyLookups);
+	});
+	Object.values(state.associations).forEach((association) => {
+		validateAssociationData(association, state, data, keyLookups);
+	});
+}
+function createDefinedDataModel(state) {
+	let cachedModel;
+	const build = () => {
+		if (cachedModel) return cachedModel;
+		const definedModel = {
+			datasets: state.datasets,
+			relationships: state.relationships,
+			associations: state.associations,
+			attributes: state.attributes,
+			materialize(id, defineView) {
+				return defineView(createMaterializationStartBuilder(id, definedModel));
+			},
+			chart(id, defineChart) {
+				return compileModelChart(definedModel, id, defineChart);
+			},
+			validateData(data) {
+				try {
+					validateModelRuntimeData(state, data);
+				} catch (error) {
+					rewriteInferredRelationshipError(getModelRuntimeMetadata(definedModel), error);
+				}
+			},
+			build() {
+				return definedModel;
+			},
+			__dataModelBrand: "data-model-definition"
+		};
+		attachModelRuntimeMetadata(definedModel, { inferredRelationships: new Map([...state.inferredRelationshipIds].map((relationshipId) => {
+			const relationship = state.relationships[relationshipId];
+			return [relationshipId, {
+				id: relationshipId,
+				fromDataset: relationship.from.dataset,
+				fromKey: relationship.from.key,
+				toDataset: relationship.to.dataset,
+				toColumn: relationship.to.column
+			}];
+		})) });
+		cachedModel = definedModel;
+		return definedModel;
+	};
+	return build();
+}
+function createDataModelBuilder(state = {
+	datasets: {},
+	relationships: {},
+	associations: {},
+	attributes: {},
+	inferredRelationshipIds: /* @__PURE__ */ new Set()
+}) {
+	let cachedModel;
+	return {
+		dataset(id, dataset) {
+			assertUniqueId(state.datasets, "dataset", id);
+			const resolvedDataset = resolveDatasetDefinition(dataset);
+			if (!resolvedDataset.key || resolvedDataset.key.length === 0) throw new Error(`Dataset "${id}" must declare a .key() before being added to a data model.`);
+			return createDataModelBuilder({
+				...state,
+				datasets: {
+					...state.datasets,
+					[id]: resolvedDataset
+				}
+			});
+		},
+		relationship(id, config) {
+			assertUniqueId(state.relationships, "relationship", id);
+			const fromKeyId = getSingleDatasetKey(getDatasetOrThrow(state.datasets, config.from.dataset), config.from.dataset);
+			getDatasetOrThrow(state.datasets, config.to.dataset);
+			if (config.from.key !== fromKeyId) throw new Error(`Relationship "${id}" must use declared key "${fromKeyId}" from dataset "${config.from.dataset}".`);
+			return createDataModelBuilder({
+				...state,
+				relationships: {
+					...state.relationships,
+					[id]: {
+						kind: "relationship",
+						id,
+						from: config.from,
+						to: config.to,
+						reverse: {
+							dataset: config.to.dataset,
+							column: config.to.column,
+							to: {
+								dataset: config.from.dataset,
+								key: config.from.key
+							}
+						}
+					}
+				}
+			});
+		},
+		association(id, config) {
+			assertUniqueId(state.associations, "association", id);
+			const fromDataset = getDatasetOrThrow(state.datasets, config.from.dataset);
+			const toDataset = getDatasetOrThrow(state.datasets, config.to.dataset);
+			const fromKeyId = getSingleDatasetKey(fromDataset, config.from.dataset);
+			const toKeyId = getSingleDatasetKey(toDataset, config.to.dataset);
+			if (config.from.key !== fromKeyId) throw new Error(`Association "${id}" must use declared key "${fromKeyId}" from dataset "${config.from.dataset}".`);
+			if (config.to.key !== toKeyId) throw new Error(`Association "${id}" must use declared key "${toKeyId}" from dataset "${config.to.dataset}".`);
+			if ("deriveFrom" in config) {
+				if (config.deriveFrom.dataset !== config.from.dataset && config.deriveFrom.dataset !== config.to.dataset) throw new Error(`Association "${id}" deriveFrom.dataset must match either "${config.from.dataset}" or "${config.to.dataset}".`);
+			}
+			return createDataModelBuilder({
+				...state,
+				associations: {
+					...state.associations,
+					[id]: {
+						kind: "association",
+						id,
+						from: config.from,
+						to: config.to,
+						reverse: {
+							dataset: config.to.dataset,
+							key: config.to.key,
+							to: {
+								dataset: config.from.dataset,
+								key: config.from.key
+							}
+						},
+						edge: "deriveFrom" in config ? {
+							kind: "derived",
+							deriveFrom: config.deriveFrom
+						} : {
+							kind: "explicit",
+							data: config.data,
+							columns: config.columns
+						}
+					}
+				}
+			});
+		},
+		attribute(id, config) {
+			assertUniqueId(state.attributes, "attribute", id);
+			return createDataModelBuilder({
+				...state,
+				attributes: {
+					...state.attributes,
+					[id]: {
+						id,
+						kind: config.kind,
+						source: config.source,
+						targets: config.targets
+					}
+				}
+			});
+		},
+		infer(options) {
+			const nextRelationships = options.relationships === true ? inferModelRelationships(state.datasets, state.relationships, new Set(options.exclude ?? [])) : {
+				relationships: state.relationships,
+				metadata: { inferredRelationships: /* @__PURE__ */ new Map() }
+			};
+			const nextAttributes = options.attributes === true ? inferModelAttributes(state.datasets, nextRelationships.relationships, state.attributes) : state.attributes;
+			return createDataModelBuilder({
+				...state,
+				relationships: nextRelationships.relationships,
+				attributes: nextAttributes,
+				inferredRelationshipIds: new Set([...state.inferredRelationshipIds, ...nextRelationships.metadata.inferredRelationships.keys()])
+			});
+		},
+		chart(id, defineChart) {
+			const model = cachedModel ?? createDefinedDataModel(state);
+			cachedModel = model;
+			return compileModelChart(model, id, defineChart);
+		},
+		materialize(id, defineView) {
+			const model = cachedModel ?? createDefinedDataModel(state);
+			cachedModel = model;
+			return defineView(createMaterializationStartBuilder(id, model));
+		},
+		validateData(data) {
+			try {
+				validateModelRuntimeData(state, data);
+			} catch (error) {
+				const model = cachedModel ?? createDefinedDataModel(state);
+				cachedModel = model;
+				rewriteInferredRelationshipError(getModelRuntimeMetadata(model), error);
+			}
+		},
+		build() {
+			if (cachedModel) return cachedModel;
+			cachedModel = createDefinedDataModel(state);
+			return cachedModel;
+		}
+	};
+}
+/**
+* Define one linked data model for dataset registration, relationships,
+* associations, reusable model-level filter attributes, and explicit
+* Phase 7 materialized views.
+*/
+function defineDataModel() {
+	return createDataModelBuilder();
+}
+//#endregion
+export { defineDataModel };