@azure-tools/typespec-ts 0.53.3 → 0.54.0

package/src/rlc-common/static/paginateContent.ts

@@ -0,0 +1,345 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export const paginateContent = `
+import type { Client, PathUncheckedResponse } from "@azure-rest/core-client";
+import { createRestError } from "@azure-rest/core-client";
+
+/**
+ * returns an async iterator that iterates over results. It also has a \`byPage\`
+ * method that returns pages of items at once.
+ *
+ * @param pagedResult - an object that specifies how to get pages.
+ * @returns a paged async iterator that iterates over results.
+ */
+function getPagedAsyncIterator<
+  TElement,
+  TPage = TElement[],
+  TPageSettings = PageSettings,
+  TLink = string,
+>(
+  pagedResult: PagedResult<TPage, TPageSettings, TLink>,
+): PagedAsyncIterableIterator<TElement, TPage, TPageSettings> {
+  const iter = getItemAsyncIterator<TElement, TPage, TLink, TPageSettings>(pagedResult);
+  return {
+    next() {
+      return iter.next();
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+    byPage:
+      pagedResult?.byPage ??
+      (((settings?: PageSettings) => {
+        const { continuationToken } = settings ?? {};
+        return getPageAsyncIterator(pagedResult, {
+          pageLink: continuationToken as unknown as TLink | undefined,
+        });
+      }) as unknown as (settings?: TPageSettings) => AsyncIterableIterator<TPage>),
+  };
+}
+
+async function* getItemAsyncIterator<TElement, TPage, TLink, TPageSettings>(
+  pagedResult: PagedResult<TPage, TPageSettings, TLink>,
+): AsyncIterableIterator<TElement> {
+  const pages = getPageAsyncIterator(pagedResult);
+  const firstVal = await pages.next();
+  // if the result does not have an array shape, i.e. TPage = TElement, then we return it as is
+  if (!Array.isArray(firstVal.value)) {
+    // can extract elements from this page
+    const { toElements } = pagedResult;
+    if (toElements) {
+      yield* toElements(firstVal.value) as TElement[];
+      for await (const page of pages) {
+        yield* toElements(page) as TElement[];
+      }
+    } else {
+      yield firstVal.value;
+      // \`pages\` is of type \`AsyncIterableIterator<TPage>\` but TPage = TElement in this case
+      yield* pages as unknown as AsyncIterableIterator<TElement>;
+    }
+  } else {
+    yield* firstVal.value;
+    for await (const page of pages) {
+      // pages is of type \`AsyncIterableIterator<TPage>\` so \`page\` is of type \`TPage\`. In this branch,
+      // it must be the case that \`TPage = TElement[]\`
+      yield* page as unknown as TElement[];
+    }
+  }
+}
+
+async function* getPageAsyncIterator<TPage, TLink, TPageSettings>(
+  pagedResult: PagedResult<TPage, TPageSettings, TLink>,
+  options: {
+    pageLink?: TLink;
+  } = {},
+): AsyncIterableIterator<TPage> {
+  const { pageLink } = options;
+  let response = await pagedResult.getPage(pageLink ?? pagedResult.firstPageLink);
+  if (!response) {
+    return;
+  }
+  yield response.page;
+  while (response.nextPageLink) {
+    response = await pagedResult.getPage(response.nextPageLink);
+    if (!response) {
+      return;
+    }
+    yield response.page;
+  }
+}
+
+/**
+ * An interface that tracks the settings for paged iteration
+ */
+export interface PageSettings {
+  /**
+   * The token that keeps track of where to continue the iterator
+   */
+  continuationToken?: string;
+}
+
+/**
+ * An interface that allows async iterable iteration both to completion and by page.
+ */
+export interface PagedAsyncIterableIterator<
+  TElement,
+  TPage = TElement[],
+  TPageSettings = PageSettings,
+> {
+  /**
+   * The next method, part of the iteration protocol
+   */
+  next(): Promise<IteratorResult<TElement>>;
+  /**
+   * The connection to the async iterator, part of the iteration protocol
+   */
+  [Symbol.asyncIterator](): PagedAsyncIterableIterator<TElement, TPage, TPageSettings>;
+  /**
+   * Return an AsyncIterableIterator that works a page at a time
+   */
+  byPage: (settings?: TPageSettings) => AsyncIterableIterator<TPage>;
+}
+
+/**
+ * An interface that describes how to communicate with the service.
+ */
+interface PagedResult<TPage, TPageSettings = PageSettings, TLink = string> {
+  /**
+   * Link to the first page of results.
+   */
+  firstPageLink: TLink;
+  /**
+   * A method that returns a page of results.
+   */
+  getPage: (
+    pageLink: TLink,
+  ) => Promise<{ page: TPage; nextPageLink?: TLink } | undefined>;
+  /**
+   * a function to implement the \`byPage\` method on the paged async iterator.
+   */
+  byPage?: (settings?: TPageSettings) => AsyncIterableIterator<TPage>;
+
+  /**
+   * A function to extract elements from a page.
+   */
+  toElements?: (page: TPage) => unknown[];
+}
+
+/**
+ * Helper type to extract the type of an array
+ */
+export type GetArrayType<T> = T extends Array<infer TData> ? TData : never;
+
+/**
+ * The type of a custom function that defines how to get a page and a link to the next one if any.
+ */
+export type GetPage<TPage> = (
+  pageLink: string,
+) => Promise<{
+  page: TPage;
+  nextPageLink?: string;
+}>;
+
+/**
+ * Options for the paging helper
+ */
+export interface PagingOptions<TResponse> {
+  /**
+   * Custom function to extract pagination details for crating the PagedAsyncIterableIterator
+  */
+  customGetPage?: GetPage<PaginateReturn<TResponse>[]>
+}
+
+/**
+ * Helper type to infer the Type of the paged elements from the response type
+ * This type is generated based on the swagger information for x-ms-pageable
+ * specifically on the itemName property which indicates the property of the response
+ * where the page items are found. The default value is \`value\`.
+ * This type will allow us to provide strongly typed Iterator based on the response we get as second parameter
+ */
+ export type PaginateReturn<TResult> = TResult extends  {{#each itemNames}}
+ {
+ 
+  body: { {{this}}?: infer TPage } 
+  
+} {{#if @last }}{{else}} | {{/if}}
+{{/each}}
+  ? GetArrayType<TPage>
+  : Array<unknown>;
+  
+  /**
+ * Helper to paginate results from an initial response that follows the specification of Autorest \`x-ms-pageable\` extension
+ * @param client - Client to use for sending the next page requests
+ * @param initialResponse - Initial response containing the nextLink and current page of elements
+ * @param customGetPage - Optional - Function to define how to extract the page and next link to be used to paginate the results
+ * @returns - PagedAsyncIterableIterator to iterate the elements
+ */
+   export function paginate<TResponse extends PathUncheckedResponse>(
+    client: Client,
+    initialResponse: TResponse,
+    options: PagingOptions<TResponse> = {}
+  ): PagedAsyncIterableIterator<PaginateReturn<TResponse>> {
+    // Extract element type from initial response
+    type TElement = PaginateReturn<TResponse>;
+    let firstRun = true;
+    {{#if isComplexPaging}}
+    // We need to check the response for success before trying to inspect it looking for
+  // the properties to use for nextLink and itemName
+  checkPagingRequest(initialResponse);
+  const { itemName, nextLinkName } = getPaginationProperties(initialResponse);
+  {{else}}
+  const itemName = {{ quoteWrap itemNames }};
+  const nextLinkName = {{quoteWrap nextLinkNames}};
+  {{/if}}
+  const { customGetPage } = options;
+  const pagedResult: PagedResult<TElement[]> = {
+    firstPageLink: "",
+    getPage:
+      typeof customGetPage === "function"
+        ? customGetPage
+        : async (pageLink: string) => {
+            const result = firstRun
+              ? initialResponse
+              : await client.pathUnchecked(pageLink).get();
+            firstRun = false;
+            checkPagingRequest(result);
+            const nextLink = getNextLink(result.body, nextLinkName);
+            const values = getElements<TElement>(result.body, itemName);
+            return {
+              page: values,
+              nextPageLink: nextLink
+            };
+          }
+  };
+
+  return getPagedAsyncIterator(pagedResult);
+}
+
+/**
+ * Gets for the value of nextLink in the body
+ */
+function getNextLink(body: unknown, nextLinkName?: string): string | undefined {
+   if (!nextLinkName) {
+    return undefined;
+  }
+
+  const nextLink = (body as Record<string, unknown>)[nextLinkName];
+
+  if (typeof nextLink !== "string" && typeof nextLink !== "undefined") {
+    throw new Error(
+      \`Body Property \${nextLinkName} should be a string or undefined\`
+    );
+  }
+
+  return nextLink;
+}
+
+/**
+ * Gets the elements of the current request in the body.
+ */
+function getElements<T = unknown>(body: unknown, itemName: string): T[] {
+  const value = (body as Record<string, unknown>)[itemName] as T[];
+
+  // value has to be an array according to the x-ms-pageable extension.
+  // The fact that this must be an array is used above to calculate the
+  // type of elements in the page in PaginateReturn
+  if (!Array.isArray(value)) {
+    throw new Error(
+      \`Couldn't paginate response\\n Body doesn't contain an array property with name: \${itemName}\`
+    );
+  }
+
+  return value ?? [];
+}
+
+/**
+ * Checks if a request failed
+ */
+function checkPagingRequest(response: PathUncheckedResponse): void {
+  const Http2xxStatusCodes = [
+    "200",
+    "201",
+    "202",
+    "203",
+    "204",
+    "205",
+    "206",
+    "207",
+    "208",
+    "226"
+  ];
+  if (!Http2xxStatusCodes.includes(response.status)) {
+    throw createRestError(
+      \`Pagination failed with unexpected statusCode \${response.status}\`,
+      response
+    );
+  }
+}
+
+{{#if isComplexPaging}}
+/**
+ * Extracts the itemName and nextLinkName from the initial response to use them for pagination
+ */
+function getPaginationProperties(initialResponse: PathUncheckedResponse) {
+  // Build a set with the passed custom nextLinkNames
+  const nextLinkNames = new Set([{{ quoteWrap nextLinkNames }}]);
+
+  // Build a set with the passed custom set of itemNames
+  const itemNames = new Set([{{ quoteWrap itemNames }}]);
+
+  let nextLinkName: string | undefined;
+  let itemName: string | undefined;
+
+  for (const name of nextLinkNames) {
+    const nextLink = (initialResponse.body as Record<string, unknown>)[
+      name
+    ] as string;
+    if (nextLink) {
+      nextLinkName = name;
+      break;
+    }
+  }
+
+  for (const name of itemNames) {
+    const item = (initialResponse.body as Record<string, unknown>)[
+      name
+    ] as string;
+    if (item) {
+      itemName = name;
+      break;
+    }
+  }
+
+  if (!itemName) {
+    throw new Error(
+      \`Couldn't paginate response\\n Body doesn't contain an array property with name: \${[
+        ...itemNames
+      ].join(" OR ")}\`
+    );
+  }
+
+  return { itemName, nextLinkName };
+}
+{{/if}}
+`;

package/src/rlc-common/static/pollingContent.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{{#if isEsm}}.js{{/if}}";
+{{/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/static/sampleTemplate.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export const sampleTemplate = `
+{{#each importedTypes}}
+{{this}}
+{{/each}}
+import "dotenv/config";
+
+{{#each samples}}
+/**
+ * This sample demonstrates how to {{this.description}}
+ *
+ * @summary {{this.description}}
+ {{#if this.originalFileLocation}}
+ * x-ms-original-file: {{this.originalFileLocation}}
+ {{/if}}
+ */
+async function {{name}}(): Promise<void>  {
+  {{#each this.clientParamAssignments}}
+  {{this}}
+  {{/each}}
+  const client = {{this.defaultFactoryName}}({{this.clientParamNames}});
+  {{#each this.pathParamAssignments}}
+  {{this}}
+  {{/each}}
+  {{#each this.methodParamAssignments}}
+  {{this}}
+  {{/each}}
+  {{#if this.isPaging}}
+  const initialResponse = await client.path({{this.pathParamNames}}).{{method}}({{methodParamNames}});
+  const pageData = paginate(client, initialResponse);
+  const result = [];
+  for await (const item of pageData) {
+    result.push(item);
+  }
+  {{else if this.isLRO}}
+  const initialResponse ={{#unless this.useLegacyLro}} await{{/unless}} client.path({{this.pathParamNames}}).{{method}}({{methodParamNames}});
+  const poller = await getLongRunningPoller(client, initialResponse);
+  const result = await poller.pollUntilDone();
+  {{else}}
+  const result = await client.path({{this.pathParamNames}}).{{method}}({{methodParamNames}});
+  {{/if}}
+  console.log(result);
+}
+
+{{/each}}
+
+async function main(): Promise<void> {
+{{#each samples}}
+  await {{this.name}}();
+{{/each}}
+}
+
+main().catch(console.error);
+`;

package/src/rlc-common/static/serializeHelper.ts

@@ -0,0 +1,34 @@
+export const buildMultiCollectionContent = `
+export function buildMultiCollection(
+  items: string[],
+  parameterName: string
+): string {
+  return items
+    .map((item, index) => {
+      if (index === 0) {
+        return item;
+      }
+      return \`\${parameterName}=\${item}\`;
+    })
+    .join("&");
+}`;
+
+export const buildPipeCollectionContent = `
+export function buildPipeCollection(items: string[] | number[]): string {
+  return items.join("|");
+}`;
+
+export const buildSsvCollectionContent = `
+export function buildSsvCollection(items: string[] | number[]): string {
+  return items.join(" ");
+}`;
+
+export const buildTsvCollectionContent = `
+export function buildTsvCollection(items: string[] | number[]): string {
+  return items.join("\\t");
+}`;
+
+export const buildCsvCollectionContent = `
+export function buildCsvCollection(items: string[] | number[]): string {
+  return items.join(",");
+}`;

package/src/rlc-common/test/buildKarmaConfig.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 { karmaConfig } from "./template.js";
+
+export function buildKarmaConfigFile(_model: RLCModel) {
+  return {
+    path: "karma.conf.js",
+    content: hbs.compile(karmaConfig, { noEscape: true })({})
+  };
+}

package/src/rlc-common/test/buildRecordedClient.ts

@@ -0,0 +1,18 @@
+// 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({
+      isEsm: model.options?.moduleKind === "esm",
+      isCjs: model.options?.moduleKind === "cjs"
+    })
+  };
+}