Skip to content

Latest commit

 

History

History
 
 

typespec-ts

README.md

Introduction

This library is the TypeSpec typescript emitter for Rest Level Client. It take TypeSpec as input, transform it into RLCModel, then call rlc-common library to generate the RLC code.

On a high level, the entire Rest Level Client generation process would be:

TypeSpec Input -> TypeSpec Compiler -> TypeSpec Program -> Transform RLCModel -> TypeSpec RLC Common library to Generate Code

Within the Transform RLCModel, it has the following stages:

TypeSpec Program + User Options -> Transform RLCModel Paths -> Transform RLCModel Options -> Transform RLCModel Schemas -> Transform RLCModel Response and Parameter Types -> TypeSpec RLCCommon libraries to generate the code.

How to use

Prerequisite

Install Node.js 16 or above. (Verify by node --version)

Install TypeSpec latest.

Initialize TypeSpec Project

Follow TypeSpec Getting Started to initialize your TypeSpec project.

Make sure npx tsp compile . runs correctly.

Add typespec-ts

Make sure the version of typespec-ts release depends on the same version of "@typespec/compiler" as in your TypeSpec project.

Modify package.json, add one line under dependencies:

    "dependencies": {
      "@typespec/compiler": "latest",
      "@typespec/rest": "latest",
      "@azure-tools/typespec-azure-core": "latest",
+      "@azure-tools/typespec-ts": "latest"
    },

Run npm install again to install @azure-tools/typespec-ts.

Modify (or create) tspconfig.yaml, add one line under emit:

emit:
+  - "@azure-tools/typespec-ts"

Modify tspconfig.yaml

One can further configure the SDK generated, using the emitter options on @azure-tools/typespec-ts.

options:
  "@azure-tools/typespec-ts":
    packageDetails:
      name: "@azure-rest/confidential-ledger"
      description: "Confidential Ledger Service"

Generate Typescript

Same npx tsp compile . or npx tsp compile . --output-path=<target-folder>.

If output-path option is not provided, generated code will be under tsp-output folder.

Emitter Options

packageDetails

Provide the metadata for package.json, README.md and user-agent information. And it's highly recommanded to set up this detail for your package.

Property Description
name the name of package.json file, usually start with @azure-rest if this is data-plane RLC client
description description used in package.json file
version detailed version for your released package, the default vaule is 1.0.0-beta.1

title

Generally the codegen will leverage the title defined in @client and @service decorator in TypeSpec to name our client. But if you'd like to override it you could config the title info.

title: AnomalyDetectorRest

generateMetadata

To indicate if the codegen needs to generate metadata files which includes package.json, README.md and tsconfig.json etc.

By default we'll enable the option but if you'd like to disable this feature you could set it as false.

generateMetadata: false

generateTest

To allow the codegen generating test sample files and updating testing configuration. And the default value is true and you could also turn it off as false.

includeShortcuts

To allow the codegen generating shortcut methods in client definition. This is an experimental feature so we disable it by default. If you want to try it just turn it on.

includeShortcuts: true

azureSdkForJs

This is used to indicate your project is generated in azure-sdk-for-js repo or not. If your package is located in that repo we'll leverage dev-tool to accelerate our building and testing, however if not we'll remove the dependency for that tool.

Usually the released JS sdk will be put into azure-sdk-for-js so we enable this option by default.

addCredentials

We support two types of authentication: Azure Key Credential(AzureKey) and Token credential(AADToken), any other will need to be handled manually.

There are two ways to set up our credential details

  • To use @useAuth decorator in TypeSpec
  • To config in yaml file

Please notice defining in TypeSpec is recommanded and also has higher priority than second one.

To enable credential in tspconfig.yaml and we need to provide more details to let codegen know types.

credentialScopes

If we enable the option addCredentials and specify credentialScopes the details we would enable the AADToken authentication.

addCredentials: true
credentialScopes: https://yourendpoint.azure.com/.default

credentialKeyHeaderName

If we enable the option addCredentials and specify credentialKeyHeaderName the details we would enable the AzureKey authentication.

addCredentials: true
credentialKeyHeaderName: Your-Subscription-Key

Contributing

If you want to contribute on this project read the contrubuting document for more details.