@microsoft/rayfin-connector-fabric-semanticmodel 1.34.0 → 1.35.0-alpha.1276

package/dist/arrow.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Apache Arrow IPC decoding for the `fabric-semanticmodel` connector.
+ *
+ * The semantic-model worker returns DAX query results as a binary Apache
+ * Arrow stream (`Content-Type: application/vnd.apache.arrow.stream`). This
+ * module decodes that stream into the connector's existing JSON wire shape
+ * ({@link FabricSemanticModelTabularResponse}) so callers and
+ * {@link toQueryResult} keep working unchanged.
+ *
+ * The value-coercion logic (Int64 overflow guards, decimal scaling,
+ * timezone-unaware DateTime formatting, dictionary unwrapping, LZ4 frame
+ * decompression) mirrors the `@microsoft/fabric-app-data` reference decoder so
+ * values match the legacy JSON path exactly.
+ */
+import type { FabricSemanticModelTabularResponse } from './types.js';
+/**
+ * Thrown when an Arrow value cannot be represented as a JavaScript `number`
+ * without losing precision (Int64 or scaled Decimal out of safe-integer
+ * range). Surfaced to callers as an `'overflow'`-category query result.
+ */
+export declare class ArrowOverflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decode an Apache Arrow IPC stream into a
+ * {@link FabricSemanticModelTabularResponse}.
+ *
+ * Success rows are objects keyed by the fully-qualified column name
+ * (e.g. `"Sales[Region]"`), matching the JSON wire shape so existing callers
+ * and {@link toQueryResult} are unaffected. DAX error tables map to
+ * `output.queryError` (categorised `'query'`), and value-overflow conditions
+ * map to a per-table error (categorised `'overflow'`).
+ *
+ * @param bytes - The raw Arrow IPC stream bytes.
+ * @param requestId - The Power BI request id, when known. Defaults to `''`.
+ * @returns The decoded tabular response envelope.
+ */
+export declare function parseArrowStream(bytes: ArrayBuffer | Uint8Array, requestId?: string): FabricSemanticModelTabularResponse;
+//# sourceMappingURL=arrow.d.ts.map

package/dist/arrow.js

@@ -0,0 +1,252 @@
+/**
+ * Apache Arrow IPC decoding for the `fabric-semanticmodel` connector.
+ *
+ * The semantic-model worker returns DAX query results as a binary Apache
+ * Arrow stream (`Content-Type: application/vnd.apache.arrow.stream`). This
+ * module decodes that stream into the connector's existing JSON wire shape
+ * ({@link FabricSemanticModelTabularResponse}) so callers and
+ * {@link toQueryResult} keep working unchanged.
+ *
+ * The value-coercion logic (Int64 overflow guards, decimal scaling,
+ * timezone-unaware DateTime formatting, dictionary unwrapping, LZ4 frame
+ * decompression) mirrors the `@microsoft/fabric-app-data` reference decoder so
+ * values match the legacy JSON path exactly.
+ */
+import { tableFromIPC, compressionRegistry, CompressionType, Type, } from 'apache-arrow';
+import { compress, decompress } from 'lz4js';
+// Power BI Arrow frames may be LZ4-compressed. apache-arrow ships the registry
+// but not the codec, so register it once on module load.
+compressionRegistry.set(CompressionType.LZ4_FRAME, {
+    decode: (data) => decompress(data),
+    encode: (data) => compress(data),
+});
+/**
+ * Columns whose combined presence marks an Arrow table as a DAX error table.
+ * Power BI surfaces query errors in-band (HTTP 200) as a single-row table
+ * with these columns rather than as a transport error.
+ */
+const REQUIRED_ERROR_COLUMNS = [
+    'ErrorCode',
+    'ErrorMessage',
+    'ErrorDescription',
+];
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = BigInt(-Number.MAX_SAFE_INTEGER);
+/**
+ * Thrown when an Arrow value cannot be represented as a JavaScript `number`
+ * without losing precision (Int64 or scaled Decimal out of safe-integer
+ * range). Surfaced to callers as an `'overflow'`-category query result.
+ */
+export class ArrowOverflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArrowOverflowError';
+    }
+}
+/**
+ * Coerce an Arrow Int64 (`bigint`) into a `number`, throwing when the value
+ * cannot be represented without precision loss.
+ */
+function coerceBigInt(raw, columnName) {
+    if (raw === null || raw === undefined)
+        return null;
+    const v = raw;
+    if (v > MAX_SAFE || v < MIN_SAFE) {
+        throw new ArrowOverflowError(`Integer value ${v} in column "${columnName}" exceeds Number.MAX_SAFE_INTEGER and cannot be safely represented.`);
+    }
+    return Number(v);
+}
+/**
+ * Build a coercer for a fixed-scale Arrow Decimal: divide the integer mantissa
+ * by `10^scale`, guarding against non-finite and unsafe results.
+ */
+function makeDecimalCoercer(scale) {
+    const divisor = Math.pow(10, scale);
+    return function coerceDecimal(raw, columnName) {
+        if (raw === null || raw === undefined)
+            return null;
+        // apache-arrow returns Decimal cells as a `DecimalBigNum` (a Uint32Array
+        // subclass). `Number()` yields the unscaled mantissa for in-range values,
+        // but throws for magnitudes beyond Number.MAX_SAFE_INTEGER; treat that
+        // throw as an overflow so it surfaces as a per-table error instead of
+        // escaping the decode.
+        let mantissa;
+        try {
+            mantissa = Number(raw);
+        }
+        catch {
+            throw new ArrowOverflowError(`Decimal value in column "${columnName}" exceeds Number.MAX_SAFE_INTEGER and cannot be safely represented.`);
+        }
+        const num = mantissa / divisor;
+        if (!Number.isFinite(num)) {
+            throw new ArrowOverflowError(`Decimal value in column "${columnName}" overflows to ${num} and cannot be represented as a finite Number.`);
+        }
+        if (Math.abs(num) > Number.MAX_SAFE_INTEGER) {
+            throw new ArrowOverflowError(`Decimal value ${num} in column "${columnName}" exceeds Number.MAX_SAFE_INTEGER and cannot be safely represented.`);
+        }
+        return num;
+    };
+}
+/**
+ * Coerce an Arrow Date/Timestamp into an ISO string *without* a trailing `Z`,
+ * matching Analysis Services' timezone-unaware DateTime semantics.
+ */
+function coerceDateTime(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    // apache-arrow normalizes Date/Timestamp cells (all units) to epoch
+    // milliseconds; coerce a defensive `bigint` to a number so `new Date` never
+    // throws a raw `TypeError` on it.
+    const ms = typeof raw === 'bigint' ? Number(raw) : raw;
+    return new Date(ms).toISOString().slice(0, -1);
+}
+/**
+ * Resolve the underlying data type for a field, unwrapping dictionary-encoded
+ * columns to their value type first.
+ */
+function unwrapType(field) {
+    let type = field.type;
+    if (type.typeId === Type.Dictionary) {
+        type = type.dictionary;
+    }
+    return { typeId: type.typeId, type };
+}
+/** Select a value coercer for a field, or `null` to pass the value through. */
+function buildCoercer(field) {
+    const { typeId, type } = unwrapType(field);
+    switch (typeId) {
+        case Type.Int:
+            // Only 64-bit integers arrive as `bigint` and need narrowing.
+            return type.bitWidth === 64 ? coerceBigInt : null;
+        case Type.Decimal:
+            return makeDecimalCoercer(type.scale);
+        case Type.Date:
+        case Type.Timestamp:
+            return coerceDateTime;
+        default:
+            return null;
+    }
+}
+/** Map an Arrow field to a Power-BI-style dataType string. */
+function resolveDataType(field) {
+    const { typeId, type } = unwrapType(field);
+    switch (typeId) {
+        case Type.Int:
+            return 'Int64';
+        case Type.Float:
+            return 'Double';
+        case Type.Decimal:
+            return 'Decimal';
+        case Type.Bool:
+            return 'Boolean';
+        case Type.Utf8:
+        case Type.LargeUtf8:
+            return 'String';
+        case Type.Date:
+        case Type.Timestamp:
+            return 'DateTime';
+        default:
+            return String(type);
+    }
+}
+/** A table is a DAX error table when it carries all error-marker columns. */
+function isArrowErrorTable(columnNames) {
+    const nameSet = new Set(columnNames);
+    return REQUIRED_ERROR_COLUMNS.every((col) => nameSet.has(col));
+}
+/**
+ * Decode an Apache Arrow IPC stream into a
+ * {@link FabricSemanticModelTabularResponse}.
+ *
+ * Success rows are objects keyed by the fully-qualified column name
+ * (e.g. `"Sales[Region]"`), matching the JSON wire shape so existing callers
+ * and {@link toQueryResult} are unaffected. DAX error tables map to
+ * `output.queryError` (categorised `'query'`), and value-overflow conditions
+ * map to a per-table error (categorised `'overflow'`).
+ *
+ * @param bytes - The raw Arrow IPC stream bytes.
+ * @param requestId - The Power BI request id, when known. Defaults to `''`.
+ * @returns The decoded tabular response envelope.
+ */
+export function parseArrowStream(bytes, requestId = '') {
+    const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    // An empty body carries no tables; decode it to an empty (successful)
+    // response rather than letting `tableFromIPC` throw on truncated input.
+    if (data.byteLength === 0) {
+        return {
+            status: 'Succeeded',
+            output: { tables: [], requestId },
+            errors: [],
+        };
+    }
+    const arrowTable = tableFromIPC(data);
+    const fields = arrowTable.schema.fields;
+    const columnNames = fields.map((f) => f.name);
+    // DAX errors are returned in-band as a single-row error table.
+    if (isArrowErrorTable(columnNames)) {
+        const firstRow = arrowTable.get(0);
+        const rowJson = (firstRow?.toJSON?.() ?? {});
+        const message = rowJson['ErrorMessage'] ?? 'Unknown DAX error';
+        return {
+            status: 'Succeeded',
+            output: {
+                tables: [],
+                requestId,
+                queryError: { message: String(message) },
+            },
+            errors: [],
+        };
+    }
+    const coercers = fields.map((f) => buildCoercer(f));
+    const numRows = arrowTable.numRows;
+    const rows = new Array(numRows);
+    for (let r = 0; r < numRows; r++) {
+        rows[r] = {};
+    }
+    try {
+        for (let c = 0; c < fields.length; c++) {
+            const col = arrowTable.getChildAt(c);
+            if (!col)
+                continue;
+            const coercer = coercers[c];
+            const colName = columnNames[c];
+            if (coercer) {
+                for (let r = 0; r < numRows; r++) {
+                    rows[r][colName] = coercer(col.get(r), colName);
+                }
+            }
+            else {
+                for (let r = 0; r < numRows; r++) {
+                    rows[r][colName] = col.get(r) ?? null;
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof ArrowOverflowError) {
+            // Surface as a per-table error so toQueryResult categorises it 'overflow'.
+            return {
+                status: 'Succeeded',
+                output: {
+                    tables: [{ rows: [], error: { message: err.message } }],
+                    requestId,
+                },
+                errors: [],
+            };
+        }
+        throw err;
+    }
+    const columns = fields.map((f) => ({
+        name: f.name,
+        dataType: resolveDataType(f),
+    }));
+    return {
+        status: 'Succeeded',
+        output: {
+            tables: [{ rows, columns }],
+            requestId,
+        },
+        errors: [],
+    };
+}
+//# sourceMappingURL=arrow.js.map

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export type { ExecuteQueryInput, FabricSemanticModelColumn, FabricSemanticModelE
 export type { FabricSemanticModel, FabricSemanticModelOperation, FabricSemanticModelOperationCatalog, } from './marker.js';
 export { toQueryResult } from './queryResult.js';
 export type { QueryColumn, QueryError, QueryErrorCategory, QueryTable, SemanticModelQueryResult, } from './queryResult.js';
+export { ArrowOverflowError, parseArrowStream } from './arrow.js';
+export { fabricSemanticModel } from './runtime.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1,4 @@
 export { toQueryResult } from './queryResult.js';
+export { ArrowOverflowError, parseArrowStream } from './arrow.js';
+export { fabricSemanticModel } from './runtime.js';
 //# sourceMappingURL=index.js.map

package/dist/lz4js-shim.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ambient module declaration for `lz4js`, which ships without bundled types.
+ *
+ * This is a global (non-module) script: it intentionally has no top-level
+ * `import`/`export`, so the `declare module 'lz4js'` block provides ambient
+ * typings for the otherwise-untyped package. A standalone `.d.ts` file cannot
+ * be used here because `packages/**\/*.d.ts` is git-ignored as a build
+ * artifact, so this `.ts` shim is committed instead.
+ */
+declare module 'lz4js' {
+    /** Decompress an LZ4 block/frame buffer. */
+    function decompress(data: Uint8Array): Uint8Array;
+    /** Compress a buffer using LZ4. */
+    function compress(data: Uint8Array): Uint8Array;
+}
+//# sourceMappingURL=lz4js-shim.d.ts.map

package/dist/lz4js-shim.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Ambient module declaration for `lz4js`, which ships without bundled types.
+ *
+ * This is a global (non-module) script: it intentionally has no top-level
+ * `import`/`export`, so the `declare module 'lz4js'` block provides ambient
+ * typings for the otherwise-untyped package. A standalone `.d.ts` file cannot
+ * be used here because `packages/**\/*.d.ts` is git-ignored as a build
+ * artifact, so this `.ts` shim is committed instead.
+ */
+//# sourceMappingURL=lz4js-shim.js.map

package/dist/marker.d.ts

@@ -3,7 +3,7 @@
  * category. Contributes the operation catalog that the typed
  * `client.connectors.<name>` proxy uses to type its operations.
  */
-import type { ConnectorMarker, OperationDef } from '@microsoft/rayfin-connectors';
+import type { ConnectorMarker, OperationDef, TypedConnectorClient } from '@microsoft/rayfin-connectors';
 import type { ExecuteQueryInput, FabricSemanticModelTabularResponse } from './types.js';
 /**
  * Union of all operation names this connector category supports.
@@ -28,5 +28,13 @@ export interface FabricSemanticModelOperationCatalog {
  * };
  * ```
  */
-export type FabricSemanticModel<TOps extends FabricSemanticModelOperation = FabricSemanticModelOperation> = ConnectorMarker<Pick<FabricSemanticModelOperationCatalog, TOps>>;
+export type FabricSemanticModel<TOps extends FabricSemanticModelOperation = FabricSemanticModelOperation> = ConnectorMarker<TypedConnectorClient<Pick<FabricSemanticModelOperationCatalog, TOps>>> & {
+    /**
+     * Diagnostic phantom — carries the operation catalog at the type level
+     * so tools (e.g. typedoc, IDE hovers) can surface the connector's
+     * operation surface without inferring through the resolved client type.
+     * Not used by {@link TypedConnectorsApi}, which reads `__client` only.
+     */
+    readonly __operations?: Pick<FabricSemanticModelOperationCatalog, TOps>;
+};
 //# sourceMappingURL=marker.d.ts.map

package/dist/runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Runtime companion for the `fabric-semanticmodel` connector marker.
+ *
+ * Connector markers are type-only, so the binary decode for the `executeQuery`
+ * operation is supplied here as a {@link ConnectorRuntime}. Pass the result of
+ * {@link fabricSemanticModel} to `ConnectorsRayfinClient` (or
+ * `createConnectorsApi`) under the same connector name used in the typed
+ * schema so the connectors proxy decodes the Apache Arrow response into a
+ * {@link FabricSemanticModelTabularResponse}.
+ */
+import type { ConnectorRuntime } from '@microsoft/rayfin-connectors';
+/**
+ * Build the runtime hooks for a `fabric-semanticmodel` connector instance.
+ *
+ * Registers the Apache Arrow decoder for the `executeQuery` operation. JSON
+ * responses bypass the decoder, so a worker that still returns JSON keeps
+ * working unchanged.
+ *
+ * @example
+ * ```ts
+ * import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+ * import {
+ *   fabricSemanticModel,
+ *   type FabricSemanticModel,
+ * } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+ *
+ * type AppConnectorsSchema = {
+ *   salesModel: FabricSemanticModel<'executeQuery'>;
+ * };
+ *
+ * const client = new ConnectorsRayfinClient<
+ *   DataSchema,
+ *   FunctionsSchema,
+ *   AppConnectorsSchema
+ * >(config, { salesModel: fabricSemanticModel() });
+ * ```
+ *
+ * @returns The connector runtime hooks for the semantic-model connector.
+ */
+export declare function fabricSemanticModel(): ConnectorRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.js

@@ -0,0 +1,49 @@
+/**
+ * Runtime companion for the `fabric-semanticmodel` connector marker.
+ *
+ * Connector markers are type-only, so the binary decode for the `executeQuery`
+ * operation is supplied here as a {@link ConnectorRuntime}. Pass the result of
+ * {@link fabricSemanticModel} to `ConnectorsRayfinClient` (or
+ * `createConnectorsApi`) under the same connector name used in the typed
+ * schema so the connectors proxy decodes the Apache Arrow response into a
+ * {@link FabricSemanticModelTabularResponse}.
+ */
+import { parseArrowStream } from './arrow.js';
+/**
+ * Build the runtime hooks for a `fabric-semanticmodel` connector instance.
+ *
+ * Registers the Apache Arrow decoder for the `executeQuery` operation. JSON
+ * responses bypass the decoder, so a worker that still returns JSON keeps
+ * working unchanged.
+ *
+ * @example
+ * ```ts
+ * import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+ * import {
+ *   fabricSemanticModel,
+ *   type FabricSemanticModel,
+ * } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+ *
+ * type AppConnectorsSchema = {
+ *   salesModel: FabricSemanticModel<'executeQuery'>;
+ * };
+ *
+ * const client = new ConnectorsRayfinClient<
+ *   DataSchema,
+ *   FunctionsSchema,
+ *   AppConnectorsSchema
+ * >(config, { salesModel: fabricSemanticModel() });
+ * ```
+ *
+ * @returns The connector runtime hooks for the semantic-model connector.
+ */
+export function fabricSemanticModel() {
+    return {
+        operations: {
+            executeQuery: {
+                decodeBinary: (data) => parseArrowStream(data),
+            },
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-connector-fabric-semanticmodel",
-  "version": "1.34.0",
+  "version": "1.35.0-alpha.1276",
   "description": "Typed connector marker for the Fabric semantic-model (Power BI dataset) connector category. Pair with @microsoft/rayfin-client to type `client.connectors.<name>.executeQuery(...)`.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,9 @@
     "rimraf": "~6.0.1"
   },
   "dependencies": {
-    "@microsoft/rayfin-connectors": "1.34.0"
+    "apache-arrow": "^21.1.0",
+    "lz4js": "^0.2.0",
+    "@microsoft/rayfin-connectors": "1.35.0-alpha.1276"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",