@movk/core 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 [![Movk Core](https://core.mhaibaraai.cn/og-image.png)](https://core.mhaibaraai.cn/)
 
-> `@movk/core` 是一个为 TypeScript 项目设计的现代化、支持 tree-shaking 的工具函数库，涵盖了数组、对象、字符串、异步操作等多个方面。
+> `@movk/core` 是一个为 TypeScript 项目设计的现代化、支持 Tree-Shaking 的工具函数库，涵盖了数组、对象、字符串、异步操作等多个方面。
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![npm version][npm-version-src]][npm-version-href]
@@ -14,11 +14,11 @@
 
 ## ✨ 特性
 
-- **现代化**: 使用 TypeScript 构建，提供完整的类型定义。
-- **Tree-Shaking**: 只打包你需要的代码，减小生产环境的包体积。
-- **功能丰富**: 涵盖数组、对象、字符串、异步等多种工具函数。
-- **组合式**: 提供 Vue Composables，方便在 Vue 项目中使用。
-- **文档齐全**: 提供完善的文档和示例。
+- **完整类型定义**：使用 TypeScript 构建，提供完整的类型定义和卓越的类型推断。
+- **支持 Tree-Shaking**：精心设计的模块化结构，只打包你需要的代码，减小生产环境的包体积。
+- **80+ 实用工具**：涵盖数组、对象、字符串、异步操作、URL 处理、树形结构等多个领域。
+- **Vue 组合式函数**：提供 `useAppStorage`、`useCopyCode` 等即用型 Vue Composables。
+- **现代化构建**：使用 Unbuild 构建，原生支持 ES Modules，无缝融入现代前端工程化体系。
 
 ## 🚀 快速开始
 
@@ -33,96 +33,69 @@ yarn add @movk/core
 npm install @movk/core
 ```
 
-## 📖 API 参考
-
-### Composables (组合式函数)
-
-- `useAppStorage`: 用于管理 `localStorage` 或 `sessionStorage` 中应用程序数据的组合式函数。
-- `useCopyCode`: 用于将文本复制到剪贴板的组合式函数。
-
-### Utils (工具函数)
-
-#### Array (数组)
-
-- `unique`: 创建一个不含重复元素的数组副本。
-- `chunk`: 将数组拆分成多个指定大小的块。
-- `flatten`: 将嵌套数组展平到指定深度。
-
-#### Async (异步)
-
-- `throttle`: 创建一个节流函数，在指定时间间隔内最多只执行一次。
-- `debounce`: 创建一个防抖函数，在指定延迟后执行，延迟时间会在每次调用时重置。
-- `sleep`: 将执行暂停指定的毫秒数。
-- `sleepWithCancel`: 可取消的 `sleep` 版本。
-
-#### File (文件)
-
-- `formatFileSize`: 将文件大小（字节）格式化为人类可读的字符串。
-- `extractFilename`: 从 `Content-Disposition` 响应头中提取文件名。
-- `triggerDownload`: 在浏览器中触发文件下载。
-
-#### Object (对象)
-
-- `isValidContainer`: 检查一个值是否为有效的容器（对象或数组）。
-- `toPath`: 将路径字符串或数组转换为路径数组。
-- `getPath`: 获取对象中指定路径的值。
-- `setPath`: 设置对象中指定路径的值。
-- `joinPath`: 将多个路径片段连接成一个路径字符串。
-- `deepClone`: 创建一个值的深拷贝。
-- `pick`: 从对象中挑选指定的属性，创建一个新对象。
-- `separate`: 将对象根据指定的键分割成两个对象。
-- `separateMany`: 根据多个键组将对象分割成多个对象。
-- `convertToKebabCase`: 将对象的所有键转换为 kebab-case 格式。
-- `omit`: `pick` 的反向操作；创建一个省略了指定属性的新对象。
-- `omitUndefined`: 创建一个移除了所有 `undefined` 属性的新对象。
-
-#### String (字符串)
-
-- `startCase`: 将字符串转换为 [Start Case](https://en.wikipedia.org/wiki/Letter_case#Stylistic_or_specialised_usage) 格式。
-- `camelCase`: 将字符串转换为 [camelCase](https://en.wikipedia.org/wiki/Camel_case) 格式。
-- `kebabCase`: 将字符串转换为 [kebab-case](https://en.wikipedia.org/wiki/Kebab_case) 格式。
-- `snakeCase`: 将字符串转换为 [snake_case](https://en.wikipedia.org/wiki/Snake_case) 格式。
-- `pascalCase`: 将字符串转换为 [PascalCase](https://en.wikipedia.org/wiki/Pascal_case) 格式。
-- `capitalize`: 将字符串的第一个字符转换为大写，其余转换为小写。
-- `upperFirst`: 将字符串的第一个字符转换为大写。
-- `lowerFirst`: 将字符串的第一个字符转换为小写。
-- `upperCase`: 将整个字符串转换为大写。
-- `lowerCase`: 将整个字符串转换为小写。
-- `words`: 将字符串拆分为一个单词数组。
-
-#### Tree (树)
-
-一个包含用于处理树状数据结构的静态方法的类。
-
-- `fromList`: 将扁平的对象列表转换为树状结构。
-- `toList`: 将树状结构转换为扁平的对象列表。
-- `estimateSize`: 估算树中的节点总数。
-- `find`: 查找树中满足条件的第一个节点。
-- `findAll`: 查找树中所有满足条件的节点。
-- `findById`: 按 ID 查找树中的节点。
-- `getStats`: 获取关于树的统计信息（总节点数、叶子节点数、深度等）。
-- `filter`: 过滤树，只保留满足条件的节点（及其祖先）。
-- `transform`: 创建一个具有相同结构的新树，但每个节点都经过转换函数处理。
-- `forEach`: 对树中的每个节点执行一次提供的函数。
-- `insertBefore`: 在目标节点之前插入一个新节点。
-- `insertAfter`: 在目标节点之后插入一个新节点。
-- `remove`: 从树中移除一个节点。
-- `validate`: 验证树结构的完整性。
-
-#### Utilities (实用工具)
-
-- `getRandomUUID`: 生成一个随机的 UUID。
-- `simpleHash`: 从字符串创建一个简单的哈希值。
-
-#### Validator (验证器)
-
-- `isObject`: 检查值是否为对象。
-- `isArray`: 检查值是否为数组。
-- `isString`: 检查值是否为字符串。
-- `isNumber`: 检查值是否为数字。
-- `isFunction`: 检查值是否为函数。
-- `isEmpty`: 检查值是否为空。
-- `isPlainObject`: 检查值是否为纯粹的对象（plain object）。
+## 📖 模块概览
+
+`@movk/core` 提供以下模块：
+
+### Composables
+
+Vue 组合式函数，用于状态管理、剪贴板操作等常见场景。
+
+### Validators
+
+类型检查和验证工具，包括 `isObject`、`isArray`、`isString` 等。
+
+### Utilities
+
+通用工具函数，包括 UUID 生成、哈希计算等。
+
+### Transformers
+
+数据转换工具，包括：
+
+- **String**：字符串格式转换（camelCase、kebabCase、snakeCase 等）
+- **Object**：对象操作（pick、omit、deepClone、路径访问等）
+- **Tree**：树形数据结构操作（遍历、查找、转换等）
+
+### Helpers
+
+专用辅助函数，包括：
+
+- **Array**：数组操作（unique、chunk、flatten）
+- **Async**：异步控制（throttle、debounce、sleep）
+- **File**：文件处理（格式化大小、触发下载等）
+
+## 📁 目录结构
+
+```
+src/
+├── composables/          # Vue 组合式函数
+│   ├── useAppStorage     # 应用存储管理
+│   └── useCopyCode       # 剪贴板复制
+├── validators/           # 类型验证工具
+│   ├── isObject          # 对象检查
+│   ├── isArray           # 数组检查
+│   ├── isString          # 字符串检查
+│   └── ...               # 其他验证器
+├── utilities/            # 通用工具函数
+│   ├── array/            # 数组工具
+│   ├── async/            # 异步工具
+│   └── url/              # URL 工具
+├── transformers/         # 数据转换工具
+│   ├── string/           # 字符串转换
+│   ├── object/           # 对象转换
+│   └── tree/             # 树形结构操作
+│       ├── fromList      # 扁平转树形
+│       ├── toList        # 树形转扁平
+│       ├── find          # 节点查找
+│       ├── filter        # 节点过滤
+│       ├── transform     # 节点转换
+│       └── ...           # 其他树操作
+└── helpers/              # 辅助函数
+    ├── file/             # 文件处理
+    ├── object/           # 对象操作
+    └── path/             # 路径处理
+```
 
 ## ⚡ 技术栈
 

package/bin/clean.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { rm } from 'node:fs/promises'
+import { relative, resolve } from 'node:path'
+import process from 'node:process'
+import fg from 'fast-glob'
+
+const DEFAULT_TARGETS = [
+  'node_modules',
+  '.nuxt',
+  '.data',
+  '.output',
+  '.cache',
+  'dist',
+  'dist.zip'
+]
+const BATCH_SIZE = 10
+
+async function removePath(path) {
+  try {
+    await rm(path, { recursive: true, force: true, maxRetries: 3 })
+    return { path, success: true }
+  }
+  catch (e) {
+    if (e.code === 'ENOENT')
+      return { path, success: true }
+    return { path, success: false, error: e.message }
+  }
+}
+
+async function processBatch(paths) {
+  const results = []
+  for (let i = 0; i < paths.length; i += BATCH_SIZE) {
+    const batch = paths.slice(i, i + BATCH_SIZE)
+    results.push(...await Promise.all(batch.map(removePath)))
+  }
+  return results
+}
+
+async function clean() {
+  const start = Date.now()
+  const args = process.argv.slice(2)
+  const targets = args.length > 0 ? args : DEFAULT_TARGETS
+  const root = resolve(process.cwd())
+
+  let paths
+  try {
+    paths = await fg(targets.map(t => `**/${t}`), {
+      cwd: root,
+      onlyFiles: false,
+      dot: true,
+      absolute: true,
+      ignore: ['**/node_modules/**/node_modules/**'],
+      suppressErrors: true
+    })
+  }
+  catch (e) {
+    console.error('搜索失败:', e.message)
+    process.exit(1)
+  }
+
+  if (!paths.length) {
+    console.log('未找到需要清理的目标')
+    return
+  }
+
+  paths = [...new Set(paths)].sort((a, b) => b.length - a.length)
+
+  const results = await processBatch(paths)
+  const removed = results.filter(r => r.success).length
+  const failed = results.filter(r => !r.success)
+  const duration = ((Date.now() - start) / 1000).toFixed(2)
+
+  console.log(`已清理 ${removed}/${results.length} 项，耗时 ${duration}s`)
+
+  if (failed.length) {
+    console.warn(`\n${failed.length} 项清理失败:`)
+    failed.forEach(f => console.warn(`  ${relative(root, f.path)}: ${f.error}`))
+    process.exit(1)
+  }
+}
+
+process.on('SIGINT', () => {
+  console.log('\n清理中断')
+  process.exit(130)
+})
+
+clean().catch((e) => {
+  console.error('清理失败:', e.message)
+  process.exit(1)
+})