Alphabetically sort transforms (#966)

drwpow · MrLeebo · web-flow · commit 16c25c65ca53 · 2022-11-01T20:30:55.000-06:00
* Alphabetically sort output from transforms

* Refactor sort into an --alphabetize flag and add test cases

* Fix typo

* Rewrite tests to test for alphabetization of specific object types

* Add test for alphabetized operations and clean up operation tests

* fix TS error

Co-authored-by: Jeremy Liberman &lt;mrleebo@msn.com&gt;
diff --git a/README.md b/README.md
@@ -155,6 +155,7 @@ npx openapi-typescript schema.yaml
 | `--support-array-length`       |       | `false`  | (optional) Generate tuples using array minItems / maxItems                                                                              |
 | `--make-paths-enum`            | `-pe` | `false`  | (optional) Generate an enum of endpoint paths                                                                                           |
 | `--path-params-as-types`       |       | `false`  | (optional) Substitute path parameter names with their respective types                                                                  |
+| `--alphabetize`                |       | `false`  | (optional) Sort types alphabetically                                                                                                    |
 | `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                                                |
 
 ### 🐢 Node
diff --git a/bin/cli.js b/bin/cli.js
@@ -30,6 +30,7 @@ Options
   --export-type                (optional) Export type instead of interface
   --support-array-length       (optional) Generate tuples using array minItems / maxItems
   --path-params-as-types       (optional) Substitute path parameter names with their respective types
+  --alphabetize                (optional) Sort types alphabetically
   --version                    (optional) Force schema parsing version
 `;
 
@@ -57,6 +58,7 @@ const flags = parser(args, {
     "supportArrayLength",
     "makePathsEnum",
     "pathParamsAsTypes",
+    "alphabetize",
   ],
   number: ["version"],
   string: ["auth", "header", "headersObject", "httpMethod", "prettierConfig"],
@@ -112,6 +114,7 @@ async function generateSchema(pathToSpec) {
     exportType: flags.exportType,
     supportArrayLength: flags.supportArrayLength,
     pathParamsAsTypes: flags.pathParamsAsTypes,
+    alphabetize: flags.alphabetize,
   });
 
   // output
diff --git a/src/index.ts b/src/index.ts
@@ -46,6 +46,7 @@ async function openapiTS(
     contentNever: options.contentNever || false,
     makePathsEnum: options.makePathsEnum || false,
     pathParamsAsTypes: options.pathParamsAsTypes,
+    alphabetize: options.alphabetize || false,
     rawSchema: options.rawSchema || false,
     supportArrayLength: options.supportArrayLength,
     version: options.version || 3,
diff --git a/src/transform/headers.ts b/src/transform/headers.ts
@@ -1,5 +1,5 @@
 import type { GlobalContext, HeaderObject } from "../types.js";
-import { comment, tsReadonly } from "../utils.js";
+import { comment, getEntries, tsReadonly } from "../utils.js";
 import { transformSchemaObj } from "./schema.js";
 
 interface TransformHeadersOptions extends GlobalContext {
@@ -12,8 +12,7 @@ export function transformHeaderObjMap(
 ): string {
   let output = "";
 
-  for (const k of Object.keys(headerMap)) {
-    const v = headerMap[k];
+  for (const [k, v] of getEntries(headerMap, options)) {
     if (!v.schema) continue;
 
     if (v.description) output += comment(v.description);
diff --git a/src/transform/parameters.ts b/src/transform/parameters.ts
@@ -1,5 +1,5 @@
 import type { GlobalContext, ParameterObject, ReferenceObject } from "../types.js";
-import { comment, tsReadonly } from "../utils.js";
+import { comment, getEntries, tsReadonly } from "../utils.js";
 import { transformSchemaObj } from "./schema.js";
 
 interface TransformParametersOptions extends GlobalContext {
@@ -19,11 +19,16 @@ export function transformParametersArray(
 
   // sort into map
   const mappedParams: Record<string, Record<string, ParameterObject>> = {};
-  for (const paramObj of parameters as any[]) {
-    if (paramObj.$ref && globalParameters) {
-      const paramName = paramObj.$ref.split('["').pop().replace(PARAM_END_RE, ""); // take last segment
+  for (const paramObj of parameters) {
+    if ("$ref" in paramObj && paramObj.$ref && globalParameters) {
+      // take last segment
+      let paramName = paramObj.$ref.split('["').pop();
+      paramName = String(paramName).replace(PARAM_END_RE, "");
+
       if (globalParameters[paramName]) {
-        const reference = globalParameters[paramName] as any;
+        const reference = globalParameters[paramName];
+        if (!reference.in) continue;
+
         if (!mappedParams[reference.in]) mappedParams[reference.in] = {};
         switch (ctx.version) {
           case 3: {
@@ -36,7 +41,7 @@ export function transformParametersArray(
           case 2: {
             mappedParams[reference.in][reference.name || paramName] = {
               ...reference,
-              $ref: paramObj.$ref,
+              ...("$ref" in paramObj ? { $ref: paramObj.$ref } : null),
             };
             break;
           }
@@ -45,15 +50,16 @@ export function transformParametersArray(
       continue;
     }
 
+    if (!("in" in paramObj)) continue;
     if (!paramObj.in || !paramObj.name) continue;
     if (!mappedParams[paramObj.in]) mappedParams[paramObj.in] = {};
     mappedParams[paramObj.in][paramObj.name] = paramObj;
   }
 
   // transform output
-  for (const [paramIn, paramGroup] of Object.entries(mappedParams)) {
+  for (const [paramIn, paramGroup] of getEntries(mappedParams, ctx)) {
     output += `  ${readonly}${paramIn}: {\n`; // open in
-    for (const [paramName, paramObj] of Object.entries(paramGroup)) {
+    for (const [paramName, paramObj] of getEntries(paramGroup, ctx)) {
       let paramComment = "";
       if (paramObj.deprecated) paramComment += `@deprecated `;
       if (paramObj.description) paramComment += paramObj.description;
diff --git a/src/transform/paths.ts b/src/transform/paths.ts
@@ -1,5 +1,5 @@
 import type { GlobalContext, OperationObject, ParameterObject, PathItemObject } from "../types.js";
-import { comment, tsReadonly, nodeType } from "../utils.js";
+import { comment, tsReadonly, nodeType, getEntries } from "../utils.js";
 import { transformOperationObj } from "./operation.js";
 import { transformParametersArray } from "./parameters.js";
 
@@ -33,7 +33,7 @@ export function transformPathsObj(paths: Record<string, PathItemObject>, options
 
   let output = "";
 
-  for (const [url, pathItem] of Object.entries(paths)) {
+  for (const [url, pathItem] of getEntries(paths, options)) {
     if (pathItem.description) output += comment(pathItem.description); // add comment
 
     if (pathItem.$ref) {
diff --git a/src/transform/request.ts b/src/transform/request.ts
@@ -1,11 +1,11 @@
 import type { GlobalContext, RequestBody } from "../types.js";
-import { comment, tsReadonly } from "../utils.js";
+import { comment, getEntries, tsReadonly } from "../utils.js";
 import { transformSchemaObj } from "./schema.js";
 
 export function transformRequestBodies(requestBodies: Record<string, RequestBody>, ctx: GlobalContext) {
   let output = "";
 
-  for (const [name, requestBody] of Object.entries(requestBodies)) {
+  for (const [name, requestBody] of getEntries(requestBodies, ctx)) {
     if (requestBody && requestBody.description) output += `  ${comment(requestBody.description)}`;
     output += `  "${name}": {\n    ${transformRequestBodyObj(requestBody, ctx)}\n  }\n`;
   }
@@ -20,7 +20,7 @@ export function transformRequestBodyObj(requestBody: RequestBody, ctx: GlobalCon
 
   if (requestBody.content && Object.keys(requestBody.content).length) {
     output += `  ${readonly}content: {\n`; // open content
-    for (const [k, v] of Object.entries(requestBody.content)) {
+    for (const [k, v] of getEntries(requestBody.content, ctx)) {
       output += `      ${readonly}"${k}": ${transformSchemaObj(v.schema, { ...ctx, required: new Set<string>() })};\n`;
     }
     output += `    }\n`; // close content
diff --git a/src/transform/responses.ts b/src/transform/responses.ts
@@ -1,5 +1,5 @@
 import type { GlobalContext } from "../types.js";
-import { comment, tsReadonly } from "../utils.js";
+import { comment, getEntries, tsReadonly } from "../utils.js";
 import { transformHeaderObjMap } from "./headers.js";
 import { transformSchemaObj } from "./schema.js";
 
@@ -15,9 +15,8 @@ export function transformResponsesObj(responsesObj: Record<string, any>, ctx: Gl
 
   let output = "";
 
-  for (const httpStatusCode of Object.keys(responsesObj)) {
+  for (const [httpStatusCode, response] of getEntries(responsesObj, ctx)) {
     const statusCode = Number(httpStatusCode) || `"${httpStatusCode}"`; // don’t surround w/ quotes if numeric status code
-    const response = responsesObj[httpStatusCode];
     if (response.description) output += comment(response.description);
 
     if (response.$ref) {
@@ -48,10 +47,10 @@ export function transformResponsesObj(responsesObj: Record<string, any>, ctx: Gl
     switch (ctx.version) {
       case 3: {
         output += `    ${readonly}content: {\n`; // open content
-        for (const contentType of Object.keys(response.content)) {
-          const contentResponse = response.content[contentType] as any;
+        // TODO: proper type definitions for this
+        for (const [contentType, contentResponse] of getEntries<any>(response.content, ctx)) {
           const responseType =
-            contentResponse && contentResponse?.schema
+            "schema" in contentResponse
               ? transformSchemaObj(contentResponse.schema, { ...ctx, required: new Set<string>() })
               : "unknown";
           output += `      ${readonly}"${contentType}": ${responseType};\n`;
diff --git a/src/transform/schema.ts b/src/transform/schema.ts
@@ -9,6 +9,7 @@ import {
   tsUnionOf,
   parseSingleSimpleValue,
   ParsedSimpleValue,
+  getEntries,
 } from "../utils.js";
 
 interface TransformSchemaObjOptions extends GlobalContext {
@@ -27,9 +28,7 @@ function hasDefaultValue(node: any): boolean {
 export function transformSchemaObjMap(obj: Record<string, any>, options: TransformSchemaObjOptions): string {
   let output = "";
 
-  for (const k of Object.keys(obj)) {
-    const v = obj[k];
-
+  for (const [k, v] of getEntries(obj, options)) {
     // 1. Add comment in jsdoc notation
     const comment = prepareComment(v);
     if (comment) output += comment;
diff --git a/src/types.ts b/src/types.ts
@@ -136,6 +136,8 @@ export interface SwaggerToTSOptions {
   rawSchema?: boolean;
   /** (optional) Generate an enum containing all API paths. **/
   makePathsEnum?: boolean;
+  /** (optional) Sort types alphabetically. */
+  alphabetize?: boolean;
   /** (optional) Should logging be suppressed? (necessary for STDOUT) */
   silent?: boolean;
   /** (optional) OpenAPI version. Must be present if parsing raw schema */
@@ -186,6 +188,7 @@ export interface GlobalContext {
   makePathsEnum: boolean;
   namespace?: string;
   pathParamsAsTypes?: boolean;
+  alphabetize?: boolean;
   rawSchema: boolean;
   silent?: boolean;
   supportArrayLength?: boolean;
diff --git a/src/utils.ts b/src/utils.ts
@@ -1,4 +1,4 @@
-import type { OpenAPI2, OpenAPI3, ReferenceObject } from "./types.js";
+import type { GlobalContext, OpenAPI2, OpenAPI3, ReferenceObject } from "./types.js";
 
 type CommentObject = {
   const?: boolean; // jsdoc without value
@@ -292,3 +292,9 @@ export function replaceKeys(obj: Record<string, any>): Record<string, any> {
     return obj;
   }
 }
+
+export function getEntries<Item>(obj: ArrayLike<Item> | Record<string, Item>, options: GlobalContext) {
+  const entries = Object.entries(obj);
+  if (options.alphabetize) entries.sort(([a], [b]) => a.localeCompare(b, "en", { numeric: true }));
+  return entries;
+}
diff --git a/test/core/operation.test.js b/test/core/operation.test.js
@@ -187,4 +187,108 @@ describe("parameters", () => {
 
   }`);
   });
+
+  describe("alphabetize", () => {
+    function assertSchema(actual, expected) {
+      const result = transformOperationObj(actual, {
+        ...defaults,
+        alphabetize: true,
+        version: 3,
+        pathItem: {
+          parameters: [
+            {
+              in: "path",
+              name: "p2",
+              schema: {
+                type: "string",
+              },
+            },
+            {
+              in: "path",
+              name: "p3",
+              schema: {
+                type: "string",
+              },
+            },
+          ],
+        },
+      });
+      expect(result.trim()).to.equal(expected.trim());
+    }
+
+    it("content types", () => {
+      const actual = {
+        requestBody: {
+          content: {
+            "font/woff2": {
+              schema: { type: "string" },
+            },
+            "font/otf": {
+              schema: { type: "string" },
+            },
+            "font/sfnt": {
+              schema: { type: "string" },
+            },
+            "font/ttf": {
+              schema: { type: "string" },
+            },
+            "font/woff": {
+              schema: { type: "string" },
+            },
+          },
+        },
+      };
+
+      const expected = `parameters: {
+      path: {
+    "p2"?: string;
+    "p3"?: string;
+  }
+
+  }
+  requestBody: {
+    content: {
+      "font/otf": string;
+      "font/sfnt": string;
+      "font/ttf": string;
+      "font/woff": string;
+      "font/woff2": string;
+    }
+  }`;
+
+      assertSchema(actual, expected);
+    });
+
+    it("operation parameters", () => {
+      const actual = {
+        parameters: [
+          {
+            in: "path",
+            name: "p2",
+            schema: {
+              type: "number",
+            },
+          },
+          {
+            in: "path",
+            name: "p1",
+            schema: {
+              type: "string",
+            },
+          },
+        ],
+      };
+
+      const expected = `parameters: {
+      path: {
+    "p1"?: string;
+    "p2"?: number;
+    "p3"?: string;
+  }
+
+  }`;
+
+      assertSchema(actual, expected);
+    });
+  });
 });
diff --git a/test/core/parameters.test.js b/test/core/parameters.test.js
diff --git a/test/core/paths.test.js b/test/core/paths.test.js
diff --git a/test/core/request.test.js b/test/core/request.test.js
diff --git a/test/core/schema.test.js b/test/core/schema.test.js
diff --git a/tsconfig.json b/tsconfig.json
