Deprecate @list decorator in favor of rest's @listsResource

Author: daviwil

common/changes/@typespec/compiler/move-list-decorator_2023-06-20-11-35.json

@@ -0,0 +1,20 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Deprecate `@list` decorator in favor of `@listsResource` in `@typespec/rest`",
+      "type": "none"
+    },
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Deprecate `isListOperation` function in favor of `isListOperation` in `@typespec/rest`",
+      "type": "none"
+    },
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Deprecate `getListOperationType` function",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/library-linter/move-list-decorator_2023-06-20-11-35.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/library-linter",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/library-linter"
+}

common/changes/@typespec/rest/move-list-decorator_2023-06-20-11-35.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "Add `isListOperation` function migrated from `@typespec/compiler`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}

docs/standard-library/built-in-decorators.md

@@ -305,6 +305,25 @@ Invalid,
 ```
 
 
+### `@list` {#@list}
+
+Mark this operation as a `list` operation for resource types.
+
+```typespec
+@list(listedType?: Model)
+```
+
+#### Target
+
+`Operation`
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| listedType | `Model` | Optional type of the items in the list. |
+
+
+
 ### `@maxItems` {#@maxItems}
 
 Specify the maximum number of items this array should have.

packages/compiler/lib/decorators.tsp

@@ -234,6 +234,14 @@ extern dec maxValueExclusive(target: numeric | ModelProperty, value: valueof num
  */
 extern dec secret(target: string | ModelProperty);
 
+/**
+ * Mark this operation as a `list` operation for resource types.
+ * @deprecated Use the `listsResource` decorator in `@typespec/rest` instead.
+ * @param listedType Optional type of the items in the list.
+ */
+@deprecated("Use the `listsResource` decorator in `@typespec/rest` instead.")
+extern dec list(target: Operation, listedType?: Model);
+
 /**
  * Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element.
  * @param tag Tag value

packages/compiler/src/lib/decorators.ts

@@ -774,6 +774,9 @@ export function $withoutDefaultValues(context: DecoratorContext, target: Model)
 
 const listPropertiesKey = createStateSymbol("listProperties");
 
+/**
+ * @deprecated Use the `listsResource` decorator in `@typespec/rest` instead.
+ */
 export function $list(context: DecoratorContext, target: Operation, listedType?: Type) {
   if (listedType && listedType.kind === "TemplateParameter") {
     // Silently return because this is probably being used in a templated interface
@@ -790,10 +793,16 @@ export function $list(context: DecoratorContext, target: Operation, listedType?:
   context.program.stateMap(listPropertiesKey).set(target, listedType);
 }
 
+/**
+ * @deprecated This function is unused and will be removed in a future release.
+ */
 export function getListOperationType(program: Program, target: Type): Model | undefined {
   return program.stateMap(listPropertiesKey).get(target);
 }
 
+/**
+ * @deprecated Use `isListOperation` in `@typespec/rest` instead.
+ */
 export function isListOperation(program: Program, target: Operation): boolean {
   // The type stored for the operation
   return program.stateMap(listPropertiesKey).has(target);

packages/library-linter/src/linter.ts

@@ -45,7 +45,6 @@ const excludeDecoratorSignature = new Set([
   "@docFromComment",
   "@indexer",
   "@test",
-  "@list", // TODO check if we actually need this one https://github.com/microsoft/typespec/issues/1978
   "@resourceTypeForKeyParam", // TODO check if we actually need this one https://github.com/microsoft/typespec/issues/1981
 ]);
 function validateDecoratorSignature(program: Program) {

packages/rest/src/rest.ts

@@ -421,6 +421,16 @@ export function $listsResource(context: DecoratorContext, entity: Operation, res
   setResourceOperation(context, entity, resourceType, "list");
 }
 
+/**
+ * Returns `true` if the given operation is marked as a list operation.
+ * @param program the TypeSpec program
+ * @param target the target operation
+ */
+export function isListOperation(program: Program, target: Operation): boolean {
+  // Is the given operation a `list` operation?
+  return getResourceOperation(program, target)?.operation === "list";
+}
+
 function lowerCaseFirstChar(str: string): string {
   return str[0].toLocaleLowerCase() + str.substring(1);
 }

packages/rest/test/routes.test.ts

@@ -118,7 +118,7 @@ describe("rest: routes", () => {
         @autoRoute
         interface SubInterface {
           @get
-          @list(Subthing)
+          @listsResource(Subthing)
           @segmentOf(Subthing)
           GetSubthings(...KeysOf<Thing>): string;