@microsoft/fabric-app-data-embed-client

postMessage-based client for apps embedded in Microsoft Fabric

Quick Reference

Package: @microsoft/fabric-app-data-embed-client Purpose: Low-level postMessage transport client for apps running inside a Fabric iframe. Use when: You need direct access to the Fabric host message channel from inside an iframe. Most apps should use @microsoft/fabric-app-data-proxy (higher-level) instead. Do NOT use when: You are running in Node.js (use @microsoft/fabric-app-data-cli-proxy), or you want the full SDK experience (use @microsoft/fabric-app-data with a proxy). Key exports: SemanticModelMessageClient, isRunningInFabric, FabricError, FabricItem, DaxQueryOptions, DaxResponse, DaxJsonResponse Peer dependencies: None Install: npm install @microsoft/fabric-app-data-embed-client

Ecosystem Context

@microsoft/fabric-app-data-embed-client is the low-level transport client for Fabric embedded scenarios.

• @microsoft/fabric-app-data-proxy uses this package internally to send structured postMessage requests from code running inside a Fabric iframe to the host.
• @microsoft/fabric-app-data is the higher-level SDK that consumes those proxies and exposes the broader app-data programming model.

Installation

npm install @microsoft/fabric-app-data-embed-client

Public API

Export Summary

| Export | Kind | | --- | --- | | SemanticModelMessageClient | class | | isRunningInFabric | function | | FabricError | error class | | FabricErrorOptions | type | | FabricItem | type | | DaxQueryOptions | type | | DaxResponse | type | | DaxJsonResponse | type |

SemanticModelMessageClient

Client for semantic-model operations over the "fabric-app-data-semantic-model" message channel.

class SemanticModelMessageClient {
    constructor();

    executeDax(
        item: FabricItem,
        query: string,
        options?: DaxQueryOptions,
    ): Promise<DaxResponse>;

    executeDaxJson(
        item: FabricItem,
        query: string,
    ): Promise<DaxJsonResponse>;
}

executeDax() sends semanticModel.executeDax and returns Arrow IPC bytes in data: ArrayBuffer.

executeDaxJson() sends semanticModel.executeDaxJson and returns host-provided JSON-shaped data in data: unknown.

isRunningInFabric

function isRunningInFabric(): boolean;

Returns true when window exists and the app is running inside an iframe. If reading window.parent throws because of cross-origin access, it also returns true.

FabricError

Structured error used for transport failures, host failures, environment checks, and invalid response payloads.

class FabricError extends Error {
    readonly code: string;
    readonly requestId?: string;
    readonly responseRequestId?: string;
    readonly statusCode?: number;
    readonly body?: string;

    constructor(
        code: string,
        message: string,
        options?: FabricErrorOptions,
    );
}

Observed error codes from this package:

| Code | Meaning | | --- | --- | | DISPOSED | Transport was disposed before the request completed. | | NOT_IN_FABRIC | The code is not running inside a Fabric iframe. | | POST_MESSAGE_TIMEOUT | No matching response arrived before the transport timeout. | | POST_MESSAGE_FAILED | window.parent.postMessage(...) threw before the request was sent. | | UNKNOWN | The host returned an error without a recognized code. | | RATE_LIMITED | Reserved for host errors surfaced through the protocol. | | INVALID_RESPONSE | The host returned a payload that does not match the expected response shape. |

FabricErrorOptions

interface FabricErrorOptions {
    requestId?: string;
    responseRequestId?: string;
    statusCode?: number;
    body?: string;
}

FabricItem

interface FabricItem {
    itemId: string;
    workspaceId: string;
}

DaxQueryOptions

interface DaxQueryOptions {
    culture?: string;
    schemaOnly?: boolean;
    queryTimeout?: number;
    resultSetRowCountLimit?: number;
}

These options are forwarded in the semanticModel.executeDax payload:

| Property | Type | Description | | --- | --- | --- | | culture | string | Optional culture value for query execution. | | schemaOnly | boolean | Optional flag to request schema-only results. | | queryTimeout | number | Optional query timeout passed to the host payload. | | resultSetRowCountLimit | number | Optional row-count limit passed to the host payload. |

DaxResponse

interface DaxResponse {
    data: ArrayBuffer;
    requestId: string;
}

DaxJsonResponse

interface DaxJsonResponse {
    data: unknown;
    requestId: string;
}

Key Constraints & Gotchas

Must be running inside a Fabric iframe

// ✅ DO: Check before creating the client
import { isRunningInFabric, SemanticModelMessageClient } from "@microsoft/fabric-app-data-embed-client";

if (!isRunningInFabric()) {
    throw new Error("Not in Fabric");
}
const client = new SemanticModelMessageClient();

// ❌ DON'T: Create the client outside an iframe — calls will throw FabricError with code NOT_IN_FABRIC

Client-side timeout is 120 seconds

• The transport enforces a 120,000ms timeout per request (separate from DaxQueryOptions.queryTimeout).
• Timeout failures throw FabricError with code POST_MESSAGE_TIMEOUT.

Response validation is strict

• executeDax() expects { data: ArrayBuffer; requestId: string }.
• executeDaxJson() expects { data: unknown; requestId: string }.
• Invalid payloads throw FabricError with code INVALID_RESPONSE.

All errors are FabricError instances

• Error codes: DISPOSED, NOT_IN_FABRIC, POST_MESSAGE_TIMEOUT, POST_MESSAGE_FAILED, UNKNOWN, RATE_LIMITED, INVALID_RESPONSE.

Minimal Usage Examples

import {
    SemanticModelMessageClient,
    isRunningInFabric,
} from "@microsoft/fabric-app-data-embed-client";

if (!isRunningInFabric()) {
    throw new Error("This app must run inside a Fabric iframe.");
}

const client = new SemanticModelMessageClient();

import type { FabricItem } from "@microsoft/fabric-app-data-embed-client";

const item: FabricItem = {
    itemId: "semantic-model-id",
    workspaceId: "workspace-id",
};

const result = await client.executeDax(item, "EVALUATE ROW(\"x\", 1)");
console.log(result.requestId);
console.log(result.data);

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See full Microsoft Open Source Code of Conduct