Feature: valueof for string, numeric and boolean literals

[timotheeguerin]

fix #1745 Add support for valueof

Waiting on:

• To be merged right before end of sprint to not block flow due to new syntax
• Breaking change review [TCGC] Add test for nested paging cases Azure/typespec-azure#2977

Azure PR Azure/typespec-azure#3061

Deprecation

Typespec

Decorators have updated to use valueof for their types when expecting a string, numeric or boolean value.

If using the decorator directly this is NOT breaking and will continue to work as expected.
If using the decorator via a template parameter the template constraint will need to be updated from string to valueof string (Similar for numeric and boolean types)

// Before
model Foo {
  @doc("My doc") name: string;
}

// After - this is the same, not breaking
model Foo {
  @doc("My doc") name: string;
}

// Before
model Foo<TDoc extends string> {
  @doc(TDoc) name: string;
}

// After
model Foo<TDoc extends valueof string> {
  @doc(TDoc) name: string;
}

The old way is still ok but will emit a deprecation warning.

Breaking change

Decorator API

Part of adding valueof is making the auto conversion of Typespec types more consistent.
A decorator that is not specifying a valueof type for its parameter will be receiving the exact type. To get the converted string, number or boolean valueof must be used

Type of parmeter	TS type before	Ts Type now
string	string	StringLiteral | Scalar
int32	number	NumericLiteral | Scalar
int8	number	NumericLiteral | Scalar
float32	number	NumericLiteral | Scalar
boolean	boolean	BooleanLiteral | Scalar
boolean	boolean	BooleanLiteral | Scalar
valueof string		string
valueof int32		number
valueof float64		number
valueof boolean		boolean

Example migration

// Before
extern dec doc(target: unknown, value: string);

// After
extern dec doc(target: unknown, value: valueof string);

Example mapping extern dec to typescript signature

Cadl	Ts Signature
dec foo(target, value: string)	export function $foo( context, target, value: StringLiteral | TemplateLiteral | Scalar ) {}
dec foo(target, value: valueof string)	export function $foo(context, target, value: string) {}
dec foo(target, value: TemplateLiteral)	export function $foo(context, target, value: TemplateLiteral) {}

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/1877/

Website: https://cadlwebsite.z1.web.core.windows.net/prs/1877/

[MaryGao]

@timotheeguerin We have a test failed (ci link) with below error, could you take a look?

Here is our test case link, we have a usage for @extension("x-ms-skip-url-encoding", true).

TypeError: key.startsWith is not a function
    at isOpenAPIExtensionKey (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+openapi@0.44.0_5dsz42v7r7ljwzbfu2zuum3liq/node_modules/@typespec/openapi/src/decorators.ts:75:14)
    at $extension (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+openapi@0.44.0_5dsz42v7r7ljwzbfu2zuum3liq/node_modules/@typespec/openapi/src/decorators.ts:42:8)
    at applyDecoratorToType (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:5480:5)
    at finishTypeForProgramAndChecker (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:5456:7)
    at finishType (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:3705:12)
    at checkModelProperty (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:2993:7)
    at checkModelProperties (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:2481:25)
    at checkModelStatement (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:2393:5)
    at checkModel (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:2324:14)
    at getTypeForNode (file:///home/vsts/work/1/s/common/temp/node_modules/.pnpm/@typespec+compiler@0.45.0-dev.26/node_modules/@typespec/compiler/core/checker.ts:615:16)
Error: TypeSpec compiler v0.44.0

[timotheeguerin]

Are you using all the latest dev version or stable version?

[MaryGao]

This happens in our nightly build which always refer the latest dev to check any breaking.

[timotheeguerin]

Do you have @typespec/openapi as an explicit dependency in your package.json? I think it it is not the tool will not bump it and due to how npm resolve things it will not use the dev version.

We just released the stable versions, if you can repro with 0.45.0(core) and 0.31.0(azure) then it is probably an issue but from the error I am pretty sure it is a mismatch of deps

[timotheeguerin]

I can't repro with your spec in the playground

[MaryGao]

Thanks for the info! Let me deep dive if any dependency mismatch.