@azure-tools/rlc-common 1.0.0-beta.1 → 1.0.0-beta.10

package/src/buildClient.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT License.
 
 import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
   Project,
   StatementStructures,
   StructureKind,
@@ -13,7 +15,31 @@ import * as path from "path";
 import { NameType, normalizeName } from "./helpers/nameUtils.js";
 import { isConstantSchema } from "./helpers/schemaHelpers.js";
 import { buildMethodShortcutImplementation } from "./buildMethodShortcuts.js";
-import { RLCModel, Schema, File } from "./interfaces.js";
+import { RLCModel, Schema, File, PathParameter } from "./interfaces.js";
+
+function getClientOptionsInterface(
+  clientName: string,
+  optionalUrlParameters?: PathParameter[]
+): OptionalKind<InterfaceDeclarationStructure> | undefined {
+  if (!optionalUrlParameters || optionalUrlParameters.length === 0) {
+    return undefined;
+  }
+
+  const properties = optionalUrlParameters.map((param) => {
+    return {
+      name: param.name,
+      type: param.type,
+      hasQuestionToken: true
+    };
+  });
+
+  return {
+    name: `${clientName}Options`,
+    extends: ["ClientOptions"],
+    isExported: true,
+    properties
+  };
+}
 
 export function buildClient(model: RLCModel): File | undefined {
   const name = normalizeName(model.libraryName, NameType.File);
@@ -26,7 +52,29 @@ export function buildClient(model: RLCModel): File | undefined {
 
   // Get all paths
   const clientName = model.libraryName;
-  const urlParameters = model?.urlInfo?.urlParameters;
+  const clientInterfaceName = clientName.endsWith("Client")
+    ? `${clientName}`
+    : `${clientName}Client`;
+
+  normalizeUrlInfo(model);
+  const urlParameters = model?.urlInfo?.urlParameters?.filter(
+    // Do not include parameters with constant values in the signature, these should go in the options bag
+    (p) => p.value === undefined
+  );
+
+  const optionalUrlParameters = model?.urlInfo?.urlParameters?.filter(
+    // Do not include parameters with constant values in the signature, these should go in the options bag
+    (p) => Boolean(p.value)
+  );
+
+  const clientOptionsInterface = getClientOptionsInterface(
+    clientInterfaceName,
+    optionalUrlParameters
+  );
+
+  if (clientOptionsInterface) {
+    clientFile.addInterface(clientOptionsInterface);
+  }
 
   if (!model.options) {
     return undefined;
@@ -46,26 +94,39 @@ export function buildClient(model: RLCModel): File | undefined {
     ...(addCredentials === false ||
     !isSecurityInfoDefined(credentialScopes, credentialKeyHeaderName)
       ? []
-      : [{ name: "credentials", type: credentialTypes.join(" | ") }])
+      : [
+          {
+            name: "credentials",
+            type: credentialTypes.join(" | "),
+            description: `uniquely identify client credential`
+          }
+        ])
   ];
-  const clientInterfaceName = clientName.endsWith("Client")
-    ? `${clientName}`
-    : `${clientName}Client`;
 
+  const allClientParams = [
+    ...commonClientParams,
+    {
+      name: "options",
+      type: `${clientOptionsInterface?.name ?? "ClientOptions"} = {}`,
+      description: "the parameter for all optional parameters"
+    }
+  ];
   const functionStatement = {
     isExported: true,
     name: `createClient`,
-    parameters: [
-      ...commonClientParams,
-      { name: "options", type: "ClientOptions = {}" }
-    ],
+    parameters: allClientParams,
     docs: [
       {
         description:
-          `Initialize a new instance of the class ${clientInterfaceName} class. \n` +
-          commonClientParams
+          `Initialize a new instance of \`${clientInterfaceName}\` \n` +
+          allClientParams
             .map((param) => {
-              return `@param ${param.name} type: ${param.type} ${param.description ?? ""}`;
+              return `@param ${param.name} type: ${param.type
+                .split("=")[0]
+                .split(" ")
+                .join("")}, ${
+                param.description ?? "The parameter " + param.name
+              }`;
             })
             .join("\n")
       }
@@ -127,6 +188,19 @@ function getClientFactoryBody(
   let clientPackageName = packageDetails.nameWithoutScope ?? "";
   const packageVersion = packageDetails.version;
   const { endpoint, urlParameters } = model.urlInfo;
+
+  const optionalUrlParameters: string[] = [];
+
+  for (const param of urlParameters ?? []) {
+    if (param.value) {
+      const value =
+        typeof param.value === "string" ? `"${param.value}"` : param.value;
+      optionalUrlParameters.push(
+        `const ${param.name} = options.${param.name} ?? ${value}`
+      );
+    }
+  }
+
   let baseUrl: string;
   if (urlParameters && endpoint) {
     let parsedEndpoint = endpoint;
@@ -142,7 +216,7 @@ function getClientFactoryBody(
     baseUrl = `options.baseUrl ?? "${endpoint}"`;
   }
 
-  const apiVersion = getApiVersion(model);
+  const apiVersion = getApiVersionInQueryParam(model);
   let apiVersionStatement: string = "";
   if (apiVersion) {
     apiVersionStatement = `options.apiVersion = options.apiVersion ?? "${apiVersion}"`;
@@ -224,6 +298,7 @@ function getClientFactoryBody(
   }
 
   return [
+    ...optionalUrlParameters,
     baseUrlStatement,
     apiVersionStatement,
     credentials,
@@ -235,17 +310,44 @@ function getClientFactoryBody(
   ];
 }
 
-function getApiVersion(model: RLCModel): string | undefined {
-  if (!model.apiVersionParam) {
+function getApiVersionInQueryParam(model: RLCModel): string | undefined {
+  if (!model.apiVersionInQueryParam) {
     return undefined;
   }
 
   if (
-    model.apiVersionParam &&
-    isConstantSchema(model.apiVersionParam as Schema)
+    model.apiVersionInQueryParam &&
+    isConstantSchema(model.apiVersionInQueryParam as Schema)
   ) {
-    return model.apiVersionParam.default;
+    return model.apiVersionInQueryParam.default;
   }
 
   return undefined;
 }
+
+function normalizeUrlInfo(model: RLCModel) {
+  if (
+    !model ||
+    !model.urlInfo ||
+    !model.urlInfo.endpoint ||
+    !model.urlInfo.urlParameters ||
+    model.urlInfo.urlParameters.length === 0
+  ) {
+    return;
+  }
+
+  let parsedEndpoint = model.urlInfo.endpoint;
+  const urlParameters = model.urlInfo.urlParameters;
+  urlParameters.forEach((urlParameter) => {
+    const name = urlParameter.name;
+    const normalizedName = normalizeName(name, NameType.Parameter);
+    if (name !== normalizedName) {
+      urlParameter.name = normalizedName;
+      parsedEndpoint = parsedEndpoint.replace(
+        `{${name}}`,
+        `{${normalizedName}}`
+      );
+    }
+  });
+  model.urlInfo.endpoint = parsedEndpoint;
+}

package/src/buildClientDefinitions.ts

@@ -18,8 +18,12 @@ import {
 } from "./helpers/operationHelpers.js";
 import { PathMetadata, Paths, RLCModel } from "./interfaces.js";
 import { generateMethodShortcuts } from "./helpers/shortcutMethods.js";
-import { REST_CLIENT_RESERVED } from './buildMethodShortcuts.js'
-import { CasingConvention, NameType, normalizeName } from "./helpers/nameUtils.js";
+import { REST_CLIENT_RESERVED } from "./buildMethodShortcuts.js";
+import {
+  CasingConvention,
+  NameType,
+  normalizeName
+} from "./helpers/nameUtils.js";
 import { pascalCase } from "./helpers/nameUtils.js";
 
 export function buildClientDefinitions(model: RLCModel) {

package/src/buildIndexFile.ts

@@ -5,9 +5,13 @@ import { Project, SourceFile } from "ts-morph";
 import { NameType, normalizeName } from "./helpers/nameUtils.js";
 import {
   hasInputModels,
+  hasMultiCollection,
   hasOutputModels,
   hasPagingOperations,
+  hasPipeCollection,
   hasPollingOperations,
+  hasSsvCollection,
+  hasTsvCollection,
   hasUnexpectedHelper
 } from "./helpers/operationHelpers.js";
 import { RLCModel } from "./interfaces.js";
@@ -89,6 +93,19 @@ function generateRLCIndexForMultiClient(file: SourceFile, model: RLCModel) {
     exports.push("PollingHelper");
   }
 
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model)
+  ) {
+    file.addImportDeclaration({
+      namespaceImport: "SerializeHelper",
+      moduleSpecifier: "./serializeHelper"
+    });
+    exports.push("SerializeHelper");
+  }
+
   file.addExportDeclarations([
     {
       moduleSpecifier: `./${moduleName}`,
@@ -165,6 +182,17 @@ function generateRLCIndex(file: SourceFile, model: RLCModel) {
     ]);
   }
 
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model)
+  ) {
+    file.addExportDeclarations([{
+      moduleSpecifier: "./serializeHelper"
+    }]);
+  }
+
   file.addExportAssignment({
     expression: createClientFuncName,
     isExportEquals: false

package/src/buildIsUnexpectedHelper.ts

@@ -22,9 +22,9 @@ export function buildIsUnexpectedHelper(model: RLCModel) {
   });
 
   let map: Record<string, string[]> = {};
-  let allResponseTypes: Set<string> = new Set();
-  let allErrorTypes: Set<string> = new Set();
-  let overloads: OptionalKind<FunctionDeclarationOverloadStructure>[] = [];
+  const allResponseTypes: Set<string> = new Set();
+  const allErrorTypes: Set<string> = new Set();
+  const overloads: OptionalKind<FunctionDeclarationOverloadStructure>[] = [];
   const pathDictionary = model.paths;
 
   for (const [path, details] of Object.entries(pathDictionary)) {
@@ -112,7 +112,7 @@ export function buildIsUnexpectedHelper(model: RLCModel) {
           } pathDetails = responseMap[\`\${method} \${url.pathname}\`];
           if (!pathDetails) {`,
         hasTemplate
-          ? "pathDetails = geParametrizedPathSuccess(method, url.pathname);"
+          ? "pathDetails = getParametrizedPathSuccess(method, url.pathname);"
           : `return true;`,
         `  }
           return !pathDetails.includes(response.status);
@@ -122,7 +122,7 @@ export function buildIsUnexpectedHelper(model: RLCModel) {
     if (hasTemplate) {
       isErrorHelper.addFunction({
         isExported: false,
-        name: "geParametrizedPathSuccess",
+        name: "getParametrizedPathSuccess",
         parameters: [
           {
             name: "method",
@@ -136,75 +136,75 @@ export function buildIsUnexpectedHelper(model: RLCModel) {
         returnType: `string[]`,
         statements: [
           `
-        const pathParts = path.split("/");
-
-        // Iterate the responseMap to find a match
-        for (const [key, value] of Object.entries(responseMap)) {
-          // Extracting the path from the map key which is in format
-          // GET /path/foo
-          if (!key.startsWith(method)) {
-            continue;
-          }
-          const candidatePath = getPathFromMapKey(key);
-          // Get each part of the url path
-          const candidateParts = candidatePath.split("/");
-      
-          // If the candidate and actual paths don't match in size
-          // we move on to the next candidate path
-          if (
-            candidateParts.length === pathParts.length &&
-            hasParametrizedPath(key)
-          ) {
+          const pathParts = path.split("/");
+            
+          // Traverse list to match the longest candidate
+          // matchedLen: the length of candidate path
+          // matchedValue: the matched status code array
+          let matchedLen = -1,
+            matchedValue: string[] = [];
+          
+          // Iterate the responseMap to find a match
+          for (const [key, value] of Object.entries(responseMap)) {
+            // Extracting the path from the map key which is in format
+            // GET /path/foo
+            if (!key.startsWith(method)) {
+              continue;
+            }
+            const candidatePath = getPathFromMapKey(key);
+            // Get each part of the url path
+            const candidateParts = candidatePath.split("/");
+        
             // track if we have found a match to return the values found.
             let found = true;
-            for (let i = 0; i < candidateParts.length; i++) {
+            for (
+              let i = candidateParts.length - 1, j = pathParts.length - 1;
+              i >= 1 && j >= 1;
+              i--, j--
+            ) {
               if (
                 candidateParts[i]?.startsWith("{") &&
-                candidateParts[i]?.endsWith("}")
+                candidateParts[i]?.indexOf("}") !== -1
               ) {
+                const start = candidateParts[i]!.indexOf("}") + 1,
+                  end = candidateParts[i]?.length;
                 // If the current part of the candidate is a "template" part
-                // it is a match with the actual path part on hand
-                // skip as the parameterized part can match anything
+                // Try to use the suffix of pattern to match the path
+                // {guid} ==> $
+                // {guid}:export ==> :export$
+                const isMatched = new RegExp(
+                  \`\${candidateParts[i]?.slice(start, end)}\`
+                ).test(pathParts[j] || '');
+        
+                if (!isMatched) {
+                  found = false;
+                  break;
+                }
                 continue;
               }
-      
+        
               // If the candidate part is not a template and
               // the parts don't match mark the candidate as not found
               // to move on with the next candidate path.
-              if (candidateParts[i] !== pathParts[i]) {
+              if (candidateParts[i] !== pathParts[j]) {
                 found = false;
                 break;
               }
             }
-      
+        
             // We finished evaluating the current candidate parts
-            // if all parts matched we return the success values form
-            // the path mapping.
-            if (found) {
-              return value;
+            // Update the matched value if and only if we found the longer pattern
+            if (found && candidatePath.length > matchedLen) {
+              matchedLen = candidatePath.length;
+              matchedValue = value;
             }
           }
-        }
-      
-        // No match was found, return an empty array.
-        return [];
+        
+          return matchedValue;
         `
         ]
       });
 
-      isErrorHelper.addFunction({
-        isExported: false,
-        name: "hasParametrizedPath",
-        parameters: [
-          {
-            name: "path",
-            type: "string"
-          }
-        ],
-        returnType: `boolean`,
-        statements: [`return path.includes("/{");`]
-      });
-
       isErrorHelper.addFunction({
         isExported: false,
         name: "getPathFromMapKey",

package/src/buildMethodShortcuts.ts

@@ -22,7 +22,7 @@ export const REST_CLIENT_RESERVED: ReservedName[] = [
 ];
 
 export function buildMethodShortcutImplementation(paths: Paths) {
-  let keys: Record<string, string[]> = {};
+  const keys: Record<string, string[]> = {};
   for (const path of Object.keys(paths)) {
     const groupName = normalizeName(
       paths[path].operationGroupName,

package/src/buildObjectTypes.ts

@@ -33,6 +33,9 @@ export function buildObjectInterfaces(
   const objectInterfaces: InterfaceDeclarationStructure[] = [];
 
   for (const objectSchema of objectSchemas) {
+    if (objectSchema.alias || objectSchema.outputAlias) {
+      continue;
+    }
     const baseName = getObjectBaseName(objectSchema, schemaUsage);
     const interfaceDeclaration = getObjectInterfaceDeclaration(
       baseName,
@@ -46,6 +49,40 @@ export function buildObjectInterfaces(
   return objectInterfaces;
 }
 
+export function buildObjectAliases(
+  model: RLCModel,
+  importedModels: Set<string>,
+  schemaUsage: SchemaContext[]
+) {
+  const objectSchemas: ObjectSchema[] = (model.schemas ?? []).filter(
+    (o) =>
+      isObjectSchema(o) &&
+      (o as ObjectSchema).usage?.some((u) => schemaUsage.includes(u))
+  );
+  const objectAliases: TypeAliasDeclarationStructure[] = [];
+
+  for (const objectSchema of objectSchemas) {
+    if (objectSchema.alias || objectSchema.outputAlias) {
+      const description = objectSchema.description;
+      objectAliases.push({
+        kind: StructureKind.TypeAlias,
+        ...(description && { docs: [{ description }] }),
+        name: schemaUsage.includes(SchemaContext.Input)
+          ? `${objectSchema.typeName}`
+          : `${objectSchema.outputTypeName}`,
+        type: schemaUsage.includes(SchemaContext.Input)
+          ? `${objectSchema.alias}`
+          : `${objectSchema.outputAlias}`,
+        isExported: true
+      });
+      if (objectSchema.alias?.startsWith("Paged<")) {
+        importedModels.add("Paged");
+      }
+    }
+  }
+  return objectAliases;
+}
+
 export function buildPolymorphicAliases(
   model: RLCModel,
   schemaUsage: SchemaContext[]
@@ -123,7 +160,7 @@ function getPolymorphicTypeAlias(
   }
 
   const description = objectSchema.description;
-  
+
   return {
     kind: StructureKind.TypeAlias,
     ...(description && { docs: [{ description }] }),
@@ -316,7 +353,7 @@ function getImmediateParentsNames(
     return [];
   }
 
-  let extendFrom: string[] = [];
+  const extendFrom: string[] = [];
 
   // If an immediate parent is a DictionarySchema, that means that the object has been marked
   // with additional properties. We need to add Record<string, unknown> to the extend list and
@@ -350,7 +387,12 @@ function getPropertySignatures(
   schemaUsage: SchemaContext[],
   importedModels: Set<string>
 ) {
-  return Object.keys(properties).map((p) =>
+  let validProperties = Object.keys(properties);
+  const readOnlyFilter = (name: string) =>
+    !(schemaUsage.includes(SchemaContext.Input) && properties[name].readOnly);
+  const neverFilter = (name: string) => properties[name].type !== "never";
+  validProperties = validProperties.filter(readOnlyFilter).filter(neverFilter);
+  return validProperties.map((p) =>
     getPropertySignature(
       { ...properties[p], name: p },
       schemaUsage,
@@ -368,26 +410,40 @@ function getPropertySignatures(
 export function getPropertySignature(
   property: Property | Parameter,
   schemaUsage: SchemaContext[],
-  importedModels = new Set<string>()
+  importedModels: Set<string>
 ): PropertySignatureStructure {
   const propertyName = property.name;
 
   const description = property.description;
-  const type =
-    ((schemaUsage.includes(SchemaContext.Output) &&
-      property.usage?.includes(SchemaContext.Output)) ||
-      (schemaUsage.includes(SchemaContext.Exception) &&
-        property.usage?.includes(SchemaContext.Exception))) &&
-    property.outputTypeName
+  let type =
+    generateForOutput(schemaUsage, property.usage) && property.outputTypeName
       ? property.outputTypeName
       : property.typeName
       ? property.typeName
       : property.type;
+  if (property.typeName && property.fromCore) {
+    importedModels.add(property.typeName);
+    type = property.typeName;
+  }
   return {
     name: propertyName,
     ...(description && { docs: [{ description }] }),
     hasQuestionToken: !property.required,
+    isReadonly:
+      generateForOutput(schemaUsage, property.usage) && property.readOnly,
     type,
     kind: StructureKind.PropertySignature
   };
 }
+
+function generateForOutput(
+  schemaUsage: SchemaContext[],
+  propertyUsage?: SchemaContext[]
+) {
+  return (
+    (schemaUsage.includes(SchemaContext.Output) &&
+      propertyUsage?.includes(SchemaContext.Output)) ||
+    (schemaUsage.includes(SchemaContext.Exception) &&
+      propertyUsage?.includes(SchemaContext.Exception))
+  );
+}

package/src/buildParameterTypes.ts

@@ -11,12 +11,12 @@ import {
 import * as path from "path";
 import {
   ImportKind,
+  ObjectSchema,
   ParameterMetadata,
   ParameterMetadatas,
   RLCModel,
   Schema
 } from "./interfaces.js";
-import { NameType, normalizeName } from "./helpers/nameUtils.js";
 import {
   getParameterBaseName,
   getParameterTypeName
@@ -92,6 +92,11 @@ export function buildParameterTypes(model: RLCModel) {
         i
       );
 
+      const bodyTypeAlias = buildBodyTypeAlias(parameter);
+      if (bodyTypeAlias) {
+        parametersFile.addTypeAlias(bodyTypeAlias);
+      }
+
       // Add interfaces for body and query parameters
       parametersFile.addInterfaces([
         ...(bodyParameterDefinition ?? []),
@@ -215,7 +220,7 @@ function getPropertyFromSchema(schema: Schema): PropertySignatureStructure {
     name: schema.name,
     ...(description && { docs: [{ description }] }),
     type: schema.type,
-    hasQuestionToken: !Boolean(schema.required),
+    hasQuestionToken: !schema.required,
     kind: StructureKind.PropertySignature
   };
 }
@@ -296,8 +301,12 @@ function buildHeaderParameterDefinitions(
     baseName
   );
 
+  let isOptional = true;
   if (headersInterface) {
     parametersFile.addInterface(headersInterface);
+    isOptional = !(headersInterface.properties || []).some(
+      (prop) => prop.hasQuestionToken === false
+    );
   }
 
   internalReferences.add(headerParameterInterfaceName);
@@ -310,7 +319,8 @@ function buildHeaderParameterDefinitions(
       {
         name: "headers",
         type: `RawHttpHeadersInput & ${baseName}Headers`,
-        kind: StructureKind.PropertySignature
+        kind: StructureKind.PropertySignature,
+        hasQuestionToken: isOptional
       }
     ]
   };
@@ -433,3 +443,35 @@ function buildBodyParametersDefinition(
     ];
   }
 }
+
+export function buildBodyTypeAlias(parameters: ParameterMetadatas) {
+  const bodyParameters = parameters.body;
+  if (
+    !bodyParameters ||
+    !bodyParameters?.body ||
+    !bodyParameters?.body.length
+  ) {
+    return undefined;
+  }
+  const schema = bodyParameters.body[0] as ObjectSchema;
+  const headerParameters = (parameters.parameters || []).filter(
+    (p) => p.type === "header" && p.name === "contentType"
+  );
+  if (!headerParameters.length || headerParameters.length > 1) {
+    return undefined;
+  }
+
+  const contentType = headerParameters[0].param.type;
+  const description = `${schema.description}`;
+  const typeName = `${schema.typeName}ResourceMergeAndPatch`;
+  if (contentType.includes("application/merge-patch+json")) {
+    const type = `Partial<${schema.typeName}>`;
+    return {
+      // kind: StructureKind.TypeAlias,
+      ...(description && { docs: [{ description }] }),
+      name: `${typeName}`,
+      type,
+      isExported: true
+    };
+  }
+}