@ruan-cat/utils 1.2.0 → 1.3.1

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@ruan-cat/utils",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "阮喵喵工具集合。一个纯typescript库。",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
-  "homepage": "https://github.com/ruan-cat/vercel-monorepo-test/tree/main/utils",
+  "homepage": "https://utils.ruancat6312.top",
   "bugs": {
     "url": "https://github.com/ruan-cat/vercel-monorepo-test/issues"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ruan-cat/vercel-monorepo-test.git",
-    "directory": "utils"
+    "directory": "packages/utils"
   },
   "exports": {
     ".": {
@@ -35,17 +35,27 @@
   },
   "files": [
     "src",
+    "!src/tests",
     "tsconfig.json"
   ],
   "devDependencies": {
-    "typedoc": "^0.26.7",
-    "typedoc-plugin-markdown": "^4.2.7",
-    "typescript": "5.4.5",
+    "@antfu/utils": "^0.7.10",
+    "@types/qs": "^6.9.17",
+    "@vueuse/integrations": "^12.1.0",
+    "axios": "^1.7.9",
+    "qs": "^6.13.1",
+    "tsup": "^8.3.5",
+    "type-plus": "^7.6.2",
+    "typedoc": "^0.27.0",
+    "typedoc-plugin-markdown": "^4.3.0",
+    "typescript": "5.7.2",
     "unplugin-vue-router": "^0.10.8",
-    "@ruan-cat/vuepress-preset-config": "^0.1.11"
+    "@ruan-cat/vuepress-preset-config": "^0.1.14"
   },
   "peerDependencies": {
-    "typescript": "5.4.5",
+    "@vueuse/integrations": "^12",
+    "axios": "^1.7.x",
+    "typescript": "5.7.2",
     "unplugin-vue-router": "^0.10.8"
   },
   "peerDependenciesMeta": {
@@ -54,12 +64,18 @@
     },
     "unplugin-vue-router": {
       "optional": true
+    },
+    "@vueuse/integrations": {
+      "optional": true
+    },
+    "axios": {
+      "optional": true
     }
   },
   "scripts": {
     "copy-readme": "cpx readme.md docs",
     "copy-changelog": "cpx CHANGELOG.md docs",
-    "typedoc": "typedoc",
+    "typedoc": "typedoc --options typedoc.config.mjs",
     "prettier-docs-(invalid)": "prettier docs/**/*.md --write",
     "docs:dev-main": "vuepress-vite dev docs",
     "docs:dev": "turbo docs:dev",
@@ -72,6 +88,7 @@
     "generate:type-3": "vue-tsc -p tsconfig.types.json",
     "get-type": "pnpm clean:type && pnpm generate:type-3",
     "build:-try-1": "pnpm clean:type && vue-tsc -p tsconfig.build.json",
+    "build:tsup": "tsup",
     "rm:node_modules": "rimraf node_modules"
   }
 }

package/readme.md

@@ -1,5 +1,7 @@
 # 工具包
 
+这是阮喵喵开发的工具包，提供了一些工具函数。
+
 ## TODO: 尝试开发一个 cli
 
 - https://cloud.tencent.com/developer/article/2033881

package/src/Prettify.ts

@@ -10,7 +10,6 @@ export type Prettify<T> = {
 
 /**
  * 转换成 NumberLike 类型
- * @author f1-阮喵喵
  * @description
  * ### *设计理由*
  * 期望让一个数值类型的联合类型 变成`NumberLike`形式的类型

package/src/define-promise-tasks.ts

@@ -0,0 +1,131 @@
+import { type SimpleAsyncTask } from "./simple-promise-tools.ts";
+
+export const taskTypes = <const>["single", "parallel", "queue"];
+
+export type TaskType = (typeof taskTypes)[number];
+
+export interface BaseTask {
+	/** 任务类型 */
+	type: TaskType;
+}
+
+export type Task = SimpleAsyncTask | TasksConfig;
+
+export interface SingleTasks extends BaseTask {
+	type: "single";
+	tasks: Task;
+}
+
+export interface ParallelTasks extends BaseTask {
+	type: "parallel";
+	tasks: Task[];
+}
+
+export interface QueueTasks extends BaseTask {
+	type: "queue";
+	tasks: Task[];
+}
+
+export type TasksConfig = SingleTasks | ParallelTasks | QueueTasks;
+
+export type PromiseTasksConfig = TasksConfig;
+
+function isSingleTasks(config: TasksConfig): config is SingleTasks {
+	return config.type === "single";
+}
+
+function isParallelTasks(config: TasksConfig): config is ParallelTasks {
+	return config.type === "parallel";
+}
+
+function isQueueTasks(config: TasksConfig): config is QueueTasks {
+	return config.type === "queue";
+}
+
+function isSimpleAsyncTask(config: Task): config is SimpleAsyncTask {
+	return typeof config === "function";
+}
+
+function isTasksConfig(config: Task): config is TasksConfig {
+	return typeof config === "object";
+}
+
+/**
+ * 定义异步任务对象
+ * @description
+ * 这个对象是一揽子异步任务的配置
+ */
+export function definePromiseTasks(config: TasksConfig) {
+	return config;
+}
+
+/**
+ * @private 一个工具函数 用于生成异步函数数组
+ * @deprecated 在处理串行任务时 疑似有故障
+ */
+function getPromises(tasks: Task[]): ((...args: any) => Promise<any>)[] {
+	return tasks.map((task) => {
+		return async function (...args: any) {
+			if (isSimpleAsyncTask(task)) {
+				return await task(...args);
+			} else {
+				return await executePromiseTasks(task);
+			}
+		};
+	});
+}
+
+/**
+ * 执行异步函数对象
+ */
+export async function executePromiseTasks(
+	config: TasksConfig,
+	/**
+	 * 上一次递归执行时提供的参数
+	 * @description
+	 * 考虑到递归函数 这里提供了一个参数 用于传递上一次递归执行的结果
+	 */
+	lastParams: any = null,
+): Promise<any> {
+	if (isSingleTasks(config)) {
+		if (isSimpleAsyncTask(config.tasks)) {
+			// 实际执行的 tasks 往往是无参函数 这里为了保险，故主动传递参数
+			return await config.tasks(lastParams);
+		}
+
+		return await executePromiseTasks(config.tasks, lastParams);
+	}
+
+	if (isParallelTasks(config)) {
+		return await Promise.all(
+			config.tasks.map((task) => {
+				if (isSimpleAsyncTask(task)) {
+					// console.log(` 并行任务遇到单独的异步函数 `);
+					return task(lastParams);
+				}
+
+				// console.log(` 并行任务遇到嵌套结构 `);
+				return executePromiseTasks(task, lastParams);
+			}),
+		);
+	}
+
+	if (isQueueTasks(config)) {
+		let res: Awaited<any>;
+		for await (const task of config.tasks) {
+			if (isSimpleAsyncTask(task)) {
+				// console.log(` 串行任务遇到单独的异步函数 `);
+
+				res = await task(lastParams);
+				lastParams = res;
+				// console.log(` 串行任务 单独 res `, res);
+			} else {
+				res = await executePromiseTasks(task, lastParams);
+				lastParams = res;
+				// console.log(` 串行任务 配置 res `, res);
+			}
+		}
+
+		return res;
+	}
+}

package/src/index.ts

@@ -2,5 +2,8 @@ export * from "./rmmv-class-expand-tools.ts";
 export * from "./conditions.ts";
 export * from "./Prettify.ts";
 export * from "./unplugin-vue-router/index.ts";
+export * from "./define-promise-tasks.ts";
+export * from "./simple-promise-tools.ts";
+export * from "./vueuse/useAxios.ts";
 
 export * from "./types/pnpm-workspace.yaml.shim.ts";

package/src/simple-promise-tools.ts

@@ -0,0 +1,55 @@
+// import { uniqueId } from "lodash-es";
+// const getCounter = () => uniqueId();
+
+/** 创建简单的异步任务 */
+export function generateSimpleAsyncTask<T extends (...args: any) => any>(func: T) {
+	// const taskId = getCounter();
+
+	return function (...args: any) {
+		// consola.info(` 这是第 ${taskId} 个异步任务 `);
+		// consola.start(" 这里是新创建的异步函数 检查参数： ", ...args);
+
+		return new Promise<ReturnType<T>>((resolve, reject) => {
+			// consola.start(" 内部promise 检查参数： ", ...args);
+			resolve(func(...args));
+		});
+	};
+}
+
+export type SimpleAsyncTask = ReturnType<typeof generateSimpleAsyncTask>;
+
+export const initFlag = <const>"initFlag";
+
+/**
+ * 以队列串行的形式 串行运行异步函数
+ * @see https://github.com/ascoders/weekly/blob/master/前沿技术/77.精读《用%20Reduce%20实现%20Promise%20串行执行》.md
+ * @version 1
+ */
+async function runPromiseByQueueV1<T>(promises: ((...args: any) => Promise<T>)[]) {
+	promises.reduce(
+		async function (previousPromise, nextPromise, currentIndex) {
+			const response = await previousPromise;
+			// consola.log(` reduce串行函数 currentIndex= ${currentIndex} res =`, response);
+			return await nextPromise(response);
+		},
+		Promise.resolve(initFlag) as Promise<any>,
+	);
+}
+
+/**
+ * 以队列串行的形式 串行运行异步函数
+ * @version 2
+ */
+export async function runPromiseByQueue<T>(promises: ((...args: any) => Promise<T>)[]) {
+	let response: typeof initFlag | Awaited<T> = initFlag;
+	for await (const promise of promises) {
+		response = await promise(response);
+	}
+}
+
+/**
+ * 以并行的形式 并发运行异步函数
+ */
+export async function runPromiseByConcurrency<T>(promises: ((...args: any) => Promise<T>)[]) {
+	await Promise.all(promises.map((promise) => promise()));
+}

package/src/vueuse/useAxios.ts

@@ -0,0 +1,126 @@
+import type { RequiredPick } from "type-plus";
+import type { AxiosRequestConfig, AxiosResponse, AxiosInstance } from "axios";
+import type { UseAxiosOptions, UseAxiosReturn } from "@vueuse/integrations/useAxios";
+
+/** 拓展的类型参数 用于约束必填的字段 */
+export type KeyAxiosRequestConfig<D = any> = keyof AxiosRequestConfig<D>;
+
+/** 填写key值的帮助类型 */
+export type KeyHelper<K extends KeyAxiosRequestConfig> = K;
+
+/**
+ * 创建 AxiosRequestConfig 的各种变种类型
+ * @description
+ * 目前需要给 AxiosRequestConfig 添加必填属性
+ *
+ * 故需要本工具创建各种变种类型
+ *
+ * @example CreateAxiosRequestConfig<"url", D>
+ */
+export type CreateAxiosRequestConfig<K extends keyof Target, D = any, Target = AxiosRequestConfig<D>> = RequiredPick<
+	Target,
+	K
+>;
+
+/** 拓展K泛型后的类型 */
+export interface StrictUseAxiosReturn<
+	T,
+	/**
+	 * 拓展的类型参数 用于约束必填的字段
+	 * @description
+	 * 这里不需要提供默认的取值
+	 */
+	K extends KeyAxiosRequestConfig<D>,
+	R,
+	D,
+> extends UseAxiosReturn<T, R, D> {
+	/**
+	 * Manually call the axios request
+	 */
+	execute: (
+		url?: string | CreateAxiosRequestConfig<K, D>,
+		config?: CreateAxiosRequestConfig<K, D>,
+	) => Promise<StrictUseAxiosReturn<T, K, R, D>>;
+}
+
+/**
+ * 拓展类型参数后的 useAxios 函数
+ * @description
+ * 在我们的封装中 使用本类型
+ */
+export declare function useAxios<
+	T = any,
+	/** 拓展的类型参数 用于约束必填的字段 */
+	K extends KeyAxiosRequestConfig<D> = "url",
+	R = AxiosResponse<T>,
+	D = any,
+>(
+	url: string,
+	config: AxiosRequestConfig<D>,
+	instance: AxiosInstance,
+	options?: UseAxiosOptions,
+): StrictUseAxiosReturn<T, K, R, D> & Promise<StrictUseAxiosReturn<T, K, R, D>>;
+
+/** 包装器的参数 */
+export interface UseAxiosWrapperParams<
+	/**
+	 * 业务数据类型
+	 * @description
+	 * 必须先填写业务类型
+	 */
+	T = any,
+	/**
+	 * AxiosRequestConfig 默认必填的字段
+	 * @description
+	 * 用于约束其他类型的字段
+	 *
+	 * 然后才能填写必传的参数类型
+	 *
+	 * 默认为 必填url请求地址的 config 请求配置
+	 */
+	K extends KeyAxiosRequestConfig<D> = "url",
+	/**
+	 * UseAxiosOptions 的派生类型
+	 */
+	UseAxiosOptionsLike extends UseAxiosOptions = UseAxiosOptions,
+	/**
+	 * AxiosRequestConfig 用的类型
+	 * @description
+	 * 最后才可以传递此类型
+	 */
+	D = any,
+> {
+	/**
+	 * axios的配置类型
+	 * @description
+	 * 默认为 必填url请求地址的 config 请求配置
+	 */
+	config: CreateAxiosRequestConfig<K, D>;
+
+	/**
+	 * axios实例
+	 * @description
+	 * 对于包装器函数而言 必须传递有意义的请求实例
+	 */
+	instance: AxiosInstance;
+
+	/** useAxios 的选项配置 */
+	options: UseAxiosOptionsLike;
+}
+
+/**
+ * useAxios 的包装函数
+ * @description
+ * 其本质是对 useAxios 函数的封装，仅仅是包装了参数层
+ *
+ * 预期设计成一个万能的 通用的请求函数
+ */
+export function useAxiosWrapper<T, K extends KeyAxiosRequestConfig, D = any>(params: UseAxiosWrapperParams) {
+	const {
+		config: { url },
+		config,
+		instance,
+		options,
+	} = params;
+	return useAxios<T, K, AxiosResponse<T>, D>(url, config, instance, options);
+}

package/tsconfig.json

@@ -33,21 +33,16 @@
 			"typedoc",
 			"typedoc-plugin-markdown",
 		],
-		"paths": {
-			"@/*": [
-				"./src/*"
-			]
-		}
 	},
 	"include": [
 		"./src/**/*.ts",
-		"./tests/**/*.ts",
 		"./src/**/*.js",
-		"./tests/**/*.js",
-		// 尝试手动提供一个全局的类型声明。
-		"./tests/with-types/types/CanNewTypeByClass.d.ts",
+		// "./tests/**/*.ts",
+		// "./tests/**/*.js",
 	],
 	"exclude": [
+		// 测试用例的全部文件 交由本项目根目录下的 tsconfig.json 处理
+		"src/tests/**/*.ts",
 		"notuse-typedoc.config.cjs"
 	]
 }