@varlet/axle 0.0.25 → 0.1.0

package/README.md

@@ -1,8 +1,11 @@
+<span>English</span> | 
+<a href="https://github.com/varletjs/axle/blob/main/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 +22,178 @@ 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 **/)
 
+axle.get('/url', { current: 1, pageSize: 10 }, { headers: {} })
+axle.post('/url', { name: 'Axle' }, { headers: {} })
+```
+
+### 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
 
-const response = await axle.get('/user', { current: 1, pageSize: 10 }, { headers: {} })
-const response = await axle.post('/user', { name: 'Axle' }, { headers: {} })
+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() })
 ```
 
-### Vue Composition Api
+## Utils
+
+#### Notify the browser to download the file
+
+```js
+import { download } from '@varlet/axle'
+
+download(await axle.getBlob('/url', { id: 1 }), 'filename')
+```
+
+#### Common Header Operate
+
+```js
+const headers = axle.getHeaders()
+axle.setHeader('TOKEN', TOKEN)
+axle.removeHeader('TOKEN')
+```
+
+## 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 +201,115 @@ 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()
 
-// 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, abort }] = 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, The transformed data will be the value of users.
+    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>
+  <button @click="abort">Abort Request</button>
 </template>
 ```
 
-### Repo Status
+### Parallel Utils
+
+Axle provides some parallel request processing tools, please refer to the following examples.
+
+```html
+<script setup>
+import { createAxle } from '@varlet/axle'
+import { createUseAxle, useAllData, useAverageProgress, useHasLoading } from '@varlet/axle/use'
+
+const axle = createAxle(/** @see https://axios-http.com **/)
+const useAxle = createUseAxle()
+
+const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
+  data: [],
+  runner: axle.get,
+  url: '/user',
+})
+
+const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
+  data: [],
+  runner: axle.get,
+  url: '/role',
+})
+
+// At the end of all requests, loading is false
+const loading = useHasLoading(isUsersLoading, isRolesLoading)
+// At the end of all requests, downloadProgress is 1
+const downloadProgress = useAverageProgress(usersDownloadProgress, rolesDownloadProgress)
+// Ref<[
+//   [{ name: 'foo' }, { name: 'bar' }], 
+//   [{ role: 'admin' }, { role: 'user' }]
+// ]> <-
+// [
+//   Ref<[{ name: 'foo' }, { name: 'bar' }]>, 
+//   Ref<[{ role: 'admin' }, { role: 'user' }]>
+// ]
+const usersRoles = useAllData(users, roles)
+
+function sendAllRequest() {
+  // parallel
+  getUsers()
+  getRoles()
+}
+</script>
+
+<template>
+  <span>{{ usersRoles }}</span>
+  <span>{{ loading }}</span>
+  <span>{{ downloadProgress }}</span>
+  <button @click="sendAllRequest">Send All Request</button>
+</template>
+```
+
+
 
-WIP and Trying
 

package/README.zh-CN.md

@@ -0,0 +1,315 @@
+<a href="https://github.com/varletjs/axle/blob/main/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: {} })
+```
+
+### 配置
+
+`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
+import { download } from '@varlet/axle'
+
+download(await axle.getBlob('/url', { id: 1 }), 'filename')
+```
+
+#### 公共 header 操作
+
+```js
+const headers = axle.getHeaders()
+axle.setHeader('TOKEN', TOKEN)
+axle.removeHeader('TOKEN')
+```
+
+## 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, abort }] = 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>
+  <button @click="abort">中断请求</button>
+</template>
+```
+
+### 并行请求实用工具
+
+Axle 提供了一些并行请求处理工具，请参考以下示例。
+
+```html
+<script setup>
+import { createAxle } from '@varlet/axle'
+import { createUseAxle, useAllData, useAverageProgress, useHasLoading } from '@varlet/axle/use'
+
+const axle = createAxle(/** @see https://axios-http.com **/)
+const useAxle = createUseAxle()
+
+const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
+  data: [],
+  runner: axle.get,
+  url: '/user',
+})
+
+const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
+  data: [],
+  runner: axle.get,
+  url: '/role',
+})
+
+// 所有请求结束时，loading 为 false
+const loading = useHasLoading(isUsersLoading, isRolesLoading)
+// 所有请求结束时，downloadProgress 为 1
+const downloadProgress = useAverageProgress(usersDownloadProgress, rolesDownloadProgress)
+// Ref<[
+//   [{ name: 'foo' }, { name: 'bar' }], 
+//   [{ role: 'admin' }, { role: 'user' }]
+// ]> <-
+// [
+//   Ref<[{ name: 'foo' }, { name: 'bar' }]>, 
+//   Ref<[{ role: 'admin' }, { role: 'user' }]>
+// ]
+const usersRoles = useAllData(users, roles)
+
+function sendAllRequest() {
+  // parallel
+  getUsers()
+  getRoles()
+}
+</script>
+
+<template>
+  <span>{{ usersRoles }}</span>
+  <span>{{ loading }}</span>
+  <span>{{ downloadProgress }}</span>
+  <button @click="sendAllRequest">发送全部请求</button>
+</template>
+```
+
+
+
+

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,15 @@ 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

@@ -1,5 +1,6 @@
 import axios from 'axios';
 import qs from 'qs';
+import { inBrowser } from '@varlet/shared';
 export function createFetchHelper(service, method, responseType) {
     return function (url, params, config) {
         return service[method](url, Object.assign({ params,
@@ -22,6 +23,9 @@ export function createModifyHelper(service, method, contentType) {
     };
 }
 export function download(url, filename) {
+    if (!inBrowser()) {
+        return;
+    }
     const a = document.createElement('a');
     a.download = filename;
     a.style.display = 'none';
@@ -33,6 +37,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 +76,16 @@ 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/es/use.d.ts

@@ -43,3 +43,6 @@ export interface CreateUseAxleOptions {
     onTransform?(response: any, refs: any): any;
 }
 export declare function createUseAxle(options?: CreateUseAxleOptions): <D = any, R = any, P = Record<string, any>>(options: UseAxleOptions<D, R, P>) => UseAxleInstance<D, R, P>;
+export * from './useAllData.js';
+export * from './useHasLoading.js';
+export * from './useAverageProgress.js';

package/es/use.js

@@ -16,7 +16,7 @@ export function createUseAxle(options = {}) {
             loading,
             error,
             downloadProgress,
-            uploadProgress
+            uploadProgress,
         };
         let controller = new AbortController();
         const run = async (options = {}) => {
@@ -81,3 +81,6 @@ export function createUseAxle(options = {}) {
     };
     return useAxle;
 }
+export * from './useAllData.js';
+export * from './useHasLoading.js';
+export * from './useAverageProgress.js';

package/es/useAllData.d.ts

@@ -0,0 +1 @@
+export declare function useAllData<DC extends any[]>(...dataCollection: DC): import("vue").WritableComputedRef<any[]>;

package/es/useAllData.js

@@ -0,0 +1,11 @@
+import { computed } from 'vue';
+export function useAllData(...dataCollection) {
+    return computed({
+        get: () => dataCollection.map((data) => data.value),
+        set(values) {
+            dataCollection.forEach((data, index) => {
+                data.value = values[index];
+            });
+        },
+    });
+}

package/es/useAverageProgress.d.ts

@@ -0,0 +1,2 @@
+import { type Ref } from "vue";
+export declare function useAverageProgress(...progressCollection: Ref<number>[]): Ref<number>;

package/es/useAverageProgress.js

@@ -0,0 +1,9 @@
+import { ref, watch } from "vue";
+export function useAverageProgress(...progressCollection) {
+    const averageProgress = ref(0);
+    watch(() => progressCollection.map(progress => progress.value), (newProgressCollection) => {
+        const total = newProgressCollection.reduce((total, progress) => total + progress, 0);
+        averageProgress.value = total / progressCollection.length;
+    }, { immediate: true });
+    return averageProgress;
+}

package/es/useHasLoading.d.ts

@@ -0,0 +1,2 @@
+import { type Ref } from "vue";
+export declare function useHasLoading(...loadings: Ref<boolean>[]): Ref<boolean>;

package/es/useHasLoading.js

@@ -0,0 +1,8 @@
+import { ref, watch } from "vue";
+export function useHasLoading(...loadings) {
+    const hasLoading = ref(false);
+    watch(() => loadings.map(loading => loading.value), (newLoadings) => {
+        hasLoading.value = newLoadings.some(Boolean);
+    }, { immediate: true });
+    return hasLoading;
+}

package/package.json

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