@microsoft/rayfin-semantic-model-pack 1.1.0 → 2.0.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.
- package/CHANGELOG +4 -0
- package/README.md +16 -5
- package/kit/hooks/use-query-factory-target.spec.ts +191 -0
- package/kit/hooks/use-query-factory-target.ts +123 -0
- package/kit/hooks/use-semantic-model-query.spec.ts +51 -34
- package/kit/hooks/use-semantic-model-query.ts +30 -49
- package/kit/lib/query-factory.spec.ts +97 -0
- package/kit/lib/query-factory.ts +68 -0
- package/kit/lib/semantic-model-errors.spec.ts +131 -0
- package/kit/lib/semantic-model-errors.ts +110 -0
- package/kit/lib/to-data-table.spec.ts +444 -0
- package/kit/lib/to-data-table.ts +221 -0
- package/pack.json +122 -25
- package/package.json +1 -1
- package/skills/analytics/SKILL.md +126 -422
- package/skills/dax-authoring/SKILL.md +98 -31
- package/skills/query-design/SKILL.md +22 -29
- package/skills/query-design/references/anti-patterns.md +13 -11
- package/skills/query-design/references/format-strings.md +6 -12
- package/skills/query-design/references/multi-grain-patterns.md +121 -108
- package/skills/schema-discovery/SKILL.md +197 -368
- package/skills/schema-discovery/references/discovery-queries.md +6 -8
- package/skills/visual-interactivity/SKILL.md +68 -0
- package/skills/visual-interactivity/references/advanced-query-shapes.md +155 -0
- package/skills/visual-interactivity/references/filter-aware-grid-totals.md +101 -0
- package/skills/visual-interactivity/references/highlight-queries.md +88 -0
- package/skills/visual-interactivity/references/interaction-manager.md +127 -0
- package/skills/visual-interactivity/references/native-selections.md +20 -0
- package/skills/visual-interactivity/references/query-factories.md +169 -0
- package/kit/scripts/rayfin-connector.mjs +0 -265
- package/kit/scripts/rayfin-connector.test.mjs +0 -243
- package/kit/scripts/schema-sql-batch.test.mjs +0 -2097
- package/kit/scripts/schema-sql-cli.test.mjs +0 -488
- package/kit/scripts/schema-sql.mjs +0 -2650
- package/kit/scripts/schema-sql.test.mjs +0 -1387
- package/kit/scripts/schema.mjs +0 -166
- package/kit/scripts/schema.test.mjs +0 -271
- package/skills/query-design/references/filter-strategy.md +0 -68
- package/skills/query-design/references/highlight-queries.md +0 -122
package/CHANGELOG
CHANGED
|
@@ -5,6 +5,10 @@ All notable changes to `@microsoft/rayfin-semantic-model-pack` will be documente
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## 2.0.0 - 2026-11-11
|
|
9
|
+
|
|
10
|
+
- [Rayfin Packs] Unify Lyra skills in shared rayfin pack npm packages
|
|
11
|
+
|
|
8
12
|
## 1.1.0 - 2026-11-05
|
|
9
13
|
|
|
10
14
|
- [Rayfin Packs] Update semantic-model and visuals packs with data-app template fixes
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Agent skills and starter code for Power BI semantic-model analytics in Rayfin ap
|
|
|
8
8
|
> **Purpose**: Capability pack that teaches a coding agent to query a Power BI semantic model from a Rayfin app: connect the model, discover its schema, write DAX, and shape queries for visuals.
|
|
9
9
|
> **Use when**: A Rayfin app template adds semantic-model analytics to an app.
|
|
10
10
|
> **Do NOT use when**: You need a runtime library (use `@microsoft/rayfin-connector-fabric-semanticmodel`), or charts and tables (use `@microsoft/rayfin-visuals-pack`).
|
|
11
|
-
> **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`, plus the `analytics` install layer: `pack.json` and `kit/`
|
|
11
|
+
> **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`, `skills/visual-interactivity`, plus the `analytics` install layer: `pack.json` and `kit/`
|
|
12
12
|
> **Install**: `npm install @microsoft/rayfin-semantic-model-pack`
|
|
13
13
|
|
|
14
14
|
## Contents
|
|
@@ -16,16 +16,18 @@ Agent skills and starter code for Power BI semantic-model analytics in Rayfin ap
|
|
|
16
16
|
The package has no entry point. It has two layers:
|
|
17
17
|
|
|
18
18
|
- `skills/` is the agent content. Each folder is one skill and maps 1:1 to
|
|
19
|
-
`.agents/skills/<name>/` in an app.
|
|
19
|
+
`.agents/skills/<name>/` in an app. The published `analytics` skill combines
|
|
20
|
+
shared guidance with Universal App installation and runtime instructions.
|
|
20
21
|
- `pack.json` and `kit/` at the package root are the Rayfin Universal App's
|
|
21
22
|
install layer for the `analytics` skill, the one named in `pack.json`.
|
|
22
23
|
|
|
23
24
|
| Skill | Contents |
|
|
24
25
|
| --- | --- |
|
|
25
|
-
| `analytics` | Reading a semantic model from the app.
|
|
26
|
+
| `analytics` | Reading a semantic model from the app. The root `pack.json` installs semantic-model tools and the kit's query hooks, error normalization, table conversion and managed query-factory loading |
|
|
26
27
|
| `dax-authoring` | Writing and testing DAX queries |
|
|
27
|
-
| `query-design` | Splitting work between DAX and TypeScript, including multi-grain
|
|
28
|
+
| `query-design` | Splitting work between DAX and TypeScript, including multi-grain queries |
|
|
28
29
|
| `schema-discovery` | Exploring a model's tables, columns, measures, and relationships |
|
|
30
|
+
| `visual-interactivity` | Managed visual selections, cross-filtering, cross-highlighting, filter-aware grid totals and runtime query factories |
|
|
29
31
|
|
|
30
32
|
`pack.json` tells a template how to apply the pack, such as which dependencies
|
|
31
33
|
to add and which kit files to copy where. Its `copy` sources are relative to
|
|
@@ -37,6 +39,14 @@ layout.
|
|
|
37
39
|
|
|
38
40
|
Resolve `@microsoft/rayfin-semantic-model-pack/package.json`, then copy each
|
|
39
41
|
`skills/<name>/` folder next to it into the app's `.agents/skills/<name>/`.
|
|
42
|
+
For Universal App installation, also copy the package-root `pack.json` and
|
|
43
|
+
`kit/` into `.agents/skills/analytics/`. The resulting analytics skill folder
|
|
44
|
+
contains both the guidance and install layer. Then run
|
|
45
|
+
`npm run pack:add -- analytics` after applying the template's `connectors` pack.
|
|
46
|
+
|
|
47
|
+
The Lyra data-app takes only shared guidance directly from the workspace's
|
|
48
|
+
`skills/`, without the sibling `universal-app/` fragment, and follows its own
|
|
49
|
+
runtime setup. It doesn't read `pack.json` or use the composed npm skill.
|
|
40
50
|
|
|
41
51
|
A template that applies packs with `npm run pack:add`, such as the Rayfin
|
|
42
52
|
Universal App, also copies `pack.json` and `kit/` into
|
|
@@ -50,7 +60,8 @@ template without `pack:add` takes `skills/` and doesn't read `pack.json`.
|
|
|
50
60
|
- The skills link to `visuals` from `@microsoft/rayfin-visuals-pack`, and to
|
|
51
61
|
`app-design` and `app-validation`, which the app template
|
|
52
62
|
provides.
|
|
53
|
-
-
|
|
63
|
+
- Schema tools need Node.js 22.13 or later and a supported stable or prerelease Rayfin CLI.
|
|
64
|
+
- `connectors.ts` belongs to the CLI/connectors pack, not analytics.
|
|
54
65
|
- A copier that takes only `skills/<name>/` folders leaves `analytics` without
|
|
55
66
|
its `pack.json`, so `npm run pack:add -- analytics` can't find it. The
|
|
56
67
|
Universal App's copier must also mount the root `pack.json` and `kit/`.
|
|
@@ -0,0 +1,191 @@
|
|
|
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 { beforeEach, describe, expect, expectTypeOf, it, vi } from "vitest";
|
|
9
|
+
import { renderHook } from "@testing-library/react";
|
|
10
|
+
import type { DataTable } from "@microsoft/fabric-visuals-core";
|
|
11
|
+
import type {
|
|
12
|
+
CompiledDaxFilters,
|
|
13
|
+
DaxFilterMode,
|
|
14
|
+
InteractionTargetData,
|
|
15
|
+
InteractionTargetLoadContext,
|
|
16
|
+
InteractionTargetLoader,
|
|
17
|
+
ManagedQueryFactoryParams,
|
|
18
|
+
ManagedTargetLoadState,
|
|
19
|
+
} from "@microsoft/fabric-interaction-manager";
|
|
20
|
+
import { useQueryFactoryTarget } from "./use-query-factory-target";
|
|
21
|
+
import type { HighlightAlignment, HighlightData, QueryFactoryTargetState } from "./use-query-factory-target";
|
|
22
|
+
import type { DataQuery } from "@/lib/query-factory";
|
|
23
|
+
|
|
24
|
+
const { useManagedInteractionTarget, createHighlightData, executeQueryFactory } = vi.hoisted(() => ({
|
|
25
|
+
useManagedInteractionTarget: vi.fn<typeof import("@microsoft/fabric-interaction-manager/react").useManagedInteractionTarget>(),
|
|
26
|
+
createHighlightData: vi.fn(),
|
|
27
|
+
executeQueryFactory: vi.fn<(factory: DataQuery) => Promise<DataTable>>(),
|
|
28
|
+
}));
|
|
29
|
+
vi.mock("@microsoft/fabric-interaction-manager/react", () => ({ useManagedInteractionTarget }));
|
|
30
|
+
vi.mock("@microsoft/fabric-interaction-manager", () => ({ createHighlightData }));
|
|
31
|
+
vi.mock("@/lib/query-factory", () => ({ executeQueryFactory }));
|
|
32
|
+
|
|
33
|
+
interface SalesParams extends ManagedQueryFactoryParams {
|
|
34
|
+
readonly region: string;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// The query text records the factory inputs so each test can see which filters reached the factory.
|
|
38
|
+
function salesByCategory({ region, interactionFilters = [] }: SalesParams): DataQuery {
|
|
39
|
+
return { connection: "sales", query: JSON.stringify({ region, interactionFilters }), columnMetadata: {} };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function tableFor(factory: DataQuery): DataTable {
|
|
43
|
+
return { columns: [{ name: "Query" }], rows: [[factory.query]] };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function contextFor(isCrossHighlightActive: boolean): InteractionTargetLoadContext {
|
|
47
|
+
const compiledFilters: CompiledDaxFilters = {
|
|
48
|
+
getFilters: (mode: DaxFilterMode): readonly string[] => [`${mode} filter`],
|
|
49
|
+
} as CompiledDaxFilters;
|
|
50
|
+
return { isCrossHighlightActive, compiledFilters };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function latestLoader(): InteractionTargetLoader {
|
|
54
|
+
return useManagedInteractionTarget.mock.lastCall![1];
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const alignment: HighlightAlignment = {
|
|
58
|
+
groupingFields: ["Category"],
|
|
59
|
+
missingMeasureReplacementValues: { Value: 0 },
|
|
60
|
+
plottedMeasureFields: ["Value"],
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
beforeEach(() => {
|
|
64
|
+
useManagedInteractionTarget.mockReset().mockReturnValue({ status: "loading" });
|
|
65
|
+
createHighlightData.mockReset().mockImplementation((all: DataTable, highlighted: DataTable) => ({ all, highlighted }));
|
|
66
|
+
executeQueryFactory.mockReset().mockImplementation(async (factory: DataQuery) => tableFor(factory));
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
describe("useQueryFactoryTarget", () => {
|
|
70
|
+
it("preserves the manager's complete load-state contract", () => {
|
|
71
|
+
expectTypeOf<QueryFactoryTargetState<InteractionTargetData>>().toExtend<ManagedTargetLoadState>();
|
|
72
|
+
expectTypeOf<ManagedTargetLoadState>().toExtend<QueryFactoryTargetState<InteractionTargetData>>();
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
it("retains a filter-only target's table and exposes a refresh error", () => {
|
|
76
|
+
const data: DataTable = tableFor(salesByCategory({ region: "West" }));
|
|
77
|
+
const error: Error = new Error("Refresh failed");
|
|
78
|
+
const loadState: ManagedTargetLoadState = { status: "refresh-error", data, isCrossHighlightActive: false, error };
|
|
79
|
+
useManagedInteractionTarget.mockReturnValue(loadState);
|
|
80
|
+
|
|
81
|
+
const { result } = renderHook(() => useQueryFactoryTarget("salesGrid", salesByCategory, { region: "West" }));
|
|
82
|
+
|
|
83
|
+
expect(result.current).toBe(loadState);
|
|
84
|
+
expect(result.current.status).toBe("refresh-error");
|
|
85
|
+
if (result.current.status === "refresh-error") {
|
|
86
|
+
expectTypeOf(result.current.data).toEqualTypeOf<DataTable>();
|
|
87
|
+
expectTypeOf(result.current.error).toEqualTypeOf<Error>();
|
|
88
|
+
expect(result.current.data).toBe(data);
|
|
89
|
+
expect(result.current.error).toBe(error);
|
|
90
|
+
expect(result.current.isCrossHighlightActive).toBe(false);
|
|
91
|
+
}
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
it("retains both highlight datasets and their flag when a refresh fails", () => {
|
|
95
|
+
const data: HighlightData = {
|
|
96
|
+
all: tableFor(salesByCategory({ region: "West" })),
|
|
97
|
+
highlighted: tableFor(salesByCategory({ region: "West", interactionFilters: ["highlight filter"] })),
|
|
98
|
+
};
|
|
99
|
+
const error: Error = new Error("Highlight refresh failed");
|
|
100
|
+
const loadState: ManagedTargetLoadState = { status: "refresh-error", data, isCrossHighlightActive: true, error };
|
|
101
|
+
useManagedInteractionTarget.mockReturnValue(loadState);
|
|
102
|
+
|
|
103
|
+
const { result } = renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
|
|
104
|
+
|
|
105
|
+
expect(result.current).toBe(loadState);
|
|
106
|
+
expect(result.current.status).toBe("refresh-error");
|
|
107
|
+
if (result.current.status === "refresh-error") {
|
|
108
|
+
expectTypeOf(result.current.data).toEqualTypeOf<HighlightData>();
|
|
109
|
+
expectTypeOf(result.current.error).toEqualTypeOf<Error>();
|
|
110
|
+
expect(result.current.data).toBe(data);
|
|
111
|
+
expect(result.current.error).toBe(error);
|
|
112
|
+
expect(result.current.isCrossHighlightActive).toBe(true);
|
|
113
|
+
}
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
it("loads a filter-only target from the factory under the baseline filters", async () => {
|
|
117
|
+
renderHook(() => useQueryFactoryTarget("salesGrid", salesByCategory, { region: "West" }));
|
|
118
|
+
|
|
119
|
+
expect(useManagedInteractionTarget.mock.lastCall![0]).toBe("salesGrid");
|
|
120
|
+
await expect(latestLoader()(contextFor(true))).resolves.toEqual(
|
|
121
|
+
tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] })),
|
|
122
|
+
);
|
|
123
|
+
expect(executeQueryFactory).toHaveBeenCalledTimes(1);
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
it("returns the baseline as both datasets when no highlight is active", async () => {
|
|
127
|
+
const { result, rerender } = renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
|
|
128
|
+
|
|
129
|
+
const all: DataTable = tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] }));
|
|
130
|
+
const loaded: InteractionTargetData = await latestLoader()(contextFor(false));
|
|
131
|
+
useManagedInteractionTarget.mockReturnValue({ status: "ready", data: loaded, isCrossHighlightActive: false });
|
|
132
|
+
rerender();
|
|
133
|
+
const state: QueryFactoryTargetState<HighlightData> = result.current;
|
|
134
|
+
if (state.status === "loading" || state.status === "error") throw new Error("Expected loaded highlight data");
|
|
135
|
+
const data: Record<string, DataTable> = state.data;
|
|
136
|
+
expect(data).toEqual({ all, highlighted: all });
|
|
137
|
+
expect(executeQueryFactory).toHaveBeenCalledTimes(1);
|
|
138
|
+
expect(createHighlightData).not.toHaveBeenCalled();
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
it("aligns the factory's highlighted subset with its baseline during a cross-highlight", async () => {
|
|
142
|
+
renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
|
|
143
|
+
|
|
144
|
+
await latestLoader()(contextFor(true));
|
|
145
|
+
expect(createHighlightData).toHaveBeenCalledWith(
|
|
146
|
+
tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] })),
|
|
147
|
+
tableFor(salesByCategory({ region: "West", interactionFilters: ["highlight filter"] })),
|
|
148
|
+
["Category"],
|
|
149
|
+
{ Value: 0 },
|
|
150
|
+
["Value"],
|
|
151
|
+
);
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
it("returns real aligned highlight rows, preserving baseline keys missing from the selection", async () => {
|
|
155
|
+
const actual = await vi.importActual<typeof import("@microsoft/fabric-interaction-manager")>(
|
|
156
|
+
"@microsoft/fabric-interaction-manager",
|
|
157
|
+
);
|
|
158
|
+
createHighlightData.mockImplementation(actual.createHighlightData);
|
|
159
|
+
const all: DataTable = {
|
|
160
|
+
columns: [{ name: "Category" }, { name: "Value" }],
|
|
161
|
+
rows: [["Bikes", 100], ["Accessories", 50]],
|
|
162
|
+
};
|
|
163
|
+
const subset: DataTable = { columns: all.columns, rows: [["Accessories", 20]] };
|
|
164
|
+
executeQueryFactory.mockResolvedValueOnce(all).mockResolvedValueOnce(subset);
|
|
165
|
+
renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
|
|
166
|
+
|
|
167
|
+
await expect(latestLoader()(contextFor(true))).resolves.toEqual({
|
|
168
|
+
all,
|
|
169
|
+
highlighted: { columns: all.columns, rows: [["Bikes", 0], ["Accessories", 20]] },
|
|
170
|
+
});
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
it("keeps the loader while inline inputs have the same contents", () => {
|
|
174
|
+
const { rerender } = renderHook(
|
|
175
|
+
({ region }: { region: string }) => useQueryFactoryTarget(
|
|
176
|
+
"salesChart",
|
|
177
|
+
salesByCategory,
|
|
178
|
+
{ region },
|
|
179
|
+
{ ...alignment, groupingFields: [...alignment.groupingFields] },
|
|
180
|
+
),
|
|
181
|
+
{ initialProps: { region: "West" } },
|
|
182
|
+
);
|
|
183
|
+
const initialLoader: InteractionTargetLoader = latestLoader();
|
|
184
|
+
|
|
185
|
+
rerender({ region: "West" });
|
|
186
|
+
expect(latestLoader()).toBe(initialLoader);
|
|
187
|
+
|
|
188
|
+
rerender({ region: "East" });
|
|
189
|
+
expect(latestLoader()).not.toBe(initialLoader);
|
|
190
|
+
});
|
|
191
|
+
});
|
|
@@ -0,0 +1,123 @@
|
|
|
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 { useMemo, useState } from "react";
|
|
9
|
+
import type { DataTable } from "@microsoft/fabric-visuals-core";
|
|
10
|
+
import { createHighlightData } from "@microsoft/fabric-interaction-manager";
|
|
11
|
+
import type {
|
|
12
|
+
InteractionTargetData,
|
|
13
|
+
InteractionTargetLoadContext,
|
|
14
|
+
InteractionTargetLoader,
|
|
15
|
+
ManagedQueryFactoryParams,
|
|
16
|
+
ManagedTargetLoadState,
|
|
17
|
+
} from "@microsoft/fabric-interaction-manager";
|
|
18
|
+
import { useManagedInteractionTarget } from "@microsoft/fabric-interaction-manager/react";
|
|
19
|
+
import { executeQueryFactory } from "@/lib/query-factory";
|
|
20
|
+
import type { DataQuery } from "@/lib/query-factory";
|
|
21
|
+
|
|
22
|
+
/** The `createHighlightData` settings that align a highlighted subset with its baseline. */
|
|
23
|
+
export interface HighlightAlignment {
|
|
24
|
+
/** Every group and series key column, including hidden identifiers. */
|
|
25
|
+
readonly groupingFields: readonly string[];
|
|
26
|
+
/** The value for each measure column in baseline groups absent from the highlighted subset. */
|
|
27
|
+
readonly missingMeasureReplacementValues: Readonly<Record<string, number | null>>;
|
|
28
|
+
/** The measure columns the chart draws. */
|
|
29
|
+
readonly plottedMeasureFields: readonly string[];
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The baseline and aligned highlighted datasets of a highlight-capable target. */
|
|
33
|
+
export type HighlightData = {
|
|
34
|
+
readonly all: DataTable;
|
|
35
|
+
readonly highlighted: DataTable;
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** A managed target load state whose data has the shape this hook's loader returns. */
|
|
39
|
+
export type QueryFactoryTargetState<TData extends InteractionTargetData> = {
|
|
40
|
+
// Preserve every manager state and its fields, narrowing only the loader's data shape.
|
|
41
|
+
[TState in ManagedTargetLoadState as TState["status"]]: TState extends { readonly data: InteractionTargetData }
|
|
42
|
+
? Omit<TState, "data"> & { readonly data: TData }
|
|
43
|
+
: TState;
|
|
44
|
+
}[ManagedTargetLoadState["status"]];
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Loads a managed interaction target from a query factory. The hook passes the target's baseline
|
|
48
|
+
* filters to the factory and returns one table. With a highlight alignment, it also runs the factory
|
|
49
|
+
* under the highlight filters during an active cross-highlight and returns `{ all, highlighted }`.
|
|
50
|
+
* `params` are the factory's app inputs other than `interactionFilters`.
|
|
51
|
+
*/
|
|
52
|
+
export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
|
|
53
|
+
targetId: string,
|
|
54
|
+
factory: (params: TParams) => DataQuery,
|
|
55
|
+
params: Omit<TParams, "interactionFilters">,
|
|
56
|
+
): QueryFactoryTargetState<DataTable>;
|
|
57
|
+
export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
|
|
58
|
+
targetId: string,
|
|
59
|
+
factory: (params: TParams) => DataQuery,
|
|
60
|
+
params: Omit<TParams, "interactionFilters">,
|
|
61
|
+
highlightAlignment: HighlightAlignment,
|
|
62
|
+
): QueryFactoryTargetState<HighlightData>;
|
|
63
|
+
export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
|
|
64
|
+
targetId: string,
|
|
65
|
+
factory: (params: TParams) => DataQuery,
|
|
66
|
+
params: Omit<TParams, "interactionFilters">,
|
|
67
|
+
highlightAlignment?: HighlightAlignment,
|
|
68
|
+
): QueryFactoryTargetState<InteractionTargetData> {
|
|
69
|
+
// Keep track of the loader inputs and only update them when the JSON-serialized key changes.
|
|
70
|
+
// This prevents unnecessary reloads when inline objects are used.
|
|
71
|
+
const inputsKey: string = JSON.stringify([params, highlightAlignment ?? null]);
|
|
72
|
+
const [loaderInputs, setLoaderInputs] = useState({ inputsKey, params, highlightAlignment });
|
|
73
|
+
if (loaderInputs.inputsKey !== inputsKey) {
|
|
74
|
+
setLoaderInputs({ inputsKey, params, highlightAlignment });
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const loader: InteractionTargetLoader = useMemo(
|
|
78
|
+
(): InteractionTargetLoader => createQueryFactoryLoader(factory, loaderInputs.params, loaderInputs.highlightAlignment),
|
|
79
|
+
[factory, loaderInputs],
|
|
80
|
+
);
|
|
81
|
+
|
|
82
|
+
return useManagedInteractionTarget(targetId, loader);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function createQueryFactoryLoader<TParams extends ManagedQueryFactoryParams>(
|
|
86
|
+
factory: (params: TParams) => DataQuery,
|
|
87
|
+
params: Omit<TParams, "interactionFilters">,
|
|
88
|
+
highlightAlignment: HighlightAlignment | undefined,
|
|
89
|
+
): InteractionTargetLoader {
|
|
90
|
+
// `params` holds every factory input except `interactionFilters`, so adding the filters gives the
|
|
91
|
+
// factory its complete input. TypeScript cannot prove that `Omit<TParams, "interactionFilters">`
|
|
92
|
+
// plus `interactionFilters` equals a generic `TParams`, so the cast states it.
|
|
93
|
+
const loadTable = (interactionFilters: readonly string[]): Promise<DataTable> =>
|
|
94
|
+
executeQueryFactory(factory({ ...params, interactionFilters } as TParams));
|
|
95
|
+
|
|
96
|
+
return async ({ isCrossHighlightActive, compiledFilters }: InteractionTargetLoadContext): Promise<InteractionTargetData> => {
|
|
97
|
+
if (highlightAlignment) {
|
|
98
|
+
if (isCrossHighlightActive) {
|
|
99
|
+
// Both queries come from the same factory, so they share grouping keys, measures,
|
|
100
|
+
// aliases, and app filters; only the interaction filter scope differs.
|
|
101
|
+
const [all, highlightedSubset]: [DataTable, DataTable] = await Promise.all([
|
|
102
|
+
loadTable(compiledFilters.getFilters("baseline")),
|
|
103
|
+
loadTable(compiledFilters.getFilters("highlight")),
|
|
104
|
+
]);
|
|
105
|
+
|
|
106
|
+
return createHighlightData(
|
|
107
|
+
all,
|
|
108
|
+
highlightedSubset,
|
|
109
|
+
highlightAlignment.groupingFields,
|
|
110
|
+
highlightAlignment.missingMeasureReplacementValues,
|
|
111
|
+
highlightAlignment.plottedMeasureFields,
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// If cross-highlight is not active, just load the baseline table and use it for both all and highlighted.
|
|
116
|
+
const all: DataTable = await loadTable(compiledFilters.getFilters("baseline"));
|
|
117
|
+
return { all, highlighted: all };
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
// Cross-highlight is not enabled, so just load the baseline table (which includes cross filters if any)
|
|
121
|
+
return loadTable(compiledFilters.getFilters("baseline"));
|
|
122
|
+
};
|
|
123
|
+
}
|
|
@@ -14,8 +14,12 @@
|
|
|
14
14
|
|
|
15
15
|
import { renderHook, act, waitFor } from '@testing-library/react';
|
|
16
16
|
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
|
17
|
+
import { NetworkError } from '@microsoft/rayfin-lib';
|
|
18
|
+
import type { WorkloadFailure } from '@microsoft/rayfin-lib';
|
|
19
|
+
import { ConnectorsError } from '@microsoft/rayfin-connectors';
|
|
17
20
|
|
|
18
21
|
import { useSemanticModelQuery } from '@/hooks/use-semantic-model-query';
|
|
22
|
+
import { isThrottlingError } from '@/lib/semantic-model-errors';
|
|
19
23
|
|
|
20
24
|
const executeQuery = vi.fn();
|
|
21
25
|
const connectors: Record<string, unknown> = {};
|
|
@@ -28,10 +32,7 @@ const connectors: Record<string, unknown> = {};
|
|
|
28
32
|
const connectorsProxy = new Proxy(connectors, {
|
|
29
33
|
get(target, key: string) {
|
|
30
34
|
if (!(key in target)) {
|
|
31
|
-
throw
|
|
32
|
-
new Error(`Connector "${key}" was accessed but has no configuration.`),
|
|
33
|
-
{ code: 'UNKNOWN_CONNECTOR' }
|
|
34
|
-
);
|
|
35
|
+
throw new ConnectorsError(`Connector "${key}" was accessed but has no configuration.`, 'UNKNOWN_CONNECTOR');
|
|
35
36
|
}
|
|
36
37
|
return target[key];
|
|
37
38
|
},
|
|
@@ -122,7 +123,7 @@ describe('useSemanticModelQuery', () => {
|
|
|
122
123
|
expect(result.current.error).toBeUndefined();
|
|
123
124
|
});
|
|
124
125
|
|
|
125
|
-
it('
|
|
126
|
+
it('mirrors a returned query failure onto error without losing its category', async () => {
|
|
126
127
|
executeQuery.mockResolvedValue({
|
|
127
128
|
status: 'Succeeded',
|
|
128
129
|
output: { tables: [], queryError: { message: 'bad DAX' } },
|
|
@@ -137,25 +138,42 @@ describe('useSemanticModelQuery', () => {
|
|
|
137
138
|
expect(
|
|
138
139
|
result.current.data?.status === 'error' && result.current.data.error
|
|
139
140
|
).toMatchObject({ category: 'query', message: 'bad DAX' });
|
|
140
|
-
|
|
141
|
-
// structured branch and the category is unreachable.
|
|
142
|
-
expect(result.current.error).toBeUndefined();
|
|
141
|
+
expect(result.current.error?.message).toBe('bad DAX');
|
|
143
142
|
});
|
|
144
143
|
|
|
145
|
-
it('
|
|
146
|
-
|
|
147
|
-
// status and service code — exactly what separates an auth failure from a
|
|
148
|
-
// malformed query.
|
|
149
|
-
const thrown = Object.assign(new Error('401 Unauthorized'), {
|
|
150
|
-
status: 401,
|
|
151
|
-
});
|
|
144
|
+
it('normalizes thrown API failures with diagnostics and original cause', async () => {
|
|
145
|
+
const thrown = new NetworkError('401 Unauthorized', 401, 'AccessDenied');
|
|
152
146
|
executeQuery.mockRejectedValue(thrown);
|
|
153
147
|
|
|
154
148
|
const { result } = render();
|
|
155
149
|
|
|
156
150
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
157
|
-
expect(result.current.error).toBe(thrown);
|
|
158
|
-
expect(
|
|
151
|
+
expect(result.current.error?.cause).toBe(thrown);
|
|
152
|
+
expect(result.current.data?.status).toBe('error');
|
|
153
|
+
if (result.current.data?.status === 'error') {
|
|
154
|
+
expect(result.current.data.error).toMatchObject({
|
|
155
|
+
category: 'api', code: 'AccessDenied', cause: thrown,
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
it.each([429, 500])('preserves structured throttle diagnostics on the convenience error for HTTP %s', async (httpStatus: number): Promise<void> => {
|
|
161
|
+
const workload: WorkloadFailure = {
|
|
162
|
+
errorCode: 'WorkloadException', subErrorCode: 'TooManyRequests', status: 'Failed',
|
|
163
|
+
};
|
|
164
|
+
const thrown: NetworkError = Object.assign(new NetworkError('Invocation failed', httpStatus, 'InvocationFailure'), { workload });
|
|
165
|
+
executeQuery.mockRejectedValue(thrown);
|
|
166
|
+
|
|
167
|
+
const { result } = render();
|
|
168
|
+
await waitFor(() => expect(result.current.isLoading).toBe(false));
|
|
169
|
+
|
|
170
|
+
expect(result.current.error).toMatchObject({
|
|
171
|
+
category: 'api', code: 'InvocationFailure', httpStatus, workload, cause: thrown,
|
|
172
|
+
});
|
|
173
|
+
expect(isThrottlingError(result.current.error)).toBe(true);
|
|
174
|
+
expect(result.current.data).toMatchObject({
|
|
175
|
+
status: 'error', error: { httpStatus, workload, cause: thrown },
|
|
176
|
+
});
|
|
159
177
|
});
|
|
160
178
|
|
|
161
179
|
it('clears a stale result when a later query throws', async () => {
|
|
@@ -172,12 +190,10 @@ describe('useSemanticModelQuery', () => {
|
|
|
172
190
|
rerender({ query: 'EVALUATE ROW(2)' });
|
|
173
191
|
|
|
174
192
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
175
|
-
|
|
176
|
-
// as a result either.
|
|
177
|
-
expect(result.current.data).toBeUndefined();
|
|
193
|
+
expect(result.current.data?.status).toBe('error');
|
|
178
194
|
});
|
|
179
195
|
|
|
180
|
-
it('
|
|
196
|
+
it('names an unregistered connector as a wiring mistake', async () => {
|
|
181
197
|
// The proxy throws for a name with no config. Left untranslated that
|
|
182
198
|
// surfaces as a generic transport failure, sending the builder to look at
|
|
183
199
|
// Fabric instead of at their own registration.
|
|
@@ -187,8 +203,8 @@ describe('useSemanticModelQuery', () => {
|
|
|
187
203
|
|
|
188
204
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
189
205
|
expect(result.current.error?.message).toBe(
|
|
190
|
-
|
|
191
|
-
|
|
206
|
+
'No connector named "model". Check that the name matches rayfin/rayfin.yml, ' +
|
|
207
|
+
'or add it with `npx rayfin connector add`.'
|
|
192
208
|
);
|
|
193
209
|
// The original is kept so the SDK's own code is still recoverable.
|
|
194
210
|
expect((result.current.error?.cause as { code?: string })?.code).toBe(
|
|
@@ -197,23 +213,24 @@ describe('useSemanticModelQuery', () => {
|
|
|
197
213
|
expect(executeQuery).not.toHaveBeenCalled();
|
|
198
214
|
});
|
|
199
215
|
|
|
200
|
-
it('
|
|
216
|
+
it('normalizes an undefined connector lookup without invoking a query', async () => {
|
|
201
217
|
connectors.model = undefined;
|
|
202
|
-
|
|
203
218
|
const { result } = render();
|
|
204
219
|
|
|
205
220
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
);
|
|
210
|
-
expect(result.current.error?.cause).
|
|
211
|
-
expect(result.current.data).
|
|
212
|
-
|
|
221
|
+
const message: string =
|
|
222
|
+
'No connector named "model". Check that the name matches rayfin/rayfin.yml, ' +
|
|
223
|
+
'or add it with `npx rayfin connector add`.';
|
|
224
|
+
expect(result.current.error?.message).toBe(message);
|
|
225
|
+
expect(result.current.error?.cause).toMatchObject({ code: 'UNKNOWN_CONNECTOR', message });
|
|
226
|
+
expect(result.current.data).toMatchObject({
|
|
227
|
+
status: 'error',
|
|
228
|
+
error: { category: 'unknown', code: 'UNKNOWN_CONNECTOR' },
|
|
229
|
+
});
|
|
213
230
|
expect(executeQuery).not.toHaveBeenCalled();
|
|
214
231
|
});
|
|
215
232
|
|
|
216
|
-
it('says so when the app never
|
|
233
|
+
it('says so when the app never registered connectorsService', async () => {
|
|
217
234
|
// The base template builds a plain RayfinClient with no `connectors`, and no
|
|
218
235
|
// pack rewrites that file. Without this the first symptom is an unrelated
|
|
219
236
|
// TypeError deep in the hook.
|
|
@@ -222,7 +239,7 @@ describe('useSemanticModelQuery', () => {
|
|
|
222
239
|
const { result } = render();
|
|
223
240
|
|
|
224
241
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
225
|
-
expect(result.current.error?.message).toContain('
|
|
242
|
+
expect(result.current.error?.message).toContain('connectorsService');
|
|
226
243
|
expect(executeQuery).not.toHaveBeenCalled();
|
|
227
244
|
});
|
|
228
245
|
|