Initial TrueGrowth source import

packages/utils/README.md

@@ -0,0 +1,311 @@
+# @aitu/utils
+
+Opentu 项目的共享工具函数库，提供常用的工具函数和格式化方法。
+
+## 功能模块
+
+### 函数工具 (Function)
+
+#### debounce
+防抖函数，延迟执行函数调用。
+
+```typescript
+import { debounce } from '@aitu/utils';
+
+const debouncedFn = debounce((value: string) => {
+  console.log(value);
+}, 300);
+
+debouncedFn('hello'); // 300ms 后执行
+```
+
+#### throttle
+节流函数，限制函数调用频率。
+
+```typescript
+import { throttle } from '@aitu/utils';
+
+const throttledFn = throttle((event: MouseEvent) => {
+  console.log(event);
+}, 100);
+
+window.addEventListener('scroll', throttledFn);
+```
+
+### 格式化工具 (Format)
+
+#### formatFileSize
+格式化文件大小为人类可读格式。
+
+```typescript
+import { formatFileSize } from '@aitu/utils';
+
+formatFileSize(1024); // "1 KB"
+formatFileSize(1048576); // "1 MB"
+formatFileSize(1073741824); // "1 GB"
+```
+
+#### formatDate
+格式化时间戳为 YYYY-MM-DD HH:mm:ss 格式。
+
+```typescript
+import { formatDate } from '@aitu/utils';
+
+formatDate(Date.now()); // "2026-01-06 20:30:45"
+formatDate(1704556800000); // "2024-01-06 20:00:00"
+```
+
+#### formatDuration
+格式化毫秒数为可读的时长字符串。
+
+```typescript
+import { formatDuration } from '@aitu/utils';
+
+formatDuration(1000); // "1s"
+formatDuration(65000); // "1m 5s"
+formatDuration(3665000); // "1h 1m 5s"
+```
+
+### 字符串工具 (String)
+
+#### sanitizeFilename
+清理字符串使其适合作为文件名。
+
+```typescript
+import { sanitizeFilename } from '@aitu/utils';
+
+sanitizeFilename('Hello World! 你好世界'); // "Hello-World-你好世界"
+sanitizeFilename('file@#$%name.txt', 20); // "filename.txt"
+```
+
+#### truncate
+截断字符串到指定长度并添加省略号。
+
+```typescript
+import { truncate } from '@aitu/utils';
+
+truncate('Hello World', 5); // "Hello..."
+truncate('Hello World', 20); // "Hello World"
+truncate('Hello World', 8, '…'); // "Hello W…"
+```
+
+#### capitalize
+首字母大写。
+
+```typescript
+import { capitalize } from '@aitu/utils';
+
+capitalize('hello world'); // "Hello world"
+capitalize('HELLO'); // "HELLO"
+```
+
+#### toKebabCase
+转换为 kebab-case 格式。
+
+```typescript
+import { toKebabCase } from '@aitu/utils';
+
+toKebabCase('HelloWorld'); // "hello-world"
+toKebabCase('hello_world'); // "hello-world"
+toKebabCase('Hello World'); // "hello-world"
+```
+
+#### toCamelCase
+转换为 camelCase 格式。
+
+```typescript
+import { toCamelCase } from '@aitu/utils';
+
+toCamelCase('hello-world'); // "helloWorld"
+toCamelCase('hello_world'); // "helloWorld"
+toCamelCase('Hello World'); // "helloWorld"
+```
+
+### 颜色工具 (Color)
+
+提供纯函数的颜色处理工具，支持 hex 颜色转换和透明度计算。
+
+```typescript
+import {
+  applyOpacityToHex,
+  hexAlphaToOpacity,
+  removeHexAlpha,
+  isValidColor,
+  TRANSPARENT,
+  NO_COLOR,
+  WHITE
+} from '@aitu/utils';
+
+// 应用不透明度到 hex 颜色
+applyOpacityToHex('#FF0000', 50); // "#FF000080" (50% 不透明度)
+
+// 提取 hex 颜色的不透明度
+hexAlphaToOpacity('#FF000080'); // 50
+
+// 移除 alpha 通道
+removeHexAlpha('#FF0000FF'); // "#FF0000"
+
+// 颜色常量
+console.log(TRANSPARENT); // "TRANSPARENT"
+console.log(NO_COLOR); // "NO_COLOR"
+console.log(WHITE); // "#FFFFFF"
+```
+
+### 日志工具 (Logger)
+
+提供环境感知的日志工具，开发环境显示调试信息，生产环境仅显示警告和错误。
+
+```typescript
+import { createLogger, logger } from '@aitu/utils';
+
+// 创建命名空间日志器
+const moduleLogger = createLogger('MyModule');
+moduleLogger.debug('调试信息'); // 仅开发环境
+moduleLogger.info('普通信息'); // 仅开发环境
+moduleLogger.warn('警告信息'); // 始终显示
+moduleLogger.error('错误信息'); // 始终显示
+
+// 使用默认日志器
+logger.debug('调试消息');
+logger.error('发生错误');
+```
+
+### 异步工具 (Async)
+
+Promise 和事件处理相关的工具函数。
+
+```typescript
+import { isPromiseLike, composeEventHandlers } from '@aitu/utils';
+
+// 类型守卫：检查值是否为 Promise
+const value: unknown = fetchData();
+if (isPromiseLike(value)) {
+  value.then(data => console.log(data));
+}
+
+// 组合多个事件处理器
+const userHandler = (e) => console.log('用户处理');
+const libHandler = (e) => console.log('库处理');
+const composed = composeEventHandlers(userHandler, libHandler);
+button.addEventListener('click', composed);
+```
+
+### 数组工具 (Array)
+
+数组操作和转换的工具函数。
+
+```typescript
+import { splitRows, chunk } from '@aitu/utils';
+
+// 将数组分割为指定大小的行
+const items = [1, 2, 3, 4, 5, 6, 7];
+splitRows(items, 3); // [[1, 2, 3], [4, 5, 6], [7]]
+
+// chunk 是 splitRows 的别名
+chunk(items, 2); // [[1, 2], [3, 4], [5, 6], [7]]
+```
+
+### TypeScript 类型工具 (Types)
+
+TypeScript 类型推断辅助类型。
+
+```typescript
+import type { ResolutionType, ValueOf } from '@aitu/utils';
+
+// 提取 Promise 解析类型
+async function fetchUser() {
+  return { id: 1, name: 'Alice' };
+}
+type User = ResolutionType<typeof fetchUser>; // { id: number; name: string }
+
+// 提取对象值类型
+const colors = {
+  red: '#FF0000',
+  blue: '#0000FF',
+} as const;
+type ColorValue = ValueOf<typeof colors>; // '#FF0000' | '#0000FF'
+```
+
+### 编码工具 (Encoding)
+
+数据编码和格式转换工具。
+
+```typescript
+import { base64ToBlob } from '@aitu/utils';
+
+// 将 base64 data URL 转换为 Blob
+const dataUrl = 'data:image/png;base64,iVBORw0KGgo...';
+const blob = base64ToBlob(dataUrl);
+
+// 使用 Blob 进行文件下载、上传等操作
+const url = URL.createObjectURL(blob);
+```
+
+### URL 工具 (URL)
+
+URL 解析、域名检查和文件扩展名检测工具。
+
+```typescript
+import {
+  isDomainMatch,
+  isVolcesDomain,
+  getFileExtension,
+  getHostname,
+  isDataURL,
+  isAbsoluteURL,
+} from '@aitu/utils';
+
+// 检查 URL 是否匹配特定域名模式
+isDomainMatch('https://cdn.example.com/file.jpg', ['.example.com']);
+// true
+
+// 检查是否为火山引擎域名（专用函数）
+isVolcesDomain('https://cdn.volces.com/video.mp4');
+// true
+
+// 从 URL 或 MIME 类型获取文件扩展名
+getFileExtension('https://example.com/image.jpg');
+// "jpg"
+getFileExtension('data:image/svg+xml;base64,...');
+// "svg"
+getFileExtension('https://api.example.com/download/123', 'video/mp4');
+// "mp4"
+
+// 提取主机名
+getHostname('https://www.example.com/path');
+// "www.example.com"
+
+// 检查是否为 data URL
+isDataURL('data:image/png;base64,...');
+// true
+
+// 检查是否为绝对 URL
+isAbsoluteURL('https://example.com/path');
+// true
+```
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 类型检查
+pnpm exec tsc --noEmit -p packages/utils
+
+# 代码检查
+pnpm exec eslint packages/utils/src
+
+# 构建
+pnpm exec nx build utils
+
+# 运行测试
+pnpm exec nx test utils
+
+# 运行测试并生成覆盖率报告
+cd packages/utils && pnpm exec vitest run --coverage
+```
+
+## License
+
+MIT