@compassdigital/sdk.typescript 3.0.0-beta.8 → 3.0.0-rc.1

package/gen.ts

@@ -12,6 +12,8 @@ import {
 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[];
@@ -60,28 +62,35 @@ const operationIDs : Record<string, string> = {
   "get /promo":                                   "get_promos",
   "get /schedule":                                "get_schedules",
   "get /brand":                                   "get_brands",
-  "get /announcement/resource":                   "get_resources"
+  "get /announcement/resource":                   "get_resources",
+  "get /order/location/brand/{id}":               "get_order_location_brand",
 };
 
-class CodeGenerator {
+export class CodeGenerator {
 
   private imports: ClientImport[] = [];
   private methods: ClientMethod[] = [];
 
-  async generate(manifest: Manifest): Promise<void> {
+  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) {
-      const print = new Printer();
       console.log(`reading: ${service.swagger}`);
-      const doc = await load(service.swagger);
-      const details = analyse(doc);
-      this.transform(details, print, service);
-      const code = prettier.format(print.code(), { parser: "typescript", printWidth: 100 });
-      const filename = path.join("src", `${service.name}.ts`);
-      fs.writeFileSync(filename, code);
+      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) {
@@ -95,9 +104,15 @@ class CodeGenerator {
     // client methods
     const template = fs.readFileSync("template.ejs", "utf-8");
     print.raw(ejs.render(template, { methods: this.methods }));
-    const code = prettier.format(print.code(), { parser: "typescript", printWidth: 100 });
-    const filename = path.join("src", "index.ts");
-    fs.writeFileSync(filename, code);
+    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 });
   }
 
   /**
@@ -106,14 +121,21 @@ class CodeGenerator {
   private addImport(service: ManifestService, name: string): void {
     this.imports.push({
       name,
-      path: `./${service.name}`,
+      path: `./interface/${service.name}`,
     });
   }
 
   /**
    * Generate typescript code from the document details.
    */
-  private transform(doc: DocumentDetails, print: Printer, service: ManifestService): void {
+  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}" {`);
+    }
     // definitions
     for (const [name, schema] of Object.entries(doc.definitions)) {
       print.schema(schema, name);
@@ -151,6 +173,10 @@ class CodeGenerator {
           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) {
@@ -194,7 +220,7 @@ class CodeGenerator {
         comment: comment,
         name: name.snake,
         params:[],
-        args: [`"${op.method}"`],
+        args: [`"${service.name}"`, `"${name.snake}"`, `"${op.method}"`],
         response: responseT,
       }
       // turn the path into a template string and add the 
@@ -233,7 +259,7 @@ class CodeGenerator {
         }
         options.setProperty("query", query);
       }
-      options.merge(new Schema("Options"));
+      options.merge(new Schema("RequestOptions"));
       method.params.push({
         name: "options",
         type: Printer.type(options),
@@ -243,13 +269,17 @@ class CodeGenerator {
       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.
    */
-  private inferName(op: OperationDetails, service: ManifestService): OperationName {
+  inferName(op: OperationDetails, service: ManifestService): OperationName {
     let { method, path } = op;
     let path_segments: string[] = [];
     // use the operationId from our collection if we have one.
@@ -309,6 +339,14 @@ class CodeGenerator {
     };
   }
 
+  /**
+   * 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.
    */
@@ -337,25 +375,6 @@ class CodeGenerator {
     }
     return request;
   }
-
-  /**
-   * Create the type for the client method parameter.
-   */
-  private toOptionsSchema(name: OperationName, details: OperationDetails): Schema {
-    const options = new Schema("empty");
-    if (!details.params.query.isEmpty()) {
-      const query = new Schema(`${name.pascal}Query`);
-      if (details.params.query.hasRequired()) {
-        query.required = true;
-      }
-      options.setProperty("query", query);
-    }
-    if (options.hasRequired()) {
-      options.required = true;
-    }
-    options.merge(new Schema("RequestOptions"));
-    return options;
-  }
 }
 
 
@@ -364,9 +383,48 @@ class CodeGenerator {
  * Main entry point.
  */
 async function main() {
-  const manifest: Manifest = JSON.parse(await fs.promises.readFile("manifest.json", "utf-8"));
-  const gen = new CodeGenerator();
-  await gen.generate(manifest);
+  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();
+main().catch(err => console.error(err.message));

package/lib/base.d.ts

@@ -1,33 +1,158 @@
 export interface RequestOptions {
     stage?: string;
-    headers?: Record<string, string>;
     token?: string;
+    headers?: Record<string, string>;
     debug?: boolean;
     retry?: number;
     base_url?: string;
-    allow?: number[];
+    intercept?: InterceptFn;
 }
-export interface ServiceClientOptions extends Omit<RequestOptions, "allow"> {
+/**
+ * The request data provided to intercept
+ * functions.
+ */
+export interface RequestData {
+    name: string;
+    service: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
 }
-export declare type ResponseType<T, Options extends RequestOptions> = Promise<T | (Options["allow"] extends number[] ? null : never)>;
+/**
+ * The response data expected from
+ * intercept functions.
+ */
+export interface ResponseData {
+    ok: boolean;
+    status: number;
+    body: string;
+    err?: any;
+}
+/**
+ * A function that performs an https request.
+ */
+export declare type FetchFn = (req: RequestData) => Promise<ResponseData>;
+/**
+ * A function that intercepts an http request and returns a response.
+ */
+export declare type InterceptFn = (req: RequestData, fetch: FetchFn) => Promise<ResponseData>;
+/**
+ * We have to re-implement the promise methods instead of just existing
+ * the existing Promise class due to: https://github.com/microsoft/TypeScript/issues/15202
+ */
+export declare class ResponsePromise<T> implements Promise<T> {
+    private promise;
+    /**
+     * Implements Promise interface.
+     */
+    [Symbol.toStringTag]: string;
+    constructor(promise: Promise<T>);
+    /**
+     * Implements Promise interface.
+     */
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): ResponsePromise<TResult1 | TResult2>;
+    /**
+     * Implements Promise interface.
+     */
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): ResponsePromise<T | TResult>;
+    /**
+     * Implements Promise interface.
+     */
+    finally(onfinally?: (() => void) | null): ResponsePromise<T>;
+    /**
+     * Returns a promise that resolves to null if http status code
+     * or service error code matches one of the provided codes.
+     * If no codes are specified, all codes are ignored.
+     */
+    ignore(...codes: number[]): ResponsePromise<T | null>;
+    /**
+     * Returns a promise that resolves to either the response body
+     * or a ServiceError.
+     */
+    combine(...codes: number[]): Promise<EitherResponse<T>>;
+}
+/**
+ * Either a response body or a service error.
+ */
+export declare type EitherResponse<T> = {
+    ok: true;
+    data: T;
+    err: null;
+} | {
+    ok: false;
+    data: null;
+    err: ServiceError;
+};
+/**
+ * An error returned from an api service.
+ */
 export declare class ServiceError extends Error {
     status: number;
     code: number;
     constructor(status: number, // http status
     code: number, // service error code
     message: string);
-    static from_res(res: Response, message: string): ServiceError;
+    /**
+     * Returns the http status code from err.
+     * If err isn't an instance of ServiceError, -1 is returned.
+     */
+    static status(err: any): number;
+    /**
+     * Returns the service error code from err.
+     * If err isn't an instance of ServiceError, -1 is returned.
+     */
+    static code(err: any): number;
+    /**
+     * Returns a promise that resolves to null if http status code
+     * or service error code matches one of the provided codes.
+     * If no codes are specified, all codes are ignored.
+     */
+    static ignore<T>(codes: number[], response: Promise<T>): Promise<T | null>;
+    /**
+     * Returns a promise that resolves to either T or a ServiceError.
+     */
+    static combine<T>(codes: number[], response: Promise<T>): Promise<EitherResponse<T>>;
+    /**
+     * Constructs a ServiceError from the provided response data.
+     */
+    static from_res(res: ResponseData): ServiceError;
 }
+/**
+ * BaseServiceClient contains the logic for executing http requests.
+ * This class is meant to be extended by the generated code.
+ */
 export declare abstract class BaseServiceClient {
     private options;
-    constructor(options?: ServiceClientOptions);
+    constructor(options?: RequestOptions);
     /**
      * Combine the route and query parameters into a full url.
      */
     private build_url;
-    private is_4xx;
-    protected request(method: string, route: string, body: any, options?: {
+    /**
+     * Perform the http request or pass it to the intercept function
+     * if one was configured.
+     */
+    private fetch;
+    /**
+     * Returns true if the status code represents a transient error
+     * or it's a network error.
+     */
+    private should_retry;
+    /**
+     * Returns the merged options.
+     */
+    private get_options;
+    /**
+     * A delegate to _request that wraps the response in a ResponsePromise.
+     */
+    protected request(service: string, name: string, method: string, route: string, body: any, options?: {
         query?: any;
-    } & RequestOptions): Promise<any>;
+    } & RequestOptions): ResponsePromise<any>;
+    /**
+     * The main logic for fulfilling a request as perscribed by
+     * the request options.
+     */
+    private _request;
 }
 //# sourceMappingURL=base.d.ts.map

package/lib/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC;CAAG;AAE9E,oBAAY,YAAY,CAAC,CAAC,EAAE,OAAO,SAAS,cAAc,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC;AAE9H,qBAAa,YAAa,SAAQ,KAAK;IAE5B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EAAE,cAAc;IAC9B,IAAI,EAAE,MAAM,EAAI,qBAAqB;IAC5C,OAAO,EAAE,MAAM;IAMjB,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY;CAW9D;AAED,8BAAsB,iBAAiB;IACrC,OAAO,CAAC,OAAO,CAAuB;gBAE1B,OAAO,CAAC,EAAE,oBAAoB;IAI1C;;OAEG;IACH,OAAO,CAAC,SAAS;IAoBjB,OAAO,CAAC,MAAM;cAIE,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,GAAG,EACT,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,cAAmB,GAC7C,OAAO,CAAC,GAAG,CAAC;CAwChB"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"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"}