Add strict type checking for registerRouteHandlersByTag

Generate ServerForTag interfaces and function overloads to enforce that only operations with the specified tag can be passed to registerRouteHandlersByTag

Co-authored-by: jasonblanchard <1238532+jasonblanchard@users.noreply.github.com>

Author: Copilot

examples/docs/gen/server.ts

@@ -75,6 +75,12 @@ export function registerRouteHandlers<Req, Res>(server: Server<Req, Res>): Route
 
 export type Tag = null;
 
+export interface ServerForUntagged<Req = unknown, Res = unknown> {
+  makePetSpeak?: (args: MakePetSpeakArgs<Req, Res>) => MakePetSpeakResult;
+  uhoh?: (args: UhohArgs<Req, Res>) => UhohResult;
+}
+
+export function registerRouteHandlersByTag<Req, Res>(tag: null, server: Partial<ServerForUntagged<Req, Res>>): Route[];
 export function registerRouteHandlersByTag<Req, Res>(tag: Tag, server: Partial<Server<Req, Res>>): Route[] {
   const routes: Route[] = [];
 

examples/kitchensink/gen/server.ts

@@ -253,6 +253,16 @@ export function registerRouteHandlers<Req, Res>(server: Server<Req, Res>): Route
 
 export type Tag = null;
 
+export interface ServerForUntagged<Req = unknown, Res = unknown> {
+  listPets?: (args: ListPetsArgs<Req, Res>) => ListPetsResult;
+  getPetById?: (args: GetPetByIdArgs<Req, Res>) => GetPetByIdResult;
+  updatePetWithForm?: (args: UpdatePetWithFormArgs<Req, Res>) => UpdatePetWithFormResult;
+  mixedContentTypes?: (args: MixedContentTypesArgs<Req, Res>) => MixedContentTypesResult;
+  getPetImage?: (args: GetPetImageArgs<Req, Res>) => GetPetImageResult;
+  getPetWebpage?: (args: GetPetWebpageArgs<Req, Res>) => GetPetWebpageResult;
+}
+
+export function registerRouteHandlersByTag<Req, Res>(tag: null, server: Partial<ServerForUntagged<Req, Res>>): Route[];
 export function registerRouteHandlersByTag<Req, Res>(tag: Tag, server: Partial<Server<Req, Res>>): Route[] {
   const routes: Route[] = [];
 

examples/petstore/gen/server.ts

@@ -746,6 +746,37 @@ export function registerRouteHandlers<Req, Res>(server: Server<Req, Res>): Route
 
 export type Tag = "pet" | "store" | "user";
 
+export interface ServerForPet<Req = unknown, Res = unknown> {
+  updatePet?: (args: UpdatePetArgs<Req, Res>) => UpdatePetResult;
+  addPet?: (args: AddPetArgs<Req, Res>) => AddPetResult;
+  findPetsByStatus?: (args: FindPetsByStatusArgs<Req, Res>) => FindPetsByStatusResult;
+  findPetsByTags?: (args: FindPetsByTagsArgs<Req, Res>) => FindPetsByTagsResult;
+  getPetById?: (args: GetPetByIdArgs<Req, Res>) => GetPetByIdResult;
+  updatePetWithForm?: (args: UpdatePetWithFormArgs<Req, Res>) => UpdatePetWithFormResult;
+  deletePet?: (args: DeletePetArgs<Req, Res>) => DeletePetResult;
+  uploadFile?: (args: UploadFileArgs<Req, Res>) => UploadFileResult;
+}
+
+export interface ServerForStore<Req = unknown, Res = unknown> {
+  getInventory?: (args: GetInventoryArgs<Req, Res>) => GetInventoryResult;
+  placeOrder?: (args: PlaceOrderArgs<Req, Res>) => PlaceOrderResult;
+  getOrderById?: (args: GetOrderByIdArgs<Req, Res>) => GetOrderByIdResult;
+  deleteOrder?: (args: DeleteOrderArgs<Req, Res>) => DeleteOrderResult;
+}
+
+export interface ServerForUser<Req = unknown, Res = unknown> {
+  createUser?: (args: CreateUserArgs<Req, Res>) => CreateUserResult;
+  createUsersWithListInput?: (args: CreateUsersWithListInputArgs<Req, Res>) => CreateUsersWithListInputResult;
+  loginUser?: (args: LoginUserArgs<Req, Res>) => LoginUserResult;
+  logoutUser?: (args: LogoutUserArgs<Req, Res>) => LogoutUserResult;
+  getUserByName?: (args: GetUserByNameArgs<Req, Res>) => GetUserByNameResult;
+  updateUser?: (args: UpdateUserArgs<Req, Res>) => UpdateUserResult;
+  deleteUser?: (args: DeleteUserArgs<Req, Res>) => DeleteUserResult;
+}
+
+export function registerRouteHandlersByTag<Req, Res>(tag: "pet", server: Partial<ServerForPet<Req, Res>>): Route[];
+export function registerRouteHandlersByTag<Req, Res>(tag: "store", server: Partial<ServerForStore<Req, Res>>): Route[];
+export function registerRouteHandlersByTag<Req, Res>(tag: "user", server: Partial<ServerForUser<Req, Res>>): Route[];
 export function registerRouteHandlersByTag<Req, Res>(tag: Tag, server: Partial<Server<Req, Res>>): Route[] {
   const routes: Route[] = [];
 

packages/openapi-typescript-server/bin/cli/index.cjs

@@ -515,7 +515,29 @@ function generate(spec, types, outpath, version) {
       });
     }
   });
-  sourceFile.addFunction({
+  Object.entries(tagToOperations).forEach(([tag, operations]) => {
+    const interfaceName = tag === "null" ? "ServerForUntagged" : `ServerFor${capitalize(tag)}`;
+    const tagInterface = sourceFile.addInterface({
+      name: interfaceName,
+      isExported: true,
+      typeParameters: [
+        { name: "Req", default: "unknown" },
+        { name: "Res", default: "unknown" }
+      ]
+    });
+    operations.forEach((operationId) => {
+      const op = operationsById[operationId];
+      if (op) {
+        tagInterface.addProperty({
+          name: operationId,
+          type: `(args: ${op.args}<Req, Res>) => ${op.result}`,
+          hasQuestionToken: true
+          // Make it optional since it's a partial implementation
+        });
+      }
+    });
+  });
+  const registerByTagFunc = sourceFile.addFunction({
     name: "registerRouteHandlersByTag",
     isExported: true,
     parameters: [
@@ -554,6 +576,18 @@ function generate(spec, types, outpath, version) {
       writer.writeLine("return routes;");
     }
   });
+  Object.entries(tagToOperations).forEach(([tag, _operations]) => {
+    const tagValue = tag === "null" ? "null" : `"${tag}"`;
+    const interfaceName = tag === "null" ? "ServerForUntagged" : `ServerFor${capitalize(tag)}`;
+    registerByTagFunc.addOverload({
+      parameters: [
+        { name: "tag", type: tagValue },
+        { name: "server", type: `Partial<${interfaceName}<Req, Res>>` }
+      ],
+      typeParameters: [{ name: "Req" }, { name: "Res" }],
+      returnType: "Route[]"
+    });
+  });
   sourceFile.insertText(
     0,
     `/**

packages/openapi-typescript-server/src/cli/generate.ts

@@ -275,8 +275,34 @@ export default function generate(
     }
   });
 
-  // Generate registerRouteHandlersByTag function
-  sourceFile.addFunction({
+  // Generate a ServerForTag interface for each tag
+  Object.entries(tagToOperations).forEach(([tag, operations]) => {
+    const interfaceName =
+      tag === "null" ? "ServerForUntagged" : `ServerFor${capitalize(tag)}`;
+    const tagInterface = sourceFile.addInterface({
+      name: interfaceName,
+      isExported: true,
+      typeParameters: [
+        { name: "Req", default: "unknown" },
+        { name: "Res", default: "unknown" },
+      ],
+    });
+
+    // Add only operations associated with this tag
+    operations.forEach((operationId) => {
+      const op = operationsById[operationId];
+      if (op) {
+        tagInterface.addProperty({
+          name: operationId,
+          type: `(args: ${op.args}<Req, Res>) => ${op.result}`,
+          hasQuestionToken: true, // Make it optional since it's a partial implementation
+        });
+      }
+    });
+  });
+
+  // Generate registerRouteHandlersByTag function with overloads
+  const registerByTagFunc = sourceFile.addFunction({
     name: "registerRouteHandlersByTag",
     isExported: true,
     parameters: [
@@ -323,6 +349,22 @@ export default function generate(
     },
   });
 
+  // Add overload signatures for each tag
+  Object.entries(tagToOperations).forEach(([tag, _operations]) => {
+    const tagValue = tag === "null" ? "null" : `"${tag}"`;
+    const interfaceName =
+      tag === "null" ? "ServerForUntagged" : `ServerFor${capitalize(tag)}`;
+
+    registerByTagFunc.addOverload({
+      parameters: [
+        { name: "tag", type: tagValue },
+        { name: "server", type: `Partial<${interfaceName}<Req, Res>>` },
+      ],
+      typeParameters: [{ name: "Req" }, { name: "Res" }],
+      returnType: "Route[]",
+    });
+  });
+
   sourceFile.insertText(
     0,
     `/**