keq 2.8.2 → 2.8.4

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.8.4](https://github.com/keq-request/keq/compare/v2.8.3...v2.8.4) (2024-10-20)
+
+
+### Bug Fixes
+
+* esm improt error ([f23cece](https://github.com/keq-request/keq/commit/f23cece5d55c21a73deb9e9191cc52dafff35bc6))
+
+## [2.8.3](https://github.com/keq-request/keq/compare/v2.8.2...v2.8.3) (2024-10-20)
+
+
+### Bug Fixes
+
+* esm import error ([97dbd78](https://github.com/keq-request/keq/commit/97dbd78eaa8b57a1a22e776347a90baf8f47335e))
+
+
+### Performance Improvements
+
+* set context.retry to be deprecated ([e8b76a4](https://github.com/keq-request/keq/commit/e8b76a48a6e824892cb0eb3e8d97b36c11b07a3d))
+
 ## [2.8.2](https://github.com/keq-request/keq/compare/v2.8.1...v2.8.2) (2024-10-07)
 
 

package/README.md

@@ -1,10 +1,8 @@
-<!-- title -->
 <p align="center" style="padding-top: 40px">
   <img src="./images/logo.svg?sanitize=true" width="120" alt="logo" />
 </p>
 
 <h1 align="center" style="text-align: center">KEQ</h1>
-<!-- title -->
 
 [npm]: https://www.npmjs.com/package/keq
 
@@ -14,7 +12,6 @@
 [![license](https://img.shields.io/npm/l/keq.svg?logo=github&style=for-the-badge)][npm]
 [![Codecov](https://img.shields.io/codecov/c/gh/keq-request/keq?logo=codecov&token=PLF0DT6869&style=for-the-badge)](https://codecov.io/gh/keq-request/keq)
 
-<!-- description -->
 
 [Fetch MDN]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch
 [Headers MDN]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
@@ -22,12 +19,17 @@
 [FormData MDN]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
 [URL MDN]: https://developer.mozilla.org/en-US/docs/Web/API/URL
 
+[Document EN]: https://keq-request.github.io/guide/introduction
+[Document CN]: https://keq-request.github.io/zh/guide/introduction
+
 Keq is a request API write by Typescript for flexibility, readability, and a low learning curve. It also works with Node.js!
 Keq wraps the Fetch APIs, adding chain calls and middleware functions.
 
-<!-- description -->
 
-## Usage
+[**Document**][Document EN] | [**中文文档**][Document CN]
+
+## Simple Usage
+
 
 <!-- usage -->
 
@@ -271,47 +273,6 @@ 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
-
-| Parameter | Default | Description                                                                                                              |
-| :--------- |:------- | :----------------------------------------------------------------------------------------------------------------------- |
-| retryTimes  | `0` | Max number of retries per call.                                                                                          |
-| retryDelay |`0` | Initial value used to calculate the retry in milliseconds (This is still randomized following the randomization factor). |
-| retryOn    | `(attempt, error) => !!error` | Will be called after request used to control whether the next retry runs. If it return `false`, stop retrying.           |
-
-```javascript
-import { request } from "keq";
-
-await request
-  .get("http://test.com")
-  .retry(2, 1000, (attempt, err, ctx) => {
-    if (err) {
-      console.log("an error throw");
-      return true;
-    }
-
-    return false;
-  });
-```
-
 ### Set Request Redirect mode
 
 Follow redirect by default, invoke `.redirect(mode)` to set the redirect mode. Allow values are `"error"`, `"manual"` and `"follow"`.
@@ -337,274 +298,24 @@ await request
   .credentials("include");
 ```
 
-### Keq Internal Options
-
-Invoke `.option()` add options.
-
-```javascript
-import { request } from "keq";
-
-const response = await request
-  .get("http://test.com")
-  .option("middlewareOption", "value");
-```
-
-Or as a single object:
-
-```javascript
-import { request } from "keq";
-
-await request
-  .get("http://test.com")
-  .options({
-    middlewareOption: "value",
-  });
-```
-
-| **Option**                | **Description**                                                                                         |
-| :------------------------ | :------------------------------------------------------------------------------------------------------ |
-| `fetchAPI`                | Replace the defaulted `fetch` function used by `Keq`.                                                   |
-
-<!-- ###### The options with **DEPRECATED** will be removed in next major version -->
-​
-### Timeout
-
-Keq has built-in timeout function.
-
-```typescript
-await request
-  .get("http://test.com")
-  // 5000 milliseconds
-  .timeout(5000)
-```
-
-### Flow Control
-
-Controlling the behavior of sending requests multiple times.
-
-#### Abort
-
-If the previous request was not completed, abort the last request.
-
-```javascript
-import { request } from "keq";
-
-request
-  .get("http://test.com/cat")
-  // second args is the abort signal
-  // this will abort the request with same signal
-  // a unique signal will be generated, if not signal set.
-  .followControl("abort", 'animal');
-  .end()
-
-request
-  .get("http://test.com/dog")
-  // abort http://test.com/cat
-  .followControl("abort", 'animal')
-  .end()
-```
-
-#### Serial
-
-The next request will not start until the previous request is completed.
-
-```javascript
-import { request } from "keq";
-
-request
-  .get("http://test.com/cat")
-  // a unique signal will be generated, if signal is not set.
-  .followControl("serial", 'animal');
-  .end()
-
-// This request will be send after https://test.com/cat is complete
-request
-  .get("http://test.com/dog")
-  .followControl("serial", 'animal')
-  .end()
-```
-
-### Middleware
-
-You can extend `Keq` by write/import middleware.
-A typical middleware might look a little like the following:
-
-```javascript
-import { request } from "keq"
-
-const middleware = async (context, next) => {
-  // equal to .retry(2)
-  context.options.retryTimes = 2
-
-  await next()
-  const response = context.response
-  if (!response) return
-  const body = await response.json()
-
-  // custom keq return type
-  context.output = JSON.stringify(body)
-}
-
-// Global Middleware
-request
-  .use(middleware)
-
-request
-  .useRouter()
-  /**
-   * the middleware run when request url host is "example.com"
-   */
-  .host("example.com", middleware)
-  /**
-   * the middleware run when request url is location
-   * It is usefully in browser.
-   */
-  .location(middleware)
-  /**
-   * the middleware run when pathname match `/api/service_name/**`.
-   */
-  .pathname("/api/service_name/**" middleware)
-  /**
-   * the middleware run when method is GET
-   */
-  .method('get', middleware)
-  /**
-   * used with keq-cli
-   */
-  .module('yourServiceName',middleware)
-  /**
-   * this middleware run when pathname start with '/api'
-   */
-  .route((ctx) => ctx.pathname.startsWith('/api'), middleware)
-
-await request
-  .get("http://test.com")
-  /**
-   * the middleware run once
-   */
-  .use(middleware)
-```
-
-#### request.use(middleware)
-
-Add an global middleware, The running order of middleware is related to the order of `.use()`
-
-#### request.useRouter()
-
-Middleware Router
-
-#### write an middleware
-
-Middleware should be an asnyc-function that accept two argument:
-
-| **Arguments**           | **Description**                                                                                                                                                                                                             |
-| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx`(first argument)   | Keq Context                                                                                                                                                                                                                 |
-| `next`(second argument) | Used to execute the next middleware. The last `next()` function will send request and bind the [`Response`][Response MDN] object to `context.res`. Don't forget to call `next()` unless you don't want to send the request. |
-
-Keq's context object has many parameters. The following lists all the built-in context attributes of `Keq`:
-
-| **Property**                     | **Type**                                                                                                                                                                                                                          |
-| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `context.request`                | Includes request options for [Fetch API][Fetch MDN].                                                                                                                                                                              |
-| `context.request.url`            | [URL][URL MDN] Class                                                                                                                                                                                                              |
-| `context.request.__url__`            | Readonly [URL][URL MDN] Class that merged routeParams                                                                                                                                                                                                              |
-| `context.request.method`         | One of 'get', 'post', 'put', 'patch', 'head', 'delete'.                                                                                                                                                                           |
-| `context.request.body`           | Object, Array, string or undefined.                                                                                                                                                                                               |
-| `context.request.headers`        | The [`Headers`][Headers MDN] Object.                                                                                                                                                                                              |
-| `context.request.routeParams`    | The URL route params set by `.params(key, value)`                                                                                                                                                                                 |
-| `context.request.catch`          | `catch` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                       |
-| `context.request.credentials`    | `credentials` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                 |
-| `context.request.integrity`      | `integrity` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                   |
-| `context.request.keepalive`      | `keepalive` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                   |
-| `context.request.mode`           | `mode` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                        |
-| `context.request.redirect`       | `redirect` arguments in [Fetch API][Fetch MDN]                                                                                                                                                                                    |
-| `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.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`                 | Custom return value of `await request()`。 It only take effect when `resolveWith` is not set or set to 'intelligent'. **This property is writeonly.** |
-| `content.identifier`   |  The unique identifier of the request's location in the code. It is used as default key of FlowControl and Cache.
-
-#### .useRouter()
-
-This is the utils used to route middleware.
-
-| **Method**                                               |
-| :------------------------------------------------------- |
-| `.location(...middlewares)`                              |
-| `.method(method: string[, ...middlewares])`              |
-| `.pathname(matcher: string \| Regexp[, ...middlewares])` |
-| `.host(host: string[, ...middlewares])`                  |
-| `.module(moduleName: string[, ...middlewares])`          |
-| `.route(...middlewares)`                                 |
-
-### Create Request
-
-If you want to create a request instance, you can invoke `request.create()`:
-
-```typescript
-import { createRequest } from "keq";
-
-const customRequest = createRequest();
-
-// Middleware only takes effect on customRequests
-customRequest.use(/** some middleware */);
-
-const body = await customRequest.get("http://test.com");
-```
-
-> The gloabl request instance is created by `request.create()` too.
-
- option          | description
-:----------------|:---------------
- initMiddlewares | `fetch`, `retry`, `flowController` are all implemented by middleware. you can customize the init middlewares to change behavior.
- baseOrigin      | When sending a request without an `origin`, `origin` will set to `window.location.origin` in the browser and `"http://127.0.0.1"` in NodeJS.
-
-<!-- usage -->
-
-<!-- addition -->
-
-## Q&A
-
-### The diffirent between `.then()` and `.end()`
-
-Both `.then ()` and `.end ()` will send a request and return a Promise object.
-The difference between the two is that when called multiple times.
-
-`.then ()` actually sends only one request, no matter how many times it is called.
-
-`.end ()` will send a request for each call.
-
-```javascript
-import { request } from "keq";
-
-const keq = request.get("http://test.com");
-
-keq.then(onfulfilled, onrejected);
-// Won't send request, and will use the last request result.
-keq.then(onfulfilled, onrejected);
-
-keq.end();
-keq.end();
-```
-
-### The diffirent between `ctx.res` and `ctx.response`
-
-`ctx.response` will allways return a new [`Response`][Response MDN] created by `ctx.res && ctx.res.clone()`. Sothat each middleware could calling `ctx.response.json()`, `ctx.response.text()`, `ctx.response.formData()`.
-
-What's more, The `.formData()` function isn't existed in `Response` returned by `node-fetch`. keq will append it to `Response` after clone, if in `NodeJS`.
+### resolve responseBody
 
-## See More
+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
 
-Keq is inspired by SuperAgent and Koa.
+| 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()`                                                                                                                                                                      |
 
-- [Superagent](https://visionmedia.github.io/superagent/#test-documentation)
-- [Koa](https://koajs.com/)
 
-<!-- addition -->
+See more usage in the [Document][Document EN]
 
 ## Contributing & Development
 

package/dist/esm/src/is/is-buffer.js

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { isBrowser } from './is-browser';
+import { isBrowser } from './is-browser.js';
 export function isBuffer(obj) {
     return isBrowser() ? false : Buffer.isBuffer(obj);
 }

package/dist/esm/src/middlewares/fetch-arguments-middleware.d.ts

@@ -1,2 +1,2 @@
-import type { KeqMiddleware } from '../types/keq-middleware';
+import type { KeqMiddleware } from '../types/keq-middleware.js';
 export declare function fetchArgumentsMiddleware(): KeqMiddleware;

package/dist/esm/src/middlewares/retry-middleware.d.ts

@@ -1,2 +1,2 @@
-import type { KeqMiddleware } from "../types/keq-middleware";
+import type { KeqMiddleware } from "../types/keq-middleware.js";
 export declare function retryMiddleware(): KeqMiddleware;

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

@@ -1,4 +1,4 @@
-import type { KeqMiddleware } from "../types/keq-middleware";
+import type { KeqMiddleware } from "../types/keq-middleware.js";
 import type { KeqRoute } from "../types/keq-route.js";
 export declare class KeqRouter {
     private readonly prependMiddlewares;

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

@@ -53,6 +53,8 @@ export interface KeqContext {
     global: KeqGlobal;
     /**
      * retry information, undefined is no retry
+     *
+     * @deprecated
      */
     retry?: {
         attempt: number;

package/dist/esm/src/util/compose-route.js

@@ -1,4 +1,4 @@
-import { Exception } from '../exception/exception';
+import { Exception } from '../exception/exception.js';
 export function composeRoute(routes) {
     if (!routes.length) {
         throw new Exception('At least one route');

package/dist/umd/src/is/is-buffer.js

@@ -4,16 +4,16 @@
         if (v !== undefined) module.exports = v;
     }
     else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "./is-browser"], factory);
+        define(["require", "exports", "./is-browser.js"], factory);
     }
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.isBuffer = void 0;
     /* eslint-disable @typescript-eslint/no-explicit-any */
-    const is_browser_1 = require("./is-browser");
+    const is_browser_js_1 = require("./is-browser.js");
     function isBuffer(obj) {
-        return (0, is_browser_1.isBrowser)() ? false : Buffer.isBuffer(obj);
+        return (0, is_browser_js_1.isBrowser)() ? false : Buffer.isBuffer(obj);
     }
     exports.isBuffer = isBuffer;
 });

package/dist/umd/src/middlewares/fetch-arguments-middleware.d.ts

@@ -1,2 +1,2 @@
-import type { KeqMiddleware } from '../types/keq-middleware';
+import type { KeqMiddleware } from '../types/keq-middleware.js';
 export declare function fetchArgumentsMiddleware(): KeqMiddleware;

package/dist/umd/src/middlewares/retry-middleware.d.ts

@@ -1,2 +1,2 @@
-import type { KeqMiddleware } from "../types/keq-middleware";
+import type { KeqMiddleware } from "../types/keq-middleware.js";
 export declare function retryMiddleware(): KeqMiddleware;

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

@@ -1,4 +1,4 @@
-import type { KeqMiddleware } from "../types/keq-middleware";
+import type { KeqMiddleware } from "../types/keq-middleware.js";
 import type { KeqRoute } from "../types/keq-route.js";
 export declare class KeqRouter {
     private readonly prependMiddlewares;

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

@@ -53,6 +53,8 @@ export interface KeqContext {
     global: KeqGlobal;
     /**
      * retry information, undefined is no retry
+     *
+     * @deprecated
      */
     retry?: {
         attempt: number;

package/dist/umd/src/util/compose-route.js

@@ -4,16 +4,16 @@
         if (v !== undefined) module.exports = v;
     }
     else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "../exception/exception"], factory);
+        define(["require", "exports", "../exception/exception.js"], factory);
     }
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.composeRoute = void 0;
-    const exception_1 = require("../exception/exception");
+    const exception_js_1 = require("../exception/exception.js");
     function composeRoute(routes) {
         if (!routes.length) {
-            throw new exception_1.Exception('At least one route');
+            throw new exception_js_1.Exception('At least one route');
         }
         return async (ctx) => {
             const results = await Promise.all(routes.map((route) => route(ctx)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keq",
-  "version": "2.8.2",
+  "version": "2.8.4",
   "description": "Request API write by Typescript for flexibility, readability, and a low learning curve.",
   "keywords": [
     "request",
@@ -68,7 +68,7 @@
     "typescript": "5.4.5",
     "typescript-transform-paths": "^3.4.7"
   },
-  "packageManager": "pnpm@9.10.0",
+  "packageManager": "pnpm@9.12.2",
   "engines": {
     "node": ">=18.0.0"
   }