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

package/manifest.json

@@ -99,6 +99,10 @@
         {
             "name": "logger",
             "swagger": "https://api.compassdigital.org/dev/logger/swagger.json"
+        },
+        {
+            "name": "menu",
+            "swagger": "https://api.compassdigital.org/dev/menu/swagger.json"
         }
     ]
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@compassdigital/sdk.typescript",
-  "version": "3.0.0-beta.8",
+  "version": "3.0.0-rc.1",
   "description": "Compass Digital Labs TypeScript SDK",
   "type": "commonjs",
+  "bin": "./bin/index.js",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {
@@ -19,10 +20,14 @@
       ]
     }
   },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "gen": "npx ts-node gen.ts && npx tsc",
-    "prepare": "npx tsc"
+    "test": "jest",
+    "gen": "ts-node gen.ts --manifest ./manifest.json && tsc",
+    "prepare": "rimraf ./lib && tsc && tsc --esModuleInterop --outDir ./bin gen.ts"
   },
   "author": "",
   "license": "ISC",
@@ -32,10 +37,15 @@
   "devDependencies": {
     "@icholy/openapi-ts": "^2.5.1",
     "@types/ejs": "^3.1.0",
+    "@types/jest": "^27.0.1",
     "@types/node": "^16.7.2",
     "@types/prettier": "^2.3.2",
     "ejs": "^3.1.6",
+    "jest": "^27.1.0",
     "prettier": "^2.3.2",
-    "ts-node": "^10.2.1"
+    "rimraf": "^3.0.2",
+    "ts-jest": "^27.0.5",
+    "ts-node": "^10.2.1",
+    "yargs": "^17.1.1"
   }
 }

package/src/base.ts

@@ -2,19 +2,129 @@
 import fetch from "cross-fetch";
 
 export interface RequestOptions {
+  // environment to make requests to
   stage?: string;
-  headers?: Record<string, string>;
+  // authentication token
   token?: string;
+  // additional headers
+  headers?: Record<string, string>;
+  // log all requests and responses
   debug?: boolean;
+  // the number of times to retry a request
   retry?: number;
+  // make requests against this base url
+  // note: the stage property is ignored if base_url is set
   base_url?: string;
-  allow?: number[];
+  // intercept outgoing http requests
+  intercept?: InterceptFn;
+}
+
+/**
+ * The request data provided to intercept
+ * functions.
+ */
+export interface RequestData {
+  name: string;
+  service: string;
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+/**
+ * The response data expected from
+ * intercept functions.
+ */
+export interface ResponseData {
+  ok: boolean;
+  status: number;
+  body: string;
+  err?: any; // network error
+}
+
+/**
+ * A function that performs an https request.
+ */
+export type FetchFn = (req: RequestData) => Promise<ResponseData>;
+
+/**
+ * A function that intercepts an http request and returns a response.
+ */
+export 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 class ResponsePromise<T> implements Promise<T> {
+
+  /**
+   * Implements Promise interface.
+   */
+  [Symbol.toStringTag] = "[object ResponsePromise]";
+
+  constructor(private 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> {
+    return new ResponsePromise(this.promise.then(onfulfilled, onrejected));
+  }
+
+  /**
+   * Implements Promise interface.
+   */
+  catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): ResponsePromise<T | TResult> {
+    return new ResponsePromise(this.promise.catch(onrejected));
+  }
+
+  /**
+   * Implements Promise interface.
+   */
+  finally(onfinally?: (() => void) | null): ResponsePromise<T> {
+    return new ResponsePromise(this.promise.finally(onfinally));
+  }
+
+  /**
+   * 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> {
+    return new ResponsePromise(ServiceError.ignore(codes, this.promise));
+  }
+
+  /**
+   * Returns a promise that resolves to either the response body
+   * or a ServiceError.
+   */
+  combine(...codes: number[]): Promise<EitherResponse<T>> {
+    return new ResponsePromise(ServiceError.combine<T>(codes, this.promise));
+  }
 }
 
-export interface ServiceClientOptions extends Omit<RequestOptions, "allow"> {}
+/**
+ * Either a response body or a service error.
+ */
+export type EitherResponse<T> = { ok: true; data: T; err: null } | { ok: false; data: null, err: ServiceError; };
 
-export type ResponseType<T, Options extends RequestOptions> = Promise<T | (Options["allow"] extends number[] ? null : never)>;
+/**
+ * This is a hack to make captureStackTrace visible.
+ */
+interface ErrorConstructor {
+  captureStackTrace?(target: object, constructorOpt?: Function): void;
+}
 
+/**
+ * An error returned from an api service.
+ */
 export class ServiceError extends Error {
   constructor(
     public status: number, // http status
@@ -23,25 +133,118 @@ export class ServiceError extends Error {
   ) {
     super(message);
     this.name = `ServiceError(${code})`;
+
+    // TODO: remove this if we change compilation target > es5
+    Object.setPrototypeOf(this, ServiceError.prototype);
   }
 
-  static from_res(res: Response, message: string): ServiceError {
-    let code = res.status;
+  /**
+   * Returns the http status code from err.
+   * If err isn't an instance of ServiceError, -1 is returned.
+   */
+  static status(err: any): number {
+    if (err instanceof ServiceError) {
+      return err.status;
+    }
+    return -1;
+  }
+
+  /**
+   * Returns the service error code from err.
+   * If err isn't an instance of ServiceError, -1 is returned.
+   */
+  static code(err: any): number {
+    if (err instanceof ServiceError) {
+      return err.code;
+    }
+    return -1;
+  }
+
+  /**
+   * 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 async ignore<T>(codes: number[], response: Promise<T>): Promise<T | null> {
     try {
-      let data = JSON.parse(message);
-      if (data.code && (data.message || data.error)) {
-        code = data.code;
-        message = data.message || data.error;
+      return await response;
+    } catch (err) {
+      if (err instanceof ServiceError) {
+        if (codes.length === 0) {
+          return null;
+        }
+        for (const code of codes) {
+          if (err.status === code || err.code === code) {
+            return null;
+          }
+        }
       }
-    } catch (_) {}
-    return new ServiceError(res.status, code, message);
+      throw err;
+    }
+  }
+
+  /**
+   * Returns a promise that resolves to either T or a ServiceError.
+   */
+  static async combine<T>(codes: number[], response: Promise<T>): Promise<EitherResponse<T>> {
+    try {
+      const data = await response;
+      return { ok: true, data, err: null };
+    } catch (err) {
+      if (err instanceof ServiceError) {
+        if (codes.length === 0) {
+          return { ok: false, data: null, err }
+        }
+        for (const code of codes) {
+          if (err.status === code || err.code === code) {
+            return { ok: false, data: null, err };
+          }
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Constructs a ServiceError from the provided response data.
+   */
+  static from_res(res: ResponseData): ServiceError {
+    let message = res.body;
+    let code = res.status;
+    if (res.err) {
+      // network error
+      if (res.err instanceof Error) {
+        message = res.err.message;
+      } else {
+        message = "Network Error";
+      }
+      code = 0;
+    } else {
+      try {
+        let data = JSON.parse(res.body);
+        if (data.code && (data.message || data.error)) {
+          code = data.code;
+          message = data.message || data.error;
+        }
+      } catch (_) {}
+    }
+    const err = new ServiceError(res.status, code, message);
+    // override the stack trace so that it doesn't include the from_res helper.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(err, ServiceError.from_res);
+    }
+    return err;
   }
 }
 
+/**
+ * BaseServiceClient contains the logic for executing http requests.
+ * This class is meant to be extended by the generated code.
+ */
 export abstract class BaseServiceClient {
-  private options: ServiceClientOptions;
+  private options: RequestOptions;
 
-  constructor(options?: ServiceClientOptions) {
+  constructor(options?: RequestOptions) {
     this.options = options ?? {};
   }
 
@@ -68,50 +271,127 @@ export abstract class BaseServiceClient {
     return url;
   }
 
-  private is_4xx(res: Response): boolean {
-    return 400 <= res.status && res.status < 500;
+  /**
+   * Perform the http request or pass it to the intercept function
+   * if one was configured.
+   */
+  private async fetch(req: RequestData, options?: RequestOptions): Promise<ResponseData> {
+    if (options?.intercept) {
+      return options.intercept(req, this.fetch.bind(this));
+    }
+    try {
+      const res = await fetch(req.url, {
+        method: req.method,
+        body: req.body,
+        headers: req.headers,
+      });
+      return {
+        ok: res.ok,
+        status: res.status,
+        body: await res.text(),
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 0,
+        body: "",
+        err: err,
+      }
+    }
   }
 
-  protected async request(
+  /**
+   * Returns true if the status code represents a transient error
+   * or it's a network error.
+   */
+  private should_retry(res: ResponseData): boolean {
+    if (res.err) {
+      return true;
+    }
+    switch (res.status) {
+      case 408: // timeout
+      case 413: // too large
+      case 429: // too many requests
+      case 500: // generic error response
+      case 502: // invalid upstream response
+      case 503: // service unavailable
+      case 504: // gateway timeout
+      case 522: // tcp connection timeout
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Returns the merged options.
+   */
+  private get_options(options: RequestOptions): RequestOptions {
+    return {
+      ...this.options,
+      ...options,
+      headers: {
+        ...this.options.headers,
+        ...options.headers,
+      }
+    };
+  }
+
+  /**
+   * 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 = {}
+  ): ResponsePromise<any> {
+    const promise = this._request(service, name, method, route, body, options);
+    return new ResponsePromise(promise);
+  }
+
+  /**
+   * The main logic for fulfilling a request as perscribed by
+   * the request options.
+   */
+  private async _request(
+    service: string,
+    name: string,
     method: string,
     route: string,
     body: any,
     options: { query?: any } & RequestOptions = {}
   ): Promise<any> {
-    options = { ...this.options, ...options };
+    options = this.get_options(options);
     const url = this.build_url(route, options, options.query ?? {});
-    const headers = Object.assign({}, options.headers);
+    const headers = Object.assign({
+      "User-Agent": "CDL/ServiceClient"
+    }, options.headers);
     if (options.token) {
       headers["Authorization"] = `Bearer ${options.token}`;
     }
-    const req: RequestInit = {
-      method: method,
-      headers: headers,
-    };
+    const req: RequestData = { name, service, url, method, headers };
     if (body) {
       req.body = JSON.stringify(body);
     }
     if (options.debug) {
       console.log(`REQ(${method.toUpperCase()})`, url, JSON.stringify(req, null, 2));
     }
-    const res = await fetch(url, req);
+    const res = await this.fetch(req, options);
     if (!res.ok) {
-      for (const status of options.allow ?? []) {
-        if (res.status === status) {
-          return null;
-        }
-      }
-      const text = await res.text();
+      const err = ServiceError.from_res(res);
       if (options.debug) {
-        console.log(`ERR(${res.status})`, url, text);
+        console.log(`ERR(${res.status})`, url, err.message);
       }
-      if (typeof options.retry === "number" && options.retry > 0 && !this.is_4xx(res)) {
+      if (typeof options.retry === "number" && options.retry > 0 && this.should_retry(res)) {
         options.retry--;
-        return this.request(method, route, body, options);
+        return this.request(service, name, method, route, body, options);
       }
-      throw ServiceError.from_res(res, text);
+      throw err;
     }
-    const data = await res.json();
+    const data = res.body ? JSON.parse(res.body) : res.body;
     if (options.debug) {
       console.log(`RES(${res.status})`, url, JSON.stringify(data, null, 2));
     }