@azure-tools/typespec-java 0.26.1 → 0.27.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/dist/src/code-model-builder.d.ts.map +1 -1
  2. package/dist/src/code-model-builder.js +50 -41
  3. package/dist/src/code-model-builder.js.map +1 -1
  4. package/dist/src/emitter.d.ts +0 -1
  5. package/dist/src/emitter.d.ts.map +1 -1
  6. package/dist/src/emitter.js +54 -98
  7. package/dist/src/emitter.js.map +1 -1
  8. package/dist/src/utils.d.ts +6 -0
  9. package/dist/src/utils.d.ts.map +1 -1
  10. package/dist/src/utils.js +47 -0
  11. package/dist/src/utils.js.map +1 -1
  12. package/dist/src/validate.d.ts +4 -0
  13. package/dist/src/validate.d.ts.map +1 -0
  14. package/dist/src/validate.js +67 -0
  15. package/dist/src/validate.js.map +1 -0
  16. package/dist/tsconfig.tsbuildinfo +1 -1
  17. package/generator/http-client-generator/target/emitter.jar +0 -0
  18. package/package.json +31 -31
  19. package/readme.md +68 -4
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@azure-tools/typespec-java",
3
- "version": "0.26.1",
3
+ "version": "0.27.1",
4
4
  "description": "TypeSpec library for emitting Java client from the TypeSpec REST protocol binding",
5
5
  "keywords": [
6
6
  "TypeSpec"
@@ -45,17 +45,17 @@
45
45
  "generator/http-client-generator/target/emitter.jar"
46
46
  ],
47
47
  "peerDependencies": {
48
- "@azure-tools/typespec-azure-core": ">=0.48.0 <1.0.0",
49
- "@azure-tools/typespec-azure-resource-manager": ">=0.48.0 <1.0.0",
50
- "@azure-tools/typespec-autorest": ">=0.48.0 <1.0.0",
51
- "@azure-tools/typespec-azure-rulesets": ">=0.48.0 <1.0.0",
52
- "@azure-tools/typespec-client-generator-core": ">=0.48.5 <1.0.0",
53
- "@typespec/compiler": ">=0.62.0 <1.0.0",
54
- "@typespec/http": ">=0.62.0 <1.0.0",
55
- "@typespec/openapi": ">=0.62.0 <1.0.0",
56
- "@typespec/rest": ">=0.62.0 <1.0.0",
57
- "@typespec/versioning": ">=0.62.0 <1.0.0",
58
- "@typespec/xml": ">=0.62.0 <1.0.0"
48
+ "@azure-tools/typespec-azure-core": ">=0.49.0 <1.0.0",
49
+ "@azure-tools/typespec-azure-resource-manager": ">=0.49.0 <1.0.0",
50
+ "@azure-tools/typespec-autorest": ">=0.49.0 <1.0.0",
51
+ "@azure-tools/typespec-azure-rulesets": ">=0.49.0 <1.0.0",
52
+ "@azure-tools/typespec-client-generator-core": ">=0.49.0 <1.0.0",
53
+ "@typespec/compiler": ">=0.63.0 <1.0.0",
54
+ "@typespec/http": ">=0.63.0 <1.0.0",
55
+ "@typespec/openapi": ">=0.63.0 <1.0.0",
56
+ "@typespec/rest": ">=0.63.0 <1.0.0",
57
+ "@typespec/versioning": ">=0.63.0 <1.0.0",
58
+ "@typespec/xml": ">=0.63.0 <1.0.0"
59
59
  },
60
60
  "dependencies": {
61
61
  "@autorest/codemodel": "~4.20.0",
@@ -63,29 +63,29 @@
63
63
  "lodash": "~4.17.21"
64
64
  },
65
65
  "devDependencies": {
66
- "@azure-tools/typespec-azure-core": "0.48.0",
67
- "@azure-tools/typespec-azure-resource-manager": "0.48.0",
68
- "@azure-tools/typespec-autorest": "0.48.0",
69
- "@azure-tools/typespec-azure-rulesets": "0.48.0",
70
- "@azure-tools/typespec-client-generator-core": "0.48.5",
66
+ "@azure-tools/typespec-azure-core": "0.49.0",
67
+ "@azure-tools/typespec-azure-resource-manager": "0.49.0",
68
+ "@azure-tools/typespec-autorest": "0.49.0",
69
+ "@azure-tools/typespec-azure-rulesets": "0.49.0",
70
+ "@azure-tools/typespec-client-generator-core": "0.49.0",
71
71
  "@types/js-yaml": "~4.0.9",
72
72
  "@types/lodash": "~4.17.13",
73
- "@types/mocha": "~10.0.9",
74
- "@types/node": "~22.9.0",
75
- "@typescript-eslint/eslint-plugin": "~8.14.0",
76
- "@typescript-eslint/parser": "~8.14.0",
77
- "@typespec/compiler": "0.62.0",
78
- "@typespec/http": "0.62.0",
79
- "@typespec/openapi": "0.62.0",
80
- "@typespec/rest": "0.62.0",
81
- "@typespec/versioning": "0.62.0",
82
- "@typespec/xml": "0.62.0",
83
- "c8": "~10.1.2",
73
+ "@types/mocha": "~10.0.10",
74
+ "@types/node": "~22.10.1",
75
+ "@typescript-eslint/eslint-plugin": "~8.18.0",
76
+ "@typescript-eslint/parser": "~8.18.0",
77
+ "@typespec/compiler": "0.63.0",
78
+ "@typespec/http": "0.63.0",
79
+ "@typespec/openapi": "0.63.0",
80
+ "@typespec/rest": "0.63.0",
81
+ "@typespec/versioning": "0.63.0",
82
+ "@typespec/xml": "0.63.0",
83
+ "c8": "~10.1.3",
84
84
  "eslint": "~8.57.0",
85
85
  "eslint-plugin-deprecation": "~3.0.0",
86
- "mocha": "~10.8.2",
87
- "prettier": "~3.3.3",
86
+ "mocha": "~11.0.1",
87
+ "prettier": "~3.4.2",
88
88
  "rimraf": "~6.0.1",
89
- "typescript": "~5.6.3"
89
+ "typescript": "~5.7.2"
90
90
  }
91
91
  }
package/readme.md CHANGED
@@ -4,9 +4,9 @@ Install [Node.js](https://nodejs.org/en/download/) 20 or above. (Verify by runni
4
4
 
5
5
  Install [Java](https://docs.microsoft.com/java/openjdk/download) 11 or above. (Verify by running `java --version`)
6
6
 
7
- Install [Maven](https://maven.apache.org/install.html). (Verify by running `mvn --version`)
7
+ Install [Maven](https://maven.apache.org/download.cgi). (Verify by running `mvn --version`)
8
8
 
9
- Install [TypeSpec](https://typespec.io/) 0.62.
9
+ Install [TypeSpec](https://typespec.io/) 0.63.
10
10
 
11
11
  # Initialize TypeSpec Project
12
12
 
@@ -36,7 +36,6 @@ emit:
36
36
  options:
37
37
  "@azure-tools/typespec-java":
38
38
  emitter-output-dir: "{project-root}/azure-ai-language-authoring"
39
- namespace: "com.azure.ai.language.authoring"
40
39
  service-name: "Authoring"
41
40
  generate-samples: true
42
41
  generate-tests: true
@@ -44,6 +43,71 @@ options:
44
43
  api-version: "2023-11-01"
45
44
  ```
46
45
 
46
+ ### SDK Related Configuration in Emitter options `tspconfig.yaml`
47
+
48
+ #### `api-version`
49
+
50
+ By default, the emitter generates code from the latest api-version in TypeSpec.
51
+
52
+ In cases where a service needs to generate code from a previous api-version, set the value to that specific api-version.
53
+
54
+ #### `service-name`
55
+
56
+ This emitter option is for management-plane SDK.
57
+
58
+ It is advised for the service to set an appropriate service name. E.g. `service-name: Standby Pool`.
59
+
60
+ The name will appear in documentation (e.g. "README.md") that describes the service and the SDK. It would also affect the name of the entry class of the SDK.
61
+
62
+ #### `partial-update`
63
+
64
+ Default value is `false`.
65
+
66
+ This emitter option is for data-plane SDK.
67
+
68
+ In the case that the generated code is not good enough for the SDK, the developer can choose to customize the generated SDK via [Partial Update](https://github.com/Azure/azure-sdk-for-java/wiki/TypeSpec-Java-QuickStart#partial-update). Set the value to `true` to enable this feature.
69
+
70
+ #### `generate-samples`
71
+
72
+ Default value is `true`. The emitter generates code samples under the `generated` package.
73
+
74
+ For data-plane SDK, the generated samples are for reference. The motivation is to show how samples can be written. It is expected that developers write correct and concise samples outside of the `generated` package.
75
+
76
+ If there is customization of the generated SDK, the generated samples may not compile after customization. One can delete the `generated` package, and set the value to `false` to disable the generated samples.
77
+
78
+ #### `generate-tests`
79
+
80
+ Default value is `true`. The emitter generates tests under the `generated` package.
81
+
82
+ For data-plane SDK, the generated tests are (disabled) live tests. The motivation is to show how test cases can be written in Java with JUnit. It is expected that developers write runnable tests outside of the `generated` package.
83
+
84
+ For management-plane SDK, the generated tests are mock tests, for JSON serialization and API requests.
85
+
86
+ If there is customization of the generated SDK, the generated tests may not compile after customization. One can delete the `generated` package, and set the value to `false` to disable the generated tests.
87
+
88
+ ### SDK Related Configuration in Client Customization `client.tsp`
89
+
90
+ For Java SDK, it is required to provide a Java package name via `@clientNamespace`.
91
+
92
+ Here is an example:
93
+
94
+ ```ts
95
+ @@clientNamespace(Client, "com.azure.ai.openai", "java");
96
+ @@clientNamespace(Azure.OpenAI, "com.azure.ai.openai", "java");
97
+ ```
98
+
99
+ For management-plane SDK, one can provide a client name via `@clientName`.
100
+
101
+ Here is an example:
102
+
103
+ ```ts
104
+ @@clientNamespace(Microsoft.StandbyPool,
105
+ "com.azure.resourcemanager.standbypool",
106
+ "java"
107
+ );
108
+ @@clientName(Microsoft.StandbyPool, "StandbyPoolManagementClient", "java");
109
+ ```
110
+
47
111
  ## Convenience API
48
112
 
49
113
  By default, TypeSpec-Java generates all protocol APIs and convenience APIs.
@@ -51,8 +115,8 @@ A few exceptions are API of JSON Merge Patch, and API of long-running operation
51
115
 
52
116
  See "convenientAPI" decorator from [typespec-client-generator-core](https://github.com/Azure/typespec-azure/tree/main/packages/typespec-client-generator-core).
53
117
 
54
-
55
118
  # Customization
119
+
56
120
  All post-code customizations listed in this [documentation](https://github.com/Azure/autorest.java/tree/main/customization-base/README.md) are supported for code generated from TypeSpec.
57
121
 
58
122
  To configure customization with TypeSpec, Java's emitter options should include a `customization-class`. The `customization-class` option should specify the path to the file containing the customization code relative to `emitter-output-dir`. Note that the path should end with `src/main/java/<YourCustomizationClassName>.java`. The recommended practice is to place the customization class in `<output-dir>/customization/src/main/java/<YourCustomizationClassName>.java` and the `customization-class` option will have the value of `customization-class: customization/src/main/java/<YourCustomizationClassName>.java`. See example `tspconfig.yaml` below: