keq 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.3.0](https://github.com/keq-request/keq/compare/v2.2.0...v2.3.0) (2024-02-24)
+
+
+### Features
+
+* add .resolveWith method add deprecated resolveWithFullResponse ([1e01e7f](https://github.com/keq-request/keq/commit/1e01e7fe07c146d9f122f0f52778b45258797c68))
+
 ## [2.2.0](https://github.com/keq-request/keq/compare/v2.1.2...v2.2.0) (2024-02-04)
 
 

package/README.md

@@ -82,20 +82,22 @@ await request.del("https://example.com/search");
 > `.del()` is the alias of `.delete()`.
 
 `Keq` will parse `body` according to the `Content-Type` of [`Response`][Response MDN]
-and return `body` of [`Response`][Response MDN] by defaulted.
-Add option `resolveWithFullResponse` to get the origin [`Response`][Response MDN] Object.
+and return `undefined` if `Content-Type` not found.
+Add invoke `.resolveWith('response')` to get the origin [`Response`][Response MDN] Object.
 
 ```javascript
 import { request } from "keq";
 
 const response = await request
   .get("http://test.com")
-  .option("resolveWithFullResponse");
+  .resolve('response')
 
 const body = await response.json();
 ```
 
-###### `Keq` won't auto parse body, if response.status is 204. The HTTP 204 No Content success status response code indicates that server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
+We will introduce `resolveWith` in more detail later.
+
+###### `Keq` won't auto parse body, if response.status is 204. The HTTP 204 No Content success status response code indicates that server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information
 
 ### Setting header fields
 
@@ -269,6 +271,22 @@ await request
 | jpeg, bmp, apng, gif, x-icon, png, webp, tiff | image/jpeg, image/bmp, image/apng, image/gif, image/x-icon, image/png, image/webp, image/tiff |
 | svg                                           | image/svg+xml                                                                                 |
 
+### resolve responseBody
+
+It was mentioned before that `Keq` will automatically parses the response body.
+And we can control the parsing behavior by calling `.resolveWith(method)`.
+There are multiple parsing methods for us to choose from
+
+| method                       | description                                                                                                                                                                                          |
+| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.resolveWith('intelligent')`  | It is the default method of `Keq`. This will returned `context.output` first if it exists. Otherwise return undefined when the response status is 204. Or return parsed response body according to the `Content-Type` of [`Response`][Response MDN]. |
+| `.resolveWith('response')`     | Return [`Response`][Response MDN].                                                                                                                                                                   |
+| `.resolveWith('text')`         | Return `response.text()`.                                                                                                                                                                            |
+| `.resolveWith('json')`         | Return `response.json()`.                                                                                                                                                                            |
+| `.resolveWith('form-data')`    | Return `response.formData()`.                                                                                                                                                                        |
+| `.resolveWith('blob')`         | Return `response.blob()`.                                                                                                                                                                            |
+| `.resolveWith('array-buffer')` | Return `response.arrayBuffer()`                                                                                                                                                                      |
+
 ### Request Retry
 
 No retry by default, invoke `.retry(retryTimes[, retryDelay[, retryOn]])` to set retry parameters
@@ -328,11 +346,6 @@ import { request } from "keq";
 
 const response = await request
   .get("http://test.com")
-  /**
-   * keq will return Response rather than parsed body
-   * when set resolveWithFullResponse
-   */
-  .option("resolveWithFullResponse")
   .option("middlewareOption", "value");
 ```
 
@@ -344,14 +357,12 @@ import { request } from "keq";
 await request
   .get("http://test.com")
   .options({
-    resolveWithFullResponse: true,
     middlewareOption: "value",
   });
 ```
 
 | **Option**                | **Description**                                                                                         |
 | :------------------------ | :------------------------------------------------------------------------------------------------------ |
-| `resolveWithFullResponse` | Get the [`Response`][Response MDN] Class. This is the `.clone()` of original [`Response`][Response MDN] |
 | `fetchAPI`                | Replace the defaulted `fetch` function used by `Keq`.                                                   |
 
 <!-- ###### The options with **DEPRECATED** will be removed in next major version -->
@@ -431,7 +442,7 @@ const middleware = async (context, next) => {
   const body = await response.json()
 
   // custom keq return type
-  response.output = JSON.stringify(body)
+  context.output = JSON.stringify(body)
 }
 
 // Global Middleware
@@ -510,10 +521,10 @@ Keq's context object has many parameters. The following lists all the built-in c
 | `context.request.referrer`       | `referrer` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                    |
 | `context.request.referrerPolicy` | `referrerPolicy` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                              |
 | `context.request.signal`         | `signal` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                      |
-| `context.options`                | It is an object includes request options.(example: `context.options.resolveWithFullResponse`). Middleware can get custom options from here.                                                                                       |
+| `context.options`                | It is an object includes request options.(example: `context.options.fetchAPI`). Middleware can get custom options from here.                                                                                       |
 | `context.res`                    | The origin [`Response`][Response MDN] Class. It will be undefined before run `await next()` or error throwed.                                                                                                                     |
 | `context.response`               | Cloned from `ctx.res`.                                                                                                                                                                                                            |
-| `context.output`                 | The return value of `await request()`. By defaulted, `context.output` is the parsed body of response. `context.output` will be the `ctx.response` When `options.resolveWithFullResponse` is true. **This property is writeonly.** |
+| `context.output`                 | Custom return value of `await request()`。 It only take effect when `resolveWith` is not set or set to 'intelligent'. **This property is writeonly.** |
 
 #### .useRouter()
 

package/dist/esm/src/core.js

@@ -13,7 +13,10 @@ export class Core {
     __global__;
     __prepend_middlewares__ = [];
     __append_middlewares__ = [];
-    __options__ = { resolveWithFullResponse: false };
+    __options__ = {
+        resolveWithFullResponse: false,
+        resolveWith: 'intelligent',
+    };
     constructor(url, init, global = {}) {
         this.__global__ = global;
         this.requestContext = {
@@ -69,39 +72,58 @@ export class Core {
         const middleware = composeMiddleware([...this.__prepend_middlewares__, ...this.__append_middlewares__]);
         // eslint-disable-next-line @typescript-eslint/no-empty-function
         await middleware(ctx, async () => { });
-        let output = ctx[OUTPUT_PROPERTY];
-        if (ctx.options.resolveWithFullResponse) {
+        const output = ctx[OUTPUT_PROPERTY];
+        if (ctx.options.resolveWithFullResponse || ctx.options.resolveWith === 'response') {
             return ctx.response;
         }
-        if (!(OUTPUT_PROPERTY in ctx)) {
-            const response = ctx.response;
-            if (response?.status === 204) {
-                // 204: NO CONTENT
-                output = response && response.body;
+        const response = ctx.response;
+        if (!response) {
+            return (OUTPUT_PROPERTY in ctx) ? output : undefined;
+        }
+        if (ctx.options.resolveWith === 'text') {
+            return await response.text();
+        }
+        else if (ctx.options.resolveWith === 'json') {
+            return await response.json();
+        }
+        else if (ctx.options.resolveWith === 'form-data') {
+            return await response.formData();
+        }
+        else if (ctx.options.resolveWith === 'blob') {
+            return await response.blob();
+        }
+        else if (ctx.options.resolveWith === 'array-buffer') {
+            return await response.arrayBuffer();
+        }
+        if (OUTPUT_PROPERTY in ctx) {
+            return output;
+        }
+        if (response.status === 204) {
+            // 204: NO CONTENT
+            return undefined;
+        }
+        const contentType = response.headers.get('content-type') || '';
+        try {
+            if (contentType.includes('application/json')) {
+                return await response.json();
             }
-            else {
-                const headers = response?.headers;
-                const contentType = headers?.get('content-type') || '';
-                try {
-                    if (contentType.includes('application/json')) {
-                        output = ctx.response && await ctx.response.json();
-                    }
-                    else if (contentType.includes('multipart/form-data')) {
-                        output = ctx.response && await ctx.response.formData();
-                    }
-                    else if (contentType.includes('plain/text')) {
-                        output = ctx.response && await ctx.response.text();
-                    }
-                    else {
-                        output = ctx.response && ctx.response.body;
-                    }
-                }
-                catch (e) {
-                    console.warn('Failed to auto parse response body', e);
-                }
+            else if (contentType.includes('multipart/form-data')) {
+                return await response.formData();
             }
+            else if (contentType.includes('plain/text')) {
+                return await response.text();
+            }
+        }
+        catch (e) {
+            console.warn('Failed to auto parse response body', e);
         }
-        return output;
+        /**
+         * Unable to parse response body
+         * Return undefined
+         * Enable users to discover the problem
+         * And modify the method of parsing response
+         */
+        return undefined;
     }
     async end() {
         return this.run();

package/dist/esm/src/keq.d.ts

@@ -71,4 +71,9 @@ export declare class Keq<T> extends Core<T> {
     mode(mod: RequestMode): this;
     flowControl(mode: KeqFlowControlMode, signal?: KeqFlowControlSignal): this;
     timeout(milliseconds: number): this;
+    resolveWith(m: 'response'): Keq<Response>;
+    resolveWith(m: 'array-buffer'): Keq<ArrayBuffer>;
+    resolveWith(m: 'blob'): Keq<Blob>;
+    resolveWith(m: 'text'): Keq<string>;
+    resolveWith<U = any>(m: 'json' | 'form-data'): Keq<U>;
 }

package/dist/esm/src/keq.js

@@ -200,4 +200,9 @@ export class Keq extends Core {
         this.option('timeout', { millisecond: milliseconds });
         return this;
     }
+    resolveWith(m) {
+        this.option('resolveWith', m);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this;
+    }
 }

package/dist/esm/src/types/keq-options.d.ts

@@ -1,4 +1,5 @@
 import { KeqFlowControl } from './keq-flow-control.js';
+import { KeqResolveMethod } from './keq-resolve-with-mode.js';
 import { KeqRetryDelay } from './keq-retry-delay';
 import { KeqRetryOn } from './keq-retry-on';
 import { KeqTimeout } from './keq-timeout.js';
@@ -8,8 +9,17 @@ export interface KeqBuildInOptions {
      * default use node-fetch@2 in node and window.fetch in browser
      */
     fetchAPI?: typeof fetch;
-    /** get response object, defaulted `false` */
+    /**
+     * get response object, defaulted `false`
+     * @deprecated use `resolveWith` instead
+     * */
     resolveWithFullResponse?: boolean;
+    /**
+     * how to resolve the response body
+     * @description 如何解析响应体
+     * @default 'intelligent'
+     */
+    resolveWith?: KeqResolveMethod;
     /**
      * The request retry times
      * @description 重试次数

package/dist/esm/src/types/keq-resolve-with-mode.d.ts

@@ -0,0 +1 @@
+export type KeqResolveMethod = 'intelligent' | 'response' | 'text' | 'json' | 'form-data' | 'blob' | 'array-buffer';

package/dist/esm/src/types/keq-resolve-with-mode.js

@@ -0,0 +1 @@
+export {};

package/dist/umd/src/core.js

@@ -25,7 +25,10 @@
         __global__;
         __prepend_middlewares__ = [];
         __append_middlewares__ = [];
-        __options__ = { resolveWithFullResponse: false };
+        __options__ = {
+            resolveWithFullResponse: false,
+            resolveWith: 'intelligent',
+        };
         constructor(url, init, global = {}) {
             this.__global__ = global;
             this.requestContext = {
@@ -81,39 +84,58 @@
             const middleware = (0, compose_middleware_1.composeMiddleware)([...this.__prepend_middlewares__, ...this.__append_middlewares__]);
             // eslint-disable-next-line @typescript-eslint/no-empty-function
             await middleware(ctx, async () => { });
-            let output = ctx[constant_1.OUTPUT_PROPERTY];
-            if (ctx.options.resolveWithFullResponse) {
+            const output = ctx[constant_1.OUTPUT_PROPERTY];
+            if (ctx.options.resolveWithFullResponse || ctx.options.resolveWith === 'response') {
                 return ctx.response;
             }
-            if (!(constant_1.OUTPUT_PROPERTY in ctx)) {
-                const response = ctx.response;
-                if (response?.status === 204) {
-                    // 204: NO CONTENT
-                    output = response && response.body;
+            const response = ctx.response;
+            if (!response) {
+                return (constant_1.OUTPUT_PROPERTY in ctx) ? output : undefined;
+            }
+            if (ctx.options.resolveWith === 'text') {
+                return await response.text();
+            }
+            else if (ctx.options.resolveWith === 'json') {
+                return await response.json();
+            }
+            else if (ctx.options.resolveWith === 'form-data') {
+                return await response.formData();
+            }
+            else if (ctx.options.resolveWith === 'blob') {
+                return await response.blob();
+            }
+            else if (ctx.options.resolveWith === 'array-buffer') {
+                return await response.arrayBuffer();
+            }
+            if (constant_1.OUTPUT_PROPERTY in ctx) {
+                return output;
+            }
+            if (response.status === 204) {
+                // 204: NO CONTENT
+                return undefined;
+            }
+            const contentType = response.headers.get('content-type') || '';
+            try {
+                if (contentType.includes('application/json')) {
+                    return await response.json();
                 }
-                else {
-                    const headers = response?.headers;
-                    const contentType = headers?.get('content-type') || '';
-                    try {
-                        if (contentType.includes('application/json')) {
-                            output = ctx.response && await ctx.response.json();
-                        }
-                        else if (contentType.includes('multipart/form-data')) {
-                            output = ctx.response && await ctx.response.formData();
-                        }
-                        else if (contentType.includes('plain/text')) {
-                            output = ctx.response && await ctx.response.text();
-                        }
-                        else {
-                            output = ctx.response && ctx.response.body;
-                        }
-                    }
-                    catch (e) {
-                        console.warn('Failed to auto parse response body', e);
-                    }
+                else if (contentType.includes('multipart/form-data')) {
+                    return await response.formData();
                 }
+                else if (contentType.includes('plain/text')) {
+                    return await response.text();
+                }
+            }
+            catch (e) {
+                console.warn('Failed to auto parse response body', e);
             }
-            return output;
+            /**
+             * Unable to parse response body
+             * Return undefined
+             * Enable users to discover the problem
+             * And modify the method of parsing response
+             */
+            return undefined;
         }
         async end() {
             return this.run();

package/dist/umd/src/keq.d.ts

@@ -71,4 +71,9 @@ export declare class Keq<T> extends Core<T> {
     mode(mod: RequestMode): this;
     flowControl(mode: KeqFlowControlMode, signal?: KeqFlowControlSignal): this;
     timeout(milliseconds: number): this;
+    resolveWith(m: 'response'): Keq<Response>;
+    resolveWith(m: 'array-buffer'): Keq<ArrayBuffer>;
+    resolveWith(m: 'blob'): Keq<Blob>;
+    resolveWith(m: 'text'): Keq<string>;
+    resolveWith<U = any>(m: 'json' | 'form-data'): Keq<U>;
 }

package/dist/umd/src/keq.js

@@ -212,6 +212,11 @@
             this.option('timeout', { millisecond: milliseconds });
             return this;
         }
+        resolveWith(m) {
+            this.option('resolveWith', m);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return this;
+        }
     }
     exports.Keq = Keq;
 });

package/dist/umd/src/types/keq-options.d.ts

@@ -1,4 +1,5 @@
 import { KeqFlowControl } from './keq-flow-control.js';
+import { KeqResolveMethod } from './keq-resolve-with-mode.js';
 import { KeqRetryDelay } from './keq-retry-delay';
 import { KeqRetryOn } from './keq-retry-on';
 import { KeqTimeout } from './keq-timeout.js';
@@ -8,8 +9,17 @@ export interface KeqBuildInOptions {
      * default use node-fetch@2 in node and window.fetch in browser
      */
     fetchAPI?: typeof fetch;
-    /** get response object, defaulted `false` */
+    /**
+     * get response object, defaulted `false`
+     * @deprecated use `resolveWith` instead
+     * */
     resolveWithFullResponse?: boolean;
+    /**
+     * how to resolve the response body
+     * @description 如何解析响应体
+     * @default 'intelligent'
+     */
+    resolveWith?: KeqResolveMethod;
     /**
      * The request retry times
      * @description 重试次数

package/dist/umd/src/types/keq-resolve-with-mode.d.ts

@@ -0,0 +1 @@
+export type KeqResolveMethod = 'intelligent' | 'response' | 'text' | 'json' | 'form-data' | 'blob' | 'array-buffer';

package/dist/umd/src/types/keq-resolve-with-mode.js

@@ -0,0 +1,12 @@
+(function (factory) {
+    if (typeof module === "object" && typeof module.exports === "object") {
+        var v = factory(require, exports);
+        if (v !== undefined) module.exports = v;
+    }
+    else if (typeof define === "function" && define.amd) {
+        define(["require", "exports"], factory);
+    }
+})(function (require, exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keq",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Request API write by Typescript for flexibility, readability, and a low learning curve.",
   "keywords": [
     "request",
@@ -33,7 +33,7 @@
     "build": "npm run clean && ./build/build.sh",
     "clean": "rm -rf ./dist/*",
     "dev": "npm run clean && ./build/watch.sh",
-    "prepare": "ts-patch install -s && is-ci || husky install",
+    "prepare": "ts-patch install -s && is-ci || husky",
     "prepublishOnly": "npm run build",
     "release": "standard-version",
     "release:alpha": "standard-version --prerelease alpha",
@@ -41,35 +41,35 @@
   },
   "dependencies": {
     "clone": "^2.1.2",
-    "fastq": "^1.16.0",
+    "fastq": "^1.17.1",
     "minimatch": "^9.0.3",
     "object.fromentries": "^2.0.7",
     "ts-custom-error": "^3.3.1",
     "whatwg-url": "^14.0.0"
   },
   "devDependencies": {
-    "@buka/eslint-config": "^1.5.0",
-    "@commitlint/cli": "^18.2.0",
-    "@commitlint/config-conventional": "^18.1.0",
+    "@buka/eslint-config": "^1.6.0",
+    "@commitlint/cli": "^18.6.1",
+    "@commitlint/config-conventional": "^18.6.2",
     "@jest/globals": "^29.7.0",
-    "@rushstack/eslint-patch": "^1.5.1",
+    "@rushstack/eslint-patch": "^1.7.2",
     "@types/clone": "^2.1.4",
     "@types/minimatch": "^5.1.2",
-    "@types/node": "^20.9.0",
-    "@types/whatwg-url": "^11.0.3",
-    "@typescript-eslint/eslint-plugin": "^6.10.0",
-    "@typescript-eslint/parser": "^6.10.0",
-    "eslint": "^8.53.0",
-    "husky": "^8.0.3",
+    "@types/node": "^20.11.20",
+    "@types/whatwg-url": "^11.0.4",
+    "@typescript-eslint/eslint-plugin": "^7.0.2",
+    "@typescript-eslint/parser": "^7.0.2",
+    "eslint": "^8.57.0",
+    "husky": "^9.0.11",
     "is-ci": "^3.0.1",
     "jest": "^29.7.0",
     "jest-mock": "^29.7.0",
     "standard-version": "^9.5.0",
-    "ts-jest": "^29.1.1",
-    "ts-node": "^10.9.1",
-    "ts-patch": "^3.0.2",
-    "typescript": "^5.2.2",
-    "typescript-transform-paths": "^3.4.6"
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "ts-patch": "^3.1.2",
+    "typescript": "^5.3.3",
+    "typescript-transform-paths": "^3.4.7"
   },
   "packageManager": "pnpm@8.6.4",
   "engines": {