@autorest/typescript 6.0.0-beta.7 → 6.0.0-rc.1

package/src/restLevelClient/paginateHelper.ts.hbs

@@ -0,0 +1,208 @@
+import {
+  getPagedAsyncIterator,
+  PagedAsyncIterableIterator,
+  PagedResult
+} from "@azure/core-paging";
+import {
+  Client,
+  createRestError,
+  PathUncheckedResponse
+} from "@azure-rest/core-client";
+
+/**
+ * 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,
+  maxPageSize?: number
+) => 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/restLevelClient/pollingHelper.ts.hbs

@@ -0,0 +1,72 @@
+import { Client, HttpResponse } from "@azure-rest/core-client";
+import {
+  LongRunningOperation,
+  LroEngine,
+  LroEngineOptions,
+  LroResponse,
+  PollerLike,
+  PollOperationState
+} from "@azure/core-lro";
+
+/**
+ * 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.
+ */
+export function getLongRunningPoller<TResult extends HttpResponse>(
+  client: Client,
+  initialResponse: TResult,
+  options: LroEngineOptions<TResult, PollOperationState<TResult>> = {}
+): PollerLike<PollOperationState<TResult>, TResult> {
+  const poller: LongRunningOperation<TResult> = {
+    requestMethod: initialResponse.request.method,
+    requestPath: initialResponse.request.url,
+    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 => {
+      // 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.
+      const response = await client
+        .pathUnchecked(path ?? initialResponse.request.url)
+        .get();
+      const lroResponse = getLroResponse(response as TResult);
+      lroResponse.rawResponse.headers["x-ms-original-url"] =
+        initialResponse.request.url;
+      return lroResponse;
+    }
+  };
+
+  return new LroEngine(poller, options);
+}
+
+/**
+ * Converts a Rest Client response to a response that the LRO engine knows about
+ * @param response - a rest client http response
+ * @returns - An LRO response that the LRO engine can work with
+ */
+function getLroResponse<TResult extends HttpResponse>(
+  response: TResult
+): LroResponse<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/restLevelClient/samples/generateSamples.ts

@@ -0,0 +1,23 @@
+export interface SampleGroup {
+    sampleFileName: string,
+    clientFactoryFuncName: string;
+    clientClassName: string,
+    clientPackageName: string,
+    samples: SampleDetails[],
+    importedTypes?: string[],
+}
+
+export interface SampleDetails {
+    sampleFunctionName: string,
+    clientParameterNames: string,
+    methodParameterNames: string,
+    clientParamAssignments: string[],
+    methodParamAssignments: string[],
+    originalFileLocation?: string,
+    operationName: string,
+    isTopLevel: boolean,
+    isPaging: boolean,
+    operationGroupName: string,
+    operationDescription: string,
+    clientClassName: string,
+}

package/src/restLevelClient/schemaHelpers.ts

@@ -8,6 +8,7 @@ import {
   ObjectSchema,
   PrimitiveSchema,
   Schema,
+  SchemaContext,
   SchemaType
 } from "@autorest/codemodel";
 import { getLanguageMetadata } from "../utils/languageHelpers";
@@ -20,15 +21,20 @@ import { NameType, normalizeName } from "../utils/nameUtils";
  */
 export function getElementType(
   schema: Schema,
+  schemaUsage: SchemaContext[],
   importedModels = new Set<string>()
 ): string {
   if (isArraySchema(schema)) {
     // Recursively find out the type for the elements in the array.
-    return `Array<${getElementType(schema.elementType, importedModels)}>`;
+    return `Array<${getElementType(
+      schema.elementType,
+      schemaUsage,
+      importedModels
+    )}>`;
   }
 
   if (isPrimitiveSchema(schema)) {
-    return `${primitiveSchemaToType(schema)}`;
+    return `${primitiveSchemaToType(schema, schemaUsage)}`;
   }
 
   if (isAnyObjectSchema(schema)) {
@@ -36,7 +42,11 @@ export function getElementType(
   }
 
   if (isObjectSchema(schema)) {
-    const { name } = getObjectInfo(schema);
+    const nameSuffix = schemaUsage.includes(SchemaContext.Output)
+      ? "Output"
+      : "";
+    const schemaInfo = getObjectInfo(schema);
+    const name = `${schemaInfo.name}${nameSuffix}`;
     importedModels.add(name);
     return `${name}`;
   }
@@ -44,6 +54,7 @@ export function getElementType(
   if (isDictionarySchema(schema)) {
     return `Record<string, ${getElementType(
       schema.elementType,
+      schemaUsage,
       importedModels
     )}>`;
   }
@@ -84,7 +95,10 @@ function isPrimitiveSchema(schema: Schema): boolean {
  * @param schema - Schema to generate a type for
  * @returns a string with the Typescript type to generate for the given schema
  */
-function primitiveSchemaToType(schema: PrimitiveSchema): string {
+export function primitiveSchemaToType(
+  schema: PrimitiveSchema,
+  schemaUse: SchemaContext[]
+): string {
   switch (schema.type) {
     case SchemaType.Any:
       return "any";
@@ -94,10 +108,12 @@ function primitiveSchemaToType(schema: PrimitiveSchema): string {
     case SchemaType.Date:
     case SchemaType.Time:
     case SchemaType.DateTime:
-      return "Date";
+      return schemaUse.includes(SchemaContext.Output)
+        ? "string"
+        : "Date | string";
     case SchemaType.Char:
       return "string";
-    case SchemaType.Binary:
+    case SchemaType.ByteArray:
     case SchemaType.Duration:
     case SchemaType.Credential:
     case SchemaType.UnixTime:
@@ -105,10 +121,12 @@ function primitiveSchemaToType(schema: PrimitiveSchema): string {
     case SchemaType.Uuid:
     case SchemaType.String:
       return "string";
+    case SchemaType.Binary:
+      return schemaUse.includes(SchemaContext.Output)
+        ? "Uint8Array"
+        : "string | Uint8Array | ReadableStream<Uint8Array> | NodeJS.ReadableStream";
     case SchemaType.Boolean:
       return "boolean";
-    case SchemaType.ByteArray:
-      return "Uint8Array";
     case SchemaType.Choice:
     case SchemaType.SealedChoice:
       return (schema as ChoiceSchema).choices
@@ -116,7 +134,11 @@ function primitiveSchemaToType(schema: PrimitiveSchema): string {
         .join(" | ");
     case SchemaType.Constant:
       const value = (schema as ConstantSchema).value.value;
-      return typeof value === "string" ? `"${value}"` : value;
+      return typeof value === "string"
+        ? (schema as ConstantSchema)?.valueType?.type === SchemaType.DateTime
+          ? `"${new Date(`${value}`).toISOString()}"`
+          : `"${value}"`
+        : value;
   }
 
   throw new Error(`Unknown primitive schema ${schema.type}`);
@@ -152,3 +174,23 @@ export function isDictionarySchema(schema: Schema): schema is DictionarySchema {
 export function isConstantSchema(schema: Schema): schema is ConstantSchema {
   return schema.type === SchemaType.Constant;
 }
+
+/**
+ * Gets additional documentation for a given schema
+ */
+export function getFormatDocs(schema: Schema) {
+  switch (schema.type) {
+    case SchemaType.ByteArray:
+      return "Value may contain base64 encoded characters";
+    case SchemaType.Binary:
+      return "Value may contain any sequence of octets";
+    case SchemaType.Credential:
+      return "Value may contain a password";
+    case SchemaType.Uuid:
+      return "Value may contain a UUID";
+    case SchemaType.Uri:
+      return "Value may contain a URL";
+    default:
+      return undefined;
+  }
+}

package/src/transforms/mapperTransforms.ts

@@ -175,6 +175,7 @@ function buildMapper(
   const serializedName =
     getDiscriminatorValue(schema) ||
     options.serializedName ||
+    (schema as ObjectSchema).discriminator && !isUberParent(schema as ObjectSchema) && getLanguageMetadata(schema.language).name ||
     // Fallback to name only for XML schemas since they need a name, otherwise don't
     (options.hasXmlMetadata && getLanguageMetadata(schema.language).name);
 
@@ -220,7 +221,7 @@ function buildMapper(
   return {
     ...{ type: mappeType },
     ...(serializedName && { serializedName }),
-    ...(!!schema.defaultValue && {
+    ...(schema.defaultValue !== undefined && {
       defaultValue: schema.defaultValue
     }),
     ...(required && { required }),
@@ -362,7 +363,10 @@ function transformObjectMapper(pipelineValue: PipelineValue) {
         uberParent,
         polymorphicDiscriminator: {
           serializedName: discriminator!.property.serializedName,
-          clientName: discriminator!.property.serializedName
+          clientName: normalizeName(
+            discriminator!.property.language.default.name,
+            NameType.Property
+          )
         }
       }),
       ...(additionalProperties && { additionalProperties })
@@ -385,7 +389,9 @@ function transformDictionaryMapper(pipelineValue: PipelineValue) {
   }
   let dictionarySchema = schema as DictionarySchema | AnyObjectSchema;
 
-  const elementSchema = isDictionarySchema(dictionarySchema) ? dictionarySchema.elementType : new AnySchema("Schema for AnyObject type");
+  const elementSchema = isDictionarySchema(dictionarySchema)
+    ? dictionarySchema.elementType
+    : new AnySchema("Schema for AnyObject type");
   const mapper = buildMapper(
     schema,
     { name: MapperType.Dictionary, value: getMapperOrRef(elementSchema) },
@@ -400,11 +406,11 @@ function transformDictionaryMapper(pipelineValue: PipelineValue) {
 }
 
 function isDictionarySchema(schema: Schema): schema is DictionarySchema {
-  return schema.type === SchemaType.Dictionary
+  return schema.type === SchemaType.Dictionary;
 }
 
 function isAnyObjectSchema(schema: Schema): schema is AnyObjectSchema {
-  return schema.type === SchemaType.AnyObject
+  return schema.type === SchemaType.AnyObject;
 }
 
 function transformArrayMapper(pipelineValue: PipelineValue) {
@@ -688,7 +694,7 @@ function processProperties(
     const propName = getLanguageMetadata(prop.language).name;
     const name = normalizeName(
       propName,
-      NameType.Property,
+      prop.language.default.isTopLevelParameter? NameType.Parameter: NameType.Property,
       true /** shouldGuard */
     );
     modelProperties[name] = getMapperOrRef(prop.schema, serializedName, {

package/src/transforms/objectTransforms.ts

@@ -6,7 +6,8 @@ import {
   ObjectSchema,
   ComplexSchema,
   Property,
-  GroupProperty
+  GroupProperty,
+  Language
 } from "@autorest/codemodel";
 import {
   ObjectDetails,
@@ -58,7 +59,7 @@ export function transformObject(
     hasAdditionalProperties: false,
     kind,
     name,
-    serializedName: metadata.serializedName,
+    serializedName: getObjectSerializedName(metadata, kind),
     description: metadata.description || undefined,
     schema,
     properties: schema.properties
@@ -69,6 +70,14 @@ export function transformObject(
   return getAdditionalObjectDetails(objectDetails, uberParents);
 }
 
+function getObjectSerializedName(metadata: Language, kind: ObjectKind) {
+  return metadata.serializedName
+    ? metadata.serializedName
+    : kind === ObjectKind.Polymorphic
+    ? metadata.name
+    : undefined;
+}
+
 export function transformProperty({
   language,
   schema,
@@ -92,12 +101,14 @@ export function transformProperty({
   return {
     name: normalizeName(
       metadata.name,
-      NameType.Property,
+      metadata.isTopLevelParameter ? NameType.Parameter : NameType.Property,
       true /** shouldGuard */
     ),
     description,
     serializedName: serializedName,
-    type: typeName,
+    type: typeName.startsWith("$DO_NOT_NORMALIZE$")
+      ? typeName.replace("$DO_NOT_NORMALIZE$", "")
+      : typeName,
     required: !!required,
     readOnly: !!readOnly,
     nullable: !!nullable,
@@ -287,12 +298,21 @@ function transformPolymorphicObject(
       ? {}
       : { [`"${discriminatorProperty}"`]: childDiscriminators };
   } else {
-    discriminatorPath = `${uberParentName}.${schema.discriminatorValue}`;
+    discriminatorPath = `${uberParentName}.${
+      schema.discriminatorValue
+        ? schema.discriminatorValue
+        : schema.language.default.name
+    }`;
     if (uberParent.discriminator) {
       const childDiscriminators = getChildrenDiscriminators(schema);
       discriminatorValues = {
         [getLanguageMetadata(uberParent.discriminator.property.language)
-          .name]: [schema.discriminatorValue!, ...childDiscriminators]
+          .name]: [
+          schema.discriminatorValue
+            ? schema.discriminatorValue
+            : schema.language.default.name,
+          ...childDiscriminators
+        ]
       };
     }
   }

package/src/transforms/operationTransforms.ts

@@ -388,7 +388,11 @@ export async function transformOperation(
     NameType.Interface,
     true /** shouldGuard */
   );
-  const typeName = `${normalizedOperationGroupName}${normalizedOperationName}`;
+
+  const typeName =
+    normalizedOperationGroupName === clientName
+      ? `${normalizedOperationName}`
+      : `${normalizedOperationGroupName}${normalizedOperationName}`;
 
   const typeDetails: TypeDetails = {
     typeName,
@@ -487,6 +491,7 @@ export async function transformOperationGroup(
   return {
     name: operationGroupClassName,
     key: operationGroup.$key,
+    originalKey: operationGroup.$key,
     operations,
     isTopLevel,
     mediaTypes

package/src/transforms/parameterTransforms.ts

@@ -28,7 +28,8 @@ import {
 import { isEqual, isNil } from "lodash";
 import {
   getTypeForSchema,
-  getSchemaTypeDocumentation
+  getSchemaTypeDocumentation,
+  getSecurityInfoFromModel
 } from "../utils/schemaHelpers";
 import { getStringForValue } from "../utils/valueHelpers";
 import { ClientOptions } from "../models/clientDetails";
@@ -104,7 +105,7 @@ export function transformParameters(
   options: ClientOptions
 ): ParameterDetails[] {
   let parameters: ParameterDetails[] = [];
-  const { addCredentials } = getAutorestOptions();
+  const { addCredentials } = getSecurityInfoFromModel(codeModel.security);
 
   const hasXmlMetadata = !!options.mediaTypes?.has(KnownMediaType.Xml);
   extractOperationParameters(codeModel).forEach(p =>
@@ -147,20 +148,36 @@ const extractOperationParameters = (codeModel: CodeModel) =>
           }
           const operationParams: OperationParameterDetails[] = (
             operation.parameters || []
-          ).map(p => ({ parameter: p, operationName }));
+          ).map(p => { 
+            if (p.required) {
+              p.language.default.isTopLevelParameter = true;
+            }
+            return {
+              parameter: p, 
+              operationName 
+            }  
+          });
 
           // Operations may have multiple requests, each with their own set of parameters.
           // This is known to be the case when an operation can consume multiple media types.
           // We need to ensure that the parameters from each request (method overload) is accounted for.
           const requestParams: OperationParameterDetails[] = [];
-          requests.forEach(request => {
-            request.parameters?.forEach(parameter => {
+          requests.map(request => {
+            request.parameters?.map(parameter => {
               requestParams.push({
                 operationName,
                 parameter,
                 targetMediaType: request.protocol.http?.knownMediaType
               });
+              if (parameter.required) {
+                if ((parameter as any)['targetProperty'] !== undefined) {
+                  (parameter as any)['targetProperty'].language.default.isTopLevelParameter = true;
+                }
+                parameter.language.default.isTopLevelParameter = true;
+              }
+              return parameter;
             });
+            return request;
           });
           return [...operations, ...requestParams, ...operationParams];
         },
@@ -236,7 +253,9 @@ export function populateOperationParameters(
     true /** shouldGuard */
   );
 
-  const sameNameParams = operationParameters.filter(p => p.name === name);
+  const sameNameParams = operationParameters.filter(
+    p => p.name === name || p.nameRef === name
+  );
   description += getSchemaTypeDocumentation(parameter.schema);
   const isRequired = getParameterRequired(parameter);
   const isNullable = !!parameter.nullable;
@@ -329,7 +348,7 @@ function getParameterPath(parameter: Parameter) {
   const name = normalizeName(
     metadata.name,
     NameType.Parameter,
-    true /** shouldGuard */
+    parameter.language.default.isTopLevelParameter ? true: false /** shouldGuard */
   );
 
   if (parameter.groupedBy) {