@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.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.
@@ -0,0 +1,224 @@
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}". Check that the name matches rayfin/rayfin.yml, ` +
59
+ `or add it with \`npx rayfin connector add\`.`
60
+ );
61
+ }
62
+
63
+ /**
64
+ * Runs one DAX query through the semantic model connector and normalizes the
65
+ * response.
66
+ *
67
+ * Throws for wiring, transport and auth failures. A query that reached Power BI
68
+ * and failed there comes back as a result whose `status` is `error` instead.
69
+ */
70
+ async function executeSemanticModelQuery(
71
+ connection: string,
72
+ query: string
73
+ ): Promise<SemanticModelQueryResult> {
74
+ // Async in this template: it resolves the deployed `rayfin.config.json` first.
75
+ const client = await getRayfinClient();
76
+ const connectors = (client as { connectors?: unknown }).connectors;
77
+
78
+ if (!connectors) {
79
+ throw new Error(
80
+ `This app's Rayfin client has no "connectors". ` +
81
+ `Run \`npm run pack:add -- connectors\` to build ` +
82
+ `ConnectorsRayfinClient. See step 1 of the analytics skill.`
83
+ );
84
+ }
85
+
86
+ let connector: ExecuteQueryClient | undefined;
87
+ try {
88
+ connector = (connectors as Record<string, ExecuteQueryClient | undefined>)[
89
+ connection
90
+ ];
91
+ } catch (err) {
92
+ // The connectors proxy throws `UNKNOWN_CONNECTOR` for an unconfigured name
93
+ // rather than returning undefined, so the miss arrives here.
94
+ throw new Error(notRegistered(connection), { cause: err });
95
+ }
96
+
97
+ // Also checked: test doubles and any future pass-through may return undefined.
98
+ if (!connector) throw new Error(notRegistered(connection));
99
+
100
+ // Idempotent, and needed on both paths: a registered runtime normalizes
101
+ // already, but a connector missing from `connectorRuntimes` falls through to
102
+ // JSON pass-through and arrives in the wire shape.
103
+ return toQueryResult(await connector.executeQuery({ query }));
104
+ }
105
+
106
+ /**
107
+ * React hook that executes a DAX query against a Power BI semantic model
108
+ * through the `fabric-semanticmodel` connector.
109
+ *
110
+ * The connector name is declared in `rayfin/rayfin.yml` (managed by
111
+ * `rayfin connector add`). Its workspace and item are resolved server-side, so
112
+ * the app never sends them and they never reach the browser.
113
+ *
114
+ * @example
115
+ * const { data, isLoading } = useSemanticModelQuery({
116
+ * connection: 'salesModel',
117
+ * query: 'EVALUATE SUMMARIZE(Sales, Products[Name], "Total", SUM(Sales[Amount]))',
118
+ * });
119
+ *
120
+ * if (data?.status === 'success') {
121
+ * const table = data.table; // table.columns, table.rows
122
+ * }
123
+ *
124
+ * @example
125
+ * // Two disjoint error channels - check both, in either order.
126
+ * // `error`: what the connector threw (wiring, transport, auth). `data` is cleared.
127
+ * // `data.status === 'error'`: what Power BI returned, categorised by the
128
+ * // connector as 'query' | 'overflow' | 'api' | 'network'. `error` stays undefined.
129
+ * // A component that reads only one renders nothing for half its failures.
130
+ * if (error) console.error(error.message);
131
+ * else if (data?.status === 'error')
132
+ * console.error(data.error.category, data.error.message);
133
+ *
134
+ * @remarks
135
+ * An empty `connection` or `query` puts the hook idle and clears any previous
136
+ * result. So a `connection` wired to the wrong variable shows up as a component
137
+ * that never loads rather than as an error - check that first when nothing
138
+ * renders.
139
+ */
140
+ export function useSemanticModelQuery(
141
+ options: UseSemanticModelQueryOptions
142
+ ): UseSemanticModelQueryResult {
143
+ const { connection, query } = options;
144
+ const canExecute = Boolean(connection && query);
145
+ const [state, setState] = useState<QueryState>(() => ({
146
+ connection,
147
+ query,
148
+ data: undefined,
149
+ isLoading: canExecute,
150
+ error: undefined,
151
+ }));
152
+
153
+ // Input changes reset request UI during render, not from the fetch effect.
154
+ if (state.connection !== connection || state.query !== query) {
155
+ setState({
156
+ connection,
157
+ query,
158
+ data: canExecute ? state.data : undefined,
159
+ isLoading: canExecute,
160
+ error: undefined,
161
+ });
162
+ }
163
+
164
+ // Monotonic request id: only the newest run may publish, so a slow first query
165
+ // cannot land after a fast second one and overwrite fresher rows.
166
+ const latestRequest = useRef(0);
167
+
168
+ const execute = useCallback(async () => {
169
+ const requestId = ++latestRequest.current;
170
+ if (!canExecute) return;
171
+
172
+ let result: SemanticModelQueryResult | undefined;
173
+ let thrown: Error | undefined;
174
+ try {
175
+ result = await executeSemanticModelQuery(connection, query);
176
+ } catch (err) {
177
+ // As-is, not re-wrapped: a transport failure carries its status and
178
+ // service code as own properties, and a fresh Error would drop them.
179
+ thrown =
180
+ err instanceof Error ? err : new Error(String(err), { cause: err });
181
+ }
182
+
183
+ // Superseded by a newer run.
184
+ if (requestId !== latestRequest.current) return;
185
+
186
+ setState((current) => {
187
+ if (current.connection !== connection || current.query !== query) {
188
+ return current;
189
+ }
190
+ return {
191
+ connection,
192
+ query,
193
+ data: thrown ? undefined : (result ?? current.data),
194
+ isLoading: false,
195
+ error: thrown,
196
+ };
197
+ });
198
+ }, [connection, query, canExecute]);
199
+
200
+ const refetch = useCallback(async () => {
201
+ setState((current) => ({
202
+ ...current,
203
+ data: canExecute ? current.data : undefined,
204
+ isLoading: canExecute,
205
+ error: undefined,
206
+ }));
207
+ await execute();
208
+ }, [execute, canExecute]);
209
+
210
+ useEffect(() => {
211
+ void execute();
212
+ return () => {
213
+ // The connector has no AbortSignal; invalidate completions on cleanup.
214
+ latestRequest.current += 1;
215
+ };
216
+ }, [execute]);
217
+
218
+ return {
219
+ data: state.data,
220
+ isLoading: state.isLoading,
221
+ error: state.error,
222
+ refetch,
223
+ };
224
+ }
@@ -0,0 +1,265 @@
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 { spawn } from 'node:child_process';
9
+ import { createRequire } from 'node:module';
10
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
11
+ import { dirname, join, resolve } from 'node:path';
12
+ import { StringDecoder } from 'node:string_decoder';
13
+
14
+ function parseJson(text) {
15
+ try {
16
+ return JSON.parse(String(text).trim());
17
+ } catch {
18
+ return null;
19
+ }
20
+ }
21
+
22
+ function samePath(left, right) {
23
+ const normalize = (value) => {
24
+ const path = resolve(String(value));
25
+ return process.platform === 'win32' ? path.toLocaleLowerCase() : path;
26
+ };
27
+ return normalize(left) === normalize(right);
28
+ }
29
+
30
+ export function rayfinErrorMessage(value) {
31
+ if (value?.status === 'error') {
32
+ return String(
33
+ value.error?.message ??
34
+ value.error ??
35
+ 'Rayfin connector invocation failed.'
36
+ );
37
+ }
38
+ return null;
39
+ }
40
+
41
+ export function resolveRayfinCliEntry({
42
+ moduleUrl = import.meta.url,
43
+ createRequireImpl = createRequire,
44
+ readFileSyncImpl = readFileSync,
45
+ } = {}) {
46
+ const require = createRequireImpl(moduleUrl);
47
+ const packagePath = require.resolve('@microsoft/rayfin-cli/package.json');
48
+ const packageJson = JSON.parse(readFileSyncImpl(packagePath, 'utf8'));
49
+ const relativeEntry =
50
+ typeof packageJson.bin === 'string'
51
+ ? packageJson.bin
52
+ : packageJson.bin?.rayfin;
53
+ if (typeof relativeEntry !== 'string' || relativeEntry.length === 0) {
54
+ throw new Error(
55
+ '@microsoft/rayfin-cli does not declare a rayfin executable.'
56
+ );
57
+ }
58
+ return join(dirname(packagePath), relativeEntry);
59
+ }
60
+
61
+ function launchError(error) {
62
+ const code = error?.code ? ` (${error.code})` : '';
63
+ return (
64
+ `Could not run the Rayfin CLI${code}. ` +
65
+ 'Install the app dependencies, then retry. ' +
66
+ `Details: ${error?.message ?? String(error)}`
67
+ );
68
+ }
69
+
70
+ export function runRayfinCli({
71
+ args,
72
+ cwd = process.cwd(),
73
+ cliEntry,
74
+ spawnImpl = spawn,
75
+ environment = process.env,
76
+ }) {
77
+ return new Promise((resolveResult) => {
78
+ let commandEntry;
79
+ try {
80
+ commandEntry = cliEntry ?? resolveRayfinCliEntry();
81
+ } catch (error) {
82
+ resolveResult({ ok: false, error: launchError(error) });
83
+ return;
84
+ }
85
+
86
+ let child;
87
+ try {
88
+ child = spawnImpl(process.execPath, [commandEntry, ...args], {
89
+ cwd,
90
+ env: environment,
91
+ windowsHide: true,
92
+ shell: false,
93
+ });
94
+ } catch (error) {
95
+ resolveResult({ ok: false, error: launchError(error) });
96
+ return;
97
+ }
98
+
99
+ let stdout = '';
100
+ let stderr = '';
101
+ let settled = false;
102
+ // Pipe chunks do not respect character boundaries, so a multi-byte
103
+ // character split across two reads decodes as U+FFFD under a per-chunk
104
+ // toString(). StringDecoder holds the partial sequence back until the rest
105
+ // arrives.
106
+ const outDecoder = new StringDecoder('utf8');
107
+ const errDecoder = new StringDecoder('utf8');
108
+ const finish = (value) => {
109
+ if (settled) return;
110
+ settled = true;
111
+ resolveResult(value);
112
+ };
113
+ child.stdout?.on('data', (chunk) => {
114
+ stdout += outDecoder.write(chunk);
115
+ });
116
+ child.stderr?.on('data', (chunk) => {
117
+ stderr += errDecoder.write(chunk);
118
+ });
119
+ child.on('error', (error) => {
120
+ finish({
121
+ ok: false,
122
+ error: launchError(error),
123
+ stdout,
124
+ stderr,
125
+ });
126
+ });
127
+ child.on('close', (code, signal) => {
128
+ stdout += outDecoder.end();
129
+ stderr += errDecoder.end();
130
+ const parsed = parseJson(stdout);
131
+ if (code === 0 && signal == null) {
132
+ finish({ ok: true, value: parsed, stdout, stderr });
133
+ return;
134
+ }
135
+ const rayfinError = parsed ? rayfinErrorMessage(parsed) : null;
136
+ const message = rayfinError || stderr.trim() || stdout.trim();
137
+ const status = signal
138
+ ? `Rayfin terminated by signal ${signal}`
139
+ : `Rayfin exited with code ${code ?? 'unknown'}`;
140
+ finish({
141
+ ok: false,
142
+ error: message ? `${status}: ${message}` : `${status}.`,
143
+ stdout,
144
+ stderr,
145
+ exitCode: code,
146
+ signal,
147
+ });
148
+ });
149
+ });
150
+ }
151
+
152
+ export async function listConfiguredConnectors(options = {}) {
153
+ const result = await runRayfinCli({
154
+ ...options,
155
+ args: ['connector', 'list', '--json'],
156
+ });
157
+ if (!result.ok) {
158
+ return result;
159
+ }
160
+ if (!Array.isArray(result.value)) {
161
+ return {
162
+ ok: false,
163
+ error:
164
+ 'Could not resolve connectors because `rayfin connector list --json` ' +
165
+ 'did not return a JSON array. Run this command from the app root.',
166
+ stdout: result.stdout,
167
+ stderr: result.stderr,
168
+ };
169
+ }
170
+ return {
171
+ ok: true,
172
+ connectors: result.value,
173
+ stdout: result.stdout,
174
+ stderr: result.stderr,
175
+ };
176
+ }
177
+
178
+ export async function invokeConnector({
179
+ connector,
180
+ query,
181
+ limit,
182
+ cwd = process.cwd(),
183
+ cliEntry,
184
+ spawnImpl = spawn,
185
+ }) {
186
+ // Rayfin rejects --file paths outside the project root. Keep both the
187
+ // request and the explicit full-result file inside the app.
188
+ const temporaryDirectory = mkdtempSync(join(cwd, '.rayfin-schema-query-'));
189
+ const payloadPath = join(temporaryDirectory, 'query.json');
190
+ const outputPath = join(temporaryDirectory, 'result.json');
191
+ const payload = {
192
+ query,
193
+ ...(limit ? { resultSetRowCountLimit: Number(limit) } : {}),
194
+ };
195
+
196
+ try {
197
+ writeFileSync(payloadPath, JSON.stringify(payload), 'utf8');
198
+ const result = await runRayfinCli({
199
+ args: [
200
+ 'connector',
201
+ 'invoke',
202
+ connector,
203
+ 'executeQuery',
204
+ '--file',
205
+ payloadPath,
206
+ '--output-file',
207
+ outputPath,
208
+ '--json',
209
+ ],
210
+ cwd,
211
+ cliEntry,
212
+ spawnImpl,
213
+ });
214
+ if (!result.ok) {
215
+ return result;
216
+ }
217
+
218
+ const envelope = result.value;
219
+ if (!envelope || envelope.status !== 'ok') {
220
+ return {
221
+ ok: false,
222
+ error:
223
+ rayfinErrorMessage(envelope) ??
224
+ 'Rayfin connector invoke returned an invalid JSON envelope.',
225
+ stdout: result.stdout,
226
+ stderr: result.stderr,
227
+ };
228
+ }
229
+ if (
230
+ typeof envelope.outputFile !== 'string' ||
231
+ !samePath(envelope.outputFile, outputPath)
232
+ ) {
233
+ return {
234
+ ok: false,
235
+ error:
236
+ 'Rayfin did not write the connector result to the requested ' +
237
+ 'output file. Refusing to trust the inline preview.',
238
+ stdout: result.stdout,
239
+ stderr: result.stderr,
240
+ };
241
+ }
242
+
243
+ const output = parseJson(readFileSync(outputPath, 'utf8'));
244
+ if (output === null) {
245
+ return {
246
+ ok: false,
247
+ error: 'Rayfin wrote a connector result that was not valid JSON.',
248
+ stdout: result.stdout,
249
+ stderr: result.stderr,
250
+ };
251
+ }
252
+
253
+ return {
254
+ ok: true,
255
+ output,
256
+ outputFile: envelope.outputFile,
257
+ outputBytes: envelope.outputBytes,
258
+ outputTruncated: envelope.outputTruncated === true,
259
+ stdout: result.stdout,
260
+ stderr: result.stderr,
261
+ };
262
+ } finally {
263
+ rmSync(temporaryDirectory, { recursive: true, force: true });
264
+ }
265
+ }