koatty_validation 1.3.6 → 1.6.0

package/dist/package.json

@@ -1,94 +1,91 @@
-{
-  "name": "koatty_validation",
-  "version": "1.3.6",
-  "description": "Validation Util for Koatty and ThinkORM.",
-  "scripts": {
-    "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp",
-    "build:cp": "node scripts/postBuild && npx copyfiles package.json LICENSE README.md dist/",
-    "build:js": "npx rollup --bundleConfigAsCjs -c .rollup.config.js",
-    "build:doc": "npx api-documenter markdown --input temp --output docs/api",
-    "build:dts": "npx tsc && npx api-extractor run --local --verbose",
-    "eslint": "eslint --ext .ts,.js ./",
-    "lock": "npx del-cli --force node_modules && npm i --package-lock-only && npx pnpm i",
-    "prepublishOnly": "npm test && npm run build && git push --follow-tags origin",
-    "prerelease": "npm run lock && npm test && npm run build",
-    "release": "standard-version",
-    "release:pre": "npm run release -- --prerelease",
-    "release:major": "npm run release -- --release-as major",
-    "release:minor": "npm run release -- --release-as minor",
-    "test": "npm run eslint && jest --passWithNoTests",
-    "test:cov": "jest --collectCoverage --detectOpenHandles",
-    "version": "conventional-changelog -p angular -i CHANGELOG.md -s"
-  },
-  "main": "./dist/index.js",
-  "exports": {
-    "require": "./dist/index.js",
-    "import": "./dist/index.mjs",
-    "types": "./dist/index.d.ts"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/koatty/koatty_validation.git"
-  },
-  "engines": {
-    "node": ">10.0.0"
-  },
-  "author": {
-    "name": "richenlin",
-    "email": "richenlin@gmail.com"
-  },
-  "license": "BSD-3-Clause",
-  "bugs": {
-    "url": "https://github.com/koatty/koatty_validation/issues"
-  },
-  "homepage": "https://github.com/koatty/koatty_validation",
-  "maintainers": [
-    {
-      "name": "richenlin",
-      "email": "richenlin@gmail.com"
-    }
-  ],
-  "devDependencies": {
-    "@commitlint/cli": "^19.x.x",
-    "@commitlint/config-conventional": "^19.x.x",
-    "@microsoft/api-documenter": "^7.x.x",
-    "@microsoft/api-extractor": "^7.x.x",
-    "@rollup/plugin-commonjs": "^28.x.x",
-    "@rollup/plugin-json": "^6.x.x",
-    "@rollup/plugin-node-resolve": "^15.x.x",
-    "@types/jest": "^29.x.x",
-    "@types/koa": "^2.x.x",
-    "@types/lodash": "^4.x.x",
-    "@types/node": "^22.x.x",
-    "@types/validator": "^13.x.x",
-    "@typescript-eslint/eslint-plugin": "^8.x.x",
-    "@typescript-eslint/parser": "^8.x.x",
-    "conventional-changelog-cli": "^5.x.x",
-    "eslint": "^8.x.x",
-    "eslint-plugin-jest": "^28.x.x",
-    "husky": "^4.x.x",
-    "jest": "^29.x.x",
-    "jest-html-reporters": "^3.x.x",
-    "libphonenumber-js": "^1.x.x",
-    "reflect-metadata": "^0.x.x",
-    "rollup": "^4.x.x",
-    "rollup-plugin-delete": "^2.1.0",
-    "rollup-plugin-typescript2": "^0.x.x",
-    "standard-version": "^9.x.x",
-    "ts-jest": "^29.x.x",
-    "ts-node": "^10.x.x",
-    "tslib": "^2.x.x",
-    "typescript": "^5.x.x"
-  },
-  "dependencies": {
-    "class-validator": "^0.14.1",
-    "koatty_container": "^1.x.x",
-    "koatty_lib": "^1.x.x",
-    "koatty_logger": "^2.x.x"
-  },
-  "peerDependencies": {
-    "koatty_container": "^1.x.x",
-    "koatty_lib": "^1.x.x",
-    "koatty_logger": "^2.x.x"
-  }
-}
+{
+  "name": "koatty_validation",
+  "version": "1.6.0",
+  "description": "Validation Util for Koatty and ThinkORM.",
+  "scripts": {
+    "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp",
+    "build:cp": "node scripts/postBuild && copyfiles package.json LICENSE README.md dist/",
+    "build:js": "del-cli --force dist && npx rollup --bundleConfigAsCjs -c .rollup.config.js",
+    "build:doc": "del-cli --force docs/api && npx api-documenter markdown --input temp --output docs/api",
+    "build:dts": "del-cli --force temp && npx tsc && npx api-extractor run --local --verbose",
+    "eslint": "eslint --ext .ts,.js ./",
+    "lock": "npm i --package-lock-only",
+    "prepublishOnly": "npm test && npm run build && git push --follow-tags origin",
+    "prerelease": "npm test && npm run build",
+    "release": "standard-version",
+    "release:pre": "npm run release -- --prerelease",
+    "release:major": "npm run release -- --release-as major",
+    "release:minor": "npm run release -- --release-as minor",
+    "test": "npm run eslint && jest --passWithNoTests"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    "require": "./dist/index.js",
+    "import": "./dist/index.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koatty/koatty_validation.git"
+  },
+  "engines": {
+    "node": ">10.0.0"
+  },
+  "author": {
+    "name": "richenlin",
+    "email": "richenlin@gmail.com"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/koatty/koatty_validation/issues"
+  },
+  "homepage": "https://github.com/koatty/koatty_validation",
+  "maintainers": [
+    {
+      "name": "richenlin",
+      "email": "richenlin@gmail.com"
+    }
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "^19.x.x",
+    "@commitlint/config-conventional": "^19.x.x",
+    "@microsoft/api-documenter": "^7.x.x",
+    "@microsoft/api-extractor": "^7.x.x",
+    "@rollup/plugin-json": "^6.x.x",
+    "@types/jest": "^29.x.x",
+    "@types/koa": "^2.x.x",
+    "@types/lodash": "^4.17.17",
+    "@types/node": "^24.x.x",
+    "@types/validator": "^13.x.x",
+    "@typescript-eslint/eslint-plugin": "^8.x.x",
+    "@typescript-eslint/parser": "^8.x.x",
+    "conventional-changelog-cli": "^5.x.x",
+    "copyfiles": "^2.x.x",
+    "del-cli": "^6.x.x",
+    "eslint": "^8.x.x",
+    "eslint-plugin-jest": "^28.x.x",
+    "husky": "^4.x.x",
+    "jest": "^29.x.x",
+    "jest-html-reporters": "^3.x.x",
+    "libphonenumber-js": "^1.x.x",
+    "reflect-metadata": "^0.x.x",
+    "rollup": "^4.x.x",
+    "rollup-plugin-typescript2": "^0.x.x",
+    "standard-version": "^9.x.x",
+    "ts-jest": "^29.x.x",
+    "ts-node": "^10.x.x",
+    "tslib": "^2.x.x",
+    "typescript": "^5.x.x"
+  },
+  "dependencies": {
+    "class-validator": "^0.14.2",
+    "koatty_container": "^1.x.x",
+    "koatty_lib": "^1.x.x",
+    "koatty_logger": "^2.x.x",
+    "lru-cache": "^11.2.2"
+  },
+  "peerDependencies": {
+    "koatty_container": "^1.x.x",
+    "koatty_lib": "^1.x.x",
+    "koatty_logger": "^2.x.x"
+  }
+}

package/examples/README.md

@@ -0,0 +1,90 @@
+# koatty_validation 使用示例
+
+本目录包含了 koatty_validation 的各种使用示例，帮助您快速上手。
+
+## 📁 文件结构
+
+- `basic-usage.ts` - 基础使用示例
+- `custom-decorators.ts` - 自定义装饰器使用示例  
+- `advanced-validation.ts` - 高级验证场景示例
+- `error-handling.ts` - 错误处理示例
+
+## 🚀 快速开始
+
+### 1. 基础验证
+
+```typescript
+import { IsNotEmpty, IsEmail, IsInt } from 'koatty_validation';
+
+class UserDto {
+  @IsNotEmpty()
+  name: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsInt({ min: 18, max: 100 })
+  age: number;
+}
+```
+
+### 2. 自定义装饰器
+
+```typescript
+import { createSimpleDecorator } from 'koatty_validation';
+
+const IsStrongPassword = createSimpleDecorator(
+  'IsStrongPassword',
+  (value: string) => {
+    return /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/.test(value);
+  },
+  'Password must be at least 8 characters with uppercase, lowercase, number and special character'
+);
+
+class RegisterDto {
+  @IsStrongPassword()
+  password: string;
+}
+```
+
+### 3. 中文本土化验证
+
+```typescript
+import { IsCnName, IsIdNumber, IsMobile } from 'koatty_validation';
+
+class ChineseUserDto {
+  @IsCnName()
+  name: string;
+
+  @IsIdNumber()
+  idCard: string;
+
+  @IsMobile()
+  phone: string;
+}
+```
+
+## 📖 详细示例
+
+查看各个示例文件了解更多用法：
+
+- **基础使用**: 查看 `basic-usage.ts`
+- **自定义装饰器**: 查看 `custom-decorators.ts`
+- **高级验证**: 查看 `advanced-validation.ts`
+- **错误处理**: 查看 `error-handling.ts`
+
+## 🔧 运行示例
+
+```bash
+# 编译TypeScript
+npm run build
+
+# 运行示例
+node dist/examples/basic-usage.js
+```
+
+## 📚 更多文档
+
+- [自定义装饰器指南](../CUSTOM_DECORATORS_GUIDE.md)
+- [API文档](../README.md)
+- [测试用例](../test/) 

package/examples/basic-usage.ts

@@ -0,0 +1,239 @@
+/**
+ * koatty_validation 基础使用示例
+ * @author richen
+ */
+
+import { validate } from 'class-validator';
+import {
+  IsNotEmpty,
+  IsEmail,
+  IsCnName,
+  IsIdNumber,
+  IsMobile,
+  Expose
+} from '../src/index';
+import {
+  IsStrongPassword,
+  IsHexColor,
+  IsPositiveInteger,
+  IsFileExtension,
+  MatchesPattern,
+  ArrayLength,
+  InRange
+} from '../examples/custom-decorators-example';
+
+// =============== 用户注册示例 ===============
+
+class UserRegistrationDto {
+  @IsNotEmpty()
+  @IsCnName()
+  name: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsStrongPassword()
+  password: string;
+
+  @IsPositiveInteger()
+  age: number;
+
+  @IsIdNumber()
+  idCard: string;
+
+  @IsMobile()
+  phone: string;
+
+  @IsHexColor()
+  favoriteColor: string;
+
+  @IsFileExtension(['jpg', 'png', 'gif'])
+  avatar: string;
+
+  @MatchesPattern(/^[A-Z]{2,3}$/)
+  countryCode: string;
+
+  @ArrayLength(1, 5)
+  hobbies: string[];
+
+  @InRange(0, 100)
+  completionRate: number;
+
+  @Expose()
+  createdAt: Date = new Date();
+}
+
+// =============== 产品信息示例 ===============
+
+class ProductDto {
+  @IsNotEmpty()
+  @MatchesPattern(/^[A-Z0-9-]+$/)
+  sku: string;
+
+  @IsNotEmpty()
+  title: string;
+
+  @InRange(0.01, 9999999.99)
+  price: number;
+
+  @InRange(0, 10000)
+  stock: number;
+
+  @ArrayLength(1, 10)
+  tags: string[];
+
+  @IsHexColor()
+  primaryColor: string;
+
+  @IsFileExtension(['jpg', 'png', 'webp'])
+  mainImage: string;
+
+  @Expose()
+  isActive: boolean = true;
+}
+
+// =============== 验证演示函数 ===============
+
+async function demonstrateValidation() {
+  console.log('🚀 koatty_validation 基础使用示例\n');
+
+  // ========== 成功验证示例 ==========
+  console.log('✅ 成功验证示例:');
+  
+  const validUser = new UserRegistrationDto();
+  validUser.name = '张三';
+  validUser.email = 'zhangsan@example.com';
+  validUser.password = 'MySecure123!';
+  validUser.age = 25;
+  validUser.idCard = '110101199001011234';
+  validUser.phone = '13812345678';
+  validUser.favoriteColor = '#FF5733';
+  validUser.avatar = 'profile.jpg';
+  validUser.countryCode = 'CN';
+  validUser.hobbies = ['reading', 'coding'];
+  validUser.completionRate = 85;
+
+  const validErrors = await validate(validUser);
+  if (validErrors.length === 0) {
+    console.log('用户注册数据验证通过 ✓');
+  } else {
+    console.log('用户注册数据验证失败:', validErrors.map(e => e.constraints));
+  }
+
+  // ========== 失败验证示例 ==========
+  console.log('\n❌ 失败验证示例:');
+  
+  const invalidUser = new UserRegistrationDto();
+  invalidUser.name = 'John123';          // 不是中文名
+  invalidUser.email = 'invalid-email';   // 无效邮箱
+  invalidUser.password = 'weak';          // 弱密码
+  invalidUser.age = -5;                  // 负数年龄
+  invalidUser.idCard = '123';            // 无效身份证
+  invalidUser.phone = '123';             // 无效手机号
+  invalidUser.favoriteColor = 'red';     // 不是十六进制颜色
+  invalidUser.avatar = 'profile.pdf';    // 不允许的文件类型
+  invalidUser.countryCode = 'china';     // 不符合模式
+  invalidUser.hobbies = [];              // 数组为空
+  invalidUser.completionRate = 150;      // 超出范围
+
+  const invalidErrors = await validate(invalidUser);
+  console.log(`发现 ${invalidErrors.length} 个验证错误:`);
+  
+  invalidErrors.forEach((error, index) => {
+    console.log(`${index + 1}. ${error.property}:`);
+    Object.values(error.constraints || {}).forEach(message => {
+      console.log(`   - ${message}`);
+    });
+  });
+
+  // ========== 产品验证示例 ==========
+  console.log('\n📦 产品信息验证示例:');
+  
+  const product = new ProductDto();
+  product.sku = 'PROD-2024-001';
+  product.title = 'Gaming Laptop';
+  product.price = 1299.99;
+  product.stock = 50;
+  product.tags = ['gaming', 'laptop', 'electronics'];
+  product.primaryColor = '#1E1E1E';
+  product.mainImage = 'laptop.jpg';
+
+  const productErrors = await validate(product);
+  if (productErrors.length === 0) {
+    console.log('产品信息验证通过 ✓');
+    console.log('产品详情:', {
+      sku: product.sku,
+      title: product.title,
+      price: `$${product.price}`,
+      stock: product.stock,
+      tags: product.tags.join(', '),
+      primaryColor: product.primaryColor,
+      isActive: product.isActive
+    });
+  } else {
+    console.log('产品信息验证失败:', productErrors.map(e => e.constraints));
+  }
+}
+
+// =============== 性能测试示例 ===============
+
+async function performanceDemo() {
+  console.log('\n⚡ 性能测试示例:');
+  
+  const testCount = 1000;
+  const startTime = Date.now();
+  
+  for (let i = 0; i < testCount; i++) {
+    const user = new UserRegistrationDto();
+    user.name = '测试用户';
+    user.email = `user${i}@example.com`;
+    user.password = 'Test123!';
+    user.age = 25;
+    user.idCard = '110101199001011234';
+    user.phone = '13812345678';
+    user.favoriteColor = '#FF5733';
+    user.avatar = 'avatar.jpg';
+    user.countryCode = 'CN';
+    user.hobbies = ['test'];
+    user.completionRate = 50;
+    
+    await validate(user);
+  }
+  
+  const endTime = Date.now();
+  const duration = endTime - startTime;
+  
+  console.log(`验证 ${testCount} 个对象耗时: ${duration}ms`);
+  console.log(`平均每个对象: ${(duration / testCount).toFixed(2)}ms`);
+}
+
+// =============== 主函数 ===============
+
+async function main() {
+  try {
+    await demonstrateValidation();
+    await performanceDemo();
+    
+    console.log('\n🎉 所有示例运行完成！');
+    console.log('\n📚 更多示例请查看:');
+    console.log('  - custom-decorators.ts - 自定义装饰器示例');
+    console.log('  - advanced-validation.ts - 高级验证示例');
+    console.log('  - error-handling.ts - 错误处理示例');
+    
+  } catch (error) {
+    console.error('示例运行失败:', error);
+    process.exit(1);
+  }
+}
+
+// 如果直接运行此文件
+if (require.main === module) {
+  main();
+}
+
+export {
+  UserRegistrationDto,
+  ProductDto,
+  demonstrateValidation,
+  performanceDemo
+};