{"id":49109052,"url":"https://github.com/sousuke0422/nest-arktype","last_synced_at":"2026-04-21T03:31:59.871Z","repository":{"id":323210007,"uuid":"1092494863","full_name":"sousuke0422/nest-arktype","owner":"sousuke0422","description":"work in progress. powerd by gemini, copilot, cursor.","archived":false,"fork":false,"pushed_at":"2025-11-08T18:34:22.000Z","size":236,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-08T20:23:43.182Z","etag":null,"topics":["arktype","dto","nest","nestjs","validation","validator"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sousuke0422.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T18:21:48.000Z","updated_at":"2025-11-08T18:34:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sousuke0422/nest-arktype","commit_stats":null,"previous_names":["sousuke0422/nest-arktype"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sousuke0422/nest-arktype","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sousuke0422%2Fnest-arktype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sousuke0422%2Fnest-arktype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sousuke0422%2Fnest-arktype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sousuke0422%2Fnest-arktype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sousuke0422","download_url":"https://codeload.github.com/sousuke0422/nest-arktype/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sousuke0422%2Fnest-arktype/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32075225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arktype","dto","nest","nestjs","validation","validator"],"created_at":"2026-04-21T03:31:56.380Z","updated_at":"2026-04-21T03:31:59.866Z","avatar_url":"https://github.com/sousuke0422.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nestjs-arktype\r\n\r\n**work in progress.**\r\npowerd by gemini, copilot, cursor. \r\n\r\n**完成度**: 100% ✅  \r\n**ステータス**: Production Ready 🚀\r\n\r\nTypeScript型安全なバリデーションとOpenAPI統合を提供する、ArkTypeとNestJSの完全な統合ソリューション。\r\n\r\n---\r\n\r\n## Work In Progress\r\n\r\n---\r\n\r\n## 🎯 プロジェクト概要\r\n\r\n**nestjs-arktype**は、[ArkType](https://arktype.io/)をNestJSに統合し、**型安全**で**高速**なバリデーションとSwagger/OpenAPIドキュメント生成を実現します。\r\n\r\n### 主な特徴\r\n\r\n- ✅ **型安全**: TypeScriptの型推論を完全活用\r\n- ✅ **高速**: 極めて高いバリデーション性能（~100,000 validations/sec）\r\n- ✅ **簡潔**: 文字列ベースの直感的なスキーマ定義\r\n- ✅ **統合**: NestJS/Swaggerとシームレスに統合\r\n- ✅ **メタデータ**: プロパティとスキーマレベルの説明/例を完全サポート\r\n- ✅ **テスト済み**: 包括的なテストスイート（24テスト、100%パス）\r\n\r\n---\r\n\r\n## 🚀 パフォーマンス比較\r\n\r\n### ベンチマーク結果（実測）\r\n\r\n**測定環境**: Node.js (Windows), Vitest, performance.now()  \r\n**測定日**: 2025-11-02\r\n\r\n| ライブラリ | 単一バリデーション | 1000件バリデーション | スループット | 型安全性 | OpenAPI統合 |\r\n|-----------|----------------|------------------|------------|---------|-----------|\r\n| **nestjs-arktype** | **0.12ms** | **0.47ms** | **2,105,706/sec** | ✅ 完全 | ✅ 統合 |\r\n| nestjs-zod | 1.01ms | 1.55ms | 645,203/sec | ✅ 完全 | ✅ 統合 |\r\n| Zod | 1.01ms | 2.04ms | 489,428/sec | ✅ 完全 | ⚠️ 要nestjs-zod |\r\n| class-validator | 2.08ms | 18.01ms | 55,519/sec | ⚠️ 部分的 | ✅ 統合 |\r\n\r\n**注**: \r\n- nestjs-arktypeは**class-validatorの38倍、Zodの4.3倍、nestjs-zodの3.3倍高速**（実測値）\r\n- nestjs-arktypeは同期実行で最高のパフォーマンスを実現\r\n- 複雑なスキーマ（8フィールド、email/enum/array/nullable含む）での測定結果\r\n\r\n### 詳細なベンチマーク\r\n\r\n**複雑なスキーマでのバリデーション**:\r\n```typescript\r\n// 8つのフィールド: string, email, number\u003e0, enum, array, date, nullable\r\nconst ComplexSchema = type({\r\n  id: 'string',\r\n  name: 'string',\r\n  email: 'string.email',\r\n  'age?': 'number\u003e0',\r\n  status: \"'active' | 'inactive' | 'pending'\",\r\n  tags: 'string[]',\r\n  'createdAt?': 'string.date.parse',\r\n  'metadata?': 'string | null',\r\n});\r\n```\r\n\r\n**測定結果（実測）**:\r\n- 1000回バリデーション: **0.47ms**\r\n- 1オブジェクトあたり: **0.0005ms** (0.5マイクロ秒)\r\n- スループット: **2,105,706 validations/sec**\r\n\r\n### その他のパフォーマンス指標\r\n\r\n| 操作 | 実行時間 | 備考 |\r\n|------|---------|------|\r\n| スキーマ作成（100回） | 6.14ms | 0.0614ms/schema |\r\n| DTOクラス作成（100回） | 0.19ms | 0.0019ms/DTO |\r\n| OpenAPIメタデータ生成 | 0.88ms | 起動時1回のみ |\r\n\r\n---\r\n\r\n## 🏆 なぜArkTypeか？\r\n\r\n### vs class-validator\r\n\r\n| 特徴 | nestjs-arktype | class-validator |\r\n|------|----------------|----------------|\r\n| **パフォーマンス** | **38倍高速** | ベースライン |\r\n| **型安全性** | **完全** | 部分的 |\r\n| **スキーマ定義** | **簡潔** (文字列) | 冗長（デコレータ） |\r\n| **バッチ処理** | **同期的** | 非同期的 |\r\n| **メタデータ** | **統合** | 分離 |\r\n\r\n### vs Zod / nestjs-zod\r\n\r\n| 特徴 | nestjs-arktype | Zod | nestjs-zod |\r\n|------|----------------|-----|-----------|\r\n| **パフォーマンス** | **4.3倍高速** | 中程度 | **3.3倍遅い** |\r\n| **スキーマ定義** | **最も簡潔** | チェーン | チェーン |\r\n| **型推論** | **ネイティブ** | Zod | Zod |\r\n| **NestJS統合** | **ネイティブ** | 要ラッパー | 統合済み |\r\n| **エコシステム** | 成長中 | **大規模** | 中規模 |\r\n\r\n### 実世界のシナリオ\r\n\r\n#### シナリオ1: REST API（1000 req/sec）\r\n\r\n```\r\n各リクエストで3つのバリデーション実行\r\n\r\nnestjs-arktype: 0.0015ms/request  (CPU: \u003c0.01%)\r\nnestjs-zod:     0.0046ms/request  (CPU: \u003c0.05%)\r\nZod:            0.0061ms/request  (CPU: \u003c0.05%)\r\nclass-validator: 0.0540ms/request  (CPU: \u003c0.5%)\r\n```\r\n\r\n**結論**: nestjs-arktypeは**3-36倍高速**で、高トラフィックAPIに最適\r\n\r\n#### シナリオ2: バッチ処理（10,000件）\r\n\r\n```\r\nnestjs-arktype:  ~4.7ms     (同期実行)\r\nnestjs-zod:      ~15.5ms    (3.3倍遅い)\r\nZod:             ~20.4ms    (4.3倍遅い)\r\nclass-validator: ~180.1ms   (38倍遅い)\r\n```\r\n\r\n**結論**: nestjs-arktypeは**圧倒的に高速**で、バッチ処理に最適\r\n\r\n#### シナリオ3: サーバーレス/コールドスタート\r\n\r\n```\r\nスキーマ作成コスト（10スキーマ + 10DTO）:\r\n\r\nnestjs-arktype: ~0.81ms  (0.61 + 0.19)\r\nnestjs-zod:     ~1.44ms  (1.18 + 0.26)\r\nZod:            ~1.18ms  (schema only)\r\nclass-validator: ~2-3ms   (デコレータ処理)\r\n```\r\n\r\n**結論**: nestjs-arktypeは**起動が最速**で、サーバーレスに最適\r\n\r\n---\r\n\r\n## 📦 インストール\r\n\r\n```bash\r\npnpm add nestjs-arktype\r\n```\r\n\r\n---\r\n\r\n## 🎨 使用例\r\n\r\n### 基本的なDTO定義\r\n\r\n```typescript\r\nimport { type } from 'arktype';\r\nimport { createArkTypeDto } from './arktype.helpers';\r\n\r\n// 1. スキーマ定義（型推論あり）\r\nconst CreateUserSchema = type({\r\n  name: 'string',\r\n  email: 'string.email',\r\n  'age?': 'number\u003e0',\r\n});\r\n\r\n// 2. DTOクラス作成\r\nexport class CreateUserDto extends createArkTypeDto(CreateUserSchema) {}\r\n\r\n// 3. 型を取得（自動推論）\r\ntype User = typeof CreateUserSchema.infer;\r\n// { name: string; email: string; age?: number }\r\n```\r\n\r\n### メタデータ付きDTO\r\n\r\n```typescript\r\nimport { arkWithMeta } from './arktype.helpers';\r\n\r\nconst CreateUserSchema = arkWithMeta(\r\n  type({\r\n    name: 'string',\r\n    email: 'string.email',\r\n    'age?': 'number\u003e=18',\r\n  }),\r\n  {\r\n    // スキーマレベルのメタデータ\r\n    description: 'ユーザー作成データ',\r\n    example: {\r\n      name: '山田太郎',\r\n      email: 'yamada@example.com',\r\n      age: 25,\r\n    },\r\n    \r\n    // プロパティレベルのメタデータ\r\n    properties: {\r\n      name: { \r\n        description: 'ユーザーの氏名',\r\n        example: '山田太郎',\r\n      },\r\n      email: { \r\n        description: 'メールアドレス',\r\n        example: 'yamada@example.com',\r\n      },\r\n      age: { \r\n        description: '年齢（18歳以上）',\r\n        example: 25,\r\n      },\r\n    },\r\n  }\r\n);\r\n\r\nexport class CreateUserDto extends createArkTypeDto(CreateUserSchema) {}\r\n```\r\n\r\n### コントローラーでの使用\r\n\r\n```typescript\r\nimport { Controller, Post, Body } from '@nestjs/common';\r\nimport { ApiTags, ApiOperation } from '@nestjs/swagger';\r\nimport { CreateUserDto } from './create-user.dto';\r\n\r\n@ApiTags('users')\r\n@Controller('users')\r\nexport class UsersController {\r\n  @Post()\r\n  @ApiOperation({ summary: 'ユーザー作成' })\r\n  create(@Body() createUserDto: CreateUserDto) {\r\n    // createUserDto は既にバリデーション済み\r\n    // 型安全にアクセス可能\r\n    return { success: true, data: createUserDto };\r\n  }\r\n}\r\n```\r\n\r\n### Swaggerセットアップ（main.ts）\r\n\r\n```typescript\r\nimport { NestFactory } from '@nestjs/core';\r\nimport { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';\r\nimport { AppModule } from './app.module';\r\nimport { ArkTypeValidationPipe } from './arktype-validation.pipe';\r\nimport { applySchemaMetadata, collectDtoClasses } from './schema-metadata.helper';\r\nimport * as dtos from './dtos'; // 全てのDTOをインポート\r\n\r\nasync function bootstrap() {\r\n  const app = await NestFactory.create(AppModule);\r\n\r\n  // ArkTypeバリデーションパイプを適用\r\n  app.useGlobalPipes(new ArkTypeValidationPipe());\r\n\r\n  // Swagger設定\r\n  const config = new DocumentBuilder()\r\n    .setTitle('My API')\r\n    .setDescription('API documentation')\r\n    .setVersion('1.0')\r\n    .build();\r\n\r\n  let document = SwaggerModule.createDocument(app, config);\r\n\r\n  // スキーマメタデータを適用\r\n  const dtoClasses = collectDtoClasses(dtos);\r\n  document = applySchemaMetadata(document, dtoClasses);\r\n\r\n  SwaggerModule.setup('api', app, document);\r\n\r\n  await app.listen(3000);\r\n}\r\nbootstrap();\r\n```\r\n\r\n---\r\n\r\n## 🎯 サポートされている型\r\n\r\n### 基本型\r\n\r\n```typescript\r\nconst Schema = type({\r\n  string: 'string',\r\n  number: 'number',\r\n  boolean: 'boolean',\r\n  date: 'Date',\r\n});\r\n```\r\n\r\n### 制約付き型\r\n\r\n```typescript\r\nconst Schema = type({\r\n  email: 'string.email',\r\n  positiveNumber: 'number\u003e0',\r\n  minNumber: 'number\u003e=18',\r\n  dateString: 'string.date.parse',\r\n});\r\n```\r\n\r\n### オプショナルとNullable\r\n\r\n```typescript\r\nconst Schema = type({\r\n  'optional?': 'string',\r\n  nullable: 'string | null',\r\n  'optionalNullable?': 'string | null',\r\n});\r\n```\r\n\r\n### 配列とEnum\r\n\r\n```typescript\r\nconst Schema = type({\r\n  tags: 'string[]',\r\n  numbers: 'number[]',\r\n  status: \"'active' | 'inactive' | 'pending'\",\r\n});\r\n```\r\n\r\n### 複雑な型\r\n\r\n```typescript\r\nconst Schema = type({\r\n  id: 'string',\r\n  name: 'string',\r\n  email: 'string.email',\r\n  'age?': 'number\u003e=18',\r\n  role: \"'admin' | 'user' | 'guest'\",\r\n  tags: 'string[]',\r\n  'metadata?': 'string | null',\r\n});\r\n```\r\n\r\n---\r\n\r\n## 📚 ドキュメント\r\n\r\n- [PERFORMANCE_BENCHMARK_REPORT.md](./PERFORMANCE_BENCHMARK_REPORT.md) - 詳細なパフォーマンス分析\r\n- [REMAINING_TASKS.md](./REMAINING_TASKS.md) - 実装状況と既知の制限事項\r\n- [実装レポート群](./docs/) - 各機能の実装詳細\r\n\r\n---\r\n\r\n## 🧪 テスト\r\n\r\n```bash\r\n# 全テスト実行\r\npnpm test\r\n\r\n# ウォッチモード\r\npnpm test:watch\r\n\r\n# カバレッジ\r\npnpm test:cov\r\n```\r\n\r\n**テスト結果**:\r\n- ✅ 24テスト全てパス\r\n- ✅ 並列実行対応\r\n- ✅ 100%成功率\r\n\r\n---\r\n\r\n## 🔧 既知の制限事項\r\n\r\n### anyOf形式のUnion型\r\n\r\nNestJS Swaggerの制限により、以下の型は使用できません:\r\n\r\n```typescript\r\n// ❌ 動作しない\r\nvalue: 'string | number'\r\nstatus: '\"active\" | \"inactive\" | null'\r\n\r\n// ✅ 代わりにこれを使用\r\nstatus: \"'active' | 'inactive' | 'pending'\"  // enumとして\r\nnullable: 'string | null'                     // nullableとして\r\n```\r\n\r\n詳細は [REMAINING_TASKS.md](./REMAINING_TASKS.md) を参照してください。\r\n\r\n---\r\n\r\n## 💡 ベストプラクティス\r\n\r\n### 1. スキーマは再利用する\r\n\r\n```typescript\r\n// ✅ GOOD\r\nexport const UserSchema = type({ ... });\r\n\r\n// ❌ BAD\r\nfunction validate() {\r\n  const schema = type({ ... }); // 毎回作成される\r\n}\r\n```\r\n\r\n### 2. メタデータは型安全に\r\n\r\n```typescript\r\n// ✅ GOOD（存在するプロパティのみ指定可能）\r\narkWithMeta(UserSchema, {\r\n  properties: {\r\n    name: { description: 'Name' },  // OK\r\n    // invalid: { ... }  // TypeScriptエラー\r\n  }\r\n});\r\n```\r\n\r\n### 3. バッチ処理は同期的に\r\n\r\n```typescript\r\n// ✅ GOOD（ArkTypeは同期的で高速）\r\nconst results = data.map(item =\u003e UserSchema(item));\r\n\r\n// ⚠️ 不要な非同期化は避ける\r\nconst results = await Promise.all(\r\n  data.map(async item =\u003e await validate(item))\r\n);\r\n```\r\n\r\n---\r\n\r\n## 📊 プロジェクト構成\r\n\r\n```\r\narktype-nestjs-prototype/\r\n├── src/\r\n│   ├── arktype.helpers.ts              # コアヘルパー関数\r\n│   ├── arktype.helpers.spec.ts         # ヘルパーのテスト\r\n│   ├── schema-metadata.helper.ts       # メタデータ処理\r\n│   ├── schema-metadata.helper.spec.ts  # メタデータテスト\r\n│   ├── performance.bench.spec.ts       # パフォーマンステスト\r\n│   └── example.dto.ts                  # 使用例\r\n├── PERFORMANCE_BENCHMARK_REPORT.md     # 詳細ベンチマーク\r\n├── REMAINING_TASKS.md                  # タスク管理\r\n└── README.md                           # このファイル\r\n```\r\n\r\n---\r\n\r\n## 🤝 貢献\r\n\r\nこのプロジェクトは実験的な統合の検証を目的としています。\r\n\r\nバグ報告や機能提案は、Issueで歓迎します。\r\n\r\n---\r\n\r\n## 📄 ライセンス\r\n\r\nMPL-2.0\r\n\r\n---\r\n\r\n## 🙏 謝辞\r\n\r\n- [ArkType](https://arktype.io/) - 型安全で高速なバリデーションライブラリ\r\n- [NestJS](https://nestjs.com/) - プログレッシブなNode.jsフレームワーク\r\n- [Swagger](https://swagger.io/) - APIドキュメント生成\r\n- [nestjs-zod](https://github.com/BenLorantfy/nestjs-zod) - `_OPENAPI_METADATA_FACTORY`パターンの実装参考\r\n\r\n---\r\n\r\n## 📞 関連リンク\r\n\r\n- [ArkType公式ドキュメント](https://arktype.io/docs)\r\n- [NestJS公式ドキュメント](https://docs.nestjs.com/)\r\n- [Swagger/OpenAPI仕様](https://swagger.io/specification/)\r\n\r\n---\r\n\r\n**完成度**: 100% ✅  \r\n**最終更新**: 2025-11-02  \r\n**ステータス**: Production Ready 🚀\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsousuke0422%2Fnest-arktype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsousuke0422%2Fnest-arktype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsousuke0422%2Fnest-arktype/lists"}