From f3846e0f27e59fd6c55e0b1a8547658156f8f4ac Mon Sep 17 00:00:00 2001
From: haoziqaq <357229046@qq.com>
Date: Tue, 3 Dec 2024 11:03:36 +0800
Subject: [PATCH] docs: update docs

---
 README.md                     |   1 -
 README.zh-CN.md               |   1 -
 packages/axle/README.md       | 156 ++++++++++++++++++++++++++++++++--
 packages/axle/README.zh-CN.md | 156 ++++++++++++++++++++++++++++++++--
 4 files changed, 298 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 3a77c5b..25bcc12 100644
--- a/README.md
+++ b/README.md
@@ -302,7 +302,6 @@ const useAxle = createUseAxle({
 })
 
 const [
-  // response data
   users, 
   // request runner/invoker
   getUsers, 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 58e5f9c..01a9fad 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -302,7 +302,6 @@ const useAxle = createUseAxle({
 })
 
 const [
-  // 请求数据
   users, 
   // 请求触发器
   getUsers, 
diff --git a/packages/axle/README.md b/packages/axle/README.md
index 9251e62..25bcc12 100644
--- a/packages/axle/README.md
+++ b/packages/axle/README.md
@@ -295,21 +295,27 @@ const axle = createAxle(/** @see https://axios-http.com **/)
 
 const useAxle = createUseAxle({
   axle,
-  // Optional value: Default immediate of the useAxle
-  immediate: true,
+  // Optional value: Default immediate of the useAxle, defaults true
+  immediate: false,
   // Optional value: Default onTransform of the useAxle
   onTransform: (response) => response,
 })
 
-const [users, getUsers, { loading, error, uploadProgress, downloadProgress, abort, resetValue }] = useAxle({
+const [
+  users, 
+  // request runner/invoker
+  getUsers, 
+  // extra properties
+  { loading, error, uploadProgress, downloadProgress, abort, resetValue }
+] = useAxle({
   // Request initial value
   value: [],
   // Request method
   method: 'get',
   // Request url can be a getter function
   url: '/user',
-  // Whether to send the request immediately, defaults false
-  immediate: true,
+  // Whether to send the request immediately, defaults true
+  immediate: false,
   // Whether the value needs to be reset before requesting, defaults false
   resetValue: true,
   // Whether to clone when resetting value, defaults false
@@ -367,13 +373,11 @@ const axle = createAxle(/** @see https://axios-http.com **/)
 const useAxle = createUseAxle({ axle })
 
 const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
-  value: [],
   method: 'get',
   url: '/user',
 })
 
 const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
-  value: [],
   method: 'get',
   url: '/role',
 })
@@ -406,3 +410,141 @@ function sendAllRequest() {
   <button @click="sendAllRequest">Send All Request</button>
 </template>
 ```
+
+### API Definition Enhancement
+
+`createApi` is supported since `v0.9.0`, which is used to define APIs.
+
+#### Define APIs
+
+```ts
+import { createAxle } from '@varlet/axle'
+import { createUseAxle } from '@varlet/axle/use'
+import { createApi } from '@varlet/axle/api'
+
+const axle = createAxle({
+  baseURL: '/api',
+})
+
+const useAxle = createUseAxle({
+  axle,
+})
+
+const api = createApi(axle, useAxle)
+
+export const apiGetUsers = api<Response<User[]>>('/user', 'get')
+
+export const apiGetUser = api<Response<User>>('/user/:id', 'get')
+
+export const apiCreateUser = api<Response<User>, CreateUser>('/user', 'post')
+
+export const apiUpdateUser = api<Response<User>, UpdateUser>('/user/:id', 'put')
+
+export const apiDeleteUser = api<Response<User>>('/user/:id', 'delete')
+
+export type Response<T> = {
+  data: T
+  code: number
+  message: string
+  success: boolean
+}
+
+export interface User {
+  id: string
+  name: string
+}
+
+export interface CreateUser {
+  name: string
+}
+
+export interface UpdateUser {
+  name: string
+}
+```
+
+#### Invoke APIs
+
+```ts
+const route = useRoute()
+
+const [users, getUsers] = apiGetUsers.use<Response<User[]>>(/** same as useAxle and extends pathParams **/)
+
+const [user, getUser] = apiGetUser.use<Response<User>>({
+  pathParams: () => ({ id: route.params.id }),
+})
+
+async function handleCreate(params: CreateUser) {
+  const { success } = await apiCreateUser.load(params)
+
+  if (success) {
+    getUsers()
+  }
+}
+
+async function handleUpdate(params: UpdateUser, id: string) {
+  const { success } = await apiUpdateUser.load(params, { id })
+
+  if (success) {
+    getUsers()
+  }
+}
+
+async function handleDelete(id: string) {
+  const { success } = await apiDeleteUser.load({}, { id })
+
+  if (success) {
+    getUsers()
+  }
+}
+```
+
+### Runner Enhancement
+
+Since `v0.10.0`, the `runner` will include all the extra properties, so we can further simplify the work.
+
+before:
+
+```html
+<script setup>
+const [users, getUsers, { loading: isUsersLoading }] = useAxle({
+  method: 'get',
+  url: '/user',
+})
+
+const [posts, getPosts, { loading: isPostsLoading }] = useAxle({
+  method: 'get',
+  url: '/post',
+})
+</script>
+
+<template>
+  <span>{{ isUsersLoading ? 'loading...' : users }}</span>
+  <span>{{ isPostsLoading ? 'loading...' : posts }}</span>
+  <button @click="getUsers">Send Request</button>
+  <button @click="getPosts">Send Request</button>
+</template>
+```
+
+after:
+
+```html
+<script setup>
+const [users, getUsers] = useAxle({
+  method: 'get',
+  url: '/user',
+})
+
+const [posts, getPosts] = useAxle({
+  method: 'get',
+  url: '/post',
+})
+</script>
+
+<template>
+  <span>{{ getUsers.loading ? 'loading...' : users }}</span>
+  <span>{{ getPosts.loading ? 'loading...' : posts }}</span>
+  <button @click="getUsers">Send Request</button>
+  <button @click="getPosts">Send Request</button>
+</template>
+```
diff --git a/packages/axle/README.zh-CN.md b/packages/axle/README.zh-CN.md
index 0893646..01a9fad 100644
--- a/packages/axle/README.zh-CN.md
+++ b/packages/axle/README.zh-CN.md
@@ -295,21 +295,27 @@ const axle = createAxle(/** @see https://axios-http.com **/)
 
 const useAxle = createUseAxle({
   axle,
-  // 可选项: useAxle 的默认 immediate
-  immediate: true,
+  // 可选项: useAxle 的默认 immediate, 默认值: true
+  immediate: false,
   // 可选项: useAxle 的默认 onTransform
   onTransform: (response) => response,
 })
 
-const [users, getUsers, { loading, error, uploadProgress, downloadProgress, abort }] = useAxle({
+const [
+  users, 
+  // 请求触发器
+  getUsers, 
+  // 附加属性
+  { loading, error, uploadProgress, downloadProgress, abort }
+] = useAxle({
   // 请求初始化数据
   value: [],
   // 请求方法
   method: 'get',
   // 请求地址, 可以是 getter 函数
   url: '/user',
-  // 是否立即发送请求, 默认值: false
-  immediate: true,
+  // 是否立即发送请求, 默认值: true
+  immediate: false,
   // 请求前是否需要重置 value, 默认值: false
   resetValue: true,
   // 重置 value 是否对 value 进行拷贝
@@ -367,13 +373,11 @@ const axle = createAxle(/** @see https://axios-http.com **/)
 const useAxle = createUseAxle({ axle })
 
 const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
-  value: [],
   method: 'get',
   url: '/user',
 })
 
 const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
-  value: [],
   method: 'get',
   url: '/role',
 })
@@ -406,3 +410,141 @@ function sendAllRequest() {
   <button @click="sendAllRequest">发送全部请求</button>
 </template>
 ```
+
+### API 定义增强
+
+从 `0.9.0` 开始支持 `createApi`，以增强 API 定义能力。
+
+#### 定义 API
+
+```ts
+import { createAxle } from '@varlet/axle'
+import { createUseAxle } from '@varlet/axle/use'
+import { createApi } from '@varlet/axle/api'
+
+const axle = createAxle({
+  baseURL: '/api',
+})
+
+const useAxle = createUseAxle({
+  axle,
+})
+
+const api = createApi(axle, useAxle)
+
+export const apiGetUsers = api<Response<User[]>>('/user', 'get')
+
+export const apiGetUser = api<Response<User>>('/user/:id', 'get')
+
+export const apiCreateUser = api<Response<User>, CreateUser>('/user', 'post')
+
+export const apiUpdateUser = api<Response<User>, UpdateUser>('/user/:id', 'put')
+
+export const apiDeleteUser = api<Response<User>>('/user/:id', 'delete')
+
+export type Response<T> = {
+  data: T
+  code: number
+  message: string
+  success: boolean
+}
+
+export interface User {
+  id: string
+  name: string
+}
+
+export interface CreateUser {
+  name: string
+}
+
+export interface UpdateUser {
+  name: string
+}
+```
+
+#### 调用 API
+
+```ts
+const route = useRoute()
+
+const [users, getUsers] = apiGetUsers.use<Response<User[]>>(/** 和 useAxle 一致并且扩展了 pathParams **/)
+
+const [user, getUser] = apiGetUser.use<Response<User>>({
+  pathParams: () => ({ id: route.params.id }),
+})
+
+async function handleCreate(params: CreateUser) {
+  const { success } = await apiCreateUser.load(params)
+
+  if (success) {
+    getUsers()
+  }
+}
+
+async function handleUpdate(params: UpdateUser, id: string) {
+  const { success } = await apiUpdateUser.load(params, { id })
+
+  if (success) {
+    getUsers()
+  }
+}
+
+async function handleDelete(id: string) {
+  const { success } = await apiDeleteUser.load({}, { id })
+
+  if (success) {
+    getUsers()
+  }
+}
+```
+
+### 请求触发器增强
+
+从 `v0.10.0` 开始, 请求触发器将包含附加属性中的全部属性。
+
+增强前:
+
+```html
+<script setup>
+const [users, getUsers, { loading: isUsersLoading }] = useAxle({
+  method: 'get',
+  url: '/user',
+})
+
+const [posts, getPosts, { loading: isPostsLoading }] = useAxle({
+  method: 'get',
+  url: '/post',
+})
+</script>
+
+<template>
+  <span>{{ isUsersLoading ? 'loading...' : users }}</span>
+  <span>{{ isPostsLoading ? 'loading...' : posts }}</span>
+  <button @click="getUsers">Send Request</button>
+  <button @click="getPosts">Send Request</button>
+</template>
+```
+
+增强后:
+
+```html
+<script setup>
+const [users, getUsers] = useAxle({
+  method: 'get',
+  url: '/user',
+})
+
+const [posts, getPosts] = useAxle({
+  method: 'get',
+  url: '/post',
+})
+</script>
+
+<template>
+  <span>{{ getUsers.loading ? 'loading...' : users }}</span>
+  <span>{{ getPosts.loading ? 'loading...' : posts }}</span>
+  <button @click="getUsers">Send Request</button>
+  <button @click="getPosts">Send Request</button>
+</template>
+```