@azure-tools/typespec-ts 0.11.0

package/test/unit/clientFactoryGenerator.spec.ts

@@ -0,0 +1,507 @@
+import { assert } from "chai";
+import { emitClientFactoryFromCadl } from "./util/emitUtil.js";
+import { assertEqualContent } from "./util/testUtil.js";
+
+describe("Client Factory generation", () => {
+  describe("should handle url parameters", () => {
+    it("should handle zero parameter", async () => {
+      const models = await emitClientFactoryFromCadl(`
+      @server(
+        "localhost",
+        "Language Service"
+      )
+      @service( {title: "PetStoreClient"})
+      namespace PetStore;
+      `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+        import { getClient, ClientOptions } from "@azure-rest/core-client";
+        import { testClient } from "./clientDefinitions";
+        
+        /**
+         * Initialize a new instance of \`testClient\`
+         * @param options type: ClientOptions, the parameter for all optional parameters
+         */
+        export default function createClient(options: ClientOptions = {}): testClient {
+        const baseUrl = options.baseUrl ?? \`localhost\`;
+        
+        const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+        const userAgentPrefix =
+            options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+            ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+            : \`\${userAgentInfo}\`;
+        options = {
+            ...options,
+            userAgentOptions: {
+            userAgentPrefix,
+            },
+        };
+        
+        const client = getClient(baseUrl, options) as testClient;
+        
+        return client;
+    }
+    `
+      );
+    });
+    it("should handle one parameter", async () => {
+      const models = await emitClientFactoryFromCadl(`
+          @server(
+            "{Endpoint}/language",
+            "Language Service",
+            {
+              Endpoint: Endpoint,
+            }
+          )
+          @service( {title: "PetStoreClient"})
+          namespace PetStore;
+          @doc("The endpoint to use.")
+          scalar Endpoint extends string;
+          `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+          import { getClient, ClientOptions } from "@azure-rest/core-client";
+          import { testClient } from "./clientDefinitions";
+
+          /**
+           * Initialize a new instance of \`testClient\`
+           * @param endpoint type: string, The endpoint to use.
+           * @param options type: ClientOptions, the parameter for all optional parameters
+           */
+          export default function createClient(
+            endpoint: string,
+            options: ClientOptions = {}
+          ): testClient {
+            const baseUrl = options.baseUrl ?? \`\${endpoint}/language\`;
+          
+            const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+            const userAgentPrefix =
+              options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+                ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+                : \`\${userAgentInfo}\`;
+            options = {
+              ...options,
+              userAgentOptions: {
+                userAgentPrefix,
+              },
+            };
+          
+            const client = getClient(baseUrl, options) as testClient;
+          
+            return client;
+        }
+        `
+      );
+    });
+
+    it("should handle two parameters", async () => {
+      const models = await emitClientFactoryFromCadl(
+        `
+            @server(
+              "{Endpoint}/language/{Version}",
+              "Language Service",
+              {
+                Endpoint: Endpoint,
+                Version: Version
+              }
+            )
+            @service( {title: "PetStoreClient"})
+            namespace PetStore;
+            @doc("The endpoint to use.")
+            scalar Endpoint extends string;
+
+            #suppress "@azure-tools/typespec-azure-core/use-extensible-enum" "for test"
+            @doc("The version to use")
+            @fixed
+            enum Version {
+              V1,
+              V2
+            }
+            `,
+        true
+      );
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+            import { getClient, ClientOptions } from "@azure-rest/core-client";
+            import { testClient } from "./clientDefinitions";
+            
+            /**
+             * Initialize a new instance of \`testClient\`
+             * @param endpoint type: string, The endpoint to use.
+             * @param version type: "V1"|"V2", The version to use
+             * @param options type: ClientOptions, the parameter for all optional parameters
+             */
+            export default function createClient(
+              endpoint: string,
+              version: "V1" | "V2",
+              options: ClientOptions = {}
+            ): testClient {
+              const baseUrl = options.baseUrl ?? \`\${endpoint}/language/\${version}\`;
+            
+              const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+              const userAgentPrefix =
+                options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+                  ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+                  : \`\${userAgentInfo}\`;
+              options = {
+                ...options,
+                userAgentOptions: {
+                  userAgentPrefix,
+                },
+              };
+            
+              const client = getClient(baseUrl, options) as testClient;
+            
+              return client;
+          }
+          `
+      );
+    });
+    it("should handle extensible enums in host parameters", async () => {
+      const models = await emitClientFactoryFromCadl(
+        `
+            @server(
+              "{Endpoint}/language/{Version}",
+              "Language Service",
+              {
+                Endpoint: Endpoint,
+                Version: Versions
+              }
+            )
+            @service( {title: "PetStoreClient"})
+            namespace PetStore;
+            @doc("The endpoint to use.")
+            scalar Endpoint extends string;
+
+            @doc("The version to use.")
+            enum Versions {
+              v1_1: "v1.1",
+            }
+            `,
+        true
+      );
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+            import { getClient, ClientOptions } from "@azure-rest/core-client";
+            import { testClient } from "./clientDefinitions";
+            
+            /**
+             * Initialize a new instance of \`testClient\`
+             * @param endpoint type: string, The endpoint to use.
+             * @param version type: string, The version to use. Possible values: v1.1
+             * @param options type: ClientOptions, the parameter for all optional parameters
+             */
+            export default function createClient(
+              endpoint: string,
+              version: string,
+              options: ClientOptions = {}
+            ): testClient {
+              const baseUrl = options.baseUrl ?? \`\${endpoint}/language/\${version}\`;
+            
+              const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+              const userAgentPrefix =
+                options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+                  ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+                  : \`\${userAgentInfo}\`;
+              options = {
+                ...options,
+                userAgentOptions: {
+                  userAgentPrefix,
+                },
+              };
+            
+              const client = getClient(baseUrl, options) as testClient;
+            
+              return client;
+          }
+          `
+      );
+    });
+  });
+
+  describe("should handle apiVersion correctly", () => {
+    describe("apiVersion as query parameter", () => {
+      it("should set the default value in options", async () => {
+        const models = await emitClientFactoryFromCadl(`
+            @server(
+              "{Endpoint}/language",
+              "Language Service",
+              {
+                Endpoint: Endpoint
+              }
+            )
+            @service({
+              title: "PetStoreClient",
+              version: "2022-05-15-preview",
+            })
+            namespace PetStore;
+            @doc("The endpoint to use.")
+            scalar Endpoint extends string;
+            `);
+        assert.ok(models);
+        assertEqualContent(
+          models!.content,
+          `
+            import { getClient, ClientOptions } from "@azure-rest/core-client";
+            import { testClient } from "./clientDefinitions";
+            
+            /**
+             * Initialize a new instance of \`testClient\`
+             * @param endpoint type: string, The endpoint to use.
+             * @param options type: ClientOptions, the parameter for all optional parameters
+             */
+            export default function createClient(
+              endpoint: string,
+              options: ClientOptions = {}
+            ): testClient {
+              const baseUrl = options.baseUrl ?? \`\${endpoint}/language\`;
+              options.apiVersion = options.apiVersion ?? "2022-05-15-preview";
+            
+              const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+              const userAgentPrefix =
+                options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+                  ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+                  : \`\${userAgentInfo}\`;
+              options = {
+                ...options,
+                userAgentOptions: {
+                  userAgentPrefix,
+                },
+              };
+            
+              const client = getClient(baseUrl, options) as testClient;
+            
+              return client;
+          }
+          `
+        );
+      });
+    });
+    describe("apiVersion as path parameter", () => {
+      it("should set the default value in customized options", async () => {
+        const models = await emitClientFactoryFromCadl(`
+            @versioned(Versions)
+            @server(
+              "{Endpoint}/anomalydetector/{ApiVersion}",
+              "Language Service",
+              {
+                Endpoint: Endpoint,
+                @doc("Api Version")
+                @path
+                ApiVersion: APIVersion,
+              }
+            )
+            @service({
+              title: "PetStoreClient"
+            })
+            namespace PetStore;
+            @doc("The endpoint to use.")
+            scalar Endpoint extends string;
+
+            enum Versions {
+              v1_1: "v1.1",
+            }
+            @knownValues(Versions)
+            scalar APIVersion extends string;
+            `);
+        assert.ok(models);
+        assertEqualContent(
+          models!.content,
+          `
+            import { getClient, ClientOptions } from "@azure-rest/core-client";
+            import { testClient } from "./clientDefinitions";
+            
+            export interface testClientOptions extends ClientOptions {
+              apiVersion?: string;
+            }
+
+            /**
+             * Initialize a new instance of \`testClient\`
+             * @param endpoint type: string, The endpoint to use.
+             * @param options type: testClientOptions, the parameter for all optional parameters
+             */
+            export default function createClient(
+              endpoint: string,
+              options: testClientOptions = {}
+            ): testClient {
+              const apiVersion = options.apiVersion ?? "v1.1";
+              const baseUrl = options.baseUrl ?? \`\${endpoint}/anomalydetector/\${apiVersion}\`;
+            
+              const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+              const userAgentPrefix =
+                options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+                  ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+                  : \`\${userAgentInfo}\`;
+              options = {
+                ...options,
+                userAgentOptions: {
+                  userAgentPrefix,
+                },
+              };
+            
+              const client = getClient(baseUrl, options) as testClient;
+            
+              return client;
+          }
+          `
+        );
+      });
+    });
+    describe("mixed apiVersion in path & query parameter", () => {});
+  });
+
+  describe("should handle no @server definition", () => {
+    it("should set default endpoint parameter when no @server", async () => {
+      const models = await emitClientFactoryFromCadl(`
+      @service( {title: "PetStoreClient"})
+      namespace PetStore;
+      `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+        import { getClient, ClientOptions } from "@azure-rest/core-client";
+        import { testClient } from "./clientDefinitions";
+        
+        /**
+         * Initialize a new instance of \`testClient\`
+         * @param endpoint type: string, The parameter endpoint
+         * @param options type: ClientOptions, the parameter for all optional parameters
+         */
+        export default function createClient(endpoint: string, options: ClientOptions = {}): testClient {
+        const baseUrl = options.baseUrl ?? \`\${endpoint}\`;
+        
+        const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+        const userAgentPrefix =
+            options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+            ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+            : \`\${userAgentInfo}\`;
+        options = {
+            ...options,
+            userAgentOptions: {
+            userAgentPrefix,
+            },
+        };
+        
+        const client = getClient(baseUrl, options) as testClient;
+        
+        return client;
+    }
+    `
+      );
+    });
+  });
+
+  describe("should handle different auth options", () => {
+    it("should not generate credential if scope is empty", async () => {
+      const models = await emitClientFactoryFromCadl(`
+      @useAuth(
+        OAuth2Auth<[{
+          type: OAuth2FlowType.implicit,
+          authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+          scopes: []
+        }]>)
+      @service( {title: "PetStoreClient"})
+      namespace PetStore;
+      `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+        import { getClient, ClientOptions } from "@azure-rest/core-client";
+        import { testClient } from "./clientDefinitions";
+        
+        /**
+         * Initialize a new instance of \`testClient\`
+         * @param endpoint type: string, The parameter endpoint
+         * @param options type: ClientOptions, the parameter for all optional parameters
+         */
+        export default function createClient(endpoint: string, options: ClientOptions = {}): testClient {
+        const baseUrl = options.baseUrl ?? \`\${endpoint}\`;
+        
+        const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+        const userAgentPrefix =
+            options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+            ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+            : \`\${userAgentInfo}\`;
+        options = {
+            ...options,
+            userAgentOptions: {
+            userAgentPrefix,
+            },
+        };
+        
+        const client = getClient(baseUrl, options) as testClient;
+        
+        return client;
+    }
+    `
+      );
+    });
+
+    it("should generate both credentials if both defined", async () => {
+      const models = await emitClientFactoryFromCadl(`
+      @useAuth(
+        ApiKeyAuth<ApiKeyLocation.header, "apiKey"> |
+          OAuth2Auth<[{
+            type: OAuth2FlowType.implicit,
+            authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+            scopes: ["https://petstor.com/default"]
+          }]>)
+      @service( {title: "PetStoreClient"})
+      namespace PetStore;
+      `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.content,
+        `
+        import { getClient, ClientOptions } from "@azure-rest/core-client";
+        import { TokenCredential, KeyCredential } from "@azure/core-auth";
+        import { testClient } from "./clientDefinitions";
+        
+        /**
+         * Initialize a new instance of \`testClient\`
+         * @param endpoint type: string, The parameter endpoint
+         * @param credentials type: TokenCredential|KeyCredential, uniquely identify client credential
+         * @param options type: ClientOptions, the parameter for all optional parameters
+         */
+        export default function createClient(endpoint: string, credentials: TokenCredential | KeyCredential, options: ClientOptions = {}): testClient {
+        const baseUrl = options.baseUrl ?? \`\${endpoint}\`;
+
+        options = {
+            ...options,
+            credentials: {
+              scopes: ["https://petstor.com/default"],
+              apiKeyHeaderName: "apiKey",
+            },
+          };
+        
+        const userAgentInfo = \`azsdk-js--rest/1.0.0-beta.1\`;
+        const userAgentPrefix =
+            options.userAgentOptions && options.userAgentOptions.userAgentPrefix
+            ? \`\${options.userAgentOptions.userAgentPrefix} \${userAgentInfo}\`
+            : \`\${userAgentInfo}\`;
+        options = {
+            ...options,
+            userAgentOptions: {
+            userAgentPrefix,
+            },
+        };
+        
+        const client = getClient(baseUrl, credentials, options) as testClient;
+        
+        return client;
+    }
+    `
+      );
+    });
+  });
+});

package/test/unit/docsGenerator.spec.ts

@@ -0,0 +1,201 @@
+import { assert } from "chai";
+import {
+  emitClientDefinitionFromCadl,
+  emitModelsFromCadl,
+  emitParameterFromCadl
+} from "./util/emitUtil.js";
+import { assertEqualContent } from "./util/testUtil.js";
+
+describe("Doc generation testing", () => {
+  describe("docs in models.ts & outputModels.ts", () => {
+    it("should generate model-level and property-level docs in input model", async () => {
+      const models = await emitModelsFromCadl(`
+        @doc("A simple model with doc")  
+        model SimpleModel {
+            @doc("A test property.")
+            prop: string;
+        }
+        op read(): { @body body: SimpleModel };
+        `);
+      assert.ok(models);
+      assertEqualContent(
+        models!.outputModelFile!.content,
+        `
+      /** A simple model with doc */
+      export interface SimpleModelOutput {
+        /** A test property. */
+        prop: string;
+      }
+      `
+      );
+    });
+  });
+
+  describe("docs in parameters.ts", () => {
+    it("should generate body description", async () => {
+      const parameters = await emitParameterFromCadl(
+        `
+        model UserDetailsParameter {
+          @body
+          @doc("Details about username.")
+          username: string;
+        }
+        op createOrUpdateUser(...UserDetailsParameter): OkResponse;
+        `
+      );
+      assert.ok(parameters);
+      assertEqualContent(
+        parameters?.content!,
+        `
+        import { RequestParameters } from "@azure-rest/core-client";
+
+        export interface CreateOrUpdateUserBodyParam {
+          /** Details about username. */
+          body: string;
+        }
+
+        export type CreateOrUpdateUserParameters = CreateOrUpdateUserBodyParam & RequestParameters;
+      `
+      );
+    });
+    it("shouldn't generate type description as body property description", async () => {
+      const parameters = await emitParameterFromCadl(
+        `
+        @doc("Body type details")
+        model UserDetailsParameter {
+          username: string;
+        }
+        op createOrUpdateUser(@body username: UserDetailsParameter): OkResponse;
+        `
+      );
+      assert.ok(parameters);
+      assertEqualContent(
+        parameters?.content!,
+        `
+        import { RequestParameters } from "@azure-rest/core-client";
+        import { UserDetailsParameter } from "./models";
+
+        export interface CreateOrUpdateUserBodyParam {
+          body: UserDetailsParameter;
+        }
+
+        export type CreateOrUpdateUserParameters = CreateOrUpdateUserBodyParam & RequestParameters;
+      `
+      );
+    });
+    it("should generate query description", async () => {
+      const parameters = await emitParameterFromCadl(
+        `
+        @doc("The filter query parameter.")
+        model FilterParameter {
+          @query
+          @doc("Input your filter condition.")
+          filter: string;
+        }
+        op list(...FilterParameter): OkResponse;
+        `
+      );
+      assert.ok(parameters);
+      assertEqualContent(
+        parameters?.content!,
+        `
+        import { RequestParameters } from "@azure-rest/core-client";
+        
+        export interface ListQueryParamProperties {
+            /** Input your filter condition. */
+            filter: string;
+        }
+        
+        export interface ListQueryParam {
+            queryParameters: ListQueryParamProperties;
+        }
+        
+        export type ListParameters = ListQueryParam & RequestParameters;
+      `
+      );
+    });
+    it("should generate header description with custom name", async () => {
+      const parameters = await emitParameterFromCadl(
+        `
+        op test(@doc("test header") @header("x-my-header") MyHeader: string): string;
+        `
+      );
+      assert.ok(parameters);
+      assertEqualContent(
+        parameters?.content!,
+        `
+        import { RawHttpHeadersInput } from "@azure/core-rest-pipeline";
+        import { RequestParameters } from "@azure-rest/core-client";
+  
+        export interface TestHeaders {
+            /** test header */
+            "x-my-header": string;
+        }
+        
+        export interface TestHeaderParam {
+            headers: RawHttpHeadersInput & TestHeaders;
+        }
+        
+       export type TestParameters = TestHeaderParam & RequestParameters;
+      `
+      );
+    });
+    it("should generate contentType description", async () => {
+      const parameters = await emitParameterFromCadl(
+        `
+        #suppress "@typespec/http/content-type-ignored" "for test"
+        op test(@doc("content type") @header contentType: "application/octet-stream"): string;
+        `
+      );
+      assert.ok(parameters);
+      assertEqualContent(
+        parameters?.content!,
+        `
+      import { RequestParameters } from "@azure-rest/core-client";
+      
+      export interface TestMediaTypesParam {
+          /** content type */
+          contentType: "application/octet-stream";
+      }
+      
+      export type TestParameters = TestMediaTypesParam & RequestParameters;
+      `
+      );
+    });
+  });
+
+  describe("docs in clientDefinitions.ts", () => {
+    it("should generate operation description", async () => {
+      const clientDef = await emitClientDefinitionFromCadl(
+        `
+        @summary("This is a summary")
+        @doc("This is the longer description")
+        op read(): {};
+        `
+      );
+      assert.ok(clientDef);
+      assertEqualContent(
+        clientDef?.content!,
+        `
+        import { ReadParameters } from "./parameters";
+        import { Read200Response } from "./responses";
+        import { Client, StreamableMethod } from "@azure-rest/core-client";
+  
+        export interface Read {
+            /** This is the longer description */
+            get(options?: ReadParameters): StreamableMethod<Read200Response>;
+        }
+  
+        export interface Routes {
+            /** Resource for '/' has methods for the following verbs: get */
+            (path: "/"): Read;
+        }
+        
+        export type testClient = Client & {
+                path: Routes;
+        };
+      `
+      );
+    });
+  });
+});