Chore: improve function signatures (#512)

Combine some function params into one option object for better DX

Author: drwpow

src/transform/index.ts

@@ -34,14 +34,11 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
   // #/paths (V2 & V3)
   output += `export interface paths {\n`; // open paths
   if (schema.paths) {
-    output += transformPathsObj(
-      schema.paths,
-      {
-        operations,
-        parameters: (schema.components && schema.components.parameters) || schema.parameters,
-      },
-      version
-    );
+    output += transformPathsObj(schema.paths, {
+      operations,
+      globalParameters: (schema.components && schema.components.parameters) || schema.parameters,
+      version,
+    });
   }
   output += `}\n\n`; // close paths
 
@@ -112,11 +109,10 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
   if (Object.keys(operations).length) {
     Object.entries(operations).forEach(([operationId, operation]) => {
       if (operation.description) output += comment(operation.description); // handle comment
-      output += `  "${operationId}": {\n    ${transformOperationObj(
-        operation,
+      output += `  "${operationId}": {\n    ${transformOperationObj(operation, {
         version,
-        schema.components && schema.components.parameters
-      )}\n  }\n`;
+        globalParameters: (schema.components && schema.components.parameters) || schema.parameters,
+      })}\n  }\n`;
     });
   }
   output += `}\n`; // close operations

src/transform/operation.ts

@@ -5,13 +5,21 @@ import { transformSchemaObj } from "./schema";
 
 export function transformOperationObj(
   operation: OperationObject,
-  version: number,
-  globalParams?: Record<string, ParameterObject>
+  {
+    version,
+    globalParameters,
+  }: {
+    version: number;
+    globalParameters?: Record<string, ParameterObject>;
+  }
 ): string {
   let output = "";
 
   if (operation.parameters) {
-    output += `  parameters: {\n    ${transformParametersArray(operation.parameters, version, globalParams)}\n  }\n`;
+    output += `  parameters: {\n    ${transformParametersArray(operation.parameters, {
+      version,
+      globalParameters,
+    })}\n  }\n`;
   }
 
   if (operation.responses) {

src/transform/parameters.ts

@@ -3,18 +3,23 @@ import { comment } from "../utils";
 
 export function transformParametersArray(
   parameters: (ReferenceObject | ParameterObject)[],
-  version: number,
-  globalParams?: Record<string, ParameterObject>
+  {
+    version,
+    globalParameters,
+  }: {
+    version: number;
+    globalParameters?: Record<string, ParameterObject>;
+  }
 ): string {
   let output = "";
 
   // sort into map
   let mappedParams: Record<string, Record<string, ParameterObject>> = {};
   parameters.forEach((paramObj: any) => {
-    if (paramObj.$ref && globalParams) {
+    if (paramObj.$ref && globalParameters) {
       const paramName = paramObj.$ref.split("/").pop(); // take last segment
-      if (globalParams[paramName]) {
-        const reference = globalParams[paramName] as any;
+      if (globalParameters[paramName]) {
+        const reference = globalParameters[paramName] as any;
         if (!mappedParams[reference.in]) mappedParams[reference.in] = {};
         if (version === 2) {
           mappedParams[reference.in][reference.name || paramName] = {

src/transform/paths.ts

@@ -4,14 +4,14 @@ import { transformParametersArray } from "./parameters";
 
 interface TransformPathsObjOption {
   operations: Record<string, OperationObject>;
-  parameters: Record<string, ParameterObject>;
+  globalParameters: Record<string, ParameterObject>;
+  version: number;
 }
 
 /** Note: this needs to mutate objects passed in */
 export function transformPathsObj(
   paths: Record<string, PathItemObject>,
-  { operations, parameters }: TransformPathsObjOption,
-  version: number
+  { operations, globalParameters, version }: TransformPathsObjOption
 ): string {
   let output = "";
 
@@ -41,16 +41,15 @@ export function transformPathsObj(
       }
 
       // otherwise, inline operation
-      output += `    "${method}": {\n      ${transformOperationObj(operation, version, parameters)}\n    }\n`;
+      output += `    "${method}": {\n      ${transformOperationObj(operation, { version, globalParameters })}\n    }\n`;
     });
 
     // parameters
     if (pathItem.parameters) {
-      output += `    parameters: {\n      ${transformParametersArray(
-        pathItem.parameters,
+      output += `    parameters: {\n      ${transformParametersArray(pathItem.parameters, {
         version,
-        parameters
-      )}\n    }\n`;
+        globalParameters,
+      })}\n    }\n`;
     }
 
     output += `  }\n`; // close PathItem

tests/operation.test.ts

@@ -18,7 +18,7 @@ describe("requestBody", () => {
             },
           },
         },
-        3
+        { version: 3 }
       ).trim()
     ).toBe(`requestBody: {
     content: {
@@ -34,7 +34,7 @@ describe("requestBody", () => {
         {
           requestBody: { $ref: "#/components/requestBodies/Request" },
         },
-        3
+        { version: 3 }
       ).trim()
     ).toBe(`requestBody: components["requestBodies"]["Request"];`);
   });

tests/parameters.test.ts

@@ -19,7 +19,7 @@ describe.only("transformParametersArray()", () => {
             { in: "path", name: "three_d_secure", required: true, type: "string" },
             { in: "body", name: "payload", schema: { type: "string" } },
           ],
-          2
+          { version: 2 }
         ).trim()
       ).toBe(
         `query: {
@@ -38,11 +38,13 @@ describe.only("transformParametersArray()", () => {
       expect(
         transformParametersArray(
           [{ $ref: "#/parameters/per_page" }, { $ref: "#/parameters/page" }, { $ref: "#/parameters/since" }],
-          2,
           {
-            per_page: { in: "query", name: "per_page", required: true, type: "number" },
-            page: { in: "query", name: "page", type: "number" },
-            since: { in: "query", name: "since", type: "string" },
+            version: 2,
+            globalParameters: {
+              per_page: { in: "query", name: "per_page", required: true, type: "number" },
+              page: { in: "query", name: "page", type: "number" },
+              since: { in: "query", name: "since", type: "string" },
+            },
           }
         ).trim()
       ).toBe(`query: {
@@ -78,7 +80,7 @@ describe.only("transformParametersArray()", () => {
               },
             },
           ],
-          3
+          { version: 3 }
         ).trim()
       ).toBe(
         `query: {
@@ -99,11 +101,13 @@ describe.only("transformParametersArray()", () => {
             { $ref: "#/components/parameters/page" },
             { $ref: "#/components/parameters/since" },
           ],
-          3,
           {
-            per_page: { in: "query", name: "per_page", required: true },
-            page: { in: "query", name: "page" },
-            since: { in: "query", name: "since" },
+            version: 3,
+            globalParameters: {
+              per_page: { in: "query", name: "per_page", required: true },
+              page: { in: "query", name: "page" },
+              since: { in: "query", name: "since" },
+            },
           }
         ).trim()
       ).toBe(`query: {

tests/paths.test.ts

@@ -1,10 +1,13 @@
 import prettier from "prettier";
 import { transformPathsObj } from "../src/transform/paths";
 
-const transform = (schema: any, operations: any = { operations: {}, parameters: {} }, parameters?: any) =>
-  prettier.format(`export interface paths {\n${transformPathsObj(schema, { operations, parameters }, 3)}\n}`.trim(), {
-    parser: "typescript",
-  });
+const transform = (schema: any, operations: any = { operations: {}, globalParameters: {} }, globalParameters?: any) =>
+  prettier.format(
+    `export interface paths {\n${transformPathsObj(schema, { operations, globalParameters, version: 3 })}\n}`.trim(),
+    {
+      parser: "typescript",
+    }
+  );
 
 describe("transformPathsObj", () => {
   it("basic", () => {