@okcy/alova 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# @okcy/alova
+
+基于 [alova](https://alova.js.org) 的 Vue 3 增强 HTTP 请求层。
+
+封装了请求/响应拦截、全局 loading、401/400/403 错误处理、分页、表单、串行请求等通用逻辑。
+
+## 安装
+
+```bash
+pnpm add @okcy/alova
+```
+
+## 快速开始
+
+```ts
+import { createAlova, alovaDefaultOptions } from "@okcy/alova";
+import { createHookHandler, createMethodHandler } from "@okcy/alova";
+
+// 1. 创建 alova 实例
+const alova = createAlova({
+  baseURL: "https://api.example.com",
+  ...alovaDefaultOptions,
+});
+
+// 2. 配置请求/响应/错误处理
+const methodHandler = createMethodHandler({
+  onAuth: () => router.push("/login"),
+  onE400: (res) => /* 处理参数校验错误 */ res,
+  onE403: () => /* 无权限处理 */,
+  onError: (res) => /* 通用错误处理 */,
+  onRequest: (method) => /* 请求前处理（如加 token） */,
+  onResponse: (data) => data,
+});
+
+// 3. 绑定到 alova
+alova.beforeRequest(methodHandler.beforeRequest);
+alova.response.onSuccess(methodHandler.responseHandler);
+alova.response.onError(methodHandler.errorHandler);
+
+// 4. 创建 hook 处理器
+const hooks = createHookHandler({
+  onLoading: (loading, instance, msg) => /* 全局 loading 控制 */,
+  onPagination: (ctx) => /* 分页状态同步 */,
+});
+
+export const useList = hooks.usePagination;
+export const useDetail = hooks.useRequest;
+export const useFormData = hooks.useForm;
+```
+
+## API
+
+### createAlova(alovaOptions)
+
+创建 alova 实例。`alovaDefaultOptions` 提供默认配置：
+- `statesHook: VueHook`
+- `timeout: 30000ms`
+- `cacheFor: GET 500ms`
+
+### createMethodHandler(options)
+
+创建请求/响应/错误统一处理器：
+
+| 选项 | 说明 |
+|------|------|
+| `onAuth()` | 401 时触发（如跳转登录页） |
+| `onE400(res, method)` | 400 参数校验失败回调，返回值会合并到 reject 的 data |
+| `onE403(res, method)` | 403 无权限回调 |
+| `onError(res, method)` | 其他错误回调 |
+| `onRequest(method)` | 请求前置处理（如添加 token） |
+| `onResponse(data, method)` | 响应数据预处理 |
+
+### createHookHandler(options)
+
+创建增强版的 alova hooks，自动处理 loading 状态：
+
+| 选项 | 说明 |
+|------|------|
+| `onLoading(loading, instance, msg?)` | loading 状态变化回调 |
+| `onPagination?(ctx)` | 分页状态同步（如更新 UI 组件） |
+| `paginationConfig?()` | 分页默认配置 |
+| `paginationRouter?(params)` | 分页参数路由同步 |
+
+返回 hooks：
+- **usePagination** — 增强分页，自动管理 `params`、路由同步、重置
+- **useRequest** — 增强请求，支持 `force()` 强制刷新
+- **useForm** — 增强表单，支持 400 错误回显
+- **useSerialRequest** — 串行请求
+
+### 工具函数
+
+```ts
+import { excludeNull, invalidateCache } from "@okcy/alova";
+
+excludeNull({ a: "  ", b: "hello", c: NaN });
+// => { b: "hello" }
+```
+
+### 缓存辅助
+
+```ts
+import { cacheForSec, cacheForMin, cacheForHour, cacheForDay } from "@okcy/alova";
+```
+
+### 类型
+
+```ts
+import type { ResponseData, ResponseList, ResponsePage, ResponseError } from "@okcy/alova";
+import type { UsePaginationResult, UseRequestResult, UseFormResult } from "@okcy/alova";
+```
+
+## 依赖
+
+- Vue 3、alova
+- `@okcy/core`（emittery）
+- query-string

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+import { AlovaMethodHandler, FormHookConfig, PaginationHookConfig, RequestHookConfig, UseHookExposure, UsePaginationExposure, createClientTokenAuthentication } from "alova/client";
+import qs from "query-string";
+import { AlovaGenerics, DetailCacheConfig, Method, Method as Method$1, createAlova, invalidateCache, queryCache, setCache } from "alova";
+import { ComponentInternalInstance, Ref } from "vue";
+//#region src/response.d.ts
+type ResponseData<T = any> = {
+  code: number;
+  data?: T;
+  msg: string;
+};
+type ResponseError<T = any> = {
+  body?: ResponseData<T>;
+  fields: {
+    [name: string]: string;
+  };
+};
+type ResponsePage = {
+  current?: number;
+  total: number;
+  pageSize: number;
+  offset?: number;
+  totalPage?: number;
+};
+type ResponseList<T> = {
+  page: ResponsePage;
+  list: T[];
+};
+//#endregion
+//#region src/alova.axios.d.ts
+declare const alovaDefaultOptions: {
+  statesHook: import("alova/vue").VueHookType;
+  responded: {
+    onError: (err: any, method: any) => Promise<never>;
+    onComplete(method: any): void;
+  };
+  timeout: number;
+  cacheFor: {
+    GET: {
+      expire: number;
+    };
+    HEAD: number;
+  };
+};
+//#endregion
+//#region src/pagination.d.ts
+type Obj = Record<string, any>;
+type AG$3<T> = AlovaGenerics<T, T, T, T, T>;
+interface UsePaginationOptions<Q extends Obj = Obj> extends PaginationHookConfig<any, any> {
+  params?: Q | Record<string, any>;
+  transform?: (params: Q) => void;
+}
+type PaginationMethodHandler<T, Q extends Obj = Obj> = (params: Q) => Method$1<any>;
+type OldUsePaginationExposure<T> = Omit<UsePaginationExposure<AG$3<T>, T[], any[]>, "onSuccess">;
+interface UsePaginationResult<T, Q extends Obj = Obj> extends OldUsePaginationExposure<T>, Pick<UseBaseHookExposure<T, AG$3<T>, UsePaginationResult<T, Q>>, "onBefore"> {
+  loading: Ref<boolean>;
+  params: Q;
+  data: Ref<T[]>;
+  /**
+   * 分页配置
+   */
+  pagination: Ref<any>;
+  /**
+   * 重置分页参数
+   * @param params 分页参数
+   * @returns 无
+   */
+  reset: () => void;
+  /**
+   * 分页路由更新
+   * @param params 分页参数
+   * @returns 无
+   */
+  onRouter: (handler?: (params: Q | any) => void) => UsePaginationResult<T, Q>;
+  /**
+   * 重置分页参数
+   * @param params 分页参数
+   * @returns 无
+   */
+  onReset: (handler?: (params: Q) => void) => UsePaginationResult<T, Q>;
+  /**
+   * 请求成功回调
+   * @param response 响应数据
+   * @returns 无
+   */
+  onSuccess: (handler?: (response: {
+    data: ResponseList<T>;
+  }) => void) => UsePaginationResult<T, Q>;
+}
+type UsePaginationHook = <T = any, Q extends Obj = Obj>(handler: PaginationMethodHandler<T, Q>, options?: UsePaginationOptions<Q>) => UsePaginationResult<T, Q>;
+//#endregion
+//#region src/request.d.ts
+type AG$2<T> = AlovaGenerics<T, T, T, T, T>;
+interface UseRequestResult<T> extends UseBaseHookExposure<T, AG$2<T>, UseRequestResult<T>> {
+  /**
+   * 强制请求
+   * @returns
+   */
+  force: () => UseRequestResult<T>;
+  data: Ref<T>;
+}
+type UseRequestHook = <T = any>(handler: Method$1<any> | AlovaMethodHandler<any, any>, config?: RequestHookConfig<AG$2<T>, any>) => UseRequestResult<T>;
+//#endregion
+//#region src/serial-request.d.ts
+type AG$1<T> = AlovaGenerics<T, T, T, T, T>;
+interface UseRequestResult$1<T> extends UseBaseHookExposure<T, AG$1<T>, UseRequestResult$1<T>> {
+  /**
+   * 强制请求
+   * @returns
+   */
+  force: () => UseRequestResult$1<T>;
+  data: Ref<T>;
+}
+type handler = Method$1<any> | AlovaMethodHandler<any, any>;
+type UseSerialRequestHook = <T = any>(handlers: handler[], config?: RequestHookConfig<AG$1<T>, any>) => UseRequestResult$1<T>;
+//#endregion
+//#region src/handler.d.ts
+export interface ErrorWithResponse extends Error {
+  response?: ResponseData;
+}
+interface CreateMethodHandler {
+  onAuth(): void;
+  onE400(response: ResponseData, method: Method$1): Record<string, any>;
+  onE403(response: ResponseData, method: Method$1): void;
+  onError(response: ResponseData, method: Method$1): void;
+  onRequest(method: Method$1<any>): void;
+  onResponse(response: ResponseData, method: Method$1): any;
+}
+export declare const createMethodHandler: (options: CreateMethodHandler) => {
+  beforeRequest: (method: Method$1) => void;
+  errorHandler: (error: ErrorWithResponse, method: Method$1) => Promise<never>;
+  responseHandler: (response: any, method: Method$1) => any;
+};
+export interface CreateHookHandler {
+  /**
+   * 加载状态处理
+   */
+  onLoading(loading: boolean, instance: ComponentInternalInstance, message?: string): void;
+  /**
+   * 分页UI处理
+   */
+  onPagination?(ctx: any): boolean | any;
+  /**
+   * 分页默认配置
+   */
+  paginationConfig?(): PaginationHookConfig<any, any>;
+  /**
+   * 默认分页路由更新
+   * @param params 分页参数
+   * @returns 无
+   */
+  paginationRouter?(params: any): void;
+}
+interface CreateHookHandlerReturn {
+  usePagination: UsePaginationHook;
+  useRequest: UseRequestHook;
+  useForm: UseFormHook;
+  useSerialRequest: UseSerialRequestHook;
+}
+export declare const defaultPaginationConfig: () => PaginationHookConfig<any, any>;
+export declare const createHookHandler: (options: CreateHookHandler) => CreateHookHandlerReturn;
+//#endregion
+//#region src/hook-base.d.ts
+interface UseBaseHookExposure<T, AG extends AlovaGenerics, SelfType = unknown> extends Omit<UseHookExposure<AG, any, SelfType>, "loading"> {
+  loading: Ref<boolean>;
+  isFirst: Ref<boolean>;
+  /**
+   * 请求前调用
+   * @param handler
+   * @param params
+   */
+  onBefore(callback: (handler: {
+    method: Method$1<AG>;
+  }, params: Record<string, any>) => void): SelfType;
+  /**
+   * 响应加载，默认只执行一次
+   * @param first 是否首次调用,默认true
+   * @param message 提示信息
+   */
+  onLoading(first?: boolean, message?: string): SelfType;
+}
+//#endregion
+//#region src/form.d.ts
+type AG<T> = AlovaGenerics<any, T, T, T, T>;
+interface UseFormResult<T> extends UseBaseHookExposure<T, AG<T>, UseFormResult<T>> {
+  e400: Ref<any>;
+  onE400: (handler: (e: any) => void) => UseFormResult<T>;
+  form: Ref<T>;
+  onRestore(handler: () => void): UseFormResult<T>;
+  updateForm(newForm: Partial<T> | ((oldForm: T) => T)): void;
+  initialForm?: Partial<T>;
+  reset(): void;
+}
+interface UseFormOptions<T> extends Omit<FormHookConfig<AG<T>, T, any>, "initialForm"> {
+  initialForm?: Partial<T>;
+}
+type UseFormHook = <T = any>(handler: (form: T) => Method$1<any>, config?: UseFormOptions<T>) => UseFormResult<T>;
+//#endregion
+//#region src/utils.d.ts
+export declare const excludeNull: (params: any) => any;
+//#endregion
+//#region src/index.d.ts
+/**
+ * 缓存配置（秒）
+ */
+export declare const cacheForSec: (sec?: number) => DetailCacheConfig<any>;
+/**
+ * 缓存时间配置
+ * @param minutes 分钟
+ */
+export declare const cacheForMin: (minutes?: number) => DetailCacheConfig<any>;
+/**
+ * 缓存时间配置
+ * @param day 天
+ */
+export declare const cacheForHour: (hour?: number) => DetailCacheConfig<any>;
+export declare const cacheForDay: (day?: number) => DetailCacheConfig<any>;
+//#endregion
+export { type Method, type ResponseData, type ResponseError, type ResponseList, type ResponsePage, type UseFormHook, type UseFormResult, type UsePaginationHook, type UsePaginationResult, type UseRequestHook, type UseRequestResult, type UseSerialRequestHook, alovaDefaultOptions, createAlova, createClientTokenAuthentication, invalidateCache, qs, queryCache, setCache };

package/dist/index.mjs

@@ -0,0 +1,308 @@
+import { createClientTokenAuthentication, useAutoRequest, useForm, usePagination, useRequest, useSerialRequest } from "alova/client";
+import qs, { default as qs$1 } from "query-string";
+import { createAlova, invalidateCache, queryCache, setCache } from "alova";
+import VueHook from "alova/vue";
+import { Emitter } from "@okcy/core/emittery";
+import { getCurrentInstance, reactive, ref, watch } from "vue";
+//#region src/alova.axios.ts
+const alovaDefaultOptions = {
+	statesHook: VueHook,
+	responded: {
+		onError: (err, method) => {
+			const response = err.response || err;
+			return Promise.reject(response);
+		},
+		onComplete(method) {}
+	},
+	timeout: 3e4,
+	cacheFor: {
+		GET: { expire: 500 },
+		HEAD: 500
+	}
+};
+//#endregion
+//#region src/hook-base.ts
+useAutoRequest.onPolling = (notify, config) => {
+	config.notify = notify;
+	config.resume();
+	return () => clearInterval(config.timer);
+};
+const useBase = function(requestHook, methodHandler, config) {
+	const self = this;
+	const instance = getCurrentInstance();
+	const events = new Emitter();
+	const isGlobalLoading = ref(false);
+	const _config = Object.assign(config || {}, { middleware(ctx, next) {
+		ctx.method.meta = {};
+		events.emit("before", ctx);
+		events.emit("loading", {
+			loading: true,
+			method: ctx.method,
+			instance
+		});
+		return next();
+	} });
+	const request = requestHook.bind(self)(methodHandler, _config);
+	request.isFirst = ref(true);
+	request.onBefore = (handler) => {
+		events.on("before", ({ data }) => {
+			handler(data, data.method.config.params);
+		});
+		return request;
+	};
+	const loadingFun = async (ctx, message) => {
+		self.onLoading(true, instance, message);
+		isGlobalLoading.value = true;
+	};
+	request.onLoading = (first = true, message) => {
+		if (first) events.once("loading", ({ data }) => {
+			loadingFun(data, message);
+			return true;
+		});
+		else events.on("loading", ({ data }) => loadingFun(data, message));
+		return request;
+	};
+	request.onComplete((ctx) => {
+		if (isGlobalLoading.value) {
+			self.onLoading(false, instance);
+			isGlobalLoading.value = false;
+		}
+		request.isFirst.value = false;
+		return request;
+	});
+	return request;
+};
+//#endregion
+//#region src/form.ts
+function useForm$1(handler, config) {
+	const events = new Emitter();
+	const self = this;
+	const e400 = ref({});
+	const _config = Object.assign({ initialForm: {} }, config);
+	const req = useBase.bind(self)(useForm, handler, _config);
+	req.onError(({ error }) => {
+		switch (error.code) {
+			case 400:
+				e400.value = error.data;
+				events.emit("e400", e400.value);
+		}
+	});
+	req.e400 = e400;
+	req.onE400 = (handler) => {
+		events.on("e400", () => handler(e400.value));
+		return req;
+	};
+	return req;
+}
+//#endregion
+//#region src/utils.ts
+const excludeNull = (params) => {
+	const q = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (value === "NaN") continue;
+		if (typeof value === "number" && isNaN(value)) continue;
+		if (typeof value === "string" && value.trim() === "") continue;
+		q[key] = typeof value === "string" ? value.trim() : value;
+	}
+	const query = qs$1.stringify(q, {
+		skipNull: true,
+		skipEmptyString: true
+	});
+	return qs$1.parse(query, {
+		parseNumbers: false,
+		parseBooleans: true
+	});
+};
+//#endregion
+//#region src/pagination.ts
+const toNumber = (val) => {
+	const num = Number(val);
+	return isNaN(num) ? 1 : num;
+};
+/**
+* 增强版 usePagination —— 一步完成参数管理 + 请求 + 参数清理
+*/
+function usePagination$1(handler, options) {
+	const self = this;
+	const { params: initialParams = {}, transform, ...config } = options ?? {};
+	const paginationConfig = self.paginationConfig();
+	const events = new Emitter();
+	const params = reactive({ ...initialParams });
+	paginationConfig.initialPage = toNumber(params.current ?? 1);
+	paginationConfig.initialPageSize = toNumber(params.initialPageSize ?? 20);
+	const req = useBase.bind(this)(usePagination, (current, pageSize) => handler({
+		...params,
+		current,
+		pageSize
+	}), Object.assign(paginationConfig, config));
+	req.isLastPage.value = false;
+	const toRouter = (params) => {
+		if (events.listenerCount("router")) events.emit("router", excludeNull(params || {}));
+		else self.paginationRouter?.(excludeNull(params || {}));
+	};
+	watch(() => params.current, (newCurrent) => {
+		params.current = toNumber(newCurrent);
+		params.pageSize = toNumber(params.pageSize || config?.initialPageSize || 20);
+		toRouter(params);
+	});
+	const pagination = ref(self.onPagination?.(req));
+	req.onBefore((ctx, params) => {
+		toRouter(params);
+	});
+	req.onComplete((ctx) => {
+		pagination.value = self.onPagination?.(req);
+	});
+	const result = Object.assign(req, {
+		params,
+		pagination,
+		reset: () => {
+			for (const key in params) delete params[key];
+			events.emit("reset", params);
+			req.reload();
+		},
+		onReset: (handler) => {
+			events.on("reset", ({ data }) => handler(data));
+			return result;
+		},
+		onRouter: (handler) => {
+			events.on("router", ({ data }) => handler(data));
+			return result;
+		}
+	});
+	return result;
+}
+//#endregion
+//#region src/request.ts
+function useRequest$1(handler, config) {
+	const force = ref(false);
+	const _config = Object.assign({ force: () => force.value }, config);
+	const req = useBase.bind(this)(useRequest, handler, _config);
+	req.force = () => {
+		force.value = true;
+		return req;
+	};
+	req.onComplete(() => {
+		force.value = false;
+	});
+	return req;
+}
+//#endregion
+//#region src/serial-request.ts
+function useSerialRequest$1(handlers, config) {
+	const force = ref(false);
+	const _config = Object.assign({ force: () => force.value }, config);
+	const req = useBase.bind(this)(useSerialRequest, handlers, _config);
+	req.force = () => {
+		force.value = true;
+		return req;
+	};
+	req.onComplete(() => {
+		force.value = false;
+	});
+	return req;
+}
+//#endregion
+//#region src/handler.ts
+const createMethodHandler = (options) => {
+	const { onE400, onE403, onError, onAuth, onRequest, onResponse } = options;
+	const beforeRequest = (method) => {
+		onRequest?.(method);
+	};
+	const responseHandler = (response, method) => {
+		const { data, request, ...res } = response;
+		Object.assign(method.meta || {}, { response: res });
+		return onResponse ? onResponse?.(data, method) : data;
+	};
+	const errorHandler = (error, method) => {
+		const { response } = error;
+		if (response) {
+			const res = onResponse?.(response, method);
+			switch (res.code) {
+				case 401:
+					onAuth();
+					break;
+				case 400:
+					res.data = onE400(res, method);
+					break;
+				case 403:
+					onE403(response.data, method);
+					break;
+				default: onError(response.data, method);
+			}
+			return Promise.reject(res);
+		}
+		return Promise.reject({
+			code: "500",
+			data: void 0,
+			msg: error.message
+		});
+	};
+	return {
+		beforeRequest,
+		errorHandler,
+		responseHandler
+	};
+};
+const defaultPaginationConfig = () => {
+	return {
+		initialPage: 1,
+		initialPageSize: 20,
+		preloadPreviousPage: false,
+		preloadNextPage: false,
+		total: (res) => res?.page?.total ?? 0,
+		data: (res) => res?.list ?? []
+	};
+};
+const createHookHandler = (options) => {
+	const { paginationConfig = defaultPaginationConfig, paginationRouter, onPagination, onLoading } = options;
+	return {
+		usePagination: usePagination$1.bind({
+			onPagination,
+			paginationConfig,
+			paginationRouter,
+			onLoading
+		}),
+		useRequest: useRequest$1.bind({ onLoading }),
+		useForm: useForm$1.bind({ onLoading }),
+		useSerialRequest: useSerialRequest$1.bind({ onLoading })
+	};
+};
+//#endregion
+//#region src/index.ts
+/**
+* 缓存配置（秒）
+*/
+const cacheForSec = (sec = 1) => {
+	return {
+		mode: "restore",
+		expire: 1e3 * sec
+	};
+};
+/**
+* 缓存时间配置
+* @param minutes 分钟
+*/
+const cacheForMin = (minutes = 1) => {
+	return {
+		mode: "restore",
+		expire: 6e4 * minutes
+	};
+};
+/**
+* 缓存时间配置
+* @param day 天
+*/
+const cacheForHour = (hour = 1) => {
+	return {
+		mode: "restore",
+		expire: 36e5 * hour
+	};
+};
+const cacheForDay = (day = 1) => {
+	return {
+		mode: "restore",
+		expire: 864e5 * day
+	};
+};
+//#endregion
+export { alovaDefaultOptions, cacheForDay, cacheForHour, cacheForMin, cacheForSec, createAlova, createClientTokenAuthentication, createHookHandler, createMethodHandler, defaultPaginationConfig, excludeNull, invalidateCache, qs, queryCache, setCache };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@okcy/alova",
+  "version": "1.0.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@alova/shared": "1.3.1",
+    "alova": "3.5.0",
+    "query-string": "9.2.2",
+    "vue": "3.5.24",
+    "@okcy/core": "1.0.0"
+  },
+  "devDependencies": {
+    "vite-plus": "0.3.1"
+  },
+  "scripts": {
+    "dev": "vp pack --watch",
+    "build": "vp pack"
+  }
+}