From b3f721792b9480f58dc7ea71e3ef8edee5c8471b Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 11 Jun 2024 13:18:51 -0700 Subject: [PATCH 1/4] Add release notes for 0.57.0 --- docs/release-notes/release-2024-06-10.md | 256 +++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/release-notes/release-2024-06-10.md diff --git a/docs/release-notes/release-2024-06-10.md b/docs/release-notes/release-2024-06-10.md new file mode 100644 index 00000000000..3106c69cf41 --- /dev/null +++ b/docs/release-notes/release-2024-06-10.md @@ -0,0 +1,256 @@ +--- +title: 0.57 - June 2024 +--- + +:::warning +This release contains deprecations +::: + +## Values In TypeSpec + +Decorators often expect some sort of configuration to be passed as an argument. In version `0.51.0` we introduced the `valueof` keyword to constrain a decorator or template parameter to be a value, however this was limited to string, numeric and boolean values. +When dealing with more complex decorators or free form data one had to use a model type to represent the data. This required a lot of manual validation in the decorator implementation and introduce a lot of potential issues(Passing a subtype like a union instead of a model) + +In this release we introduce a whole new world to TypeSpec, values. This include new syntax for declaring object and array values, scalar constructors, `const`. + +### Object values + +Object values can be declared with the `#{}` syntax. + +```tsp +const user = #{ name: "Bob", age: 48, address: #{ city: "London" } }; +``` + +### Array values + +Array values can be declared with the `#[]` syntax. + +```tsp +const users = #["Bob", "Frank"]; +``` + +### `const` + +Const are the value world equivalent of `alias` but also allows you to specify a type + +```tsp +const name = "Bob"; +const name: string = "Bob"; +``` + +### Scalar constructors + +Scalars also needs to be able to define values. For scalars that don't extend a base type like `string`, `number` or `boolean` which have literal syntax you can define a constructor. + +```tsp +scalar ipV4 { + init fromInt(value: int32); +} +const ip: ipV4 = ipV4.fromInt(3232235776); +``` + +[See values doc for more info](https://typespec.io/docs/language-basics/values) + +## Deprecations + +### @typespec/compiler + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Using a tuple type as a value is deprecated. Tuple types in contexts where values are expected must be updated to be array values instead. A codefix is provided to automatically convert tuple types into array values. + +```tsp +model Test { + // Deprecated + values: string[] = ["a", "b", "c"]; + + // Correct + values: string[] = #["a", "b", "c"]; +} +``` + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Using a model type as a value is deprecated. Model types in contexts where values are expected must be updated to be object values instead. A codefix is provided to automatically convert model types into object values. + +```tsp +model Test { + // Deprecated + user: { + name: string; + } = { + name: "System"; + }; + + // Correct + user: { + name: string; + } = #{ name: "System" }; +} +``` + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Decorator API: Legacy marshalling logic + +With the introduction of values, the decorator marshalling behavior has changed in some cases. This behavior is opt-in by setting the `valueMarshalling` package flag to `"new"`, but will be the default behavior in future versions. It is strongly recommended to adopt this new behavior as soon as possible. + +Example: + +```tsp +extern dec multipleOf(target: numeric | Reflection.ModelProperty, value: valueof numeric); +``` + +Will now emit a deprecated warning because `value` is of type `valueof string` which would marshall to `Numeric` under the new logic but as `number` previously. + +To opt-in you can add the following to your library js/ts files. + +```ts +export const $flags = definePackageFlags({ + decoratorArgMarshalling: "new", +}); +``` + +## Features + +### @typespec/compiler + +- [#3280](https://github.com/microsoft/typespec/pull/3280) Support completion for Model with extended properties + + Example + + ```tsp + model Device { + name: string; + description: string; + } + + model Phone extends Device { + ┆ + } | [name] + | [description] + ``` + +- [#3280](https://github.com/microsoft/typespec/pull/3280) Support completion for object values and model expression properties. + + Example + + ```tsp + model User { + name: string; + age: int32; + address: string; + } + + const user: User = #{name: "Bob", ┆} + | [age] + | [address] + ``` + +- [#3375](https://github.com/microsoft/typespec/pull/3375) Allow `@` to be escaped in doc comment with `\` +- [#3022](https://github.com/microsoft/typespec/pull/3022) Add syntax for declaring values. [See docs](https://typespec.io/docs/language-basics/values). + +Object and array values + +```tsp +@dummy(#{ + name: "John", + age: 48, + address: #{ city: "London" } + aliases: #["Bob", "Frank"] +}) +``` + +Scalar constructors + +```tsp +scalar utcDateTime { + init fromISO(value: string); +} + +model DateRange { + minDate: utcDateTime = utcDateTime.fromISO("2024-02-15T18:36:03Z"); +} +``` + +- [#3527](https://github.com/microsoft/typespec/pull/3527) Add support for `@prop` doc comment tag to describe model properties +- [#3460](https://github.com/microsoft/typespec/pull/3460) Hide deprecated items from completion list +- [#3462](https://github.com/microsoft/typespec/pull/3462) Linter `all` rulesets is automatically created if not explicitly provided +- [#3533](https://github.com/microsoft/typespec/pull/3533) More logs and traces are added for diagnostic and troubleshooting in TypeSpec language server +- [#3422](https://github.com/microsoft/typespec/pull/3422) Formatter: Indent or dedent multiline strings to the current indentation + +### @typespec/http + +- [#3342](https://github.com/microsoft/typespec/pull/3342) Add new multipart handling. Using `@multipartBody` with `HttpPart`. See [multipart docs] for more information https://typespec.io/docs/next/libraries/http/multipart + + ```tsp + op upload( + @header contentType: "multipart/mixed", + @multipartBody body: { + name: HttpPart; + avatar: HttpPart[]; + }, + ): void; + ``` + +- [#3462](https://github.com/microsoft/typespec/pull/3462) Use new compiler automatic `all` ruleset instead of explicitly provided one + +### @typespec/openapi3 + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Add support for new object and array values as default values (e.g. `decimals: decimal[] = #[123, 456.7];`) + +### @typespec/html-program-viewer + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Add support for values + +### @typespec/json-schema + +- [#3557](https://github.com/microsoft/typespec/pull/3557) Add support for @oneOf decorator. + +### typespec-vs + +- [#3461](https://github.com/microsoft/typespec/pull/3461) Support Arm64 + +### typespec-vscode + +- [#3533](https://github.com/microsoft/typespec/pull/3533) Enhance logging and trace + +1. Support "Developer: Set Log Level..." command to filter logs in TypeSpec output channel +2. Add "typespecLanguageServer.trace.server" config for whether and how to send the traces from TypeSpec language server to client. (It still depends on client to decide whether to show these traces based on the configured Log Level.) +3. More logs and traces are added for diagnostic and troubleshooting + +- [#3385](https://github.com/microsoft/typespec/pull/3385) Add 'TypeSpec: Show Output Channel' command in VSCode extension + +## Bug Fixes + +### @typespec/compiler + +- [#3399](https://github.com/microsoft/typespec/pull/3399) Preserve leading whitespace in fenced blocks in doc comments +- [#3522](https://github.com/microsoft/typespec/pull/3522) Fix EINVAL error when running `tsp code install` +- [#3371](https://github.com/microsoft/typespec/pull/3371) Numeric not handling trailing zeros and causing freeze(e.g. `const a = 100.0`) +- [#3451](https://github.com/microsoft/typespec/pull/3451) Emitter framework: fix losing context when referencing circular types +- [#3517](https://github.com/microsoft/typespec/pull/3517) Fix application of `@param` doc tag on operation create with `op is` to override upstream doc +- [#3488](https://github.com/microsoft/typespec/pull/3488) Add `PickProperties` type to dynamically select a subset of a model + +### @typespec/http + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Update Flow Template to make use of the new array values + +### @typespec/versioning + +- [#3292](https://github.com/microsoft/typespec/pull/3292) Add `@madeRequired` decorator +- [#3022](https://github.com/microsoft/typespec/pull/3022) Update to support new value types +- [#3409](https://github.com/microsoft/typespec/pull/3409) Using `@removed` on member types and `@added` on containing type could result in errors +- [#3255](https://github.com/microsoft/typespec/pull/3255) If a property were marked with @added on a later version, the logic that said it was originally added on the first version was erroneously removed, resulting in incorrect projections. + +### @typespec/rest + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Update types to support new values in TypeSpec + +### @typespec/openapi3 + +- [#3342](https://github.com/microsoft/typespec/pull/3342) Add support for new multipart constructs in http library + +### @typespec/protobuf + +- [#3022](https://github.com/microsoft/typespec/pull/3022) Update to support new value types + +### @typespec/json-schema + +- [#3398](https://github.com/microsoft/typespec/pull/3398) Fix decorators application for union variants +- [#3022](https://github.com/microsoft/typespec/pull/3022) Update to support new value types +- [#3430](https://github.com/microsoft/typespec/pull/3430) The emitted JSON Schema now doesn't make root schemas for TypeSpec types which do not have the @jsonSchema decorator or are contained in a namespace with that decorator. Instead, such schemas are put into the $defs of any root schema which references them, and are referenced using JSON Pointers. From 9050d9425a6a81dc64c655ca01236fb0cccb57b6 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 11 Jun 2024 13:41:06 -0700 Subject: [PATCH 2/4] add protobuf fix --- docs/release-notes/release-2024-06-10.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/release-notes/release-2024-06-10.md b/docs/release-notes/release-2024-06-10.md index 3106c69cf41..83a699e83ed 100644 --- a/docs/release-notes/release-2024-06-10.md +++ b/docs/release-notes/release-2024-06-10.md @@ -248,6 +248,8 @@ model DateRange { ### @typespec/protobuf - [#3022](https://github.com/microsoft/typespec/pull/3022) Update to support new value types +- [#3561](https://github.com/microsoft/typespec/pull/3561) Corrected cross-package reference behavior in some buggy cases. +- ### @typespec/json-schema From b21e74c556232b7adc2c5b6607197965b585ede4 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 11 Jun 2024 16:12:23 -0700 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Brian Terlson --- docs/release-notes/release-2024-06-10.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/release-notes/release-2024-06-10.md b/docs/release-notes/release-2024-06-10.md index 83a699e83ed..19ddda30704 100644 --- a/docs/release-notes/release-2024-06-10.md +++ b/docs/release-notes/release-2024-06-10.md @@ -9,9 +9,9 @@ This release contains deprecations ## Values In TypeSpec Decorators often expect some sort of configuration to be passed as an argument. In version `0.51.0` we introduced the `valueof` keyword to constrain a decorator or template parameter to be a value, however this was limited to string, numeric and boolean values. -When dealing with more complex decorators or free form data one had to use a model type to represent the data. This required a lot of manual validation in the decorator implementation and introduce a lot of potential issues(Passing a subtype like a union instead of a model) +When dealing with more complex decorators or free form data, one had to use a model type to represent the data. Unfortunately, this approach was difficult for decorator authors to handle reliably and required somewhat sophisticated validation to avoid some common pitfalls that couldn't be prevented through type system constraints. -In this release we introduce a whole new world to TypeSpec, values. This include new syntax for declaring object and array values, scalar constructors, `const`. +In this release we introduce a new concept to TypeSpec: values. This includes new syntax for declaring object and array values, scalar constructors, and `const` declarations. ### Object values @@ -31,7 +31,7 @@ const users = #["Bob", "Frank"]; ### `const` -Const are the value world equivalent of `alias` but also allows you to specify a type +Const declares a variable that holds a value, and can optionally specify a type. ```tsp const name = "Bob"; @@ -40,7 +40,7 @@ const name: string = "Bob"; ### Scalar constructors -Scalars also needs to be able to define values. For scalars that don't extend a base type like `string`, `number` or `boolean` which have literal syntax you can define a constructor. +Scalars can define custom values with scalar value constructors. Scalars which don't extend a base type like `string`, `number` or `boolean` can define a constructor. ```tsp scalar ipV4 { @@ -175,7 +175,7 @@ model DateRange { ### @typespec/http -- [#3342](https://github.com/microsoft/typespec/pull/3342) Add new multipart handling. Using `@multipartBody` with `HttpPart`. See [multipart docs] for more information https://typespec.io/docs/next/libraries/http/multipart +- [#3342](https://github.com/microsoft/typespec/pull/3342) Add new multipart handling. Using `@multipartBody` with `HttpPart`. See [multipart docs](https://typespec.io/docs/next/libraries/http/multipart) for more information. ```tsp op upload( From afb7921ec2bdf84e73026478d1c50bdea012eb3d Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 13 Jun 2024 07:54:05 -0700 Subject: [PATCH 4/4] fix in changelog.md too --- .chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md | 2 +- docs/release-notes/release-2024-06-10.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md b/.chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md index a082e13d3e5..0ef637f7dbd 100644 --- a/.chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md +++ b/.chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md @@ -5,7 +5,7 @@ packages: - "@typespec/http" --- -Add new multipart handling. Using `@multipartBody` with `HttpPart`. See [multipart docs] for more information https://typespec.io/docs/next/libraries/http/multipart +Add new multipart handling. Using `@multipartBody` with `HttpPart`. See [multipart docs](https://typespec.io/docs/next/libraries/http/multipart) for more information. ```tsp op upload(@header contentType: "multipart/mixed", @multipartBody body: { diff --git a/docs/release-notes/release-2024-06-10.md b/docs/release-notes/release-2024-06-10.md index 19ddda30704..5e37300aee7 100644 --- a/docs/release-notes/release-2024-06-10.md +++ b/docs/release-notes/release-2024-06-10.md @@ -244,6 +244,7 @@ model DateRange { ### @typespec/openapi3 - [#3342](https://github.com/microsoft/typespec/pull/3342) Add support for new multipart constructs in http library +- [#3574](https://github.com/microsoft/typespec/pull/3574) Emit diagnostic when an invalid type is used as a property instead of crashing. ### @typespec/protobuf