Improve spec resource composability and reusability with improved templates

Using some workarounds, the following features are now usable in Protobuf emitter:
- direct use of templated models without intermediaries
- operation templates
- interface templates

Author: Tomaszal

packages/spec/api/resource.tsp

@@ -4,9 +4,7 @@ import "../lib";
 
 import "./change.tsp";
 
-using TypeSpec.Protobuf;
 using TypeSpec.Reflection;
-using TypeSpec.Rest.Resource;
 
 namespace API.Resource;
 
@@ -37,30 +35,59 @@ model Change<Resource extends Model> {
   ...OptionalProperties<OmitKey<Resource>>;
 }
 
+interface CRUD<Resource extends Model>
+  extends List.Operation<Resource>,
+    Get.Operation<Resource>,
+    Create.Operation<Resource>,
+    Update.Operation<Resource>,
+    Delete.Operation<Resource> {}
+
 namespace List {
+  interface Operation<Resource extends Model> {
+    @useFriendlyName
+    @friendlyName("{name}List", Resource)
+    List(...Request<Resource>): Response<Resource>;
+  }
+
+  @move(Resource)
+  @friendlyName("{name}ListItem", Resource)
   @normalize(Resource)
   @withVisibility(Query.List)
   model Item<Resource extends Model> {
     ...Resource;
   }
 
-  model Request<Resource> {
+  @move(Resource)
+  @friendlyName("{name}ListRequest", Resource)
+  model Request<Resource extends Model> {
     ...ParentKeyOf<Resource>;
   }
 
+  @move(Resource)
+  @friendlyName("{name}ListResponse", Resource)
   @autoFields
   @normalize
-  model Response<Resource, Item = Resource> {
+  model Response<Resource extends Model, Item = List.Item<Resource>> {
     ...Request<Resource>;
     items: Item[];
   }
 }
 
 namespace Get {
-  model Request<Resource> {
+  interface Operation<Resource extends Model> {
+    @useFriendlyName
+    @friendlyName("{name}Get", Resource)
+    Get(...Request<Resource>): Response<Resource>;
+  }
+
+  @move(Resource)
+  @friendlyName("{name}GetRequest", Resource)
+  model Request<Resource extends Model> {
     ...KeyOf<Resource>;
   }
 
+  @move(Resource)
+  @friendlyName("{name}GetResponse", Resource)
   @normalize(Resource)
   @withVisibility(Query.Get)
   model Response<Resource extends Model> {
@@ -69,13 +96,23 @@ namespace Get {
 }
 
 namespace Create {
+  interface Operation<Resource extends Model> {
+    @useFriendlyName
+    @friendlyName("{name}Create", Resource)
+    Create(...Request<Resource>): Response<Resource>;
+  }
+
+  @move(Resource)
+  @friendlyName("{name}CreateRequest", Resource)
   @normalize(Resource)
   @withVisibility(Mutation.Create)
   model Request<Resource extends Model> {
     ...ParentKeyOf<Resource>;
     ...Resource;
   }
 
+  @move(Resource)
+  @friendlyName("{name}CreateResponse", Resource)
   @autoChange({
     $data: {
       kind: API.Change.SourceKind.MERGE,
@@ -98,13 +135,23 @@ namespace Create {
 }
 
 namespace Update {
+  interface Operation<Resource extends Model> {
+    @useFriendlyName
+    @friendlyName("{name}Update", Resource)
+    Update(...Request<Resource>): Response<Resource>;
+  }
+
+  @move(Resource)
+  @friendlyName("{name}UpdateRequest", Resource)
   @normalize(Resource)
   @withVisibility(Mutation.Update)
   model Request<Resource extends Model> {
     ...KeyOf<Resource>;
     ...OptionalProperties<OmitKey<Resource>>;
   }
 
+  @move(Resource)
+  @friendlyName("{name}UpdateResponse", Resource)
   @autoChange({
     kind: API.Change.ChangeKind.CHANGE_KIND_UPDATE,
     $data: {
@@ -118,11 +165,21 @@ namespace Update {
 }
 
 namespace Delete {
+  interface Operation<Resource extends Model> {
+    @useFriendlyName
+    @friendlyName("{name}Delete", Resource)
+    Delete(...Request<Resource>): Response<Resource>;
+  }
+
+  @move(Resource)
+  @friendlyName("{name}DeleteRequest", Resource)
   @normalize(Resource)
   model Request<Resource extends Model> {
     ...KeyOf<Resource>;
   }
 
+  @move(Resource)
+  @friendlyName("{name}DeleteResponse", Resource)
   @autoChange({
     kind: API.Change.ChangeKind.CHANGE_KIND_DELETE,
     $data: {

packages/spec/lib/decorators.js

@@ -1,11 +1,11 @@
-import { getKeyName } from '@typespec/compiler';
+import { getFriendlyName, getKeyName } from '@typespec/compiler';
 import { $field } from '@typespec/protobuf';
 import { getParentResource, getResourceTypeKey } from '@typespec/rest';
 import { Array, Hash, Number, Option, pipe, Record } from 'effect';
 
 import { $lib } from './lib.js';
 
-/** @import { DecoratorApplication, DecoratorContext, Model, ModelProperty, Type } from '@typespec/compiler' */
+/** @import { DecoratorApplication, DecoratorContext, Model, ModelProperty, Operation, Type } from '@typespec/compiler' */
 
 /**
  * @param {DecoratorContext} context
@@ -198,3 +198,20 @@ export function $autoChange(context, target, value) {
   const autoChangesMap = context.program.stateMap($lib.stateKeys.autoChanges);
   pipe(autoChangesMap.get(target) ?? [], Array.append(change), (_) => autoChangesMap.set(target, _));
 }
+
+/**
+ * @param {DecoratorContext} context
+ * @param {Model} target
+ * @param {Model} destination
+ */
+export function $move(context, target, destination) {
+  target.namespace = destination.namespace;
+}
+
+/**
+ * @param {DecoratorContext} context
+ * @param {Operation} target
+ */
+export function $useFriendlyName(context, target) {
+  target.name = getFriendlyName(context.program, target);
+}

packages/spec/lib/main.tsp

@@ -30,3 +30,12 @@ extern dec normalize(target: Model, base?: Model);
 extern dec normalKey(target: ModelProperty);
 
 extern dec autoChange(target: TypeSpec.Reflection.Model, change: API.Change.AutoChange);
+
+/** Move model to specified namespace. Useful for collocating templated models */
+extern dec move(target: Model, destination: Model);
+
+/**
+ * Replace name with friendly name. Useful for when friendly names are
+ * unsupported, f.e. operations in Protobuf emitter
+ */
+extern dec useFriendlyName(target: Operation);