@compassdigital/sdk.typescript 3.0.0-beta.10 → 3.0.0-beta.12

package/src/base.ts

@@ -19,6 +19,10 @@ export interface RequestOptions {
   intercept?: InterceptFn;
 }
 
+/**
+ * The request data provided to intercept
+ * functions.
+ */
 export interface RequestData {
   name: string;
   service: string;
@@ -28,23 +32,91 @@ export interface RequestData {
   body?: string;
 }
 
+/**
+ * The response data expected from
+ * intercept functions.
+ */
 export interface ResponseData {
   ok: boolean;
   status: number;
   body: string;
 }
 
+/**
+ * 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>;
 
-export type ServiceRequestOptions = Omit<RequestOptions, "allow">;
+/**
+ * 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> {
 
-export interface ServiceClientOptions extends ServiceRequestOptions {
-  services?: Record<string, ServiceRequestOptions>;
-  methods?: Record<string, ServiceRequestOptions>;
+  /**
+   * 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(): Promise<EitherResponse<T>> {
+    return new ResponsePromise(ServiceError.combine<T>(this.promise));
+  }
 }
 
+/**
+ * Either a response body or a service error.
+ */
+type EitherResponse<T> = { ok: true; body: T; err?: ServiceError } | { ok: false; body?: T, err: ServiceError; };
+
+/**
+ * An error returned from an api service.
+ */
 export class ServiceError extends Error {
   constructor(
     public status: number, // http status
@@ -58,6 +130,10 @@ export class ServiceError extends Error {
     Object.setPrototypeOf(this, ServiceError.prototype);
   }
 
+  /**
+   * 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;
@@ -65,6 +141,10 @@ export class ServiceError extends Error {
     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;
@@ -72,11 +152,19 @@ export class ServiceError extends Error {
     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 {
       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;
@@ -87,6 +175,24 @@ export class ServiceError extends Error {
     }
   }
 
+  /**
+   * Returns a promise that resolves to either T or a ServiceError.
+   */
+  static async combine<T>(response: Promise<T>): Promise<EitherResponse<T>> {
+    try {
+      const body = await response;
+      return { ok: true, body };
+    } catch (err) {
+      if (err instanceof ServiceError) {
+        return { ok: false, 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;
@@ -101,10 +207,14 @@ export class ServiceError extends Error {
   }
 }
 
+/**
+ * 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 ?? {};
   }
 
@@ -131,6 +241,10 @@ export abstract class BaseServiceClient {
     return url;
   }
 
+  /**
+   * 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));
@@ -147,28 +261,47 @@ export abstract class BaseServiceClient {
     };
   }
 
+  /**
+   * Returns true if the response status was a 4xx error.
+   */
   private is_4xx(res: ResponseData): boolean {
     return 400 <= res.status && res.status < 500;
   }
 
-  private get_options(service: string, name: string, options: RequestOptions): RequestOptions {
-    const service_options = this.options.services?.[service];
-    const method_options = this.options.methods?.[name];
+  /**
+   * Returns the merged options.
+   */
+  private get_options(options: RequestOptions): RequestOptions {
     return {
       ...this.options,
-      ...service_options,
-      ...method_options,
       ...options,
       headers: {
         ...this.options.headers,
-        ...method_options?.headers,
-        ...service_options?.headers,
         ...options.headers,
       }
     };
   }
 
-  protected async request(
+  /**
+   * 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,
@@ -176,7 +309,7 @@ export abstract class BaseServiceClient {
     body: any,
     options: { query?: any } & RequestOptions = {}
   ): Promise<any> {
-    options = this.get_options(service, name, options);
+    options = this.get_options(options);
     const url = this.build_url(route, options, options.query ?? {});
     const headers = Object.assign({
       "User-Agent": "CDL/ServiceClient"