@microsoft/rayfin-semantic-model-pack 1.1.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG +9 -0
  2. package/README.md +16 -5
  3. package/kit/hooks/use-query-factory-target.spec.ts +191 -0
  4. package/kit/hooks/use-query-factory-target.ts +123 -0
  5. package/kit/hooks/use-semantic-model-query.spec.ts +51 -34
  6. package/kit/hooks/use-semantic-model-query.ts +30 -49
  7. package/kit/lib/query-factory.spec.ts +97 -0
  8. package/kit/lib/query-factory.ts +68 -0
  9. package/kit/lib/semantic-model-errors.spec.ts +131 -0
  10. package/kit/lib/semantic-model-errors.ts +110 -0
  11. package/kit/lib/to-data-table.spec.ts +444 -0
  12. package/kit/lib/to-data-table.ts +221 -0
  13. package/pack.json +122 -25
  14. package/package.json +1 -1
  15. package/skills/analytics/SKILL.md +126 -422
  16. package/skills/dax-authoring/SKILL.md +98 -31
  17. package/skills/query-design/SKILL.md +22 -29
  18. package/skills/query-design/references/anti-patterns.md +13 -11
  19. package/skills/query-design/references/format-strings.md +6 -12
  20. package/skills/query-design/references/multi-grain-patterns.md +121 -108
  21. package/skills/schema-discovery/SKILL.md +197 -368
  22. package/skills/schema-discovery/references/discovery-queries.md +6 -8
  23. package/skills/visual-interactivity/SKILL.md +68 -0
  24. package/skills/visual-interactivity/references/advanced-query-shapes.md +155 -0
  25. package/skills/visual-interactivity/references/filter-aware-grid-totals.md +101 -0
  26. package/skills/visual-interactivity/references/highlight-queries.md +89 -0
  27. package/skills/visual-interactivity/references/interaction-manager.md +127 -0
  28. package/skills/visual-interactivity/references/native-selections.md +20 -0
  29. package/skills/visual-interactivity/references/query-factories.md +197 -0
  30. package/kit/scripts/rayfin-connector.mjs +0 -265
  31. package/kit/scripts/rayfin-connector.test.mjs +0 -243
  32. package/kit/scripts/schema-sql-batch.test.mjs +0 -2097
  33. package/kit/scripts/schema-sql-cli.test.mjs +0 -488
  34. package/kit/scripts/schema-sql.mjs +0 -2650
  35. package/kit/scripts/schema-sql.test.mjs +0 -1387
  36. package/kit/scripts/schema.mjs +0 -166
  37. package/kit/scripts/schema.test.mjs +0 -271
  38. package/skills/query-design/references/filter-strategy.md +0 -68
  39. package/skills/query-design/references/highlight-queries.md +0 -122
@@ -0,0 +1,444 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import { describe, it, expect } from "vitest";
9
+ import { splitRollupDataTable, toDataTable, toRollupDataTables } from "@/lib/to-data-table";
10
+ import type { ColumnMetadataMap } from "@/lib/to-data-table";
11
+ import type { ColumnDef, DataTable } from "@microsoft/fabric-visuals-core";
12
+ import type { QueryTableLike } from "@/lib/to-data-table";
13
+
14
+ type QueryTable = {
15
+ columns: { name: string; dataType: string }[];
16
+ rows: QueryTableLike["rows"];
17
+ };
18
+
19
+ describe("toDataTable", () => {
20
+ const queryTable: QueryTable = {
21
+ columns: [
22
+ { name: "Products[Region]", dataType: "string" },
23
+ { name: "[Total Revenue]", dataType: "number" },
24
+ ],
25
+ rows: [
26
+ ["East", 100],
27
+ ["West", 200],
28
+ ],
29
+ };
30
+
31
+ it("merges column metadata with the query table columns", () => {
32
+ const columnMetadata: ColumnMetadataMap = {
33
+ "Products[Region]": { name: "ProductsRegion", displayName: "Region" },
34
+ "[Total Revenue]": { name: "TotalRevenue", displayName: "Total Revenue", format: "$#,0.00" },
35
+ };
36
+
37
+ const result = toDataTable(queryTable, columnMetadata);
38
+
39
+ expect(result.columns).toEqual([
40
+ { name: "ProductsRegion", displayName: "Region" },
41
+ { name: "TotalRevenue", displayName: "Total Revenue", format: "$#,0.00" },
42
+ ]);
43
+ });
44
+
45
+ it("falls back to { name: col.name } for columns with no metadata entry", () => {
46
+ const result = toDataTable(queryTable, {});
47
+
48
+ expect(result.columns).toEqual([
49
+ { name: "Products[Region]" },
50
+ { name: "[Total Revenue]" },
51
+ ]);
52
+ });
53
+
54
+ it("passes rows through unchanged", () => {
55
+ const result = toDataTable(queryTable, {});
56
+
57
+ expect(result.rows).toBe(queryTable.rows);
58
+ });
59
+
60
+ it("applies metadata to known columns and falls back for unknown ones", () => {
61
+ const columnMetadata: ColumnMetadataMap = {
62
+ "Products[Region]": { name: "ProductsRegion", displayName: "Region" },
63
+ };
64
+
65
+ const result = toDataTable(queryTable, columnMetadata);
66
+
67
+ expect(result.columns[0]).toEqual({ name: "ProductsRegion", displayName: "Region" });
68
+ expect(result.columns[1]).toEqual({ name: "[Total Revenue]" });
69
+ });
70
+ });
71
+
72
+ describe("toRollupDataTables", () => {
73
+ const columnMetadata: ColumnMetadataMap = {
74
+ "Region[Name]": { name: "RegionName", displayName: "Region" },
75
+ "[Revenue]": {
76
+ name: "Revenue",
77
+ displayName: "Revenue",
78
+ format: "$#,0.00",
79
+ },
80
+ "[Customer Count]": {
81
+ name: "CustomerCount",
82
+ displayName: "Customer Count",
83
+ format: "#,##0",
84
+ },
85
+ };
86
+
87
+ it("partitions body and one grand-total row and removes rollup flags", () => {
88
+ const queryTable: QueryTable = {
89
+ columns: [
90
+ { name: "Region[Name]", dataType: "string" },
91
+ { name: "[IsGrandTotal]", dataType: "boolean" },
92
+ { name: "[Revenue]", dataType: "number" },
93
+ { name: "[Customer Count]", dataType: "number" },
94
+ ],
95
+ rows: [
96
+ ["East", false, 100, 8],
97
+ ["West", false, 80, 7],
98
+ [null, true, 180, 12],
99
+ ],
100
+ };
101
+
102
+ const result = toRollupDataTables(queryTable, columnMetadata, {
103
+ rollupFlagColumns: ["[IsGrandTotal]"],
104
+ });
105
+
106
+ expect(result.bodyTable).toEqual({
107
+ columns: [
108
+ { name: "RegionName", displayName: "Region" },
109
+ {
110
+ name: "Revenue",
111
+ displayName: "Revenue",
112
+ format: "$#,0.00",
113
+ },
114
+ {
115
+ name: "CustomerCount",
116
+ displayName: "Customer Count",
117
+ format: "#,##0",
118
+ },
119
+ ],
120
+ rows: [
121
+ ["East", 100, 8],
122
+ ["West", 80, 7],
123
+ ],
124
+ });
125
+ expect(result.grandTotalTable).toEqual({
126
+ columns: result.bodyTable.columns,
127
+ rows: [[null, 180, 12]],
128
+ });
129
+ });
130
+
131
+ it("requires every configured rollup flag column", () => {
132
+ const queryTable: QueryTable = {
133
+ columns: [{ name: "[Revenue]", dataType: "number" }],
134
+ rows: [[100]],
135
+ };
136
+
137
+ expect(() =>
138
+ toRollupDataTables(queryTable, columnMetadata, {
139
+ rollupFlagColumns: ["[IsGrandTotal]"],
140
+ }),
141
+ ).toThrow('Rollup flag column "[IsGrandTotal]" was not found.');
142
+ });
143
+
144
+ it("requires at least one rollup flag column", () => {
145
+ const queryTable: QueryTable = {
146
+ columns: [{ name: "[Revenue]", dataType: "number" }],
147
+ rows: [[100]],
148
+ };
149
+
150
+ expect(() =>
151
+ toRollupDataTables(
152
+ queryTable,
153
+ columnMetadata,
154
+ { rollupFlagColumns: [] },
155
+ ),
156
+ ).toThrow("At least one rollup flag column is required.");
157
+ });
158
+
159
+ it("requires every configured internal column", () => {
160
+ const queryTable: QueryTable = {
161
+ columns: [
162
+ { name: "[IsGrandTotal]", dataType: "boolean" },
163
+ { name: "[Revenue]", dataType: "number" },
164
+ ],
165
+ rows: [[true, 100]],
166
+ };
167
+
168
+ expect(() =>
169
+ toRollupDataTables(queryTable, columnMetadata, {
170
+ rollupFlagColumns: ["[IsGrandTotal]"],
171
+ internalColumns: ["[InternalSortKey]"],
172
+ }),
173
+ ).toThrow('Internal column "[InternalSortKey]" was not found.');
174
+ });
175
+
176
+ it("returns an empty grand-total table when the query has no grand-total row", () => {
177
+ const columns = [
178
+ { name: "[IsGrandTotal]", dataType: "boolean" },
179
+ { name: "[Revenue]", dataType: "number" },
180
+ ];
181
+
182
+ const result = toRollupDataTables(
183
+ { columns, rows: [[false, 100]] },
184
+ columnMetadata,
185
+ { rollupFlagColumns: ["[IsGrandTotal]"] },
186
+ );
187
+
188
+ expect(result.bodyTable).toEqual({
189
+ columns: [
190
+ {
191
+ name: "Revenue",
192
+ displayName: "Revenue",
193
+ format: "$#,0.00",
194
+ },
195
+ ],
196
+ rows: [[100]],
197
+ });
198
+ expect(result.grandTotalTable).toEqual({
199
+ columns: result.bodyTable.columns,
200
+ rows: [],
201
+ });
202
+ });
203
+
204
+ it("returns empty tables when an empty result omits the rollup flag column", () => {
205
+ const result = toRollupDataTables(
206
+ { columns: [], rows: [] },
207
+ columnMetadata,
208
+ { rollupFlagColumns: ["[IsGrandTotal]"], internalColumns: ["[InternalSortKey]"] },
209
+ );
210
+
211
+ expect(result.bodyTable).toEqual({ columns: [], rows: [] });
212
+ expect(result.grandTotalTable).toEqual({ columns: [], rows: [] });
213
+ });
214
+
215
+ it("removes rollup flag columns from an empty result that keeps its schema", () => {
216
+ const queryTable: QueryTable = {
217
+ columns: [
218
+ { name: "Region[Name]", dataType: "string" },
219
+ { name: "[IsGrandTotal]", dataType: "boolean" },
220
+ { name: "[Revenue]", dataType: "number" },
221
+ ],
222
+ rows: [],
223
+ };
224
+
225
+ const result = toRollupDataTables(
226
+ queryTable,
227
+ columnMetadata,
228
+ { rollupFlagColumns: ["[IsGrandTotal]"] },
229
+ );
230
+
231
+ expect(result.bodyTable).toEqual({
232
+ columns: [
233
+ { name: "RegionName", displayName: "Region" },
234
+ { name: "Revenue", displayName: "Revenue", format: "$#,0.00" },
235
+ ],
236
+ rows: [],
237
+ });
238
+ expect(result.grandTotalTable).toEqual({ columns: result.bodyTable.columns, rows: [] });
239
+ });
240
+
241
+ it("rejects more than one grand-total row", () => {
242
+ const columns = [
243
+ { name: "[IsGrandTotal]", dataType: "boolean" },
244
+ { name: "[Revenue]", dataType: "number" },
245
+ ];
246
+
247
+ expect(() =>
248
+ toRollupDataTables(
249
+ {
250
+ columns,
251
+ rows: [
252
+ [true, 100],
253
+ [true, 200],
254
+ ],
255
+ },
256
+ columnMetadata,
257
+ { rollupFlagColumns: ["[IsGrandTotal]"] },
258
+ ),
259
+ ).toThrow("Expected at most one grand-total row, received 2.");
260
+ });
261
+
262
+ it("requires boolean rollup flag values", () => {
263
+ const queryTable: QueryTable = {
264
+ columns: [
265
+ { name: "[IsGrandTotal]", dataType: "boolean" },
266
+ { name: "[Revenue]", dataType: "number" },
267
+ ],
268
+ rows: [[null, 100]],
269
+ };
270
+
271
+ expect(() =>
272
+ toRollupDataTables(
273
+ queryTable,
274
+ columnMetadata,
275
+ { rollupFlagColumns: ["[IsGrandTotal]"] },
276
+ ),
277
+ ).toThrow("Rollup flag values must be boolean.");
278
+ });
279
+
280
+ it("rejects subtotal rows until DataGrid supports them", () => {
281
+ const queryTable: QueryTable = {
282
+ columns: [
283
+ { name: "[YearTotal]", dataType: "boolean" },
284
+ { name: "[MonthTotal]", dataType: "boolean" },
285
+ { name: "[Revenue]", dataType: "number" },
286
+ ],
287
+ rows: [
288
+ [false, false, 100],
289
+ [false, true, 100],
290
+ [true, true, 100],
291
+ ],
292
+ };
293
+
294
+ expect(() =>
295
+ toRollupDataTables(queryTable, columnMetadata, {
296
+ rollupFlagColumns: ["[YearTotal]", "[MonthTotal]"],
297
+ }),
298
+ ).toThrow("Subtotal rows are not supported.");
299
+ });
300
+ });
301
+
302
+ describe("splitRollupDataTable", () => {
303
+ const regionColumn: ColumnDef = { name: "RegionName", displayName: "Region" };
304
+ const grandTotalFlagColumn: ColumnDef = { name: "IsGrandTotal" };
305
+ const revenueColumn: ColumnDef = {
306
+ name: "Revenue",
307
+ displayName: "Revenue",
308
+ format: "$#,0.00",
309
+ };
310
+ const sortKeyColumn: ColumnDef = { name: "RegionSortKey" };
311
+
312
+ function freezeDataTable(dataTable: DataTable): DataTable {
313
+ dataTable.rows.forEach((row) => Object.freeze(row));
314
+ Object.freeze(dataTable.rows);
315
+ Object.freeze(dataTable.columns);
316
+ return Object.freeze(dataTable);
317
+ }
318
+
319
+ it("partitions converted body and grand-total rows and keeps column metadata", () => {
320
+ const dataTable: DataTable = freezeDataTable({
321
+ columns: [regionColumn, grandTotalFlagColumn, revenueColumn, sortKeyColumn],
322
+ rows: [
323
+ ["East", false, 100, 2],
324
+ ["West", false, 80, 1],
325
+ [null, true, 180, null],
326
+ ],
327
+ });
328
+
329
+ const result = splitRollupDataTable(dataTable, {
330
+ rollupFlagColumns: ["IsGrandTotal"],
331
+ internalColumns: ["RegionSortKey"],
332
+ });
333
+
334
+ expect(result.bodyTable).toEqual({
335
+ columns: [
336
+ { name: "RegionName", displayName: "Region" },
337
+ { name: "Revenue", displayName: "Revenue", format: "$#,0.00" },
338
+ ],
339
+ rows: [
340
+ ["East", 100],
341
+ ["West", 80],
342
+ ],
343
+ });
344
+ expect(result.grandTotalTable).toEqual({
345
+ columns: result.bodyTable.columns,
346
+ rows: [[null, 180]],
347
+ });
348
+ expect(result.bodyTable.columns[0]).toBe(regionColumn);
349
+ expect(result.bodyTable.columns[1]).toBe(revenueColumn);
350
+ expect(result.grandTotalTable.columns[1]).toBe(revenueColumn);
351
+ expect(dataTable.rows[2]).toEqual([null, true, 180, null]);
352
+ });
353
+
354
+ it("returns an empty grand-total table when the result has no grand-total row", () => {
355
+ const result = splitRollupDataTable(
356
+ { columns: [grandTotalFlagColumn, revenueColumn], rows: [[false, 100]] },
357
+ { rollupFlagColumns: ["IsGrandTotal"] },
358
+ );
359
+
360
+ expect(result.bodyTable.rows).toEqual([[100]]);
361
+ expect(result.grandTotalTable).toEqual({ columns: [revenueColumn], rows: [] });
362
+ });
363
+
364
+ it("returns empty tables when an empty result omits the rollup flag column", () => {
365
+ const result = splitRollupDataTable(
366
+ { columns: [], rows: [] },
367
+ { rollupFlagColumns: ["IsGrandTotal"], internalColumns: ["RegionSortKey"] },
368
+ );
369
+
370
+ expect(result.bodyTable).toEqual({ columns: [], rows: [] });
371
+ expect(result.grandTotalTable).toEqual({ columns: [], rows: [] });
372
+ });
373
+
374
+ it("matches converted column names rather than raw query names", () => {
375
+ expect(() =>
376
+ splitRollupDataTable(
377
+ { columns: [grandTotalFlagColumn, revenueColumn], rows: [[true, 100]] },
378
+ { rollupFlagColumns: ["[IsGrandTotal]"] },
379
+ ),
380
+ ).toThrow('Rollup flag column "[IsGrandTotal]" was not found.');
381
+ });
382
+
383
+ it("requires at least one rollup flag column", () => {
384
+ expect(() =>
385
+ splitRollupDataTable(
386
+ { columns: [revenueColumn], rows: [[100]] },
387
+ { rollupFlagColumns: [] },
388
+ ),
389
+ ).toThrow("At least one rollup flag column is required.");
390
+ });
391
+
392
+ it("requires every configured internal column", () => {
393
+ expect(() =>
394
+ splitRollupDataTable(
395
+ { columns: [grandTotalFlagColumn, revenueColumn], rows: [[true, 100]] },
396
+ {
397
+ rollupFlagColumns: ["IsGrandTotal"],
398
+ internalColumns: ["RegionSortKey"],
399
+ },
400
+ ),
401
+ ).toThrow('Internal column "RegionSortKey" was not found.');
402
+ });
403
+
404
+ it("requires boolean rollup flag values", () => {
405
+ expect(() =>
406
+ splitRollupDataTable(
407
+ { columns: [grandTotalFlagColumn, revenueColumn], rows: [[null, 100]] },
408
+ { rollupFlagColumns: ["IsGrandTotal"] },
409
+ ),
410
+ ).toThrow("Rollup flag values must be boolean.");
411
+ });
412
+
413
+ it("rejects subtotal rows until DataGrid supports them", () => {
414
+ const dataTable: DataTable = {
415
+ columns: [{ name: "YearTotal" }, { name: "MonthTotal" }, revenueColumn],
416
+ rows: [
417
+ [false, false, 100],
418
+ [false, true, 100],
419
+ [true, true, 100],
420
+ ],
421
+ };
422
+
423
+ expect(() =>
424
+ splitRollupDataTable(dataTable, {
425
+ rollupFlagColumns: ["YearTotal", "MonthTotal"],
426
+ }),
427
+ ).toThrow("Subtotal rows are not supported.");
428
+ });
429
+
430
+ it("rejects more than one grand-total row", () => {
431
+ expect(() =>
432
+ splitRollupDataTable(
433
+ {
434
+ columns: [grandTotalFlagColumn, revenueColumn],
435
+ rows: [
436
+ [true, 100],
437
+ [true, 200],
438
+ ],
439
+ },
440
+ { rollupFlagColumns: ["IsGrandTotal"] },
441
+ ),
442
+ ).toThrow("Expected at most one grand-total row, received 2.");
443
+ });
444
+ });
@@ -0,0 +1,221 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import type { ColumnDef, DataTable } from '@microsoft/fabric-visuals-core';
9
+
10
+ /**
11
+ * The shape `toDataTable` reads from a query result: a raw table, before column
12
+ * metadata is merged in.
13
+ *
14
+ * Composed from the `visuals-core` types rather than re-declaring their fields,
15
+ * and narrowed to `name` because that is the only column property this reads -
16
+ * everything else comes from `columnMetadata`. Declared here rather than
17
+ * imported from `@microsoft/rayfin-connector-fabric-semanticmodel` so charting
18
+ * does not drag the semantic-model connector in; that package's `QueryTable`
19
+ * satisfies this structurally.
20
+ */
21
+ export interface QueryTableLike {
22
+ columns: readonly Pick<ColumnDef, 'name'>[];
23
+ rows: DataTable['rows'];
24
+ }
25
+
26
+ /**
27
+ * Dictionary keyed by the original column name from the DAX query result.
28
+ * Each value holds the `ColumnDef` metadata for that column.
29
+ */
30
+ export type ColumnMetadataMap = Record<string, ColumnDef>;
31
+
32
+ export interface RollupDataTables {
33
+ bodyTable: DataTable;
34
+ grandTotalTable: DataTable;
35
+ }
36
+
37
+ export interface RollupDataTableOptions {
38
+ rollupFlagColumns: readonly string[];
39
+ internalColumns?: readonly string[];
40
+ }
41
+
42
+ /**
43
+ * Merges a raw connector query table with static column metadata to produce
44
+ * a `DataTable` that `VegaVisual` and `DataGrid` accept directly.
45
+ *
46
+ * @param queryTable - The `table` value from a successful query result.
47
+ * @param columnMetadata - Metadata dictionary exported from the query barrel file,
48
+ * keyed by the original column name.
49
+ * @returns A `DataTable` with enriched `ColumnDef` entries and the original rows.
50
+ *
51
+ * @remarks
52
+ * `rows` is passed through by reference. Treat results as immutable and derive
53
+ * a new array with `[...rows].sort(...)` rather than mutating in place.
54
+ *
55
+ * @example
56
+ * ```tsx
57
+ * import { columnMetadata, query } from "@/queries/sales/revenue-by-region";
58
+ * import { toDataTable } from "@/lib/to-data-table";
59
+ *
60
+ * const { data } = useSemanticModelQuery({ connection: "myModel", query });
61
+ *
62
+ * if (data?.status === "success") {
63
+ * const dataTable = toDataTable(data.table, columnMetadata);
64
+ * return <VegaVisual spec={vegaLiteSpec} data={dataTable} theme={theme} />;
65
+ * }
66
+ * ```
67
+ */
68
+ export function toDataTable(
69
+ queryTable: QueryTableLike,
70
+ columnMetadata: ColumnMetadataMap,
71
+ ): DataTable {
72
+ const columns: ColumnDef[] = queryTable.columns.map((col) => {
73
+ return columnMetadata[col.name] ?? { name: col.name };
74
+ });
75
+
76
+ return { columns, rows: queryTable.rows };
77
+ }
78
+
79
+ /**
80
+ * Splits a rollup query result into DataGrid body and grand-total tables.
81
+ * Rollup flags and other internal query columns are removed from emitted tables.
82
+ */
83
+ export function toRollupDataTables(
84
+ queryTable: QueryTableLike,
85
+ columnMetadata: ColumnMetadataMap,
86
+ options: RollupDataTableOptions,
87
+ ): RollupDataTables {
88
+ const partition: RollupPartition<Pick<ColumnDef, "name">> = partitionRollupRows(
89
+ queryTable.columns,
90
+ queryTable.rows,
91
+ options,
92
+ );
93
+ const bodyTable = toDataTable(
94
+ { columns: partition.outputColumns, rows: partition.bodyRows },
95
+ columnMetadata,
96
+ );
97
+ return {
98
+ bodyTable,
99
+ grandTotalTable: toDataTable(
100
+ { columns: partition.outputColumns, rows: partition.grandTotalRows },
101
+ columnMetadata,
102
+ ),
103
+ };
104
+ }
105
+
106
+ /**
107
+ * Splits an already converted rollup `DataTable`, such as one returned by
108
+ * `executeQueryFactory`, into DataGrid body and grand-total tables.
109
+ *
110
+ * @param dataTable - A converted table whose column names are the metadata `name` aliases.
111
+ * @param options - Rollup flag and internal columns, named by their converted `ColumnDef.name`.
112
+ * @returns Body and grand-total tables that keep the input `ColumnDef` entries,
113
+ * without the rollup flag and internal columns.
114
+ */
115
+ export function splitRollupDataTable(
116
+ dataTable: DataTable,
117
+ options: RollupDataTableOptions,
118
+ ): RollupDataTables {
119
+ const partition: RollupPartition<ColumnDef> = partitionRollupRows(
120
+ dataTable.columns,
121
+ dataTable.rows,
122
+ options,
123
+ );
124
+
125
+ return {
126
+ bodyTable: { columns: partition.outputColumns, rows: partition.bodyRows },
127
+ grandTotalTable: {
128
+ columns: [...partition.outputColumns],
129
+ rows: partition.grandTotalRows,
130
+ },
131
+ };
132
+ }
133
+
134
+ type DataRow = DataTable["rows"][number];
135
+
136
+ interface RollupPartition<TColumn> {
137
+ outputColumns: TColumn[];
138
+ bodyRows: DataRow[];
139
+ grandTotalRows: DataRow[];
140
+ }
141
+
142
+ /**
143
+ * Validates rollup flags and partitions rows into body and grand-total rows.
144
+ * Emits new row arrays without flag and internal columns; input rows are not mutated.
145
+ * A result with no rows, such as one filtered by an empty slicer selection,
146
+ * yields empty body and grand-total tables.
147
+ */
148
+ function partitionRollupRows<TColumn extends { readonly name: string }>(
149
+ columns: readonly TColumn[],
150
+ rows: readonly DataRow[],
151
+ options: RollupDataTableOptions,
152
+ ): RollupPartition<TColumn> {
153
+ if (options.rollupFlagColumns.length === 0) {
154
+ throw new Error("At least one rollup flag column is required.");
155
+ }
156
+
157
+ const internalColumns: Set<string> = new Set([
158
+ ...options.rollupFlagColumns,
159
+ ...(options.internalColumns ?? []),
160
+ ]);
161
+ const outputIndexes: { column: TColumn; index: number }[] = columns
162
+ .map((column, index) => ({ column, index }))
163
+ .filter(({ column }) => !internalColumns.has(column.name));
164
+
165
+ // When filters exclude every row, the query service can return a schema
166
+ // without the rollup flag and internal columns. There are no rows to
167
+ // partition, so the configured columns are validated only for non-empty results.
168
+ if (rows.length === 0) {
169
+ return {
170
+ outputColumns: outputIndexes.map(({ column }) => column),
171
+ bodyRows: [],
172
+ grandTotalRows: [],
173
+ };
174
+ }
175
+
176
+ const columnIndexes: Map<string, number> = new Map(
177
+ columns.map((column, index) => [column.name, index]),
178
+ );
179
+ const rollupFlagIndexes: number[] = options.rollupFlagColumns.map((columnName) => {
180
+ const index = columnIndexes.get(columnName);
181
+ if (index === undefined) {
182
+ throw new Error(`Rollup flag column "${columnName}" was not found.`);
183
+ }
184
+ return index;
185
+ });
186
+ for (const columnName of options.internalColumns ?? []) {
187
+ if (!columnIndexes.has(columnName)) {
188
+ throw new Error(`Internal column "${columnName}" was not found.`);
189
+ }
190
+ }
191
+ const bodyRows: DataRow[] = [];
192
+ const grandTotalRows: DataRow[] = [];
193
+
194
+ for (const row of rows) {
195
+ const flags = rollupFlagIndexes.map((index) => row[index]);
196
+ if (flags.some((flag) => typeof flag !== "boolean")) {
197
+ throw new Error("Rollup flag values must be boolean.");
198
+ }
199
+
200
+ const outputRow: DataRow = outputIndexes.map(({ index }) => row[index]);
201
+ if (flags.every((flag) => flag === true)) {
202
+ grandTotalRows.push(outputRow);
203
+ } else if (flags.every((flag) => flag === false)) {
204
+ bodyRows.push(outputRow);
205
+ } else {
206
+ throw new Error("Subtotal rows are not supported.");
207
+ }
208
+ }
209
+
210
+ if (grandTotalRows.length > 1) {
211
+ throw new Error(
212
+ `Expected at most one grand-total row, received ${grandTotalRows.length}.`,
213
+ );
214
+ }
215
+
216
+ return {
217
+ outputColumns: outputIndexes.map(({ column }) => column),
218
+ bodyRows,
219
+ grandTotalRows,
220
+ };
221
+ }