lemon-core 3.0.0 → 3.1.1

package/dist/cores/api/api-service.d.ts

@@ -0,0 +1,239 @@
+/**
+ * API headers.
+ */
+export interface APIHeaders {
+    [key: string]: string;
+}
+/**
+ * class: `APIServiceClient`
+ * - General API Request Client w/ url like `GET <endpoint>/<id>?/<cmd>?`
+ */
+export interface APIServiceClient {
+    hello(): string;
+    doGet<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPut<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPost<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPatch<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doDelete<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+}
+/**
+ * possible method.
+ */
+export declare type APIHttpMethod = 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE';
+/**
+ * class: `ApiHttpProxy`
+ * - http proxy service.
+ */
+export interface ApiHttpProxy {
+    /**
+     * say this service name.
+     */
+    hello(): string;
+    /**
+     * call http request via proxy server.
+     *
+     * url := `<host>/<path?>?<param>`
+     *
+     * @param method    http method
+     * @param host      host name (or https://~)
+     * @param path      object id
+     * @param param     query paramters
+     * @param body      body
+     * @param ctx       context
+     * @param hash      (optional) hash value (valid only for client-side).
+     */
+    doProxy<T = any>(method: APIHttpMethod, host: string, path?: string, param?: any, body?: any, ctx?: any, hash?: string): Promise<T>;
+}
+/**
+ * class: `APIProxyClient`
+ * - proxed APIServiceClient
+ */
+export declare class APIProxyClient implements APIServiceClient {
+    protected service: APIServiceClient;
+    constructor(service: APIServiceClient);
+    hello: () => string;
+    doGet<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPut<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPost<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPatch<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doDelete<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+}
+/**
+ * class: `APIService`
+ * - use internal http-proxy service due to restriction internet-face in VPC lambda.
+ */
+export declare class APIService implements APIServiceClient {
+    protected type: string;
+    protected endpoint: string;
+    protected headers: APIHeaders;
+    protected client: APIServiceClient;
+    /**
+     * create API service.
+     *
+     * ```js
+     * // basic
+     * const api = new API('web', 'http://localhost:8081', {});
+     * api.doGet('');
+     *
+     * // via python
+     * const api = new API('residents', 'http://localhost:8113', {});
+     * api.doGet('123');    // http GET :8113/residents/123
+     *
+     * // proxy server
+     * const api = new API('web', 'http://localhost:8081', {}, null, proxy);
+     * api.doGet('');
+     * ```
+     *
+     * @param type      type in endpoint
+     * @param endpoint  base endpoint (support ONLY http, https)
+     * @param headers   common headers.
+     * @param client    real api-client to use (or use proxy, or create default)
+     * @param proxy     proxy-service to use if there is no client (or use backbone server)
+     */
+    constructor(type: string, endpoint: string, headers?: APIHeaders, client?: APIServiceClient, proxy?: ApiHttpProxy);
+    hello: () => string;
+    /**
+     * helper to make http client
+     *
+     * @param backbone  backbone address like 'http://localhost:8081'
+     */
+    static buildClient(type: string, endpoint: string, headers?: APIHeaders, backbone?: string, proxy?: ApiHttpProxy): APIServiceClient;
+    /**
+     * make a client for sub-typed endpoint.
+     * @param type      sub-type path.
+     */
+    buildSubTypeClient(type: string, useRecord?: boolean, folder?: string): APIServiceClient;
+    /**
+     * make api recorder of this service.
+     * @param folder    base folder (default `./logs`)
+     */
+    buildRecorder(folder?: string): APIServiceClient;
+    /**
+     * class: `TypedEndpoint`
+     * - by using common proxy, extends endpoint by type.
+     * - endpoint := base+'/'+type.
+     */
+    private static ProxyServiceClient;
+    /**
+     * use sub-typed endpoint.
+     * - extends as endpoint := parent.endpoint + '/' + type
+     */
+    static SubTypeClient: {
+        new (parent: APIServiceClient, type: string): {
+            readonly parent: APIServiceClient;
+            readonly type: string;
+            hello: () => string;
+            asCmd: (id: string, cmd?: string) => string;
+            doGet(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPut(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPost(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPatch(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doDelete(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+        };
+    };
+    /**
+     * recorder of api-http-proxy client.
+     */
+    static ApiHttpProxyRecorder: {
+        new (target: ApiHttpProxy, folder?: string): {
+            readonly target: ApiHttpProxy;
+            readonly folder: string;
+            hello: () => string;
+            doProxy<T = any>(method: APIHttpMethod, host: string, path?: string, param?: any, body?: any, context?: any, hash?: string): Promise<T>;
+        };
+        next: number;
+    };
+    /**
+     * recorder of api-service client.
+     */
+    static APIServiceClientRecorder: {
+        new (target: APIServiceClient, endpoint: string, folder?: string): {
+            readonly target: APIServiceClient;
+            readonly endpoint: string;
+            readonly folder: string;
+            hello: () => string;
+            doRecord(method: APIHttpMethod, id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doGet(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPut(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPost(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doPatch(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+            doDelete(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<any>;
+        };
+        next: number;
+    };
+    /**
+     * GET HOST/PATH?$param
+     */
+    doGet: (id: string, cmd?: string, $param?: any, $body?: any, hash?: string) => Promise<any>;
+    /**
+     * PUT HOST/PATH?$param
+     */
+    doPut: (id: string, cmd?: string, $param?: any, $body?: any, hash?: string) => Promise<any>;
+    /**
+     * POST HOST/PATH?$param
+     */
+    doPost: (id: string, cmd?: string, $param?: any, $body?: any, hash?: string) => Promise<any>;
+    /**
+     * PATCH HOST/PATH?$param
+     */
+    doPatch: (id: string, cmd?: string, $param?: any, $body?: any, hash?: string) => Promise<any>;
+    /**
+     * DELETE HOST/PATH?$param
+     */
+    doDelete: (id: string, cmd?: string, $param?: any, $body?: any, hash?: string) => Promise<any>;
+}
+/**
+ * create http-web-proxy agent which using endpoint as proxy server.
+ *
+ * # as cases.
+ * as proxy agent: GET <endpoint>/<host?>/<path?>
+ * as direct agent: GET <endpoint>/<id?>/<cmd?>
+ *
+ * @param name              client-name
+ * @param endpoint          service url (or backbone proxy-url)
+ * @param headers           headers
+ * @param encoder           path encoder (default encodeURIComponent)
+ * @param relayHeaderKey    relay-key in headers for proxy.
+ * @param resultKey         resultKey in response
+ */
+export declare const createHttpWebProxy: (name: string, endpoint: string, headers?: APIHeaders, encoder?: (name: string, path: string) => string, relayHeaderKey?: string, resultKey?: string) => ApiHttpProxy;
+/** ********************************************************************************************************************
+ *  MOCKS API-SERVICE
+ ** ********************************************************************************************************************/
+/**
+ * class: `MocksAPIService`
+ * - use <mock>.json file in `./data/mocks/` instead of real http request.
+ * - it redirect to url like `endpoint/type/id/cmd`
+ *
+ * ```ts
+ * // json format
+ * {
+ *    param: {          // input format
+ *      method: string;
+ *      endpoint: string;
+ *      id?: string;
+ *      cmd?: string;
+ *    },
+ *    data: {           // response data
+ *      ...
+ *    },
+ *    error?: string;   // in case of error.
+ * }
+ * ```
+ */
+export declare class MocksAPIService implements ApiHttpProxy, APIServiceClient {
+    private $map;
+    private type;
+    private endpoint;
+    constructor(type: string, endpoint: string);
+    protected loadSync(): void;
+    protected asPath: (id?: string, cmd?: string) => string;
+    doProxy<T = any>(method: APIHttpMethod, type: string, path: string, param?: any, body?: any, ctx?: any, hash?: string): Promise<T>;
+    protected na: (a: any, x: string, y: string) => string;
+    hello: () => string;
+    doGet<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPut<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPost<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doPatch<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+    doDelete<T = any>(id: string, cmd?: string, param?: any, body?: any, hash?: string): Promise<T>;
+}