cosmos-explorer/utils/armClientGenerator/generator.ts

/* eslint-disable no-console */
/// <reference types="node" />
import { writeFileSync } from "fs";
import mkdirp from "mkdirp";
import fetch from "node-fetch";
import * as path from "path";

/* 
Open API TypeScript Client Generator 

This is a bespoke Open API client generator not intended for general public use. 
It is not designed to handle the full OpenAPI spec.
Many other more general purpose generators exist, but their output is very verbose and overly complex for our use case.
But it does work well enough to generate a fully typed tree-shakeable client for the Cosmos resource provider.
Results of this file should be checked into the repo.
*/

// CHANGE THESE VALUES TO GENERATE NEW CLIENTS
const version = "2023-09-15-preview";
/* The following are legal options for resourceName but you generally will only use cosmos-db:
"cosmos-db" | "managedCassandra" | "mongorbac" | "notebook" | "privateEndpointConnection" | "privateLinkResources" |
"rbac" | "restorable" | "services"
*/
const githubResourceName = "cosmos-db";
const deResourceName = "cosmos";
const schemaURL = `https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/${version}/${githubResourceName}.json`;
const outputDir = path.join(__dirname, `../../src/Utils/arm/generatedClients/${deResourceName}`);

// Array of strings to use for eventual output
const outputTypes: string[] = [""];
mkdirp.sync(outputDir);

// Buckets for grouping operations based on their name
interface Client {
  paths: string[];
  functions: string[];
  constructorParams: string[];
}
const clients: { [key: string]: Client } = {};

// Mapping for OpenAPI types to TypeScript types
const propertyMap: { [key: string]: string } = {
  integer: "number",
};

// Converts a Open API reference: "#/definitions/Foo" to a type name: Foo
function refToType(path: string | undefined, namespace?: string) {
  // References must be in the same file. Bail to `unknown` types for remote references
  if (path && path.startsWith("#")) {
    const type = path.split("/").pop();
    return namespace ? `${namespace}.${type}` : type;
  }
  return "unknown";
}

// Converts "Something_Foo" ->  "somethingFoo"
function camelize(str: string) {
  return str
    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word: string, index: number) => {
      return index === 0 ? word.toLowerCase() : word.toUpperCase();
    })
    .replace(/\s+/g, "");
}

// Converts a body paramter to the equivalent typescript function parameter type
function bodyParam(parameter: { schema: { $ref: string } }, namespace: string) {
  if (!parameter) {
    return "";
  }
  return `,body: ${refToType(parameter.schema.$ref, namespace)}`;
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
function parametersFromPath(path: string) {
  // TODO: Remove any. String.matchAll is a real thing.
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const matches = (path as any).matchAll(/{(\w+)}/g);
  return Array.from(matches).map((match: string[]) => match[1]);
}

type Operation = { responses: { [key: string]: { schema: { $ref: string } } } };

// Converts OpenAPI response definition to TypeScript return type. Uses unions if possible. Bails to unknown
function responseType(operation: Operation, namespace: string) {
  if (operation.responses) {
    return Object.keys(operation.responses)
      .map((responseCode: string) => {
        if (!operation.responses[responseCode].schema) {
          return "void";
        }
        return refToType(operation.responses[responseCode].schema.$ref, namespace);
      })
      .filter((value, index, array) => array.indexOf(value) === index)
      .filter((value) => value !== "unknown")
      .join(" | ");
  }
  return "unknown";
}

interface Property {
  $ref?: string;
  description?: string;
  readOnly?: boolean;
  type: "array" | "object" | "unknown";
  properties: Property[];
  items?: {
    $ref: string;
  };
  enum?: string[];
  allOf?: {
    $ref: string;
  }[];
}

const propertyToType = (property: Property, prop: string, required: boolean) => {
  if (property) {
    if (property.allOf) {
      outputTypes.push(`
      /* ${property.description || "undocumented"} */
      ${property.readOnly ? "readonly " : ""}${prop}${
        required ? "" : "?"
      }: ${property.allOf.map((allof: { $ref: string }) => refToType(allof.$ref)).join(" & ")}`);
    } else if (property.$ref) {
      const type = refToType(property.$ref);
      outputTypes.push(`
          /* ${property.description || "undocumented"} */
          ${property.readOnly ? "readonly " : ""}${prop}${required ? "" : "?"}: ${type}
          `);
    } else if (property.type === "array") {
      const type = refToType(property.items.$ref);
      outputTypes.push(`
          /* ${property.description || "undocumented"} */
          ${property.readOnly ? "readonly " : ""}${prop}${required ? "" : "?"}: ${type}[]
          `);
    } else if (property.type === "object") {
      const type = refToType(property.$ref);
      outputTypes.push(`
          /* ${property.description || "undocumented"} */
          ${property.readOnly ? "readonly " : ""}${prop}${required ? "" : "?"}: ${type}
          `);
    } else if (property.enum) {
      outputTypes.push(`
          /* ${property.description || "undocumented"} */
          ${property.readOnly ? "readonly " : ""}${prop}${required ? "" : "?"}: ${property.enum
        .map((v: string) => `"${v}"`)
        .join(" | ")}
          `);
    } else {
      if (property.type === undefined) {
        console.log(`generator.ts - UNHANDLED TYPE: ${prop}. Falling back to unknown`);
        property.type = "unknown";
      }
      outputTypes.push(`
          /* ${property.description || "undocumented"} */
          ${property.readOnly ? "readonly " : ""}${prop}${required ? "" : "?"}: ${
        propertyMap[property.type] ? propertyMap[property.type] : property.type
      }`);
    }
  }
};

async function main() {
  const response = await fetch(schemaURL);
  const schema = await response.json();

  // STEP 1: Convert all definitions to TypeScript types and interfaces
  for (const definition in schema.definitions) {
    const properties = schema.definitions[definition].properties;
    if (properties) {
      outputTypes.push(`
      /* ${schema.definitions[definition].description || "undocumented"} */
      `);
      if (schema.definitions[definition].allOf) {
        const baseTypes = schema.definitions[definition].allOf
          .map((allof: { $ref: string }) => refToType(allof.$ref))
          .join(" & ");
        outputTypes.push(`export type ${definition} = ${baseTypes} & {`);
      } else {
        outputTypes.push(`export interface ${definition} {`);
      }
      for (const prop in schema.definitions[definition].properties) {
        const property = schema.definitions[definition].properties[prop];
        propertyToType(property, prop, schema.definitions[definition].required?.includes(prop));
      }
      outputTypes.push(`}`);
      outputTypes.push("\n\n");
    } else {
      const def = schema.definitions[definition];
      if (def.enum) {
        outputTypes.push(`
        /* ${def.description || "undocumented"} */
        export type ${definition} = ${def.enum.map((v: string) => `"${v}"`).join(" | ")}`);
        outputTypes.push("\n");
      } else if (def.type === "string") {
        outputTypes.push(`
        /* ${def.description || "undocumented"} */
        export type ${definition} = string
          `);
      } else if (def.type === "array") {
        const type = refToType(def.items.$ref);
        outputTypes.push(`
        /* ${def.description || "undocumented"} */
        export type ${definition} = ${type}[]
        `);
      } else if (def.type === "object" && def.additionalProperties) {
        outputTypes.push(`
        /* ${def.description || "undocumented"} */
        export type ${definition} = { [key: string]: ${def.additionalProperties.type}}
        `);
      } else if (def.type === "object" && def.allOf) {
        const type = refToType(def.allOf[0].$ref);
        outputTypes.push(`
        /* ${def.description} */
        export type ${definition} = ${type}
        `);
      } else {
        console.log("generator.ts - UNHANDLED MODEL:", def, schema.definitions[def]);
      }
    }
  }

  // STEP 2: Group all paths by output client and extract common constructor parameters
  // Functions are grouped into clients based on operation name
  for (const path in schema.paths) {
    for (const method in schema.paths[path]) {
      const operation = schema.paths[path][method];
      const [namespace] = operation.operationId.split("_");
      if (clients[namespace] === undefined) {
        clients[namespace] = { paths: [], functions: [], constructorParams: [] };
        clients[namespace];
      }
      if (!clients[namespace].paths.includes(path)) {
        clients[namespace].paths.push(path);
      }
    }
  }

  // Write all grouped fetch functions to objects
  for (const clientName in clients) {
    const outputClient: string[] = [""];
    outputClient.push(`import { armRequest } from "../../request"\n`);
    outputClient.push(`import * as Types from "./types"\n`);
    outputClient.push(`import { configContext } from "../../../../ConfigContext";\n`);
    outputClient.push(`const apiVersion = "${version}"\n\n`);
    for (const path of clients[clientName].paths) {
      for (const method in schema.paths[path]) {
        const operation = schema.paths[path][method];
        const [, methodName] = operation.operationId.split("_");
        const bodyParameter = operation.parameters.find(
          (parameter: { in: string; required: boolean }) => parameter.in === "body" && parameter.required === true
        );
        outputClient.push(`
          /* ${operation.description || "undocumented"} */
          export async function ${sanitize(camelize(methodName))} (
            ${parametersFromPath(path)
              .map((p) => `${p}: string`)
              .join(",\n")}
            ${bodyParam(bodyParameter, "Types")}
          ) : Promise<${responseType(operation, "Types")}> {
            const path = \`${path.replace(/{/g, "${")}\`
            return armRequest({ host: configContext.ARM_ENDPOINT, path, method: "${method.toLocaleUpperCase()}", apiVersion, ${
          bodyParameter ? "body" : ""
        } })
          }
          `);
      }
    }
    writeOutputFile(`./${camelize(clientName)}.ts`, outputClient);
  }

  writeOutputFile("./types.ts", outputTypes);
}

function sanitize(name: string) {
  if (name === "delete") {
    return "destroy";
  }
  return name;
}

function writeOutputFile(outputPath: string, components: string[]) {
  components.unshift(`/* 
  AUTOGENERATED FILE
  Run "npm run generateARMClients" to regenerate
  Edting this file directly should be done with extreme caution as not to diverge from ARM REST specs

  Generated from: ${schemaURL}
*/\n\n`);
  writeFileSync(path.join(outputDir, outputPath), components.join(""));
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});