Ensure Distributed .d.ts Files Are Runtime-Scoped and Self-Contained

[deyaaeldeen]

Overview

Our TypeScript libraries target multiple runtimes, Node.js, browser, and React Native, with dedicated output folders in the distributed artifact:

• dist/esm => Node.js
• dist/commonjs => Node.js
• dist/browser => Browser
• dist/react-native => React Native

Each folder includes its own set of .d.ts files describing the public API surface for that runtime. When a user imports a library, the type definitions from the folder corresponding to the chosen runtime are added to their TypeScript typing context.

However, our current .d.ts files are not fully runtime-isolated. They sometimes reference types from other runtime environments, creating invalid type contexts.

Example

In the Node.js build, a function may legitimately reference the Buffer type:

import type { Buffer } from "node:buffer";
...
  sendData(input: Buffer): Promise<void>;
... 

This reference is valid only when @types/node is available in the project. Similarly, .d.ts files under dist/browser should depend only on the Web Platform API types, such as those included by specifying "lib": ["DOM", "DOM.Iterable", "DOM.AsyncIterable"] in tsconfig.json.

Each runtime’s .d.ts files should only reference types:

• defined within the same runtime’s dist folder, and
• provided by that runtime’s standard API

They must not reference types from other runtimes.

Problem

Our builds currently emit identical type declarations across all runtime targets.

For example, the HTTP request body type includes explicit references to Node.js-only types that are unavailable in the browser or React Native environments:

azure-sdk-for-js/sdk/core/ts-http-runtime/src/interfaces.ts

Lines 61 to 66 in 76f0890

	body:
	| ((() => ReadableStream<Uint8Array>) | (() => NodeJS.ReadableStream))
	| ReadableStream<Uint8Array>
	| NodeJS.ReadableStream
	| Uint8Array
	| Blob;

,
This results in:

• missing symbol errors when compiling against non-Node.js runtimes
• confusing or misleading type information for consumers

Goal

Ensure that each runtime’s distributed .d.ts files are:

• self-contained
• runtime-scoped
• free from cross-runtime type references

Acceptance Criteria

• .d.ts files in dist/esm reference only Node.js APIs
• .d.ts files in dist/browser reference only Web API types
• .d.ts files in dist/react-native reference only React Native types
• Type isolation verified through TypeScript precise-typechecking that makes sure the only types loaded in the typing context are the ones of the corresponding runtime environment