[compiler] Named instantiation of template arguments

common/changes/@typespec/compiler/compiler-named-template-params_2023-10-10-02-34.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Added support for named template arguments (#2340)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

docs/language-basics/templates.md

@@ -5,11 +5,11 @@ title: Templates
 
 # Templates
 
-It is often useful to let the users of a model fill in certain details. Templates enable this pattern. Similar to generics found in other languages, model templates declare template parameters that users provide when referencing the type.
+It is often useful to let the users of a model fill in certain details. Templates enable this pattern. Similar to generics found in other languages, model templates declare template arguments that users provide when referencing the type.
 
 Templates can be used on:
 
-- [alias](./alias.md)
+- [aliases](./alias.md)
 - [models](./models.md)
 - [operations](./operations.md)
 - [interfaces](./interfaces.md)
@@ -27,7 +27,7 @@ model DogPage {
 
 ## Default values
 
-A template parameter can be given a default value with `= <value>`.
+A template argument can be given a default value with `= <value>`.
 
 ```typespec
 model Page<T = string> {
@@ -36,33 +36,75 @@ model Page<T = string> {
 }
 ```
 
-## Parameter constraints
+## Argument constraints
 
-Template parameter can provide a constraint using the `extends` keyword. See [type relations](./type-relations.md) documentation for details on how validation works.
+Template arguments can provide a constraint using the `extends` keyword. See the [type relations](./type-relations.md) documentation for details on how validation works.
 
 ```typespec
 alias Foo<T extends string> = T;
 ```
 
-now instantiating Foo with the wrong type will result in an error
+Now, instantiating Foo with a type that does not satisfy the constraint `string` will result in an error:
 
 ```typespec
 alias Bar = Foo<123>;
                 ^ Type '123' is not assignable to type 'TypeSpec.string'
 ```
 
-Template constraints can be a model expression
+A template argument constraint can also be a model expression:
 
 ```typespec
 // Expect T to be a model with property name: string
 alias Foo<T extends {name: string}> = T;
 ```
 
-Template parameter default also need to respect the constraint
+Template argument defaults also need to respect the constraint:
 
 ```typespec
 alias Foo<T extends string = "Abc">  = T
 // Invalid
 alias Bar<T extends string = 123>  = T
                              ^ Type '123' is not assignable to type 'TypeSpec.string'
 ```
+
+Furthermore, all optional arguments must come at the end of the template. A required argument cannot follow an optional argument:
+
+```typespec
+// Invalid
+alias Foo<T extends string = "Abc", U> = ...;
+                                    ^ Required template parameters must not follow optional template parameters
+```
+
+## Named template arguments
+
+Template arguments may also be specified by name. In that case, they can be specified out of order and optional arguments may be omitted. This can be useful when dealing with templates that have many defaultable arguments:
+
+```typespec
+alias Test<T, U extends numeric = int32, V extends string = "example"> = ...;
+
+// Specify the argument V by name to skip argument U, since U is optional and we
+// are okay with its default
+alias Example1 = Test<unknown, V = "example1">;
+
+// Even all three arguments can be specified out of order
+alias Example2 = Test<
+  V = "example2",
+  T = unknown,
+  U = uint64
+>;
+```
+
+However, once a template argument is specified by name, all subsequent arguments must also be specified by name:
+
+```typespec
+// Invalid
+alias Example3 = Test<
+  V = "example3",
+  unknown,
+  ^^^^^^^ Positional template arguments cannot follow named arguments in the same argument list.
+>;
+```
+
+Since template arguments may be specified by name, the names of template arguments are part of the public API of a template. **Changing the name of a template argument may break existing specifications that use the template.**
+
+**Note**: Template arguments are evaluated in the order they are defined in the template _definition_, not the order in which they are written in the template _instance_. Most of the time, this should not matter, but may be important in some cases where evaluating a template argument may invoke decorators with side effects.