Alphabetically sort transforms (#966)

* 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 <mrleebo@msn.com>

Author: drwpow

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

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

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,

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);

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;

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) {

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

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`;

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;

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;