Feature: valueof for string, numeric and boolean literals (microsoft#1877)

Author: timotheeguerin

common/changes/@typespec/compiler/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,20 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Added new keyword `valueof` designed to request for a value type in a decorator parameter.",
+      "type": "none"
+    },
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "**BREAKING** Decorator API will not be marshalling values unless the parameter type is using `valueof`. `extern dec foo(target, value: string)` should be changed to `extern dec foo(target, value: valueof string)`.",
+      "type": "none"
+    },
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "**DEPRECATION** To make transition to valueof smoother if using a template parameter inside a decorator that is now using valueof the existing parmater constraint will still be compatible but emit a warning.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/http/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "Update decorators to use `valueof`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

common/changes/@typespec/openapi/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi",
+      "comment": "Update decorators to use `valueof`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi"
+}

common/changes/@typespec/protobuf/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/protobuf",
+      "comment": "Update decorators to use `valueof`",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@typespec/protobuf"
+}

common/changes/@typespec/rest/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "Update decorators to use `valueof`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}

common/changes/@typespec/versioning/feature-valueof_2023-05-24-17-11.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/versioning",
+      "comment": "Update decorators to use `valueof`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/versioning"
+}

docs/extending-typespec/create-decorators.md

@@ -40,15 +40,37 @@ extern dec track(target: Model | Enum);
 A decorator parameter can be marked optional using `?`
 
 ```typespec
-extern dec track(target: Model | Enum, name?: StringLiteral);
+extern dec track(target: Model | Enum, name?: valueof string);
 ```
 
 ### Rest parameters
 
 A decorator's last parameter can be prefixed with `...` to collect all the remaining arguments. The type of that parameter must be an `array expression`
 
 ```typespec
-extern dec track(target: Model | Enum, ...names: StringLiteral[]);
+extern dec track(target: Model | Enum, ...names: valueof string[]);
+```
+
+## Ask for a value type
+
+It is common that decorators parameter will expect a value(e.g. a string or a number). However just using `: string` as the type will also allow a user of the decorator to pass `string` itself or a custom scalar extending string as well as union of strings.
+Instead the decorator can use `valueof <T>` to specify that it is expecting a value of that kind.
+
+| Example           | Description      |
+| ----------------- | ---------------- |
+| `valueof string`  | Expect a string  |
+| `valueof float64` | Expect a float   |
+| `valueof int32`   | Expect a number  |
+| `valueof boolean` | Expect a boolean |
+
+```tsp
+extern dec tag(target: unknown, value: valueof string);
+
+// bad
+@tag(string)
+
+// good
+@tag("This is the tag name")
 ```
 
 ## Implement the decorator in JS
@@ -63,7 +85,7 @@ Decorators can be implemented in JavaScript by prefixing the function name with
 // model.ts
 import type { DecoratorContext, Type } from "@typespec/compiler";
 
-export function $logType(context: DecoratorContext, target: Type, name: string) {
+export function $logType(context: DecoratorContext, target: Type, name: valueof string) {
   console.log(name + ": " + targetType.kind);
 }
 ```
@@ -92,13 +114,13 @@ model Dog {
 
 ### Decorator parameter marshalling
 
-For certain TypeSpec types(Literal types) the decorator do not receive the actual type but a marshalled value. This is to simplify the most common cases.
+For certain TypeSpec types(Literal types) the decorator do not receive the actual type but a marshalled value if the decorator parmaeter type is a `valueof`. This is to simplify the most common cases.
 
-| TypeSpec Type    | Marshalled value in JS |
-| ---------------- | ---------------------- |
-| `StringLiteral`  | `string`               |
-| `NumericLiteral` | `number`               |
-| `BooleanLiteral` | `boolean`              |
+| TypeSpec Type     | Marshalled value in JS |
+| ----------------- | ---------------------- |
+| `valueof string`  | `string`               |
+| `valueof numeric` | `number`               |
+| `valueof boolean` | `boolean`              |
 
 for all the other types they are not transformed.