@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.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.
Files changed (29) hide show
  1. package/CHANGELOG +10 -0
  2. package/LICENSE +21 -0
  3. package/README.md +65 -2
  4. package/package.json +10 -3
  5. package/skills/analytics/SKILL.md +460 -0
  6. package/skills/analytics/kit/hooks/use-semantic-model-query.spec.ts +342 -0
  7. package/skills/analytics/kit/hooks/use-semantic-model-query.ts +229 -0
  8. package/skills/analytics/kit/lib/connectors.ts +94 -0
  9. package/skills/analytics/kit/scripts/rayfin-connector.mjs +265 -0
  10. package/skills/analytics/kit/scripts/rayfin-connector.test.mjs +243 -0
  11. package/skills/analytics/kit/scripts/schema-sql-batch.test.mjs +2097 -0
  12. package/skills/analytics/kit/scripts/schema-sql-cli.test.mjs +488 -0
  13. package/skills/analytics/kit/scripts/schema-sql.mjs +2650 -0
  14. package/skills/analytics/kit/scripts/schema-sql.test.mjs +1387 -0
  15. package/skills/analytics/kit/scripts/schema.mjs +166 -0
  16. package/skills/analytics/kit/scripts/schema.test.mjs +271 -0
  17. package/skills/analytics/pack.json +49 -0
  18. package/skills/dax-authoring/SKILL.md +172 -0
  19. package/skills/dax-authoring/references/dax-core-reference.md +862 -0
  20. package/skills/dax-authoring/references/dax-query-patterns.md +396 -0
  21. package/skills/dax-authoring/references/dax-time-intelligence.md +347 -0
  22. package/skills/query-design/SKILL.md +114 -0
  23. package/skills/query-design/references/anti-patterns.md +285 -0
  24. package/skills/query-design/references/filter-strategy.md +68 -0
  25. package/skills/query-design/references/format-strings.md +62 -0
  26. package/skills/query-design/references/highlight-queries.md +122 -0
  27. package/skills/query-design/references/multi-grain-patterns.md +159 -0
  28. package/skills/schema-discovery/SKILL.md +382 -0
  29. package/skills/schema-discovery/references/discovery-queries.md +153 -0
@@ -0,0 +1,342 @@
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
+ // Runs once the pack has copied this kit into an app: the template's vitest
9
+ // `include` is `src/**/*.spec.ts`, and these imports resolve against the copied
10
+ // locations rather than the kit.
11
+ //
12
+ // Only the Rayfin client is mocked, so the connector's own `toQueryResult` runs
13
+ // for real against wire-shaped responses.
14
+
15
+ import { renderHook, act, waitFor } from '@testing-library/react';
16
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
17
+
18
+ import { useSemanticModelQuery } from '@/hooks/use-semantic-model-query';
19
+
20
+ const executeQuery = vi.fn();
21
+ const connectors: Record<string, unknown> = {};
22
+
23
+ /**
24
+ * Stands in for the SDK's connectors proxy, which **throws**
25
+ * `ConnectorsError('UNKNOWN_CONNECTOR')` for an unconfigured name rather than
26
+ * returning `undefined`.
27
+ */
28
+ const connectorsProxy = new Proxy(connectors, {
29
+ get(target, key: string) {
30
+ if (!(key in target)) {
31
+ throw Object.assign(
32
+ new Error(`Connector "${key}" was accessed but has no configuration.`),
33
+ { code: 'UNKNOWN_CONNECTOR' }
34
+ );
35
+ }
36
+ return target[key];
37
+ },
38
+ });
39
+
40
+ let clientHasConnectors = true;
41
+
42
+ vi.mock('@/lib/rayfin-client', () => ({
43
+ // Async, matching this template's client: the hook has to await it rather
44
+ // than index a synchronous singleton.
45
+ getRayfinClient: () =>
46
+ Promise.resolve(clientHasConnectors ? { connectors: connectorsProxy } : {}),
47
+ }));
48
+
49
+ /** A wire-shaped success, as the FuncSet adapter returns it. */
50
+ const wireSuccess = (total: number) => ({
51
+ status: 'Succeeded',
52
+ output: {
53
+ tables: [{ rows: [{ 'Sales[Total]': total }] }],
54
+ requestId: 'r1',
55
+ },
56
+ errors: [],
57
+ });
58
+
59
+ describe('useSemanticModelQuery', () => {
60
+ beforeEach(() => {
61
+ vi.clearAllMocks();
62
+ for (const key of Object.keys(connectors)) delete connectors[key];
63
+ connectors.model = { executeQuery };
64
+ clientHasConnectors = true;
65
+ });
66
+
67
+ const render = (connection = 'model', query = 'EVALUATE ROW()') =>
68
+ renderHook(() => useSemanticModelQuery({ connection, query }));
69
+
70
+ it('starts in the loading state', () => {
71
+ executeQuery.mockReturnValue(new Promise(() => {}));
72
+
73
+ const { result } = render();
74
+
75
+ expect(result.current.isLoading).toBe(true);
76
+ expect(result.current.data).toBeUndefined();
77
+ expect(result.current.error).toBeUndefined();
78
+ });
79
+
80
+ it('normalises a successful response into column-aligned rows', async () => {
81
+ executeQuery.mockResolvedValue(wireSuccess(42));
82
+
83
+ const { result } = render();
84
+
85
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
86
+ expect(result.current.data).toEqual({
87
+ status: 'success',
88
+ table: {
89
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
90
+ rows: [[42]],
91
+ },
92
+ requestId: 'r1',
93
+ });
94
+ expect(result.current.error).toBeUndefined();
95
+ });
96
+
97
+ it('publishes an already-normalised result unchanged', async () => {
98
+ // A registered runtime normalises internally, so this arrives as the union
99
+ // rather than the wire shape. A connector missing from `connectorRuntimes`
100
+ // falls through to raw JSON and does arrive in the wire shape, so this
101
+ // pins that both paths agree.
102
+ executeQuery.mockResolvedValue({
103
+ status: 'success',
104
+ table: {
105
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
106
+ rows: [[7]],
107
+ },
108
+ requestId: 'r9',
109
+ });
110
+
111
+ const { result } = render();
112
+
113
+ await waitFor(() => expect(result.current.data).toBeDefined());
114
+ expect(result.current.data).toEqual({
115
+ status: 'success',
116
+ table: {
117
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
118
+ rows: [[7]],
119
+ },
120
+ requestId: 'r9',
121
+ });
122
+ expect(result.current.error).toBeUndefined();
123
+ });
124
+
125
+ it('reports a failure Power BI returned on the data channel only', async () => {
126
+ executeQuery.mockResolvedValue({
127
+ status: 'Succeeded',
128
+ output: { tables: [], queryError: { message: 'bad DAX' } },
129
+ errors: [],
130
+ });
131
+
132
+ const { result } = render();
133
+
134
+ await waitFor(() => expect(result.current.data).toBeDefined());
135
+ expect(result.current.data?.status).toBe('error');
136
+ // Categorised by the connector, not invented here.
137
+ expect(
138
+ result.current.data?.status === 'error' && result.current.data.error
139
+ ).toMatchObject({ category: 'query', message: 'bad DAX' });
140
+ // `error` must stay clear, or a caller checking it first never reaches the
141
+ // structured branch and the category is unreachable.
142
+ expect(result.current.error).toBeUndefined();
143
+ });
144
+
145
+ it('surfaces the thrown error itself, not a copy of its message', async () => {
146
+ // Re-wrapping into a fresh Error keeps only the message and drops the
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
+ });
152
+ executeQuery.mockRejectedValue(thrown);
153
+
154
+ const { result } = render();
155
+
156
+ await waitFor(() => expect(result.current.error).toBeDefined());
157
+ expect(result.current.error).toBe(thrown);
158
+ expect((result.current.error as { status?: number }).status).toBe(401);
159
+ });
160
+
161
+ it('clears a stale result when a later query throws', async () => {
162
+ // Prevents rows staying on screen under an error banner. Asserting this on
163
+ // the first query would pass either way - there has to be a result to lose.
164
+ executeQuery.mockResolvedValueOnce(wireSuccess(42));
165
+ const { result, rerender } = renderHook(
166
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
167
+ { initialProps: { query: 'EVALUATE ROW()' } }
168
+ );
169
+ await waitFor(() => expect(result.current.data).toBeDefined());
170
+
171
+ executeQuery.mockRejectedValueOnce(new Error('401 Unauthorized'));
172
+ rerender({ query: 'EVALUATE ROW(2)' });
173
+
174
+ await waitFor(() => expect(result.current.error).toBeDefined());
175
+ // A throw is not something Power BI returned, so it must not be dressed up
176
+ // as a result either.
177
+ expect(result.current.data).toBeUndefined();
178
+ });
179
+
180
+ it('names an unregistered connector as a wiring mistake', async () => {
181
+ // The proxy throws for a name with no config. Left untranslated that
182
+ // surfaces as a generic transport failure, sending the builder to look at
183
+ // Fabric instead of at their own registration.
184
+ delete connectors.model;
185
+
186
+ const { result } = render();
187
+
188
+ await waitFor(() => expect(result.current.error).toBeDefined());
189
+ expect(result.current.error?.message).toContain('connectorRuntimes');
190
+ // The original is kept so the SDK's own code is still recoverable.
191
+ expect((result.current.error?.cause as { code?: string })?.code).toBe(
192
+ 'UNKNOWN_CONNECTOR'
193
+ );
194
+ expect(executeQuery).not.toHaveBeenCalled();
195
+ });
196
+
197
+ it('says so when the app never wired ConnectorsRayfinClient', async () => {
198
+ // The base template builds a plain RayfinClient with no `connectors`, and no
199
+ // pack rewrites that file. Without this the first symptom is an unrelated
200
+ // TypeError deep in the hook.
201
+ clientHasConnectors = false;
202
+
203
+ const { result } = render();
204
+
205
+ await waitFor(() => expect(result.current.error).toBeDefined());
206
+ expect(result.current.error?.message).toContain('ConnectorsRayfinClient');
207
+ expect(executeQuery).not.toHaveBeenCalled();
208
+ });
209
+
210
+ it('does not let a slow earlier query overwrite a newer result', async () => {
211
+ let resolveSlow: (value: unknown) => void = () => {};
212
+ executeQuery.mockReturnValueOnce(
213
+ new Promise((resolve) => {
214
+ resolveSlow = resolve;
215
+ })
216
+ );
217
+
218
+ const { result, rerender } = renderHook(
219
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
220
+ { initialProps: { query: 'EVALUATE ROW()' } }
221
+ );
222
+
223
+ executeQuery.mockResolvedValueOnce(wireSuccess(2));
224
+ rerender({ query: 'EVALUATE ROW(2)' });
225
+ await waitFor(() =>
226
+ expect(result.current.data?.status === 'success').toBe(true)
227
+ );
228
+
229
+ // The first query lands last and must not publish. A microtask is not
230
+ // enough to prove that: a stale publish needs several turns plus a React
231
+ // flush to become visible, so asserting too early passes either way.
232
+ await act(async () => {
233
+ resolveSlow(wireSuccess(999));
234
+ await new Promise((resolve) => setTimeout(resolve, 20));
235
+ });
236
+
237
+ expect(
238
+ result.current.data?.status === 'success' &&
239
+ result.current.data.table.rows
240
+ ).toEqual([[2]]);
241
+ });
242
+
243
+ it('clears a previous result when it goes idle', async () => {
244
+ executeQuery.mockResolvedValue(wireSuccess(1));
245
+
246
+ const { result, rerender } = renderHook(
247
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
248
+ { initialProps: { query: 'EVALUATE ROW()' } }
249
+ );
250
+ await waitFor(() => expect(result.current.data).toBeDefined());
251
+
252
+ // Leaving the rows in place renders data for a query that no longer
253
+ // applies.
254
+ rerender({ query: '' });
255
+
256
+ await waitFor(() => expect(result.current.data).toBeUndefined());
257
+ expect(result.current.isLoading).toBe(false);
258
+ });
259
+
260
+ it('keeps the previous result while an explicit refetch is loading', async () => {
261
+ executeQuery.mockResolvedValueOnce(wireSuccess(1));
262
+ const { result } = render();
263
+ await waitFor(() => expect(result.current.data).toBeDefined());
264
+
265
+ let resolveNext!: (value: unknown) => void;
266
+ executeQuery.mockReturnValueOnce(
267
+ new Promise((resolve) => {
268
+ resolveNext = resolve;
269
+ })
270
+ );
271
+ let pending: Promise<void>;
272
+ act(() => {
273
+ pending = result.current.refetch();
274
+ });
275
+ expect(result.current.isLoading).toBe(true);
276
+ expect(
277
+ result.current.data?.status === 'success' &&
278
+ result.current.data.table.rows
279
+ ).toEqual([[1]]);
280
+
281
+ await act(async () => {
282
+ resolveNext(wireSuccess(2));
283
+ await pending;
284
+ });
285
+ expect(result.current.isLoading).toBe(false);
286
+ expect(
287
+ result.current.data?.status === 'success' &&
288
+ result.current.data.table.rows
289
+ ).toEqual([[2]]);
290
+ });
291
+
292
+ it('does not publish an in-flight result after the query goes idle', async () => {
293
+ let resolveQuery!: (value: unknown) => void;
294
+ executeQuery.mockReturnValueOnce(
295
+ new Promise((resolve) => {
296
+ resolveQuery = resolve;
297
+ })
298
+ );
299
+ const { result, rerender } = renderHook(
300
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
301
+ { initialProps: { query: 'EVALUATE ROW()' } }
302
+ );
303
+ rerender({ query: '' });
304
+ await act(async () => {
305
+ resolveQuery(wireSuccess(9));
306
+ await new Promise((resolve) => setTimeout(resolve, 20));
307
+ });
308
+ expect(result.current.data).toBeUndefined();
309
+ expect(result.current.error).toBeUndefined();
310
+ expect(result.current.isLoading).toBe(false);
311
+ });
312
+
313
+ it('starts loading again when revisiting a previously completed query', async () => {
314
+ executeQuery.mockResolvedValueOnce(wireSuccess(1));
315
+ const { result, rerender } = renderHook(
316
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
317
+ { initialProps: { query: 'EVALUATE ROW(1)' } }
318
+ );
319
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
320
+
321
+ executeQuery.mockReturnValueOnce(new Promise(() => {}));
322
+ rerender({ query: 'EVALUATE ROW(2)' });
323
+ expect(result.current.isLoading).toBe(true);
324
+
325
+ let resolveRevisited!: (value: unknown) => void;
326
+ executeQuery.mockReturnValueOnce(
327
+ new Promise((resolve) => {
328
+ resolveRevisited = resolve;
329
+ })
330
+ );
331
+ rerender({ query: 'EVALUATE ROW(1)' });
332
+ expect(result.current.isLoading).toBe(true);
333
+ await act(async () => {
334
+ resolveRevisited(wireSuccess(3));
335
+ });
336
+ expect(result.current.isLoading).toBe(false);
337
+ expect(
338
+ result.current.data?.status === 'success' &&
339
+ result.current.data.table.rows
340
+ ).toEqual([[3]]);
341
+ });
342
+ });
@@ -0,0 +1,229 @@
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 {
9
+ ExecuteQueryInput,
10
+ FabricSemanticModelTabularResponse,
11
+ SemanticModelQueryResult,
12
+ } from '@microsoft/rayfin-connector-fabric-semanticmodel';
13
+ import { toQueryResult } from '@microsoft/rayfin-connector-fabric-semanticmodel';
14
+ import { useCallback, useEffect, useRef, useState } from 'react';
15
+
16
+ import { getRayfinClient } from '@/lib/rayfin-client';
17
+
18
+ /**
19
+ * One entry of the typed `client.connectors` proxy, narrowed to the operation
20
+ * this hook uses.
21
+ *
22
+ * The schema keys `client.connectors` by the exact connector names declared in
23
+ * `rayfin/rayfin.yml`, so it cannot be indexed by a `string` variable. This is
24
+ * the one place that widening happens, and the missing-connector branch below
25
+ * is what makes it safe.
26
+ */
27
+ type ExecuteQueryClient = {
28
+ executeQuery(
29
+ input: ExecuteQueryInput
30
+ ): Promise<FabricSemanticModelTabularResponse>;
31
+ };
32
+
33
+ interface UseSemanticModelQueryOptions {
34
+ /** Connector name from `rayfin/rayfin.yml` (e.g. `salesModel`). */
35
+ connection: string;
36
+ /** DAX query string. */
37
+ query: string;
38
+ }
39
+
40
+ interface UseSemanticModelQueryResult {
41
+ data: SemanticModelQueryResult | undefined;
42
+ isLoading: boolean;
43
+ error: Error | undefined;
44
+ refetch: () => Promise<void>;
45
+ }
46
+
47
+ interface QueryState {
48
+ connection: string;
49
+ query: string;
50
+ data: SemanticModelQueryResult | undefined;
51
+ isLoading: boolean;
52
+ error: Error | undefined;
53
+ }
54
+
55
+ /** Message for a connector this app has not registered. Names the fix, not the symptom. */
56
+ function notRegistered(connection: string): string {
57
+ return (
58
+ `No connector named "${connection}". Register it in connectorConfigs and ` +
59
+ `connectorRuntimes (packages/frontend/src/lib/connectors.ts), and check the name matches ` +
60
+ `rayfin/rayfin.yml.`
61
+ );
62
+ }
63
+
64
+ /**
65
+ * Runs one DAX query through the semantic model connector and normalizes the
66
+ * response.
67
+ *
68
+ * Throws for wiring, transport and auth failures. A query that reached Power BI
69
+ * and failed there comes back as a result whose `status` is `error` instead.
70
+ */
71
+ async function executeSemanticModelQuery(
72
+ connection: string,
73
+ query: string
74
+ ): Promise<SemanticModelQueryResult> {
75
+ // Async in this template: it resolves the deployed `rayfin.config.json` first.
76
+ const client = await getRayfinClient();
77
+ const connectors = (client as { connectors?: unknown }).connectors;
78
+
79
+ if (!connectors) {
80
+ throw new Error(
81
+ `This app's Rayfin client has no "connectors". ` +
82
+ `packages/frontend/src/lib/rayfin-client.ts ` +
83
+ `builds a plain RayfinClient; querying a semantic model needs ` +
84
+ `ConnectorsRayfinClient constructed with connectorConfigs and ` +
85
+ `connectorRuntimes from packages/frontend/src/lib/connectors.ts. ` +
86
+ `See step 1 of the ` +
87
+ `analytics skill.`
88
+ );
89
+ }
90
+
91
+ let connector: ExecuteQueryClient | undefined;
92
+ try {
93
+ connector = (connectors as Record<string, ExecuteQueryClient | undefined>)[
94
+ connection
95
+ ];
96
+ } catch (err) {
97
+ // The connectors proxy throws `UNKNOWN_CONNECTOR` for an unconfigured name
98
+ // rather than returning undefined, so the miss arrives here.
99
+ throw new Error(notRegistered(connection), { cause: err });
100
+ }
101
+
102
+ // Also checked: test doubles and any future pass-through may return undefined.
103
+ if (!connector) throw new Error(notRegistered(connection));
104
+
105
+ // Idempotent, and needed on both paths: a registered runtime normalizes
106
+ // already, but a connector missing from `connectorRuntimes` falls through to
107
+ // JSON pass-through and arrives in the wire shape.
108
+ return toQueryResult(await connector.executeQuery({ query }));
109
+ }
110
+
111
+ /**
112
+ * React hook that executes a DAX query against a Power BI semantic model
113
+ * through the `fabric-semanticmodel` connector.
114
+ *
115
+ * The connector name is declared in `rayfin/rayfin.yml` (managed by
116
+ * `rayfin connector add`). Its workspace and item are resolved server-side, so
117
+ * the app never sends them and they never reach the browser.
118
+ *
119
+ * @example
120
+ * const { data, isLoading } = useSemanticModelQuery({
121
+ * connection: 'salesModel',
122
+ * query: 'EVALUATE SUMMARIZE(Sales, Products[Name], "Total", SUM(Sales[Amount]))',
123
+ * });
124
+ *
125
+ * if (data?.status === 'success') {
126
+ * const table = data.table; // table.columns, table.rows
127
+ * }
128
+ *
129
+ * @example
130
+ * // Two disjoint error channels - check both, in either order.
131
+ * // `error`: what the connector threw (wiring, transport, auth). `data` is cleared.
132
+ * // `data.status === 'error'`: what Power BI returned, categorised by the
133
+ * // connector as 'query' | 'overflow' | 'api' | 'network'. `error` stays undefined.
134
+ * // A component that reads only one renders nothing for half its failures.
135
+ * if (error) console.error(error.message);
136
+ * else if (data?.status === 'error')
137
+ * console.error(data.error.category, data.error.message);
138
+ *
139
+ * @remarks
140
+ * An empty `connection` or `query` puts the hook idle and clears any previous
141
+ * result. So a `connection` wired to the wrong variable shows up as a component
142
+ * that never loads rather than as an error - check that first when nothing
143
+ * renders.
144
+ */
145
+ export function useSemanticModelQuery(
146
+ options: UseSemanticModelQueryOptions
147
+ ): UseSemanticModelQueryResult {
148
+ const { connection, query } = options;
149
+ const canExecute = Boolean(connection && query);
150
+ const [state, setState] = useState<QueryState>(() => ({
151
+ connection,
152
+ query,
153
+ data: undefined,
154
+ isLoading: canExecute,
155
+ error: undefined,
156
+ }));
157
+
158
+ // Input changes reset request UI during render, not from the fetch effect.
159
+ if (state.connection !== connection || state.query !== query) {
160
+ setState({
161
+ connection,
162
+ query,
163
+ data: canExecute ? state.data : undefined,
164
+ isLoading: canExecute,
165
+ error: undefined,
166
+ });
167
+ }
168
+
169
+ // Monotonic request id: only the newest run may publish, so a slow first query
170
+ // cannot land after a fast second one and overwrite fresher rows.
171
+ const latestRequest = useRef(0);
172
+
173
+ const execute = useCallback(async () => {
174
+ const requestId = ++latestRequest.current;
175
+ if (!canExecute) return;
176
+
177
+ let result: SemanticModelQueryResult | undefined;
178
+ let thrown: Error | undefined;
179
+ try {
180
+ result = await executeSemanticModelQuery(connection, query);
181
+ } catch (err) {
182
+ // As-is, not re-wrapped: a transport failure carries its status and
183
+ // service code as own properties, and a fresh Error would drop them.
184
+ thrown =
185
+ err instanceof Error ? err : new Error(String(err), { cause: err });
186
+ }
187
+
188
+ // Superseded by a newer run.
189
+ if (requestId !== latestRequest.current) return;
190
+
191
+ setState((current) => {
192
+ if (current.connection !== connection || current.query !== query) {
193
+ return current;
194
+ }
195
+ return {
196
+ connection,
197
+ query,
198
+ data: thrown ? undefined : (result ?? current.data),
199
+ isLoading: false,
200
+ error: thrown,
201
+ };
202
+ });
203
+ }, [connection, query, canExecute]);
204
+
205
+ const refetch = useCallback(async () => {
206
+ setState((current) => ({
207
+ ...current,
208
+ data: canExecute ? current.data : undefined,
209
+ isLoading: canExecute,
210
+ error: undefined,
211
+ }));
212
+ await execute();
213
+ }, [execute, canExecute]);
214
+
215
+ useEffect(() => {
216
+ void execute();
217
+ return () => {
218
+ // The connector has no AbortSignal; invalidate completions on cleanup.
219
+ latestRequest.current += 1;
220
+ };
221
+ }, [execute]);
222
+
223
+ return {
224
+ data: state.data,
225
+ isLoading: state.isLoading,
226
+ error: state.error,
227
+ refetch,
228
+ };
229
+ }
@@ -0,0 +1,94 @@
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 {
9
+ ConnectorConfig,
10
+ ConnectorsRuntime,
11
+ } from '@microsoft/rayfin-connectors';
12
+ import type { FabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
13
+
14
+ /**
15
+ * Connectors this app can talk to, keyed by the connector name declared in
16
+ * `rayfin/rayfin.yml` under `connectors[].name`.
17
+ *
18
+ * The index signature keeps every name usable without editing this file each
19
+ * time you run `rayfin connector add`. Narrow it to the names you actually use
20
+ * if you want the compiler to catch a typo in a connection alias:
21
+ *
22
+ * @example
23
+ * export type AppConnectorsSchema = {
24
+ * salesModel: FabricSemanticModel<'executeQuery'>;
25
+ * };
26
+ */
27
+ export type AppConnectorsSchema = Record<
28
+ string,
29
+ FabricSemanticModel<'executeQuery'>
30
+ >;
31
+
32
+ /**
33
+ * Routing config for each connector, keyed by the same name again.
34
+ *
35
+ * `rayfin connector add` writes a `connectorConfig` constant into
36
+ * `rayfin/connectors/<name>/schema.ts`. Re-export that constant here rather
37
+ * than hand-writing the object, so this file cannot drift from `rayfin.yml`.
38
+ *
39
+ * @example
40
+ * import { connectorConfig as salesModel } from '../../../../rayfin/connectors/salesModel/schema';
41
+ *
42
+ * export const connectorConfigs: Record<string, ConnectorConfig> = { salesModel };
43
+ */
44
+ export const connectorConfigs: Record<string, ConnectorConfig> = {};
45
+
46
+ /**
47
+ * Per-connector runtime hooks, keyed by the same name again.
48
+ *
49
+ * `fabric-semanticmodel` returns an Apache Arrow stream and chooses its
50
+ * transport from where the app is running — embedded in the Fabric portal, or
51
+ * standalone — and both of those live in the runtime. A connector left out of
52
+ * this map falls back to the plain JSON pass-through and will not decode.
53
+ * Register one runtime per semantic model; the connectors layer already keys
54
+ * instances by name.
55
+ *
56
+ * @example
57
+ * import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
58
+ *
59
+ * export const connectorRuntimes: ConnectorsRuntime = {
60
+ * salesModel: fabricSemanticModel({}),
61
+ * };
62
+ *
63
+ * @remarks
64
+ * Do not pass a `target`. The workspace and item ids come from `rayfin.yml` and
65
+ * are injected by the host, so they never ship to the browser. Deriving one from
66
+ * a `VITE_*` variable throws at module load, because a per-model URL is not
67
+ * among the variables `rayfin env` emits.
68
+ */
69
+ export const connectorRuntimes: ConnectorsRuntime = {};
70
+
71
+ /**
72
+ * Fails when a connector is configured without a matching runtime.
73
+ *
74
+ * A config with no runtime still sends the call, falls back to JSON
75
+ * pass-through, and returns an Arrow stream nothing decodes — unreadable rows,
76
+ * far from the missing line that caused them. Call this before constructing the
77
+ * client to turn that into a startup error naming the connector.
78
+ *
79
+ * A runtime with no config is fine: it can be registered ahead of the
80
+ * `connector add` that declares it.
81
+ */
82
+ export function assertConnectorRuntimesRegistered(): void {
83
+ const missing = Object.keys(connectorConfigs).filter(
84
+ (name) => !(name in connectorRuntimes)
85
+ );
86
+
87
+ if (missing.length > 0) {
88
+ throw new Error(
89
+ `Connector(s) ${missing.map((n) => `"${n}"`).join(', ')} are in connectorConfigs but have no runtime in connectorRuntimes ` +
90
+ `(packages/frontend/src/lib/connectors.ts). Without a runtime the response is not decoded and rows arrive unreadable. ` +
91
+ `Add: ${missing.map((n) => `${n}: fabricSemanticModel({})`).join(', ')}.`
92
+ );
93
+ }
94
+ }