elysia

Elysia

Elysia または ElysiaJS に関わる作業では、このスキルを使用してください。

ワークフロー

1. 変更を提案する前に、アプリケーションを調査します。
   • インストールされている elysia および関連する @elysia/* パッケージのバージョン。安定版の latest は 1.4.x（セキュリティ修正のみ）です。2.0.0-beta.x は next dist-tag で公開されており、コア API が変更されています。1 つのアプリで 1.4 と 2.0 の構文を混在させないでください。
   • 1.4.x では、>= 1.4.30 を必須とします（<= 1.4.29 には、スキーマのデフォルト値とプロパティ名に関する重大な RCE アドバイザリがあります）。
   • ランタイムとアダプター：Bun、@elysia/node、Deno、Cloudflare Worker、Vercel、Netlify、またはその他の Web Standard ホスト。
   • ルートインスタンス、エクスポート／リッスンの形式、ルートプラグイン、プレフィックス、ガード、マクロ、スキーマ、エラーフック、テスト。
   • 横断的な各フックの登録順序とプラグインのスコープ。
2. 最新の API、アダプター、パッケージの互換性、実験的サポート、またはバージョン固有の動作に関わる作業では、最新の公式ドキュメントを確認します。source-map.md から始めてください。
3. 作業内容に応じて、以下の関連リファレンスを確認します。
   • セットアップ、ルーティング、ハンドラー、ストリーミング、プロジェクトの構成：setup-routing.md。
   • スキーマ、ライフサイクルの順序、ステータスレスポンス、エラー：validation-lifecycle-errors.md。
   • プラグイン、スコープ、ガード、マクロ、依存関係、コンテキスト：plugins-context.md。
   • テスト、Eden、OpenAPI、WebSocket、SSE：testing-clients-realtime.md。
   • ランタイム、デプロイ、セキュリティ、オブザーバビリティ、本番環境のチェック：production-runtime-security.md。
   • Elysia 2 ベータ版の導入、codemod、1.4 から 2.0 への API 変更：elysia-2-migration.md。
4. ユーザーが移行を明示的に依頼していない限り、リポジトリの既存のアーキテクチャとコマンドを維持します。
5. まず適切な範囲で動作を検証し、その後、組み立てたアプリケーション全体を検証します。

核心的な判断

• スキーマは実行可能な HTTP コントラクトとして扱います。境界が重要な場合は、リクエストとステータスごとのレスポンススキーマを定義し、手書きのインターフェースで重複させないでください。
• ルートハンドラーは薄く保ちます。HTTP に関する処理には機能単位の Elysia インスタンスを使い、リクエストコンテキストを必要としないビジネスロジックには通常の関数やモジュールを使います。
• 各ルート／プラグインファイルから const の Elysia インスタンスをエクスポートします。ルートを export function featureRoutes(db) ／ (runtime) ／同様のファクトリーでラップしないでください。
• アプリのシングルトン（データベースクライアント、Effect ManagedRuntime、環境変数、メーラー）は、使用するモジュールでインポートします。サービスでは DB をインポートし、ルートでは runPromise を呼び出すためだけに runtime をインポートします。これらの値を関数の引数として渡したり、ハンドラーに渡すためだけに .decorate("db", db)（または runtime）を呼び出したりしないでください。
• オプションを受け取るプラグインファクトリーは、再利用可能な共通プラグイン（prefix、version、CORS origins などの設定）に限ります。アプリから機能へデータベースやランタイムを渡す方法として使わないでください。
• ハンドラーのコンテキスト型は Elysia に推論させます。分割代入した値やスキーマから導出した型で十分な場合に、広範な手動型付けの Context をコントローラーやサービスに渡さないでください。
• チェーンの順序を守ります。インターセプターフックは、グローバルな受信リクエストに適用される onRequest を除き、その後に登録されたルートとプラグインに適用されます。
• プラグインのカプセル化を尊重します。プラグインのライフサイクルフックとスキーマが親ルートを自動的に保護するわけではありません。local、scoped、global を意図的に選び、その境界をテストしてください。
• 1.4 では、検証済みのリクエストデータに依存する値には derive より resolve を優先します。derive は検証前に実行され、resolve は検証後に実行されます。2.0 では resolve が削除され、derive はハンドラー実行前（従来の resolve と同じタイミング）に実行されます。
• 信頼できない入力（フォームビルダー、データベース駆動のスキーマ）からスキーマ、プロパティ名、default 値を決して構築しないでください。Elysia はこれらを生成コードにコンパイルします。
• 型安全なレスポンスの絞り込みが重要な場合は、想定される HTTP の結果に対して status(code, value) を返します。1.4 では、結果を onError に渡す必要がある場合に限り、例外をスローします。2.0 では、返されたエラーもスローされたエラーも error フックに到達します。
• ライフサイクルの重複排除が重要な場合は、名前付きプラグインを使います。設定によって識別情報が変わる場合は seed も指定してください。
• OpenAPI のセキュリティ宣言はドキュメントとしてのみ扱います。認証と認可はガード、マクロ、フック、またはハンドラーで強制してください。
• 他のアダプターで Bun 専用 API が使えると想定しないでください。server と server.requestIP は Bun 固有です。アダプターとプラットフォームの制限に応じた実装にしてください。
• ベンチマークの数値を、一般的なアプリケーション性能の保証として引用しないでください。実際のアプリとランタイムをプロファイルしてください。
• Eden Treaty（@elysia/eden の treaty(app)）を使って HTTP エンドポイントをテストします。app.handle(new Request(...))、plugin.handle(...)、および const handle = (path) => app.handle(new Request(\http://localhost${path}\`))` のようなヘルパーは禁止します。

検証

リポジトリが提供するコマンドを優先してください。Elysia に重要な変更を加える場合は、関連する項目を実施してください。

• 実際のランタイム／アダプターを使用して、型チェックと本番ビルドを行います。
• Eden Treaty のテスト（treaty(app)）で、成功、バリデーション失敗、認証失敗、エラーマッピング、ヘッダー、ステータス固有のレスポンスボディを確認します。{ data, error, status } をアサートしてください。
• フック、ガード、マクロ、またはプラグインの合成を変更する場合は、スコープ／実行順序のリグレッションテストを実施します（引き続き Treaty を使用してください）。
• 遅延または遅延読み込みされるプラグインに対して Treaty を呼び出す前に、await app.modules を実行します。
• スキーマ、レスポンスのステータスマップ、タグ、セキュリティメタデータ、または型生成を変更する場合は、生成された OpenAPI を確認します。
• listen／export、プロキシヘッダー、Cookie、CORS プリフライト、ストリーミング、ランタイム固有の動作について、実際の HTTP スモークテストを実施します。
• リアルタイム動作を変更する場合は、WebSocket の接続、不正なメッセージ、切断、タイムアウト、バックプレッシャーを確認します。
• アダプター、バンドル、バイナリーコンパイル、サーバーレスエクスポート、環境変数、またはプラットフォームバインディングを変更する場合は、デプロイ先でスモークテストを実施します。

実施したチェックと実施しなかったチェックを報告し、バージョンに依存する前提が残っている場合はそれも記載してください。