@azure-tools/typespec-ts 0.55.0-dev.1 → 0.55.0-dev.11

package/src/rlc-common/metadata/build-warp-config.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+
+export interface WarpConfigOptions {
+  /** Source-level exports, e.g. { ".": "./src/index.ts", "./models": "./src/models/index.ts" } */
+  exports?: Record<string, string>;
+}
+
+/** Default exports included in every warp config. */
+const BASE_EXPORTS: Record<string, string> = {
+  "./package.json": "./package.json",
+  ".": "./src/index.ts",
+};
+
+/** Full inline warp config template with react-native target. */
+const WarpConfigTemplateWithReactNative = `# warp.config.yml — build configuration
+
+exports:
+{{exports}}
+
+targets:
+  - name: browser
+    tsconfig: "./config/tsconfig.src.browser.json"
+
+  - name: react-native
+    tsconfig: "./config/tsconfig.src.react-native.json"
+
+  - name: esm
+    condition: import
+    tsconfig: "./config/tsconfig.src.esm.json"
+
+  - name: commonjs
+    condition: require
+    tsconfig: "./config/tsconfig.src.cjs.json"
+    moduleType: commonjs
+`;
+
+/** Warp config template without react-native target (default). */
+const WarpConfigTemplateDefault = `# warp.config.yml — build configuration
+
+exports:
+{{exports}}
+
+targets:
+  - name: browser
+    tsconfig: "./config/tsconfig.src.browser.json"
+
+  - name: esm
+    condition: import
+    tsconfig: "./config/tsconfig.src.esm.json"
+
+  - name: commonjs
+    condition: require
+    tsconfig: "./config/tsconfig.src.cjs.json"
+    moduleType: commonjs
+`;
+
+/**
+ * Builds a self-contained warp.config.yml file.
+ *
+ * Emits a full inline config with all exports and targets.
+ * Polyfill resolution (browser/react-native file substitution) is handled
+ * via package.json `imports` subpath imports (#platform/*).
+ *
+ * By default, react-native target is NOT included. Set `generateReactNativeTarget: true`
+ * in options to include it.
+ */
+export function buildWarpConfig(model: RLCModel, { exports }: WarpConfigOptions = {}) {
+  const allExports: Record<string, string> = {
+    ...BASE_EXPORTS,
+    ...exports,
+  };
+
+  const exportsContent = Object.entries(allExports)
+    .map(([key, value]) => `  ${JSON.stringify(key)}: ${JSON.stringify(value)}`)
+    .join("\n");
+
+  const template = model.options?.generateReactNativeTarget
+    ? WarpConfigTemplateWithReactNative
+    : WarpConfigTemplateDefault;
+
+  const content = template.replace("{{exports}}", exportsContent);
+
+  return { path: "warp.config.yml", content };
+}

package/src/rlc-common/metadata/package-json/azure-package-common.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { PackageCommonInfoConfig } from "./package-common.js";
+
+export interface AzurePackageInfoConfig extends PackageCommonInfoConfig {
+  hasLro: boolean;
+}
+
+/**
+ * Build the common package.json config for an Azure package.
+ */
+export function getAzureCommonPackageInfo(_config: AzurePackageInfoConfig) {
+  return {
+    keywords: ["node", "azure", "cloud", "typescript", "browser", "isomorphic"],
+    author: "Microsoft Corporation",
+    license: "MIT",
+    files: ["dist/", "!dist/**/*.d.*ts.map", "README.md", "LICENSE"],
+  };
+}

package/src/rlc-common/metadata/package-json/build-azure-monorepo-package.ts

@@ -0,0 +1,179 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { AzurePackageInfoConfig, getAzureCommonPackageInfo } from "./azure-package-common.js";
+import { getCommonPackageScripts, getPackageCommonInfo } from "./package-common.js";
+
+export interface AzureMonorepoInfoConfig extends AzurePackageInfoConfig {
+  monorepoPackageDirectory?: string;
+  clientContextPaths?: string[];
+}
+
+/**
+ * Builds the package.json for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function buildAzureMonorepoPackage(config: AzureMonorepoInfoConfig) {
+  const packageInfo = {
+    ...getAzureMonorepoPackageInfo(config),
+    ...getAzureMonorepoDependencies(config),
+    scripts: getAzureMonorepoScripts(config),
+    ...getSampleMetadata(config),
+  };
+
+  return packageInfo;
+}
+
+/**
+ * Builds the dependencies for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function getAzureMonorepoDependencies(config: AzureMonorepoInfoConfig) {
+  const { hasLro, dependencies, withTests } = config;
+
+  // revert this change after sdk repo update.
+  const runtimeDeps = {
+    ...dependencies,
+    "@azure-rest/core-client": "^2.3.1",
+    ...(hasLro && {
+      "@azure/abort-controller": "^2.1.2",
+    }),
+    "@azure/core-auth": "^1.9.0",
+    ...(hasLro && {
+      "@azure/core-lro": "^3.1.0",
+    }),
+    "@azure/core-rest-pipeline": "^1.20.0",
+    "@azure/core-util": "^1.12.0",
+    "@azure/logger": "^1.2.0",
+    tslib: "^2.8.1",
+  };
+
+  const testDeps = withTests
+    ? {
+        "@vitest/browser-playwright": "catalog:testing",
+        "@vitest/coverage-istanbul": "catalog:testing",
+        dotenv: "catalog:testing",
+        playwright: "catalog:testing",
+        typescript: "catalog:",
+        vitest: "catalog:testing",
+      }
+    : {
+        typescript: "catalog:",
+      };
+
+  return {
+    dependencies: runtimeDeps,
+    devDependencies: {
+      "@azure-tools/test-credential": "workspace:^",
+      "@azure-tools/test-recorder": "workspace:^",
+      "@azure-tools/test-utils-vitest": "workspace:^",
+      "@azure/dev-tool": "workspace:^",
+      "@azure/eslint-plugin-azure-sdk": "workspace:^",
+      "@azure/identity": "catalog:internal",
+      "@types/node": "catalog:",
+      "cross-env": "catalog:",
+      eslint: "catalog:",
+      prettier: "catalog:",
+      rimraf: "catalog:",
+      ...testDeps,
+    },
+  };
+}
+
+/**
+ * Build the common package.json config for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function getAzureMonorepoPackageInfo(config: AzureMonorepoInfoConfig): Record<string, any> {
+  const commonPackageInfo = getPackageCommonInfo(config);
+  const repositoryDirectory = config.monorepoPackageDirectory ?? "sdk/";
+
+  return {
+    ...commonPackageInfo,
+    ...getAzureCommonPackageInfo(config),
+    "sdk-type": `${config.azureArm ? "mgmt" : "client"}`,
+    repository: {
+      type: "git",
+      url: "git+https://github.com/Azure/azure-sdk-for-js",
+      directory: repositoryDirectory,
+    },
+    bugs: {
+      url: "https://github.com/Azure/azure-sdk-for-js/issues",
+    },
+    ...(config.monorepoPackageDirectory && {
+      homepage: `https://github.com/Azure/azure-sdk-for-js/tree/main/${config.monorepoPackageDirectory}/README.md`,
+    }),
+    prettier: "@azure/eslint-plugin-azure-sdk/prettier.json",
+    "//metadata": getMetadataInfo(config),
+  };
+}
+
+function getSampleMetadata({ name, version, withSamples }: AzureMonorepoInfoConfig) {
+  if (!withSamples) {
+    return {};
+  }
+
+  let apiRefUrlQueryParameter: string = "";
+  if (version.includes("beta")) {
+    apiRefUrlQueryParameter = "?view=azure-node-preview";
+  }
+
+  return {
+    "//sampleConfiguration": {
+      productName: name,
+      productSlugs: ["azure"],
+      disableDocsMs: true,
+      apiRefLink: `https://learn.microsoft.com/javascript/api/${name}${apiRefUrlQueryParameter}`,
+    },
+  };
+}
+
+function getAzureMonorepoScripts(config: AzureMonorepoInfoConfig) {
+  const esmScripts = getEsmScripts();
+  const skipLinting = config.azureArm;
+  const buildSampleScripts = config.azureArm
+    ? "tsc -p config/tsconfig.samples.json && dev-tool samples publish -f"
+    : "tsc -p config/tsconfig.samples.json";
+  return {
+    ...getCommonPackageScripts(),
+    "build:samples": config.withSamples ? buildSampleScripts : "echo skipped",
+    "check-format": `prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.{ts,cts,mts}" "test/**/*.{ts,cts,mts}" "*.{js,cjs,mjs,json}" ${
+      config.withSamples ? '"samples-dev/*.ts"' : ""
+    }`,
+    clean: "rimraf --glob dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+    "execute:samples": config.withSamples ? "dev-tool samples run samples-dev" : "echo skipped",
+    "extract-api": "rimraf review && dev-tool run extract-api",
+    format: `prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.{ts,cts,mts}" "test/**/*.{ts,cts,mts}" "*.{js,cjs,mjs,json}" ${
+      config.withSamples ? '"samples-dev/*.ts"' : ""
+    }`,
+    "generate:client": "echo skipped",
+    "test:browser": "dev-tool run test:vitest --browser",
+    "lint:fix": skipLinting
+      ? "echo skipped"
+      : "eslint package.json src test --fix --fix-type [problem,suggestion]",
+    lint: skipLinting ? "echo skipped" : "eslint package.json src test",
+    pack: `pnpm pack 2>&1`,
+    ...esmScripts,
+    "update-snippets": "dev-tool run update-snippets",
+  };
+}
+
+function getEsmScripts() {
+  return {
+    build: "npm run clean && dev-tool run build-package && dev-tool run extract-api",
+    "test:node": "dev-tool run test:vitest",
+    test: "tsc -b --noEmit && npm run test:node && npm run test:browser",
+  };
+}
+
+function getMetadataInfo(config: AzureMonorepoInfoConfig) {
+  const metadata: Record<string, any> = {
+    constantPaths: [],
+  };
+  const paths = config.clientContextPaths;
+  for (const path of paths ?? []) {
+    metadata["constantPaths"].push({
+      path: path,
+      prefix: "userAgentInfo",
+    });
+  }
+
+  return metadata;
+}

package/src/rlc-common/metadata/package-json/package-common.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export interface PackageCommonInfoConfig {
+  name: string;
+  nameWithoutScope?: string;
+  version: string;
+  description: string;
+  withTests: boolean;
+  withSamples: boolean;
+  exports?: Record<string, any>;
+  dependencies?: Record<string, string>;
+  azureArm?: boolean;
+  /**
+   * When true, generates React Native build targets (dist/react-native, exports condition).
+   * Defaults to false.
+   */
+  generateReactNativeTarget?: boolean;
+}
+
+/**
+ * Common package.json config for a package.
+ */
+export function getPackageCommonInfo(config: PackageCommonInfoConfig) {
+  const { name, version, description } = config;
+
+  return {
+    name,
+    version,
+    description,
+    engines: {
+      node: ">=22.0.0",
+    },
+    sideEffects: false,
+    autoPublish: false,
+    ...getEntryPointInformation(config),
+  };
+}
+
+function getEntryPointInformation(config: PackageCommonInfoConfig) {
+  // Azure monorepo packages use warp.
+  const result: Record<string, any> = {
+    type: "module",
+    main: "./dist/commonjs/index.js",
+    module: "./dist/esm/index.js",
+    types: "./dist/commonjs/index.d.ts",
+    browser: "./dist/browser/index.js",
+    imports: {
+      "#platform/*": {
+        browser: "./src/*-browser.mts",
+        default: "./src/*.ts",
+      } as Record<string, string>,
+    },
+    exports: resolveWarpExports(config.exports, config.generateReactNativeTarget),
+  };
+
+  if (config.generateReactNativeTarget) {
+    result["react-native"] = "./dist/react-native/index.js";
+    (result["imports"]["#platform/*"] as Record<string, string>)["react-native"] =
+      "./src/*-react-native.mts";
+    // Reorder so react-native comes before default
+    const importsEntry = result["imports"]["#platform/*"] as Record<string, string>;
+    result["imports"]["#platform/*"] = {
+      browser: importsEntry["browser"],
+      "react-native": importsEntry["react-native"],
+      default: importsEntry["default"],
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Resolve source-level exports to dist-level exports for warp.
+ * Converts { ".": "./src/index.ts" } to the nested condition map with
+ * browser/import/require conditions pointing to dist/ paths.
+ */
+export function resolveWarpExports(
+  sourceExports?: Record<string, any>,
+  includeReactNative?: boolean,
+): Record<string, any> {
+  const exports: Record<string, any> = {};
+  const allExports: Record<string, string> = {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    ...sourceExports,
+  };
+
+  for (const [subpath, sourcePath] of Object.entries(allExports)) {
+    // Pass-through entries (e.g. "./package.json": "./package.json")
+    if (!/\.ts$/.test(sourcePath)) {
+      exports[subpath] = sourcePath;
+      continue;
+    }
+
+    // Convert source path to dist path: "./src/foo/index.ts" -> "foo/index"
+    const relPath = sourcePath.replace(/^\.\/src\//, "").replace(/\.ts$/, "");
+
+    const exportEntry: Record<string, any> = {
+      browser: {
+        types: `./dist/browser/${relPath}.d.ts`,
+        default: `./dist/browser/${relPath}.js`,
+      },
+    };
+
+    if (includeReactNative) {
+      exportEntry["react-native"] = {
+        types: `./dist/react-native/${relPath}.d.ts`,
+        default: `./dist/react-native/${relPath}.js`,
+      };
+    }
+
+    exportEntry["import"] = {
+      types: `./dist/esm/${relPath}.d.ts`,
+      default: `./dist/esm/${relPath}.js`,
+    };
+
+    exportEntry["require"] = {
+      types: `./dist/commonjs/${relPath}.d.ts`,
+      default: `./dist/commonjs/${relPath}.js`,
+    };
+
+    exports[subpath] = exportEntry;
+  }
+
+  return exports;
+}
+
+export function getCommonPackageScripts() {
+  return {
+    clean: "rimraf --glob dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+    "extract-api": "rimraf review && mkdirp ./review && api-extractor run --local",
+    pack: "npm pack 2>&1",
+    lint: "eslint package.json api-extractor.json src",
+    "lint:fix": "eslint package.json api-extractor.json src --fix --fix-type [problem,suggestion]",
+  };
+}

package/src/rlc-common/static/polling-content.ts

@@ -0,0 +1,225 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export const pollingContent = `
+import type { Client, HttpResponse } from "@azure-rest/core-client";
+import type { AbortSignalLike } from "@azure/abort-controller";
+import type {
+  CancelOnProgress,
+  CreateHttpPollerOptions,
+  RunningOperation,
+  OperationResponse,
+  OperationState,
+} from "@azure/core-lro";
+ import { createHttpPoller } from "@azure/core-lro";
+{{#if clientOverload}}
+import type {
+  {{#each importedResponses}}
+  {{this}},
+  {{/each}}
+} from "./responses.js";
+{{/if}}
+
+/**
+ * A simple poller that can be used to poll a long running operation.
+ */
+export interface SimplePollerLike<
+  TState extends OperationState<TResult>,
+  TResult
+> {
+  /**
+   * Returns true if the poller has finished polling.
+   */
+  isDone(): boolean;
+  /**
+   * Returns the state of the operation.
+   */
+  getOperationState(): TState;
+  /**
+   * Returns the result value of the operation,
+   * regardless of the state of the poller.
+   * It can return undefined or an incomplete form of the final TResult value
+   * depending on the implementation.
+   */
+  getResult(): TResult | undefined;
+  /**
+   * Returns a promise that will resolve once a single polling request finishes.
+   * It does this by calling the update method of the Poller's operation.
+   */
+  poll(options?: { abortSignal?: AbortSignalLike }): Promise<TState>;
+  /**
+   * Returns a promise that will resolve once the underlying operation is completed.
+   */
+  pollUntilDone(pollOptions?: {
+    abortSignal?: AbortSignalLike;
+  }): Promise<TResult>;
+  /**
+   * Invokes the provided callback after each polling is completed,
+   * sending the current state of the poller's operation.
+   *
+   * It returns a method that can be used to stop receiving updates on the given callback function.
+   */
+  onProgress(callback: (state: TState) => void): CancelOnProgress;
+
+  /**
+   * Returns a promise that could be used for serialized version of the poller's operation
+   * by invoking the operation's serialize method.
+   */
+  serialize(): Promise<string>;
+
+  /**
+   * Wait the poller to be submitted.
+   */
+  submitted(): Promise<void>;
+
+  /**
+   * Returns a string representation of the poller's operation. Similar to serialize but returns a string.
+   * @deprecated Use serialize() instead.
+   */
+  toString(): string;
+
+  /**
+   * Stops the poller from continuing to poll. Please note this will only stop the client-side polling
+   * @deprecated Use abortSignal to stop polling instead.
+   */
+  stopPolling(): void;
+
+  /**
+   * Returns true if the poller is stopped.
+   * @deprecated Use abortSignal status to track this instead.
+   */
+  isStopped(): boolean;
+}
+
+/**
+ * Helper function that builds a Poller object to help polling a long running operation.
+ * @param client - Client to use for sending the request to get additional pages.
+ * @param initialResponse - The initial response.
+ * @param options - Options to set a resume state or custom polling interval.
+ * @returns - A poller object to poll for operation state updates and eventually get the final response.
+ */
+{{#if clientOverload}}
+{{#each overloadMap}}
+export async function getLongRunningPoller<
+  TResult extends {{ this.finalResponses }}
+>(
+  client: Client,
+  initialResponse: {{ this.initialResponses }},
+  options?: CreateHttpPollerOptions<TResult, OperationState<TResult>>
+): Promise<SimplePollerLike<OperationState<TResult>, TResult>>;
+{{/each}}
+{{/if}}
+export async function getLongRunningPoller<TResult extends HttpResponse>(
+    client: Client,
+    initialResponse: TResult,
+    options: CreateHttpPollerOptions<TResult, OperationState<TResult>> = {}
+    ): Promise<SimplePollerLike<OperationState<TResult>, TResult>> { 
+  const abortController = new AbortController();
+  const poller: RunningOperation<TResult> = {
+    sendInitialRequest: async () => {
+      // In the case of Rest Clients we are building the LRO poller object from a response that's the reason
+      // we are not triggering the initial request here, just extracting the information from the
+      // response we were provided.
+      return getLroResponse(initialResponse);
+    },
+    sendPollRequest: async (
+      path: string,
+      pollOptions?: { abortSignal?: AbortSignalLike }
+    ) => {
+      // This is the callback that is going to be called to poll the service
+      // to get the latest status. We use the client provided and the polling path
+      // which is an opaque URL provided by caller, the service sends this in one of the following headers: operation-location, azure-asyncoperation or location
+      // depending on the lro pattern that the service implements. If non is provided we default to the initial path.
+      function abortListener(): void {
+        abortController.abort();
+      }
+      const inputAbortSignal = pollOptions?.abortSignal;
+      const abortSignal = abortController.signal;
+      if (inputAbortSignal?.aborted) {
+        abortController.abort();
+      } else if (!abortSignal.aborted) {
+        inputAbortSignal?.addEventListener("abort", abortListener, {
+          once: true
+        });
+      }
+      let response;
+      try {
+        response = await client
+          .pathUnchecked(path ?? initialResponse.request.url)
+          .get({ abortSignal });
+      } finally {
+        inputAbortSignal?.removeEventListener("abort", abortListener);
+      }
+      const lroResponse = getLroResponse(response as TResult);
+      lroResponse.rawResponse.headers["x-ms-original-url"] =
+        initialResponse.request.url;
+      return lroResponse;
+    }
+  };
+
+  options.resolveOnUnsuccessful = options.resolveOnUnsuccessful ?? true;
+  const httpPoller = createHttpPoller(poller, options);
+  const simplePoller: SimplePollerLike<OperationState<TResult>, TResult> = {
+    isDone() {
+      return httpPoller.isDone;
+    },
+    isStopped() {
+      return abortController.signal.aborted;
+    },
+    getOperationState() {
+      if (!httpPoller.operationState) {
+        throw new Error(
+          "Operation state is not available. The poller may not have been started and you could await submitted() before calling getOperationState()."
+        );
+      }
+      return httpPoller.operationState;
+    },
+    getResult() {
+      return httpPoller.result;
+    },
+    toString() {
+      if (!httpPoller.operationState) {
+        throw new Error(
+          "Operation state is not available. The poller may not have been started and you could await submitted() before calling getOperationState()."
+        );
+      }
+      return JSON.stringify({
+        state: httpPoller.operationState
+      });
+    },
+    stopPolling() {
+      abortController.abort();
+    },
+    onProgress: httpPoller.onProgress,
+    poll: httpPoller.poll,
+    pollUntilDone: httpPoller.pollUntilDone,
+    serialize: httpPoller.serialize,
+    submitted: httpPoller.submitted
+  };
+  return simplePoller;
+}
+
+/**
+ * Converts a Rest Client response to a response that the LRO implementation understands
+ * @param response - a rest client http response
+ * @returns - An LRO response that the LRO implementation understands
+ */
+function getLroResponse<TResult extends HttpResponse>(
+  response: TResult
+): OperationResponse<TResult>  {
+  if (Number.isNaN(response.status)) {
+    throw new TypeError(
+      \`Status code of the response is not a number. Value: \${response.status}\`
+    );
+  }
+
+  return {
+    flatResponse: response,
+    rawResponse: {
+      ...response,
+      statusCode: Number.parseInt(response.status),
+      body: response.body
+    }
+  };
+}
+`;

package/src/rlc-common/test/build-recorded-client.ts

@@ -0,0 +1,15 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { recordedClientContent } from "./template.js";
+
+export function buildRecordedClientFile(_model: RLCModel) {
+  const recordedClientFileContents = hbs.compile(recordedClientContent, {
+    noEscape: true,
+  });
+  return {
+    path: "test/public/utils/recordedClient.ts",
+    content: recordedClientFileContents({}),
+  };
+}

package/src/rlc-common/test/build-sample-test.ts

@@ -0,0 +1,12 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { sampleTestContent } from "./template.js";
+
+export function buildSampleTest(_model: RLCModel) {
+  return {
+    path: "test/public/sampleTest.spec.ts",
+    content: hbs.compile(sampleTestContent, { noEscape: true })({}),
+  };
+}