feat: generate immutable types (#522)

* feat: generate immutable types

* fix: remove optional chaining

* fix: use kebab-case flag

* test: add immutable types tests

* test: extend empty definitions with immutable types

* test: extend parameters with immutable types

* test: extend raw schema with immutable types

* test: extend operation with immutable types

* test: extend schema with immutable types

* test: extend paths with immutable types

* fix: immutable additional properties

* test: add schema v2 immutable types tests

* add npm prepare script

* refactor to use function

Author: dnalborczyk

.prettierignore

@@ -1,6 +1,4 @@
 examples/**/*.ts
-tests/*/expected/**/*.ts
-tests/*/generated/**/*.ts
 *.md
 *.yaml
 *.yml

README.md

@@ -110,6 +110,7 @@ For anything more complicated, or for generating specs dynamically, you can also
 | :----------------------------- | :---- | :------: | :--------------------------------------------------------------- |
 | `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                           |
 | `--auth [token]`               |       |          | (optional) Provide an auth token to be passed along in the request (only if accessing a private schema). |
+| `--immutable-types`            |       | `false`  | (optional) Generates immutable types (readonly properties and readonly array). |
 | `--prettier-config [location]` |       |          | (optional) Path to your custom Prettier configuration for output |
 | `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level) |
 

bin/cli.js

@@ -15,6 +15,7 @@ Options
   --help                display this
   --output, -o          Specify output file (default: stdout)
   --auth                (optional) Provide an authentication token for private URL
+  --immutable-types     (optional) Generates immutable types (readonly properties and readonly array)
   --prettier-config     (optional) specify path to Prettier config file
   --raw-schema          (optional) Read from raw schema instead of document
   --version             (optional) Schema version (must be present for raw schemas)
@@ -28,6 +29,9 @@ Options
       auth: {
         type: "string",
       },
+      immutableTypes: {
+        type: "boolean",
+      },
       prettierConfig: {
         type: "string",
       },
@@ -69,6 +73,7 @@ async function main() {
 
   // 2. generate schema (the main part!)
   const result = swaggerToTS(spec, {
+    immutableTypes: cli.flags.immutableTypes,
     prettierConfig: cli.flags.prettierConfig,
     rawSchema: cli.flags.rawSchema,
     version: cli.flags.version,

package.json

@@ -46,6 +46,7 @@
     "build": "rm -rf dist && tsc --build tsconfig.json && tsc --build tsconfig.cjs.json",
     "format": "yarn prettier -w .",
     "lint": "eslint --ignore-path .gitignore --ext .js,.ts src",
+    "prepare": "npm run build",
     "pregenerate": "npm run build",
     "test": "npm run build && jest --no-cache",
     "test:coverage": "npm run build && jest --no-cache --coverage && codecov",

src/index.ts

@@ -22,7 +22,11 @@ export default function swaggerToTS(
 
   // 2. generate output
   let output = `${WARNING_MESSAGE}
-  ${transformAll(schema, { version, rawSchema: options && options.rawSchema })}
+  ${transformAll(schema, {
+    immutableTypes: (options && options.immutableTypes) || false,
+    rawSchema: options && options.rawSchema,
+    version,
+  })}
 `;
 
   // 3. Prettify output

src/transform/headers.ts

@@ -1,16 +1,24 @@
 import { HeaderObject } from "../types";
-import { comment } from "../utils";
+import { comment, tsReadonly } from "../utils";
 import { transformSchemaObj } from "./schema";
 
-export function transformHeaderObjMap(headerMap: Record<string, HeaderObject>): string {
+export function transformHeaderObjMap(
+  headerMap: Record<string, HeaderObject>,
+  { immutableTypes }: { immutableTypes: boolean }
+): string {
   let output = "";
 
   Object.entries(headerMap).forEach(([k, v]) => {
     if (!v.schema) return;
 
     if (v.description) output += comment(v.description);
+
+    const readonly = tsReadonly(immutableTypes);
     const required = v.required ? "" : "?";
-    output += `  "${k}"${required}: ${transformSchemaObj(v.schema)}\n`;
+
+    output += `  ${readonly}"${k}"${required}: ${transformSchemaObj(v.schema, {
+      immutableTypes,
+    })}\n`;
   });
 
   return output;

src/transform/index.ts

@@ -1,17 +1,20 @@
 import { OperationObject } from "../types";
-import { comment } from "../utils";
+import { comment, tsReadonly } from "../utils";
 import { transformHeaderObjMap } from "./headers";
 import { transformOperationObj } from "./operation";
 import { transformPathsObj } from "./paths";
 import { transformResponsesObj, transformRequestBodies } from "./responses";
 import { transformSchemaObjMap } from "./schema";
 
 interface TransformOptions {
+  immutableTypes: boolean;
   rawSchema?: boolean;
   version: number;
 }
 
-export function transformAll(schema: any, { version, rawSchema }: TransformOptions): string {
+export function transformAll(schema: any, { immutableTypes, rawSchema, version }: TransformOptions): string {
+  const readonly = tsReadonly(immutableTypes);
+
   let output = "";
 
   let operations: Record<string, OperationObject> = {};
@@ -21,11 +24,13 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
     switch (version) {
       case 2: {
         return `export interface definitions {\n  ${transformSchemaObjMap(schema, {
+          immutableTypes,
           required: Object.keys(schema),
         })}\n}`;
       }
       case 3: {
         return `export interface schemas {\n    ${transformSchemaObjMap(schema, {
+          immutableTypes,
           required: Object.keys(schema),
         })}\n  }\n\n`;
       }
@@ -36,8 +41,9 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
   output += `export interface paths {\n`; // open paths
   if (schema.paths) {
     output += transformPathsObj(schema.paths, {
-      operations,
       globalParameters: (schema.components && schema.components.parameters) || schema.parameters,
+      immutableTypes,
+      operations,
       version,
     });
   }
@@ -48,6 +54,7 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
       // #/definitions
       if (schema.definitions) {
         output += `export interface definitions {\n  ${transformSchemaObjMap(schema.definitions, {
+          immutableTypes,
           required: Object.keys(schema.definitions),
         })}\n}\n\n`;
       }
@@ -56,13 +63,16 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
       if (schema.parameters) {
         const required = Object.keys(schema.parameters);
         output += `export interface parameters {\n    ${transformSchemaObjMap(schema.parameters, {
+          immutableTypes,
           required,
         })}\n  }\n\n`;
       }
 
       // #/parameters
       if (schema.responses) {
-        output += `export interface responses {\n    ${transformResponsesObj(schema.responses)}\n  }\n\n`;
+        output += `export interface responses {\n    ${transformResponsesObj(schema.responses, {
+          immutableTypes,
+        })}\n  }\n\n`;
       }
       break;
     }
@@ -74,30 +84,40 @@ export function transformAll(schema: any, { version, rawSchema }: TransformOptio
         // #/components/schemas
         if (schema.components.schemas) {
           const required = Object.keys(schema.components.schemas);
-          output += `  schemas: {\n    ${transformSchemaObjMap(schema.components.schemas, { required })}\n  }\n`;
+          output += `  ${readonly}schemas: {\n    ${transformSchemaObjMap(schema.components.schemas, {
+            immutableTypes,
+            required,
+          })}\n  }\n`;
         }
 
         // #/components/responses
         if (schema.components.responses) {
-          output += `  responses: {\n    ${transformResponsesObj(schema.components.responses)}\n  }\n`;
+          output += `  ${readonly}responses: {\n    ${transformResponsesObj(schema.components.responses, {
+            immutableTypes,
+          })}\n  }\n`;
         }
 
         // #/components/parameters
         if (schema.components.parameters) {
           const required = Object.keys(schema.components.parameters);
-          output += `  parameters: {\n    ${transformSchemaObjMap(schema.components.parameters, {
+          output += `  ${readonly}parameters: {\n    ${transformSchemaObjMap(schema.components.parameters, {
+            immutableTypes,
             required,
           })}\n  }\n`;
         }
 
         // #/components/requestBodies
         if (schema.components.requestBodies) {
-          output += `  requestBodies: {\n    ${transformRequestBodies(schema.components.requestBodies)}\n  }\n`;
+          output += `  ${readonly}requestBodies: {\n    ${transformRequestBodies(schema.components.requestBodies, {
+            immutableTypes,
+          })}\n  }\n`;
         }
 
         // #/components/headers
         if (schema.components.headers) {
-          output += `  headers: {\n    ${transformHeaderObjMap(schema.components.headers)}  }\n`;
+          output += `  ${readonly}headers: {\n    ${transformHeaderObjMap(schema.components.headers, {
+            immutableTypes,
+          })}  }\n`;
         }
       }
 
@@ -110,9 +130,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, {
-        version,
+      output += `  ${readonly}"${operationId}": {\n    ${transformOperationObj(operation, {
         globalParameters: (schema.components && schema.components.parameters) || schema.parameters,
+        immutableTypes,
+        version,
       })}\n  }\n`;
     });
   }

src/transform/operation.ts

@@ -1,57 +1,69 @@
 import { OperationObject, ParameterObject, RequestBody } from "../types";
-import { comment, isRef, transformRef } from "../utils";
+import { comment, isRef, transformRef, tsReadonly } from "../utils";
 import { transformParametersArray } from "./parameters";
 import { transformResponsesObj } from "./responses";
 import { transformSchemaObj } from "./schema";
 
 export function transformOperationObj(
   operation: OperationObject,
   {
-    version,
     globalParameters,
+    immutableTypes,
+    version,
   }: {
-    version: number;
     globalParameters?: Record<string, ParameterObject>;
+    immutableTypes: boolean;
+    version: number;
   }
 ): string {
+  const readonly = tsReadonly(immutableTypes);
+
   let output = "";
 
   if (operation.parameters) {
-    output += `  parameters: {\n    ${transformParametersArray(operation.parameters, {
-      version,
+    output += `  ${readonly}parameters: {\n    ${transformParametersArray(operation.parameters, {
       globalParameters,
+      immutableTypes,
+      version,
     })}\n  }\n`;
   }
 
   if (operation.responses) {
-    output += `  responses: {\n  ${transformResponsesObj(operation.responses)}\n  }\n`;
+    output += `  ${readonly}responses: {\n  ${transformResponsesObj(operation.responses, {
+      immutableTypes,
+    })}\n  }\n`;
   }
 
   if (operation.requestBody) {
     if (isRef(operation.requestBody)) {
-      output += `  requestBody: ${transformRef(operation.requestBody.$ref)};\n`;
+      output += `  ${readonly}requestBody: ${transformRef(operation.requestBody.$ref)};\n`;
     } else {
       if (operation.requestBody.description) output += comment(operation.requestBody.description);
 
-      output += `  requestBody: {\n`; // open requestBody
-      output += `  ${transformRequestBodyObj(operation.requestBody)}`;
+      output += `  ${readonly}requestBody: {\n`; // open requestBody
+      output += `  ${transformRequestBodyObj(operation.requestBody, { immutableTypes })}`;
       output += `  }\n`; // close requestBody
     }
   }
 
   return output;
 }
 
-export function transformRequestBodyObj(requestBody: RequestBody) {
+export function transformRequestBodyObj(
+  requestBody: RequestBody,
+  { immutableTypes }: { immutableTypes: boolean }
+): string {
+  const readonly = tsReadonly(immutableTypes);
+
   let output = "";
 
   const { content } = requestBody;
 
   if (content && Object.keys(content).length) {
-    output += `  content: {\n`; // open content
+    output += `  ${readonly}content: {\n`; // open content
 
     Object.entries(content).forEach(([k, v]) => {
-      output += `      "${k}": ${transformSchemaObj(v.schema)};\n`;
+      output += `      ${readonly}"${k}": ${transformSchemaObj(v.schema, { immutableTypes })};\n`;
     });
     output += `    }\n`; // close content
   } else {

src/transform/parameters.ts

@@ -1,17 +1,21 @@
 import { ParameterObject, ReferenceObject } from "../types";
-import { comment } from "../utils";
+import { comment, tsReadonly } from "../utils";
 import { transformSchemaObj } from "./schema";
 
 export function transformParametersArray(
   parameters: (ReferenceObject | ParameterObject)[],
   {
-    version,
     globalParameters,
+    immutableTypes,
+    version,
   }: {
-    version: number;
     globalParameters?: Record<string, ParameterObject>;
+    immutableTypes: boolean;
+    version: number;
   }
 ): string {
+  const readonly = tsReadonly(immutableTypes);
+
   let output = "";
 
   // sort into map
@@ -44,7 +48,7 @@ export function transformParametersArray(
 
   // transform output
   Object.entries(mappedParams).forEach(([paramIn, paramGroup]) => {
-    output += `  ${paramIn}: {\n`; // open in
+    output += `  ${readonly}${paramIn}: {\n`; // open in
     Object.entries(paramGroup).forEach(([paramName, paramObj]) => {
       let paramComment = "";
       if (paramObj.deprecated) paramComment += `@deprecated `;
@@ -55,16 +59,16 @@ export function transformParametersArray(
       let paramType = ``;
       if (version === 2) {
         if (paramObj.in === "body" && paramObj.schema) {
-          paramType = transformSchemaObj(paramObj.schema);
+          paramType = transformSchemaObj(paramObj.schema, { immutableTypes });
         } else if (paramObj.type) {
-          paramType = transformSchemaObj(paramObj);
+          paramType = transformSchemaObj(paramObj, { immutableTypes });
         } else {
           paramType = "unknown";
         }
       } else if (version === 3) {
-        paramType = paramObj.schema ? transformSchemaObj(paramObj.schema) : "unknown";
+        paramType = paramObj.schema ? transformSchemaObj(paramObj.schema, { immutableTypes }) : "unknown";
       }
-      output += `    "${paramName}"${required}: ${paramType};\n`;
+      output += `    ${readonly}"${paramName}"${required}: ${paramType};\n`;
     });
     output += `  }\n`; // close in
   });