@varlet/axle 0.0.25 → 0.0.26

package/README.md

@@ -1,8 +1,13 @@
+<span>English</span> | 
+<a href="https://github.com/varletjs/axle/blob/dev/README.zh-CN.md">中文</a>
+
+---
+
 ### Intro
 
-A tool library based on axios to simplify the development process
+Progressive request tool based on axios. It does not destroy the original abilities of axios, and helps you process requests more easily.
 
-### Quickstart
+### QuickStart
 
 #### Install
 
@@ -19,22 +24,22 @@ yarn add @varlet/axle
 pnpm add @varlet/axle
 ```
 
-#### Request Call
+#### Send Request
+
+Axle normalizes the parameters of the request function, and expands more request functions for different interface requirements. Here is a simple example.
 
 ```js
 import { createAxle } from '@varlet/axle'
 
-// create axle instance
 const axle = createAxle(/** @see https://axios-http.com **/)
 
-// The built-in axios of the axle, the usage is exactly the same as that of axios, and shares the configuration with the axle.
-const { axios } = axle
-
-const response = await axle.get('/user', { current: 1, pageSize: 10 }, { headers: {} })
-const response = await axle.post('/user', { name: 'Axle' }, { headers: {} })
+axle.get('/url', { current: 1, pageSize: 10 }, { headers: {} })
+axle.post('/url', { name: 'Axle' }, { headers: {} })
 ```
 
-### Vue Composition Api
+#### Vue Composition API
+
+Axle provides the usage of Vue Composition API style, which encapsulates the `loading status`, `error status`, `upload and download progress` of the request, `return data`, `error retry`, `lifecycle`, etc., And inherit all the configuration of `axios`.
 
 ```html
 <script setup>
@@ -42,26 +47,215 @@ import { createAxle } from '@varlet/axle'
 import { createUseAxle } from '@varlet/axle/use'
 
 const axle = createAxle(/** @see https://axios-http.com **/)
-const useAxle = createUseAxle(/** @see https://github.com/varletjs/axle/blob/main/src/use.ts?plain=1#L5 **/)
+const useAxle = createUseAxle(/** Unstable **/)
 
-// default immediate request
-const [users, getUsers, loading, { error }] = useAxle({
-  /** @see https://github.com/varletjs/axle/blob/main/src/use.ts?plain=1#L26 **/
+const [users, getUsers, { loading, error, uploadProgress, downloadProgress }] = useAxle({
+  // Request initial data
+  data: [],
+  // Request runner
   runner: axle.get,
+  // Request url
   url: '/user',
+  // Whether to send the request immediately, defaults false
+  immediate: true,
+  // The number of retries after a failed request, defaults 0
+  retry: 3,
+  // Request params, defaults {}
   params: { current: 1, pageSize: 10 },
-  config: { headers: {} }
+  // Axios config, see https://axios-http.com
+  config: { headers: {} },
+  // lifecycle
+  onBefore(refs) {
+    const { data, loading, error, uploadProgress, downloadProgress } = refs
+    console.log(
+      data.value, 
+      loading.value,
+      error.value, 
+      uploadProgress.value, 
+      downloadProgress.value
+    )
+    // Do request before
+  },
+  onTransform(response, refs) {
+    // Handle data transform
+    return response.data
+  },
+  onSuccess(response, refs) {
+    // Do request success
+  },
+  onError(error, refs) {
+    // Do request error
+  },
+  onAfter(refs) {
+    // Do request after
+  }
 })
 </script>
 
 <template>
-   <span>{{ users }}</span>
-   <span>{{ loading }}</span>
-   <span>{{ error }}</span>
+  <span>{{ users }}</span>
+  <span>{{ loading }}</span>
+  <span>{{ error }}</span>
+  <span>{{ uploadProgress }}</span>
+  <span>{{ downloadProgress }}</span>
+  <button @click="getUsers">Send Request</button>
 </template>
 ```
 
-### Repo Status
+### Config
+
+Axle fully supports all configuration abilities of axios.
+
+```js
+const axle = createAxle(/** @see https://axios-http.com **/)
+// The built-in axios of the axle, the usage is exactly the same as that of axios, and shares the configuration with the axle.
+const { axios } = axle
+
+axios.defaults.baseURL = 'https://api.example.com'
+axios.defaults.headers.common['TOKEN'] = TOKEN
+axios.defaults.timeout = 2500
+
+// Add a request interceptor
+axios.interceptors.request.use((config) => {
+  // Do something before request is sent
+  return config
+}, (error) => {
+  // Do something with request error
+  return Promise.reject(error)
+})
+
+// Add a response interceptor
+axios.interceptors.response.use((response) => {
+  // Any status code that lie within the range of 2xx cause this function to trigger
+  // Do something with response data
+  return response
+}, (error) => {
+  // Any status codes that falls outside the range of 2xx cause this function to trigger
+  // Do something with response error
+  return Promise.reject(error)
+})
+```
+
+## Axle & Axios Request Functions
+
+The request function provided by Axle can help you send requests more easily. Here are some examples including comparison with axios.
+Tips: Take `get` and `post` as examples below, Axle also supports `options`, `head`, `delete`, `patch` , `put` methods.
+
+### get
+
+#### JSON
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 } })
+// axle
+axle.get('/url', { id: 1 })
+```
+
+#### Blob
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'blob' })
+// axle
+axle.getBlob('/url', { id: 1 })
+```
+
+#### Text
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'text' })
+// axle
+axle.getText('/url', { id: 1 })
+```
+
+#### Document
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'document' })
+// axle
+axle.getDocument('/url', { id: 1 })
+```
+
+#### ArrayBuffer
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'arraybuffer' })
+// axle
+axle.getArrayBuffer('/url', { id: 1 })
+```
+
+#### Stream
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'stream' })
+// axle
+axle.getStream('/url', { id: 1 })
+```
+
+## post
+
+#### JSON
+
+Same with axios.
+
+```js
+// axios
+axios.post('/url', { name: 'foo' })
+// axle
+axle.post('/url', { name: 'foo' })
+```
+
+#### application/x-www-form-urlencoded
+
+```js
+// axios
+axios.post('/url', qs.stringify({ name: 'foo' }), { 
+  headers: { 
+    'Content-Type': 'application/x-www-form-urlencoded'
+  }
+})
+// axle
+axle.postUrlEncode('/url', { name: 'foo' })
+```
+
+#### multipart/form-data
+
+```js
+// axios
+const formData = new FormData()
+formData.append('name', 'foo')
+formData.append('file', new File())
+
+axios.post('/url', formData, { 
+  headers: { 
+    'Content-Type': 'multipart/form-data'
+  }
+})
+// axle
+axle.postMultipart('/url', { name: 'foo', file: new File() })
+```
+
+### Utils
+
+#### Notify the browser to download the file
+
+```js
+axle.download(await axle.getBlob('/url', { id: 1 }), 'filename')
+```
+
+#### Common Header Operate
+
+```js
+const headers = axle.getHeaders()
+axle.setHeader('TOKEN', TOKEN)
+axle.removeHeader('TOKEN')
+```
+
+
 
-WIP and Trying
 

package/README.zh-CN.md

@@ -0,0 +1,261 @@
+<a href="https://github.com/varletjs/axle/blob/dev/README.md">English</a> |
+<span>中文</span>
+
+---
+
+### 介绍
+
+基于 [axios](https://axios-http.com/) 的渐进式请求工具。 它不会破坏 `axios` 原有的能力，帮助您更轻松地处理请求。
+
+### 快速开始
+
+#### 安装
+
+```shell
+# 通过 npm, yarn, pnpm 安装
+
+# npm
+npm i @varlet/axle -S
+
+#yarn
+yarn add @varlet/axle
+
+#pnpm
+pnpm add @varlet/axle
+```
+
+#### 发送请求
+
+`Axle` 归一化了请求函数的参数，并针对不同的业务需求，扩展了更多请求函数，下面是一个简单的例子。
+
+```js
+import { createAxle } from '@varlet/axle'
+
+const axle = createAxle(/** @see https://axios-http.com **/)
+
+axle.get('/url', { current: 1, pageSize: 10 }, { headers: {} })
+axle.post('/url', { name: 'Axle' }, { headers: {} })
+```
+
+#### Vue 组合式 API
+
+Axle 提供了 Vue Composition API 风格的用法，封装了请求的 `加载状态`, `错误状态`, `请求的上下行进度`，`返回数据`，`错误重试`，`生命周期` 等等，并继承了 `axios` 的所有配置。
+
+```html
+<script setup>
+import { createAxle } from '@varlet/axle'
+import { createUseAxle } from '@varlet/axle/use'
+
+const axle = createAxle(/** @see https://axios-http.com **/)
+const useAxle = createUseAxle()
+
+const [users, getUsers, { loading, error, uploadProgress, downloadProgress }] = useAxle({
+  // 请求初始化数据
+  data: [],
+  // 请求函数
+  runner: axle.get,
+  // 请求地址
+  url: '/user',
+  // 是否立即发送请求, 默认值: false
+  immediate: true,
+  // 错误重试次数, 默认值: 0
+  retry: 3,
+  // 请求参数, 默认值: {}
+  params: { current: 1, pageSize: 10 },
+  // Axios 配置, see https://axios-http.com
+  config: { headers: {} },
+  // 生命周期
+  onBefore(refs) {
+    const { data, loading, error, uploadProgress, downloadProgress } = refs
+    console.log(
+      data.value, 
+      loading.value,
+      error.value, 
+      uploadProgress.value, 
+      downloadProgress.value
+    )
+    // 处理请求前逻辑
+  },
+  onTransform(response, refs) {
+    // 处理数据转换，转换后的数据将成为 users 的值。
+    return response.data
+  },
+  onSuccess(response, refs) {
+    // 处理请求成功逻辑
+  },
+  onError(error, refs) {
+    // 处理请求错误逻辑
+  },
+  onAfter(refs) {
+    // 处理请求结束逻辑，无论成功失败都会触发。
+  }
+})
+</script>
+
+<template>
+  <span>{{ users }}</span>
+  <span>{{ loading }}</span>
+  <span>{{ error }}</span>
+  <span>{{ uploadProgress }}</span>
+  <span>{{ downloadProgress }}</span>
+  <button @click="getUsers">发送请求</button>
+</template>
+```
+
+### 配置
+
+`Axle` 完全支持 `axios` 的所有配置能力。
+
+```js
+const axle = createAxle(/** @see https://axios-http.com **/)
+// axle 内置的 axios ，用法和 axios 一模一样，并且和 axle 共享配置。
+const { axios } = axle
+
+axios.defaults.baseURL = 'https://api.example.com'
+axios.defaults.headers.common['TOKEN'] = TOKEN
+axios.defaults.timeout = 2500
+
+// 添加请求前拦截器
+axios.interceptors.request.use((config) => {
+  // 请求前处理
+  return config
+}, (error) => {
+  // 请求错误处理
+  return Promise.reject(error)
+})
+
+// 添加请求后返回拦截器
+axios.interceptors.response.use((response) => {
+  // 任何位于 2xx 范围内的状态码都会导致该函数触发
+  // 对响应数据做一些事情
+  return response
+}, (error) => {
+  // 任何超出 2xx 范围的状态代码都会导致此函数触发
+  // 对响应错误做一些事情
+  return Promise.reject(error)
+})
+```
+
+## Axle & Axios 请求函数
+
+`Axle` 提供的请求函数可以帮助您更轻松地发送请求。 以下是一些示例，包括与 `axios` 的比较。
+提示：下面只是以 `get` 和 `post` 为例，除此之外 Axle 还支持 `options`、`head`、`delete`、`patch` 、`put` 方法。
+
+### get
+
+#### JSON
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 } })
+// axle
+axle.get('/url', { id: 1 })
+```
+
+#### Blob
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'blob' })
+// axle
+axle.getBlob('/url', { id: 1 })
+```
+
+#### Text
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'text' })
+// axle
+axle.getText('/url', { id: 1 })
+```
+
+#### Document
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'document' })
+// axle
+axle.getDocument('/url', { id: 1 })
+```
+
+#### ArrayBuffer
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'arraybuffer' })
+// axle
+axle.getArrayBuffer('/url', { id: 1 })
+```
+
+#### Stream
+
+```js
+// axios
+axios.get('/url', { params: { id: 1 }, responseType: 'stream' })
+// axle
+axle.getStream('/url', { id: 1 })
+```
+
+## post
+
+#### JSON
+
+和 axios 一致。
+
+```js
+// axios
+axios.post('/url', { name: 'foo' })
+// axle
+axle.post('/url', { name: 'foo' })
+```
+
+#### application/x-www-form-urlencoded
+
+```js
+// axios
+axios.post('/url', qs.stringify({ name: 'foo' }), { 
+  headers: { 
+    'Content-Type': 'application/x-www-form-urlencoded'
+  }
+})
+// axle
+axle.postUrlEncode('/url', { name: 'foo' })
+```
+
+#### multipart/form-data
+
+```js
+// axios
+const formData = new FormData()
+formData.append('name', 'foo')
+formData.append('file', new File())
+
+axios.post('/url', formData, { 
+  headers: { 
+    'Content-Type': 'multipart/form-data'
+  }
+})
+// axle
+axle.postMultipart('/url', { name: 'foo', file: new File() })
+```
+
+### 实用工具
+
+#### 通知浏览器下载文件
+
+```js
+axle.download(await axle.getBlob('/url', { id: 1 }), 'filename')
+```
+
+#### 公共 header 操作
+
+```js
+const headers = axle.getHeaders()
+axle.setHeader('TOKEN', TOKEN)
+axle.removeHeader('TOKEN')
+```
+
+
+
+

package/es/instance.d.ts

@@ -1,4 +1,4 @@
-import type { AxiosInstance, AxiosRequestConfig, AxiosResponse, ResponseType } from 'axios';
+import type { AxiosInstance, AxiosRequestConfig, AxiosResponse, HeadersDefaults, ResponseType } from 'axios';
 export type AxleRequestConfig = AxiosRequestConfig & {
     exceptionMessage?: any;
 };
@@ -32,15 +32,16 @@ export type AxleInstance = {
     deleteArrayBuffer: FetchHelper;
     deleteStream: FetchHelper;
     post: ModifyHelper;
-    postJSON: ModifyHelper;
+    postUrlEncode: ModifyHelper;
     postMultipart: ModifyHelper;
     put: ModifyHelper;
-    putJSON: ModifyHelper;
+    putUrlEncode: ModifyHelper;
     putMultipart: ModifyHelper;
     patch: ModifyHelper;
-    patchJSON: ModifyHelper;
+    patchUrlEncode: ModifyHelper;
     patchMultipart: ModifyHelper;
     download(blob: string | Blob, filename: string): void;
+    getHeaders(): HeadersDefaults['common'];
     setHeader(key: string, value: string): void;
     removeHeader(key: string | string[]): void;
     axios: AxiosInstance;

package/es/instance.js

@@ -33,6 +33,9 @@ export function download(url, filename) {
 }
 export function createAxle(config = {}) {
     const service = axios.create(config);
+    function getHeaders() {
+        return service.defaults.headers['common'];
+    }
     function setHeader(key, value) {
         ;
         service.defaults.headers['common'][key] = value;
@@ -69,16 +72,17 @@ export function createAxle(config = {}) {
         deleteArrayBuffer: createFetchHelper(service, 'delete', 'arraybuffer'),
         deleteText: createFetchHelper(service, 'delete', 'text'),
         deleteStream: createFetchHelper(service, 'delete', 'stream'),
-        post: createModifyHelper(service, 'post', 'application/x-www-form-urlencoded'),
-        postJSON: createModifyHelper(service, 'post', 'application/json'),
+        post: createModifyHelper(service, 'post', 'application/json'),
+        postUrlEncode: createModifyHelper(service, 'post', 'application/x-www-form-urlencoded'),
         postMultipart: createModifyHelper(service, 'post', 'multipart/form-data'),
-        put: createModifyHelper(service, 'put', 'application/x-www-form-urlencoded'),
-        putJSON: createModifyHelper(service, 'put', 'application/json'),
+        put: createModifyHelper(service, 'put', 'application/json'),
+        putUrlEncode: createModifyHelper(service, 'put', 'application/x-www-form-urlencoded'),
         putMultipart: createModifyHelper(service, 'put', 'multipart/form-data'),
-        patch: createModifyHelper(service, 'patch', 'application/x-www-form-urlencoded'),
-        patchJSON: createModifyHelper(service, 'patch', 'application/json'),
+        patch: createModifyHelper(service, 'patch', 'application/json'),
+        patchUrlEncode: createModifyHelper(service, 'patch', 'application/x-www-form-urlencoded'),
         patchMultipart: createModifyHelper(service, 'patch', 'multipart/form-data'),
         download,
+        getHeaders,
         setHeader,
         removeHeader,
         axios: service,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varlet/axle",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "A useful axios helper",
   "type": "module",
   "main": "es/index.js",