@compassdigital/sdk.typescript 3.14.0 → 3.15.0

package/gen.ts

@@ -1,442 +0,0 @@
-
-import fs from "fs";
-import {
-  analyse,
-  load,
-  Schema,
-  Printer,
-  DocumentDetails,
-  OperationDetails,
-  isMethod,
-} from "@icholy/openapi-ts";
-import prettier from "prettier";
-import path from "path";
-import ejs from "ejs";
-import yargs from "yargs/yargs";
-import { hideBin } from "yargs/helpers";
-
-interface Manifest {
-  services: ManifestService[];
-}
-
-interface ManifestService {
-  name: string; // service name
-  swagger: string; // swagger url or file
-}
-
-interface ClientImport {
-  path: string;
-  name: string;
-}
-
-interface MethodParam {
-  name: string;
-  type: string;
-  required: boolean;
-  description: string;
-}
-
-interface ClientMethod {
-  comment: string;
-  name: string;
-  params: MethodParam[];
-  args: string[];
-  response: string;
-}
-
-/**
- * The method and path combined into snake and pascal style names.
- */
- interface OperationName {
-  snake: string;  // used for method names
-  pascal: string; // used for type names
-}
-
-/**
- * This is a mapping between "${method} ${path}" and the default
- * operationId.
- */
-const operationIDs : Record<string, string> = {
-  "get /location/group/{id}/deliverydestination": "get_location_group_deliverydestinations",
-  "get /location/search":                         "get_location_search",
-  "get /promo":                                   "get_promos",
-  "get /schedule":                                "get_schedules",
-  "get /brand":                                   "get_brands",
-  "get /announcement/resource":                   "get_resources",
-  "get /order/location/brand/{id}":               "get_order_location_brand",
-};
-
-export class CodeGenerator {
-
-  private imports: ClientImport[] = [];
-  private methods: ClientMethod[] = [];
-
-  async manifest(manifest: Manifest): Promise<void> {
-    // generate service types
-    await fs.promises.mkdir(path.join("src", "interface"), { recursive: true });
-    for (const service of manifest.services) {
-      console.log(`reading: ${service.swagger}`);
-      const code = await this.service(service, false);
-      const filename = path.join("src", "interface", `${service.name}.ts`);
-      await fs.promises.writeFile(filename, code);
-    }
-    // generate client
-    const code = await this.client();
-    const filename = path.join("src", "index.ts");
-    await fs.promises.writeFile(filename, code);
-  }
-
-  async client(): Promise<string> {
-    const print = new Printer();
-    // "do not modify" warning
-    print.comment("THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY");
-    print.blank();
-    // client imports
-    const imports: Record<string, string[]> = {};
-    for (const _import of this.imports) {
-      imports[_import.path] ??= [];
-      imports[_import.path].push(_import.name);
-    }
-    for (const [path, names] of Object.entries(imports)) {
-      print.import(path, names);
-      print.blank();
-    }
-    // client methods
-    const template = fs.readFileSync("template.ejs", "utf-8");
-    print.raw(ejs.render(template, { methods: this.methods }));
-    return prettier.format(print.code(), { parser: "typescript", printWidth: 100 });
-  }
-
-  async service(service: ManifestService, ambient: boolean): Promise<string> {
-    const print = new Printer();
-    const doc = await load(service.swagger);
-    const details = analyse(doc);
-    this.transform(details, print, service, ambient);
-    return prettier.format(print.code(), { parser: "typescript", printWidth: 100 });
-  }
-
-  /**
-   * Add an import that the client will need.
-   */
-  private addImport(service: ManifestService, name: string): void {
-    this.imports.push({
-      name,
-      path: `./interface/${service.name}`,
-    });
-  }
-
-  /**
-   * Generate typescript code from the document details.
-   */
-  private transform(doc: DocumentDetails, print: Printer, service: ManifestService, ambient: boolean): void {
-    // "do not modify" warning
-    print.comment("THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY");
-    print.blank();
-    // declaration if it's ambient
-    if (ambient) {
-      print.raw(`declare module "@compassdigital/sdk.typescript/interface/${service.name}" {`);
-    }
-    // utility types
-    if (ambient) {
-      print.raw("export type RequestQuery<T extends object> = { [K in keyof T]: T[K] extends number|undefined ? string : T[K]; }");
-    } else {
-      print.import("./util", ["RequestQuery"]);
-    }
-    print.blank();
-    // definitions
-    for (const [name, schema] of Object.entries(doc.definitions)) {
-      // allow additional propties in meta objects.
-      const { meta } = schema.properties;
-      if (meta?.type === "object" && !meta.additional) {
-        meta.additional = new Schema();
-      }
-      print.schema(schema, name);
-      print.blank();
-    }
-    // routes
-    for (const op of doc.operations) {
-      const { params, path } = op;
-      for (const skipped of params.skipped) {
-        console.warn("SKIPPED", skipped);
-      }
-      // add missing path parameters
-      for (const name of this.findPathParams(path)) {
-        if (!params.path.properties[name]) {
-          params.path.setProperty(name, new Schema("string", {
-            required: true,
-            description: "TODO: add parameter to swagger.json",
-          }));
-        }
-      }
-      // make all path parameters required and valid path types.
-      for (const param of Object.values(params.path.properties)) {
-        if (!param.required) {
-          param.required = true;
-          if (param.description) {
-            param.description += "; ";
-          }
-          param.description += "TODO: mark parameter as required in swagger";
-        }
-        if (param.isRef() || param.type === "object") {
-          if (param.description) {
-            param.description += "; ";
-          }
-          param.description += `TODO: cannot use ${param.type} as path parameter`;
-          param.type = "string";
-        }
-      }
-      // add nocache query parameter if x-cache-control is specified
-      if (this.hasCacheControl(op) && !params.query.properties["nocache"]) {
-        params.query.setProperty("nocache", new Schema("boolean"));
-      }
-      const name = this.inferName(op, service);
-      let comment = `${op.method.toUpperCase()} ${path}`;
-      if (op.obj.summary) {
-        comment += ` - ${op.obj.summary}`;
-      }
-
-      print.comment(comment);
-      print.blank();
-      // path parameters
-      if (!params.path.isEmpty()) {
-        const pathT = `${name.pascal}Path`;
-        print.schema(params.path, pathT);
-        print.blank();
-      }
-      // query parameters
-      const queryT = `${name.pascal}Query`;
-      if (!params.query.isEmpty()) {
-        this.addImport(service, queryT);
-        print.schema(params.query, queryT);
-        print.blank();
-      }
-      // body
-      const bodyT = `${name.pascal}Body`;
-      if (!params.body.isEmpty()) {
-        this.addImport(service, bodyT);
-        print.schema(params.body, bodyT);
-        print.blank();
-      }
-      // response
-      const responseT = `${name.pascal}Response`;
-      this.addImport(service, responseT);
-      print.schema(params.response, responseT);
-      print.blank();
-      // server request
-      const requestT = `${name.pascal}Request`;
-      print.schema(this.toRequestSchema(name, op), requestT);
-      print.blank();
-
-      // method parameters
-      const method: ClientMethod = {
-        comment: comment,
-        name: name.snake,
-        params:[],
-        args: [`"${service.name}"`, `"${name.snake}"`, `"${op.method}"`],
-        response: responseT,
-      }
-      // turn the path into a template string and add the 
-      // corresponding method parameters.
-      let pathexpr = "`" + path + "`";
-      for (const name of this.findPathParams(path)) {
-        const schema = params.path.properties[name];
-        method.params.push({
-          name: name,
-          type: Printer.type(schema),
-          required: true,
-          description: schema.description,
-        });
-        pathexpr = pathexpr.replace(`{${name}}`, "${" + name + "}");
-      }
-      method.args.push(pathexpr);
-      // if there's a body, make that a parameter too.
-      if (!params.body.isEmpty()) {
-        method.params.push({
-          name: "body",
-          type: bodyT,
-          required: true,
-          description: params.body.description,
-        });
-        method.args.push("body");
-      } else {
-        method.args.push("null");
-      }
-      // build the options type.
-      const options = new Schema("empty");
-      if (!params.query.isEmpty()) {
-        const query = new Schema(queryT);
-        if (params.query.hasRequired()) {
-          query.required = true;
-          options.required = true;
-        }
-        options.setProperty("query", query);
-      }
-      options.merge(new Schema("RequestOptions"));
-      method.params.push({
-        name: "options",
-        type: Printer.type(options),
-        required: options.required,
-        description: "additional request options",
-      });
-      method.args.push("options");
-      this.methods.push(method);
-    }
-    // close declaration
-    if (ambient) {
-      print.raw(`}`);
-    }
-  }
-
-  /**
-   * Infer the operation name from the method and parameter.
-   * These are a bunch of dirty hacks to make the generated names consistent.
-   */
-  inferName(op: OperationDetails, service: ManifestService): OperationName {
-    let { method, path } = op;
-    let path_segments: string[] = [];
-    // use the operationId from our collection if we have one.
-    // TODO: update the swagger.json definitions so we don't need to do this.
-    let operationID: string | undefined = operationIDs[`${op.method} ${op.path}`];
-    if (!operationID) {
-      operationID = op.obj.operationId;
-    }
-    if (operationID) {
-      const parts = operationID.split("_");
-      if (parts.length > 1) {
-        // replace common operationId values with the canonical ones.
-        if (parts[0] === "create") {
-          parts[0] = "post";
-        }
-        if (parts[0] === "update") {
-          parts[0] = "put";
-        }
-        if (parts[0] === "remove") {
-          parts[0] = "delete";
-        }
-        if (parts[0] === "find") {
-          parts[0] = "get";
-        }
-        if (!isMethod(parts[0])) {
-          parts.unshift(method);
-        }
-        if (parts[0] === method) {
-          parts.shift(); // remove the method
-          if (!parts[0].startsWith(service.name)) {
-            parts.unshift(service.name);
-          }
-          path_segments = parts;
-        }
-      }
-      if (parts.length > 1 && parts[0] === method) {
-        parts.shift(); // remove the method
-        if (!parts[0].startsWith(service.name)) {
-          parts.unshift(service.name);
-        }
-        path_segments = parts;
-      }
-    }
-    // combined the path & method into a name.
-    if (path_segments.length === 0) {
-      if (path.endsWith(".json")) {
-        path = path.slice(0, -5);
-      }
-      path_segments = path.split("/").filter(segment => {
-        return segment != "" && !segment.includes("{");
-      });
-    }
-    const parts = [method.toLowerCase(), ...path_segments];
-    return {
-      snake: parts.join("_"),
-      pascal: parts.map(s => s.charAt(0).toUpperCase() + s.substr(1)).join(''),
-    };
-  }
-
-  /**
-   * Check if the any response has caching enabled.
-   */
-  private hasCacheControl(op: OperationDetails): boolean {
-    const responses = Object.values(op.obj.responses ?? {});
-    return responses.some(response => "x-cache-control" in response);
-  }
-
-  /**
-   * Find all the path parameter names.
-   */
-  private findPathParams(path: string): string[] {
-    const matches = path.matchAll(/{[^}]*}/g);
-    return Array.from(matches).map((match) => {
-      return match[0].slice(1, -1);
-    });
-  }
-
-  /**
-   * Create a Response type by combining the Query, Path, and Body types.
-   */
-  private toRequestSchema(name: OperationName, details: OperationDetails): Schema {
-    const request = new Schema("empty");
-    if (!details.params.body.isEmpty()) {
-      const body = new Schema(`${name.pascal}Body`);
-      body.required = true;
-      request.setProperty("body", body);
-    }
-    if (!details.params.query.isEmpty()) {
-      request.merge(new Schema(`RequestQuery<${name.pascal}Query>`));
-    }
-    if (!details.params.path.isEmpty()) {
-      request.merge(new Schema(`${name.pascal}Path`));
-    }
-    return request;
-  }
-}
-
-
-
-/**
- * Main entry point.
- */
-async function main() {
-  const { argv } = yargs(hideBin(process.argv))
-    .options("manifest", {
-      type: "string",
-      description: "manifest.json file to generate sdk from",
-    })
-    .options("swagger", {
-      type: "string",
-      description: "swagger.json file to generate interfaces from",
-    })
-    .options("service", {
-      type: "string",
-      description: "service name for generated interfaces",
-    })
-    .options("ambient", {
-      type: "boolean",
-      description: "wrap the types in a declare module directive",
-      default: true,
-    })
-  // generate sdk from manifest
-  if (argv.manifest) {
-    const data = await fs.promises.readFile(argv.manifest, "utf-8");
-    const manifest: Manifest = JSON.parse(data);
-    const gen = new CodeGenerator();
-    await gen.manifest(manifest);
-    return;
-  }
-  // generate interfaces for a single swagger.json
-  if (argv.swagger || argv.service) {
-    if (!argv.swagger) {
-      throw new Error(`--swagger must be provided with --service`);
-    }
-    if (!argv.service) {
-      throw new Error(`--service must be provided with --swagger`);
-    }
-    const gen = new CodeGenerator();
-    const code = await gen.service({
-      name: argv.service,
-      swagger: argv.swagger,
-    }, argv.ambient);
-    console.log(code);
-    return;
-  }
-}
-
-main().catch(err => console.error(err.message));

package/template.ejs

@@ -1,21 +0,0 @@
-
-import { BaseServiceClient, RequestOptions, ResponsePromise } from "./base";
-export * from "./base";
-
-export class ServiceClient extends BaseServiceClient {
-
-<% for (const {comment, name, params, args, response} of methods) { %>
-  /**
-   * <%- comment %>
-<% if (params.length > 0) {-%>
-   *
-<% } -%>
-<% for (const param of params) { -%>
-   * @param <%- param.name %><%- param.description ? " - " + param.description : "" %>
-<% } -%>
-   */
-  <%- name %>(<% for (let i = 0; i < params.length; i++) { %><%- i > 0 ? ", " : "" %><%- params[i].name %><%= params[i].required ? "" : "?" %>: <%- params[i].type %><% } %>): ResponsePromise<<%= response %>> {
-    return this.request(<% for (let i = 0; i < args.length; i++) { %><%- i > 0 ? ", " : "" %><%- args[i] %><% } %>);
-  }
-<% } %>
-}

package/test/gen.test.ts

@@ -1,22 +0,0 @@
-
-import { OperationObject, OperationParams, Schema } from "@icholy/openapi-ts";
-import { CodeGenerator } from "../gen";
-
-describe("CodeGenerator", () => {
-    describe("inferName", () => {
-        const gen = new CodeGenerator();
-        test("/order/location/brand/{id}", () => {
-            const op: OperationObject = {
-                operationId: "get_brand_orders",
-            }
-            const name = gen.inferName({
-                method: "get",
-                params: new OperationParams(op),
-                path: "/order/location/brand/{id}",
-                obj: op,
-            }, { name: "order", swagger: "" });
-            expect(name.pascal).toBe("GetOrderLocationBrand");
-            expect(name.snake).toBe("get_order_location_brand");
-        });
-    });
-});