Value world, object, tuple literals, const

[timotheeguerin]

resolves #2046 Playround

Add the new syntax for object literals using #{. For this first version an object literal can only contain other object literal and other literals(string, number, boolean))

Values axioms

1. alias always produces a type. If you attempt to alias a value, you get an error.
2. A string template produces a string template type if all substitutions are types, and a value if all substitutions are numeric, boolean, or string values. A mixture of types and values is an error.
3. The string literal syntax always results in a string literal type
4. A string literal type may be passed as a string value when the signature expects a value. When the signature expects either a string literal type or a string value, it is passed as a string value.
5. A string template type can be passed as a string value when all its substitutions are string literal types.

Breaking change

Removal of the ValueType replacement with MixedConstraint

This shouldn't affect anyone as you were only exposed to this if you digged into the template parameter and looked at the constraint

Deprecation

Using a tuple instead of a tuple literal

• ✅ still work
• emit a warning

• provide a codefix

Using a model expression instead of an object literal

This technically didn't work before(different from above where tuple was used as a value) but allow this will allow us to convert most of our decorators to use valueof without being breaking

Old decorator marshalling

If a library had a decorator with valueof one of those types numeric, int64, uint64, integer, float, decimal, decimal128, null it used to marshall those as JS number and NullType for null. With the introduction of values we have a new marshalling logic which will marshall those numeric types as Numeric and the others will remain numbers. null will also get marshalled as null.

For now this is an opt-in behavior with a warning on decorators not opt-in having a parameter with a constraint from the list above.

Example:

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

export const $flags = defineModuleFlags({
  decoratorArgMarshalling: "value",
});

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/html-program-viewer
• ✅ @typespec/http
• ✅ @typespec/json-schema
• ✅ @typespec/openapi3
• ✅ @typespec/protobuf
• ✅ @typespec/rest
• ✅ @typespec/versioning

Show changes

@typespec/compiler - deprecation ✏️

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"];,>

@typespec/compiler - deprecation ✏️

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"};,>

@typespec/compiler - feature ✏️

Add syntax for declaring values. See docs.,> ,> 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");,> },>

@typespec/json-schema - fix ✏️

Update to support new value types

@typespec/protobuf - fix ✏️

Update to support new value types

@typespec/versioning - fix ✏️

Update to support new value types

@typespec/compiler - deprecation ✏️

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",,> });,>

@typespec/openapi3 - feature ✏️

Add support for new object and array values as default values (e.g. decimals: decimal[] = #[123, 456.7];)

@typespec/rest - fix ✏️

Update types to support new values in TypeSpec

@typespec/html-program-viewer - feature ✏️

Add support for values

@typespec/http - fix ✏️

Update Flow Template to make use of the new array values

[azure-sdk]

You can try these changes at https://cadlplayground.z22.web.core.windows.net/prs/3022/

Check the website changes at https://tspwebsitepr.z22.web.core.windows.net/prs/3022/

[MaryGao]

@timotheeguerin that's interesting, do we take this as breaking change?

Our code would fail compile due to this change. https://dev.azure.com/azure-sdk/public/_build/results?buildId=3820465&view=logs&j=830f3c89-f0a6-536d-4907-0d5f5b592ed8&t=e0231fa7-1c00-50a2-4f06-772d628498b2&l=209

[qiaozha]

widen the union in output is a breaking, in this case that union type is being used by us, it's an output, therefore it's a breaking. as inspired by the point 6 of @xirzec 's summary of what should be considered as breaking Azure/azure-sdk-for-js#22983 (comment)