xjs-common 8.5.0 → 9.0.0

package/README.md

@@ -11,7 +11,7 @@ npm i xjs-common
 **NOTE**: The versions <= `v6.2.0` was unpublished. If you has been used these versions, please update to the version >= `v7.0.0`.
 
 # Code example (only part)
- - Miscellaneous utilities.
+### Miscellaneous utilities.
 ```ts
 import { checkPortAvailability, delay, int2array, UFile, UHttp, retry } from "xjs-common";
 
@@ -41,7 +41,7 @@ import { checkPortAvailability, delay, int2array, UFile, UHttp, retry } from "xj
     UFile.mkdir(["path", "to", "dir"]);
 })();
 ```
- - Array utilities.
+### Array utilities.
 ```ts
 import { UArray } from "xjs-common";
 
@@ -70,7 +70,7 @@ import { UArray } from "xjs-common";
     console.log(UArray.randomPick(ary3));
 })();
 ```
- - String utilities.
+### String utilities.
 ```ts
 import { UString } from "xjs-common";
 
@@ -94,7 +94,7 @@ import { UString } from "xjs-common";
     console.log(UString.simpleTime({ date: getJSTDate(), unit: TimeUnit.Day }));
 })();
 ```
- - Http client enhanced for web scraping.
+### Enhanced http client.
 ```ts
 import { HttpResolver, s_clientMode } from "xjs-common";
 
@@ -103,28 +103,29 @@ import { HttpResolver, s_clientMode } from "xjs-common";
     // const http = new HttpResolver(chromeMajorVersion, logger);
     const http = new HttpResolver();
 
-    // switch tls ciphers order pattern by passing clientMode. (default is random between chrome or firefox.)
-    let body = await http.get("https://begyyal.net", { mode: s_clientMode.chrome });
+    // implicitly corresponds to cookies and redirect, and do randomization.
+    let res = await http.get("https://begyyal.net");
+    const { payload, headers } = res;
 
     // use proxy by passing the configuration.
     const proxy = { server: "proxy.sample.com", port: 8080, auth: { name: "prx", pass: "****" } }
-    body = await http.post("https://begyyal.net", { proxy });
+    res = await http.post("https://begyyal.net", { proxy });
 
-    // implicitly corresponds to cookies and redirect, and do randomization.
-    body = await http.get("https://begyyal.net");
+    // switch tls ciphers order pattern by passing clientMode. (default is random between chrome or firefox.)
+    res = await http.get("https://begyyal.net", { mode: s_clientMode.chrome });
 
     // download a file when [Content-Disposition: attachment] exists in the response.
     await http.get("https://begyyal.net/a.txt", { downloadPath: "/path/to/store" });
 
     // if you want to keep some states of requests (and suppress to randomize), it can create new context to do.
     const context = http.newContext();
-    body = await context.get("https://begyyal.net/1");
+    res = await context.get("https://begyyal.net/1");
     // this request sends with cookies that is set by precedent requests. 
     // in POST, payload is treated as json if it is an object.
-    body = await context.post("https://begyyal.net/2", { a: "b" });
+    res = await context.post("https://begyyal.net/2", { a: "b" });
 })();
 ```
- - Mark method as transaction.  
+### Mark method as transaction.  
 **NOTE**: this feature uses decorator, so requires `"experimentalDecorators": true` in tsconfig.
 ```ts
 import { transaction, delay } from "xjs-common";
@@ -149,7 +150,7 @@ class Cls {
     console.log(e);
 });
 ```
- - Validate and crop class fields.  
+### Validate and crop class fields.  
 **NOTE**: this feature uses decorator, so requires `"experimentalDecorators": true` in tsconfig.  
 **NOTE**: some functionalities  in this feature are based on `"useDefineForClassFields": true` in tsconfig.  
 this flag is true by default at the target higher than `ES2022`, [here is for more](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields).

package/dist/prcs/http/http-resolver-context.d.ts

@@ -1,5 +1,5 @@
 import { ClientMode } from "./http-resolver";
-import { ClientOption, IHttpClient, RequestOption } from "./i-http-client";
+import { ClientOption, HttpResponse, IHttpClient, RequestOption } from "./i-http-client";
 import { Loggable } from "../../const/types";
 export declare const s_clientMode: Record<string, ClientMode>;
 export declare class HttpResolverContext implements IHttpClient {
@@ -22,7 +22,7 @@ export declare class HttpResolverContext implements IHttpClient {
      */
     get(url: string, op?: RequestOption & {
         outerRedirectCount?: number;
-    }): Promise<any>;
+    }): Promise<HttpResponse>;
     /**
      * request POST to the url.
      * @param url target url.
@@ -32,7 +32,7 @@ export declare class HttpResolverContext implements IHttpClient {
      * @param op.downloadPath {@link RequestOption.downloadPath}
      * @returns string encoded by utf-8 as response payload.
      */
-    post(url: string, payload: any, op?: RequestOption): Promise<any>;
+    post(url: string, payload: any, op?: RequestOption): Promise<HttpResponse>;
     private createProxyAgent;
     private getIn;
     private postIn;

package/dist/prcs/http/http-resolver-context.js

@@ -215,7 +215,7 @@ class HttpResolverContext {
                 const stream = fs.createWriteStream(dest);
                 res.pipe(stream);
                 stream.on("finish", () => stream.close());
-                resolve({});
+                resolve({ headers: res.headers });
             }
             catch (e) {
                 this.error(e);
@@ -239,7 +239,7 @@ class HttpResolverContext {
                     reject(new xjs_err_1.XjsErr(s_errCode, `Https received a error status ${res.statusCode}`));
                 }
                 else
-                    resolve(data);
+                    resolve({ payload: data, headers: res.headers });
             }
             catch (e) {
                 reject(e);

package/dist/prcs/http/http-resolver.d.ts

@@ -1,6 +1,6 @@
 import { Loggable } from "../../const/types";
 import { HttpResolverContext } from "./http-resolver-context";
-import { ClientOption, IHttpClient, RequestOption } from "./i-http-client";
+import { ClientOption, HttpResponse, IHttpClient, RequestOption } from "./i-http-client";
 export interface ClientMode {
     id: number;
     cipherOrder: number[];
@@ -30,7 +30,7 @@ export declare class HttpResolver implements IHttpClient {
     newContext(op?: ClientOption): HttpResolverContext;
     get(url: string, op?: RequestOption & ClientOption & {
         redirectAsNewRequest?: boolean;
-    }): Promise<any>;
-    post(url: string, payload: any, op?: RequestOption & ClientOption): Promise<any>;
+    }): Promise<HttpResponse>;
+    post(url: string, payload: any, op?: RequestOption & ClientOption): Promise<HttpResponse>;
     private fixCmv;
 }

package/dist/prcs/http/i-http-client.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { OutgoingHttpHeaders } from "http";
+import { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
 import { ClientMode, ProxyConfig } from "./http-resolver";
 export interface ClientOption {
     mode?: ClientMode;
@@ -17,6 +17,16 @@ export interface RequestOption {
      */
     downloadPath?: string;
 }
+export interface HttpResponse {
+    /**
+     * http headers in the response.
+     */
+    headers?: IncomingHttpHeaders;
+    /**
+     * string encoded by utf-8 as response payload.
+     */
+    payload?: string;
+}
 export interface IHttpClient {
     /**
      * request GET to the url with new context.
@@ -27,11 +37,11 @@ export interface IHttpClient {
      * @param op.ignoreQuery {@link RequestOption.ignoreQuery}
      * @param op.downloadPath {@link RequestOption.downloadPath}
      * @param op.redirectAsNewRequest handle redirect as new request. this may be efficient when using proxy which is implemented reverse proxy.
-     * @returns string encoded by utf-8 as response payload.
+     * @returns http response. {@link HttpResponse}
      */
     get(url: string, op?: RequestOption & ClientOption & {
         redirectAsNewRequest?: boolean;
-    }): Promise<any>;
+    }): Promise<HttpResponse>;
     /**
      * request POST to the url with new context.
      * @param url target url.
@@ -41,7 +51,7 @@ export interface IHttpClient {
      * @param op.proxy proxy configuration.
      * @param op.ignoreQuery {@link RequestOption.ignoreQuery}
      * @param op.downloadPath {@link RequestOption.downloadPath}
-     * @returns string encoded by utf-8 as response payload.
+     * @returns http response. {@link HttpResponse}
      */
-    post(url: string, payload: any, op?: RequestOption & ClientOption): Promise<any>;
+    post(url: string, payload: any, op?: RequestOption & ClientOption): Promise<HttpResponse>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xjs-common",
-  "version": "8.5.0",
+  "version": "9.0.0",
   "description": "library modules for nodejs + typescript that bundled general-purpose implementations.",
   "repository": {
     "type": "git",